Skip to content

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

docs(changelog): record the latest hardening fixes and refresh guard, agora and ops docs and the generated public pages

nirholas2ea5195c223c
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 3adbece0f..cbc429c59 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -6,6 +6,7 @@ Public history for [three.ws](https://three.ws), newest first. New pages come fr
## 2026-10-25
+- **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]`
- **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/data/changelog.json b/data/changelog.json
index a0fa0a077..f9fe31bbc 100644
--- a/data/changelog.json
+++ b/data/changelog.json
@@ -1,6 +1,20 @@
{
"$comment": "Curated changelog entries for three.ws, the editorial layer of the public changelog. New PAGE launches are tracked automatically via the `added` field in data/pages.json; this file is for everything else holders care about: improvements, fixes, SDK releases, trading/payments capabilities, security work. scripts/build-page-index.mjs merges both sources into CHANGELOG.md, public/changelog.json, and public/changelog.xml. Newest first. Allowed tags: feature, improvement, fix, sdk, infra, docs, security, desktop (desktop entries become the desktop app's release notes). `link` is optional and must be a live three.ws path.",
"entries": [
+ {
+ "date": "2026-10-25",
+ "title": "Allowance pulls now require the signed real-funds agreement",
+ "summary": "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.",
+ "tags": ["fix"]
+ },
+ {
+ "date": "2026-10-25",
+ "title": "Commit feed cron skips quietly on a lock-check fault",
+ "summary": "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.",
+ "tags": [
+ "fix"
+ ]
+ },
{
"date": "2026-10-25",
"title": "Object-storage outages now answer a clean 503 with Retry-After instead of a raw 500",
@@ -102,82 +116,113 @@
"date": "2026-10-24",
"title": "Chat no longer fails when its default NVIDIA model is retired",
"summary": "NVIDIA stopped serving the Nemotron 3 Super function while still listing it, so chat requests that fell through to it got a 404 and, with the other providers throttled, ended in a 503. Chat, the tool chain, the brain and the CAD writer now use the Nemotron 3.5 Lightning model (with Ultra as its fallback), both verified live.",
- "tags": ["fix"],
+ "tags": [
+ "fix"
+ ],
"link": "/chat"
},
{
"date": "2026-10-24",
"title": "Fixed three more legacy thumbnail links that browsers refused to load",
"summary": "A handful of forge creations and 3D props stored from before an earlier URL fix still pointed straight at the storage bucket's own domain instead of three.ws's own CDN link, which Chrome blocks as an opaque cross-origin response. Model-page posters, a creation's related-models sidebar, forge share-card previews (the image X and Discord show when a link is pasted), and the Forged gallery's model-viewer thumbnails now all resolve through the same CDN link as everything else.",
- "tags": ["fix"],
+ "tags": [
+ "fix"
+ ],
"link": "/forge"
},
{
"date": "2026-10-23",
"title": "Bonding-curve status API no longer hard-fails when pump.fun blips",
"summary": "GET /api/crypto/bonding was returning a 503 to every caller during a pump.fun outage, even for mints it had already fetched successfully. It now caches each mint's bonding-curve status and keeps a longer last-known-good copy, so a failed upstream fetch serves that cached data (flagged with an x-pump-stale header) instead of a hard error. A 503 with a retry hint is now only returned for a mint that has no cached data at all.",
- "tags": ["fix"],
+ "tags": [
+ "fix"
+ ],
"link": "/api/crypto/bonding"
},
{
"date": "2026-10-24",
"title": "Hundreds of dependency security advisories cleared across the repo",
"summary": "Every committed lockfile was audited and patched: same-line security releases everywhere, vetted moves to patched majors (vitest 4, zod 4, helia 7, Svelte 5 and Vite 7 in the chat app, transformers 4 in HQ, gltf-transform 4 for the meshopt worker), and each package's tests and builds were rerun before and after. What remains are advisories with no patched release published anywhere (bigint-buffer, elliptic, node-forge) and pins that upstream SDKs still require.",
- "tags": ["security", "infra"]
+ "tags": [
+ "security",
+ "infra"
+ ]
},
{
"date": "2026-10-24",
"title": "Desktop app moves to Electron 45",
"summary": "The desktop app now runs on Electron 45 and electron-builder 26, clearing 61 security advisories from the old Electron 33 toolchain. Launch at login still starts the app hidden in the tray; on Windows, toggle the setting once if the console window opens at login.",
- "tags": ["desktop", "security"]
+ "tags": [
+ "desktop",
+ "security"
+ ]
},
{
"date": "2026-10-24",
"title": "Math renders in chat again",
"summary": "The chat app moved to Svelte 5, and KaTeX formulas in messages now render instead of showing raw TeX.",
- "tags": ["fix"],
+ "tags": [
+ "fix"
+ ],
"link": "/chat"
},
{
"date": "2026-10-24",
"title": "Long MCP answers arrive as a summary, and agents can search the docs",
"summary": "list_my_agents, recall and crypto_data now answer with a short summary, a count, a handle and the first page when the list is long, and the new expand tool reads the rest on request. A 100-coin market list drops from about 47,800 to 4,400 tokens. Handles are signed, account-bound and last 15 minutes. The new free search_docs tool answers how-to questions from the docs index on the main and studio servers.",
- "tags": ["feature", "docs"],
+ "tags": [
+ "feature",
+ "docs"
+ ],
"link": "/docs/mcp"
},
{
"date": "2026-10-24",
"title": "See what a prediction strategy would have earned before it trades",
"summary": "Agent Predictions records every strategy decision at the live order-book price in shadow mode, marks it at resolution, and shows shadow beside live results. A fee-aware scanner reads Solana event contracts for YES plus NO pairs under $1. Live stays owner-only.",
- "tags": ["feature"],
+ "tags": [
+ "feature"
+ ],
"link": "/agent-predictions"
},
{
"date": "2026-10-24",
"title": "Pay for a model request with a wallet, no account needed",
"summary": "POST /api/v1/chat/completions now answers an unauthenticated request with an x402 upto challenge on Solana, sized to the model's worst case for that request. Sign it, retry, and only the metered tokens are charged at the published per-token price; the rest of the cap is refunded. Streaming settles when the stream closes, and a dropped stream is charged only for the tokens already sent. GET /api/v1/models now lists the price sheet and round limits.",
- "tags": ["feature", "docs"],
+ "tags": [
+ "feature",
+ "docs"
+ ],
"link": "/docs/metered-router"
},
{
"date": "2026-10-24",
"title": "Skills are scanned for hidden behaviour before they are listed",
"summary": "Every marketplace skill version is now checked for secret access, calls to hosts it never declared, hidden or obfuscated code and instructions that skip the owner's confirmation. Clean skills list as before, suspicious ones are held for a moderator, and dangerous ones are refused. Authors see the file, the line and how to fix each finding in the publish form, and the existing catalog was rescanned.",
- "tags": ["security", "feature", "docs"],
+ "tags": [
+ "security",
+ "feature",
+ "docs"
+ ],
"link": "/docs/skill-supply-scan"
},
{
"date": "2026-10-24",
"title": "See what a Forge generation costs before you press Generate",
"summary": "The Forge page now shows a live cost line for the tier, engine and options you picked, read from the same pricing code that bills you, with nothing spent. A pay-to-keep mode (free preview, pay in $THREE to download, holders keep free) is built and switched off, so downloads stay free until it is turned on.",
- "tags": ["feature", "docs"],
+ "tags": [
+ "feature",
+ "docs"
+ ],
"link": "/docs/forge"
},
{
"date": "2026-10-24",
"title": "Agents join the open Solana agent registry and hires read trust tiers",
"summary": "Minted agents are enrolled in the open Solana agent registry (8004) with the platform authority signing, so owners pay nothing. The marketplace ranks providers by registry tier after completed hires, a hire can require a minimum tier, and agent pages show an 8004 tier badge when registered. A rate-limited back-fill covers existing agents.",
- "tags": ["feature"],
+ "tags": [
+ "feature"
+ ],
"link": "/docs/solana-agent-registry"
},
{
@@ -194,7 +239,10 @@
"date": "2026-10-24",
"title": "Drive the CLI from scripts and agents, and download a run report",
"summary": "Every three-ws command now takes --json (one JSON document on stdout, diagnostics on stderr) and --non-interactive (never prompts), with a stable exit-code table: 2 usage, 3 auth, 4 refused by a guard, 5 payment required, 6 network. New commands cover agents, runs, wallet balance, skill install and orders. `three-ws report run <id> --out run.html` writes one self-contained offline file with the goal, tool calls, decisions, trades, outcome and the decision-trail head hash, and the run page has a matching Download report button.",
- "tags": ["feature", "sdk"],
+ "tags": [
+ "feature",
+ "sdk"
+ ],
"link": "/docs/cli"
},
{
diff --git a/docs/ca2x402.md b/docs/ca2x402.md
index 1b70d0374..1caac705b 100644
--- a/docs/ca2x402.md
+++ b/docs/ca2x402.md
@@ -216,6 +216,16 @@ never charged for a bad or missing answer:
- `503 data_unavailable` when the market reader (DexScreener plus its 15-minute
last-known-good copy) has no live market or no 24 hour change for the token.
+A failure that happens after settlement (rare for this read-only handler) is
+answered with `paid: true` and `retry_safe`, and the same `X-PAYMENT` header may
+re-run the call without a second charge, bounded by `X402_PAID_RETRY_MAX` and a
+time window. A call that already completed answers `409` on a replay. The `402`
+challenge also mirrors its envelope into a base64 `PAYMENT-REQUIRED` header,
+capped at 7 KB (the body stays the canonical, complete copy).
+
+This endpoint answers x402 only. It does not opt in to the MPP `Payment`
+challenge that some other paid routes offer (see [MPP on Solana](mpp-solana.md)).
+
Access control uses the shared bypass hook with the `x402:bypass` scope
([`api/_lib/x402/access-control.js`](../api/_lib/x402/access-control.js)), which is
how platform-internal callers read the endpoint without paying.
diff --git a/docs/chatgpt-ar.md b/docs/chatgpt-ar.md
index 7ec4b3271..1c9af3179 100644
--- a/docs/chatgpt-ar.md
+++ b/docs/chatgpt-ar.md
@@ -31,7 +31,7 @@ The same free lane ships into ChatGPT twice, because ChatGPT has two integration
### 1. The ChatGPT app (Apps SDK / MCP connector)
-Three front doors serve the same free tools over one handler, all with no authentication. `https://three.ws/api/mcp-chatgpt` is the one ChatGPT lists: the eight 3D tools and the model viewer, with no catalog or persona tools and no `frameDomains`, because OpenAI's app guidelines reserve frame domains for embedding an essential third-party experience. `https://three.ws/api/mcp-studio` is the full surface for Claude and every other MCP host, and `https://three.ws/api/mcp-grok` serves the same full set to Grok and the xAI Responses API. `SURFACES` in [api/_mcp-studio/dispatch.js](../api/_mcp-studio/dispatch.js) is the single definition of what each door advertises. The full surface carries fourteen free tools: six generation tools (`forge_free`, `text_to_avatar`, `mesh_forge`, `rig_mesh`, `forge_avatar`, `refine_model`), the `check_job` collector that picks up a generation which outran the tool call (a pending result names its `stage`, `mesh` or `rig`, so the collector knows which leg it is waiting on), the read-only `look_at_model` tool that renders any public GLB from several angles and returns the frames as images plus a plain reading of its geometry, so the assistant can judge its own output before printing a link, three read-only asset catalog tools (`search_catalog`, `get_catalog_item`, `get_item_source`, in [api/_mcp-studio/catalog-tools.js](../api/_mcp-studio/catalog-tools.js)), and three persona/embodiment tools (`create_agent_persona`, `get_agent_persona`, `persona_say`, in [api/_mcp-studio/persona-tools.js](../api/_mcp-studio/persona-tools.js)). The first eight are the ChatGPT listing. Full server documentation: [3D Studio MCP](./mcp-studio.md).
+Three front doors serve the same free tools over one handler, all with no authentication. `https://three.ws/api/mcp-chatgpt` is the one ChatGPT lists: the eight 3D tools and the model viewer, with no catalog or persona tools and no `frameDomains`, because OpenAI's app guidelines reserve frame domains for embedding an essential third-party experience. `https://three.ws/api/mcp-studio` is the full surface for Claude and every other MCP host, and `https://three.ws/api/mcp-grok` serves the same full set to Grok and the xAI Responses API. `SURFACES` in [api/_mcp-studio/dispatch.js](../api/_mcp-studio/dispatch.js) is the single definition of what each door advertises. The full surface carries sixteen free tools: six generation tools (`forge_free`, `text_to_avatar`, `mesh_forge`, `rig_mesh`, `forge_avatar`, `refine_model`), the `check_job` collector that picks up a generation which outran the tool call (a pending result names its `stage`, `mesh` or `rig`, so the collector knows which leg it is waiting on), `get_job` (full and Grok surfaces only, not the ChatGPT listing), a status reader for the same jobs that reports `progress`, `eta_seconds` and `elapsed_seconds` while one runs and never starts or repeats a generation, the read-only `look_at_model` tool that renders any public GLB from several angles and returns the frames as images plus a plain reading of its geometry, so the assistant can judge its own output before printing a link, four read-only catalog and docs tools (`search_catalog`, `get_catalog_item`, `get_item_source`, `search_docs`, in [api/_mcp-studio/catalog-tools.js](../api/_mcp-studio/catalog-tools.js)), and three persona/embodiment tools (`create_agent_persona`, `get_agent_persona`, `persona_say`, in [api/_mcp-studio/persona-tools.js](../api/_mcp-studio/persona-tools.js)). The first eight are the ChatGPT listing. Every generation tool also accepts an optional `idempotency_key`, so a retried call returns the first call's job instead of generating twice, and every generation, rig and refinement result carries a signed run receipt (see [Run receipts](./run-receipts.md)). Full server documentation: [3D Studio MCP](./mcp-studio.md).
ChatGPT drops a tool call still open at 60 seconds, while a generation takes one to four minutes. So on `/api/mcp-chatgpt` every call answers inside a 40 second budget (`CHATGPT_CALL_BUDGET_MS`) with either the finished model or a pending job, and the inline viewer widget collects that job itself (running the rig leg when an avatar's mesh lands first) and shows the model when it is ready. The assistant does not have to loop on `check_job`. Generation quotas on this door are keyed per ChatGPT user rather than on OpenAI's shared egress IP.
diff --git a/docs/discord-activity.md b/docs/discord-activity.md
index 098fe6361..a4e1ea9b4 100644
--- a/docs/discord-activity.md
+++ b/docs/discord-activity.md
@@ -22,7 +22,9 @@ the call sees the same room:
3. The finished model (preview image + an "Open in 3D" link) posts to
everyone in the room at once, with a shared like/vote count.
4. An agent reacts in text to what just happened, grounded only in the real
- prompt and vote count (see [Agent reactions](#agent-reactions)).
+ prompt and vote count (`api/_lib/gateway/discord-activity-agent.js`: one
+ short LLM-written sentence, dropped for a deterministic template if it
+ fails the validation checks; it never mentions money, coins or wallets).
No account creation, no wallet, no purchase: the room is free to use for
anyone already in the voice channel.
@@ -41,10 +43,13 @@ The Activity never holds a Discord client secret. The flow, per
finish authenticating the SDK itself.
4. The client POSTs the access token plus the Activity's `instance_id`,
`guild_id`, and `channel_id` to `POST /api/gateway/discord-activity-session`,
- which re-verifies the token against Discord's own `/users/@me` (never
- trusting the client's claimed identity), creates or updates the room, and
- mints a short-lived (4 hour) HMAC-signed session token scoped to that one
- room.
+ which re-verifies the token against Discord's own `/oauth2/@me` (never
+ trusting the client's claimed identity, and refusing with `wrong_audience`
+ any token that was not issued to our `DISCORD_CLIENT_ID` application),
+ creates or updates the room, and mints a short-lived (4 hour) HMAC-signed session token scoped to that one
+ room. An `instance_id` is bound to the guild and channel it was first seen
+ with; a later request claiming the same instance under a different guild
+ or channel is refused with `403 room_mismatch`.
Every room API call after that carries `Authorization: Bearer <session token>`
(the SSE stream carries it as `?token=` instead, since the browser's native
@@ -60,7 +65,11 @@ against needs an explicit URL Mapping in the Discord Developer Portal, or
Discord's CSP blocks it.
This app has exactly one such cross-origin dependency: the R2 CDN that serves
-Forge preview images and GLBs. The client calls
+Forge preview images and GLBs. (Forge reads now normalize stored media URLs to
+the same-origin `/cdn/` proxy form, so the mapping only matters for legacy
+rows or payloads that still carry the raw bucket domain. The client gets the
+host from `GET /api/gateway/discord-activity-config`, derived from
+`S3_PUBLIC_DOMAIN`.) The client calls
`patchUrlMappings([{ prefix: 'cdn', target: cdnHost }], { patchFetch: true, patchXhr: true, patchSrcAttributes: true })`
once at startup (`src/discord-activity/app.js`), which transparently rewrites
any request to that host through Discord's proxy. The matching Developer
diff --git a/docs/domains.md b/docs/domains.md
index 046bbeee3..7583b31ab 100644
--- a/docs/domains.md
+++ b/docs/domains.md
@@ -16,7 +16,7 @@ Agents can search, price, check and register real web domains, and serve their p
| Renewal price | Same as the yearly registration price. |
| Payment | Prepaid credits ([/credits](https://three.ws/credits)), debited at the exact price Google quotes. No markup. |
| Premium names | A name can price above its TLD base. `domain_check` and `domain_register_quote` return the exact figure for that name. |
-| Supported TLDs | Cloud Domains has no list endpoint. [data/domain-tlds.json](../data/domain-tlds.json) is a snapshot probed by `node scripts/refresh-domain-tlds.mjs` (run with `DOMAINS_ACCESS_TOKEN=$(gcloud auth print-access-token)`). An unsupported TLD answers `UNSUPPORTED`. |
+| Supported TLDs | Cloud Domains has no list endpoint. [data/domain-tlds.json](../data/domain-tlds.json) is a snapshot probed by `node scripts/refresh-domain-tlds.mjs` (run with `DOMAINS_ACCESS_TOKEN=$(gcloud auth print-access-token)`). The committed snapshot lists 121 supported TLDs of the 153 probed. An unsupported TLD answers `UNSUPPORTED`. |
| Registrar quota | 300 sensitive requests per day per project, 100 per minute, 20 registrations per project. |
### The daily quota
@@ -32,9 +32,9 @@ Search, availability and register count against the 300/day quota, which resets
| `domain_pricing` | read | TLD price list from the snapshot, filter by `tld` or `max_price_usd`. |
| `domain_register_quote` | write | Validate-only register against the real API: exact price, term, renewal, privacy, notices, credit balance. Returns the `quote_id`. |
| `domain_register` | financial | Spend credits and register. Needs `quote_id`, `confirm_spend: true`, `expected_price_usd`, `idempotency_key`. |
-| `domain_status` | read | Settle and read a registration. |
+| `domain_status` | read | Settle and read a registration. It polls the registrar and writes the outcome, so it is annotated not read-only (but idempotent). |
| `domain_connect` | write | Serve an agent's public page on a registered domain. |
-| `domain_connect_status` | read | DNS, certificate and live state of a connected host. |
+| `domain_connect_status` | read | DNS, certificate and live state of a connected host. Promotes the host to live when its certificate turns active, so it carries the same not-read-only, idempotent annotation. |
The flow an agent follows:
@@ -56,6 +56,8 @@ curl 'https://three.ws/api/domains/suggest?name=Orbit'
Signed-in: `POST /api/domains/quote`, `POST /api/domains/register`, `GET /api/domains/status`, `GET /api/domains/list`, `POST /api/domains/connect`, `GET /api/domains/connect-status`. Registration through an API key needs the key's spend scope.
+A real registration first creates the domain's Cloud DNS zone and registers the name on that zone's name servers, because the registrar rejects a body with no DNS provider and Google Domains DNS is deprecated. Connecting the name to an agent later needs no DNS switch. Validate-only quotes use the standard Cloud DNS name server set.
+
## Registrant contact
Required: `name`, `email`, `phone` (international, `+14155550123`), `address_lines`, `city`, `postal_code`, `country` (two letters), optionally `region`. It is sent to the registrar, stored on the registration so the owner can see what it was registered to, and never returned to another account. Privacy defaults to hidden WHOIS where the TLD supports it.
@@ -73,11 +75,11 @@ Coin pages ([/coin/:id](https://three.ws/coin/bitcoin)) show a "Domains" panel:
`domain_connect` / `POST /api/domains/connect` runs the Cloud Run plus load balancer procedure in [docs/ops/gcp-production.md](ops/gcp-production.md#web-domains):
1. Create a Cloud DNS zone for the domain and A records for the apex and `www` at the load balancer address.
-2. Point the registration's nameservers at the zone.
+2. Make sure the registration's nameservers point at the zone (already true for names registered here; the step is idempotent).
3. Create a Google-managed certificate and attach it to the HTTPS proxy.
4. Mark the host `live` when the certificate is `ACTIVE`.
-Once live, `https://<domain>/` serves the agent's public page (`/agents/<id>`), and every other path serves the normal site. Certificates take minutes to provision after the nameservers propagate; `domain_connect_status` reports `pending_dns`, `pending_cert`, then `live`. The load balancer's HTTPS proxy holds at most 15 certificates, so connected domains are capped there until the proxy moves to certificate maps.
+Once live, `https://<domain>/` serves the agent's public page (`/agents/<id>`), and every other path serves the normal site. Certificates usually turn active within 15 to 60 minutes after the nameservers propagate; `domain_connect_status` reports `pending_dns`, `pending_cert`, then `live`. The load balancer's HTTPS proxy holds at most 15 certificates, so connected domains are capped there until the proxy moves to certificate maps.
`docs/tutorials/deploy-to-vercel-custom-domain.md` describes the legacy Vercel path and does not apply to production, which runs on Cloud Run.
diff --git a/docs/drops.md b/docs/drops.md
index 7e87e55b7..f440ac65c 100644
--- a/docs/drops.md
+++ b/docs/drops.md
@@ -35,7 +35,7 @@ Open [/drops](https://three.ws/drops), sign in, and press **Launch a
collection**. You supply:
- **Name and symbol.** The symbol is 2 to 10 letters or digits, shown on cards.
-- **Supply.** Up to 10,000. The roll is instant and free at any size, because no
+- **Supply.** 1 to 10,000. The roll is instant and free at any size, because no
art is generated at this step.
- **Base style.** The look every item shares, for example
`stylized matte-clay guardian creature, soft rim light, chunky proportions`.
@@ -43,7 +43,8 @@ collection**. You supply:
weights. The builder shows each option's resulting share as you type. An
option can carry its own prompt fragment when the trait's display name is not
what you want fed to the generator: the value `Bomber jacket` can generate
- from `wearing a worn leather bomber jacket`.
+ from `wearing a worn leather bomber jacket`. A drop takes at most 12 layers
+ and 64 options per layer.
Submitting rolls the supply and lands you on the collection page. The drop
starts as a **draft**: its seed is withheld, so the provenance hash it publishes
@@ -79,7 +80,9 @@ curl -X POST https://three.ws/api/drops/create \
```
A layer's options may be bare strings, in which case each weighs 1 and its value
-doubles as its prompt fragment. The response carries the `slug`, the
+doubles as its prompt fragment. Optional body fields are `description`,
+`visibility` (`public` by default, or `unlisted` / `private`) and `seed`. The
+`201` response wraps the collection in `drop`, which carries the `slug`, the
`provenance_hash`, and (for the creator) the `seed`.
## How rarity is computed
@@ -107,8 +110,9 @@ uses for cosmetics:
## Reveal: art is forged per item
A freshly rolled item is **sealed**. Its traits are already public and its rank
-is already fixed; only the art is unforged. Pressing **Reveal** on the collection
-page composes the item's prompt (the base style, then each rolled trait's prompt
+is already fixed; only the art is unforged. Pressing **Reveal this item** on the
+collection page (a draft must be published first, otherwise `409 not_published`)
+composes the item's prompt (the base style, then each rolled trait's prompt
fragment in layer order, then the hints that keep the output riggable) and
submits it to [the Forge](forge.md). The page then polls until the GLB lands.
@@ -120,8 +124,9 @@ Reveal states are `sealed`, `revealing`, `revealed`, and `failed`. A failed
reveal keeps its error and is retryable from the same button. Claiming an item
for reveal is a conditional database update, so a double-clicked button cannot
start two paid generation jobs for the same token, and a claim that never comes
-back is released automatically after fifteen minutes rather than needing a
-sweeper cron.
+back is released to `sealed` by the next poll once it is fifteen minutes old,
+rather than needing a sweeper cron. The button reads **Retry reveal** after a
+failure.
Because every item is generated as a full-body character in a neutral A-pose, it
inherits the platform's universal animation retarget: any revealed item drives
diff --git a/docs/hold-to-access.md b/docs/hold-to-access.md
index f02170184..b273ffbd1 100644
--- a/docs/hold-to-access.md
+++ b/docs/hold-to-access.md
@@ -130,13 +130,18 @@ UI needs to recover — no second round-trip:
"required": { "level": 1, "id": "bronze", "min_usd": 25 },
"usd_to_go": 12.50,
"acquire": { "mint": "Fe…pump", "symbol": "THREE", "swap_url": "…", "pump_url": "…" },
- "pay_per_use": { "action": "forge.high", "usd": 0.49 } // null when hold-only
+ "pay_per_use": { "action": "forge.high", "usd": 0.50 } // null when hold-only
}
```
A feature with a `payPerUse` action lets a non-holder pay once in $THREE instead of
holding. A hold-only feature omits `pay_per_use`.
+A handler that owns its own 402 (a pay-per-use action whose price depends on the request,
+like pay-to-keep below) uses `checkFeatureAccess(req, res, featureId, { body })` from the
+same module instead. It resolves the caller the same way (comp, pass, on-chain tier) but
+only reports `{ eligible, level, wallet }` and writes no gate response.
+
---
## The perk registry
@@ -164,12 +169,27 @@ how an unbuilt feature ends up reading as a benefit, so when a gate ships, flip
|---------|----------|--------|-------------|---------|
| `forge.high` — High-quality generation (200k poly + PBR) | Bronze | **Live** | yes | [`api/forge.js`](../api/forge.js) |
| `forge.gameready` — Game-ready export (Unity/Unreal) | Bronze | **Live** | yes | [`api/forge-gameready.js`](../api/forge-gameready.js) |
+| `forge.keep`: Keep a Forge generation (original file) | Bronze | Off by default (`enforced: false`) | per-tier `forge.keep.<tier>` | [`api/forge-keep.js`](../api/forge-keep.js) |
| `worlds.private` — Private, invite-only worlds | Silver | Planned | — | partial (no visibility dim yet) |
| `mcp.priority` — Priority MCP routing | Silver | Planned | — | not built (no shared queue) |
| `worlds.branded` — Branded worlds + custom environments | Gold | Planned | — | not built |
| `drops.early` — Early access to drops | Gold | Planned | — | drop endpoints exist |
| `names.first_dibs` — First dibs on rare `*.threews.sol` | Genesis | Planned | `name.auction` | SNS exists |
+### Pay-to-keep (`forge.keep`)
+
+[`api/forge-keep.js`](../api/forge-keep.js) is an optional gate on the original file of a
+Forge generation. It is **off** unless `FORGE_PAY_TO_KEEP=on` (flip it with
+`npm run forge:pay-to-keep -- on|off|status`, which uses `--update-env-vars`). While off,
+every generation is keepable and the endpoint answers `enabled: false, kept: true`. While
+on, generating and previewing on a free lane stays free, and the original file is released
+once per creation to a Bronze+ holder, or against one settled $THREE payment for
+`forge.keep.draft` ($0.05) or `forge.keep.standard` ($0.15). High needs no keep payment
+because it is already held or paid for at generation time. Because the registry flag
+describes a gate that is off by default, `forge.keep` stays `enforced: false` and `/three`
+shows it as Planned. `GET /api/forge-quote` prices a generation (and the keep step) per
+path, tier and options from the same tier and catalog code.
+
### Adjacent levers (live, not feature-gated)
- **Compute discount** — every fixed-price action is re-priced by the holder's
@@ -261,7 +281,9 @@ Today worlds are **owner-based with no visibility concept**
with its id. Making "private" a real perk means adding a visibility dimension and
enforcing it on read.
-**1. Schema** — migration `api/_lib/migrations/2026-06-24-world-visibility.sql`:
+**1. Schema**: a new migration in `api/_lib/migrations/` (timestamp-prefixed, like
+`20261015000000_world_gems.sql`) against the `world_docs` table from
+`2026-06-01-world-docs.sql`:
```sql
ALTER TABLE world_docs ADD COLUMN IF NOT EXISTS visibility text NOT NULL DEFAULT 'public';
@@ -344,6 +366,7 @@ Unit coverage for the same behavior lives in `tests/forge-high-gate.test.js`,
| Env var | Required | Purpose |
|---------|----------|---------|
| `HOLDER_PASS_SECRET` | prod | HMAC key for signing/verifying tier passes |
+| `FORGE_PAY_TO_KEEP` | no | `on` enables the pay-to-keep gate in `api/forge-keep.js` (default off) |
| `THREE_COMP_ACCOUNTS` | no | extra comped handles / emails / user ids, comma-separated (merged with the built-in allowlist) |
| `THREE_TOKEN_MINT` | — | $THREE mint (defaults to the canonical CA) |
| `THREE_TOKEN_DECIMALS` | — | token decimals (default 6) |
diff --git a/docs/internal/fable-playbook.md b/docs/internal/fable-playbook.md
index 74a44c364..6425f6ee8 100644
--- a/docs/internal/fable-playbook.md
+++ b/docs/internal/fable-playbook.md
@@ -60,7 +60,7 @@ new work while those sit unexecuted; they were sequenced deliberately.
The queue is also worked unattended. Evolve (`npm run evolve:start`, runbook
[docs/ops/evolve.md](../ops/evolve.md)) runs headless Claude Code sessions
-around the clock in its own worktree: it runs the lowest runnable order, writes
+around the clock in its own worktree (on Sonnet by default, `EVOLVE_MODEL` overrides it): it runs the lowest runnable order, writes
new scouted orders into the `400` band when the queue runs thin, and sweeps
production every few hours. It leaves an order alone for 6 hours after a human
last touched it, and `npm run evolve:pause` frees the subscription for
@@ -96,7 +96,7 @@ interactive work.
## 3. Engineering plays, ranked by (revenue impact x Fable advantage)
These extend, never replace, the open work orders. Each is additive, flag-gated,
-and sourced from the REUSE-MAP where OSS applies. State as of 3 September 2026 is
+and sourced from the REUSE-MAP where OSS applies. State as of 25 October 2026 is
noted per item so nobody rebuilds what already exists.
### Tier 1: direct revenue or conversion
@@ -114,7 +114,8 @@ noted per item so nobody rebuilds what already exists.
(`npm run check:vendored` keeps the vendored copies honest). Remaining upside
is measurement, not plumbing: prove the byte and first-render win per surface.
3. **AR everywhere.** *Shipped.* `src/usdz-pipeline.js`, `src/usdz-animated.js`,
- `src/ar-studio.js`, `api/ar.js` and `api/_lib/ar-launch.js` exist, with an AR
+ `src/ar-studio.js` (also extracted as the standalone `packages/ar-studio`,
+ kept in step with the app by a parity test), `api/ar.js` and `api/_lib/ar-launch.js` exist, with an AR
MCP tool at `api/_mcp3d/tools/ar.js`. Remaining upside is placement: make the
AR link unmissable on every generated artifact rather than a page you find.
4. **Embed, oEmbed and OG thumbnails.** *Shipped.* `api/agent-oembed.js`,
@@ -136,9 +137,14 @@ Before building the next lane, instrument the ones that exist.
the universal-rig doctrine in `CLAUDE.md`: no rig allowlist). This is graphics
work competitors cannot hire cheaply and Fable does natively. It makes every
avatar feel alive instead of looped.
-6. **Gaussian splatting lane.** Partially present (`src/splat-viewer.js`,
- `pages/splat.html`). The open half is the pipeline: photo or video to splat to
- embeddable scene, on the same monetization rails as Forge. All REUSE-MAP
+6. **Gaussian splatting lane.** Mostly present. The viewer (`src/splat-viewer.js`,
+ `pages/splat.html`) runs Spark 2.3.1 with worker-built LoD trees on large
+ scenes and saved camera hotspots with in-browser video export
+ (`src/splat-hotspots.js`). `POST /api/forge-splat` turns one image into a
+ splat (`workers/model-triposplat`), and the AR Studio "From a photo" tab
+ (`/api/forge-scene-objects`, `workers/model-sam3d-objects`) is built but off
+ until the gated weights are staged. The open half is the product loop: photo
+ or video to splat to embeddable scene, on the same monetization rails as Forge. All REUSE-MAP
splatting picks in the allowed column are permissively licensed; the
non-commercial rasterizers are a hard no regardless of demo quality.
7. **WebGPU/TSL migration, flag-gated.** three.js ships a WebGPU renderer;
@@ -177,24 +183,24 @@ $50M to $100M ARR. The ladder:
### The measured position
-Run `npm run readout:revenue -- --window all`. As of 9 October 2026 that
+Run `npm run readout:revenue -- --window all`. As of 25 October 2026 that
returns:
-- **61,767 settled x402 payments, $10,303.60 gross.**
-- **61,748 of them (99.97%, $10,163.51) are the internal ring**: platform-controlled
+- **51,796 settled x402 payments, $7,564.28 gross.**
+- **51,767 of them (99.94%, $7,414.21) are the internal ring**: platform-controlled
wallets paying platform endpoints on a cron. Real money on a real chain, and
entirely our own.
-- **0 calls are synthetic** (the classifier's bucket for test payers such as a
+- **1 call is synthetic** (the classifier's bucket for test payers such as a
literal `PAYER` string from a replay-test path).
-- **External, all time: 19 calls from 4 addresses, $140.09.** $140.00 of it is
+- **External, all time: 28 calls from 5 addresses, $150.08.** $140.00 of it is
two routes, nine `/api/x402/dance-tip` payments ($90) and five
`/api/x402/club-cover` payments ($50); the rest is cents across
- `/api/x402/skill-marketplace`, `/api/x402/pump-agent-audit` and
- `/api/x402/mint-to-mesh-batch`. Four addresses is few enough to check by hand
+ `/api/x402/market-pulse`, `/api/x402/skill-marketplace`,
+ `/api/x402/pump-agent-audit` and a handful of other routes. Five addresses is few enough to check by hand
that they are strangers before any of it is cited as rung-1 proof.
So we are not on rung 1. We are below it, and the gross ledger hides that by a
-factor of roughly 74. This is the single most important fact in this
+factor of roughly 50. This is the single most important fact in this
document, and until this readout existed it was not visible to anyone reading
the numbers the platform reported about itself.
diff --git a/docs/seeker-app.md b/docs/seeker-app.md
index 0e408fc1f..738935e01 100644
--- a/docs/seeker-app.md
+++ b/docs/seeker-app.md
@@ -13,7 +13,7 @@ three.ws ships as a native Android app for the Solana Seeker (and Saga) through
| Share sheet | Share a photo from any app to three.ws: it opens the selfie flow with the photo attached. Share a `.glb`: it opens the upload flow | `public/share-target-sw.js`, `src/shared/share-target.js` |
| Offline | A branded offline screen that reloads itself when the network returns, instead of Chrome's error page | `public/offline.html`, `vite.config.js` (workbox `precacheFallback`) |
| Home-screen shortcuts | Long-press the icon: Create, Discover, My agents | `solana-mobile/twa/twa-manifest.json`, web manifest in `vite.config.js` |
-| Icon | A maskable icon with the glyph inside Android's safe zone, so circle and squircle launchers never crop it | `public/pwa-maskable-*.png` |
+| Icon | A maskable icon with the glyph inside Android's safe zone, so circle and squircle launchers never crop it | `public/pwa-maskable-192x192.png`, `public/pwa-maskable-512x512.png` |
| Seeker verification | Prove Seeker ownership by holding the soulbound Seeker Genesis Token; owners get a "Seeker verified" badge on every agent they own | `api/seeker/[action].js`, `api/_lib/seeker-genesis.js` |
| Deep links | Any `https://three.ws/...` link opens inside the app once Digital Asset Links verify the release key | `public/.well-known/assetlinks.json` |
@@ -33,9 +33,9 @@ The web manifest declares a `share_target` at `POST /create/share`. The service
- an image goes to `/create/selfie?shared=1`, where the page picks it up as the frontal selfie (a second and third image fill the optional side angles);
- a `.glb` goes to `/create?shared=glb`, where the upload flow validates and stages it;
-- anything else goes to `/create`.
+- anything else goes to `/create?shared=1`.
-The handoff is one-shot and expires after ten minutes, so a stale share can never resurface. On the Seeker the APK registers the same target with Android, so three.ws appears in the system share sheet for photos and `model/gltf-binary` files.
+The handoff is one-shot and expires after ten minutes, so a stale share can never resurface. (The iOS app has no service worker, so its share extension hands files over through the app instead, using the same one-shot rule; see `takeSharedFiles` in `src/shared/share-target.js`.) On the Seeker the APK registers the same target with Android, so three.ws appears in the system share sheet for photos and `model/gltf-binary` files.
## Testing without a Seeker
diff --git a/docs/shipfeed.md b/docs/shipfeed.md
index c9f28c49d..0f3006f38 100644
--- a/docs/shipfeed.md
+++ b/docs/shipfeed.md
@@ -81,6 +81,8 @@ Everything unclaimed is clustered into **ships**: bursts of commits separated by
Public, no auth, cached for 5 minutes.
+If GitHub cannot be read (rate limit or outage) and an earlier response exists, the endpoint serves that last-good feed (kept up to 24 hours) with `"stale": true` instead of failing.
+
| param | values | default |
| --- | --- | --- |
| `limit` | 1 to 500 commits | 200 |
@@ -158,7 +160,7 @@ The footer is best-effort by design: if GitHub cannot be read at that moment, th
The same cron also replies to the @trythreews X thread with every entry that passes `data/changelog-x-filter.json` (no wallet, payment, key, outage or security internals, and nothing that is only a fix). That lane is isolated from Telegram, so one failing never blocks the other, and its tweets carry no provenance footer: just the title, summary and changelog link inside the 280-character budget.
-**The raw commit feed** (`/api/cron/commit-feed-push`, every 5 minutes) reads its headline from the same parser, so a scoped commit now says "Feature · resilience" rather than "feat(resilience)", and it skips commits the classifier calls noise: merges, `chore(deps):` bumps, and lockfile-only changes. A skipped commit still advances the lane's state, so nothing is ever re-read, and the tick reports `{ posted, skipped }` so the drop is visible in the logs rather than silent.
+**The raw commit feed** (`/api/cron/commit-feed-push`, every 5 minutes) reads its headline from the same parser, so a scoped commit now says "Feature · resilience" rather than "feat(resilience)", and it skips commits the classifier calls noise: merges, `chore(deps):` bumps, and lockfile-only changes. A skipped commit still advances the lane's state, so nothing is ever re-read, and the tick reports `{ posted, skipped }` so the drop is visible in the logs rather than silent. If GitHub's rate limit is exhausted the lane returns `{ skipped: 'github_rate_limited' }` and retries on the next tick (a 200, not an error). Any other failure reading GitHub answers 502 `{ ok: false, error }` and releases the lane lock; state lives in `app_settings`, so the next tick resumes where this one stopped.
---
@@ -200,6 +202,6 @@ The full reference, including the linking internals exported for tuning, is in t
## Known limits
-- **GitHub's unauthenticated rate limit is 60 requests an hour per IP.** Set `GITHUB_TOKEN` on the service to raise it. Without one, a busy hour can leave the feed serving its 5-minute cache and the Telegram footer absent.
+- **GitHub's unauthenticated rate limit is 60 requests an hour per IP.** Set `GITHUB_TOKEN` on the service to raise it. Without one, a busy hour leaves the feed serving its last-good copy (marked `stale`), the commit-feed lane skipping ticks, and the Telegram footer absent.
- **Linking is a heuristic, and it publishes as one.** Every link carries a confidence and its reasons; a release note that legitimately found no code says so on the page rather than silently showing nothing.
- **A commit older than the window can never be linked**, however well it matches. That is deliberate: the alternative is a note claiming work from a month it had nothing to do with.
diff --git a/public/changelog-recent.json b/public/changelog-recent.json
index 2b6578da2..b18a383bb 100644
--- a/public/changelog-recent.json
+++ b/public/changelog-recent.json
@@ -1,14 +1,24 @@
{
- "generated_at": "2026-10-25T11:57:17.256Z",
+ "generated_at": "2026-10-25T11:57:28.846Z",
"generated_by": "scripts/build-page-index.mjs from data/pages.json + data/changelog.json",
"site": {
"name": "three.ws",
"url": "https://three.ws"
},
- "total": 4200,
+ "total": 4201,
"complete": false,
"full_feed": "/changelog.json",
"entries": [
+ {
+ "date": "2026-10-25",
+ "type": "update",
+ "title": "Allowance pulls now require the signed real-funds agreement",
+ "summary": "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.",
+ "link": null,
+ "tags": [
+ "fix"
+ ]
+ },
{
"date": "2026-10-25",
"type": "update",
@@ -1549,17 +1559,6 @@
"improvement",
"docs"
]
- },
- {
- "date": "2026-10-13",
- "type": "update",
- "title": "Video to Motion: download any video's motion as a GLB, BVH, or FBX",
- "summary": "A new page for creators who want the animation file itself, not a composited video: upload a video, preview the captured motion on a stock avatar or any rigged GLB you drop in, trim the in and out points, and download a GLB (clip baked onto the previewed avatar), a BVH (the platform's own canonical-skeleton proportions, the standard shape to re-retarget in a DCC tool), or an FBX (server-side Blender conversion that preserves the rig). Reuses the production model-video2motion worker that already powers /motion-swap for capture; signed-in users can save the clip straight to an agent's animation library. New writer: src/animation-bvh-export.js, round-tripped through three.js's own BVHLoader in tests/animation-bvh-export.test.js. Cross-linked from /motion-swap, /animations, and /mocap-studio. Docs: /docs/video-to-motion.",
- "link": "/video-to-motion",
- "tags": [
- "feature",
- "docs"
- ]
}
]
}
diff --git a/public/changelog.json b/public/changelog.json
index 079540134..dd4a1baba 100644
--- a/public/changelog.json
+++ b/public/changelog.json
@@ -1,11 +1,21 @@
{
- "generated_at": "2026-10-25T11:57:17.211Z",
+ "generated_at": "2026-10-25T11:57:28.802Z",
"generated_by": "scripts/build-page-index.mjs from data/pages.json + data/changelog.json",
"site": {
"name": "three.ws",
"url": "https://three.ws"
},
"entries": [
+ {
+ "date": "2026-10-25",
+ "type": "update",
+ "title": "Allowance pulls now require the signed real-funds agreement",
+ "summary": "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.",
+ "link": null,
+ "tags": [
+ "fix"
+ ]
+ },
{
"date": "2026-10-25",
"type": "update",
diff --git a/public/changelog.xml b/public/changelog.xml
index da20e5633..87a5dc5bc 100644
--- a/public/changelog.xml
+++ b/public/changelog.xml
@@ -6,6 +6,14 @@
<atom:link href="https://three.ws/changelog.xml" rel="self" type="application/rss+xml"/>
<description>What's new on three.ws: features, improvements, and releases, newest first.</description>
<language>en</language>
+ <item>
+ <title>Allowance pulls now require the signed real-funds agreement</title>
+ <link>https://three.ws/changelog</link>
+ <guid isPermaLink="false">2026-10-25:Allowance pulls now require the signed real-funds agreement</guid>
+ <pubDate>Sun, 25 Oct 2026 12:00:00 GMT</pubDate>
+ <category>fix</category>
+ <description>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.</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.json
index d27a4ce9c..14c800398 100644
--- a/public/features.json
+++ b/public/features.json
@@ -1,5 +1,5 @@
{
- "generated_at": "2026-10-25T11:57:17.180Z",
+ "generated_at": "2026-10-25T11:57:28.772Z",
"generated_by": "scripts/build-page-index.mjs from data/pages.json",
"site": {
"name": "three.ws",