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): record the docs and SDK run and the one live suite it found red
nirholas6ea660cb0735
diff --git a/prompts/finish/home-PROGRESS.md b/prompts/finish/home-PROGRESS.mdindex 29d3f4cb7..8b9af623a 100644--- a/prompts/finish/home-PROGRESS.md+++ b/prompts/finish/home-PROGRESS.md@@ -47,7 +47,7 @@ One section per finished order, newest at the bottom:| 15 privacy and retention | done | 2026-09-03 || 16 test program | open | || 17 a11y, i18n, mobile | open | |-| 18 docs and SDK | open | |+| 18 docs and SDK | docs done, npm publish owner-gated | 2026-09-03 || 19 plans and entitlements | open | || 20 launch readiness | standing | || 21 Matter direct | horizon | |@@ -506,3 +506,90 @@ retention cron as section E of `api/cron/db-retention.js` rather than becoming cthe changelog entry were swept into concurrent agents' commits before this order could stage them(`875e1c828`, `9d82e63d9`, `e6a32da61`, and others); this commit carries the progress record andretires the order file.++## 18. Docs, SDK publish, the home MCP server package (2026-09-03)++**Shipped:** the documentation layer the lane had been skipping, plus one new package. A+standalone MCP server, `packages/home-mcp` (`@three-ws/home-mcp`), gives any assistant the home+tools over stdio with no three.ws account and no reachability problem, because it runs on the+user's own machine; it imports the gate from `@three-ws/home-bridge` rather than keeping a second+copy. READMEs for `packages/home-mcp`, `services/home-relay` and `services/home-satellite`, which+were the three directories breaking the 100% coverage standard and failing `npm run gate` at+`check:claude`. `docs/tutorials/connect-your-home.md`, zero to a working agent in a real house.+`docs/home-relay-threat-model.md`, which three shipped source files already told readers to read+and which did not exist. `docs/smart-home.md` rewritten from a plan into a map of the tree.+`docs/mcp.md` (the five hosted home tools, the gate, and the new package) and+`docs/api-reference.md` (a full Home API section: every route, the role matrix, the confirmation+endpoint's three refusals). `STRUCTURE.md` rows for the surface, the package and both services.+`tests/home-relay-protocol.test.js`, which `scripts/gen-allowlist.mjs` claimed existed as the+staleness guard and did not. Both packages registered in the publish scripts.++**The gate decision for stdio, which the order required be chosen and written down:** a guarded+action is REFUSED. `confirmed: true` represents a human saying yes; an MCP stdio server has no+human in it, carries no session and has no browser to prompt in, so anything it accepted as a+confirmation would be model output wearing a person's clothes. No tool schema has a confirmation+field, so a model cannot set one. The only way through is `HOME_ALLOWED_ENTITIES`, set by hand by+whoever starts the process, per entity, never per domain, and no tool can widen it. The refusal+names the entity, the risk, and the two places a person can actually confirm. Documented in+`packages/home-mcp/README.md` and in `src/lib/gate.js`.++**Measured** (house: `scripts/home-test-instance.mjs --up --onboard --seed`, Home Assistant+2026.9.0, one floor, four areas, 122 entities, two scenes, four locks):++- `packages/home-mcp/test/gate-live.test.mjs`: 13 tests, all passing. It spawns the real entry+ point as a child process, speaks MCP over stdin/stdout the way a desktop client does, and then+ asks Home Assistant itself whether the door moved. `lock.front_door` stayed `locked` through a+ bare unlock, through `{confirmed:true}`, `{confirm:'yes'}` and+ `{confirmed:true,user_said_yes:true}` smuggled into service data, and through an allowance+ naming a different lock. It unlocked only under `HOME_ALLOWED_ENTITIES=lock.front_door`, and+ `lock.lock` ran with no allowance at all.+- Every code example in both READMEs executed against that instance: `home-bridge`'s connect,+ graph, service call, `activate`, gate, allow list, no-match and MCP channel (29 real tools, and+ a tool call that turned on a real light); `home-mcp`'s stdio client example, which printed the+ real rooms and `refused: true`. The `claude mcp add ... -- npx -y @three-ws/home-mcp` line was+ run and `claude mcp list` reported the server Connected, then it was removed.+- `npx vitest run packages/home-bridge`: 41 passed. `tests/home-relay-protocol.test.js`: passing.+- `npm run audit:docs`: clean, 1493 files. `npm run check:docs-search`: index current (643 docs,+ 8097 sections). `npm run check:claude`: OK (it had been failing on the three missing READMEs).+ `npm run check:rules`: clean.+- `npm run publish:packages:dry` and `npm run publish:mcp:dry`: both clean, both new packages+ reported as "would publish". `npm pack --dry-run`: `@three-ws/home-bridge` 12 files / 28.7 kB,+ `@three-ws/home-mcp` 12 files / 17.3 kB. No test files, no fixtures, no tokens in either.++**Deviations from the order file, all corrected in place:**++- The public routes are `/smart-home` and `/smart-home/:id`, not `/home` and `/home/:id`. `/home`+ is a 301 to `/`, so a doc pointing at it would have sent every reader to the homepage. The+ refusal text in `packages/home-mcp/src/lib/gate.js` points at `/smart-home`.+- The order said `home-mcp` wraps order 04's handlers. It cannot: those handlers are+ account-scoped, and this server has no account, no session and no database. It wraps+ `@three-ws/home-bridge` directly and imports the gate from it, which is the same rule enforced+ by the same code. `list_entities` asks `classifyMcpCall` whether an entity is guarded rather+ than keeping a second list of guarded domains.+- `docs/smart-home.md` did not need its status corrected downward. It said "phase 1 built" and+ that was true; what it needed was the opposite edit, replacing a build plan with what the tree+ now holds.+- The voice loop shipped while this order was being written (`/voice/home`,+ `src/voice/home-voice.js`). The tutorial's voice section and the doc's shipped table were+ rewritten against it rather than against the satellite alone.++**Left open, both named and neither owned by this order:**++1. **The npm publish, which is owner-gated.** Everything is staged and both dry runs are clean.+ The exact commands are in the report and are `npm run publish:packages -- --only home-bridge`+ and `npm run publish:mcp -- --only home-mcp`. The order file stays on disk until that lands.+2. **`tests/home-runtime-live.test.js` is red, and this order did not cause it.** `e6a32da61`+ added `resolveDialPin` to `api/_lib/home/runtime.js`, which routes every acquisition through+ `assertDialableHomeUrl`. That refuses a loopback address, and this file's own header documents+ pointing it at `http://127.0.0.1:<port>` from the local harness. Five tests fail with+ `127.0.0.1 is a private address`. Not fixed here on purpose: whether the home lane's SSRF guard+ should relax outside production is a security decision belonging to the order that added it,+ and `api/_lib/ssrf.js` already carries an unused `IS_DEV` for exactly that shape of allowance.+ **Owner: order 11.**++**Commits:** the tutorial, the three READMEs, the threat model, the `home-mcp` package and its+tests, the `docs/mcp.md` and `docs/api-reference.md` sections, the `STRUCTURE.md` rows, the+`data/pages.json` entry, the changelog entry and the publish-script registrations were all swept+into concurrent agents' commits before this order could stage them (`ad2e5f3f8`, `b9060b962`,+`f9a8780d8`, `f9d09844c` and others). `17ac4d8d4` carries the regenerated page index; this commit+carries the progress record.