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): document the smart-home surface and record the build's progress
nirholas858a2f86bc0a
diff --git a/docs/ops/wallet-key-migration.md b/docs/ops/wallet-key-migration.mdindex a80eef37d..c7dcc5fc7 100644--- a/docs/ops/wallet-key-migration.md+++ b/docs/ops/wallet-key-migration.md@@ -317,6 +317,41 @@ gcloud run services update-traffic three-ws-api --region us-central1 \--project aerial-vehicle-466722-p5 --to-revisions <prior revision>=100```+## The other ciphertext under this key: connected homes (2026-09-03)++Everything above is about custodial wallet secrets. Since 2026-09-03 the same+`WALLET_ENCRYPTION_KEY` also seals a second, unrelated class of secret:+`home_connections.access_token_enc`, the Home Assistant long-lived access token a user+hands over when they connect their house (`api/_lib/home/store.js`). A rotation covers+both or it covers neither.++The two failures look nothing alike, so do not reason about one from the other:++| | Custodial wallet secret | Home access token |+|---|---|---|+| What a lost key costs | custody, permanently. The SOL is visible on chain and can never be signed for again | reach, temporarily. Nothing is destroyed |+| How the user recovers | they cannot | they paste a fresh long-lived token and reconnect |+| How you notice | a funded wallet fails to sign, and `stranded_custody` counts it | every connected home goes dark at once, with nothing on chain to notice it by |+| What it is a key to | money | a physical building |++The last row is the reason it gets this primitive at all: a home token unlocks a front+door, so it is stored like a wallet key from its first write, never as a hash (we have to+replay it on every socket open) and never in plaintext.++Because a sealed home has no balance to show up in a treasury sweep, it needs its own+reading. Run it alongside the wallet audit at step 3 of the rotation above:++```sh+node scripts/audit-home-credential-health.mjs+```++It is read-only, decrypts in memory only, never prints a token, and carries the same+no-key guard the wallet audit learned: with no decryption key configured it exits 3 rather+than reporting every home as sealed. Exit 1 means something really is sealed. If EVERY+home fails to decrypt, that is one wrong key for the deployment, not a fleet of separately+broken houses: put the outgoing key in `WALLET_ENCRYPTION_KEY_PREVIOUS` before telling+anybody to reconnect.+## Takeaways- **A key rotation must carry the old key forward, or accompany a sweep.** This is now@@ -335,6 +370,9 @@ gcloud run services update-traffic three-ws-api --region us-central1 \pool feeds.- `api/_lib/agent-pumpfun.js` — the self-heal + fund-safety guard.- `scripts/rekey-stale-launch-wallets.mjs` — the batch re-key tool.+- `scripts/audit-home-credential-health.mjs`: the same reading for connected homes, whose+ tokens sit under the same key (see the section above). Exits 3 with no key, 1 when a+ home is sealed.- `scripts/audit-custodial-key-health.mjs`: read-only sweep of every custodial wallet,how many still decrypt, how much SOL sits behind the ones that do not, and whichaddresses they are. Needs `DATABASE_URL` and `WALLET_ENCRYPTION_KEY`; it exits 3 ratherdiff --git a/docs/smart-home.md b/docs/smart-home.mdindex 73c730082..7a77e4aed 100644--- a/docs/smart-home.md+++ b/docs/smart-home.md@@ -211,9 +211,28 @@ Each phase is shippable on its own and none of them block on the next.[`packages/home-bridge/`](../packages/home-bridge) is the client: the WebSocket channel forstate and actions, the MCP channel for the user's curated tools, the room graph, intentresolution against the house's own scenes, and the physical-action gate in front of both. See-[its README](../packages/home-bridge/README.md). What remains in this phase is product-surface, not protocol: the connection record, a `/home` connect flow, and registration of the-home tools into the existing agent tool catalog.+[its README](../packages/home-bridge/README.md).++The connection record landed on 2026-09-03 and is the first piece of this phase that is+product rather than protocol. `home_connections` holds one row per connected house: the+normalized base URL, the Home Assistant long-lived token encrypted with the same+AES-256-GCM primitive as a custodial wallet key (`api/_lib/secret-box.js`), a sha256+fingerprint so a re-connect is idempotent and a token rotation is detectable without+decrypting anything, and the capabilities that were MEASURED at connect rather than+assumed. `home_entity_grants` holds the standing allowances behind the physical-action+gate, per entity and never per domain, because letting the agent open the office door is+not letting it open the front door. `home_action_log` records every write the platform+performs against a house, with the gate's verdict and the resolved targets, so an owner+can answer "what did my agent do in my house last Tuesday".++`api/_lib/home/store.js` is the only module that touches those tables, and+`getDecryptedToken` is the only function in the codebase that returns a plaintext home+credential. `api/_lib/home/verify.js` opens a real bridge at connect time and measures what+the instance can actually do. Covered by `tests/home-store.test.js`, whose live tier runs+against a real database and a real Home Assistant.++What remains in this phase is the rest of the surface: a `/home` connect flow and+registration of the home tools into the existing agent tool catalog.**Phase 2: the 3D home.** `/home` renders a live scene from the entity registry: areasbecome rooms, lights become lights, and the agent stands in it. Scene lighting is driven by