Open-source platform for 3D AI agents. Turn text or a photo into a rigged, animated GLB avatar, give it an LLM brain, memory and a wallet, and embed it anywhere with one web component. Remote MCP server, x402 payments, Three.js, browser-native.
JavaScript 3d-generationai-agentsanimationavatardigital-humangenerative-aiglbgltfimage-to-3dllmmcpmcp-servermodel-context-protocolsolanatext-to-3dthreejsweb-componentswebglwebxrx402
docs(home): price a connected house from what it measurably costs, and say what a limit may never do
nirholasc59a3f0572dc
diff --git a/CHANGELOG.md b/CHANGELOG.mdindex b74e2c7b8..38fc81833 100644--- a/CHANGELOG.md+++ b/CHANGELOG.md@@ -7,6 +7,7 @@ Public history for [three.ws](https://three.ws), newest first. New pages come fr## 2026-09-03- **Docs · Home households and roles** (`/docs/home-households`): Sharing a connected house without sharing a login: the five roles and what each one may do, per-member entity scopes that narrow the house a member can even see, how invitations are issued and accepted, what happens to somebody's access when they leave, and the rule everything hangs off, that a guest can never confirm an action that opens a building.+- **Docs · Home plans and quotas** (`/docs/home-plans`): What a connected house costs and what each plan covers, with the two commitments enforced in code rather than promised in prose: a limit never blocks a safety action, so locking up, closing a garage or valve and arming an alarm work over quota and past due; and nothing about the confirmation gate, the action log's integrity or the role system is ever a paid feature.- **Docs · Home privacy and retention** (`/docs/home-privacy`): Everything three.ws stores about a home you connect, why, for how long, and what removes it: the full inventory, the promise that room names and device states are never persisted, the 90-day action-log window and the control that changes it, the export and deletion paths, the logging rules, and the disclosure text shown at connect and at the voice opt-in.- **Docs · Home relay threat model** (`/docs/home-relay-threat-model`): What an attacker gets at every position around the socket a LAN-only house dials out through, and what stops them: why the relay carries a fixed list of message types instead of proxying HTTP into a home network, what a stolen install token is and is not worth, why the allowlist is enforced again inside the house so a compromised relay widens nothing, and the residuals accepted on purpose.- **Docs · Home security** (`/docs/home-security`): The threat model for a connected house, written about a building rather than a database: what each actor can do and what stops them, why the confirmation gate is the load-bearing control and prompt filtering is depth, the eleven checks that run with every build, the SSRF guard every server-side dial goes through and why a hostname check is not one, the prompt-injection proof that ends by asking a real lock whether it opened, and the residuals accepted on purpose.@@ -20,10 +21,12 @@ Public history for [three.ws](https://three.ws), newest first. New pages come fr- **A stranger cannot make your agent open your front door**: The home lane now has a written threat model and eleven security checks that run with every build, and the standard they hold is a lock, not a database row. The big fix: the address you give for your house is now resolved and pinned on our side before anything dials it, so a web address that secretly points back into our own network is refused instead of connected to, and it is re-checked every time your house reconnects rather than trusted from the day you added it. A device or integration in your house cannot talk your agent into anything either: we wrote an unlock instruction into a real room name, a real device name and a real scene name, ran a real agent against that house, and the front door stayed locked. Your privacy page is now rate limited like everything else, so nobody can hammer the export or the delete. (`/smart-home`) `[security, improvement]`- **Any assistant can now run your house, and it still will not open your door**: There is a new way to connect your home that needs no three.ws account and no remote web address at all: install @three-ws/home-mcp in Claude, Cursor, or anything else that speaks Model Context Protocol, give it your Home Assistant address and a token, and it reads your rooms, runs the scenes you already built, and calls services. Because it runs on your own machine, your ordinary home network address works and nothing about your house leaves the building. The safety rule is the same one the rest of the platform uses, applied honestly to this setup: locking up, closing the garage and arming the alarm run straight away and never ask. Unlocking, opening a door and disarming are refused outright, every time, because saying yes to opening a building takes a person and this kind of connection has no person in it to ask. If you genuinely want one specific door handled without asking, you name that exact door yourself when you start it, by hand, and nothing your assistant can do will widen that to any other door. We proved it against a real Home Assistant rather than a stand-in: the front door was told to unlock seven different ways, including with a fake confirmation smuggled into the request, and it stayed locked every time. Alongside it there is now a full walkthrough from nothing to a working agent in a real house, covering what to do when it says your home is unreachable, and what a guest in your household can and cannot do. (`/smart-home`) `[feature, sdk, docs]`- **Connect your house to your agent, and see every way it can go wrong**: The /smart-home page now takes you from "I have a Home Assistant somewhere" to a connected house, and it is honest at every step. An address that only exists on your home network is refused the moment you type it, with the two real ways round it, instead of spinning for fifteen seconds. A rejected token says so and puts the cursor back in the token box. A house that stops answering keeps its rooms on screen, marked stale with how long ago it last replied, rather than blanking out. Your access token is sent once, encrypted at rest, and never comes back to the page: it is not in your browser storage, not in a URL, and not in any response. Disconnecting says plainly that the stored token is erased and reminds you to delete it in Home Assistant too. (`/smart-home`) `[feature]`+- **See what your connected homes use, before a limit ever stops you**: Your smart home plan now has a page. It shows every allowance whether or not you are near it: how many homes you have connected, how many people are in each household, how many live screens, how many voice minutes and agent turns you have used this month, and the exact date each one resets. Two things a plan can never do are written on the page itself, because they matter more than any number on it. Locking a door, closing a garage or a water valve and arming an alarm are never refused by a limit, on any plan, in any state, including on a home your plan has paused. And confirmation prompts, your action log and every safety property of household roles are on every plan, free included: safety is not an upgrade. If a plan change ever leaves you with more homes than it covers, nothing is disconnected and nothing is deleted. The extra homes are paused, with their access tokens and their whole history untouched, and you pick which ones are live from the same page. (`/smart-home/plan`) `[feature, improvement]`- **See, export and delete everything a connected home stores**: Connecting a house to three.ws hands over a key to a physical building, so the answer to "what do you keep, and for how long" is now a page you can read and an endpoint you can call. Every piece of data a connected home creates is listed with why it exists and what removes it, including the parts we deliberately never store: the names of your rooms and devices, their states, and any audio from voice control. There is no record of which lights were on, or when. The log of what the agent did in your home is yours: it keeps 90 days by default, you can shorten it to a single day and the old entries go immediately, and an operator who has to keep records for longer can, with a written reason. One endpoint shows you what is stored, downloads all of it as JSON, and deletes one home or every trace of all of them. (`/docs/home-privacy`) `[feature, security, docs]`- **The status page can tell one dark house from an outage**: Connected homes now report on the public status page at /status, and the hard part was making that number honest. If your Home Assistant is switched off, your token expired or your internet dropped, that is your house: it shows up in your own home view, not as a three.ws outage and not as an alert to anyone. It takes at least ten homes failing at once before the platform will call it a problem on our side, because with three homes connected one holiday cottage losing power would look like a third of everything being broken. One thing is treated as an emergency at a count of one: an action that can open a building (a lock, a garage door, an alarm) recorded as having run without someone saying yes. That has no acceptable rate. (`/status`) `[infra, improvement]`- **The tour atlas counts its stops correctly again**: The atlas at /tour/atlas is the map of the guided tour: one card per stop, numbered in the order you would walk them. Two hundred and three of those cards were still carrying numbers from an older version of the tour, so the grid showed duplicate stop numbers, skipped others, and put cards out of order, under a heading that claimed one more stop than the grid actually held. Every card is now numbered by its real position in the tour and the count above the grid matches what is under it. Nothing about the stops themselves changed: same pages, same screenshots, same highlights. (`/tour/atlas`) `[fix]`- **three.ws Drive: your agent, in the car**: There is a new page at /drive built for a car screen instead of a desk. Your agent is on it full size, you hold one big button and talk, and it answers out loud in its own voice with its face moving. It shows you one line of what it said rather than a wall of chat, because you are driving. It starts dark, because a bright panel at night is glare, and it will switch to a day palette on one press or one sentence. The keyboard stays out of the way while you are moving: if your browser can tell how fast you are going, text entry locks itself the moment you pull away and comes back when you have properly stopped. A few things you say never leave the car at all, so "repeat that", "stop talking", "louder" and "night mode" happen instantly, while "stop at the next charger" still goes to your agent like any other question. It works today on a head unit browser, on a phone in a cradle, and on Android Automotive. The Apple CarPlay version is built and waiting on Apple's approval for voice assistants in the car. One thing this fixed for everyone: an avatar used to answer in silence if you were not signed in, and now it always has a voice. (`/drive`) `[feature, improvement]`+- **We tried making your agent a Matter device, measured it, and decided against it for now**: Matter is the standard that lets smart-home gear from different brands work together, and the plan had always been to make a three.ws agent show up as a Matter device so that any smart-home controller could see it, drop it in a room, and use it in an automation. We built it and pointed it at a real Home Assistant to find out whether the idea holds up. It does, technically: the agent paired in under a second over an ordinary network with no Bluetooth and no special radio, Home Assistant listed it as a proper device with a name, a model and a serial number, put it in the living room, and messages went both ways in well under a second. It also held the line that matters most: an automation that asked the agent to unlock a front door was refused and the door stayed locked, because an automation is not a person saying yes, and only a real confirmation from a person opened it. We are still not shipping it, and the honest reason is that it would be a narrower version of something you can already have. The three.ws Home Assistant integration already puts your agent inside your house with the whole conversation available to it, where Matter would offer a switch and a sensor. On top of that, appearing in the big-name smart-home apps needs a certified manufacturer identity we do not hold. The full write-up, every measurement, and the exact conditions that would change our answer are now in the smart-home documentation, so nobody has to guess or start over. (`/docs/smart-home`) `[docs]`- **Your home is a household now, and a house sitter still cannot open your front door**: A house has more than one person in it, and until now the only way to let a partner, a house sitter or a colleague use a connected home was to hand over your password. Every home has a household. On its card under “Who can reach this home” you can invite somebody by email and choose exactly what they get. There are five roles and each one says plainly what it can and cannot do at the moment you pick it. Someone who lives there can control everything and approve unlocking a door. A guest can turn the lights on and can never approve unlocking anything, ever, no matter what your agent asks them: that refusal is enforced on our servers and there is no version of the app that could offer them the button. A guest or a viewer can also be given just the kitchen, or just three specific devices, and the rooms you did not give them are removed from what they receive rather than hidden on screen, so their app never learns those rooms exist. Invitations work once, expire after a week, and can be withdrawn before anyone uses them. Removing somebody takes back every standing allowance they ever approved in the same instant, so a door can never keep opening on the say-so of a person who has left. And every action in your home log is attributed to the person who took it, so “who did what” has a real answer. (`/smart-home`) `[feature, security]`- **Your house reads in your language, in your units, at a size a finger can hit**: Three fixes to the smart home page, all of them things you would have noticed. It now speaks all 87 languages: the page was written to be translated but never loaded the piece that does the translating, so everyone got English, and Arabic and Hebrew never flipped to right to left. Temperatures now come from your house rather than from an assumption. If your Home Assistant is set to Fahrenheit, every room reads in Fahrenheit, and a room at 70 no longer shows as blazing hot because the comfort range was written in Celsius. A house that mixes a Celsius sensor with a Fahrenheit thermostat is converted before it is averaged, so the number you see belongs to a real scale. The small print at the top of the page also got lighter so it clears the contrast standard, in both the light and dark themes, and the Show button next to the token field is now big enough to tap without missing. (`/smart-home`) `[fix, improvement]`diff --git a/STRUCTURE.md b/STRUCTURE.mdindex 419d86b37..91ad28d55 100644--- a/STRUCTURE.md+++ b/STRUCTURE.md@@ -148,12 +148,13 @@ 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), 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). 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). 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). 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) || 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) || 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). |diff --git a/api/chat.js b/api/chat.jsindex fdeaf423c..3ce55667d 100644--- a/api/chat.js+++ b/api/chat.js@@ -1040,6 +1040,15 @@ export default wrap(async (req, res) => {// card; the approval happens at /api/home/:id/confirm, which this file never// calls and no model can reach.let homeResults = [];+ /**+ * The home this turn touched, stamped into the usage row below.+ *+ * This is what makes a home agent turn countable WITHOUT a second counter:+ * the row the chat meter already writes (priced, with the real token counts)+ * is the same row the Home lane's quota reads, distinguished only by this+ * key. See api/_lib/home/usage.js.+ */+ let homeTouched = null;if (auth?.userId && (result.toolCalls || []).some((c) => isHomeTool(c.name))) {let pass = result;let workingHistory = history;@@ -1053,11 +1062,13 @@ export default wrap(async (req, res) => {// Streamed immediately, ahead of the model's next pass, so a// confirmation card is on screen while the model is still composing// the sentence that explains it.+ const touchedId = entry.result.structured?.home?.id || entry.call.input?.home_id || null;+ if (touchedId) homeTouched = touchedId;sendSSE({type: 'home_tool',tool: entry.call.name,status: entry.result.kind,- home_id: entry.result.structured?.home?.id || entry.call.input?.home_id || null,+ home_id: touchedId,data: entry.result.structured,});}diff --git a/data/changelog.json b/data/changelog.jsonindex bc97118dc..6e53f9b0c 100644--- a/data/changelog.json+++ b/data/changelog.json@@ -1,6 +1,16 @@{"$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. `link` is optional and must be a live three.ws path.","entries": [+ {+ "date": "2026-09-03",+ "title": "See what your connected homes use, before a limit ever stops you",+ "summary": "Your smart home plan now has a page. It shows every allowance whether or not you are near it: how many homes you have connected, how many people are in each household, how many live screens, how many voice minutes and agent turns you have used this month, and the exact date each one resets. Two things a plan can never do are written on the page itself, because they matter more than any number on it. Locking a door, closing a garage or a water valve and arming an alarm are never refused by a limit, on any plan, in any state, including on a home your plan has paused. And confirmation prompts, your action log and every safety property of household roles are on every plan, free included: safety is not an upgrade. If a plan change ever leaves you with more homes than it covers, nothing is disconnected and nothing is deleted. The extra homes are paused, with their access tokens and their whole history untouched, and you pick which ones are live from the same page.",+ "tags": [+ "feature",+ "improvement"+ ],+ "link": "/smart-home/plan"+ },{"date": "2026-09-02","title": "Keyboard users can move past the Create page hero card",@@ -25919,12 +25929,21 @@{"date": "2026-09-03","title": "Your home is a household now, and a house sitter still cannot open your front door",- "summary": "A house has more than one person in it, and until now the only way to let a partner, a house sitter or a colleague use a connected home was to hand over your password. Every home has a household. On its card under \u201cWho can reach this home\u201d you can invite somebody by email and choose exactly what they get. There are five roles and each one says plainly what it can and cannot do at the moment you pick it. Someone who lives there can control everything and approve unlocking a door. A guest can turn the lights on and can never approve unlocking anything, ever, no matter what your agent asks them: that refusal is enforced on our servers and there is no version of the app that could offer them the button. A guest or a viewer can also be given just the kitchen, or just three specific devices, and the rooms you did not give them are removed from what they receive rather than hidden on screen, so their app never learns those rooms exist. Invitations work once, expire after a week, and can be withdrawn before anyone uses them. Removing somebody takes back every standing allowance they ever approved in the same instant, so a door can never keep opening on the say-so of a person who has left. And every action in your home log is attributed to the person who took it, so \u201cwho did what\u201d has a real answer.",+ "summary": "A house has more than one person in it, and until now the only way to let a partner, a house sitter or a colleague use a connected home was to hand over your password. Every home has a household. On its card under “Who can reach this home” you can invite somebody by email and choose exactly what they get. There are five roles and each one says plainly what it can and cannot do at the moment you pick it. Someone who lives there can control everything and approve unlocking a door. A guest can turn the lights on and can never approve unlocking anything, ever, no matter what your agent asks them: that refusal is enforced on our servers and there is no version of the app that could offer them the button. A guest or a viewer can also be given just the kitchen, or just three specific devices, and the rooms you did not give them are removed from what they receive rather than hidden on screen, so their app never learns those rooms exist. Invitations work once, expire after a week, and can be withdrawn before anyone uses them. Removing somebody takes back every standing allowance they ever approved in the same instant, so a door can never keep opening on the say-so of a person who has left. And every action in your home log is attributed to the person who took it, so “who did what” has a real answer.","tags": ["feature","security"],"link": "/smart-home"+ },+ {+ "date": "2026-09-03",+ "title": "We tried making your agent a Matter device, measured it, and decided against it for now",+ "summary": "Matter is the standard that lets smart-home gear from different brands work together, and the plan had always been to make a three.ws agent show up as a Matter device so that any smart-home controller could see it, drop it in a room, and use it in an automation. We built it and pointed it at a real Home Assistant to find out whether the idea holds up. It does, technically: the agent paired in under a second over an ordinary network with no Bluetooth and no special radio, Home Assistant listed it as a proper device with a name, a model and a serial number, put it in the living room, and messages went both ways in well under a second. It also held the line that matters most: an automation that asked the agent to unlock a front door was refused and the door stayed locked, because an automation is not a person saying yes, and only a real confirmation from a person opened it. We are still not shipping it, and the honest reason is that it would be a narrower version of something you can already have. The three.ws Home Assistant integration already puts your agent inside your house with the whole conversation available to it, where Matter would offer a switch and a sensor. On top of that, appearing in the big-name smart-home apps needs a certified manufacturer identity we do not hold. The full write-up, every measurement, and the exact conditions that would change our answer are now in the smart-home documentation, so nobody has to guess or start over.",+ "tags": [+ "docs"+ ],+ "link": "/docs/smart-home"}]}diff --git a/docs/home-plans.md b/docs/home-plans.mdnew file mode 100644index 000000000..fc25177aa--- /dev/null+++ b/docs/home-plans.md@@ -0,0 +1,269 @@+# Home plans, entitlements and quotas++How three.ws decides what a connected house costs, what each plan covers, and the two things no+plan may ever refuse.++This document is both the reference for the mechanism and the **pricing proposal put to the+owner**. Every number in the plan table is a proposal with a measured cost behind it, and every+number is a config value: applying an owner-approved figure is an environment variable on a+running service, not a deploy.++Related: [`docs/smart-home.md`](smart-home.md) (what the lane is),+[`docs/home-privacy.md`](home-privacy.md) (retention and deletion),+[`docs/home-households.md`](home-households.md) (roles and seats).++---++## The two commitments to read first++**1. A limit never blocks a safety action.** Over quota, past due, downgraded, paused: a user can+still lock their door, close their garage, close a water valve and arm their alarm. The safe+direction is always free. A product that will not let someone lock up because they hit a quota is+indefensible.++**2. Nothing about the gate is a paid feature.** Confirmation prompts, the action log's integrity+and every safety property of the role system exist on every tier, including the free one. There is+no metered dimension for any of them and there must never be one. Selling safety would be wrong,+and it would also make the free tier a liability.++Both are enforced in code rather than promised in prose.+[`api/_lib/home/entitlements.js`](../api/_lib/home/entitlements.js) checks the safety exemption+*before* it looks at any counter, any plan or any pause state, and it gets the list of safe moves+from [`packages/home-bridge/src/safety.js`](../packages/home-bridge/src/safety.js) rather than+keeping a copy that could drift. `tests/home-entitlements.test.js` asserts both, first in the file.++---++## The cost model, measured++The Home lane's cost model is unusual, and the unusual part decides the shape of the plans: **the+expensive thing is not an action, it is a held socket.** A house that is connected and idle+occupies heap on a Cloud Run instance for the whole month whether or not anybody speaks to it, so+a plan metered only on actions would charge nothing for the dominant cost.++Everything below was measured, not assumed. Re-derive it with:++```bash+node scripts/home-test-instance.mjs --up --onboard --seed --json --name cost+node --expose-gc scripts/measure-home-entitlement-cost.mjs \+ --url http://127.0.0.1:<port> --token "<token>" --homes 16 --rates+```++`--rates` reads the live Cloud Run prices from Google's own Cloud Billing Catalog API rather than+from a remembered figure. The production service shape comes from+`gcloud run services describe three-ws-api --region us-central1`: 4 GiB, 2 vCPU, concurrency 160.++| Dimension | Measured marginal cost | How it was read (2026-09-03) |+|---|---|---|+| A connected home | **$0.0155 / home / month** | 16 real WebSocket connections to a real Home Assistant (125 entities): 302 KB heap, 262 KB RSS marginal per connection. At 60% of a 4 GiB instance that is ~9,800 homes per instance; the instance costs $152.42/month at $0.0000025/GiB-s + $0.000024/vCPU-s |+| An open live stream | **$0.0066 / stream / month** | a 23,036-byte room graph, serialized once per 10 s, at the same rates |+| An agent turn, default chain | **$0** | the default provider chain leads with platform-held free lanes (`isFreeLane` in [`api/_lib/llm-pricing.js`](../api/_lib/llm-pricing.js)) |+| An agent turn, Vertex Gemini 2.5 Flash | **$0.0025** | `costMicroUsd` over the real 6,359-token home prompt (the room graph) plus 250 output tokens |+| An agent turn, Claude Haiku 4.5 | **$0.0076** | same prompt, same function |+| An agent turn, Claude Sonnet 5 | **$0.0228** | same prompt, same function |+| A voice minute | **$0** | the default lanes are keyless: Edge Read Aloud TTS ([`api/_lib/tts-edge.js`](../api/_lib/tts-edge.js)) and NVIDIA Riva ASR ([`api/_lib/asr-nvidia.js`](../api/_lib/asr-nvidia.js)) |+| An action-log row | negligible | a busy evening of voice control is a few dozen rows of a few hundred bytes |++### What that measurement changed++Two findings inverted the assumptions this work started from, and both are worth stating plainly+because they point the pricing in the opposite direction:++**One agent turn on a paid model costs more than a year of holding that house's socket.**+$0.0228 against $0.0155 per month. The connection is not the expensive part after all; the prompt+is, because the room graph makes a home prompt large.++**Voice is not a cost driver at all.** The default speech lanes are keyless and cost the platform+nothing per utterance. Voice minutes are metered because an unbounded always-listening satellite is+an abuse surface and because a paid speech lane can be selected, not because the default costs+money.++### Can the free tier carry a connected home?++**Yes, comfortably.** At 1.6 cents per home per month, ten thousand free connected homes cost+about $155 a month, which is roughly one warm Cloud Run instance. The honest constrained free tier+some cost models would have forced (a session-scoped connection that closes when the tab does) is+not necessary and would make the free tier worse for no saving worth having. The free tier gets a+real, persistent, always-connected home.++The dimension that actually needs a ceiling is the agent turn on a paid model, and that is where+the tiers separate.++---++## The dimensions++| Dimension | Scope | Period | Scales with $THREE | Why it is metered |+|---|---|---|---|---|+| `homes` | account | concurrent | yes | the held socket, the lane's primary cost |+| `members` | per home | concurrent | **no** | the enterprise dimension: seats are sold, not held |+| `streams` | per home | concurrent | yes | a wall display is a subscriber we serialize the house to |+| `voiceMinutes` | account | monthly | yes | abuse surface, and a paid speech lane can be chosen |+| `agentTurns` | account | monthly | yes | the only dimension where a turn can really spend money |+| `logRetentionDays` | account | ceiling | yes | a hotel needs a year of attribution, a household needs last Tuesday |+| `relayConnections` | account | concurrent | yes | a dial-out tunnel costs what a direct connection costs |++`members` deliberately does **not** scale with the $THREE ladder. Holding a bag and buying seats+for a hotel are different purchases, and multiplying one by the other prices neither correctly.++`logRetentionDays` is a **ceiling on what a user may set**, never a value of its own.+[`api/_lib/home/privacy.js`](../api/_lib/home/privacy.js) owns the per-home retention setting, its+90-day default and the purge. The ceiling is checked when the user raises the setting and is never+applied retroactively: shortening somebody's existing audit trail for a billing reason would+destroy their evidence, and the log's integrity is not for sale on any tier.++---++## The proposed plan table++**This table is a proposal. Nothing here is a decided price.**++| Dimension | User (free) | Beta | Pro | Three Dimensional |+|---|---|---|---|---|+| Connected homes | 1 | 2 | 5 | unlimited |+| Household seats per home | 3 | 5 | 15 | unlimited |+| Live streams per home | 2 | 3 | 10 | unlimited |+| Voice minutes / month | 300 | 600 | 3,000 | unlimited |+| Agent turns / month | 1,000 | 2,500 | 15,000 | unlimited |+| Action-log retention | 90 days | 90 days | 365 days | 3,650 days |+| Relay connections | 1 | 1 | 5 | unlimited |++Reasoning, dimension by dimension:++- **Homes at 1 on free** is not a cost constraint (a free home costs 1.6 cents a month). It is the+ natural upgrade trigger: the second house is a household with an office or a parent's place, and+ that is a person who has already decided the product is worth something.+- **Turns at 1,000 free** covers roughly 33 agent conversations a day. On the default free LLM+ chain that costs the platform nothing; on Sonnet 5 it would be $22.83, which is why the ceiling+ exists at all. Pro's 15,000 is $342 at Sonnet prices and $0 on the default chain, so the number+ to watch is the paid-model mix, not the turn count.+- **Voice at 300 minutes free** is five hours of speech a month. It costs nothing today; the+ number is an abuse ceiling, and it should move the day a paid speech lane becomes the default.+- **Seats at 3 free** is a household. 15 on Pro is a small office. A hotel is an override, not a+ tier, which is exactly the point of the override row.+- **Retention at 90 days free** deliberately equals the platform default, so no existing home is+ retroactively over its ceiling the day this ships. Pro's 365 is the compliance answer;+ 3,650 is the schema's hard maximum and promising more would be a promise the database refuses.++The `holder` badge intentionally carries the same base numbers as `user`: holding $THREE raises+quotas through the ladder's existing `rateMultiplier` (2x Bronze through 10x Genesis) rather than+through a second set of thresholds. A Genesis holder therefore gets 10 homes and 10,000 turns+without any of that being modelled twice.++### Applying a number++Every limit is env-overridable as `HOME_LIMIT_<TIER>_<DIMENSION>` in upper snake case:++```bash+gcloud run services update three-ws-api --region us-central1 \+ --update-env-vars HOME_LIMIT_PRO_HOMES=25,HOME_LIMIT_USER_AGENT_TURNS=1500+```++`unlimited` and `-1` both mean no limit. An unparseable value is ignored and the default stands,+because a typo that resolved to zero would lock somebody out of their own house. Note+`--update-env-vars`, never `--set-env-vars`, which replaces the whole environment.++---++## Per-account overrides: the enterprise row++Enterprise limits are configurable per account rather than hardcoded, because that is what the+sales conversation is. A hotel does not buy "Pro", it buys 400 rooms and a year of attribution,+and the shape of that deal is known on the call and not at deploy time.++```bash+curl -X POST https://three.ws/api/home/plan \+ -H 'content-type: application/json' \+ -H "x-csrf-token: $CSRF" --cookie "$SESSION" \+ -d '{+ "action": "override",+ "user_id": "…",+ "limits": { "homes": 400, "members": "unlimited", "logRetentionDays": 730 },+ "note": "Hotel group: 400 rooms, one year of attribution. Agreed on the 2026-09-03 call."+ }'+```++Admin session only. Sending `"limits": {}` clears the override and returns the account to its plan.+An unknown dimension is dropped rather than stored, so a typo in a form cannot install a limit+nothing reads. A dimension the deal did not mention keeps its plan value.++The `note` is not decoration: "why does this account have 400 homes" is a question somebody asks+six months after the person who agreed it has moved on, and the answer has to be in the row.++---++## The downgrade path++**A downgrade never disconnects a house.** When a plan change leaves an account with more connected+homes than it covers, the excess are **paused**:++- `home_connections.deactivated_at` and `deactivated_reason` are set. Nothing else changes.+- The row survives. The encrypted access token survives. The action log survives with its lineage.+- `revoked_at` is **not** set. Revoke is the user saying "take my house off this platform" and it+ scrubs the credential irreversibly; a pause is the platform saying "your plan covers fewer of+ these right now" and it must be reversible.+- The oldest homes stay live by default, because they are the ones most likely to be the real+ house, and the user swaps freely at [`/smart-home/plan`](https://three.ws/smart-home/plan).+- **A paused home still answers safety actions.** Locking up, closing a garage or valve and arming+ an alarm work on a paused home exactly as they do on a live one.++Bringing a paused home back while at the limit is refused with a designed message, not a 500,+which is the whole reason a user pauses one first and resumes another.++---++## Counters: one number, not two++`agentTurns` has **no event kind of its own**. A conversation with the agent already writes exactly+one `kind: 'chat'` row into `usage_events` carrying the provider, model, token counts and priced+cost ([`api/chat.js`](../api/chat.js)), and that row is what an invoice would charge for. Minting a+second row beside it would mean two numbers that disagree, and the one on the invoice being wrong.+So a home turn is the same row, distinguished by the `home_id` the chat handler stamps into its+`meta` when a home tool ran.++`voiceMinutes` does get its own kind (`home.voice`), because nothing counted voice before: the TTS+and ASR lanes write no usage events at all. That is a new fact, not a duplicated one.++Reads are cached in Redis per (account, dimension, month) and **seeded from `usage_events`** when+cold, so the cache converges on the authoritative number rather than starting a private tally. A+cache eviction while events are still in the write buffer under-counts for the rest of the month.+That bias is deliberate: a quota that errs must err toward serving the user, and over-counting+would refuse somebody access to their own house over a Redis hiccup.++Without Redis, every read goes straight to `usage_events`. Correct, just slower.++The **quota period is the UTC calendar month.** The platform has no per-user plan billing cycle to+key off (`users.plan` is a column, not a subscription), and inventing one here would be a second+billing clock that drifts from whatever the real one turns out to be. It resets on a date every+user can predict, and it is shown on the plan page with that date.++---++## Where enforcement happens++| Point | File | What it refuses |+|---|---|---|+| Acquisition | [`api/home/index.js`](../api/home/index.js) | a new home past `homes`, **before** any socket is opened. Reconnecting a house the account already has is an update, not an acquisition, so a token rotation is never refused |+| Stream | [`api/home/[id]/stream.js`](../api/home/%5Bid%5D/stream.js) | a new SSE subscriber past `streams`, before any SSE head is written |+| Seats | [`api/home/[id]/members.js`](../api/home/%5Bid%5D/members.js) | an invitation past `members`, counting outstanding invites as well as members, billed to the home's **owner** |+| Retention | [`api/_lib/home/privacy.js`](../api/_lib/home/privacy.js) | raising retention past the plan's ceiling. Never applied retroactively |+| Actions | [`api/home/[id]/call.js`](../api/home/%5Bid%5D/call.js) | an ordinary action on a paused home. **The safety exemption is checked first**, so a safety action is never reached by this code |++Ordinary service calls are **not** metered at all. Actions are cheap; the socket is the cost. A+user can run twenty lights all evening without touching a quota.++There is also a separate, unrelated ceiling: the per-instance backpressure ladder in+[`api/_lib/home/admission.js`](../api/_lib/home/admission.js). That answers "is this instance+full"; this document answers "does your plan cover this". The two compose and neither replaces the+other.++---++## The plan page++[`/smart-home/plan`](https://three.ws/smart-home/plan) shows every dimension whether or not it is+near its ceiling, each with its usage, its limit, the reset date and the reason it is metered. A+quota you only meet at the moment it refuses you is a quota nobody showed you.++It is also where a user swaps which homes are live after a downgrade, and where the two lines a+limit can never touch are stated in words rather than buried in a policy nobody opens.diff --git a/public/changelog.json b/public/changelog.jsonindex 33f017eb8..c7363ca64 100644--- a/public/changelog.json+++ b/public/changelog.json@@ -1,5 +1,5 @@{- "generated_at": "2026-09-03T04:01:57.539Z",+ "generated_at": "2026-09-03T04:06:00.555Z","generated_by": "scripts/build-page-index.mjs from data/pages.json + data/changelog.json","site": {"name": "three.ws",@@ -16,6 +16,16 @@"launch"]},+ {+ "date": "2026-09-03",+ "type": "launch",+ "title": "Docs · Home plans and quotas",+ "summary": "What a connected house costs and what each plan covers, with the two commitments enforced in code rather than promised in prose: a limit never blocks a safety action, so locking up, closing a garage or valve and arming an alarm work over quota and past due; and nothing about the confirmation gate, the action log's integrity or the role system is ever a paid feature.",+ "link": "/docs/home-plans",+ "tags": [+ "launch"+ ]+ },{"date": "2026-09-03","type": "launch",@@ -149,6 +159,17 @@"feature"]},+ {+ "date": "2026-09-03",+ "type": "update",+ "title": "See what your connected homes use, before a limit ever stops you",+ "summary": "Your smart home plan now has a page. It shows every allowance whether or not you are near it: how many homes you have connected, how many people are in each household, how many live screens, how many voice minutes and agent turns you have used this month, and the exact date each one resets. Two things a plan can never do are written on the page itself, because they matter more than any number on it. Locking a door, closing a garage or a water valve and arming an alarm are never refused by a limit, on any plan, in any state, including on a home your plan has paused. And confirmation prompts, your action log and every safety property of household roles are on every plan, free included: safety is not an upgrade. If a plan change ever leaves you with more homes than it covers, nothing is disconnected and nothing is deleted. The extra homes are paused, with their access tokens and their whole history untouched, and you pick which ones are live from the same page.",+ "link": "/smart-home/plan",+ "tags": [+ "feature",+ "improvement"+ ]+ },{"date": "2026-09-03","type": "update",@@ -193,6 +214,16 @@"improvement"]},+ {+ "date": "2026-09-03",+ "type": "update",+ "title": "We tried making your agent a Matter device, measured it, and decided against it for now",+ "summary": "Matter is the standard that lets smart-home gear from different brands work together, and the plan had always been to make a three.ws agent show up as a Matter device so that any smart-home controller could see it, drop it in a room, and use it in an automation. We built it and pointed it at a real Home Assistant to find out whether the idea holds up. It does, technically: the agent paired in under a second over an ordinary network with no Bluetooth and no special radio, Home Assistant listed it as a proper device with a name, a model and a serial number, put it in the living room, and messages went both ways in well under a second. It also held the line that matters most: an automation that asked the agent to unlock a front door was refused and the door stayed locked, because an automation is not a person saying yes, and only a real confirmation from a person opened it. We are still not shipping it, and the honest reason is that it would be a narrower version of something you can already have. The three.ws Home Assistant integration already puts your agent inside your house with the whole conversation available to it, where Matter would offer a switch and a sensor. On top of that, appearing in the big-name smart-home apps needs a certified manufacturer identity we do not hold. The full write-up, every measurement, and the exact conditions that would change our answer are now in the smart-home documentation, so nobody has to guess or start over.",+ "link": "/docs/smart-home",+ "tags": [+ "docs"+ ]+ },{"date": "2026-09-03","type": "update",diff --git a/public/changelog.xml b/public/changelog.xmlindex c0c3c7b66..6bee5e141 100644--- a/public/changelog.xml+++ b/public/changelog.xml@@ -14,6 +14,14 @@<category>launch</category><description>Sharing a connected house without sharing a login: the five roles and what each one may do, per-member entity scopes that narrow the house a member can even see, how invitations are issued and accepted, what happens to somebody's access when they leave, and the rule everything hangs off, that a guest can never confirm an action that opens a building.</description></item>+ <item>+ <title>Docs · Home plans and quotas</title>+ <link>https://three.ws/docs/home-plans</link>+ <guid isPermaLink="false">2026-09-03:Docs · Home plans and quotas</guid>+ <pubDate>Thu, 03 Sep 2026 12:00:00 GMT</pubDate>+ <category>launch</category>+ <description>What a connected house costs and what each plan covers, with the two commitments enforced in code rather than promised in prose: a limit never blocks a safety action, so locking up, closing a garage or valve and arming an alarm work over quota and past due; and nothing about the confirmation gate, the action log's integrity or the role system is ever a paid feature.</description>+ </item><item><title>Docs · Home privacy and retention</title><link>https://three.ws/docs/home-privacy</link>@@ -118,6 +126,14 @@<category>feature</category><description>The /smart-home page now takes you from "I have a Home Assistant somewhere" to a connected house, and it is honest at every step. An address that only exists on your home network is refused the moment you type it, with the two real ways round it, instead of spinning for fifteen seconds. A rejected token says so and puts the cursor back in the token box. A house that stops answering keeps its rooms on screen, marked stale with how long ago it last replied, rather than blanking out. Your access token is sent once, encrypted at rest, and never comes back to the page: it is not in your browser storage, not in a URL, and not in any response. Disconnecting says plainly that the stored token is erased and reminds you to delete it in Home Assistant too.</description></item>+ <item>+ <title>See what your connected homes use, before a limit ever stops you</title>+ <link>https://three.ws/smart-home/plan</link>+ <guid isPermaLink="false">2026-09-03:See what your connected homes use, before a limit ever stops you</guid>+ <pubDate>Thu, 03 Sep 2026 12:00:00 GMT</pubDate>+ <category>feature</category>+ <description>Your smart home plan now has a page. It shows every allowance whether or not you are near it: how many homes you have connected, how many people are in each household, how many live screens, how many voice minutes and agent turns you have used this month, and the exact date each one resets. Two things a plan can never do are written on the page itself, because they matter more than any number on it. Locking a door, closing a garage or a water valve and arming an alarm are never refused by a limit, on any plan, in any state, including on a home your plan has paused. And confirmation prompts, your action log and every safety property of household roles are on every plan, free included: safety is not an upgrade. If a plan change ever leaves you with more homes than it covers, nothing is disconnected and nothing is deleted. The extra homes are paused, with their access tokens and their whole history untouched, and you pick which ones are live from the same page.</description>+ </item><item><title>See, export and delete everything a connected home stores</title><link>https://three.ws/docs/home-privacy</link>@@ -150,6 +166,14 @@<category>feature</category><description>There is a new page at /drive built for a car screen instead of a desk. Your agent is on it full size, you hold one big button and talk, and it answers out loud in its own voice with its face moving. It shows you one line of what it said rather than a wall of chat, because you are driving. It starts dark, because a bright panel at night is glare, and it will switch to a day palette on one press or one sentence. The keyboard stays out of the way while you are moving: if your browser can tell how fast you are going, text entry locks itself the moment you pull away and comes back when you have properly stopped. A few things you say never leave the car at all, so "repeat that", "stop talking", "louder" and "night mode" happen instantly, while "stop at the next charger" still goes to your agent like any other question. It works today on a head unit browser, on a phone in a cradle, and on Android Automotive. The Apple CarPlay version is built and waiting on Apple's approval for voice assistants in the car. One thing this fixed for everyone: an avatar used to answer in silence if you were not signed in, and now it always has a voice.</description></item>+ <item>+ <title>We tried making your agent a Matter device, measured it, and decided against it for now</title>+ <link>https://three.ws/docs/smart-home</link>+ <guid isPermaLink="false">2026-09-03:We tried making your agent a Matter device, measured it, and decided against it for now</guid>+ <pubDate>Thu, 03 Sep 2026 12:00:00 GMT</pubDate>+ <category>docs</category>+ <description>Matter is the standard that lets smart-home gear from different brands work together, and the plan had always been to make a three.ws agent show up as a Matter device so that any smart-home controller could see it, drop it in a room, and use it in an automation. We built it and pointed it at a real Home Assistant to find out whether the idea holds up. It does, technically: the agent paired in under a second over an ordinary network with no Bluetooth and no special radio, Home Assistant listed it as a proper device with a name, a model and a serial number, put it in the living room, and messages went both ways in well under a second. It also held the line that matters most: an automation that asked the agent to unlock a front door was refused and the door stayed locked, because an automation is not a person saying yes, and only a real confirmation from a person opened it. We are still not shipping it, and the honest reason is that it would be a narrower version of something you can already have. The three.ws Home Assistant integration already puts your agent inside your house with the whole conversation available to it, where Matter would offer a switch and a sensor. On top of that, appearing in the big-name smart-home apps needs a certified manufacturer identity we do not hold. The full write-up, every measurement, and the exact conditions that would change our answer are now in the smart-home documentation, so nobody has to guess or start over.</description>+ </item><item><title>Your home is a household now, and a house sitter still cannot open your front door</title><link>https://three.ws/smart-home</link>diff --git a/public/features.json b/public/features.jsonindex 03b97750e..c6af951c8 100644--- a/public/features.json+++ b/public/features.json@@ -1,5 +1,5 @@{- "generated_at": "2026-09-03T04:01:57.493Z",+ "generated_at": "2026-09-03T04:06:00.542Z","generated_by": "scripts/build-page-index.mjs from data/pages.json","site": {"name": "three.ws",@@ -3307,6 +3307,16 @@"tags": [],"showcase": false},+ {+ "path": "/docs/home-plans",+ "title": "Docs · Home plans and quotas",+ "description": "What a connected house costs and what each plan covers, with the two commitments enforced in code rather than promised in prose: a limit never blocks a safety action, so locking up, closing a garage or valve and arming an alarm work over quota and past due; and nothing about the confirmation gate, the action log's integrity or the role system is ever a paid feature.",+ "added": "2026-09-03",+ "auth": null,+ "indexable": true,+ "tags": [],+ "showcase": false+ },{"path": "/docs/carplay","title": "Docs · three.ws Drive",diff --git a/public/llms-full.txt b/public/llms-full.txtindex 74efdb1bd..66695c2bb 100644--- a/public/llms-full.txt+++ b/public/llms-full.txt@@ -2013,6 +2013,12 @@ URL: https://three.ws/docs/home-privacyEverything three.ws stores about a home you connect, why, for how long, and what removes it: the full inventory, the promise that room names and device states are never persisted, the 90-day action-log window and the control that changes it, the export and deletion paths, the logging rules, and the disclosure text shown at connect and at the voice opt-in.+### Docs · Home plans and quotas++URL: https://three.ws/docs/home-plans++What a connected house costs and what each plan covers, with the two commitments enforced in code rather than promised in prose: a limit never blocks a safety action, so locking up, closing a garage or valve and arming an alarm work over quota and past due; and nothing about the confirmation gate, the action log's integrity or the role system is ever a paid feature.+### Docs · three.ws DriveURL: https://three.ws/docs/carplaydiff --git a/public/llms.txt b/public/llms.txtindex bb3ecff42..ad56237b6 100644--- a/public/llms.txt+++ b/public/llms.txt@@ -371,6 +371,7 @@ Docs, tutorials, and reference.- [Docs · Home security](https://three.ws/docs/home-security): The threat model for a connected house, written about a building rather than a database: what each actor can do and what stops them, why the confirmation gate is the load-bearing control and prompt filtering is depth, the eleven checks that run with every build, the SSRF guard every server-side dial goes through and why a hostname check is not one, the prompt-injection proof that ends by asking a real lock whether it opened, and the residuals accepted on purpose.- [Docs · Home relay threat model](https://three.ws/docs/home-relay-threat-model): What an attacker gets at every position around the socket a LAN-only house dials out through, and what stops them: why the relay carries a fixed list of message types instead of proxying HTTP into a home network, what a stolen install token is and is not worth, why the allowlist is enforced again inside the house so a compromised relay widens nothing, and the residuals accepted on purpose.- [Docs · Home privacy and retention](https://three.ws/docs/home-privacy): Everything three.ws stores about a home you connect, why, for how long, and what removes it: the full inventory, the promise that room names and device states are never persisted, the 90-day action-log window and the control that changes it, the export and deletion paths, the logging rules, and the disclosure text shown at connect and at the voice opt-in.+- [Docs · Home plans and quotas](https://three.ws/docs/home-plans): What a connected house costs and what each plan covers, with the two commitments enforced in code rather than promised in prose: a limit never blocks a safety action, so locking up, closing a garage or valve and arming an alarm work over quota and past due; and nothing about the confirmation gate, the action log's integrity or the role system is ever a paid feature.- [Docs · three.ws Drive](https://three.ws/docs/carplay): How a three.ws agent rides in the car: the CarPlay entitlement categories measured, why Apple's voice-based conversational category is the one that fits and why it grants no drawing surface, the open-source in-car projects worth adopting and the copyleft ones that are not, and how the /drive surface, the native CarPlay scene, and an open head unit share one implementation.- [Docs · Terminal avatar](https://three.ws/docs/tty-avatar): The @three-ws/tty-avatar package: any three.ws avatar or agent body rendered live in a terminal by a software rasterizer (truecolor half-blocks, braille, or plain ASCII), procedural moods, and Claude Code hooks that turn it into your coding agent's face.- [Docs · Site load performance](https://three.ws/docs/site-performance): The load-cost rules behind every page that is not /play, each with the Lighthouse measurement that produced it: catalogue grids skip the rows nobody can see, analytics waits for the first idle moment, the CDN bundle ships minified, below-the-fold sections load below the fold, and thumbnails decode off the critical path.