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.

fix(guards): make the four red audits tell the truth about the repo again

nirholasd1f62feace57
diff --git a/CLAUDE.md b/CLAUDE.md
index da182124f..f7bbdb424 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -305,7 +305,7 @@ The whole build + submit + purge in one command: `npm run deploy:gcp:full`.
- Frontend: vanilla JS modules + Vite (`npm run dev`, port 3000).
- 3D: Three.js with glTF/GLB.
- Backend touchpoints: serverless-style handlers in `api/`, workers in `workers/`.
-- **Production runs on Google Cloud Run, NOT Vercel** (migrated 2026-07-07 after Vercel disabled the deployment). One container ([server/index.mjs](server/index.mjs)) serves the static frontend, the vercel.json route table, and all `api/**` handlers; the crons (113 as of 2026-09-03, see vercel.json) run on Cloud Scheduler. `vercel.json` is a LIVE config file: `server/index.mjs` reads its `routes` array on boot (split at the `{handle:"filesystem"}` marker into pre- and post-filesystem phases), and `scripts/create-gcp-scheduler.mjs` reads its `crons` array to sync Cloud Scheduler jobs. The server itself never reads `crons`. Never delete `vercel.json` as a leftover. GCP builds/deploys must pin the `three-ws-build@` (build) and `three-ws@` (runtime) service accounts; the project's default compute SA was deleted. Deploys: see the "Deploy runbook" section above.
+- **Production runs on Google Cloud Run, NOT Vercel** (migrated 2026-07-07 after Vercel disabled the deployment). One container ([server/index.mjs](server/index.mjs)) serves the static frontend, the vercel.json route table, and all `api/**` handlers; the crons (114 as of 2026-09-03, see vercel.json) run on Cloud Scheduler. `vercel.json` is a LIVE config file: `server/index.mjs` reads its `routes` array on boot (split at the `{handle:"filesystem"}` marker into pre- and post-filesystem phases), and `scripts/create-gcp-scheduler.mjs` reads its `crons` array to sync Cloud Scheduler jobs. The server itself never reads `crons`. Never delete `vercel.json` as a leftover. GCP builds/deploys must pin the `three-ws-build@` (build) and `three-ws@` (runtime) service accounts; the project's default compute SA was deleted. Deploys: see the "Deploy runbook" section above.
- **Env-var trap:** `vercel env pull` returns EMPTY for secret-type vars. Never trust a Vercel env export as complete. Production env lives on the Cloud Run service (`gcloud run services describe/update three-ws-api --region us-central1`).
- Solana/agent SDKs in `sdk/`, `solana-agent-sdk/`, `agent-payments-sdk/`.
- Real APIs in use: Pump.fun feed, Solana RPC, OpenAI/Anthropic via worker proxies. Never mock these.
diff --git a/README.md b/README.md
index 07cd02a0e..e70b55078 100644
--- a/README.md
+++ b/README.md
@@ -9994,7 +9994,7 @@ The full OpenAPI 3.1 spec is available at `/openapi.json`. The key API surface i
Cron schedules are declared in `vercel.json` (still the live cron/route config the server reads) and executed in production by **Google Cloud Scheduler**, which calls each endpoint on its schedule. All cron endpoints are fail-closed — a missing auth token aborts with an error rather than silently skipping (see [Security Hardening](#security-hardening)).
-The crons in `vercel.json` (112 entries on 2026-09-02) are routed through a single dynamic handler at [`api/cron/[name].js`](api/cron/[name].js); the `name` segment selects the handler function. Scheduler jobs are provisioned from the `vercel.json` cron list via [scripts/create-gcp-scheduler.mjs](scripts/create-gcp-scheduler.mjs). The table below is a selection of the notable jobs, each schedule quoted verbatim from `vercel.json`; that file is the complete list.
+The crons in `vercel.json` (114 entries on 2026-09-03) are routed through a single dynamic handler at [`api/cron/[name].js`](api/cron/[name].js); the `name` segment selects the handler function. Scheduler jobs are provisioned from the `vercel.json` cron list via [scripts/create-gcp-scheduler.mjs](scripts/create-gcp-scheduler.mjs). The table below is a selection of the notable jobs, each schedule quoted verbatim from `vercel.json`; that file is the complete list.
| Schedule | Endpoint | Purpose |
| -------------------- | --------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------- |
diff --git a/STRUCTURE.md b/STRUCTURE.md
index 91ad28d55..cf1fd1077 100644
--- a/STRUCTURE.md
+++ b/STRUCTURE.md
@@ -47,7 +47,7 @@ bottom.
| Examples gallery | [pages/examples.html](pages/examples.html) `→ /examples`, curated snippets [public/examples.js](public/examples.js), generated index renderer [public/examples-index.js](public/examples-index.js), styles [public/examples.css](public/examples.css), hosted example tree [public/examples/](public/examples) built by [scripts/build-hosted-examples.mjs](scripts/build-hosted-examples.mjs) | Live | Two halves. The top is 17 copy-paste snippets that RUN on the page, grouped into four lanes (avatars and embeds, 3D models, agents, agent economy) behind a sticky jump nav and a text/tag filter that folds away lanes as they empty (a deep link always beats an active filter): each is a complete document loading the production CDN bundle into an iframe, so "Run" executes exactly the code shown, and the model/agent/economy lanes call the live CORS-open production APIs rather than illustrating them (free text→3D at `/api/v1/ai/text-to-3d`, free text→speech at `/api/v1/ai/tts` played through the new `speakAudio()` viseme path, `/api/3d/inspect`, the 112-clip `/animations/manifest.json`, `/api/forged`, the public no-auth MCP server at `/api/mcp-studio` for both `tools/list` and a live `look_at_model` render-and-critique, the 402 quote from `/api/x402/forge`, `/api/pump/launches`). The `agent-from-files` card loads a real manifest from `/examples/coach-leo/manifest.json`: `npm run build:examples` publishes [examples/coach-leo/](examples/coach-leo) and its wave skill into `public/examples/` with body/image URIs rewritten absolute, so the manifest resolves the same way off-site as it does here. The bottom is every example that ships in the repo, generated by [scripts/build-examples-index.mjs](scripts/build-examples-index.mjs) scanning every `examples/` directory into [data/examples.json](data/examples.json), mirrored to the served [public/examples.json](public/examples.json) by [scripts/mirror-examples-index.mjs](scripts/mirror-examples-index.mjs) (`npm run build:examples` runs all three). Because it is scanned, the page cannot advertise a deleted example or miss an added one; each card carries the files it contains and the command that runs it. Tests: [tests/examples-page.test.js](tests/examples-page.test.js), [tests/examples-index.test.js](tests/examples-index.test.js) |
| Cookbook (runnable recipes) | Index [pages/cookbook.html](pages/cookbook.html) `-> /cookbook`, recipe viewer [pages/recipe.html](pages/recipe.html) `-> /cookbook/<slug>`, manifest [public/cookbook-manifest.js](public/cookbook-manifest.js), styles [public/cookbook.css](public/cookbook.css), recipe prose [docs/cookbook/](docs/cookbook), runnable files [public/cookbook/recipes/](public/cookbook/recipes), notebook export [public/cookbook/self-correcting-3d/](public/cookbook/self-correcting-3d) | Live | The sibling of the Examples gallery, and deliberately a different thing: an example is a snippet you read on the page, a recipe is a file you download and run. Five recipes, each one executed against the live API before it was published: a standard-library text-to-3D CLI, a parallel asset-pack builder that emits a manifest plus a gallery, an MCP server that hands Claude Code or Cursor a 3D tool, a CI budget gate over [api/3d/inspect.js](api/3d/inspect.js), and the function-calling-plus-vision notebook also submitted to the OpenAI Cookbook. The manifest is the single source of truth for both surfaces; recipe prose is markdown under `docs/cookbook/` fetched by the viewer, so adding a recipe is a manifest entry plus a `.md` plus the file itself. Route order is load-bearing in both [vercel.json](vercel.json) and the dev middleware: the notebook's static export must be matched before the generic `/cookbook/<slug>` rule or the viewer shadows it. Docs: [public/cookbook/recipes/README.md](public/cookbook/recipes/README.md). Tests: [tests/cookbook.test.js](tests/cookbook.test.js) |
| Walkthroughs (interactive product tours from real frames) | Index [pages/walkthroughs.html](pages/walkthroughs.html) + [src/walkthroughs-index.js](src/walkthroughs-index.js) `→ /walkthroughs`, player [pages/walkthrough.html](pages/walkthrough.html) + [src/walkthrough.js](src/walkthrough.js) `→ /walkthroughs/<slug>` (routed in [vercel.json](vercel.json), mirrored by the Vite dev middleware in [vite.config.js](vite.config.js)), pure step geometry [src/walkthrough-geometry.js](src/walkthrough-geometry.js), generated manifest + screenshot sets [public/walkthroughs/](public/walkthroughs) captured by [scripts/capture-walkthroughs.mjs](scripts/capture-walkthroughs.mjs) | Live | Step-by-step guided tours (forge a 3D model, build an agent, embed an avatar, find an agent worth using) built from real frames captured on the live product: each step zooms and pans to the element it describes, cuts a spotlight around it, and anchors a callout, so it reads like a screen recording but is a handful of deep-linkable, keyboard-operable JPEGs that degrade to annotated stills under reduced motion. Index and player read the same generated manifest, so a walkthrough that did not capture cleanly cannot be advertised. Registered in [data/pages.json](data/pages.json). |
-| Cross-entity search | [pages/search.html](pages/search.html) `→ /search`, backend [api/search.js](api/search.js) + query layer [api/_lib/cross-search.js](api/_lib/cross-search.js) | Live | The one search across every creation type — avatars, on-chain/Solana agents, forged 3D models, worlds, and coins. Federates (not one SQL UNION — the stores are genuinely heterogeneous, two of five aren't even in the same database) five parallel queries, normalizes into one card shape, and ranks by recency plus real signals (follower count via `user_follows`, remix count, view count) — see the file header in `api/search.js` for the full unify-vs-federate writeup. Model results carry a working "Remix — $0.25" action against the existing paid rail ([api/x402/remix-asset.js](api/x402/remix-asset.js)), reused from [pages/creations.html](pages/creations.html) rather than re-derived. Coin search checks three.ws's own launch directory (`pump_agent_mints`) first, then falls back to market-wide pump.fun/Birdeye search for broader coverage (those external matches carry no verified timestamp or creator profile, and are ranked/labelled accordingly). Linked from the Discover nav menu. |
+| Cross-entity search | [pages/search.html](pages/search.html) `→ /search` + page module [src/search-page.js](src/search-page.js), backend [api/search.js](api/search.js) + query layer [api/_lib/cross-search.js](api/_lib/cross-search.js) | Live | The one search across every creation type: avatars, on-chain/Solana agents, forged 3D models, worlds, and coins. Federates (not one SQL UNION, because the stores are genuinely heterogeneous and two of five are not even in the same database) five parallel queries, normalizes into one card shape, and ranks by recency plus real signals (follower count via `user_follows`, remix count, view count); see the file header in `api/search.js` for the full unify-vs-federate writeup. Model results carry a working "Remix, $0.25" action against the existing paid rail ([api/x402/remix-asset.js](api/x402/remix-asset.js)), reused from [pages/creations.html](pages/creations.html) rather than re-derived. Coin search checks three.ws's own launch directory (`pump_agent_mints`) first, then falls back to market-wide pump.fun/Birdeye search for broader coverage (those external matches carry no verified timestamp or creator profile, and are ranked/labelled accordingly). The page reads `?q=` and `?type=` from the URL before it paints the filter row, so a shared scoped link shows the filter it is actually applying; a type whose source returned nothing for the current query is dimmed from the real `counts` in the response. The backend answering `{enabled:false}` (creation stores unreachable) renders its own "search is warming up" state with a retry and live browse links, never a false "nothing matched". Enter runs the query without waiting out the debounce and Escape clears it. Linked from the Discover nav menu. |
| Cross-surface rankings, streaks & badges | [pages/rankings.html](pages/rankings.html) `→ /rankings`, backend [api/leaderboard/unified.js](api/leaderboard/unified.js), streak/badge engine [api/_lib/streaks.js](api/_lib/streaks.js) (migration [api/_lib/migrations/20260712020000_leaderboard_streaks_badges.sql](api/_lib/migrations/20260712020000_leaderboard_streaks_badges.sql)), daily Top-10 badge sweep [api/cron/leaderboard-rollup.js](api/cron/leaderboard-rollup.js) | Live | Five real, queried leaderboard metrics — creations (forge models + worlds), remixes received, coin launches, followers, and walk distance (signed-in walkers, all-time) — ranked live with the viewer's own rank pinned even off-page. Every signed-in qualifying action (login, a finished forge model, a saved world, a `/walk` session) rolls a per-user daily streak in `user_streaks` via `recordDailyActivity()`, called from [api/_lib/auth.js](api/_lib/auth.js), [api/_lib/forge-store.js](api/_lib/forge-store.js), [api/_lib/diorama-store.js](api/_lib/diorama-store.js), and [api/walk/metrics.js](api/walk/metrics.js). Four real earned badges persist in `user_badges`: First Creation, Remixed (awarded in [api/x402/remix-asset.js](api/x402/remix-asset.js) when a remix lands on your creation), 7-Day Streak, and a daily-refreshed `top10_<metric>` per leaderboard. Streak + badges surface on the profile ([pages/profile.html](pages/profile.html)) and the Rankings page itself. Rejected metrics (documented in `api/leaderboard/unified.js`'s header): royalties earned in USD (the settlement record is a single overwritten JSONB column, not a cumulative ledger) and `/play` activity (no per-human-user session table exists). |
| create-agent (one command, one 3D character) | [packages/create-agent/](packages/create-agent) (client [src/forge.js](packages/create-agent/src/forge.js), scaffold [src/scaffold.js](packages/create-agent/src/scaffold.js), CLI [bin/create-agent.js](packages/create-agent/bin/create-agent.js)), server tools [api/_mcp-studio/tools.js](api/_mcp-studio/tools.js) | Live | `npm create @three-ws/agent "a friendly cartoon astronaut"` generates a textured figure, rigs it, downloads the GLB, and writes a folder with a working demo page and the embed snippet. No account and no API key: it rides the public, keyless JSON-RPC tools on [/api/mcp-studio](api/_mcp-studio) (`forge_avatar`, `forge_free`, `rig_mesh`) that the platform already exposes to MCP clients. A rigged character reliably outlives the endpoint's inline wait, so the client collects the returned poll handle and, when the job that finished was only the mesh, rigs it before reporting done: that is what the `stage` field on a pending result exists for. Progress is real elapsed time, never an invented bar. Docs [docs/create-agent.md](docs/create-agent.md). Tests: [tests/create-agent.test.js](tests/create-agent.test.js) |
| Glance (agent cards for home screens, READMEs and chat) | Page [public/glance/index.html](public/glance/index.html) `-> /glance` (+ [glance-page.js](public/glance/glance-page.js), [glance.css](public/glance/glance.css)), hosted element [public/glance/element.js](public/glance/element.js), endpoints [api/glance/card.js](api/glance/card.js) / [api/glance/mine.js](api/glance/mine.js) / [api/glance/token.js](api/glance/token.js) / [api/glance/template.js](api/glance/template.js), model [api/_lib/glance-card.js](api/_lib/glance-card.js), SVG [api/_lib/glance-svg.js](api/_lib/glance-svg.js), PNG [api/_lib/glance-png.js](api/_lib/glance-png.js), widget tokens [api/_lib/glance-tokens.js](api/_lib/glance-tokens.js) (`glance_widget_tokens`), Adaptive Card [api/_lib/glance-adaptive.js](api/_lib/glance-adaptive.js), Windows widget worker [public/glance-sw.js](public/glance-sw.js) (imported by the VitePWA service worker, manifest `widgets` member in [vite.config.js](vite.config.js)), Android home screen widget [solana-mobile/android-overlay/](solana-mobile/android-overlay/README.md) (applied by [solana-mobile/scripts/apply-overlay.mjs](solana-mobile/scripts/apply-overlay.mjs) inside `build-apk.sh`), npm client [packages/agent-glance/](packages/agent-glance) | Live | One agent reduced to what fits in an OS widget slot: name, one live number (actions in the last 24h), and a link back. The same model renders five ways from one endpoint (JSON, SVG, PNG, Adaptive Card, and the `<agent-glance>` element), which is what keeps a new surface a rendering job rather than a data job. Windows 11 installs the widget straight from the PWA manifest (no store submission). Android ships it in the app (1.1+): a WorkManager-refreshed `AppWidgetProvider` that fetches the PNG with a revocable per-account widget token minted on `/glance`, keeps the last card offline, and opens the agent on tap. macOS and iOS (WidgetKit) consume the same PNG and token next. Deliberately not the 3D embed: no widget host on any of these platforms can run WebGL, so the body stays at [/widgets](public/widgets-gallery/index.html) and the status lives here. Private avatars never leak (the thumbnail is attached only for a public or unlisted avatar; everything else draws a generated monogram). Spec [specs/GLANCE_CARD.md](specs/GLANCE_CARD.md), docs [docs/glance.md](docs/glance.md), [docs/native-widgets.md](docs/native-widgets.md). Tests: [tests/glance-card.test.js](tests/glance-card.test.js), [tests/glance-png.test.js](tests/glance-png.test.js), [tests/glance-tokens.test.js](tests/glance-tokens.test.js), [tests/glance-sw.test.js](tests/glance-sw.test.js), [tests/agent-glance-sdk.test.js](tests/agent-glance-sdk.test.js) |
@@ -60,6 +60,7 @@ bottom.
| Notification bell & preferences | Event vocabulary [api/_lib/feed.js](api/_lib/feed.js) (`USER_EVENT_TYPES` → `publishUserEvent()` → `user_notifications`), endpoints [api/notifications/](api/notifications), preference matrix [api/_lib/notify-prefs.js](api/_lib/notify-prefs.js), bell client [src/notifications.js](src/notifications.js), avatar announcements [src/notification-herald.js](src/notification-herald.js), settings panel [src/dashboard-next/pages/settings.js](src/dashboard-next/pages/settings.js) | Live | In-app inbox covering remixes ([api/x402/remix-asset.js](api/x402/remix-asset.js)), DMs ([api/friends/messages.js](api/friends/messages.js)), coin bonding-curve graduations (pump cron in [api/cron/[name].js](api/cron/%5Bname%5D.js)), follows, sales, purchases, IRL, market, and account events. Preferences are a category × channel matrix (`in_app` always on; push/email/telegram/avatar are per-category opt-outs) edited from `/dashboard/settings`. **The `avatar` channel delivers in person:** for a fresh, unread notification in an opted-in category the corner companion walks on screen, gestures, and says the line with a link straight to it, summoning itself for that one message and retreating if it was off ([walk-sdk](walk-sdk) `control.announce`). Rules (15-minute freshness, once per browser, two per batch, visible tab only, device-level mute) live in [src/notification-herald.js](src/notification-herald.js). Docs: [docs/notifications.md](docs/notifications.md), [docs/social-layer.md](docs/social-layer.md). Tests: [tests/notification-herald.test.js](tests/notification-herald.test.js), [tests/notify-prefs.test.js](tests/notify-prefs.test.js) |
| Personal companion (`/companion`) | Page [pages/companion.html](pages/companion.html) `→ /companion` + [src/companion/](src/companion) (page, source cards, voice), API [api/companion/](api/companion) (settings, sources, contacts, events, `ingest`, `stream`, `poll`), engine [api/_lib/companion/](api/_lib/companion) (store, encrypted BYOK configs, triage, lanes for Telegram / iCal / IMAP), cron [api/cron/companion-poll.js](api/cron/companion-poll.js), migration [api/_lib/migrations/20260828140000_companion_harness.sql](api/_lib/migrations/20260828140000_companion_harness.sql) | Live | Turns a person's own inbox, chats, calendar and phone into deliveries a 3D character makes **in person**. BYOK per source (a Telegram bot the user made, a private iCal URL, IMAP with an app password) plus a universal bridge token anything can POST to. Every message is scored 0-100 by the shared deterministic rules ([@three-ws/companion/triage](packages/companion-sdk/src/triage-rules.js), the same module the CLI runs locally) and optionally refined by the user's own Anthropic key; above their threshold and outside quiet hours it is delivered through `companion_delivery` notifications, so the bell, Web Push, and the avatar channel all carry it. A contact's message is spoken by **that contact's avatar and voice** (`control.announce({ avatar })` in [walk-sdk](walk-sdk)). A delivery whose lane can carry an answer (Telegram, through the user's own bot) offers a reply box in place, and the reply is stored with the message. Live SSE at `/api/companion/stream` feeds the desktop app and any third-party body. Docs: [docs/companion.md](docs/companion.md). Tests: [tests/companion-triage.test.js](tests/companion-triage.test.js), [tests/companion-calendar.test.js](tests/companion-calendar.test.js), [packages/companion-sdk/tests/](packages/companion-sdk/tests) |
| three.ws Drive: the agent in the car (`/drive`) | Page [pages/drive.html](pages/drive.html) `→ /drive` + [src/drive/](src/drive) (page controller, surface presets, native bridge, local commands, motion gate); native CarPlay scene [ios/native/App/App/CarPlaySceneDelegate.swift](ios/native/App/App/CarPlaySceneDelegate.swift) + [DriveLink.swift](ios/native/App/App/DriveLink.swift) | Live (web) / built, entitlement pending (CarPlay) | The existing talk loop (`/api/asr` → `/api/chat` → `/api/tts` → lipsync on a real rigged avatar) rebuilt for a car panel: one glanceable two-line reply instead of a transcript, exactly four controls, night by default, and a keyboard that hides itself while the wheels turn. Speed comes from `navigator.geolocation`'s real ground speed, so moving above walking pace locks text entry back and a sustained stop is what unlocks it. Control phrases ("repeat that", "stop talking", "louder", "night mode") are answered locally with no round trip, matched against the whole utterance so "stop at the next charger" still reaches the agent. Hands free ends a turn from the real captured mic level on the Riva lane. **CarPlay is a second scene, not a second product:** Apple's voice-based conversational category (iOS 26.4) grants templates and an audio session and no drawing surface, so the car screen renders four rows plus `CPVoiceControlTemplate` while this page runs on the phone, joined by the versioned `threeWsDrive` WebKit channel. Docs: [docs/carplay.md](docs/carplay.md), [ios/docs/CARPLAY.md](ios/docs/CARPLAY.md). Tests: [tests/drive-surface.test.js](tests/drive-surface.test.js) |
+| Hands-free voice for the house (`/voice/home`) | Loop [src/voice/home-voice.js](src/voice/home-voice.js), VAD [src/voice/vad.js](src/voice/vad.js), wake word [src/voice/wake-word.js](src/voice/wake-word.js) + catalog [src/voice/wake-words.js](src/voice/wake-words.js), panel [src/voice/home-voice-ui.js](src/voice/home-voice-ui.js) + [public/home-voice.css](public/home-voice.css); page [pages/voice-home.html](pages/voice-home.html) `→ /voice/home` + [src/voice-home.js](src/voice-home.js); models committed under [public/models/voice/wake-word/](public/models/voice/wake-word) with the silero + onnxruntime runtime staged by [scripts/copy-voice-models.mjs](scripts/copy-voice-models.mjs) | Live | The browser half of three.ws Home: mic → silero VAD → openWakeWord → `/api/asr` → `/api/chat` (home tools) → `/api/tts/speak` → lipsync, with one `getUserMedia` shared by all three consumers. Wake-word matching runs entirely in the tab on committed openWakeWord v0.5.1 weights served from three.ws, so nothing is uploaded until after the wake word; nothing about detection is even downloaded until the user opts in. Barge-in cuts playback ~110 ms after the user starts talking, and a playback-aware guard means the agent saying its own wake word (score 0.99) wakes it zero times. A pause is not an ending: a closed segment stays open 450 ms so "Hey Jarvis… turn the kitchen light off" is one command. Guarded actions are spoken in full, shown on screen by name and entity id, and satisfied only by the token `confirm` redeemed at `POST /api/home/:id/confirm`; a general "yeah" is refused by name and a screenless surface is refused outright. Twelve designed states, mute that ends the track rather than hiding a dot, and every leg timed live. Docs: [docs/home-voice.md](docs/home-voice.md). Proof: [scripts/check-home-voice.mjs](scripts/check-home-voice.mjs) (34 assertions in a real Chromium). Tests: [tests/home-voice.test.js](tests/home-voice.test.js) |
| Knock: a priced door to a person (`/knock`) | Hub [pages/knock.html](pages/knock.html) `→ /knock` + [src/knock/page.js](src/knock/page.js), public door [pages/knock-door.html](pages/knock-door.html) `→ /knock/<handle>` + [src/knock/door.js](src/knock/door.js), API [api/knock/](api/knock) (door, directory, send, reply, settings, inbox), paid lane [api/x402/knock.js](api/x402/knock.js), engine [api/_lib/knock/](api/_lib/knock) (pure policy, store, delivery, receipt tokens), migration [api/_lib/migrations/20260828210000_knock_doors.sql](api/_lib/migrations/20260828210000_knock_doors.sql), SDK + CLI [packages/knock-sdk/](packages/knock-sdk) (`@three-ws/knock`), MCP [packages/knock-mcp/](packages/knock-mcp) (`@three-ws/knock-mcp`) | Live | Every account can publish a door at `/knock/<username>` and set what one message from a stranger costs. Paying it buys exactly one message through, and the delivery is **in person**: the knock becomes a `companion_events` row whose importance is derived from the amount paid, so the recipient's corner avatar walks on wherever they are and says who is at the door and what they paid. **The USDC settles straight to the recipient** (`payTo` on the 402 challenge is their own address, and a priced door cannot be opened without one), so there is no platform wallet in the path and no cut. Solana leads; Base is advertised only when the owner sets an address for it. **Every refusal happens before the 402** (shut door, daily cap, block list, length limits) and again before settlement, so a knock that was never going to land is never a knock somebody paid for. Only the subject line is spoken; an untrusted body never uses the recipient's avatar as a speaker. The sender gets a derived HMAC receipt URL and reads the reply through it with no account, which is why answering someone never hands out an address. Free doors take a plain POST on a tight per-IP bucket. Spec: [specs/KNOCK_PROTOCOL.md](specs/KNOCK_PROTOCOL.md). Docs: [docs/knock.md](docs/knock.md). Tests: [tests/knock-policy.test.js](tests/knock-policy.test.js), [packages/knock-sdk/test/](packages/knock-sdk/test), [packages/knock-mcp/test/](packages/knock-mcp/test) |
| Visitor feedback loop | Recorder [@three-ws/witness](packages/witness), capture + panel [src/feedback-companion.js](src/feedback-companion.js) (mounted by [src/walk-companion.js](src/walk-companion.js)), intake [api/feedback/report.js](api/feedback/report.js), queue API [api/feedback/index.js](api/feedback/index.js), scoring [api/_lib/feedback/triage.js](api/_lib/feedback/triage.js), store [api/_lib/feedback/store.js](api/_lib/feedback/store.js), cron [api/cron/feedback-triage.js](api/cron/feedback-triage.js), review page [pages/feedback.html](pages/feedback.html) `→ /feedback` + [src/feedback-page.js](src/feedback-page.js) | Live | The return channel on the corner companion: the visitor tells the avatar what broke and the report carries the route, build SHA, viewport, and the last console errors and failed requests the browser captured, so a vague sentence lands as an actionable row. The companion offers proactively at the one moment worth asking (right after the page actually threw), once per route per session, never in a background tab. **Feedback is data, never an instruction:** the model that reads untrusted visitor text writes six scalars to that report's own row and has no path to the repo, a deploy, or any other write; the admin-only `/feedback` queue groups reports into one row per problem and a person decides. **A report arrives as a runnable failing test:** the recorded session compiles into a Playwright spec asserting the failure is GONE (red until fixed, green after), reachable from the queue's Copy test button, `GET /api/feedback/repro`, `npm run feedback:repro`, and the `get_feedback_repro` MCP tool. Docs: [docs/feedback.md](docs/feedback.md), [docs/witness.md](docs/witness.md). Tests: [tests/feedback-triage.test.js](tests/feedback-triage.test.js) |
| Session-to-test recorder | [packages/witness/](packages/witness) `→ @three-ws/witness`: recorder [recorder.js](packages/witness/src/recorder.js), selector synthesis [selector.js](packages/witness/src/selector.js), capture-time privacy [redact.js](packages/witness/src/redact.js), spec compiler [compile.js](packages/witness/src/compile.js); compiled repros land in [tests/repros/](tests/repros) with [their own Playwright config](tests/repros/playwright.config.mjs) | Published as `@three-ws/witness` (Apache-2.0, zero deps) | Turns a real user session into a runnable failing test. Records INTENT (about 2 KB) rather than DOM mutations (megabytes), so it can be always-on, which is the point: the trace already exists when somebody decides to complain. Every element gets the strongest handle that is unique in the live document (test id > id > aria-label > role+name > text > name > placeholder > class > structural path), framework-generated ids and utility classes refused, and each trace carries a replay confidence equal to its WEAKEST link. The compiled spec asserts the failure is gone, never that it happened, so it locks in the fix rather than the bug; a session with no machine-visible failure emits `test.fail()` and says which assertion a human must add rather than faking green. Privacy is enforced at capture: typed values are never held (only a length and a shape), password/hidden/email/tel/date inputs and `data-witness="off"` subtrees record nothing, URLs lose their credentials before storage. Docs: [docs/witness.md](docs/witness.md). Tests: [packages/witness/test/](packages/witness/test) (36, `npm run test:witness`) |
@@ -148,13 +149,14 @@ bottom.
| Object Library | [pages/objects.html](pages/objects.html) + [src/objects-library.js](src/objects-library.js) → `/objects`, API [api/objects/library.js](api/objects/library.js) | Live at `/objects` | Hundreds of CC0 (public-domain) 3D props from Poly Haven (packed to GLB on R2, `objects/polyhaven/`). Pipeline: [scripts/fetch-polyhaven-objects.mjs](scripts/fetch-polyhaven-objects.mjs) (glTF→GLB via @gltf-transform) → [scripts/render-glb-thumbnails.mjs](scripts/render-glb-thumbnails.mjs) → [scripts/build-object-library.mjs](scripts/build-object-library.mjs) publishes `objects/library/manifest.json`. Same R2-manifest pattern as the Character/animation libraries (no DB). Cards preview in the 3D viewer (`/app#model=`), place into AR Studio (`/ar/studio?src=`), and download the GLB directly (CC0). AR Studio's tray also has an Objects tab over the same manifest. |
| Agent-Forged Gallery | [pages/forged.html](pages/forged.html) + [src/forged-gallery.js](src/forged-gallery.js) → `/forged`, API [api/forged.js](api/forged.js), writer [api/_lib/x402/pipelines/forge-content.js](api/_lib/x402/pipelines/forge-content.js) | Live at `/forged` | 3D props BOUGHT by the autonomous x402 agents with real USDC: the hourly forge-content pipeline pays `/api/x402/forge` (draft tier), the generated GLB lands in `forge_autonomous_props` with payment provenance (payer wallet, price, Solana settlement signature), and `/forged` renders each prop with its on-chain receipt linked to Solscan. Honest feed: no synthetic entries; before the first paid generation the page shows its designed empty state. Category chips built from the eight families in [api/_lib/x402/pipelines/forge-catalog.js](api/_lib/x402/pipelines/forge-catalog.js) (club-decor, ar-object, diorama-set, avatar-item, vehicle, container, furniture, terrain), prompt search, newest/priciest/most-novel sorts. |
| Motion Swap (avatar body-swap in video) | [pages/motion-swap.html](pages/motion-swap.html) `→ /motion-swap` + [src/motion-swap.js](src/motion-swap.js), API [api/motion-swap.js](api/motion-swap.js), worker [workers/model-video2motion/](workers/model-video2motion) | Live | Upload a video of one person, get it back with a 3D avatar performing their motion. The worker (CPU Cloud Run, MediaPipe pose + hands + multiclass person segmentation, all Apache-2.0) tracks 33 body world landmarks plus 21 per hand each frame, solves them onto the canonical Wolf3D skeleton, body and all 30 finger bones, with an in-house bend-plane IK solver ([pose_solver.py](workers/model-video2motion/pose_solver.py), pure NumPy, unit-tested), and emits a standard `AnimationClip.toJSON()` + person-mask video + per-frame screen anchors. The browser composites in one WebGL scene: footage on a shader quad with the subject pixelated under the mask, avatar retargeted via [src/animation-retarget.js](src/animation-retarget.js) and pinned to the subject's anchor each frame, MediaRecorder export with original audio. Provider mode `video2motion` (`GCP_VIDEO2MOTION_URL`) in [api/_providers/gcp.js](api/_providers/gcp.js). Docs: [docs/motion-swap.md](docs/motion-swap.md). Tests: [test_pose_solver.py](workers/model-video2motion/test_pose_solver.py) (solver) and [test_service.py](workers/model-video2motion/test_service.py) (HTTP contract, ffmpeg normalize/mask encode, SSRF guard, live MediaPipe pass). |
-| Smart home (`/smart-home`) | Page [pages/smart-home.html](pages/smart-home.html) `→ /smart-home` and `/smart-home/:id` + [src/home/](src/home) (connect, manage, scene-model, scene-render, scene-fallback, satellite, satellite-link, pcm-player, plan, api). Store [api/_lib/home/store.js](api/_lib/home/store.js), runtime + backpressure [runtime.js](api/_lib/home/runtime.js) + [admission.js](api/_lib/home/admission.js), gate + tools [tools.js](api/_lib/home/tools.js) + [confirm.js](api/_lib/home/confirm.js), roster [members.js](api/_lib/home/members.js), privacy [privacy.js](api/_lib/home/privacy.js), plans + quotas [entitlements.js](api/_lib/home/entitlements.js) + [usage.js](api/_lib/home/usage.js), SSRF pin [api/_lib/home-url-guard.js](api/_lib/home-url-guard.js). HTTP [api/home/](api/home) (index, [id], [id]/call, [id]/activate, [id]/stream, [id]/grants, [id]/members, [id]/confirm, invites/[token], pair, pair/redeem, privacy, plan). Client [packages/home-bridge/](packages/home-bridge/README.md), MCP server [packages/home-mcp/](packages/home-mcp/README.md), hosted MCP tools [api/_mcp/tools/home.js](api/_mcp/tools/home.js). Dial-out for LAN-only houses [services/home-relay/](services/home-relay/README.md) + [home-assistant-integration/](home-assistant-integration) (HACS). Voice [services/home-satellite/](services/home-satellite/README.md) (Wyoming). Harness [scripts/home-test-instance.mjs](scripts/home-test-instance.mjs). Migrations `api/_lib/migrations/*_home_*.sql` | Live | The agent past the screen and into the building. **Zero device code, ever:** Home Assistant owns Zigbee, Z-Wave, Matter, Thread, BLE and 1,500 integrations, and three.ws is the layer in between: a connection record with the token encrypted at rest, a pooled per-home WebSocket, a room graph the 3D scene renders live, intent resolved to the household's own scenes, and one gate in front of everything. **The gate is the product decision:** reads are free, moves toward safety (lock, close, arm) run immediately and never prompt, and moves that OPEN the house (unlock, open a door/gate/garage, disarm) never run from a model call at all. They mint a pending confirmation a signed-in person redeems at `POST /api/home/:id/confirm`, which refuses every bearer principal including one holding `home:act`. It exists because Home Assistant's own `intent__HassTurnOff` is documented as performing an **unlock** on a lock, verified live. Entity and area names are untrusted input travelling in `structuredContent`, never interpolated into prose. Three reachability answers, all shipped: a remote https URL, a browser or MCP server inside the network, and the HACS integration that dials out so no Home Assistant credential ever leaves the house. Docs: [docs/smart-home.md](docs/smart-home.md), [docs/tutorials/connect-your-home.md](docs/tutorials/connect-your-home.md), [docs/home-households.md](docs/home-households.md), [docs/home-privacy.md](docs/home-privacy.md), [docs/home-plans.md](docs/home-plans.md). Tests: `tests/home-*.test.js`, [tests/e2e/home-connect.spec.js](tests/e2e/home-connect.spec.js), [packages/home-bridge/tests/](packages/home-bridge/tests), [packages/home-mcp/test/](packages/home-mcp/test) |
+| Smart home (`/smart-home`) | Page [pages/smart-home.html](pages/smart-home.html) `→ /smart-home` and `/smart-home/:id` + [src/home/](src/home) (connect, manage, scene-model, scene-render, scene-fallback, satellite, satellite-link, pcm-player, plan, api). Store [api/_lib/home/store.js](api/_lib/home/store.js), runtime + backpressure [runtime.js](api/_lib/home/runtime.js) + [admission.js](api/_lib/home/admission.js), gate + tools [tools.js](api/_lib/home/tools.js) + [confirm.js](api/_lib/home/confirm.js), roster [members.js](api/_lib/home/members.js), privacy [privacy.js](api/_lib/home/privacy.js), plans + quotas [entitlements.js](api/_lib/home/entitlements.js) + [usage.js](api/_lib/home/usage.js), SSRF pin [api/_lib/home-url-guard.js](api/_lib/home-url-guard.js). HTTP [api/home/](api/home) (index, [id], [id]/call, [id]/activate, [id]/stream, [id]/grants, [id]/members, [id]/confirm, invites/[token], pair, pair/redeem, privacy, plan). Client [packages/home-bridge/](packages/home-bridge/README.md), MCP server [packages/home-mcp/](packages/home-mcp/README.md), hosted MCP tools [api/_mcp/tools/home.js](api/_mcp/tools/home.js). Dial-out for LAN-only houses [services/home-relay/](services/home-relay/README.md) + [home-assistant-integration/](home-assistant-integration) (HACS). Voice [services/home-satellite/](services/home-satellite/README.md) (Wyoming). Harness [scripts/home-test-instance.mjs](scripts/home-test-instance.mjs), load fleet + envelope + chaos [scripts/home-fleet.mjs](scripts/home-fleet.mjs) / [scripts/home-load.mjs](scripts/home-load.mjs) / [scripts/home-chaos.mjs](scripts/home-chaos.mjs) (`npm run home:fleet`, `home:load`, `home:chaos`). Migrations `api/_lib/migrations/*_home_*.sql` | Live | The agent past the screen and into the building. **Zero device code, ever:** Home Assistant owns Zigbee, Z-Wave, Matter, Thread, BLE and 1,500 integrations, and three.ws is the layer in between: a connection record with the token encrypted at rest, a pooled per-home WebSocket, a room graph the 3D scene renders live, intent resolved to the household's own scenes, and one gate in front of everything. **The gate is the product decision:** reads are free, moves toward safety (lock, close, arm) run immediately and never prompt, and moves that OPEN the house (unlock, open a door/gate/garage, disarm) never run from a model call at all. They mint a pending confirmation a signed-in person redeems at `POST /api/home/:id/confirm`, which refuses every bearer principal including one holding `home:act`. It exists because Home Assistant's own `intent__HassTurnOff` is documented as performing an **unlock** on a lock, verified live. Entity and area names are untrusted input travelling in `structuredContent`, never interpolated into prose. Three reachability answers, all shipped: a remote https URL, a browser or MCP server inside the network, and the HACS integration that dials out so no Home Assistant credential ever leaves the house. Docs: [docs/smart-home.md](docs/smart-home.md), [docs/tutorials/connect-your-home.md](docs/tutorials/connect-your-home.md), [docs/home-households.md](docs/home-households.md), [docs/home-privacy.md](docs/home-privacy.md), [docs/home-plans.md](docs/home-plans.md), [docs/ops/home-operations.md](docs/ops/home-operations.md) (SLOs, the alerts, the measured scale envelope, the backpressure ladder, the seven chaos scenarios and the Cloud Run sizing). Evidence: [tasks/home/](tasks/home). Tests: `tests/home-*.test.js`, [tests/e2e/home-connect.spec.js](tests/e2e/home-connect.spec.js), [packages/home-bridge/tests/](packages/home-bridge/tests), [packages/home-mcp/tests/](packages/home-mcp/tests) |
| Sign Language (feature home) | [pages/sign-language.html](pages/sign-language.html) `→ /sign-language` + [src/sign-language-page.js](src/sign-language-page.js) | Live | The front door for signing avatars: a live avatar signing on arrival (PoseStage + [src/sign-speech.js](src/sign-speech.js) SignSpeaker, portrait-framed), an input that signs or spells anything you type (reporting which words were which), a playable vocabulary of every word with a real sign, and an embedded webcam sign-recognition demo. Controls for signing speed, left- vs right-handed signing, and which avatar signs: [src/sign-avatars.js](src/sign-avatars.js) owns the shared rig list, the one preference block every signing surface reads, and the Avatar pill group whose third pill opens the avatar gallery, so any avatar you own (or any public one) signs with the same vocabulary; a rig with no usable skeleton is rejected with a named message and the working rig is remounted. Verified in a real browser by `npm run verify:sign-avatar` ([scripts/verify-sign-avatar.mjs](scripts/verify-sign-avatar.mjs)). Engines: [src/sign-rig.js](src/sign-rig.js) (skeleton measured from the bind pose → forward kinematics, two-bone arm IK, and hand geometry, so a sign is authored as a place in signing space or as CONTACT, "fingertips on the palm", never as joint angles), [src/sign-handshapes.js](src/sign-handshapes.js) (A, Z, 0, 9, and the named shapes), [src/sign-clip.js](src/sign-clip.js) (resting signer, phase poser, non-manual face markers, eased timeline → clip JSON), [src/sign-dictionary.js](src/sign-dictionary.js) (the lexical vocabulary, one- and two-handed), [src/fingerspelling.js](src/fingerspelling.js) (the manual alphabet), [src/sign-speech.js](src/sign-speech.js) (text→one signing clip: hands rise once and lower once, signs where they exist and spelling for the rest), [src/sign-input.js](src/sign-input.js) (browser Holistic landmarks → text). Face markers ride a morph-target lane through [src/animation-retarget.js](src/animation-retarget.js), re-pointed at whichever meshes the target avatar owns. Tools: `npm run sign:sheet` (contact sheet of every sign, [scripts/sign-contact-sheet.mjs](scripts/sign-contact-sheet.mjs)), `npm run build:sign-goldens` (positional snapshot). Docs: [docs/sign-language.md](docs/sign-language.md). Tests: `tests/{sign-rig,sign-dictionary,sign-linguistics,sign-goldens,fingerspelling,sign-speech,sign-input}.test.js`. |
| ASL alphabet (learn + practice) | [pages/asl-alphabet.html](pages/asl-alphabet.html) `→ /asl-alphabet` + [src/asl-alphabet-page.js](src/asl-alphabet-page.js), letter notes [src/asl-alphabet-data.js](src/asl-alphabet-data.js) | Live | The manual alphabet as a reference you can turn around: every letter A-Z and digit 0-9 formed on a live portrait-framed rig ([src/fingerspelling.js](src/fingerspelling.js) via PoseStage), each with a written handshape description and the letters it is confused with (F/9, M/N, K/V, G/Q). A single letter holds its final frame (`playOnce({ settleTo: null })`) so it can be orbited; a word settles like a signer finishing. Typing any letter key signs it. Spelling a word lights each key in step with the hand, driven by the `marks` schedule the clip builder emits rather than a parallel timer. A practice drill spells a random letter or word and checks what you type, keeping a streak in localStorage. Shares speed / dominant-hand / avatar preferences with [/sign-language](pages/sign-language.html) under one key via [src/sign-avatars.js](src/sign-avatars.js), including a custom avatar picked from the gallery on either page. Deep links `?letter=W`, `?spell=HELLO`. Docs: [docs/sign-language.md](docs/sign-language.md). |
| Sign Mirror (camera-graded handshape practice) | [pages/sign-mirror.html](pages/sign-mirror.html) `→ /sign-mirror` + [src/sign-mirror-page.js](src/sign-mirror-page.js), grader [src/sign-grader.js](src/sign-grader.js), reference hand [src/sign-hand-model.js](src/sign-hand-model.js) | Live | The practice half of the signing loop: the avatar forms the target letter, MediaPipe's hand landmarker watches the learner's hand in-tab, and the grader scores the handshape live, finger by finger, naming the finger that is off. Avatar pose, target diagram, and grading all read the same handshape spec ([src/sign-handshapes.js](src/sign-handshapes.js)) so taught and graded can never drift. The whole practice loop is on-device: no frame, landmark, or score is ever uploaded. Course rail orders the alphabet easiest-first with localStorage progress; shared sign prefs (hand, avatar) carry over from `/sign-language` and `/asl-alphabet`. Tests: [tests/sign-grader.test.js](tests/sign-grader.test.js) |
| ASL recognition (webcam signing → text) | worker [workers/model-asl-recognition/](workers/model-asl-recognition), API [api/asl-recognition.js](api/asl-recognition.js) (`GCP_ASL_RECOGNITION_URL`) | Live | The reverse direction of [sign speech](docs/sign-language.md): the browser extracts MediaPipe landmarks from the webcam (video never leaves the device) and the worker transcribes continuous ASL fingerspelling to text on CPU via LiteRT, with a decode-confidence score and an LLM cleanup pass on the API. Model: Kaggle 2023 ASLFR 1st-place (Apache-2.0 code + weights, FSboard CC BY 4.0 corpus, the license-clean chain most ASL models lack). Cloud Run gen2 + `patchelf --clear-execstack` on the LiteRT .so. Next: word-level signs (PopSign retrain). Tests: [test_decode.py](workers/model-asl-recognition/test_decode.py) (schema + decode, no weights) and [test_model_smoke.py](workers/model-asl-recognition/test_model_smoke.py) (real weights end to end, run inside the built image). |
| Smart home: the connect flow and household management | Page [pages/smart-home.html](pages/smart-home.html) `-> /smart-home` + controller [src/home/connect.js](src/home/connect.js), manage view [src/home/manage.js](src/home/manage.js), styles [src/home/home.css](src/home/home.css). Consumes [api/home/index.js](api/home/index.js) (`GET`/`POST /api/home`), [api/home/[id].js](api/home/[id].js), `/api/home/:id/grants` and `/api/home/:id/log`. Reachability rules shared with the server through the [@three-ws/home-bridge](packages/home-bridge) `./url` subpath export | Live | The front door of the Home lane: how a stranger gets from "I have a Home Assistant somewhere" to "my agent is connected", and every way that goes wrong. Twelve designed states rather than a happy path plus an error toast: signed out, empty, inline validation, the private-host refusal, verifying, connected, a rejected token, unreachable, degraded, disconnected, many homes, and the plan ceiling. Two rules hold the surface together. **The token goes to the server once and never comes back**: the field is `type=password` with a reveal toggle, it is never written to storage, never put in a URL, never logged and never echoed by the API, and it is gone from the DOM the moment a connect succeeds. **Reachability is decided in the browser, before the network**: a `192.168.x.x` or `.local` address is refused with zero network calls using the same `normalizeBaseUrl`/`isPrivateHost` the server validates with, so the two can never disagree and nobody waits out a timeout to be told something we knew at the first keystroke. Every string that came from a house (a label, an entity id, an area name) is rendered as `textContent`, because those are attacker-influenceable and there is a physical actuator on the other end. Docs: [docs/smart-home.md](docs/smart-home.md). Tests: [tests/e2e/home-connect.spec.js](tests/e2e/home-connect.spec.js) |
| Smart home: plans, entitlements and quotas (`/smart-home/plan`) | Page [pages/smart-home-plan.html](pages/smart-home-plan.html) `-> /smart-home/plan` + controller [src/home/plan.js](src/home/plan.js), styles [src/home/plan.css](src/home/plan.css). Resolver [api/_lib/home/entitlements.js](api/_lib/home/entitlements.js), counters [api/_lib/home/usage.js](api/_lib/home/usage.js), endpoint [api/home/plan.js](api/home/plan.js). Enforced at [api/home/index.js](api/home/index.js) (acquisition), [api/home/[id]/stream.js](api/home/[id]/stream.js) (streams), [api/home/[id]/members.js](api/home/[id]/members.js) (seats), [api/home/[id]/call.js](api/home/[id]/call.js) (paused homes), [api/_lib/home/privacy.js](api/_lib/home/privacy.js) (retention ceiling). Cost measurement [scripts/measure-home-entitlement-cost.mjs](scripts/measure-home-entitlement-cost.mjs). Migration `api/_lib/migrations/20260903160000_home_plan_overrides.sql` | Live | What a plan covers for connected houses, and the two things no plan may ever refuse. **A limit never blocks a safety action:** over quota, downgraded or paused, locking a door, closing a garage or valve and arming an alarm always execute, checked before any counter is read and classified from the domain and service alone so the exemption never depends on a healthy socket. **Nothing about the gate is sold:** confirmations, the action log's integrity and every role safety property are on every tier and there is deliberately no dimension for any of them. Seven metered dimensions (homes, seats, streams, voice minutes, agent turns, log retention, relay connections), each carrying the measured cost that justifies it. **No fourth entitlement system:** limits resolve from `account-tier.js` badges merged by MAX (so holding $THREE never costs a Pro their Pro limits) and are scaled by the `three-tier.js` holder multiplier, never by thresholds of our own. **One counter:** an agent turn is the same priced `usage_events` chat row an invoice reads, tagged with `home_id`, not a second tally that could disagree. **A downgrade pauses, it never disconnects:** excess homes get `deactivated_at` with a written reason, the credential and the action log survive, `revoked_at` stays null, and the user swaps which houses are live. Enterprise limits are a `home_plan_overrides` row with the reason on it, not a tier. Every number is env-overridable (`HOME_LIMIT_<TIER>_<DIMENSION>`), so applying an owner-approved price is a config change. Docs: [docs/home-plans.md](docs/home-plans.md). Tests: [tests/home-entitlements.test.js](tests/home-entitlements.test.js) |
+| Smart home: the live 3D home (`/smart-home/:id`) | Page [pages/home-scene.html](pages/home-scene.html) `-> /smart-home/:id` and `-> /home/:id`, styles [public/home-scene.css](public/home-scene.css). Pure layout [src/home/scene-model.js](src/home/scene-model.js), WebGL renderer [src/home/scene-render.js](src/home/scene-render.js), the 2D house [src/home/scene-fallback.js](src/home/scene-fallback.js), page controller [src/home/scene.js](src/home/scene.js), browser half of the API contract [src/home/api.js](src/home/api.js). Consumes `GET /api/home/:id`, the SSE stream [api/home/[id]/stream.js](api/home/%5Bid%5D/stream.js), [api/home/[id]/call.js](api/home/%5Bid%5D/call.js) and `/api/home/:id/grants` | Live | A live 3D model of the user's house, driven entirely by their own Home Assistant, with the agent's body standing in it. **Home Assistant stores no geometry**, so everything spatial is derived from its four flat registries by a PURE module with no Three.js in it: floors stack by level, rooms pack per floor in name order, and a saved floorplan overrides the packing through one `layout` option. That split is why the layout of a real recorded house is asserted in a unit test without a GPU. **A room is lit the way the room is lit**: colour and intensity from the lights that are actually on, genuinely dark when they are all off, and the outline around its footprint goes amber the moment anything in it is unlocked or open. **A room with sixty entities is not sixty objects**: objects are ranked (lights, locks, covers, climate, alarms, media, fans, cameras, the rest), capped per surface, and the remainder summarized; numeric sensors become readouts, never objects. A device Home Assistant cannot reach is drawn as a ghost with a marker, never omitted. **The house never empties**: a dropped connection greys the scene, keeps every room, and says how old it is. Stale (the platform is retrying) and disconnected (nobody is) are different pills, and only the second offers a button. **The 2D view is not a consolation prize**: same model, real rows and real buttons, reads and operates the whole house, and it is where a browser with no WebGL or a device measured below 18 fps is routed automatically, with the page saying so. A guarded action answers 409 and the question is rendered on the object it would move, with an optional standing allowance for that one entity. Measured: 86 ms median from a real Home Assistant service call to the SSE frame, 10 to 23 ms from that frame to the painted one, 0.1 to 0.3 ms of per-frame work, 108 draw calls, and a flat heap across ten minutes of live updates. Docs: [docs/home-scene.md](docs/home-scene.md). Tests: [tests/home-scene-model.test.js](tests/home-scene-model.test.js), [tests/e2e/home-scene.spec.js](tests/e2e/home-scene.spec.js) |
| three.ws Home privacy, retention, export and deletion | Inventory + purge + export + deletion [api/_lib/home/privacy.js](api/_lib/home/privacy.js), disclosure copy [api/_lib/home/disclosure.js](api/_lib/home/disclosure.js), endpoint [api/home/privacy.js](api/home/privacy.js) `-> /api/home/privacy`, schema [api/_lib/migrations/20260903180000_home_privacy_retention.sql](api/_lib/migrations/20260903180000_home_privacy_retention.sql), purge section E of [api/cron/db-retention.js](api/cron/db-retention.js) | Live | The single place that knows everything the Home lane stores. `INVENTORY` is not documentation of the code, it IS the code: the endpoint renders it, the export walks it, and [tests/home-privacy.test.js](tests/home-privacy.test.js) re-derives the set of `home_*` tables from the migration files and fails the build if one of them has no row, which is what stops an undocumented data class from ever landing. The load-bearing promise is that entity names and states are never persisted (the room graph lives in the bridge runtime's memory and dies with the instance); a second test fails any migration that creates a table shaped like a state history. The action log's window is per home and the owner's, 90 days by default, adjustable down to a day and up to ten years with a written reason the schema also enforces, applied immediately on change and swept by the platform's existing retention cron rather than a cron of its own. Deletion goes further than the cascades: memberships and grants on other people's homes, the departed user's id inside another household's action log, invitations addressed to their email, and the lane's rows in the 365-day `audit_log`. Docs: [docs/home-privacy.md](docs/home-privacy.md). Tests: [tests/home-privacy.test.js](tests/home-privacy.test.js) |
| Avatar thumbnail coverage | [api/_lib/avatar-thumbs.js](api/_lib/avatar-thumbs.js) + crons [api/cron/avatar-thumbnail-backfill.js](api/cron/avatar-thumbnail-backfill.js) (absent thumbnails, `*/5`) and [api/cron/avatar-thumbnail-render.js](api/cron/avatar-thumbnail-render.js) (stale marketplace thumbnails, `*/10`) | Live | The single owner of `avatars.thumbnail_key`. Enforces the invariant that a thumbnail key is persisted **only after** its R2 object is confirmed to exist — a key pointing at a missing object makes R2 return 404 `text/plain`, which Chrome blocks as `ERR_BLOCKED_BY_ORB` inside an `<img>`. Fills coverage cheapest-first: zero-copy adoption of `forge_creations.preview_key`, then a headless-chromium GLB→PNG render to `thumb/<avatarId>.png` ([api/_lib/render-glb.js](api/_lib/render-glb.js)). Bounded retries via the `avatar_thumbnail_backfill` claim ledger ([migration](api/_lib/migrations/20260709120000_avatar_thumbnail_backfill.sql)), with `isBrowserInfrastructureError()` separating an OOM-killed browser from a genuinely broken model so a crash never retires healthy avatars. Bulk runner: [scripts/backfill-avatar-thumbnails.mjs](scripts/backfill-avatar-thumbnails.mjs) (`--status`, `--adopt-only`, `--loop`, `--reset-infra`). Docs: [docs/avatar-thumbnails.md](docs/avatar-thumbnails.md). Tests: [tests/avatar-thumbs.test.js](tests/avatar-thumbs.test.js), [tests/home-thumbnail-orb.test.js](tests/home-thumbnail-orb.test.js) |
| Forge model categorization | Classifier [api/_lib/forge-classify.js](api/_lib/forge-classify.js), wired at generation in [api/_lib/forge-store.js](api/_lib/forge-store.js) (`createCreation`), backfill [scripts/backfill-forge-categories.mjs](scripts/backfill-forge-categories.mjs), coloured badges in [src/forge-showcase.js](src/forge-showcase.js) + `/forge-studio` twin | Live | Assigns every forge model a `model_category` (avatar/accessory/item/scene/creature/vehicle/other) from its prompt with a deterministic, dependency-free keyword classifier — most-specific-first so "a knight riding a horse" is an avatar, not a creature. Nothing set the category before, so ~99.8% of the corpus was `other` and the category badges, filters, and Forge-Off category dimension were dead; the classifier now runs inline on every generation (all lanes) and reclassifies ~85% of the 9.8k-row back catalogue (dry-run verified). Coloured category pills render across the showcase/gallery/community feed. Tests: [tests/forge-classify.test.js](tests/forge-classify.test.js). |
@@ -287,6 +289,8 @@ surface-map row already covers:
| [services/agent-screen-caster/](services/agent-screen-caster) | Self-hosted Playwright caster: an agent owner runs it on their own host with their agent id + key, and it streams the browser it drives into the agent-screen feed. No managed instance exists (the platform's own casting runs in `workers/agent-screen-pool` and `workers/agent-screen-worker`). Tests: [tests/agent-screen-caster.test.js](tests/agent-screen-caster.test.js) |
| [services/fleet-console/](services/fleet-console) | Health console for an open-source fleet: enumerates a GitHub owner's repositories, probes every deployment URL and npm package they advertise, and scores what each one actually delivers. Ships an HTTP dashboard, a CLI (`scan --attention` exits 1 when anything is broken, so cron can gate on it) and an MCP server over the same snapshot. Not deployed and not meant to be: it runs from a terminal, a cron job, or beside an agent. Tests: [tests/fleet-console.test.js](tests/fleet-console.test.js), [tests/fleet-console-server.test.js](tests/fleet-console-server.test.js) |
| [services/pump-graduations/](services/pump-graduations) | Standalone watcher for pump.fun bonding-curve graduations |
+| [services/home-relay/](services/home-relay) | Terminates the outbound WebSocket a LAN-only Home Assistant dials, and multiplexes allowlisted platform sessions onto it. Holds no database and no credential at rest: a house proves ownership with an HMAC install token, and the Home Assistant authentication happens inside the house and never crosses this process. Not a proxy, on purpose: it carries a fixed list of Home Assistant message types and refuses everything else, including every service domain that would administer the machine rather than a device. Deployed unthrottled with min-instances 1 because it holds sockets between requests. Docs: [docs/home-relay.md](docs/home-relay.md), [docs/home-relay-threat-model.md](docs/home-relay-threat-model.md). Tests: [tests/home-relay-protocol.test.js](tests/home-relay-protocol.test.js), [tests/home-relay-transport.test.js](tests/home-relay-transport.test.js) |
+| [home-assistant-integration/](home-assistant-integration) | The Python that runs inside a user's house: a Home Assistant custom integration, distributed through HACS as its own public repository, that dials out to `services/home-relay`. A custom integration rather than a Home Assistant add-on because add-ons only work on OS and Supervised installs while an integration works on all four, and because HACS distributes integrations rather than add-ons. Mints its own system refresh token locally, so no Home Assistant credential ever reaches three.ws, and enforces the relay's allowlist a second time from a generated `allowlist.json` shipped byte-identical from `services/home-relay`. Publishing the public repository is owner-gated. |
## npm workspaces
diff --git a/data/guards.json b/data/guards.json
index 78c488dcd..cad593060 100644
--- a/data/guards.json
+++ b/data/guards.json
@@ -1007,6 +1007,22 @@
"reason": "It reads the production home_connections table and the live encryption key, then decrypts in memory to test each token against the current key. There is no offline fixture for \"this ciphertext no longer opens\" that would prove anything about the real fleet. Read-only: it never writes and never opens a socket to any house."
}
},
+ {
+ "id": "check-home-voice",
+ "script": "scripts/check-home-voice.mjs",
+ "npm": "check:home-voice",
+ "title": "Hands-free voice loop",
+ "protects": "The browser voice loop keeps the properties the feature is sold on: nothing about listening loads before opt-in, an ambient \"yeah\" never confirms a guarded action, and the agent does not wake itself.",
+ "why": "This loop holds a live microphone and can reach a physical actuator, so its claims are the kind that have to be measured rather than reasoned about. It drives a real Chromium with a fake capture device fed from speech the platform synthesized itself, and walks ten scenarios end to end including barge-in, mute at the track, a refused microphone and a deployment with no speech lane. It cannot sit on an automatic path: it needs a browser, a server and the live speech lanes, and a flaky guard on the gate is a guard people learn to skip.",
+ "stages": [
+ "manual"
+ ],
+ "needs": "browser",
+ "proof": {
+ "kind": "live",
+ "reason": "Drives a real Chromium against the running voice loop with a synthesized microphone stream. The behaviours under test (a wake word firing, playback stopping on barge-in, a capture track actually ending) only exist at runtime, so there is no static fixture that could stand in for them."
+ }
+ },
{
"id": "audit-play-failure-modes",
"script": "scripts/audit-play-failure-modes.mjs",
diff --git a/data/pages.json b/data/pages.json
index 60e7861c3..60859957b 100644
--- a/data/pages.json
+++ b/data/pages.json
@@ -395,7 +395,7 @@
{
"path": "/tour/atlas",
"title": "Tour Atlas",
- "description": "Every stop on the guided tour as a real screenshot of the live site, with the feature circled by the tour's own spotlight. Search 185 stops, filter by chapter, read what the guide says about each one, and drop the tour onto any feature in a single click.",
+ "description": "Every stop on the guided tour as a real screenshot of the live site, with the feature circled by the tour's own spotlight. Search 263 stops, filter by chapter, read what the guide says about each one, and drop the tour onto any feature in a single click.",
"priority": 0.6,
"changefreq": "weekly",
"added": "2026-07-31"
@@ -1009,6 +1009,14 @@
"changefreq": "yearly",
"added": "2026-09-03"
},
+ {
+ "path": "/smart-home/privacy",
+ "title": "Your home data",
+ "description": "Everything three.ws stores about the homes you connected, with why it exists and how long it stays. Set how long your action log lives and watch the old entries go, download all of it as JSON, or delete one home or every trace of all of them. Room names, device states and voice audio are never stored at all.",
+ "priority": 0.5,
+ "changefreq": "monthly",
+ "added": "2026-09-03"
+ },
{
"path": "/smart-home/plan",
"title": "Home plan",
@@ -2662,6 +2670,14 @@
"changefreq": "monthly",
"added": "2026-08-16"
},
+ {
+ "path": "/docs/home-voice",
+ "title": "Docs · The browser voice loop",
+ "description": "How hands-free works for a connected home: a wake word matched by a model running in your own tab, an interruption that stops the agent mid-sentence, a pause that does not truncate your command, and a spoken confirmation narrow enough that a background yes can never unlock a front door. Includes the measured latency of every leg and how to mount the loop on your own surface.",
+ "priority": 0.6,
+ "changefreq": "monthly",
+ "added": "2026-09-03"
+ },
{
"path": "/docs/smart-home",
"title": "Docs · three.ws Home",
@@ -2686,6 +2702,14 @@
"changefreq": "monthly",
"added": "2026-09-03"
},
+ {
+ "path": "/docs/home-relay",
+ "title": "Docs \u00b7 Connect a home that is only on your network",
+ "description": "Most Home Assistant installs cannot be reached from the internet, so the house dials three.ws instead: install one HACS integration, paste a ten-minute pairing code, and nothing listens on your network, no port is forwarded, and three.ws never receives a Home Assistant token. Includes the operator half: the relay service, its configuration and deploy, how the allowlist is changed, and how to prove the whole path against a real house on a network the server cannot route to.",
+ "priority": 0.6,
+ "changefreq": "monthly",
+ "added": "2026-09-03"
+ },
{
"path": "/docs/home-relay-threat-model",
"title": "Docs · Home relay threat model",
@@ -2694,6 +2718,14 @@
"changefreq": "monthly",
"added": "2026-09-03"
},
+ {
+ "path": "/docs/home-scene",
+ "title": "Docs \u00b7 The live 3D home",
+ "description": "How the connected house becomes a room you can stand in: the room graph the bridge builds from Home Assistant's registries, how a real light dimming dims the model, what the scene does while the house is unreachable, and the fallback that keeps every control usable without WebGL.",
+ "priority": 0.6,
+ "changefreq": "monthly",
+ "added": "2026-09-03"
+ },
{
"path": "/docs/home-privacy",
"title": "Docs · Home privacy and retention",
diff --git a/docs/build.md b/docs/build.md
index a1b2f52ba..f8256ff72 100644
--- a/docs/build.md
+++ b/docs/build.md
@@ -45,7 +45,7 @@ front-end, the `vercel.json` route table, and every `api/**` handler from source
provisioned from the `crons` array in `vercel.json` by
[scripts/create-gcp-scheduler.mjs](../scripts/create-gcp-scheduler.mjs); that
array is the count, so read it there rather than trusting a number quoted here
-(112 entries on 2026-09-02). There is **no GitHub Actions CI**. Full runbook: [docs/ops/gcp-production.md](./ops/gcp-production.md).
+(114 entries on 2026-09-03). There is **no GitHub Actions CI**. Full runbook: [docs/ops/gcp-production.md](./ops/gcp-production.md).
`.npmrc` sets `legacy-peer-deps=true` (npm never auto-installs peers — the
reason `audit:deploy` checks the peer tree), and `engines.node` pins Node
diff --git a/docs/guards.md b/docs/guards.md
index d6ed5d961..38cc507a7 100644
--- a/docs/guards.md
+++ b/docs/guards.md
@@ -158,6 +158,7 @@ Run `npm run audit:guards` to print the current count and per-stage breakdown. T
| Cron liveness | `npm run audit:cron-liveness` | Each cron in `vercel.json` resolves to a handler that exists, imports, answers a live request, and refuses an unauthenticated one. |
| Custodial key health | `npm run audit:custodial-keys` | Every stored custodial Solana secret still decrypts under the current `WALLET_ENCRYPTION_KEY`. |
| Home credential health | `npm run audit:home-credentials` | Every stored Home Assistant token still decrypts under the current `WALLET_ENCRYPTION_KEY`, so no connected house is sealed. |
+| Hands-free voice loop | `npm run check:home-voice` | Nothing about listening loads before opt-in, an ambient "yeah" never confirms a guarded action, and the agent does not wake itself. |
| Delegation contract addresses | `npm run check:erc7710` | Every delegation-manager address is a deployed contract. |
---
diff --git a/package.json b/package.json
index 16626c456..acff66d02 100644
--- a/package.json
+++ b/package.json
@@ -126,7 +126,8 @@
"packages/witness",
"packages/portal",
"packages/tty-avatar",
- "packages/home-bridge"
+ "packages/home-bridge",
+ "packages/home-mcp"
],
"main": "src/app.js",
"browserslist": [
@@ -169,6 +170,8 @@
"build:x-strip": "node scripts/make-x-strip.mjs",
"build:dapp-store-media": "node solana-mobile/scripts/make-media.mjs",
"build:dapp-store-previews": "node solana-mobile/scripts/make-screenshots.mjs",
+ "seeker:screencast": "node solana-mobile/scripts/make-screencast.mjs",
+ "seeker:feature-tour": "node solana-mobile/scripts/make-feature-tour.mjs --authed",
"render:pumpfun-verified": "node scripts/render-pumpfun-verified.mjs",
"build:ibm-shell": "node scripts/build-ibm-shell.mjs",
"i18n": "npm run i18n:extract && npm run i18n:translate",
@@ -353,6 +356,7 @@
"check:vendored": "node scripts/check-vendored-workers.mjs",
"check:secrets": "node scripts/check-secrets.mjs",
"check:gcloudignore": "node scripts/check-gcloudignore.mjs",
+ "check:home-voice": "node scripts/check-home-voice.mjs",
"check:evm-rpc": "node --env-file=.env scripts/probe-evm-rpc.mjs --chain 1 --ens",
"awal:pin": "node scripts/update-awal-version.mjs",
"smoke:prod": "node scripts/check-pages.mjs --base https://three.ws",
@@ -421,6 +425,10 @@
"token:volume": "node scripts/token-volume.mjs",
"companion:e2e": "node --env-file=.env.local --env-file=.env scripts/companion-e2e.mjs",
"home:instance": "node scripts/home-test-instance.mjs --up --onboard --seed --name lane",
+ "home:fleet": "node scripts/home-fleet.mjs up --homes 12 --big 1",
+ "home:fleet:down": "node scripts/home-fleet.mjs down",
+ "home:load": "node --expose-gc scripts/home-load.mjs all --out tasks/home/envelope-$(date -u +%Y-%m-%d).json",
+ "home:chaos": "node --expose-gc scripts/home-chaos.mjs all --out tasks/home/chaos-$(date -u +%Y-%m-%d).json",
"home:instance:down": "node scripts/home-test-instance.mjs --down --name lane",
"test:home:live": "HOME_LIVE=1 vitest run packages/home-bridge tests/home-store.test.js",
"home:matrix": "node scripts/home-version-matrix.mjs",
diff --git a/public/guards.json b/public/guards.json
index 78c488dcd..cad593060 100644
--- a/public/guards.json
+++ b/public/guards.json
@@ -1007,6 +1007,22 @@
"reason": "It reads the production home_connections table and the live encryption key, then decrypts in memory to test each token against the current key. There is no offline fixture for \"this ciphertext no longer opens\" that would prove anything about the real fleet. Read-only: it never writes and never opens a socket to any house."
}
},
+ {
+ "id": "check-home-voice",
+ "script": "scripts/check-home-voice.mjs",
+ "npm": "check:home-voice",
+ "title": "Hands-free voice loop",
+ "protects": "The browser voice loop keeps the properties the feature is sold on: nothing about listening loads before opt-in, an ambient \"yeah\" never confirms a guarded action, and the agent does not wake itself.",
+ "why": "This loop holds a live microphone and can reach a physical actuator, so its claims are the kind that have to be measured rather than reasoned about. It drives a real Chromium with a fake capture device fed from speech the platform synthesized itself, and walks ten scenarios end to end including barge-in, mute at the track, a refused microphone and a deployment with no speech lane. It cannot sit on an automatic path: it needs a browser, a server and the live speech lanes, and a flaky guard on the gate is a guard people learn to skip.",
+ "stages": [
+ "manual"
+ ],
+ "needs": "browser",
+ "proof": {
+ "kind": "live",
+ "reason": "Drives a real Chromium against the running voice loop with a synthesized microphone stream. The behaviours under test (a wake word firing, playback stopping on barge-in, a capture track actually ending) only exist at runtime, so there is no static fixture that could stand in for them."
+ }
+ },
{
"id": "audit-play-failure-modes",
"script": "scripts/audit-play-failure-modes.mjs",
diff --git a/public/tutorials-manifest.js b/public/tutorials-manifest.js
index baf6bbd4b..ebc83ccb4 100644
--- a/public/tutorials-manifest.js
+++ b/public/tutorials-manifest.js
@@ -442,6 +442,16 @@
previewModel: '/animations/soldier.glb',
ctaPrimary: { label: 'Open /play', href: '/play' },
},
+ {
+ slug: 'connect-your-home',
+ tier: 'middle',
+ title: 'Connect your home',
+ blurb: 'Point your agent at a real Home Assistant and it runs your actual house: lights, thermostat, and the scenes you already built. Covers the three honest ways to reach a house that lives on a home network, and the rule that unlocking, opening and disarming always stop and ask, while locking up never does. Ends with sharing the house: five roles, per-person scopes, and why a house sitter can turn a light on and can never open the front door.',
+ builds: 'A house your agent can run, shared with the people who live in it',
+ time: '20 min',
+ previewModel: '/animations/robotexpressive.glb',
+ ctaPrimary: { label: 'Connect a home', href: '/smart-home' },
+ },
/* ───────────────────────── ADVANCED ───────────────────────── */
{