Skip to content

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

docs(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.md
index 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 which
addresses they are. Needs `DATABASE_URL` and `WALLET_ENCRYPTION_KEY`; it exits 3 rather
diff --git a/docs/smart-home.md b/docs/smart-home.md
index 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 for
state and actions, the MCP channel for the user's curated tools, the room graph, intent
resolution 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: areas
become rooms, lights become lights, and the agent stands in it. Scene lighting is driven by