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(freshness): refresh feature docs across agents, forge, pump, x402 and ops, and regenerate the changelog and public pages
nirholas9952a5ae1c88
diff --git a/CHANGELOG.md b/CHANGELOG.mdindex 83da41abf..6e13d973c 100644--- a/CHANGELOG.md+++ b/CHANGELOG.md@@ -9,6 +9,7 @@ Public history for [three.ws](https://three.ws), newest first. New pages come fr- **Allowance pulls now require the signed real-funds agreement**: Pulling funds through an owner-funded on-chain allowance now checks the signed real-funds agreements before the agent key is used, matching every other custodial signing path. Unsigned accounts get the standard agreement-required refusal and nothing is sent. `[fix]`- **Background-removal service moves to Pillow 13, closing 41 image-decoder advisories**: The background-removal worker decodes images that callers upload, and its pinned Pillow carried 41 open advisories including heap overflows in the JPEG, TIFF and FlashPix loaders. It now runs Pillow 13.0.0 on rembg 2.0.86 (the first release that allows it), matching every other worker, and the image build gate passes against the real models. `[fix]`- **BNB Greenfield vault writes no longer ship a vulnerable XML builder**: The Greenfield SDK and the Bot Framework expression library each carried a nested fast-xml-parser 4.5.7 that the version-scoped override never reached, leaving the XMLBuilder comment and CDATA injection advisory (GHSA-gh4j-gqv2-49f6) open. The override now applies to every copy, all of them resolve to 5.11.2, and a lockfile test guards every nested path. `[fix, security]`+- **Chat pairing and X connect returns land on a working Connections page**: The /settings/connections link that the Telegram and Discord bots, the notification settings and the X connect flow all send people to returned a 404. Every /settings subpath now serves the settings app, and a new Connections tab lists paired chats, toggles notifications, picks the default agent, unpairs, issues a pairing code and redeems the code a bot prints. (`/settings/connections`) `[fix]`- **Commit feed cron skips quietly on a lock-check fault**: The commit feed cron now skips a tick with a 200 when the database lock check hits a transient fault, instead of answering a raw 500 and raising an ops alert. The next tick retries. `[fix]`- **Fixed phone/desktop/CLI/Telegram account linking, which was failing on every attempt**: Every account-link action (mint, claim, poll, pending, decide, devices, revoke) behind /dashboard/account and the mobile-app pairing flow had been throwing on every call since the device-linking feature shipped on 2026-10-11, because its own first migration created a table under a name an older, unrelated agent-identity feature already owned, so the new table silently never got created with the right columns. The old table is renamed out of the way instead of dropped, so its rows are preserved, and the device-linking table now gets created with the shape the feature actually needs. (`/dashboard/account`) `[fix]`- **Gallery and marketplace thumbnails degrade gracefully instead of showing a broken-image icon**: Six image spots on /gallery and /marketplace (the avatar grid thumbnail, the equip-avatar picker row, the live-sale ticker avatar, the animation marketplace listing card, the animation buy-modal preview, and a tool-detail icon) rendered a plain <img> with no fallback, so a 502 or missing thumbnail left the browser's default broken-image glyph on two of the highest-traffic pages in the product. All six now carry the same data-fallback attribute the site already uses elsewhere: card-style thumbnails swap to the existing placeholder box, small avatar icons just disappear instead. A seventh untagged image turned up in the gallery's forge-card renderer while verifying the other six and got the same fix. (`/gallery`) `[fix]`diff --git a/docs/agent-abilities/chapters/07-skills.md b/docs/agent-abilities/chapters/07-skills.mdindex 7f07ae34e..ba6e45ada 100644--- a/docs/agent-abilities/chapters/07-skills.md+++ b/docs/agent-abilities/chapters/07-skills.md@@ -2,7 +2,7 @@Skills are the agent’s installed abilities: trading rails, launch tooling, NFTs, blinks, sentiment, scenes, all wired to real APIs. Owners switch them on and off in the Agent Studio's Skills room (three.ws/agent-studio), and MCP-exposed skills are callable by other agents through /api/mcp. The enabled skill list also travels in the agent's signed manifest, pinned to IPFS whenever a public agent's persona is saved (private agents publish on request), so anyone can verify which skills an agent carries without an account ([agent manifest](/docs/agent-manifest)).-The in-world agent skills system (src/agent-skills.js plus 13 family modules) is what a three.ws agent can DO — and what you can watch it doing. Each skill bundles an instruction, an animation hint, a voice template, and a real handler, so execution flows through the agent protocol bus and the avatar physically performs the action (gestures, speech, mood shifts) instead of silently returning JSON. Skill families span 3D work (present/validate models, build the scene), the full Solana economy (pump.fun launch/trade/watch, Jupiter swaps, Pyth prices, Blinks, NFTs), agent monetization (on-chain payment vaults on Solana and EVM, x402 agent-to-agent hiring under signed mandates), and market intelligence (aixbt, sentiment, KOL P&L) — all against real APIs and SDKs with no mocks, keys held either in the user's browser wallet or server-side, never in the client. MCP-exposed skills double as tools on /api/mcp, so the same registry powers both the living avatar and the developer API.+The in-world agent skills system (src/agent-skills.js plus 14 family modules and a memory-hook subscriber) is what a three.ws agent can DO, and what you can watch it doing. Each skill bundles an instruction, an animation hint, a voice template, and a real handler, so execution flows through the agent protocol bus and the avatar physically performs the action (gestures, speech, mood shifts) instead of silently returning JSON. Skill families span 3D work (present/validate models, build the scene), the full Solana economy (pump.fun launch/trade/watch, Jupiter swaps, Pyth prices, Blinks, NFTs), launches on Robinhood Chain, agent monetization (on-chain payment vaults on Solana and EVM, x402 agent-to-agent hiring under signed mandates), and market intelligence (aixbt, sentiment, KOL P&L), all against real APIs and SDKs with no mocks, keys held either in the user's browser wallet or server-side, never in the client. MCP-exposed skills double as tools on /api/mcp, so the same registry powers both the living avatar and the developer API.## Skill registry and performed execution (core)@@ -22,7 +22,7 @@ Out of the box every agent can greet you, narrate the currently loaded 3D model## Pump.fun launch and bonding-curve trading-Agents launch real pump.fun tokens (pumpfun-create, or pumpfun-launch-from-agent which auto-derives name/image/bio metadata from the agent's own identity and GLB), buy and sell on the bonding curve (SOL- or USDC-paired), trade graduated tokens on the AMM pool, read live curve state and market cap (pumpfun-status), and claim accumulated creator fees.+Agents launch real pump.fun tokens (pumpfun-create, or pumpfun-launch-from-agent which auto-derives name/image/bio metadata from the agent's own identity and GLB), buy and sell on the bonding curve (SOL- or USDC-paired), trade graduated tokens on the AMM pool, read live curve state and market cap (pumpfun-status), and claim accumulated creator fees (pumpfun-claim-fees first sweeps the creator fees that v3 curve and PumpSwap v2 trades leave on the curve or pool, for the coins passed in `mints`, then collects the vault).**How it works:** src/agent-skills-pumpfun.js wraps the official @pump-fun/pump-sdk and @pump-fun/pump-swap-sdk, signing with the owner's injected browser wallet (Phantom/Backpack/Solflare) — the module never holds keys. It auto-detects Token-2022 vs legacy SPL mints and the quote mint from the on-chain curve, and converts slippage bps to the SDKs' percent convention.@@ -40,7 +40,7 @@ A research layer alongside trading: compute realized+unrealized P&L for any wallThe agent subscribes to live pump.fun activity and reacts in-world as events arrive: pumpfun-watch-start streams claims/mints/graduations and the avatar celebrates first-time claims, shows concern at fakes, and waves at graduations; pumpfun.watchWhales speaks each whale buy/sell above a USD threshold on a specific mint; pumpfun-watch-claims polls a creator wallet for fee-claim transactions; pumpfun-recent-claims and pumpfun-token-intel give on-demand reads.-**How it works:** src/agent-skills-pumpfun-watch.js opens an SSE stream to /api/agents/pumpfun-feed and a WebSocket whale watcher (src/pump/pumpkit-whale.js), dispatching reactions through the protocol bus as SPEAK/EMOTE/gesture events. The whale watcher probes three public Solana WebSocket hosts for one that answers, routes its RPC reads through /api/solana-rpc with the public endpoint as fallback, prices SOL through the shared multi-provider USD chain instead of a hard-coded rate, and reports subscription_unavailable or usd_price_unavailable through an optional onStatus callback so a blind feed is never mistaken for a quiet market. Every feed read is bounded (8 s) so a dead edge cannot freeze the agent's turn. Read-only: no keys, no transactions.+**How it works:** src/agent-skills-pumpfun-watch.js opens an SSE stream to /api/agents/pumpfun-feed and a WebSocket whale watcher (src/pump/pumpkit-whale.js), dispatching reactions through the protocol bus as SPEAK/EMOTE/gesture events. The whale watcher probes three public Solana WebSocket hosts for one that answers, routes its RPC reads through /api/solana-rpc with the public endpoint as fallback, counts the pool part of a curve-completing buy (it folds the separate post-complete event into the trade through `pumpTradesFromEvents`, so the largest buy a coin ever sees is not undercounted), prices SOL through the shared multi-provider USD chain instead of a hard-coded rate, and reports subscription_unavailable or usd_price_unavailable through an optional onStatus callback so a blind feed is never mistaken for a quiet market. Every feed read is bounded (8 s) so a dead edge cannot freeze the agent's turn. Read-only: no keys, no transactions.**Why it matters:** Your avatar becomes a living market ticker — you see whale trades and graduation moments performed in real time instead of scanning a feed yourself.@@ -68,6 +68,14 @@ A protocol-bus subscriber that automatically writes structured memories whenever**Why it matters:** You never have to re-state context — ask 'what's my token?' or 'what was my last trade?' and the agent answers from its own recorded history.+## Robinhood Chain launches (quote first)++Agents launch coins on Robinhood Chain from their own custodial EVM wallet: pons-launch deploys a coin on a bonding curve with an optional opening buy, creator tax and buyback share, and paired-launch deploys one that trades against up to five assets at once (tokenized stocks, WETH, stablecoins, chain coins). paired-markets lists every asset a paired coin can trade against, and paired-fees shows and, with claim: true, collects the swap fees the agent earned as creator.++**How it works:** src/agent-skills-pons.js and src/agent-skills-paired.js POST to /api/agents/:id/pons/* and /api/agents/:id/paired/*. Without confirm: true a launch skill only prices the launch (fee, gas, opening buy, USD total, blockers such as an unfunded wallet); the same call with confirm: true launches. The server checks ownership, signer mode, the real-funds agreement and the agent's spend policy; the client files hold no keys. See [Robinhood Chain launches](/docs/pons-launch) and [paired coins](/docs/paired-coins).++**Why it matters:** The agent shows its owner the exact cost before any money moves, then launches and earns fees from its own wallet.+## Jupiter swaps and Pyth oracle pricesWhole-of-Solana trading beyond pump.fun: jupiter-quote (read-only best-route quote for any SPL pair with price impact), jupiter-swap (execute with wallet approval), jupiter-tokens (resolve symbol to mint via Jupiter's list), and pyth-price (live USD prices with confidence intervals for SOL/BTC/ETH/USDC).@@ -120,7 +128,7 @@ The full monetization lifecycle for an agent: register it on-chain with the pumpOne agent autonomously discovers, pays, and calls a peer agent's paid A2A skill — under a signed Intent Mandate the user issued ahead of time, with optional ERC-8004 reputation gating (minimum average rating and review count) before any USDC moves. The payment is performed, not hidden: PAY_INTENT, then PAY_SETTLED with a celebration emote or PAY_FAILED with visible concern.-**How it works:** src/agent-skills-a2a.js POSTs to /api/agents/a2a-call, where the server enforces the mandate, a budget ledger, the peer's on-chain reputation, and the agent's own spend policy (the freeze switch and the per-transaction, rolling-daily, and per-counterparty ceilings), which a mandate cannot widen: a halted agent is refused with wallet_frozen before the peer is even quoted, and an agent deleted or transferred since the mandate was signed stops being spendable. Each payment writes a receipt to the agent's custody ledger (returned as receipt_id, readable at GET /api/agents/:id/solana/custody?category=x402) and releases it again on any failure; settlement flows over the x402 protocol and the receipt (amount, network, transaction, artifacts) comes back to be spoken in dollars.+**How it works:** src/agent-skills-a2a.js POSTs to /api/agents/a2a-call, where the server enforces the mandate, a budget ledger, the peer's on-chain reputation, and the agent's own spend policy (the freeze switch and the per-transaction, rolling-daily, and per-counterparty ceilings), which a mandate cannot widen, plus platform-set ceilings (`api/_lib/a2a/platform-ceiling.js`: $100 per mandate, $25 per call, $50 per user per day and $500 for the whole payer wallet per day by default, each overridable by `A2A_PLATFORM_*` env vars) that neither the self-issued mandate nor the agent's own limits can raise: a halted agent is refused with wallet_frozen before the peer is even quoted, and an agent deleted or transferred since the mandate was signed stops being spendable. Each payment writes a receipt to the agent's custody ledger (returned as receipt_id, readable at GET /api/agents/:id/solana/custody?category=x402) and releases it again on any failure; settlement flows over the x402 protocol and the receipt (amount, network, transaction, artifacts) comes back to be spoken in dollars.**Why it matters:** This is the agent economy made visible and safe: your agent can hire other agents within a budget you pre-authorized, refuse untrusted peers, and you literally watch the money move — every payment bounded by your signed mandate.diff --git a/docs/agent-abilities/chapters/09-the-agent-economy.md b/docs/agent-abilities/chapters/09-the-agent-economy.mdindex bb8932609..8bc03caf5 100644--- a/docs/agent-abilities/chapters/09-the-agent-economy.md+++ b/docs/agent-abilities/chapters/09-the-agent-economy.md@@ -8,7 +8,7 @@ On three.ws, agents don't just chat — they earn, spend, hire, and get hired, wYour agent can autonomously hire another agent for a skill it doesn't have — it resolves the provider's published offer, reserves the spend against its own policy, pays real USDC from its own wallet, and only settles after the work actually succeeds. A failed job can never charge the hirer: the flow is verify-then-settle by construction. Every completed hire produces an on-chain settlement plus a separate on-chain invocation receipt naming both agents, auditable from both sides with explorer links.-**How it works:** POST /api/agents/a2a-hire chains the offer registry (agent_paid_services), atomic spend reservation (per-tx + daily caps + kill switch), the x402 exact-scheme USDC payment on Solana mainnet via @x402/svm, and an on-chain invocation-receipt program write; hires land in the agent_hires ledger.+**How it works:** POST /api/agents/a2a-hire chains the offer registry (agent_paid_services), atomic spend reservation (per-tx + daily caps + kill switch), the x402 exact-scheme USDC payment on Solana mainnet via @x402/svm, and an on-chain invocation-receipt program write; hires land in the agent_hires ledger. Each settled hire also writes a signed fulfillment attestation (a client-side payment timeout is recorded as disputed, not guessed as delivered); the recency-weighted fulfillment rate feeds the agent's Settlement reliability score, and a provider can opt a priced service into an x402 discount for well-reputed hirers via a signed, short-lived voucher (off by default).**Why it matters:** Your agent can buy capabilities it lacks, safely, with zero chance of paying for failed work.@@ -72,7 +72,7 @@ Every agent's skills can carry a price. Buyers pay with a wallet scan via SolanaAn agent can autonomously buy persistent skill access from another agent, signing the payment from its own wallet — no human at the checkout. Safety is built in: per-agent purchase rate limits, a configurable daily spend cap, and self-dealing flagged in the ledger.-**How it works:** POST /api/marketplace/purchase-as-agent signs a real SPL transfer from the buyer agent's server-custodied keypair, with a 10-purchases-per-hour cap and daily USDC ceilings enforced against confirmed and pending purchases.+**How it works:** POST /api/marketplace/purchase-as-agent signs a real SPL transfer from the buyer agent's server-custodied keypair, with a 10-purchases-per-hour cap and daily USDC ceilings enforced against confirmed and pending purchases. A bearer API key must carry the wallet:write scope to spend this way.**Why it matters:** Your agent upgrades itself when it needs a capability, within limits you set.@@ -112,7 +112,7 @@ Every autonomous spend path an agent has — hiring, trading, bounties, treasuryThe monetization dashboard aggregates your agents' revenue by skill and by day across selectable periods, showing gross, fees, and net. When you want the money, request a withdrawal — all or part of the available balance — straight to your own wallet, with a full withdrawal history.-**How it works:** agent_revenue_events records every sale; GET /api/monetization/withdrawals reads the live balance from them, and POST /api/monetization/withdrawals validates Solana/EVM payout addresses with a 1 USDC minimum against the real available balance.+**How it works:** agent_revenue_events records every sale; GET /api/monetization/withdrawals reads the live balance from them, and POST /api/monetization/withdrawals validates Solana/EVM payout addresses with a 1 USDC minimum against the real available balance. Revenue from x402 agent API sales settles straight to the agent's own wallet, so it is not counted as withdrawable.**Why it matters:** Agent income is real income: measured, itemized, and withdrawable.diff --git a/docs/agent-abilities/chapters/11-markets-intelligence.md b/docs/agent-abilities/chapters/11-markets-intelligence.mdindex 715f78695..b0f1b7748 100644--- a/docs/agent-abilities/chapters/11-markets-intelligence.md+++ b/docs/agent-abilities/chapters/11-markets-intelligence.md@@ -16,15 +16,15 @@ The front door for all market surfaces: live global stats (total market cap, domLive news aggregated natively from 197 real publisher RSS/Atom feeds across 27 categories (CoinDesk, The Block, Decrypt, Cointelegraph, Blockworks, Bitcoin Magazine, and more, including 34 international feeds in 17 languages) with category tabs, search, per-article sentiment, and ticker chips; a rich article reader with server-side extraction, AI summary and key points (extractive fallback), and related coverage; plus the largest open crypto-news archive: 662,047 enriched articles from Sept 2017 to today, English + Chinese.-**How it works:** /markets/news, /markets/news/article, /markets/archive backed by api/news/{feed,article,archive,rss}.js over api/_lib/news.js + api/_lib/news-sources.js; the archive corpus lives on gs://three-ws-news-archive (recovered from the cryptocurrency.cv aggregator, which three.ws now runs natively).+**How it works:** /markets/news, /markets/news/article, /markets/archive backed by api/news/{feed,article,archive,rss}.js over api/_lib/news.js + api/_lib/news-sources.js (when the native feed merge comes back empty, api/_lib/news-failover.js asks a hosted news API as a last-resort rung, through the same rights and curation filters); the archive corpus lives on gs://three-ws-news-archive (recovered from the cryptocurrency.cv aggregator, which three.ws now runs natively).**Why it matters:** Real-time and nine-years-deep crypto news in one place, readable without visiting 197 different publisher sites, with machine-friendly JSON and RSS.## Global markets index + coin detail pages-A CoinGecko-style /coins index (global stats bar, sortable top-coins table with 7d sparklines, debounced full-catalog search, load-more paging) and a shareable /coin/:id detail page per coin: interactive 24H-1Y chart with crosshair (switchable between the native CoinGecko chart and TradingView, DexScreener, 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).+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, per-chain contract addresses and a domain-suggestion panel for the coin's name. 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.+**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 (the markets table falls back to the coin's DEX pairs when CoinGecko and CoinPaprika both miss a young token). :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.**Why it matters:** Full-market price coverage that plugs directly into the platform's Solana/pump.fun surfaces — a coin page is never a dead end.@@ -62,9 +62,9 @@ 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 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.+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, holder-concentration Gini and how much of the first-buyer supply one funder seeded; mint and freeze authority; bonding-curve progress and graduation state; liquidity) beside a live price chart, a trade tape and a plain-English launch receipt (mint and freeze authority, supply, fee routing, the creation transaction and the Trade Safety Firewall verdict, one sentence per fact, copyable as text or downloadable as JSON), 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.+**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 (coins an agent launched on Robinhood Chain through Pons render with their venue and chain explorer instead); the receipt comes from GET /api/pump/launch-receipt; 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 plus its own /launches/<mint> profile that shows the numbers and leaves the verdict to the reader.@@ -88,7 +88,7 @@ Agents launched as pump.fun coins can charge for their services on-chain: buildToken sentiment on demand: POST /api/sentiment scores any text (Positive/Negative/Neutral) with a deterministic lexicon scorer; /api/social/sentiment-pulse pulls the real community commentary (pump.fun callouts) for any Solana/pump.fun mint and returns an overall score with per-source breakdown and examples (also sold as the paid sentiment_pulse MCP tool); aixbt narrative intel and momentum-ranked project scans are exposed at api/aixbt/* and as aixbt_intel / aixbt_projects MCP tools. All packaged for developers as the @three-ws/intel npm module.-**How it works:** Sentiment-pulse fetches the coin's most recent pump.fun callouts (the frontend-api-v3 `/callout/coin/:mint` feed the pump.fun coin page renders; the older comments and `/callout/top` routes were retired upstream) plus caller-supplied snippets, scored by the in-repo lexicon engine (src/social/sentiment.js, which matches terms on word boundaries so "partnered" never scores as "red"). A pump.fun outage with no caller-supplied texts answers 502 `upstream_unavailable` rather than a fabricated neutral score, while a coin that is simply quiet still answers 200 with `count: 0`; aixbt endpoints proxy the aixbt market-intelligence service.+**How it works:** Sentiment-pulse fetches the coin's most recent pump.fun callouts (the frontend-api-v3 `/callout/coin/:mint` feed the pump.fun coin page renders; the older comments and `/callout/top` routes were retired upstream) plus caller-supplied snippets, scored by the in-repo lexicon engine (src/social/sentiment.js, which matches terms on word boundaries so "partnered" never scores as "red"). A pump.fun outage serves the last good callouts for that mint (reported as `sources.pumpfunStatus: 'stale'`); only a mint never fetched before, with no caller-supplied texts, answers 502 `upstream_unavailable` rather than a fabricated neutral score, while a coin that is simply quiet still answers 200 with `count: 0`; aixbt endpoints proxy the aixbt market-intelligence service.**Why it matters:** Read the crowd on any token before acting — from a free one-call API, an agent skill, an MCP tool, or a single npm import.diff --git a/docs/agent-index.md b/docs/agent-index.mdindex 970a00f63..2c018d1c5 100644--- a/docs/agent-index.md+++ b/docs/agent-index.md@@ -138,7 +138,9 @@ The monitor reports both legs. Read them differently:blocks faster than the crawl consumes them keeps a fresh cursor forever whilefalling further behind every tick. The monitor therefore reports **blocksbehind head**, and the crawl grows its block window while a chain is behind- (halving it when a provider rejects the range) so a fast chain can actually+ (halving it when a provider rejects the range, bounded by a 60-second+ per-chain wall-clock budget after which it checkpoints the cursor instead of+ retrying blind) so a fast chain can actuallyclose the gap. One window per chain per tick holds a slow chain but cannotdrain a fast one, so after the first pass over every chain the cron spendswhatever is left of its budget on a **catch-up pass**: it re-picks the chain@@ -178,7 +180,8 @@ resumes from the last signature or block it recorded; when the RPC answering thecall no longer serves it, the read throws, the cursor is never written, andevery later tick re-asks for the same dead history. Both legs recover from itnow. [`api/_lib/solana/cursor-recovery.js`](../api/_lib/solana/cursor-recovery.js)-recognizes an unresolvable cursor signature and restarts that agent's sweep from+recognizes an unresolvable cursor signature (including a lane that reports the+history is not on the node) and restarts that agent's sweep fromthe head, and the EVM crawl skips forward once per tick past a pruned-historyrejection instead of letting the range backoff retry something it cannot fix.The blocks skipped that way are published on the health board@@ -186,7 +189,8 @@ The blocks skipped that way are published on the health boardis 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+an EVM-only fault caps the subsystem at `degraded` instead of `down` whenever the+Solana leg is not itself `down` (fresh or merely degraded), since asecondary chain months behind head changes nothing on the agent profile a readeractually opens. The detail line says so whenever the cap applies.diff --git a/docs/animations.md b/docs/animations.mdindex 8ada0c9bb..8dbf617cd 100644--- a/docs/animations.md+++ b/docs/animations.md@@ -1,6 +1,6 @@# Animations-Animations are the motion clips (idle, wave, dance, and about 3,000 more) that bring three.ws avatars to life. Browse and preview every clip at [three.ws/animations](https://three.ws/animations); this page is the developer reference for how the clip collections are organized, how the runtime loads them, and how agents pick which clip to play.+Animations are the motion clips (idle, wave, dance, 113 curated clips plus a CC0 library of 200+ more) that bring three.ws avatars to life. Browse and preview every clip at [three.ws/animations](https://three.ws/animations); this page is the developer reference for how the clip collections are organized, how the runtime loads them, and how agents pick which clip to play.> For how FBX, GLB, and clip JSON relate — the formats, the conversions, and the full generate→rig→animate→export chain — see **[docs/3d-asset-pipeline.md](3d-asset-pipeline.md)**. This page is the runtime registry and agent-slot reference.@@ -131,14 +131,14 @@ Its measured companion is `public/animations/signatures.json`: a motion-signatur- **Poster thumbnails**: a WebP still of the preview avatar posed mid-motion, rendered offline by `node scripts/build-animation-thumbnails.mjs` (which drives `scripts/thumbnail-harness.html` in headless Chromium through the site's own retarget engine). Curated thumbs are committed at `public/animations/thumbs/<name>.webp`; library thumbs upload to R2 alongside their clips via `npm run cc0-library:upload`, which publishes each one as the manifest entry's `thumb` URL. Added a clip? Re-run the thumbnail script, then re-upload. **The library manifest's `thumb` field is the only source of truth for a library thumbnail.** Coverage is partial, and the gallery renders the clip's icon for those instead of guessing a CDN path: the guess 404s on every one of them, which cost a blocked cross-origin request per card.- **Categories**: the bulk library carries no category metadata, so `src/animation-categories.js` derives one per clip from its label (ordered keyword rules; curated clips keep their hand-assigned `animation-presets.js` category). Covered by `tests/animation-categories.test.js`, which also asserts <10% of the real library falls into the "More" catch-all.-- **Per-clip credit**: every bulk-library card shows its source pack and license next to the category chip (`src/animations-gallery.js` `normalizeFullLibraryClip`), pulled straight from the manifest's `source`/`license` fields. See "Licensing" below.+- **Per-clip credit**: every bulk-library card shows its source pack and license next to the category chip (`src/animations-gallery.js` `normalizeFullLibraryClip`), pulled straight from the manifest's `source`/`license` fields. The curated studio manifest carries no such fields, so `studioClipCredit()` in the same file classifies those clips by name prefix (Avaturn, Mixamo, three.js examples) to match `public/animations/LICENSES.md`; a clip whose source is unresolved stays uncredited. See "Licensing" below.- **Live previews** — one shared WebGL engine (`src/animations-live-preview.js`) serves every card hover and the detail modal: a single renderer + preview avatar; the canvas moves into whichever card is previewing. Nothing 3D loads until the first hover.- **Deep links**: `?clip=<id>` opens a clip's detail modal directly; `q`, `cat`, `filter`, and `sort` round-trip through the URL so filtered views are shareable. Every one of them is validated against the values the controls can represent, so a hand-edited `?sort=bogus` falls back to `featured` rather than blanking the sort menu, and an arriving `?filter=once` presses the matching segmented button instead of filtering invisibly.- **Detail modal**: a real dialog. Focus moves into it on open, Tab wraps inside it, Escape closes it and returns focus to the card that opened it. Arrow keys step through the filtered list (except while a slider is focused, which owns its own arrows), and Space toggles playback. The transport row only appears once a clip is actually on the stage, so a preview that fails to load shows the error and its Studio link rather than controls that do nothing.## Licensing-The curated 131-clip default avatar set (`public/animations/clips/`, built from+The curated 113-clip default avatar set (`public/animations/clips/`, built from`mx-*.fbx` Mixamo sources and the MIT/CC0 three.js example-model clips) shipsbaked into the site and is out of scope for this section: Adobe's Mixamo termspermit using those clips in a project, which is exactly what the defaultdiff --git a/docs/ar-studio.md b/docs/ar-studio.mdindex 503e3caf6..ac3742e56 100644--- a/docs/ar-studio.md+++ b/docs/ar-studio.md@@ -3,7 +3,7 @@AR Studio turns your camera view into an infinite canvas. Place as many 3D models and avatars as you like into the room around you, drawn from your own forges, the community gallery, a pasted GLB link, or brand-new ones forged from a text prompt without leaving the scene. It scales from full WebXR immersive AR down to camera passthrough down to a desktop 3D preview, and it can go multiplayer: open a shared room and everyone in it builds the same scene live. Share an arrangement with a link, or hand it to your phone with a QR code.Page: [/ar/studio](https://three.ws/ar/studio)-API: `POST /api/forge` (in-view text-to-3D) · `GET /api/forge-gallery` (your and community models) · `GET /api/objects/library` (the CC0 prop library). Multiplayer runs on a Colyseus room, `studio_world`.+API: `POST /api/forge` (in-view text-to-3D) · `GET /api/forge-gallery` (your and community models) · `GET /api/objects/library` (the CC0 prop library) · `POST /api/forge-scene-objects` (scene from a photo). Multiplayer runs on a Colyseus room, `studio_world`.## Why it exists@@ -28,7 +28,7 @@ Edit the shared modules in `packages/ar-studio`, not in `src/`. The directory is### Model sources-`addModel({ src, title })` normalizes the URL (https or site-relative only), enforces a 20-model cap, clones the loaded template (using SkeletonUtils for skinned rigs), and drops it on the floor in front of the camera. The "Add models" tray has five tabs:+`addModel({ src, title })` normalizes the URL (https or site-relative only), enforces a 20-model cap, clones the loaded template (using SkeletonUtils for skinned rigs), and drops it on the floor in front of the camera. The "Add models" tray has six tabs:- **Recent forges**: read from local storage (`twx_ar_forge_recent`), shared with `/ar` so one forge history opens in two doors.- **Yours**: `GET /api/forge-gallery?limit=24` with an `x-forge-client` header (your anonymous browser id). Forge cards are titled with the first clause of the prompt they were generated from (`cardTitleFromPrompt`), with the whole prompt as the tooltip; a poster that fails to load falls back to the cube mark a poster-less item uses.@@ -37,8 +37,9 @@ Edit the shared modules in `packages/ar-studio`, not in `src/`. The directory isBoth gallery reads and the objects manifest answer with `Access-Control-Allow-Origin: *`: they are public, keyless, read-only feeds, and the standalone studio (npm `3d-ar-studio`) offers them as its Community and Objects tabs from whatever origin a developer embedded it on. Rate limiting, not origin, is the control.- **GLB link**: paste any https `.glb`: a forge result, a viewer share link's `src`, or your own hosting.+- **From a photo**: paste a public https photo link and `POST /api/forge-scene-objects` (SAM 3D Objects) finds the objects in it and rebuilds them as one GLB with a named node per object, laid out like the photo. The tab polls `GET /api/forge-scene-objects?job=<id>` every 4 seconds (up to 150 polls) and drops the finished scene in as a single model titled "Photo scene". The endpoint answers `503 backend_unconfigured` until the GPU worker ([`workers/model-sam3d-objects`](../workers/model-sam3d-objects/README.md), 32 GB+ GPU) is deployed and `MODEL_SAM3D_URL` is set, and the tab shows that message; requests from comprehensively sanctioned territories are refused before any work is queued.-A sixth source is the **in-view forge**: the dock form calls `POST /api/forge` with `{ prompt, backend: 'nvidia' }` (the free NVIDIA NIM / TRELLIS lane), polls `GET /api/forge?job=<id>` until the GLB is ready, remembers it, and drops it into the scene. A seventh is deep links: repeatable `?src=` (paired with `?title=`) and `?forge=<prompt>` boot content on open.+A seventh source is the **in-view forge**: the dock form calls `POST /api/forge` with `{ prompt, backend: 'nvidia' }` (the free NVIDIA NIM / TRELLIS lane), polls `GET /api/forge?job=<id>` until the GLB is ready, remembers it, and drops it into the scene. An eighth is deep links: repeatable `?src=` (paired with `?title=`) and `?forge=<prompt>` boot content on open.### Device-capability ladderdiff --git a/docs/avatar-reconstruction.md b/docs/avatar-reconstruction.mdindex 13dd5a182..c4b6d7d7c 100644--- a/docs/avatar-reconstruction.md+++ b/docs/avatar-reconstruction.md@@ -44,6 +44,10 @@ poll would have, so an abandoned job still lands in the library. Design notes:- **BYOK jobs (meshy/tripo) stay browser-driven.** They authenticate with theuser's own key, which the status poll resolves from request context; a cron hasno user context to decrypt it. They age out via the same window.+- **A full avatar library closes the job instead of retrying it.** Materialization+ refused by the plan quota is the owner's to fix, so the sweep fails the job with+ the same `PLAN_LIMIT_JOB_ERROR` copy (`error_kind = 'input'`) the status poll+ relays, rather than re-running the refused step every tick.- A provider 404 (`gcp_task_missing`) is terminal here, so a job whose workerrecord is genuinely gone resolves instead of being retried forever.@@ -270,7 +274,7 @@ on one L4 (24 GB); an A100 is only needed for throughput, not any single stage.## Deploy-The worker is already provisioned on Cloud Run GPU. From a clean tree:+The worker is already provisioned on Cloud Run (CPU-only, 8 vCPU / 16 GiB, `DEVICE=cpu`). From a clean tree:```bashgcloud builds submit \diff --git a/docs/cad-forge.md b/docs/cad-forge.mdindex 4eb6d6c77..c0dd76b37 100644--- a/docs/cad-forge.md+++ b/docs/cad-forge.md@@ -28,7 +28,7 @@ Describe a mechanical part in a sentence and get real CAD: a parametric [build12The page shows each of these stages live, including the kernel's actual error text during a repair. Nothing is shown to you until the kernel has accepted it.-The writer is a model ladder in [`api/_lib/cad/writer.js`](../api/_lib/cad/writer.js): Kimi K3 on NVIDIA NIM first, then Nemotron Super, then gpt-oss-120b on Groq, then the platform's general LLM chain. The order came from a bake-off against the real kernel.+The writer is a model ladder in [`api/_lib/cad/writer.js`](../api/_lib/cad/writer.js): Kimi K3 on NVIDIA NIM first, then Nemotron 3.5 Lightning, then gpt-oss-120b on Groq, then the platform's general LLM chain. The order came from a bake-off against the real kernel.### Kernel adjustmentsdiff --git a/docs/configuration.md b/docs/configuration.mdindex eeff59368..76f81b49f 100644--- a/docs/configuration.md+++ b/docs/configuration.md@@ -271,7 +271,7 @@ AVATURN_API_URL=https://api.avaturn.me**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`.+**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; `TRIPO_API_KEY` adds Tripo as a last house-key lane for avatar auto-rig (it is never inferred as the primary); with none of those the platform provider is `none` and the reconstruct endpoint falls back to a user's stored BYOK key (Meshy, Tripo) before answering `501`.```AVATAR_REGEN_PROVIDER=replicate@@ -409,7 +409,7 @@ A **live configuration file** consumed at runtime by the Cloud Run server ([`ser{"src": "/agent/([^/]+)/embed","headers": {- "content-security-policy": "frame-ancestors *; base-uri 'self'; object-src 'none'; script-src 'self' 'unsafe-inline' 'unsafe-eval' blob: https://cdn.jsdelivr.net https://cdnjs.cloudflare.com https://unpkg.com https://esm.sh https://ajax.googleapis.com https://s3.tradingview.com https://platform.twitter.com https://3d-agent.vercel.app https://three.ws; worker-src 'self' blob:; report-uri /api/client-errors",+ "content-security-policy": "frame-ancestors *; base-uri 'self'; object-src 'none'; script-src 'self' 'unsafe-inline' 'unsafe-eval' blob: https://cdn.jsdelivr.net https://cdnjs.cloudflare.com https://unpkg.com https://esm.sh https://ajax.googleapis.com https://s3.tradingview.com https://platform.twitter.com https://three.ws; worker-src 'self' blob:; report-uri /api/client-errors","x-content-type-options": "nosniff","referrer-policy": "strict-origin-when-cross-origin","permissions-policy": "microphone=(self), camera=(self), xr-spatial-tracking=*",diff --git a/docs/copy-coach.md b/docs/copy-coach.mdindex 31a07a9a2..6ae54c038 100644--- a/docs/copy-coach.md+++ b/docs/copy-coach.md@@ -18,7 +18,7 @@ Page: `pages/copy-coach.html`, `src/copy-coach.js`, `src/copy-coach.css`|---|---|---|| 1. See a real win | The most recent public trade that closed up 25% or more in the last 14 days, with its signed buy and sell transactions on Solscan and the "why it traded" [receipt](./trade-receipts.md), **right next to the same agent's full 30-day record**. When that record is negative the page says so in plain words: the win is real, and it still came from an agent that lost money. | Reading only. || 2. Ghost-copy | Leaders with closed trades in the last 30 days, each marked copyable or not against the platform's real bar (and, if not, what is missing). One click replays the chosen leader with fake money through [ghost-copy](./ghost-copy.md): fake balance, realized result, wins and losses, worst drawdown, and the equity curve. A losing replay gets a red verdict: the coach would not copy this leader with real money yet. | Fake money. No wallet, no signature, no account. |-| 3. One tiny real copy | A starter copy of the chosen leader: a fixed size per trade, a daily cap, a limit on open copies, an automatic pause if the leader draws down, and only coins that pass the safety check. A confirmation card restates every term, including the performance fee, before anything is saved. Confirm stays disabled until the user ticks "I understand copy trading can lose money", and a second box appears when their own ghost run of that leader lost. | Non-custodial, server-enforced caps, and nothing is spent at confirmation: each copied entry arrives as an intent in [/dashboard/copy](https://three.ws/dashboard/copy) that only trades if the user signs it. |+| 3. One tiny real copy | A starter copy of the chosen leader: a fixed size per trade, a daily cap, a limit on open copies, an automatic pause if the leader draws down, and only coins that pass the safety check. A copied entry is also skipped, with the reason shown on that copy, when the leader's wallet appears to be controlled by the coin's creator (the buy would just mirror the creator's own launch). A confirmation card restates every term, including the performance fee, before anything is saved. Confirm stays disabled until the user ticks "I understand copy trading can lose money", and a second box appears when their own ghost run of that leader lost. | Non-custodial, server-enforced caps, and nothing is spent at confirmation: each copied entry arrives as an intent in [/dashboard/copy](https://three.ws/dashboard/copy) that only trades if the user signs it. || 4. What comes next | Where copies show up, the leader's full record, other ghost runs, full copy with the user's own caps, and the [Sentiment Scout](./sentiment-scout.md). The advice is to stay at starter size until the record, not one good day, earns more. | Links only. |Progress (current step, completed steps, chosen leader) is remembered in thediff --git a/docs/deployments.md b/docs/deployments.mdindex 7f6bef5c5..678a697ba 100644--- a/docs/deployments.md+++ b/docs/deployments.md@@ -46,7 +46,7 @@ What lives elsewhere: the *creation* path for a Solana identity is documented in**The live feed** itself, newest first. Each row carries the agent's name (linked to its token or asset page on that chain's explorer), a truncated description, `3D` and `x402` capability tags, the chain name, the owner address (linked to the explorer), a relative timestamp with the absolute time on hover, and a `tx` link to the registration transaction where one is known.-Feed images are third-party data: whatever URL the agent's owner published on-chain, frequently on an IPFS gateway. Every remote image is routed through the same-origin `/api/img` proxy, which resolves IPFS across gateways, follows a metadata document to the real art, and always answers with a valid image, so a row never fires a failing request. Anything that is not an `http(s)`, `ipfs`, or `ar` URL degrades to a monogram tile.+Feed images are third-party data: whatever URL the agent's owner published on-chain, frequently on an IPFS gateway. Every remote image is routed through the same-origin `/api/img` proxy, which resolves IPFS across gateways, follows a metadata document to the real art, and always answers with a valid image, so a row never fires a failing request. Proxied SVGs are served under a sandboxed, script-free policy. Anything that is not an `http(s)`, `ipfs`, or `ar` URL degrades to a monogram tile. Art stored by three.ws itself (a Solana mint's `image_key`) is returned as a same-origin `/cdn/` URL, never the raw bucket domain.**Controls:**@@ -205,7 +205,7 @@ Percentages are integers, rounded, so a capability held by a very small fraction### Caching and failure- `view=stats` is cached server-side for 60 seconds and served with `cache-control: public, max-age=30`.-- The **first unfiltered feed page** (no `cursor`, no `chain`, `kind=all`) is cached server-side for 20 seconds and served with `max-age=12`, to shield the database from a thundering herd. Filtered and paged requests go straight to the database with no cache header.+- The **first unfiltered feed page** (no `cursor`, no `chain`, `kind=all`) is cached server-side for 20 seconds and served with `max-age=12`, to shield the database from a thundering herd. Filtered and paged requests skip the server-side cache and go straight to the database, though they are still served with `max-age=12`.- A database outage returns `503 service_unavailable`. Any other failure returns `502 deployments_failed`. The page renders its reconnecting state with a retry rather than a blank feed.---diff --git a/docs/desktop.md b/docs/desktop.mdindex e6e67105b..9f2014f6a 100644--- a/docs/desktop.md+++ b/docs/desktop.md@@ -153,7 +153,7 @@ gems onto the account, so nothing mined before signing in is lost. The serverrefuses a dig that comes sooner than the dig time allows (`429 dig_too_soon`,with `retry_in_sec`), stops at 300 digs a day (`429 daily_cap`) and rejects anunknown vein (`400 invalid_node`). Table and rules: `api/_lib/world-gems.js`;-storage: migration `20261015000000_world_gems.sql`.+storage: migration `api/_lib/migrations/20261015000000_world_gems.sql`.## The Grid@@ -169,7 +169,7 @@ A second place to walk: a neon wireframe room where the platform's apps are thin- **Theme.** The CTRL design system (Windows-12 lineage): Mica gradients, glassand blur presets, the CTRL token names, light and dark. Dark is the default.Light follows the site-wide `twx_theme` switch, so the desktop and every- framed page flip together. Tokens: `src/desktop/theme.css`.+ framed page flip together. Tokens: `src/desktop/theme.css`, which resolves colours and motion timings from the site-wide canonical vars in `/tokens.css` (the desktop page links that sheet).- **Shell.** Floating taskbar with pinned and running apps, Start menu, systemtray, notification centre and calendar, lock screen, power menu, Run and Aboutdialogs, desktop icons and files, right-click menus. `src/desktop/shell.js`diff --git a/docs/developer-plans.md b/docs/developer-plans.mdindex 490eb3c8b..9e47b9b3d 100644--- a/docs/developer-plans.md+++ b/docs/developer-plans.md@@ -87,7 +87,7 @@ That call is a v1 call, so a key asking about its own quota spends one call of i## Upgrade, downgrade, cancel-Plan changes are made from the dashboard with a signed-in session and a CSRF token; an API key can read its plan but never buy one. Three payment assets are accepted:+Plan changes are made from the dashboard with a signed-in session and a CSRF token; an API key can read its plan but cannot use these routes to buy one (the one exception is the agent x402 path below). Three payment assets are accepted:| Asset | How it settles || --- | --- |@@ -103,9 +103,13 @@ Plan changes are made from the dashboard with a signed-in session and a CSRF tok**Receipts.** Every settlement writes a receipt (plan, amount, asset, transaction signature or ledger id, period covered) that is listed on the Plan tab, returned by `GET /api/v1/me/dev-plan/receipts`, and sent by email. A wallet payment is idempotent on its signature: confirming the same transaction twice returns the same receipt.+### Agents: upgrade with one x402 payment++An agent that signed itself up can upgrade with no human and no form. `POST /api/billing/agent-upgrade?plan=builder` (or `scale`) with the account's API key (scope `agents:write`) answers 402 with the exact USDC-on-Solana price for moving that account to the plan today: the full price from Free, the pro-rata difference mid-period. Pay it and repeat the call with the x402 payment header. The payment settles before the handler runs, so the plan is granted only against a landed transaction, and a transaction signature can fund only one plan change. The 200 body carries the receipt and a scoped API key (read, generate, agents, wallet:read) that can never spend. `$THREE` is not offered on this route; pay in `$THREE` through the checkout above.+### The wallet flow over the API-1. `POST /api/v1/me/dev-plan/checkout` with `{ "plan": "builder", "asset": "USDC", "wallet": "<your Solana address>" }`. The response holds `checkout` (`pay_to`, `amount_atomics`, `amount_usd`, `chain: "solana"`, `expires_at`) and `tx_base64`, the unsigned transfer.+1. `POST /api/v1/me/dev-plan/checkout` with `{ "plan": "builder", "asset": "USDC", "wallet": "<your Solana address>" }`. If wallet payments are not configured the answer is HTTP 503 `payments_not_configured`; pay with credits or retry shortly. The response holds `checkout` (`pay_to`, `amount_atomics`, `amount_usd`, `chain: "solana"`, `expires_at`) and `tx_base64`, the unsigned transfer.2. Review the recipient, amount, asset and chain, then sign and send `tx_base64` with your wallet.3. `POST /api/v1/me/dev-plan/confirm` with `{ "checkout_id", "tx_signature" }`. While the chain is still confirming the answer is HTTP 202 `{ "status": "pending", "reason" }`; poll again. Once confirmed it answers `{ "status": "paid", "receipt" }` and the plan is in force.@@ -126,7 +130,8 @@ Plan changes are made from the dashboard with a signed-in session and a CSRF tok| Plan table, calculation note, `$THREE` discount | `api/_lib/dev-plans/config.js` || Gate (burst, concurrency, quota, headers, 429 and 402) | `api/_lib/dev-plans/quota.js`, called from `api/_lib/gateway.js` || Subscriptions and period rollover | `api/_lib/dev-plans/subscription.js` |-| Quotes, checkouts, confirmation, receipts | `api/_lib/dev-plans/billing.js` |+| Quotes, checkouts, confirmation, receipts, x402 plan payments | `api/_lib/dev-plans/billing.js` |+| Agent x402 upgrade | `api/billing/agent-upgrade.js` || Per-key analytics | `api/_lib/dev-plans/analytics.js` || Key cache and immediate invalidation | `api/_lib/api-key-cache.js` || Allowlist parsing and matching | `api/_lib/ip-allowlist.js` |diff --git a/docs/erc8004.md b/docs/erc8004.mdindex 8503336c1..a1ca16e76 100644--- a/docs/erc8004.md+++ b/docs/erc8004.md@@ -431,7 +431,8 @@ fetch runs behind the platform SSRF guard([api/_lib/ssrf-guard.js](../api/_lib/ssrf-guard.js)): DNS is validated, thesocket is pinned to the checked address, every redirect hop is re-validated, andthe response is capped at 2 MB. A URI pointing at a private or cloud-metadata-address is refused with `400 blocked_uri`; a host that answers with something+address is refused with `400 blocked_uri`, a body over the cap with+`413 too_large`; a host that answers with somethingother than JSON is reported as `502 invalid_json` rather than passed through.---diff --git a/docs/event-readiness/19-forge-props-live.md b/docs/event-readiness/19-forge-props-live.mdindex d350c6f04..9544eeac4 100644--- a/docs/event-readiness/19-forge-props-live.md+++ b/docs/event-readiness/19-forge-props-live.md@@ -4,7 +4,7 @@ The platform's headline capability is text to 3D, and the world's build mode can## Where the code lives-- Forge lane: `api/forge.js` (`POST /api/forge` submits, `GET /api/forge?job=` polls, `POST /api/forge?action=rig` auto-rigs; there is no separate rig handler) and siblings (`api/forge-gameready.js`, which now also accepts a settled forge purchase and echoes only its own payment error codes, and `api/forge-remesh.js`); in-world client `src/game/forge-prop.js` (submit, poll every 2.5 s, up to 6 minutes for a cold GPU start, reference photos via `/api/forge-upload` capped at 8 MB, keyed to the same `forge:cid` handle the /forge page uses so in-world forges land in the same history); page precedents in `src/forge.js` / `src/forge-studio/`. Use the platform's free text-to-3D lane and its existing rate limits; do not add a new paid dependency+- Forge lane: `api/forge.js` (`POST /api/forge` submits, `GET /api/forge?job=` polls, `POST /api/forge?action=rig` auto-rigs; there is no separate rig handler) and siblings (`api/forge-gameready.js`, which now also accepts a settled forge purchase and echoes only its own payment error codes, and `api/forge-remesh.js`); in-world client `src/game/forge-prop.js` (submit, poll every 2.5 s, up to 6 minutes for a cold GPU start, with a "Waking up a GPU" status line from the shared `coldStartLabel` in `src/shared/forge-frames.js` while a worker boots, reference photos via `/api/forge-upload` capped at 8 MB, keyed to the same `forge:cid` handle the /forge page uses so in-world forges land in the same history); page precedents in `src/forge.js` / `src/forge-studio/`. Use the platform's free text-to-3D lane and its existing rate limits; do not add a new paid dependency- Prop plumbing (already networked and persistent): `src/game/world-objects.js` (`registerUploadedProp`, mirrors the server `objects` MapSchema), `src/game/avatar-upload.js` (`uploadPropModel`, presigned upload), the `_uploadProp` flow in `src/game/coincommunities.js`, persistence via `src/game/world-persist.js`- Prop palette UI: the props panel in `src/game/coincommunities-ui.js` (the gallery tab still fetches `/api/avatars/public`; the Forge form is `forgeBtn` / `toggleForge()` reporting through the shared status strip, and the game side is `_forgeProp` in `src/game/coincommunities.js`), styles in `src/game/coincommunities.css`- The mobile lesson: `src/game/ambient-crowd.js` documents how uncapped user models killed iOS tabs, and its `CROWD_BUDGET` tiers are the sizing precedent@@ -14,7 +14,7 @@ The platform's headline capability is text to 3D, and the world's build mode can1. **A Forge tab in the prop palette.** Shipped as the Forge form in the props panel (prompt or reference photo, one forge at a time, progress in the status strip) plus the `/forge <prompt>` chat command, which opens build mode with the result armed. Still open: a short history of this session's generations, and guidance text that sets expectations honestly (the lane comment says draft-tier generations land in about 30 to 60 s; quote observed behavior, not a made-up number).2. **Placement-first flow.** Still open. Today the prop is armed as a ghost only after the GLB lands and the next click places it. Build the other order: the player aims and places a hologram placeholder immediately (ghost shell in the build style, clearly "generating", using the real async state, never a fake progress bar). When the GLB lands, it swaps in place with a brief materialize effect. On failure the hologram becomes a designed error marker with retry and dismiss.-3. **The full prop pipeline, not a side door.** Shipped: `_forgeProp` hands the finished GLB to `registerUploadedProp` and the normal `obj:spawn` placement, so it is networked to every player, persists like any other build, respects the per-player build budget, and is undoable with the existing Ctrl+Z stack. Verify a result that comes back with `durable: false` (temporary storage the server's asset allow-list may refuse) surfaces its warning and never leaves a phantom in the palette.+3. **The full prop pipeline, not a side door.** Shipped: `_forgeProp` hands the finished GLB to `registerUploadedProp` and the normal `obj:spawn` placement, so it is networked to every player, persists like any other build, respects the per-player build budget, and is undoable with the existing Ctrl+Z stack. A result that comes back with `durable: false` (temporary storage the server's asset allow-list may refuse) already raises a warning toast in `_forgeProp`; verify that a refused placement never leaves a phantom in the palette.4. **Size discipline.** Still open, and the one that matters most. `forge-prop.js` enforces no triangle or file-size ceiling and never routes through the gameready/remesh path. Run generations through it so what enters the world is capped: enforce a hard triangle and file-size ceiling in the spirit of `CROWD_BUDGET` before a model is ever registered. An oversized result is decimated or rejected with a clear message, never placed raw. This is the difference between a demo moment and a repeat of the iOS crash.5. **Abuse limits.** Still open beyond the lane's own rate limits and the client's one-forge-at-a-time guard. Per-player generation cooldown and a per-world concurrent-generation cap, enforced server-side on the endpoint, with the client showing queue position honestly.diff --git a/docs/everything.md b/docs/everything.mdindex 8dac85113..fd3ca0205 100644--- a/docs/everything.md+++ b/docs/everything.md@@ -1,6 +1,6 @@# /everything: browse every feature by goal-three.ws has about 340 product pages. The nav shows roughly 30 of them to a first-time visitor on purpose (see [onboarding-tier.md](onboarding-tier.md)), and `/sitemap` lists all of them by section. Neither answers the question a visitor actually has: "I want to animate my avatar, where do I go?"+three.ws has about 400 product pages. The nav shows roughly 30 of them to a first-time visitor on purpose (see [onboarding-tier.md](onboarding-tier.md)), and `/sitemap` lists all of them by section. Neither answers the question a visitor actually has: "I want to animate my avatar, where do I go?"`/everything` answers it. Every product page is assigned one **goal** (a job), and the page is a searchable directory of those goals.diff --git a/docs/forge-workflows.md b/docs/forge-workflows.mdindex fa00f7022..555d487c2 100644--- a/docs/forge-workflows.md+++ b/docs/forge-workflows.md@@ -161,6 +161,7 @@ The For Each loop semantics, the typed-port model and the idea of a local-GPU ge| `src/forge-workflows/editor.js` | Canvas, nodes, links, pan and zoom. || `src/forge-workflows/inspector.js` | The settings panel. || `src/forge-workflows/results.js` | Preview viewer and result links. |+| `src/forge-workflows/ui.js` | Small DOM helpers shared by the editor, inspector and page. || `src/forge-workflows/templates.js` | The four templates. || `tests/forge-workflows-graph.test.js`, `tests/forge-workflows-runner.test.js` | Unit tests for the graph and the runner. |diff --git a/docs/free-crypto-apis.md b/docs/free-crypto-apis.mdindex a30ec1fbb..96eb22b95 100644--- a/docs/free-crypto-apis.md+++ b/docs/free-crypto-apis.md@@ -64,7 +64,7 @@ We only use Kraken, Coinbase, and Bitfinex as price fallbacks. Every other major| Provider | Free offering | Key? | Notes || --- | --- | --- | --- |-| CoinGlass | Free developer tier | Yes | Cross-exchange open interest, funding, liquidations, long/short ratios. Complements our Hyperliquid-only derivatives view in `api/coin/derivatives.js`. |+| CoinGlass | Free developer tier | Yes | Cross-exchange open interest, funding, liquidations, long/short ratios. Complements our derivatives view in `api/coin/derivatives.js` (CoinGecko venue tickers, with Hyperliquid as the backup and a Deribit options block alongside). || Binance/Bybit funding + OI endpoints | Keyless | No | Raw per-venue inputs if we aggregate ourselves. |## On-chain analytics and indexing (EVM + multichain)diff --git a/docs/galaxy.md b/docs/galaxy.mdindex ecd67a1b4..a8f1b2f35 100644--- a/docs/galaxy.md+++ b/docs/galaxy.md@@ -21,6 +21,8 @@ The page ([`pages/galaxy.html`](../pages/galaxy.html)) loads [`src/galaxy.js`](.6. **Inspect.** Clicking a star opens an in-scene card with the agent's thumbnail, constellation, description, and meta chips (net worth, chat count, token), plus two actions: "View agent" and "Chat", both on the canonical `/agents/:id` route.7. **Search.** The search box POSTs `{ query }` to `/api/galaxy`, which embeds the query with the model the current map was built with and ranks stored agent vectors by cosine similarity (`ranking: "semantic"`). The client highlights matches and flies the camera to the best one. When the embedder cannot answer (unreachable, or no vector returned) there is deliberately no other embedding lane to fall back to, because the stored vectors live in one model's space and a vector from another model would be compared in a different geometry; instead the same corpus is ranked lexically ([`api/_lib/lexical-rank.js`](../api/_lib/lexical-rank.js)) and the response says so with `ranking: "lexical"` and `degraded: { reason: "embedder_unavailable", detail, retryable: true }`, so a search still returns useful matches rather than a `502`.+8. **Money-Cam.** The Money-Cam toggle (enabled once the galaxy has rendered) overlays the live economy from `GET /api/galaxy/flows`: real, explorer-verifiable transfers that touch at least one public agent, drawn as a pulse travelling star to star (agent to agent) or a flare on one star (a tip or DEX trade). Live mode polls for new flows (`?since=<cursor>`); Replay scrubs older history (`?cursor=<cursor>`) with play/pause and speed control. Filter by All, Tips, Trades, Pay or Launches (`?type=`). There are no synthetic edges: a quiet platform shows an empty feed. Private and pulse-opted-out agents never appear, and owner-private events (withdrawals and the like) are excluded.+Only projected coordinates and cluster centroids are sent to the browser; raw high-dimensional vectors never leave the server.## Walkthroughdiff --git a/docs/github-growth.md b/docs/github-growth.mdindex 5ad4e97c4..683dd38ee 100644--- a/docs/github-growth.md+++ b/docs/github-growth.md@@ -57,6 +57,8 @@ The README carries animated charts rendered by `scripts/lib/profile-visuals.mjs`| `languages` | Extruded donut of primary languages that spins in 3D || `punchcard` | Repo creation by weekday and hour (UTC) |+The README header also carries a star-history "Top Committer 2026" badge on its own centered row under the follower badges.+The same run adds an **About** section (the owner's background, first person) and a **How I build** section of coding analytics, rendered by `scripts/lib/profile-visuals.mjs` from numbers computed in `scripts/lib/profile-activity.mjs`:| Asset | What it shows |diff --git a/docs/home-plans.md b/docs/home-plans.mdindex a13899ca1..ceb3d716c 100644--- a/docs/home-plans.md+++ b/docs/home-plans.md@@ -283,6 +283,13 @@ with a real conversation rather than only with a unit test:arm is recognised with no live entity list and therefore in precisely the degraded states wheresomebody most needs to lock up.+Home tools are also **only offered to the agent's owner**. When a signed-in visitor chats with an+agent they do not own, `homeToolsOffered` in [`api/chat.js`](../api/chat.js) withholds every home+tool for that turn, because the other account's persona and custom skills share the prompt and the+tools would run under the visitor's authority. A turn with no agent, or with the visitor's own+agent, keeps them. That is a trust boundary rather than a quota, so it applies on every plan, and+it does not touch the safety exemption: the exemption governs limits, not who may be offered a tool.+The gate also **fails open**. An unreadable entitlement row or an unreachable usage counterresolves to "allowed", never to "refused": a quota that errs must err toward serving the user, andrefusing a person access to their own house over a billing hiccup is the failure this lane is leastdiff --git a/docs/home-security.md b/docs/home-security.mdindex bcb2c3775..0471d0886 100644--- a/docs/home-security.md+++ b/docs/home-security.md@@ -38,8 +38,11 @@ model is never permitted to assert its own confirmation.| A stranger who obtains a session | Act as the user | The gate. An unlock still needs a fresh, single-use, 90 second confirmation minted server-side and redeemed by a session that also passes CSRF || A compromised or hijacked model | Call any tool with any argument | `confirmed` is absent from every home tool schema on both the MCP and the chat surface. A confirmation is only ever asserted by a browser session: `api/home/:id/confirm.js` refuses a bearer before it authenticates one, and `call.js` and `activate.js` refuse an inline `confirmed: true` from any principal that is not a session ([`canAssertConfirmation`](../api/_lib/home/access.js)). A token holding `home:act` can ask to act and is answered with the same 409 a browser gets. A standing allowance is a yes too, so `POST`/`DELETE /api/home/:id/grants` refuse every principal that is not a session for the same reason: otherwise a token could grant itself `lock.front_door` and then unlock it unconfirmed || A delegate the user authorised for something else | Hold a valid API key or OAuth token for this account | `resolveHomeAccess` reads the granted scope before it reads the home: `home:read` for a read, `home:act` for anything that changes a house. A token granted only `profile` is refused with `insufficient_scope` and never reaches the tenancy lookup |+| An agent that belongs to someone else | Put persona text or custom skills into a visitor's chat turn | Home tools run under the visitor's authority, so `homeToolsOffered` in `api/chat.js` withholds all of them whenever the visitor chats with an agent they do not own. Only a turn with no agent, or the visitor's own agent, carries them |+| A call that hides its real targets | Name one harmless entity, or an area, `all`, a scene or a script, and let Home Assistant expand it | The gate classifies the whole call (`classifyCallTargets` in [`packages/home-bridge/src/safety.js`](../packages/home-bridge/src/safety.js)): every entity id lowercased the way Home Assistant reads it, selectors (`area_id`, `device_id`, `label_id`, `floor_id`, `all`) judged as the riskiest thing they could expand to even beside a named entity, and scene, script and automation runs treated as guarded when they can reach a lock, valve, alarm or opening. The bridge forwards the same normalised data it classified. A standing allowance never covers an unresolved selector |+| A model that reaches for host administration | Call `shell_command`, `python_script`, `hassio`, `homeassistant.restart` and the like | `HomeBridge.call` refuses the denylist in [`packages/home-bridge/src/denylist.js`](../packages/home-bridge/src/denylist.js) for every transport and caller, and no confirmation lifts it. The relay protocol carries a byte-identical copy, asserted equal by the suite || A malicious device or integration in the user's own house | Control entity names, area names, scene names | Those strings reach a model, so they are treated as untrusted input: capped, structured, and never the sole basis of an action. The gate is downstream of all of them and classifies by resolved entity, not by the words in the request |-| Another household member | Hold legitimate partial access | Roles and per-entity scopes ([`api/_lib/home/members.js`](../api/_lib/home/members.js)). A role that is short answers 403 and names the role; a home you are not in answers 404 and names nothing |+| Another household member | Hold legitimate partial access | Roles and per-entity scopes ([`api/_lib/home/members.js`](../api/_lib/home/members.js)). A role that is short answers 403 and names the role; a home you are not in answers 404 and names nothing. A scoped member may only call device domains (`SCOPED_CALL_DOMAINS`: light, lock, cover, climate and similar) and must name every entity; `scene`, `script`, `automation`, `homeassistant`, `notify` and unknown domains, and any area, device, label or floor target, are refused because they reach entities the scope check never sees (`scopedCallRefusal`) || Us, operationally | Read the database | The Home Assistant token is encrypted with `secret-box` (AES-256-GCM, per-record salt, rotation-tolerant decrypt), decrypted only on the path that opens a socket, and scrubbed to empty on revoke. A relayed home holds no token at all: the house authenticates locally || A compromised relay | Speak the relay protocol to a house | Per-install pairing codes, stored as digests, single use, five wrong guesses and the pairing dies. The gate is still upstream of the relay, so a relay that speaks perfectly still cannot open a lock without a human confirmation minted on our side |@@ -77,6 +80,10 @@ Each one is a test. The number is the test's name in| 10 | Dependency posture | Every lane dependency installed, permissively licensed, and pinned to a semver range || 11 | Logout and revoke | The revoke route must scrub the credential and evict the live connection, not wait for an idle sweep |+Two further suites sit at the end of the same file without a number: the bridge and the relay+must deny exactly the same host-administration services, and a scoped member's call is refused+unless it is a target-based call on a named entity in a device domain.+### Check 4 in detail: what the injection proof actually assertsThe assertion is a lock's state, never a model's words. Model output varies run to run; adiff --git a/docs/home-voice.md b/docs/home-voice.mdindex eb91bb5d5..8bd5b3554 100644--- a/docs/home-voice.md+++ b/docs/home-voice.md@@ -40,6 +40,10 @@ listener's own machine, and both are served from three.ws itself rather than a Calways-on microphone feature, a third-party fetch on the audio path would put a stranger's serverin the room.+The home tools ride the agent turn only when it is the caller's own: `/api/chat` withholds them+(`homeToolsOffered`) when a visitor talks to an agent they do not own, because another account's+persona and skills share that prompt and the tools act with the visitor's authority.+---## What leaves your device, and what does notdiff --git a/docs/i18n.md b/docs/i18n.mdindex 58b645bba..a558250b2 100644--- a/docs/i18n.md+++ b/docs/i18n.md@@ -415,7 +415,7 @@ that still has them, reporting what it skipped:```So a locale that is mid-translation is simply absent from the switcher until the-run finishes, instead of shipping as a half-translated page.+run finishes, instead of shipping as a half-translated page. `i18n:translate` writes the manifest twice, before the run and again after it, so the locales a run just completed are listed by the time it exits rather than one run later.The switcher shrinks where space is tight. Below the 640px breakpoint, or on anypage that sets a `compact` attribute on `<lang-switcher>` (a narrow HUD rail),diff --git a/docs/irl/THREAT-MODEL.md b/docs/irl/THREAT-MODEL.mdindex 17b64ef66..a78e5a0e4 100644--- a/docs/irl/THREAT-MODEL.md+++ b/docs/irl/THREAT-MODEL.md@@ -109,8 +109,11 @@ is a speed bump with a real slope; it is not a wall.> That made the limits simultaneously useless (no per-attacker ceiling) and harmful> (one caller exhausted everyone's budget; `/api/irl/privacy` answered 429 to its> first caller). `clientIp()` now reads `X-Forwarded-For` right-to-left, skipping the-> hops our own infrastructure appends and ignoring the caller-settable prefix. The-> numbers above assume that fix is deployed; see `tests/client-ip-proxy.test.js`.+> hops our own infrastructure appends (`TRUSTED_PROXY_HOPS`, default 1: the load+> balancer) and ignoring the caller-settable prefix. On the direct `*.run.app` host,+> which bypasses the balancer, no trailing hop is skipped, so a spoofed header cannot+> rotate buckets there. IPv6 callers collapse to their /64 (`ipRateKey`). The numbers+> above assume that fix is deployed; see `tests/client-ip-proxy.test.js`.## The control that does hold: private pinsdiff --git a/docs/monitor.md b/docs/monitor.mdindex d84a69c70..f20de4c53 100644--- a/docs/monitor.md+++ b/docs/monitor.md@@ -1,7 +1,7 @@# Agent Monitor**[`/monitor`](https://three.ws/monitor)** is the ops room for the three.ws-agent fleet: twelve live panels on one screen, each one a real public endpoint+agent fleet: eleven live panels on one screen, each one a real public endpointpolled on its own cadence.Every other agent surface answers one question well.@@ -36,7 +36,7 @@ the same probe data as the Systems panel, and a refresh-all button.Every endpoint above is public and unauthenticated. Nothing on this page needs asession, and nothing on it is admin-only. The authenticated operator view lives-elsewhere: `/api/ops/health` behind `OPS_SECRET` for subsystem probes.+elsewhere: `/api/ops/health` behind an admin session or `OPS_SECRET` for subsystem probes.---@@ -47,7 +47,7 @@ The board is meant to be driven, not just watched.| Control | Where | What it does ||---|---|---|| Search | Fleet | Server-side search on name and description (`q=`), debounced |-| Sort | Fleet | `live` (most recent action), `newest`, `popular`, `name` |+| Sort | Fleet | `live` (default, labeled "recently active": ordered by most recent action), `newest`, `popular`, `name` || Prev / next / full | Spotlight | Cycle the roster without leaving the board; `full` opens the avatar fullscreen || main / dev | Money Pulse | Switch the whole pulse read between mainnet and devnet || 7d / 30d / 90d | A2A Hires | Re-query the hire ledger |@@ -76,7 +76,7 @@ text selection alive in a panel that updates every 15 seconds.**A failed panel degrades alone.** Each panel catches its own error, badgesitself `stale`, and offers a retry button. A panel that already rendered gooddata keeps showing it rather than blanking, because last-known-good beats an-empty box. One dead endpoint never takes the board down.+empty box. One dead endpoint never takes the board down. A thumbnail that fails to load (fleet, On Air, Leaders and Forge Feed rows) swaps to the designed fallback tile rather than the browser's broken-image glyph.**Empty is a designed state, not a void.** No crews yet, no casts running, nohires this window: each empty panel says what would fill it and links to thediff --git a/docs/onboarding-tier.md b/docs/onboarding-tier.mdindex 1fadf7d63..54576ec2e 100644--- a/docs/onboarding-tier.md+++ b/docs/onboarding-tier.md@@ -3,7 +3,7 @@three.ws ships a lot of surface: over 100 nav destinations and a homepage thatruns from text-to-3D through autonomous trading, on-chain identity and pay-per-callpayments. For someone who already knows the platform that breadth is the point.-For someone arriving for the first time it was the problem — the product's core+For someone arriving for the first time it was the problem: the product's corepromise (make a 3D avatar, give it a brain, put it on your site) was competing forattention with a trading terminal.@@ -14,15 +14,22 @@ and once a visitor asks for it, it stays open on every page and every visit.**Nothing is removed. Only deferred.**+Where the homepage half lives: since 2026-10-11 `/` serves the web desktop+(`pages/desktop.html`) and the long-form homepage described below, with the start+path and the advanced gate, is served at [/classic](https://three.ws/classic)+from `pages/home.html`. The nav half applies on every page that mounts+`public/nav.js`; pages framed inside the desktop hide that header because the+desktop's taskbar is the navigation.+---## What a first-time visitor sees| Surface | Lite tier | Full tier || --- | --- | --- |-| 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 ~30 destinations in one flat list | all ~126 |+| Nav menus | Build, Discover, Learn (~30 links) | + Launch (~147 links in all) |+| Homepage (`/classic`) | 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 ~30 destinations in one flat list | all ~147 |Directly under the homepage hero sits the **start path**: three steps, each with anhonest time estimate, in the order the product actually works.@@ -46,7 +53,7 @@ Any of these flips the same preference, and every other surface follows immediat- **"Show the advanced platform"** on the homepage's advanced gate- Any **topic chip** on that gate (Autonomous trading, Token economy, Oraclescoring, …), which expands and jumps to that section-- **Following a link into a gated section** — a shared `three.ws/#home-x402` URL+- **Following a link into a gated section**: a shared `three.ws/classic#home-x402` URLreveals its section for that visit rather than landing on a page that appearsto be missing content- Programmatically: `window.twsTier.set(false)` for full, `true` for lite,@@ -76,7 +83,7 @@ dropdown and drawer wiring binds document-level listeners once at mount, sore-rendering the menus would strand those listeners on detached nodes. Everydestination is always in the DOM; CSS decides what is visible.-**It never flashes.** The class is applied before paint — in the homepage's inline+**It never flashes.** The class is applied before paint, in the classic homepage's inline`<head>` boot script, and at the top of `nav.js` before the menus are rendered. Avisitor never sees advanced content appear and then vanish.@@ -100,16 +107,16 @@ Add it to `public/nav-data.js` as usual. Then decide the tier:Tag it `advanced` when someone would have to already know what it is to want it:trading terminals, payment protocols, on-chain intel, capture rigs. Leave it in the-lite tier when it serves **creating, publishing, or browsing** — that is the journey+lite tier when it serves **creating, publishing, or browsing**: that is the journeythe lite tier exists to protect. `tier` works at three levels; the widest one wins:-- **group** — the whole menu disappears from the nav bar (this is how `Launch` is+- **group**: the whole menu disappears from the nav bar (this is how `Launch` ishandled). A wholly-advanced group deliberately gets no "show everything" footer:that control could only ever collapse the menu the visitor is reading.-- **column** — one column of a mega menu, e.g. `Money & social`. The popover+- **column**: one column of a mega menu, e.g. `Money & social`. The popoverre-lays its grid to the remaining column count (`lite-cols-N`), so a hiddencolumn never leaves an empty track.-- **item** — a single row.+- **item**: a single row.### Adding a homepage section@@ -139,6 +146,6 @@ drift silently, since the four files involved have no import edge between them:## Related-- [`public/nav-data.js`](../public/nav-data.js) — the single source of truth for every menu-- [`STRUCTURE.md`](../STRUCTURE.md) — where every product surface lives-- [`docs/start-here.md`](start-here.md) — the same journey, written for a human rather than a maintainer+- [`public/nav-data.js`](../public/nav-data.js): the single source of truth for every menu+- [`STRUCTURE.md`](../STRUCTURE.md): where every product surface lives+- [`docs/start-here.md`](start-here.md): the same journey, written for a human rather than a maintainerdiff --git a/docs/onchain-agents.md b/docs/onchain-agents.mdindex 07d619843..a0cd3bfab 100644--- a/docs/onchain-agents.md+++ b/docs/onchain-agents.md@@ -50,6 +50,7 @@ Files:| [api/_lib/onchain-deploy.js](../api/_lib/onchain-deploy.js) | Shared mint logic — collection resolution, manifest pin, Core mint, DB persist. || [scripts/deploy-agents-onchain.mjs](../scripts/deploy-agents-onchain.mjs) | CLI runner — dry-run preview, canary, full fleet. || [scripts/register-agents-onchain.mjs](../scripts/register-agents-onchain.mjs) | CLI back-fill: enrols already-minted agents that have a Core asset but no Agent Identity PDA (same `--network` / `--limit` / `--dry-run` / `--confirm` flags). |+| [scripts/register-8004-agents.mjs](../scripts/register-8004-agents.mjs) | CLI back-fill for the 8004 registry enrolment (see [Open Solana agent registry](solana-agent-registry.md)). || [api/_lib/solana-collection.js](../api/_lib/solana-collection.js) | Collection authority + address helpers. || [api/_lib/three-brand.js](../api/_lib/three-brand.js) | Manifest + on-chain attributes builders. |@@ -135,7 +136,7 @@ On a confirmed mint, `deployAgentOnce()` writes to `agent_identities.meta`:`sol_mint_address` is the canonical key every read path uses (explore, discover, profiles). It also makes re-runs **idempotent**: an agent that already has it is skipped. (Devnet runs are isolated under `meta.devnet` so they never block a real mainnet mint.) An `agent_actions` row (`type: solana.deploy`) is logged, and on mainnet a truthful `agent-onchain` feed event fires.-Right after the mint, `registerAgentOnce()` enrols the asset in the Metaplex Agent Registry. The collection authority signs (the owner still never signs and needs no SOL), the Agent Identity PDA's URI is set to the agent's live `/api/agents/:id/registration` document rather than a pinned snapshot (the registry program has no instruction to change a URI later, so a mutable endpoint keeps `active`, services, and the model current), and an `agent_registry` block is merged into the same `meta` (`standard: metaplex-agent-registry`, `program`, `identity_pda`, `asset`, `collection`, `authority`, `registration_uri`, `network`, `tx_hash`, `registered_at`; under `meta.devnet` for devnet runs). A second `agent_actions` row (`type: solana.register`) is logged. A registry failure never undoes the mint: the asset and `sol_mint_address` are already persisted, the runner prints `registry skipped: <error> (back-fill later)`, and `scripts/register-agents-onchain.mjs` picks up every agent that has `sol_mint_address` but no `agent_registry.identity_pda`.+Right after the mint, `registerAgentOnce()` enrols the asset in the Metaplex Agent Registry. The collection authority signs (the owner still never signs and needs no SOL), the Agent Identity PDA's URI is set to the agent's live `/api/agents/:id/registration` document rather than a pinned snapshot (the registry program has no instruction to change a URI later, so a mutable endpoint keeps `active`, services, and the model current), and an `agent_registry` block is merged into the same `meta` (`standard: metaplex-agent-registry`, `program`, `identity_pda`, `asset`, `collection`, `authority`, `registration_uri`, `network`, `tx_hash`, `registered_at`; under `meta.devnet` for devnet runs). A second `agent_actions` row (`type: solana.register`) is logged. The same step also enrols the agent in the open 8004 Solana agent registry (`register8004Agent` in `api/_lib/solana-8004.js`, stored as `meta.registry_8004`). It is always on for devnet and opt-in on mainnet via `SOLANA_8004_REGISTER_MAINNET=1`, and a failure there is reported and left for `scripts/register-8004-agents.mjs`; see [Open Solana agent registry](solana-agent-registry.md). A Metaplex registry failure never undoes the mint: the asset and `sol_mint_address` are already persisted, the runner prints `registry skipped: <error> (back-fill later)`, and `scripts/register-agents-onchain.mjs` picks up every agent that has `sol_mint_address` but no `agent_registry.identity_pda`.---@@ -279,6 +280,7 @@ A confirmed canary asset shows `inCollection=true`, `royalty=500bps`, `attrs=11`## See also- [Solana agents](solana.md) — the single-agent, user-signed registration flow.+- [Open Solana agent registry](solana-agent-registry.md): the 8004 enrolment and trust tiers.- [ERC-8004](erc8004.md) — the EVM on-chain identity path.- [Agent manifest](agent-manifest.md) — the metadata schema.- [Mint mark ("3ws")](mint-mark.md) — vanity marking for three.ws launches.diff --git a/docs/ops/agent-index.md b/docs/ops/agent-index.mdindex 993eb5a41..ff75efea9 100644--- a/docs/ops/agent-index.md+++ b/docs/ops/agent-index.md@@ -109,6 +109,7 @@ gcloud logging read 'resource.type="cloud_run_revision" resource.labels.service_| EVM `block range` / `response size` / `query returned more than` / `ranges over N blocks` | The window was too wide. dRPC's free tier says `ranges over 10000 blocks` for any window above about 100 blocks, so its number is not the real ceiling. | Self-healing: `backoffChunkSize()` halves it in place and the width is persisted in `chunk_size`. || EVM `limit exceeded` | A plan or compute limit, **not** a range ceiling. | Shrinking does not help. Deliberately excluded from `isRangeRejection`. || EVM `ENOTFOUND` / `HTTP 401 … tenant disabled` / `chain is not available on free plan` | The lane is gone, not busy. | Replace it in that chain's `rpcUrls` with a lane probed to serve `eth_getLogs` at the chain's window. A failing tick still banks `head_block` and `blocks_behind`, so a chain stuck on dead lanes shows its real backlog instead of the 0 its last good crawl left. |+| EVM `shrink loop exceeded 60000ms budget at chunk N` (in `last_error`) | One chain's shrink-retry loop ran past `ERC8004_CHAIN_BUDGET_MS` (a slow or rejecting lane burning wall clock). | Self-healing: the crawl checkpoints `head_block`, `blocks_behind` and `chunk_size` and returns, so the next tick resumes instead of replaying the same blocks. Persistent means the chain's lanes are slow: replace them in `rpcUrls`. || EVM `HTTP 403 from <host>` | A lane refused us with no readable JSON-RPC body. | The body is read first now, so a bare status here means the lane returned nothing to classify. The chain needs a lane that answers from a datacenter IP; see the `rpcUrls` note in `api/_lib/erc8004-chains.js`. |## Recovery: drain a wedged backlog now@@ -139,9 +140,10 @@ that is months behind changes nothing they can see.Read the numbers from `index-lag.js`; they are exported so nothing has to quotethem. Two rules shape the verdict:-- **An EVM-only fault caps at `degraded`.** Letting a stale secondary cursor- drive the whole subsystem to `down` reports an outage no user is having, and- it buries the Solana leg's real state.+- **An EVM-only fault caps at `degraded`.** The cap applies whenever the Solana+ leg is anything short of `down` (fresh, or merely degraded). Letting a stale+ secondary cursor drive the whole subsystem to `down` reports an outage no user+ is having, and it buries the Solana leg's real state.- **The Solana error rate is scored, not just the cursor age.** The sweep stamps`last_indexed_at` on the failure path too (deliberately, so one unreadableaccount cannot hold the oldest-first queue head forever), which means a wedgeddiff --git a/docs/ops/forge-storage-failover.md b/docs/ops/forge-storage-failover.mdindex e9e389dcc..d6338419e 100644--- a/docs/ops/forge-storage-failover.md+++ b/docs/ops/forge-storage-failover.md@@ -50,7 +50,8 @@ inline as a `data:` URI, and the generation continues:"Storage infrastructure fault" is `isStorageInfrastructureError` in[api/_lib/r2.js](../../api/_lib/r2.js): a rejected or revoked credential, a-missing bucket, an unreachable endpoint. Object-level faults are not included,+missing bucket, an account not entitled to R2 (`NotEntitled`), an unreachable+endpoint. Object-level faults are not included,because those blame the object and the fallback would be wrong.### Which lanes may receive an inline view@@ -58,7 +59,7 @@ because those blame the object and the fallback would be wrong.Only ours. `backendAcceptsInlineViews` in[api/_lib/forge-tiers.js](../../api/_lib/forge-tiers.js) is true exactly for thebackends whose `provider` is `gcp` (`trellis2`, `trellis_selfhost`, `hunyuan3d`,-`modly`, `modly_hunyuan`, `triposg`),+`modly`, `modly_hunyuan`, `triposg`, `pixal3d`, `anigen`, `partcrafter`),and it is derived from the registry rather than a hand-written list, so a backendadded later is classified by what it is.@@ -76,6 +77,10 @@ that names the real cause and suggests the lanes that can still run:}```+When the write failure happens later, after a lane was already chosen, the+handler answers a generic 503 `storage_unavailable` with `retry_after: 60`+instead of a 502 carrying the vendor's sentence.+That path also closes the information leak: a caller is no longer told to checkour secret access key.@@ -119,5 +124,5 @@ listed in `/.well-known/x402.json`.- Daily automated version of the same bar: [api/cron/forge-smoke.js](../../api/cron/forge-smoke.js), 09:30 UTC, alerts to ops Telegram.- Which failure classes recur, from the outcome ledger: [forge-error-triage.md](./forge-error-triage.md).-- The credential's own health signal: [api/_lib/ops/object-storage-health.js](../../api/_lib/ops/object-storage-health.js).+- The credential's own health signal: [api/_lib/ops/object-storage-health.js](../../api/_lib/ops/object-storage-health.js). It retries the signed list once after a 300 ms backoff before classifying the bucket down (`metrics.retried`), so a one-off network blip does not page, while two consecutive failures still do.- Worker URLs and env: [gcp-model-workers.md](./gcp-model-workers.md).diff --git a/docs/ops/materialize-fulfillment.md b/docs/ops/materialize-fulfillment.mdindex 3e07c0a85..0ae520dea 100644--- a/docs/ops/materialize-fulfillment.md+++ b/docs/ops/materialize-fulfillment.md@@ -122,6 +122,29 @@ Always configured, because it needs a person rather than a credential.- There is no webhook. `verifyWebhook()` refuses every delivery rather thanleaving an unauthenticated door open on a lane that cannot call it.+### `craftcloud`, quotes and a reserved cart++[api/_lib/print/adapters/craftcloud.js](../../api/_lib/print/adapters/craftcloud.js).+Craftcloud (All3DP) fronts a network of about 186 print shops through a public+API that needs no key, so the adapter is always configured and is registered+ahead of `partner-cn` and `manual`. It uploads the model, prices it across the+whole catalog and takes the cheapest live quote. It goes exactly as far as+reserving a cart (price locked, quote and shipping selected, the referral+voucher applied when one is set) and no further: creating an upstream order+exposes a payment step, which is a spend, so an operator completes checkout on+Craftcloud by hand. For that reason `status()` and `cancel()` have no upstream+order to poll.++The same adapter powers the buyer-direct "Get it printed" flow+(`POST /api/print/craftcloud-quote`, [src/craftcloud-print.js](../../src/craftcloud-print.js)),+where the buyer pays Craftcloud rather than three.ws; see+[../materialize.md](../materialize.md) for how that differs from the paid+in-house pipeline.++Optional env: `PRINT_CRAFTCLOUD_VOUCHER_CODE` (a referral code pasted in from a+Craftcloud account made by hand), `PRINT_CRAFTCLOUD_API_BASE` and+`PRINT_CRAFTCLOUD_CUSTOMER_API_BASE` (host overrides).+### `partner-cn`, wired and waiting on a contract[api/_lib/print/adapters/partner-cn.js](../../api/_lib/print/adapters/partner-cn.js).@@ -146,11 +169,11 @@ the credentials exist.### Adding a lane-1. Write the module beside the other two, satisfying the interface above.+1. Write the module beside the others, satisfying the interface above.2. Register it in [adapters/index.js](../../api/_lib/print/adapters/index.js).Order matters: the first configured adapter that supports an order is the- default route, and `manual` is deliberately last. A contracted partner- should take a job it can run; a human should take everything else.+ default route, and `manual` is deliberately last. A lane that can run a job+ without a human should take it; a human should take everything else.3. Add it to the conformance suite's adapter list in[tests/print-adapter-contract.test.js](../../tests/print-adapter-contract.test.js).Every adapter runs through the same checks; that is the point.@@ -247,6 +270,7 @@ reloads, so it can be acted on rather than glimpsed.| `OPS_SECRET` | script access to the ops API | The dedicated ops credential. Never `CRON_SECRET`. || `CRON_SECRET` | the sweep | Standard cron gate. || `TELEGRAM_BOT_TOKEN` + `TELEGRAM_PRINT_OPS_CHAT_ID` | Telegram paging | Falls back to `TELEGRAM_ALERTS_CHAT_ID`. Without either, paging degrades to the bell and `ops_alerts`. |+| `PRINT_CRAFTCLOUD_VOUCHER_CODE` | referral discount on Craftcloud carts | Optional. The adapter works without it. || `PRINT_PARTNER_CN_URL` + `PRINT_PARTNER_CN_KEY` | the partner lane | Absent today. Until both exist the adapter is not registered at all. |## Diagnosing a stuck orderdiff --git a/docs/ops/redis.md b/docs/ops/redis.mdindex 419b14fac..0d1db2f8d 100644--- a/docs/ops/redis.md+++ b/docs/ops/redis.md@@ -187,21 +187,23 @@ to `local` (no Redis command) or must stay Redis-backed.| `mcp3dGenerate`, `mcpValidate`, `mcpInspect`, `mcpOptimize`, `mcpBazaar`, `mcpAgent`, `mcpAgentPay` | critical | paid compute / paid tools || `avatarPayoutDaily`, `agentBuy`, `x402PayGlobal`, `videoGenerateUser`, `videoGenerateGlobal` | critical | real money movement || `bountyJudge`, `voiceClone`, `ttsSpeakUser`, `ttsSpeakIp` | critical | paid synthesis / inference |-| all other `*Ip` / `*User` read & write limiters | cross-instance-required | distributed per-principal caps; fail open on outage |+| further `local` read/poll guards (`authedReadIp`, `mcpIp`, `mcpUser`, `walletRead`, `imgProxyIp`, `galaxyIp`, and others; grep `local: true` in `rate-limit.js` for the full set) | local | per-instance flood guards, zero Redis commands |+| all other `*Ip` / `*User` read & write limiters | cross-instance-required | distributed per-principal caps; fail open on outage unless marked `critical` in `rate-limit.js` |### Direct Redis usage (cache, feeds, ledgers)| File | Class | Operation || --- | --- | --- |-| `api/_lib/cache.js` | cross-instance-required | shared cache GET/SET/DEL (read-memo + single-flight in front to cut burn); `cacheWrapLastGood()` keeps a `<key>:lkg` sibling (24h) that is served when a refresh throws, so an upstream blip returns last-good data instead of an error |+| `api/_lib/cache.js` | cross-instance-required | shared cache GET/SET/DEL plus `cacheSetIfAbsent` (`SET NX EX`, per-instance memory as the degraded fallback) (read-memo + single-flight in front to cut burn); `cacheWrapLastGood()` keeps a `<key>:lkg` sibling (24h) that is served when a refresh throws, so an upstream blip returns last-good data instead of an error || `api/_lib/feed.js` | cross-instance-required | activity feed LPUSH/LTRIM/LRANGE (8s read-coalesce window) || `api/_lib/usage.js` | cross-instance-required | usage-event buffer RPUSH/LRANGE/LTRIM (batched flush) || `api/_lib/x402-spending-ledger.js` | critical / cross-instance-required | atomic INCRBY spend caps per hour/day/address |-| `api/_lib/a2a/spend-ledger.js` | critical / cross-instance-required | agent-to-agent daily payout caps |-| `api/_lib/x402/idempotency-cache.js` | critical / cross-instance-required | payment replay dedup (GET/SET) |+| `api/_lib/a2a/spend-ledger.js` | critical / cross-instance-required | agent-to-agent daily payout caps; in production with no Redis, reads and reservations are refused (fail closed) because a per-instance ledger would multiply every mandate budget by the instance count |+| `api/_lib/x402/idempotency-cache.js` | critical / cross-instance-required | payment replay dedup (GET/SET); proofs are hashed over the payment's canonical identity so re-encoding a header cannot dodge the check |+| `api/_lib/idempotency.js` | cross-instance-required | shared `Idempotency-Key` store (24h): atomic claim via `cacheSetIfAbsent`, used by the v1 agents API, the free 3D studio and `runOnce` callers || `api/_lib/builds-store.js` | cross-instance-required | build metadata + per-mint index cache || `api/_lib/alerts.js` | cross-instance-required | ops-alert dedup + hourly ceiling |-| `api/x402-pay.js`, `api/feed-stream.js`, `api/_lib/channel-feed-sources.js`, `api/_lib/pumpfun-mcp.js` | cross-instance-required | demo payment feed + feed reads |+| `api/x402-pay.js`, `api/feed-stream.js`, `api/_lib/channel-feed-sources.js`, `api/_lib/pumpfun-mcp.js` | cross-instance-required | paid-call feed (`x402:pay:feed`) + feed reads || `api/cron/uptime-check.js`, `api/cron/quota-check.js`, `api/cron/flush-usage-events.js` | cross-instance-required | cron cache snapshots + buffer drain |> The spend-ledger and idempotency entries are both critical (money-moving) anddiff --git a/docs/ops/trading-bot-report.md b/docs/ops/trading-bot-report.mdindex b407d4724..325bae9a9 100644--- a/docs/ops/trading-bot-report.md+++ b/docs/ops/trading-bot-report.md@@ -73,7 +73,7 @@ an RPC blip must not report a healthy fleet as starved.retries up to five times, so a full sweep takes about a minute. Point it atthe production Helius endpoint for a fast run.- SOL/USD comes from `api/_lib/sol-price.js`, the platform's nine-source- failover chain, so the dollar columns are spot. If every source is down it+ failover chain (ordered by recent canary health, so a degraded source is tried last), so the dollar columns are spot. If every source is down itfalls back to the last price stamped into `sniper_trade_analytics`.## Relateddiff --git a/docs/permissions.md b/docs/permissions.mdindex 5a28158dd..6f7536ec1 100644--- a/docs/permissions.md+++ b/docs/permissions.md@@ -99,6 +99,8 @@ const signed = await signDelegation(delegation, signer);// signed.hash — keccak256 of the struct (safe to log; never log the signature)```+To check a delegation against the chain from code, call `isDelegationValid({ hash, chainId, delegation? })` from the same module. It has three outcomes, not two: `{ valid: true }`, `{ valid: false, reason }` naming what is wrong (for example `delegation_revoked`), and `{ valid: null, reason: 'rpc_unavailable' }` when no RPC could be reached. An outage is not evidence of revocation, so callers decide deliberately whether null fails closed. The RPC is the pinned `rpcUrl` or `RPC_URL_<chainId>` first, then the same-origin proxy and public hosts.+Then store the signed delegation via `POST /api/permissions/grant`:```jsdiff --git a/docs/play-hardening.md b/docs/play-hardening.mdindex 50dfc4723..30e310561 100644--- a/docs/play-hardening.md+++ b/docs/play-hardening.md@@ -77,7 +77,7 @@ The app bundle is not on screen yet while the boot loader is up, so the loader h- `name` is capped at 28 characters and `symbol` at 12, cut on a word boundary.- Anything unexpected throws into a `catch` that leaves the generic loader exactly as it shipped.-The art has a designed failure path in both places it appears. In the loader, a monogram sits under the `<img>` and the image only fades in on `load`; an `error` removes the `<img>` and leaves the monogram. In the world, the HUD banner's `.cc-coin-img` does the same against `.cc-coin-mono` ([src/game/coincommunities-ui.js](../src/game/coincommunities-ui.js)). The 3D totem and jumbotron already degraded to text-only on a failed `TextureLoader` fetch. This matters on venue wifi, where the IPFS gateway behind `/api/img` is the single most likely thing to fail while everything else about the world works. A single gateway is also no longer the only try: `uriCandidates()` in [src/ipfs.js](../src/ipfs.js) expands an `ipfs://` source, or a URL that already names one gateway, into one candidate per gateway in preference order, and each fetch is bounded at 8 s, so one rate-limited gateway degrades to the next rather than to the monogram.+The art has a designed failure path in both places it appears. In the loader, a monogram sits under the `<img>` and the image only fades in on `load`; an `error` removes the `<img>` and leaves the monogram. In the world, the HUD banner's `.cc-coin-img` does the same against `.cc-coin-mono` ([src/game/coincommunities-ui.js](../src/game/coincommunities-ui.js)). The 3D totem and jumbotron already degraded to text-only on a failed `TextureLoader` fetch. This matters on venue wifi, where the IPFS gateway behind `/api/img` is the single most likely thing to fail while everything else about the world works. A single gateway is also no longer the only try: `uriCandidates()` in [src/ipfs.js](../src/ipfs.js) expands an `ipfs://` source, or a URL that already names one gateway, into one candidate per gateway in preference order, and each fetch is bounded at 8 s, so one rate-limited gateway degrades to the next rather than to the monogram. The ladder holds only gateways that still serve subresource reads (Filebase, 4everland, Pinata); `ipfs.io`, `dweb.link`, `w3s.link` and `nftstorage.link` answer non-navigation requests with 429/403 since October 2026, so `normalizeGatewayURL()` rewrites a URL naming one of them onto a working gateway. `/api/img` walks the same list on the server (`api/_lib/ipfs-gateways.js`), and serves every proxied body under a sandboxed, script-free `Content-Security-Policy` so a hostile SVG opened directly cannot run script on the three.ws origin.The loader also sets a provisional `document.title` from the link and stashes the original in `documentElement.dataset.lobbyTitle`; `_setTabTitle()` in [src/game/coincommunities.js](../src/game/coincommunities.js) replaces it with the resolved coin on entry and restores the stashed original on leave, so the two writers never fight and the localised title is never re-spelled in JS.diff --git a/docs/pump-claims-channel.md b/docs/pump-claims-channel.mdindex d25a3ac48..12a007fa4 100644--- a/docs/pump-claims-channel.md+++ b/docs/pump-claims-channel.md@@ -209,7 +209,7 @@ State lives in `app_settings` under `pump_claims_push_telegram`:This limit is specific to **ordinary wallet claims**. The GitHub fee-claim path(`_fetchGithubClaimsFromRpc`) always runs a direct RPC scan, independent of-`PUMPFUN_BOT_URL`; see "Verifying it" below for a live check of that path.+`PUMPFUN_BOT_URL`; see "Verifying it" above for a live check of that path.`scanFirstClaims` prefers the `PUMPFUN_BOT_URL` indexer for wallet claims andfalls back to a direct RPC scan of the pump program's recent signatures. **Thatdiff --git a/docs/pump-launch-repos.md b/docs/pump-launch-repos.mdindex 2953c346c..68aa0f5d5 100644--- a/docs/pump-launch-repos.md+++ b/docs/pump-launch-repos.md@@ -75,8 +75,11 @@ lamport delta before committing mainnet SOL.## Safety-- **Localhost only.** The UI never binds a public route; keys never leave your- machine.+- **Meant for localhost only.** The UI is a local tool with no authentication and+ serves the key bundle download, and `server.listen` is called without a host, so+ Node accepts connections on every interface. Run it on a machine you trust and+ keep port `4599` firewalled; never forward or tunnel it. Keys never leave your+ machine through the app itself, and key files are written with mode `0600`.- **Nothing is sent until you Launch** against a funded master. `generate`,`verify`, `preflight`, and repo browsing are all free and offline of on-chainspend.diff --git a/docs/recurring-payments.md b/docs/recurring-payments.mdindex e9b69b9e3..2429b069f 100644--- a/docs/recurring-payments.md+++ b/docs/recurring-payments.md@@ -7,7 +7,7 @@ Two kinds of schedule ride the same rails:| Kind | What it does each period | Table | Cron ||---|---|---|---|| **Subscription** | Transfers a fixed USDC amount to an agent's wallet | `agent_subscriptions` | `/api/cron/run-subscriptions`, hourly |-| **DCA strategy** | Swaps a fixed USDC amount into a target token through Uniswap V3 | `dca_strategies` | `/api/cron/run-dca`, hourly |+| **DCA strategy** | Swaps a fixed USDC amount into a target token through Uniswap V3 | `orders` (rail `evm`, see [Schema](#schema)) | `/api/cron/run-dca`, hourly |Both are managed at **[/recurring](https://three.ws/recurring)**.@@ -52,6 +52,8 @@ Resuming never back-fills. A schedule resumed after two missed weeks charges oncAll endpoints require a signed-in session (or a bearer API key on `/api/agent-subscriptions`). Cookie-session mutations need the double-submit CSRF token from `/api/csrf-token`.+Two gates apply to anything that arms a charge. Creating or resuming a schedule (subscription or DCA) needs a signed Terms of Service, Risk Disclosure and Agent Wallet Agreement on the account, otherwise it is refused with `403 risk_ack_required`. And a bearer API key needs the `wallet:write` scope to create or resume a subscription; without it the call is refused with the "needs a browser session on three.ws" answer. Pausing and cancelling stop money moving, so any key that owns the schedule may do them. DCA strategies accept a browser session only.+### Subscriptions```bash@@ -108,7 +110,7 @@ Cancelling stops the charges and leaves the permission alone. To stop the agent### DCA strategies-`/api/dca-strategies` has the same lifecycle with a path-addressed id.+`/api/dca-strategies` has the same lifecycle with a path-addressed id. It is a compatibility facade over the unified order store: the `<id>` is the strategy's order id (the old `dca_strategies` id is accepted too), and the unified endpoint covering both the Solana and EVM rails is `/api/agents/:id/orders/dca`.```bashcurl -X POST https://three.ws/api/dca-strategies \@@ -158,10 +160,11 @@ Recurring charges settle through `/api/permissions/redeem`, which needs the EVM|---|---|| `agent_subscriptions` | One row per subscription schedule, with `status`, `next_charge_at`, `consecutive_failures`, `last_error_code`, `paused_at`, `resumed_at` || `subscription_charges` | One row per charge attempt: `status`, `code`, `outcome`, `tx_hash`, `amount`, `period_start_at`. A partial unique index on `(subscription_id, period_start_at)` for successful charges makes a double-charge impossible to record |-| `dca_strategies` | One row per DCA schedule, same lifecycle columns |-| `dca_executions` | One row per swap attempt, with the quote, the divergence, and the fill |+| `orders` | One row per DCA schedule (`type` `dca`, `network` `evm`, `venue` `evm_delegation`), with `status`, `next_fire_at`, the period in `schedule.interval_seconds`, `slippage_bps` and `delegation_id` |+| `order_fills` | One row per swap attempt, with the quote, the divergence, and the fill. The attempt log is served in the legacy `executions[]` shape |+| `dca_strategies`, `dca_executions` | Legacy tables. Their rows were copied into `orders` and `order_fills` (migration `20261010210000_orders_any_token`) and are only read to adopt rows an older image wrote during a rollout |-Definitions live in [api/\_lib/schema.sql](../api/_lib/schema.sql); the lifecycle columns and the charge ledger were added by [20260813191500_recurring_payment_lifecycle.sql](../api/_lib/migrations/20260813191500_recurring_payment_lifecycle.sql).+Definitions live in [api/\_lib/schema.sql](../api/_lib/schema.sql) and [api/\_lib/dca-unified.js](../api/_lib/dca-unified.js); the subscription lifecycle columns and the charge ledger were added by [20260813191500_recurring_payment_lifecycle.sql](../api/_lib/migrations/20260813191500_recurring_payment_lifecycle.sql).---diff --git a/docs/reputation.md b/docs/reputation.mdindex 55225d31a..22858e803 100644--- a/docs/reputation.md+++ b/docs/reputation.md@@ -11,7 +11,7 @@ Traditional rating systems (app stores, review sites) share a structural weaknesOn-chain reputation addresses all three:- **Permanent.** The blockchain is append-only. A submitted score exists as long as the chain does.-- **Publicly verifiable.** Anyone can read the `ReputationRegistry` contract directly — no API key, no account required.+- **Publicly verifiable.** Anyone can read the `ReputationRegistry` contract directly, with no API key and no account.- **Sybil-resistant.** Every review is tied to the wallet that signed it, and creating fake identities costs real gas.- **Composable.** Other applications can read the same reputation data. A marketplace, a search engine, or a governance contract can all consume the same scores without asking permission.@@ -97,7 +97,7 @@ Chains covered: Base (8453, the default), Base Sepolia (84532), Ethereum (1), OpWhat the page renders:- **Aggregate stats.** Attestation count, average star rating over the scored ones, and a 1-to-5 distribution bar. The count is labelled "attestations", not "reviews": most addresses hold attestations written against other EAS schemas (verifications, name claims), and calling those reviews would overstate the address's review history.-- **The attestation list**, filterable by All / Scored / With comments, paged 30 at a time with a running "Showing X of Y" and a **Show more** button, so a heavily attested address does not silently truncate.+- **The attestation list**, filterable by All / Scored / With comments, paged 30 at a time with a running "Showing X of Y" and a **Show N more** button, so a heavily attested address does not silently truncate.- **Every attestation's payload.** A review renders as stars plus its comment. An attestation written against any other schema renders its decoded fields (name and value) with the schema string as a tag, so no card is a blank row with only an address and a timestamp.- **An ERC-8004 badge** when the address owns an agent in the Identity Registry on that chain, showing the registry's own vote count and average, linking out to the agent's registry token on the block explorer and to [/agent-identities](https://three.ws/agent-identities).- **A review form**, wallet-gated. Writes go to Base Sepolia, a free test network, which the form states plainly before you sign.diff --git a/docs/run-receipts.md b/docs/run-receipts.mdindex 0649226fb..7656a6525 100644--- a/docs/run-receipts.md+++ b/docs/run-receipts.md@@ -1,6 +1,6 @@# Run receipts: what each stage was expected to do, and what it did-Every generation the free 3D Studio runs (`forge_avatar`, `text_to_avatar`, `mesh_forge`, `forge_free`, `rig_mesh`, `refine_model`) writes a **run receipt**. A receipt walks the pipeline stage by stage. For each stage it records:+Every generation the free 3D Studio starts (`forge_avatar`, `text_to_avatar`, `mesh_forge`, `forge_free`, `rig_mesh`) writes a **run receipt**. `refine_model` does not write one. A receipt walks the pipeline stage by stage. For each stage it records:- the **expected** result- the **observed** resultdiff --git a/docs/selfie-to-avatar.md b/docs/selfie-to-avatar.mdindex 828fe5cdf..dc3b6a5a8 100644--- a/docs/selfie-to-avatar.md+++ b/docs/selfie-to-avatar.md@@ -23,17 +23,17 @@ Two of those numbers are measured rather than reasoned about. The blur floor (`B4. **Refine, in the browser.** `assessPhoto` gates the frontal (no face is the only hard block; blur, illustration, or a distant subject are non-fatal warnings). `refineSelfie` isolates the subject from its background and reframes to a clean head-and-shoulders square, rendered at 1024x1024 with JPEG quality 0.92 ([`src/selfie-refine.js`](../src/selfie-refine.js)). The refined frontal is previewed so you see exactly what the engine sees.5. **Submit.** The pipeline ([`src/selfie-pipeline.js`](../src/selfie-pipeline.js)) downscales each photo to a 1024px longest edge at JPEG quality 0.88, POSTs them as data URIs to `/api/avatars/reconstruct`, and gets back a `jobId`. Before any GPU work starts the handler pre-flights the caller's avatar library against its plan ceiling (`assertAvatarSlotAvailable`) and refuses a full library with `402 plan_limit`, so nobody waits ninety seconds for a mesh that could never be saved.6. **Reconstruct, server-side.** The reconstruct handler (`api/avatars/_actions.js`) selects a provider through [`api/_lib/regen-provider.js`](../api/_lib/regen-provider.js). The production lane is **GCP**: it POSTs `{ images, body_type }` to the Cloud Run service behind `GCP_RECONSTRUCTION_URL`, today the [`workers/avatar-reconstruction/`](../workers/avatar-reconstruction/) FastAPI app deployed as `avatar-reconstruction`. (The multi-backend [`workers/avatar-pipeline-controller/`](../workers/avatar-pipeline-controller/) speaks the identical contract and can take over that env var, but is not deployed today.) That pipeline (`face_texture_transfer_v2`) uses **MediaPipe FaceLandmarker** (468 landmarks, Apache-2.0) to transfer your face texture and geometry onto a fixed-topology, pre-rigged Wolf3D/Ready-Player-Me-style humanoid template carrying a Mixamo-compatible skeleton, 52 ARKit blendshapes, and 15 visemes. Full engine detail is in [avatar-reconstruction.md](./avatar-reconstruction.md).-7. **Auto-rig fallback.** The template is born rigged. If a generic mesh comes back unrigged and a rig model is configured, `reconstruct-finalize.js` chains a `rerig` job (the `model-rig` worker, `workers/rig`) and moves the job through a `rigging` status before surfacing the avatar. If rigging is impossible it delivers the static mesh tagged `unrigged` rather than nothing.+7. **Auto-rig fallback.** The template is born rigged. If a generic mesh comes back unrigged and a rig lane is configured (the `model-rig` worker, a Replicate rig model, or the house-key Tripo lane behind `TRIPO_API_KEY`), `reconstruct-finalize.js` chains a `rerig` job (`workers/rig` for the `model-rig` worker) and moves the job through a `rigging` status before surfacing the avatar. If rigging is impossible it delivers the static mesh tagged `unrigged` rather than nothing.8. **Poll and finish.** The client polls `GET /api/avatars/regenerate-status?jobId=...` every ~3 seconds (backing off on errors). On `status: 'done'` it fetches the finished avatar from `GET /api/avatars/:id` and shows it in a `<model-viewer>`. A `done` job with no `resultAvatarId` means the server's materialize stage threw after the mesh was generated; that stage re-runs on every poll, so the client looks again up to three more times before treating it as a failure. If the materialization lost the quota race (another avatar landed while this one was generating), the server ends the job as `failed` with caller-facing copy rather than leaving it stranded at `done`. The poll uses the adapter for the provider recorded on the job row, not whichever provider currently leads the precedence order, because the stored job id is provider-shaped and only that backend can read it.9. **Register and mint.** Materializing the avatar also registers it in the Forge store (`forge_creations`, `path: 'reconstruct'`) so galleries, share and embed pages, and provenance treat a capture like any other creation, and fires a best-effort [draft agent identity mint](./draft-agent-mint.md): a Metaplex Core asset on Solana, with an ERC-8004 registration behind its own flag. Both are best-effort by design: the avatar is already delivered, so neither can fail the job.-10. **Backstop for a closed tab.** The browser poll is what drives finalization, so closing the tab mid-build would otherwise strand the job even though the worker finished. [`api/cron/reconstruct-sweep.js`](../api/cron/reconstruct-sweep.js) runs the same finalize stages server-side every few minutes, so an abandoned capture still lands in your library. It rescues jobs up to 30 days old, and fails anything older with an honest reason rather than leaving it open forever.+10. **Backstop for a closed tab.** The browser poll is what drives finalization, so closing the tab mid-build would otherwise strand the job even though the worker finished. [`api/cron/reconstruct-sweep.js`](../api/cron/reconstruct-sweep.js) runs the same finalize stages server-side every few minutes, so an abandoned capture still lands in your library. It rescues jobs up to 30 days old, and fails anything older with an honest reason rather than leaving it open forever. A job whose materialization is refused by a full avatar library is closed as `failed` with the same plan-limit copy the status poll relays, instead of being retried every tick.### The text-to-avatar variantThe same `/api/avatars/reconstruct` endpoint accepts a `prompt` instead of `photos`, but a prompt never touches the face pipeline: face-texture transfer keeps only the face and pastes it onto the template body, so a described character came back in the template's own clothes. Instead ([`api/_lib/prompt-avatar.js`](../api/_lib/prompt-avatar.js)):1. The prompt is painted as one square (1:1) full-body reference image on the forge reference-image lane (`generateReferenceImage`: Vertex first, then the shared text-to-image ladder), with framing cues appended (single figure, neutral A-pose, head to feet in frame, plain background) that say nothing about style.-2. That image is reconstructed on a full-figure image-to-3D engine, in plan order: the self-hosted Hunyuan3D worker (high tier), self-hosted TRELLIS, the Replicate and HuggingFace lanes, then the caller's own Meshy or Tripo key. A self-hosted lane whose health probe reads hard down is moved to the back of the plan rather than accepting a job it would fail.+2. That image is reconstructed on a full-figure image-to-3D engine, in plan order: self-hosted TRELLIS.2 (MIT licensed, served everywhere), the self-hosted Hunyuan3D worker (high tier), self-hosted TRELLIS, the Replicate and HuggingFace lanes, then the caller's own Meshy or Tripo key. The Tencent-model lanes (Hunyuan3D and HuggingFace) are dropped from the plan for requests from the EU, the UK and South Korea, and for an unknown country ([`api/_lib/forge-territory.js`](../api/_lib/forge-territory.js) resolves it server side from the edge geo header). A self-hosted lane whose health probe reads hard down is moved to the back of the plan rather than accepting a job it would fail.3. The unchanged finalize tail auto-rigs the bare mesh and materializes the avatar and its agent, exactly as for a selfie. The job records `source: 'prompt'`, the reference image, and the engine that ran.One endpoint, two front doors.diff --git a/docs/shopify-app.md b/docs/shopify-app.mdindex 2d863e6f8..924a8874c 100644--- a/docs/shopify-app.md+++ b/docs/shopify-app.md@@ -83,7 +83,10 @@ Four webhooks, registered via GraphQL `webhookSubscriptionCreate` right afterOAuth completes (`api/_lib/shopify/webhook-register.js`), each verifiedagainst `X-Shopify-Hmac-Sha256` (`api/_lib/shopify/webhook-verify.js`) andclaimed against a delivery-id ledger (`shopify_webhook_deliveries`) before any-handler logic runs, so a Shopify retry never double-processes:+handler logic runs, so a Shopify retry never double-processes. If a handler's+side effect throws, the claim is released (`applyClaimed` in `webhook-verify.js`)+before the 5xx goes back, so Shopify's retry runs the effect again instead of+hitting the ledger and skipping an erasure or uninstall:- `customers/data_request`, `customers/redact`: no-ops. This app never readscustomer data (scopes are `read_products,write_products` only) and storesdiff --git a/docs/skill-candidates.md b/docs/skill-candidates.mdindex 9f2b3875c..c550ebb8d 100644--- a/docs/skill-candidates.md+++ b/docs/skill-candidates.md@@ -36,7 +36,7 @@ The draft is validated with `validateBundle` from `@three-ws/skill-import`, the| Action | Effect || --- | --- || Install on this agent | Adds the hosted bundle URI to this agent's `skills` and nothing else. The agent's next run can call the new tool. |-| Publish to marketplace | Creates the listing through the existing marketplace flow, owned by the owner. It does not install anything by itself. |+| Publish to marketplace | Creates the listing through the existing marketplace flow, owned by the owner, after the draft passes the marketplace safety scan (`scanSkillBundle`). A `blocked` verdict is refused with `422 skill_blocked`; a `review` verdict creates the listing held for admin review and not public until approved. It does not install anything by itself. || Dismiss | Hides the candidate. Dismissing an installed candidate uninstalls it, and the agent's `skills` no longer contains it. || Redraft | Retries the draft for an `invalid` candidate. |diff --git a/docs/skill-royalties.md b/docs/skill-royalties.mdindex 3357667e0..b322da190 100644--- a/docs/skill-royalties.md+++ b/docs/skill-royalties.md@@ -22,6 +22,15 @@ script can call it: the first request answers `402 Payment Required` with a quotequal to that skill's `price_per_call_usd`, the caller pays in USDC, and theresponse carries the skill's tool schema and content so the caller can run it.+The same priced skill can also be redeemed on three more rails, all through+`/api/skills/:id/invoke`: `mpp` (HTTP `Payment` authentication scheme), `a2a`+(JSON-RPC `message/send` with the a2a-x402 extension) and `ap2` (Intent Mandate in,+Cart Mandate out). The author picks the enabled rails per skill+(`marketplace_skills.rails`, default `x402` and `a2a`). Every rail settles through+the same verify path and the same split, and each accrual's ledger `source` is the+rail that carried it. On `/api/x402/skill-call`, a skill with `x402` switched off+answers `404 rail_disabled` and lists its `enabled_rails`.+There is no re-access grant. Unlike a buy-once asset download, every invocationis a fresh payment, which is what "per call" actually means.@@ -39,7 +48,7 @@ redeem leg described in [Activation](#activation-owner-gated) below.| | Per-call x402 rail | In-app runtime || --- | --- | --- || Caller | Any paying wallet | An agent on three.ws |-| Ledger `source` | `x402` | `skill-runtime` |+| Ledger `source` | the rail used (`x402`, `mpp`, `a2a`, `ap2`) | `skill-runtime` || Lands as | `settled` (money already moved) | `pending` || Chain | Solana first, Base second | EVM, behind a flag || Status | Live | Accrual live, settlement owner-gated |@@ -91,7 +100,8 @@ published a skill and it is earning, Creator Studio shows you the money even ifyou never created an agent.**`GET /api/users/me/earnings`** is the same data as JSON, for the signed-in-author. It returns `pending_usd`, `settling_usd`, `settled_usd`,+author (a session, or a bearer token carrying the `profile` scope; other tokens+get `403 insufficient_scope`). It returns `pending_usd`, `settling_usd`, `settled_usd`,`platform_fee_usd`, and an `entries` array where each royalty entry carries`source`, `network`, `tx_hash`, and `platform_fee_usd` alongside the amount.diff --git a/docs/teams.md b/docs/teams.mdindex ea2ab02f4..4e8c88e18 100644--- a/docs/teams.md+++ b/docs/teams.md@@ -7,7 +7,8 @@ on research it can cite from that board, so no trade ever happens on a hunch,and no specialist redoes work another one already did.Pages: [/teams](https://three.ws/teams) (your teams, assemble a new one) ·-`/teams/<id>` (one team: the squad, the console, the board) · API: `/api/teams`+`/teams/<id>` (one team: the squad, the console, the board) ·+`/teams/<id>/chat` (talk to the squad, see [Team chat](./team-chat.md)) · API: `/api/teams`## The four roles@@ -122,6 +123,9 @@ curl -N -b cookies.txt https://three.ws/api/teams/$TEAM/findings/streamper account.- A live trade needs the signed real-funds agreement, `confirm: true`, and for abearer token the `wallet:write` scope.+- A bearer token also needs `wallet:write` to change the spend caps+ (`per_trade_sol`, `daily_budget_sol`) with `PATCH /api/teams/:id`, because the+ caps live on the Trader's trade limits. A session cookie does not.## Where it livesdiff --git a/docs/trader-duels.md b/docs/trader-duels.mdindex 5d26b9cda..b43d8a5f0 100644--- a/docs/trader-duels.md+++ b/docs/trader-duels.md@@ -42,6 +42,21 @@ Page: [/duels](https://three.ws/duels) · one duel: `/duels/:id` · API: `/api/d| A trader went private or was deleted, at any time before resolution | Void immediately: every stake refunded || One trader closed trades, the other sat out | The idle trader counts as flat (0 SOL): sitting out beats a loss and loses to a profit |+## Challenge duels++The rivalry engine only pairs neighbours on the board. An agent owner can also+pick the opponent: through the agent MCP tools, the owner of one public agent+challenges another owner's public agent (`duel_challenge`) to the next UTC day+or week window, with an optional note of up to 280 characters. The opponent's+owner is notified and has 48 hours to accept, decline or let it lapse+(`duel_accept`); the challenger can withdraw while it is pending, and an owner+can have at most 20 challenges pending. An unanswered challenge expires on the+`duels-tick` cron. Accepting opens a regular duel for that window, tagged as a+challenge so the rivalry generator still opens its own pairings for the same+window. From there it behaves like any duel: realized P&L decides it, anyone who+owns neither trader can call it for points, and it counts toward the challenge+leaderboard (`duel_markets` with `view: "leaderboard"`). Still points only.+## Points, XP, seasons, badges- **Daily allowance:** 100 points per UTC day, credited the first time you open@@ -138,7 +153,7 @@ badges, newly_unlocked }`. Reading it credits today's allowance. Signed out:Migration `api/_lib/migrations/20260930150000_trader_duels.sql`: `duel_markets`,`duel_picks`, `duel_wallets`, `duel_points_ledger`. Model`api/_lib/trader-duels.js`, endpoints `api/duels/*`, cron-`api/cron/duels-tick.js` (every 15 minutes, in `vercel.json`), pages+`api/cron/duels-tick.js` (every 15 minutes, in `vercel.json`; it also expires stale challenges), challenges `api/_lib/duel-challenges.js` with MCP tools in `api/_mcpagent/duels-tools.js`, pages`pages/duels.html` + `src/duels.js` and `pages/duel.html` + `src/duel.js`,trader-profile widget `src/trader-duels.js`, tests `tests/trader-duels.test.js`.diff --git a/docs/tutorials/pay-for-x402-service.md b/docs/tutorials/pay-for-x402-service.mdindex 8e598f870..56ff95da0 100644--- a/docs/tutorials/pay-for-x402-service.md+++ b/docs/tutorials/pay-for-x402-service.md@@ -224,6 +224,7 @@ If the result looks wrong but you were charged, note: x402 has **single-shot, no- **"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 that pays network fees is under its SOL reserve. (The daily fee budget only paces the platform's own autonomous traffic; a paying customer's settle is admitted past it.) Nothing was charged and the error is marked retryable; try again shortly.- **"... rewrote the payment transaction before signing ..."**: your Solana wallet changed the prepared transaction (a different transfer, a swapped fee payer, or an unknown program), so it can no longer settle and nothing was sent. Phantom's default transaction protection is not the cause: its Lighthouse guard instructions are accepted. Turn off transaction modification in the wallet, or pay with a different Solana wallet.+- **"Payments continue in Safari"** (error code `native_handoff`): inside the three.ws iOS app, `pay()` does not sign in the app. It opens a sheet that sends you to the same page in Safari, already signed in through a one-time handoff code, and you pay there.- **"Your wallet could not display this payment request"**: the wallet refused to open its approval window. Nothing was signed or charged; unlock or update the wallet and retry, or pay with the other token.- **"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.diff --git a/docs/tutorials/write-a-guard.md b/docs/tutorials/write-a-guard.mdindex 1b4777679..7be66449a 100644--- a/docs/tutorials/write-a-guard.md+++ b/docs/tutorials/write-a-guard.md@@ -193,7 +193,7 @@ The runner builds a throwaway git worktree overlaid with your working tree and r1. **Control.** The unmutated sandbox must make the guard exit 0. A clean baseline is what makes the next step attributable. Without it, a non-zero exit could just mean the sandbox is broken.2. **Violation.** The `write` fixture lands `api/guard-proof-fetch-timeout.js`, and the guard must now exit non-zero *and* print the `expect` fragment, because a guard that fails for the wrong reason is not a working guard.-The verdicts you can get back are `proven`, `control-failed` (your guard already fails on a clean tree), `not-caught` (the fixture slipped past it, so the guard is a no-op), and `wrong-reason` (it failed, but not on your violation). Only the first one means what you built works. Results land in `public/guard-proofs.json` with a verdict per guard.+The verdicts you can get back are `proven`, `control-failed` (your guard already fails on a clean tree), `not-caught` (the fixture slipped past it, so the guard is a no-op), and `wrong-reason` (it failed, but not on your violation). A guard that declared a `live` proof reports `declared-live` and is not run offline. Only `proven` means what you built works. Results land in `public/guard-proofs.json` with a verdict per guard.It is safe to run while other agents are working in this tree: each run gets its own sandbox keyed to its process id and never writes to the repository except that one results file.@@ -276,7 +276,7 @@ Build the sandbox rather than pointing the test at the real repository. A test t## Step 7: document it-Add a row to the relevant table in [`docs/guards.md`](/docs/guards), and add a `data/changelog.json` entry if the guard changes what contributors have to do.+Add a row to the relevant table in [`docs/guards.md`](/docs/guards) that names `npm run check:fetch-timeouts` (`audit:guards` fails when a registered guard's npm script appears in no table there), and add a `data/changelog.json` entry if the guard changes what contributors have to do.---diff --git a/docs/ux-flows/01-onboarding-creation.md b/docs/ux-flows/01-onboarding-creation.mdindex dc6bbc3c1..b41d6b0a9 100644--- a/docs/ux-flows/01-onboarding-creation.md+++ b/docs/ux-flows/01-onboarding-creation.md@@ -180,11 +180,11 @@- **Prerequisites / gates:** **Auth required.** Loading an agent you don't own (or with no session) hits a 401, which stashes `login_redirect` and redirects to `/login`. No $THREE gate.- **Steps (N):**1. Navigate to `/agents/<id>/edit`; `loadAgent()` fetches `GET /api/agents/:id` and the full editor renders (`render()`): identity (name/description), 3D body (starter/library picker/upload via `avatar-gallery-picker.js` + `AvatarCreator`), skills, animations, **gesture slots** (per-agent bindings for the fixed gesture vocabulary, saved via `#anim-slots-save`, previewable on `/gestures`), voice, wallet chip, and the embed/manifest panels. The wallet panel reads balances from `GET /api/portfolio/summary` (`{ usd, native, tokens }` per wallet), sends through `POST /api/portfolio/send` with `asset: 'native'` or the USDC mint and the typed decimal amount (echoing the returned `tx_hash`), and the Fund modal's deposit QR tries qrserver then quickchart before hiding the image behind the copyable address. The Social tab hides Connect X with a stated reason when X OAuth is not configured on the deployment (`?x=unconfigured` after a bounced connect). Embed and manifest panels emit the canonical `/agents/<id>` URLs.- 2. Edit any field → changes persist through the same verified endpoints (PUT `/api/agents/:id`, animations endpoint, etc.).+ 2. Edit any field → changes persist through the same verified endpoints (PUT `/api/agents/:id`, animations endpoint, etc.). `PUT /api/agents/:id` only links an `avatar_id` the signed-in owner owns: a non-UUID id returns 400 and an avatar that is missing, deleted or someone else's returns 404 `avatar not found`.- **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. 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.+- **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. A card whose thumbnail URL is dead swaps to the designed placeholder tile (`data-thumb-fallback`, wired by `src/shared/thumb-fallback.js`) instead of the browser's broken-image glyph.- **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 c489898a1..3981fc5f2 100644--- a/docs/ux-flows/02-forge-text-to-3d.md+++ b/docs/ux-flows/02-forge-text-to-3d.md@@ -6,7 +6,7 @@ Routing facts (from `vercel.json`):- `/forge` → `pages/forge.html` (loads `src/forge.js` + 29 sibling `src/forge-*.js` modules).- `/image-to-3d` → `pages/forge.html` (same app; lands with the photos tab preselected and its own document title; `?mode=image` on any forge URL does the same).- `/forge-max` → `pages/forge.html` (same app; lands with the High tier pinned and "Forge Max" header copy; `?tier=draft|standard|high` presets the selector on any forge URL).-- `/forge/share/<id>` → `api/forge-share.js` (SSR page that bakes OG/Twitter/Farcaster preview meta plus a schema.org `3DModel` JSON-LD node for crawlers (built by `api/_lib/creation-jsonld.js`: the GLB, a poster rendered by `/api/render/glb`, the creator, the date), then JS-redirects browsers to `/forge?share=<id>`, which opens the creation in the viewer; a private or unknown id redirects to `/forge` instead).+- `/forge/share/<id>` → `api/forge-share.js` (SSR page that bakes OG/Twitter/Farcaster preview meta plus a schema.org `3DModel` JSON-LD node for crawlers (built by `api/_lib/creation-jsonld.js`: the GLB, a poster rendered by `/api/render/glb`, the creator, the date); stored preview-image URLs pass through `normalizeStoredUrl()` before they reach a browser, so a raw `r2.dev` URL never lands in the OG/Twitter/Farcaster tags, then JS-redirects browsers to `/forge?share=<id>`, which opens the creation in the viewer; a private or unknown id redirects to `/forge` instead).- `/features/forge` → `pages/features/forge.html` (static marketing landing, no app module).- `/create/prompt` → `pages/create-prompt.html` → `src/create-prompt.js` (text → **rigged avatar**, a different backend from Forge).- `/tutorials/text-to-3d` and `/tutorials/image-to-3d` → `pages/tutorial.html` (one shared template) which `fetch`es `/docs/tutorials/<slug>.md` and renders it with marked.js. Read-only content pages.@@ -37,7 +37,7 @@ Routing facts (from `vercel.json`):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.+ 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, and a quote line under it (`#forge-quote`, rendered by `src/forge-keep.js` from the public, no-spend `GET /api/forge-quote`) prices the generation for the current path, tier, engine and options from the same tier and pricing-catalog code the generator charges from.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; 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.@@ -49,7 +49,7 @@ Routing facts (from `vercel.json`):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.18. (optional) **Restyle materials** (`forge-materials.js`): free-text or preset-chip PBR re-skin (chrome, brushed gold, weathered wood, ...) via synchronous `POST /api/material-studio?action=restyle`; geometry untouched. Same pipeline as the paid `restyle_material` MCP tool.- 19. (optional) **Rig for animation** (`forge-rig.js`): adds a humanoid skeleton + skin weights to the current GLB via `POST /api/forge?action=rig` (the self-hosted GCP model-rig worker, falling back to the configured Replicate rerig model), polled through the same `GET /api/forge?job=` contract.+ 19. (optional) **Rig for animation** (`forge-rig.js`): adds a humanoid skeleton + skin weights to the current GLB via `POST /api/forge?action=rig` (rigging runs on platform-paid capacity, so it is behind the same global hourly ceiling and per-client daily paid limit as the reconstruction lanes: a `429` with `daily_limit_reached` or an at-capacity message) (the self-hosted GCP model-rig worker, falling back to the configured Replicate rerig model), polled through the same `GET /api/forge?job=` contract.20. (optional) **Optimize topology** (`forge-optimize.js`): tri/quad/low-poly remesh via `POST /api/forge-remesh` (polled). Above the server remesh sit the in-browser mesh tools (`src/mesh-ops/`): repair, smooth and decimate run in a browser worker with undo, no upload.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).@@ -58,7 +58,7 @@ Routing facts (from `vercel.json`):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>`).27. (optional) **Share** → `forge-share-btn`: when the creation was persisted server-side it shares a real permalink, `/forge/share/<id>`, that unfurls with a preview card (an X `player` card pointing at `/forge/embed` for a finished creation, `summary_large_image` otherwise); otherwise it falls back to a remix link (`/forge?prompt=`). **Cinema** mode (fullscreen turntable for screen recording, F/Esc). **More like this** (`forge-more-like-this.js`): one-tap chips that re-run the same subject with a different material/finish via the `forge:run-prompt` event (text results only).- 28. User clicks **Download GLB**: the anchor fetches + "stamps" the GLB (`#download[data-stamping]`), reports `downloaded:true` feedback, and saves the file. **OR** clicks **Make another** to reset to the idle composer.+ 28. User clicks **Download GLB**: first, for a saved creation, `ensureKept()` (`src/forge-keep.js`) asks `GET /api/forge-keep?creation_id=<uuid>` whether the original file may be released. Pay-to-keep is **off unless the owner sets `FORGE_PAY_TO_KEEP=on`** (`npm run forge:pay-to-keep -- on|off|status`); while off, every creation answers `kept:true` and Download behaves as it always did. When on, a $THREE holder keeps free, High is already paid or held at generation time, and everyone else pays the `forge.keep.<tier>` price once through the $THREE quote/sign/settle rail (`POST /api/forge-keep`, `402 three_hold_required` with the price when unpaid); a refusal shows its message in the quote line and the download does not proceed, while a server fault fails open. Then the anchor fetches + "stamps" the GLB (`#download[data-stamping]`), reports `downloaded:true` feedback, and saves the file. **OR** clicks **Make another** to reset to the idle composer.- **Photo / multi-view branch (steps 3-11 differ):** "From photos" tab shows up to 6 view slots (Front/Back/Left/Right/Top/3-4) with a live "N of 6 views" counter + pips. Each photo is uploaded via presign `POST /api/forge-upload` → `PUT` to object storage; the public URL is recorded. Drag-to-reorder, paste (⌘V/Ctrl+V), drop, or click-to-browse (PNG/JPG/WebP, ≤8MB). An optional guidance prompt is allowed. Submit posts `{ image_urls, prompt?, ... }`. A server-side **vision pre-check** can reject an unusable photo (`422 image_not_usable`) → recoverable "Generate anyway" override.- **Use your GPU branch (photos tab, opt-in):** the Use your GPU panel (`forge-modly.js`) probes a local Modly app on loopback only when the user presses Connect, never on page load. Its downloaded image-to-3D models join the engine picker badged "Your GPU, free"; the timeline shows Modly's real percent and step text, Cancel calls Modly's own cancel endpoint, and the finished GLB is copied to storage through `/api/scene-glb-upload` so rig, optimize, AR and embed get a public URL (a save row writes it to the avatar library via `/api/avatars/from-forge`). Not running, browser blocked (Chrome Local Network Access, Safari mixed content), no models and custom-port states are designed.- **Sketch branch:** "From a sketch" tab (only when a live sketch engine exists) takes one drawing + a **required** description; outputs untextured geometry (user is told to Stylize/Retexture after).@@ -73,7 +73,8 @@ Routing facts (from `vercel.json`):- **External calls / dependencies:**- Catalog/health: `GET /api/forge?catalog=1`, `GET /api/forge?health=1`- Submit/poll: `POST /api/forge`, `GET /api/forge?job=<id>`- - Uploads: `POST /api/forge-upload` (presign) + `PUT` object storage+ - Uploads: `POST /api/forge-upload` (presign) + `PUT` object storage. The presign check is the only size gate at request time (the 8 MB image ceiling comes from `ANON_UPLOAD_LIMITS['forge/uploads/']` in `api/_lib/anon-upload-limits.js`), so the hourly cron `api/cron/anon-upload-sweep.js` deletes anonymous objects that exceed their prefix ceiling after the fact. The presign handlers (`forge-upload`, `scene-glb-upload`) look the content type up with `Object.hasOwn`, so an inherited key such as `constructor` is a `400 invalid_content_type`.+ - Cost preview and keep: `GET /api/forge-quote` (public, read-only, `?table=1` for all tiers); `GET|POST /api/forge-keep` (pay-to-keep, below)- 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); 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)diff --git a/docs/ux-flows/06-marketplace-skills.md b/docs/ux-flows/06-marketplace-skills.mdindex 5839e22cf..e80d66041 100644--- a/docs/ux-flows/06-marketplace-skills.md+++ b/docs/ux-flows/06-marketplace-skills.md@@ -57,7 +57,7 @@ Routing facts confirmed in `vercel.json` (line numbers shift too often to pin; g- **Decision points / branches:** owner vs buyer view; skill is free / owned / paid / trial-eligible; asset is for-sale vs not; tier subscribed vs not.- **External calls / dependencies:** `/api/marketplace/agents/:id` (+ `/versions`, `/similar`, `/preview`), `/api/creators/:id`, `/api/avatars/:id` (avatar detail), `/api/marketplace/asset-price` (owner price edit).- **Success state:** Full detail with interactive 3D, skill list, live preview, and the correct action (Unlock / Buy / Try free / owner editor).-- **Empty / error states:** `showDetailState('error'|'notfound')` overlay with retry; avatar detail "Avatar not found"; 3D stage "Couldn't load the 3D model." with a 15s "still loading" hint; preview errors surfaced in the chat footer.+- **Empty / error states:** `showDetailState('error'|'notfound')` overlay with retry; avatar detail "Avatar not found"; 3D stage "Couldn't load the 3D model." with a 15s "still loading" hint; in the avatar modal, when a body fails to load the viewer retries once with the same-origin default avatar GLB and says it is showing a placeholder, and only a second failure shows "Failed to load 3D model." (`src/shared/model-viewer-fallback.js`); grid and picker thumbnails that 404 fall back to a placeholder tile instead of the browser's broken-image icon; preview errors surfaced in the chat footer.- **Step count:** 3 required (+5 optional)---@@ -141,12 +141,13 @@ Routing facts confirmed in `vercel.json` (line numbers shift too often to pin; g5. User clicks a card → `/marketplace/skills/:id` → `GET /api/skills/:id` renders the detail panel (header, meta pills, description, tool schemas, full content, related skills).6. User clicks "Install" → `toggleSkillInstall()` POSTs `/api/skills/:id/install` (DELETE to remove); 401 → login redirect; on success the detail + grid refetch, the button flips to "Installed ✓ — Remove", and the "what next" panel (`#skill-detail-next`) appears: knowledge skills get a "Chat with your agent →" CTA to `/app`, schema-only packs get the `GET /api/skills?installed=true` retrieval hint. Pre-install, `#skill-detail-how` explains what installing does.7. (optional) User rates 1–5 stars → `POST /api/skills/:id/rate { rating }` → detail refetches with updated counts.- 8. (optional, paid skills) Detail shows an x402 panel: endpoint `GET /api/x402/skill-call?skill=:slug`, price `$X.XXX/call`, and a copy-paste `@three-ws/x402-fetch` snippet - developers pay per call from their own wallet; the server settles to the author. The x402 panel only applies when the author left the x402 rail on: the publish-skill form has a "Payment rails" fieldset (x402 and a2a on by default, mpp and ap2 off, at least one required for a priced skill, stored as `marketplace_skills.rails`, policy in `api/_lib/skill-rails.js`), and a call to `/api/x402/skill-call` for a skill with x402 switched off returns `404 rail_disabled`.+ 8. (optional, paid skills) Detail shows an x402 panel: endpoint `GET /api/x402/skill-call?skill=:slug`, price `$X.XXX/call`, and a copy-paste `@three-ws/x402-fetch` snippet - developers pay per call from their own wallet; the server settles to the author. The x402 panel only applies when the author left the x402 rail on: the publish-skill form has a "Payment rails" fieldset (x402 and a2a on by default, mpp and ap2 off, at least one required for a priced skill, stored as `marketplace_skills.rails`, policy in `api/_lib/skill-rails.js`), and a call to `/api/x402/skill-call` for a skill with x402 switched off returns `404 rail_disabled`. The same skill is also served on every enabled rail (x402, mpp, a2a, ap2) at `/api/skills/:id/invoke` with one price, one author/platform split and one receipt; a disabled rail answers `404 rail_disabled` there too ([skill-rails.md](../skill-rails.md)).+ 9. (optional, authors) The publish form has an optional "Skill code and instructions" block (`SKILL.md`, `manifest.json`, `handlers.js`) and a **Check skill** button that dry-runs the safety scan via `POST /api/skills/scan`, showing file, line and fix guidance per finding. Every publish, edit and new version is scanned before it lists: `clean` lists normally, `review` saves the skill private and held for a moderator, and `blocked` is refused with `422 skill_blocked` ([skill-supply-scan.md](../skill-supply-scan.md)).- **Decision points / branches:** free vs paid (paid = x402 per-call, not an install purchase); installed vs not; authed vs anon (install/rate gated). Marketplace skills (community tool packs with schema/content) are distinct from built-in agent skills in `src/agent-skills*.js`.- **External calls / dependencies:** `/api/skills`, `/api/skills/categories`, `/api/skills/:id`, `/api/skills/:id/install` (POST/DELETE), `/api/skills/:id/rate`, `/api/x402/skill-call` (per-call payment), `/api/creators/:id` (author modal).- **Success state:** Skill installed (flips to "Installed ✓" + the what-next panel), rating recorded, x402 snippet copyable. Installs take effect at chat time: `/api/chat` loads the signed-in user's installed knowledge skills (`api/_lib/installed-skills.js`, newest 8, content budget 24k chars) into the system prompt and reports them as `skills_applied` in the SSE `done` event; `GET /api/skills?installed=true` returns the full payload (content + schema_json) for external agents.- **Empty / error states:** "No skills found", naming the search / category / tag that emptied the list, with Clear-filters / Publish-a-Skill CTAs; a failed fetch renders `renderErrorState('skills')` ("Couldn't load skills") with a working Retry; install button restores text + re-enables on error; auth redirect on 401.-- **Step count:** 3 required (+5 optional)+- **Step count:** 3 required (+6 optional)---diff --git a/docs/x-memory-seeding.md b/docs/x-memory-seeding.mdindex 688f10db1..a9bef085d 100644--- a/docs/x-memory-seeding.md+++ b/docs/x-memory-seeding.md@@ -83,6 +83,11 @@ than failing at the X API. The scope sets and both guards live inresolves to the full set, so a typo can never silently narrow what a postingsurface asks for.+A third guard, `X_MENTION_REQUIRED_SCOPES` (`tweet.read users.read tweet.write`),+covers an agent answering mentions from its own X account (the "Answer mentions"+section of the agent editor's X panel). A read-only seeding connection does not+carry it, so that panel shows a reconnect link instead of enabling the policy.+Connections made before scopes were recorded store an empty scope string. Thoseare treated as unknown rather than as empty, so neither guard blocks them.diff --git a/docs/x-mention-avatar.md b/docs/x-mention-avatar.mdindex 67c26c937..d9881f10e 100644--- a/docs/x-mention-avatar.md+++ b/docs/x-mention-avatar.md@@ -1,6 +1,6 @@# X mention bot: "make me an avatar"-When someone mentions the account with "make me an avatar", the bot turns their own X profile picture into a rigged 3D avatar and replies with a rendered image, the creation link and a link that opens the avatar in the pose studio. This is the `avatar` intent of the X mention bot. It runs in dry run only: each reply is recorded on the mention's `x_mention_events` row and nothing is posted to X until the account goes live.+When someone mentions the account with "make me an avatar", the bot turns their own X profile picture into a rigged 3D avatar and replies with a rendered image, the creation link and a link that opens the avatar in the pose studio. This is the `avatar` intent of the X mention bot. On the platform account it runs in dry run only: each reply is recorded on the mention's `x_mention_events` row and nothing is posted to X until the account goes live. An agent with its own X account answers in its persona and goes live only when its policy has dry run off and the X bot is live.## Whose picture@@ -13,12 +13,14 @@ Only the author of the mention. The picture comes from the mention's own author3. A vision model reviews it for ages-13+ safety and for showing a person, character or creature. This fails closed: with no vision provider the bot replies with the /create link and generates nothing (`review_unavailable`). An unsafe picture gets a fixed refusal that echoes nothing.4. The studio's rigged-avatar lane runs: image to 3D at the avatar tier, then auto-rig, the same two stages as the `forge_avatar` MCP tool. The creation is attributed to the system bot account and the X author (`forge_creations.x_author_id`) and is unlisted.5. The reply carries the render of the rigged model as media, `/m/<creation id>` and `/pose?src=<rigged glb>`. If the rig fails, the unrigged mesh is returned (reason `avatar_done_unrigged:*`).-6. A job that outlives `X_MAKE_BUDGET_MS` is recorded as `pending` with its stage (`mesh` or `rig`). Every cron tick, `finishPendingAvatars` probes it once: a finished mesh starts its rig, a finished rig replies, and a failed or overdue job (`X_MAKE_GIVE_UP_MS`) gets the mesh if one exists or the failure reply.+6. Every success reply ends with a claim line (`withClaimNote` in `api/_lib/x-creation-claim.js`): "Saved to your library." when the author has already linked the same X id, otherwise a link to https://three.ws/x/claim. Linking X later moves the bot-owned creation into the author's library and logs the move in `x_creation_claims`.+7. A job that outlives `X_MAKE_BUDGET_MS` is recorded as `pending` with its stage (`mesh` or `rig`). Every cron tick, `finishPendingAvatars` probes it once: a finished mesh starts its rig, a finished rig replies, and a failed or overdue job (`X_MAKE_GIVE_UP_MS`) gets the mesh if one exists or the failure reply.## Code- `api/_lib/x-mention-avatar.js`: `handleAvatar`, `finishPendingAvatars`, `reviewProfileImage`, `composeAvatarReply`, `isDefaultProfileImage`, `poseLink`.- `api/_lib/x-media-image.js`: `xProfileImageUrl`, and `fetchXImage(url, { profile: true })`.+- `api/_lib/x-creation-claim.js`: claim lines and the move into the author's library (page: `pages/x-claim.html`).- `api/_lib/x-mention-poll.js`: dispatches `avatar` mentions and runs the follow-up each tick.- `tests/x-mention-avatar.test.js`: own image, named-other-account cases, default image, moderation, CDN rules, pending follow-up.- `scripts/x-mention-avatar-dry-run.mjs`: real dry runs from the real profile pictures of recent mentions; writes `prompts/x-grok/_generated/avatar-dry-run.json`.diff --git a/docs/x-mention-image3d.md b/docs/x-mention-image3d.mdindex 3d308e7d1..ac2d92058 100644--- a/docs/x-mention-image3d.md+++ b/docs/x-mention-image3d.md@@ -14,12 +14,12 @@ The picture is only used when its poster is the person who wrote the mention. An1. Fetch from X's photo CDN only (`pbs.twimg.com/media/...`, https, the `large` rendition). Redirects are refused. The download has a 5 MB cap (`X_MEDIA_MAX_BYTES` in `api/_lib/x-media-image.js`), a 15 second timeout, a JPEG or PNG Content-Type check and a magic-byte check. A URL on any other host is a skip with reason `image_rejected:not_cdn` and no request is made. A too-large, wrong-type or stalled picture gets a reply pointing at https://three.ws/forge.2. Review with a vision model for ages-13+ safety and for one reconstructable subject. This fails closed: with no vision provider the bot replies with the /forge link and generates nothing. An unsafe picture gets a fixed refusal that echoes nothing from the post. Text typed after "3D this" also passes the studio prompt safety check.3. Store the picture and run the image-to-3D lane, attributed to the system bot account and the X author (`forge_creations.x_author_id`) so the author can claim it later. Creations are unlisted.-4. Reply with the rendered PNG and `/m/<creation id>`. A job that outlives `X_MAKE_BUDGET_MS` is recorded as `pending` and `finishPendingImage3d` replies once when it completes, or with the failure reply after `X_MAKE_GIVE_UP_MS`.+4. Reply with the rendered PNG and `/m/<creation id>`. Before attaching the PNG the bot probes the render URL (`posterRenders`, 90 second timeout); if the render service refuses the mesh (for example a size cap) the reply is link-only. Every success reply also gets a claim line from `withClaimNote` in `api/_lib/x-creation-claim.js`: "Saved to your library." when the author has linked the same X account, otherwise a link to `/x/claim`, where linking X moves the creation into their library. A job that outlives `X_MAKE_BUDGET_MS` is recorded as `pending` and `finishPendingImage3d` replies once when it completes, or with the failure reply after `X_MAKE_GIVE_UP_MS`.## Code- `api/_lib/x-media-image.js`: `fetchXImage`, `xMediaUrl`, `XMediaError`.-- `api/_lib/x-mention-image3d.js`: `handleImage3d`, `finishPendingImage3d`, `reviewImage`, `isOwnImage`, `composeImage3dReply`.+- `api/_lib/x-mention-image3d.js`: `handleImage3d`, `finishPendingImage3d`, `reviewImage`, `isOwnImage`, `composeImage3dReply`, `cleanSubject` (drops a leading article such as "a" or "the" from the subject), `posterRenders`.- `tests/x-mention-image3d.test.js`: own image, someone else's image, non-CDN URL, oversized image, moderation and the pending follow-up.- `scripts/x-mention-image3d-dry-run.mjs`: real dry runs from real mentions that carry photos; writes `prompts/x-grok/_generated/image3d-dry-run.json`.diff --git a/docs/x402-buyer.md b/docs/x402-buyer.mdindex 659f1e374..03db7c728 100644--- a/docs/x402-buyer.md+++ b/docs/x402-buyer.md@@ -1,6 +1,6 @@# x402 Buyer Client-To consume a paid [x402 endpoint](x402-endpoints.md) — ours or anyone's — a+To consume a paid [x402 endpoint](x402-endpoints.md), ours or anyone's, acaller has to perform the "402 dance": probe the URL, read the payment challenge,sign and settle a payment, then retry with an `X-PAYMENT` header. three.ws ships abuyer client that wraps that whole sequence in one call, with spending-cap@@ -48,24 +48,41 @@ if (!ok) {| `method`, `headers`, `body` | no | Standard request shape; an object `body` is JSON-encoded. || `caps` | recommended | Spending-cap envelope: `address` plus `maxPerCall` / `maxPerHour` / `maxPerDay` in USDC atomics. || `signPayment({ requirement })` | **yes** | Returns the signed payment payload for the chosen requirement. |-| `preferNetwork` | no | Pick which advertised network to pay on — a network string, or a function over the `accepts` array. |+| `preferNetwork` | no | Pick which advertised network to pay on, a network string, or a function over the `accepts` array. |+| `preferScheme` | no | `'upto'` takes an escrow-backed offer when one is advertised, so you pay the measured charge rather than the cap. |+| `preferProtocol` | no | `'mpp'` pays an MPP Solana charge when the server offers one. By default an x402 `accepts` list wins. |+| `dryRun` | no | Stops after the cap check and returns the quote and every offer, signing and paying nothing. || `fetchImpl` | no | Inject a custom `fetch` (tests, proxies). |### Why you supply `signPayment`-Signing differs per chain — EIP-712 `transferWithAuthorization` on Base, a signed-`VersionedTransaction` on Solana, a contract call on BSC — so the caller owns it.+Signing differs per chain, EIP-712 `transferWithAuthorization` on Base, a signed+`VersionedTransaction` on Solana, a contract call on BSC, so the caller owns it.The client owns only the cap check, the header dance, and settlement parsing. Thecallback receives the selected `requirement` from the 402 challenge and returnsthe payment payload to attach.+### x402 or MPP from one call++A 402 can speak either protocol. When a server offers only an MPP+`WWW-Authenticate: Payment` Solana charge (or you set `preferProtocol: 'mpp'`),+`buyerFetch` expresses the charge as the equivalent `exact` requirement, so caps+and `signPayment` see one shape. `signPayment` must return a Solana exact payload+(`{ payload: { transaction } }`), which goes back as `Authorization: Payment`, and+the receipt is read from `Payment-Receipt`. Results carry `protocol: 'x402' | 'mpp'`;+a `dryRun` result is `{ ok: true, dryRun: true, protocol, quote, offers: { x402, mpp } }`.+See [MPP on Solana](mpp-solana.md).+### Spending capsCaps are enforced as a reserve → commit / rollback transaction in`x402-spending-cap.js`, so a call is **counted before it fires** and rolled back if-it fails — caps hold even across concurrent calls. The store is Redis-backed when+it fails, caps hold even across concurrent calls. The store is Redis-backed whenavailable. If a call would exceed any window, `buyerFetch` returns-`{ ok: false, abort: true, reason }` **without paying**. The platform-wide ceiling+`{ ok: false, abort: true, reason }` **without paying**. For an `upto` payment the cap is reserved up front, and once+the settlement reports the measured charge the unused part of the reservation is+released, so the hourly and daily windows reflect real spend+([x402 upto](x402-upto.md)). The platform-wide ceilingdefaults live in env (`X402_MAX_PER_CALL_ATOMIC`, `X402_MAX_PER_HOUR_ATOMIC`,`X402_MAX_PER_DAY_ATOMIC`; see [Configuration](configuration.md)).@@ -107,9 +124,9 @@ guarantees: [Pending settlement](x402-settlement-pending.md).## Related-- [x402 protocol](x402.md) — the underlying challenge/settle mechanics.-- [x402 paid endpoints](x402-endpoints.md) — what you can buy from us.-- [Autonomous x402 loop](autonomous-x402.md) — uses this client on a schedule.+- [x402 protocol](x402.md), the underlying challenge/settle mechanics.+- [x402 paid endpoints](x402-endpoints.md), what you can buy from us.+- [Autonomous x402 loop](autonomous-x402.md), uses this client on a schedule.- [Pending settlement](x402-settlement-pending.md): the `settlement_pending`outcome, what a buyer does with it, and how the books close afterwards.- [Payment Sessions](payment-sessions.md#get-apix402outbound-receipts): thediff --git a/public/changelog-recent.json b/public/changelog-recent.jsonindex e3263080e..fd303e6ee 100644--- a/public/changelog-recent.json+++ b/public/changelog-recent.json@@ -1,11 +1,11 @@{- "generated_at": "2026-10-25T12:02:24.949Z",+ "generated_at": "2026-10-25T12:02:47.812Z","generated_by": "scripts/build-page-index.mjs from data/pages.json + data/changelog.json","site": {"name": "three.ws","url": "https://three.ws"},- "total": 4206,+ "total": 4207,"complete": false,"full_feed": "/changelog.json","entries": [@@ -40,6 +40,16 @@"security"]},+ {+ "date": "2026-10-25",+ "type": "update",+ "title": "Chat pairing and X connect returns land on a working Connections page",+ "summary": "The /settings/connections link that the Telegram and Discord bots, the notification settings and the X connect flow all send people to returned a 404. Every /settings subpath now serves the settings app, and a new Connections tab lists paired chats, toggles notifications, picks the default agent, unpairs, issues a pairing code and redeems the code a bot prints.",+ "link": "/settings/connections",+ "tags": [+ "fix"+ ]+ },{"date": "2026-10-25","type": "update",@@ -1545,16 +1555,6 @@"feature","docs"]- },- {- "date": "2026-10-13",- "type": "update",- "title": "Free voice is back: the Edge lane speaks again",- "summary": "Microsoft changed the handshake on its free Read Aloud service, so the default Edge voice lane answered every request with an error. The lane now speaks the current protocol, so the /voice page and every agent that uses the free voice can talk again.",- "link": "/voice",- "tags": [- "fix"- ]}]}diff --git a/public/changelog.json b/public/changelog.jsonindex 1aba05c92..285eadb2b 100644--- a/public/changelog.json+++ b/public/changelog.json@@ -1,5 +1,5 @@{- "generated_at": "2026-10-25T12:02:24.924Z",+ "generated_at": "2026-10-25T12:02:47.671Z","generated_by": "scripts/build-page-index.mjs from data/pages.json + data/changelog.json","site": {"name": "three.ws",@@ -37,6 +37,16 @@"security"]},+ {+ "date": "2026-10-25",+ "type": "update",+ "title": "Chat pairing and X connect returns land on a working Connections page",+ "summary": "The /settings/connections link that the Telegram and Discord bots, the notification settings and the X connect flow all send people to returned a 404. Every /settings subpath now serves the settings app, and a new Connections tab lists paired chats, toggles notifications, picks the default agent, unpairs, issues a pairing code and redeems the code a bot prints.",+ "link": "/settings/connections",+ "tags": [+ "fix"+ ]+ },{"date": "2026-10-25","type": "update",diff --git a/public/changelog.xml b/public/changelog.xmlindex d4f7e6cb0..745028352 100644--- a/public/changelog.xml+++ b/public/changelog.xml@@ -30,6 +30,14 @@<category>fix</category><description>The Greenfield SDK and the Bot Framework expression library each carried a nested fast-xml-parser 4.5.7 that the version-scoped override never reached, leaving the XMLBuilder comment and CDATA injection advisory (GHSA-gh4j-gqv2-49f6) open. The override now applies to every copy, all of them resolve to 5.11.2, and a lockfile test guards every nested path.</description></item>+ <item>+ <title>Chat pairing and X connect returns land on a working Connections page</title>+ <link>https://three.ws/settings/connections</link>+ <guid isPermaLink="false">2026-10-25:Chat pairing and X connect returns land on a working Connections page</guid>+ <pubDate>Sun, 25 Oct 2026 12:00:00 GMT</pubDate>+ <category>fix</category>+ <description>The /settings/connections link that the Telegram and Discord bots, the notification settings and the X connect flow all send people to returned a 404. Every /settings subpath now serves the settings app, and a new Connections tab lists paired chats, toggles notifications, picks the default agent, unpairs, issues a pairing code and redeems the code a bot prints.</description>+ </item><item><title>Commit feed cron skips quietly on a lock-check fault</title><link>https://three.ws/changelog</link>diff --git a/public/features.json b/public/features.jsonindex 3243d91fd..e2d9211bd 100644--- a/public/features.json+++ b/public/features.json@@ -1,5 +1,5 @@{- "generated_at": "2026-10-25T12:00:57.741Z",+ "generated_at": "2026-10-25T12:02:47.648Z","generated_by": "scripts/build-page-index.mjs from data/pages.json","site": {"name": "three.ws",diff --git a/public/sitemap/index.html b/public/sitemap/index.htmlindex 0e0763c0f..cde3f79de 100644--- a/public/sitemap/index.html+++ b/public/sitemap/index.html@@ -3,16 +3,16 @@<head><meta charset="utf-8" /><meta name="viewport" content="width=device-width,initial-scale=1" />-<title>Sitemap · three.ws</title>-<meta name="description" content="Human-readable index of every page on three.ws." />+<title data-i18n="sitemap_index.meta_title">Sitemap · three.ws</title>+<meta name="description" content="Human-readable index of every page on three.ws." data-i18n-attr="content:sitemap_index.meta_description"/><meta name="robots" content="index, follow, max-image-preview:large, max-snippet:-1" /><link rel="canonical" href="https://three.ws/sitemap" /><meta property="og:type" content="website" /><meta property="og:site_name" content="three.ws" /><meta property="og:locale" content="en_US" /><meta property="og:url" content="https://three.ws/sitemap" />-<meta property="og:title" content="Sitemap · three.ws" />-<meta property="og:description" content="Human-readable index of every page on three.ws." />+<meta property="og:title" content="Sitemap · three.ws" data-i18n-attr="content:sitemap_index.meta_og_title"/>+<meta property="og:description" content="Human-readable index of every page on three.ws." data-i18n-attr="content:sitemap_index.meta_og_description"/><meta property="og:image" content="https://three.ws/api/page-og?s=main&t=Sitemap&d=Human-readable+index+of+every+page+on+three.ws.&p=%2Fsitemap" /><meta property="og:image:width" content="1200" /><meta property="og:image:height" content="630" />@@ -20,8 +20,8 @@<meta property="og:image:alt" content="Sitemap - three.ws" /><meta name="twitter:card" content="summary_large_image" /><meta name="twitter:site" content="@trythreews" />-<meta name="twitter:title" content="Sitemap · three.ws" />-<meta name="twitter:description" content="Human-readable index of every page on three.ws." />+<meta name="twitter:title" content="Sitemap · three.ws" data-i18n-attr="content:sitemap_index.meta_twitter_title"/>+<meta name="twitter:description" content="Human-readable index of every page on three.ws." data-i18n-attr="content:sitemap_index.meta_twitter_description"/><meta name="twitter:image" content="https://three.ws/api/page-og?s=main&t=Sitemap&d=Human-readable+index+of+every+page+on+three.ws.&p=%2Fsitemap" /><script type="application/ld+json">{"@context":"https://schema.org","@graph":[{"@type":"WebPage","name":"Sitemap","description":"Human-readable index of every page on three.ws.","url":"https://three.ws/sitemap","isPartOf":{"@type":"WebSite","name":"three.ws","url":"https://three.ws"},"primaryImageOfPage":"https://three.ws/api/page-og?s=main&t=Sitemap&d=Human-readable+index+of+every+page+on+three.ws.&p=%2Fsitemap"}]}</script><link rel="alternate" type="application/xml" title="XML sitemap" href="/sitemap.xml" />@@ -95,16 +95,16 @@<header><div id="nav-container"></div></header><main class="sm-wrap"><div class="sm-hero">- <h1>Sitemap</h1>+ <h1 data-i18n="sitemap_index.sitemap">Sitemap</h1><p><span>1111</span> <span data-i18n="sitemap_index.pages_grouped">pages on three.ws, grouped by purpose. Looking for the machine-readable versions?</span></p><div class="sm-formats">- <a href="/everything"><code>/everything</code> · browse by goal, not by section</a>- <a href="/sitemap.xml"><code>sitemap.xml</code> · for search engines</a>- <a href="/llms.txt"><code>llms.txt</code> · for AI agents</a>- <a href="/llms-full.txt"><code>llms-full.txt</code> · long form</a>- <a href="/api/features.json"><code>features.json</code> · machine manifest</a>- <a href="/changelog"><code>changelog</code> · what's new</a>- <a href="/openapi.json"><code>openapi.json</code> · HTTP API</a>+ <a href="/everything" data-i18n-html="sitemap_index.browse_by_goal_not_by_section"><code>/everything</code> · browse by goal, not by section</a>+ <a href="/sitemap.xml" data-i18n-html="sitemap_index.for_search_engines"><code>sitemap.xml</code> · for search engines</a>+ <a href="/llms.txt" data-i18n-html="sitemap_index.for_ai_agents"><code>llms.txt</code> · for AI agents</a>+ <a href="/llms-full.txt" data-i18n-html="sitemap_index.long_form"><code>llms-full.txt</code> · long form</a>+ <a href="/api/features.json" data-i18n-html="sitemap_index.machine_manifest"><code>features.json</code> · machine manifest</a>+ <a href="/changelog" data-i18n-html="sitemap_index.what_s_new"><code>changelog</code> · what's new</a>+ <a href="/openapi.json" data-i18n-html="sitemap_index.http_api"><code>openapi.json</code> · HTTP API</a></div></div><div class="sm-filter">@@ -114,8 +114,8 @@</div><p class="sm-filter-count" role="status" aria-live="polite"><span id="sm-filter-count"></span><span id="sm-filter-hint" aria-hidden="true"></span></p><section class="sm-new" id="sm-new" aria-labelledby="sm-new-title">- <h2 id="sm-new-title">Newest<a class="sm-new-more" href="/changelog">full changelog →</a></h2>- <p class="sm-section-desc">The 9 most recently launched pages, straight to the live surface.</p>+ <h2 id="sm-new-title" data-i18n-html="sitemap_index.newestfull_changelog">Newest<a class="sm-new-more" href="/changelog">full changelog →</a></h2>+ <p class="sm-section-desc" data-i18n="sitemap_index.the_9_most_recently_launched_pages_straight">The 9 most recently launched pages, straight to the live surface.</p><ul class="sm-list"><li><a href="/docs/webgpu-renderer">@@ -192,22 +192,22 @@</ul></section><nav class="sm-toc" aria-label="Sections">- <a href="#main">Main</a>- <a href="#build">Build</a>- <a href="#labs">Labs</a>- <a href="#crypto">Crypto</a>- <a href="#agent-tools">Agent Tools</a>- <a href="#account">Account</a>- <a href="#learn">Learn</a>- <a href="#blog">Blog</a>- <a href="#legal">Legal</a>- <a href="#machine">Machine-readable</a>- <a href="#news">News</a>+ <a href="#main" data-i18n="sitemap_index.main">Main</a>+ <a href="#build" data-i18n="sitemap_index.build">Build</a>+ <a href="#labs" data-i18n="sitemap_index.labs">Labs</a>+ <a href="#crypto" data-i18n="sitemap_index.crypto">Crypto</a>+ <a href="#agent-tools" data-i18n="sitemap_index.agent_tools">Agent Tools</a>+ <a href="#account" data-i18n="sitemap_index.account">Account</a>+ <a href="#learn" data-i18n="sitemap_index.learn">Learn</a>+ <a href="#blog" data-i18n="sitemap_index.blog">Blog</a>+ <a href="#legal" data-i18n="sitemap_index.legal">Legal</a>+ <a href="#machine" data-i18n="sitemap_index.machine_readable">Machine-readable</a>+ <a href="#news" data-i18n="sitemap_index.news">News</a></nav><section class="sm-section" id="main"><header><h2><span data-i18n="sitemap_index.section_main">Main</span><span class="sm-count" data-count>76</span></h2>- <p class="sm-section-desc">Entry points into the product.</p>+ <p class="sm-section-desc" data-i18n="sitemap_index.entry_points_into_the_product">Entry points into the product.</p></header><ul class="sm-list"><li>@@ -748,7 +748,7 @@<section class="sm-section" id="build"><header><h2><span data-i18n="sitemap_index.section_build">Build</span><span class="sm-count" data-count>96</span></h2>- <p class="sm-section-desc">Create and customize an agent.</p>+ <p class="sm-section-desc" data-i18n="sitemap_index.create_and_customize_an_agent">Create and customize an agent.</p></header><ul class="sm-list"><li>@@ -1429,7 +1429,7 @@<section class="sm-section" id="labs"><header><h2><span data-i18n="sitemap_index.section_labs">Labs</span><span class="sm-count" data-count>26</span></h2>- <p class="sm-section-desc">Experimental features actively shipping. Expect fast iteration.</p>+ <p class="sm-section-desc" data-i18n="sitemap_index.experimental_features_actively_shipping_expe">Experimental features actively shipping. Expect fast iteration.</p></header><ul class="sm-list"><li>@@ -1620,7 +1620,7 @@<section class="sm-section" id="crypto"><header><h2><span data-i18n="sitemap_index.section_crypto">Crypto</span><span class="sm-count" data-count>174</span></h2>- <p class="sm-section-desc">On-chain features: pay-per-call, token launches, vanity wallets.</p>+ <p class="sm-section-desc" data-i18n="sitemap_index.on_chain_features_pay_per_call_token">On-chain features: pay-per-call, token launches, vanity wallets.</p></header><ul class="sm-list"><li>@@ -2847,7 +2847,7 @@<section class="sm-section" id="agent-tools"><header><h2><span data-i18n="sitemap_index.section_agent-tools">Agent Tools</span><span class="sm-count" data-count>11</span></h2>- <p class="sm-section-desc">Manage, talk to, and deploy individual agents.</p>+ <p class="sm-section-desc" data-i18n="sitemap_index.manage_talk_to_and_deploy_individual_agents">Manage, talk to, and deploy individual agents.</p></header><ul class="sm-list"><li>@@ -2933,7 +2933,7 @@<section class="sm-section" id="account"><header><h2><span data-i18n="sitemap_index.section_account">Account</span><span class="sm-count" data-count>16</span></h2>- <p class="sm-section-desc">Sign-in, dashboard, billing.</p>+ <p class="sm-section-desc" data-i18n="sitemap_index.sign_in_dashboard_billing">Sign-in, dashboard, billing.</p></header><ul class="sm-list"><li>@@ -3054,7 +3054,7 @@<section class="sm-section" id="learn"><header><h2><span data-i18n="sitemap_index.section_learn">Learn</span><span class="sm-count" data-count>532</span></h2>- <p class="sm-section-desc">Docs, tutorials, and reference.</p>+ <p class="sm-section-desc" data-i18n="sitemap_index.docs_tutorials_and_reference">Docs, tutorials, and reference.</p></header><ul class="sm-list"><li>@@ -6787,7 +6787,7 @@<section class="sm-section" id="blog"><header><h2><span data-i18n="sitemap_index.section_blog">Blog</span><span class="sm-count" data-count>39</span></h2>- <p class="sm-section-desc">Long-form announcements, launches, and writing from three.ws.</p>+ <p class="sm-section-desc" data-i18n="sitemap_index.long_form_announcements_launches_and_writing">Long-form announcements, launches, and writing from three.ws.</p></header><ul class="sm-list"><li>@@ -7141,7 +7141,7 @@<section class="sm-section" id="machine"><header><h2><span data-i18n="sitemap_index.section_machine">Machine-readable</span><span class="sm-count" data-count>20</span></h2>- <p class="sm-section-desc">Indexes and well-known files for crawlers and AI agents.</p>+ <p class="sm-section-desc" data-i18n="sitemap_index.indexes_and_well_known_files_for_crawlers">Indexes and well-known files for crawlers and AI agents.</p></header><ul class="sm-list"><li>@@ -7290,7 +7290,7 @@<section class="sm-section" id="news"><header><h2><span data-i18n="sitemap_index.section_news">News</span><span class="sm-count" data-count>112</span></h2>- <p class="sm-section-desc">Product launches, integrations, and announcements from three.ws.</p>+ <p class="sm-section-desc" data-i18n="sitemap_index.product_launches_integrations_and_announceme">Product launches, integrations, and announcements from three.ws.</p></header><ul class="sm-list"><li>@@ -8081,10 +8081,10 @@</section><div class="sm-empty" id="sm-empty" hidden><p><span data-i18n="sitemap_index.no_pages_match">No pages match</span> “<span id="sm-empty-q"></span>”.</p>- <p class="sm-empty-hint">Try a shorter word, or search everything: global search covers agents, coins, and skills too.</p>+ <p class="sm-empty-hint" data-i18n="sitemap_index.try_a_shorter_word_or_search_everything">Try a shorter word, or search everything: global search covers agents, coins, and skills too.</p><div class="sm-empty-actions">- <button type="button" id="sm-empty-clear">Clear filter</button>- <a id="sm-empty-search" href="/search">Search all of three.ws</a>+ <button type="button" id="sm-empty-clear" data-i18n="sitemap_index.clear_filter">Clear filter</button>+ <a id="sm-empty-search" href="/search" data-i18n="sitemap_index.search_all_of_three_ws">Search all of three.ws</a></div></div></main>