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): retire order 17 with the 15/15 a11y run, a clean i18n lint, and the e2e baseline

nirholas546870550222
diff --git a/prompts/codex/02-i18n-lint-clean.md b/prompts/codex/02-i18n-lint-clean.md
index 11b7ca119..b55e35287 100644
--- a/prompts/codex/02-i18n-lint-clean.md
+++ b/prompts/codex/02-i18n-lint-clean.md
@@ -20,7 +20,7 @@ Do all work and commits inside `/workspaces/wt-codex-i18n` on the `codex/i18n-li
three.ws ships 87 locales. `npm run i18n:lint` fails with about 15,700 problems, almost all
`missing key` or `empty value`, so non-English visitors see English fallbacks or blanks. The last
-item blocking the Home accessibility order (`prompts/finish/311-home-17-a11y-i18n-mobile.md`) is
+item blocking the Home accessibility order (home campaign order 17, retired 2026-09-29) was
this lint. Make it pass.
Measured worst locales (count of missing keys): zu, ps, mt, ha, af (1,179 each), lt (1,133),
diff --git a/prompts/finish/311-home-17-a11y-i18n-mobile.md b/prompts/finish/311-home-17-a11y-i18n-mobile.md
deleted file mode 100644
index 354352d6e..000000000
--- a/prompts/finish/311-home-17-a11y-i18n-mobile.md
+++ /dev/null
@@ -1,212 +0,0 @@
-# 17. Accessibility, 87 locales, mobile and PWA
-
-**How to run this:** paste this whole file into a fresh Claude Code chat opened in
-`/workspaces/three.ws`. Read [00-CONTEXT.md](_context/home-00-CONTEXT.md) first. Orders
-[05](302-home-05-connect-flow.md) to [08](305-home-08-voice-loop.md) must have landed.
-
-## State on 2026-09-09: one item left, and it is not code
-
-**Do not re-run this order from the top.** Read
-[_context/home-PROGRESS.md](_context/home-PROGRESS.md), entry 17, first.
-
-Everything in this file is done and verified against a real Home Assistant except one line of
-the Definition of done: `npm run i18n:lint` is not clean. `tests/e2e/home-a11y.spec.js` is
-15 tests and passes 15/15 (axe on all three views, the keyboard-only walk, the live regions,
-colour-independence, stale contrast, the four breakpoints, the 44px floor on an emulated phone,
-Fahrenheit, RTL through the real Arabic catalog, untranslated device names, reduced motion, the
-stray-tap-proof confirmation). Six real defects were found and fixed getting there; the entry
-lists them.
-
-**Corrected 2026-09-10: the premise below was wrong in its first half and right in its second.**
-Translation backends ARE reachable from a session, and gcloud does not need an interactive
-login: `gcloud auth print-access-token` mints a token in this workspace today (the binary is not
-on PATH, call it at `/home/codespace/google-cloud-sdk/bin/gcloud`). What is actually missing is
-THROUGHPUT, not auth or reachability.
-
- node scripts/read-service-env.mjs '^NVIDIA_API_KEY$' # the key is on the Cloud Run service
- node scripts/i18n-translate.mjs --provider=nvidia --locales=<shard> --concurrency=3
- node scripts/i18n-translate.mjs --provider=nvidia --locales=<shard> --repair
- node scripts/i18n-translate.mjs --lint # ground truth, always
-
-That works and was used on 2026-09-10 to take Spanish to a clean 19,875-key catalog and to fill
-a large part of the rest. But every free lane is throttled per key and they cannot finish 84
-locales in a session:
-
-- **NVIDIA NIM** is the working lane, at roughly 27 keys/min per process. Running six processes
- against it does NOT go six times faster: the key is throttled per account, all six collapsed
- into `429 Too Many Requests`, and the whole batch stalled. Two processes at `--concurrency=3`
- is about the ceiling.
-- **Groq** authenticates and translates well, but its free tier is 200,000 tokens per DAY, which
- is a few hundred keys. It is a useful second lane, not a bulk one.
-- **OpenAI** is `billing_not_active`.
-- **Vertex AND the Generative Language API are both denied project-wide** by the same
- `Lightning dunning decision is deny` billing hold, so `GOOGLE_API_KEY` is no help either.
-
-Vertex is the lane that can actually do this in one pass, because it is billed to the GCP credit
-pool with no free-tier quota to exhaust. So the single owner action for this order is **not**
-`gcloud auth login`; it is **clearing the GCP billing hold**, which is the same action that
-unblocks orders 903 (fact-check `groundedSearch`) and 907 (the OKX bot reply lane). Three orders,
-one payment.
-
-Until it clears, the free lanes make real progress and should be left grinding: the run is
-resumable, idempotent, and an incomplete locale is held out of `manifest.json` rather than shipped
-half-translated, so stopping mid-way is safe.
-
-**Measured throughput, so nobody re-derives it.** Turning off the reasoning model's chain of
-thought is worth more than any amount of parallelism and was the single biggest win
-(`d14497d11`): on a five-string chunk, 40 output tokens in 1.1s with thinking off against
-hundreds of tokens and tens of seconds with it on. Even so, NVIDIA's free tier will not absorb a
-bulk run. Six processes collapsed into `429 Too Many Requests`; three at `--concurrency=4` still
-drew `429` plus `503 Service temporarily overloaded`, and a chunk that fails takes its whole
-locale's pass with it, so an over-parallel run can spend an hour and finish nothing. One process
-at `--concurrency=2` is the sustainable shape. Budget on the order of a day of wall clock for the
-remaining catalog on free lanes, against roughly one pass on Vertex. When it lands: confirm `npm run i18n:lint` is clean,
-delete the `publishLocale` helper in `tests/e2e/home-a11y.spec.js` (the RTL and never-translate
-tests can read the real manifest once a locale is complete), re-run the suite, and retire this
-file per the section at the bottom.
-
-Also never produced, and never claimed: a VoiceOver or NVDA transcript. No screen reader exists
-in this environment. The live regions are asserted mechanically instead; see the entry.
-
----
-
-## Binding operating clause
-
-Finish 100%. Never end with a question or an unexecuted plan. All CLAUDE.md hard rules apply: no
-mocks, no fake data, no TODOs, no stubs, no em-dash or en-dash, explicit-path commits, pushes and
-production deploys owner-gated.
-
-**Nothing in this file is a status claim to trust.** Step 0 re-measures.
-
----
-
-## Step 0: re-derive the current state
-
-```bash
-ls public/locales | wc -l # the locale count to match
-npm run i18n:lint
-head -30 tests/e2e/a11y-top-pages.spec.js # the existing axe gate and its rule sets
-grep -n "priority" data/pages.json | head -3
-npx playwright test tests/e2e/a11y-top-pages.spec.js 2>&1 | tail -10
-```
-
-## Why accessibility is load-bearing here specifically
-
-A voice-controlled home is, for a lot of people, an assistive technology. Someone who cannot
-easily reach a light switch is exactly the user for whom this product is not a convenience.
-Shipping a home controller that a screen-reader user cannot operate would be a particular kind of
-failure, and it is also the case where the 2D fallback from order 06 stops being a nicety.
-
-## The accessibility bar
-
-WCAG 2.1 AA, enforced by the existing axe gate (`wcag2a`, `wcag2aa`, `wcag21aa` rule sets, no
-best-practice rules, so it stays a hard gate and not a taste argument). Add every home route to
-that spec's page list.
-
-Beyond what axe can see, and each verified by hand:
-
-| Requirement | Verified by |
-|---|---|
-| The whole lane is operable by keyboard alone | walk connect, act, confirm, floorplan, disconnect with no mouse |
-| Focus is visible at every step and never trapped | including inside the 3D canvas and the confirmation card |
-| The confirmation card takes focus when it appears and announces itself | it is the safety control; a user must not be able to miss it |
-| Screen reader announces state changes | a light turning on, a home going stale, a confirmation pending. Use a polite live region; the confirmation uses assertive. |
-| The 3D scene has a complete non-visual equivalent | order 06's 2D fallback plus a semantic room and device list. A canvas is opaque to a screen reader, so the fallback is the accessible path, not a downgrade. |
-| Nothing depends on colour alone | locked versus unlocked, on versus off, stale versus live all carry a shape or a label |
-| Reduced motion respected | `prefers-reduced-motion` disables scene transitions and any animation |
-| Target sizes | 44px minimum on touch for every control, including in the floorplan editor |
-| Contrast | AA on every state, including the desaturated stale state, which is the one most likely to fail |
-
-## Internationalisation
-
-87 locales exist. Everything user-visible goes through the existing extraction path.
-
-- `npm run i18n:extract` then `npm run i18n:translate`, then `npm run i18n:lint` clean.
-- **Entity names, area names and scene names are never translated.** They are the user's own
- words. Make sure the extractor does not capture them and that no string concatenation puts a
- translated fragment inside a user-supplied name.
-- Plurals and number formatting through the existing i18n mechanism, not string concatenation.
- "3 rooms" and "1 room" both come from the catalog.
-- Temperature units follow the Home Assistant instance's own configuration, which it reports.
- Never assume Celsius and never guess from the locale: read what the house says.
-- RTL: the connect flow, the manage view, the floorplan editor and the scene all work in an RTL
- locale. Test with a real RTL locale from `public/locales`, not with a CSS override.
-- Voice (order 08): the language of the wake word and the ASR lane follows the existing
- `TALK_LANGUAGES` mechanism in `src/voice/talk-languages.js`. Do not add a second language store.
-
-## Mobile
-
-The phone is a primary surface here, not a secondary one. Someone standing in a doorway is on a
-phone.
-
-- 320px, 375px, 768px and 1440px all correct, on every state of orders 05, 06, 07.
-- The 3D scene holds its frame budget on a mid-range phone or routes to the fallback automatically
- and says so.
-- One-handed reach: the primary action on each screen is in the lower half.
-- The confirmation card is unmissable on a small screen and cannot be dismissed by an accidental
- tap. It requires a deliberate action.
-- Safe areas respected on notched devices.
-- Installable as a PWA if the platform already has a manifest path; if it does not, say so and
- do not invent one for this lane alone.
-- Wake-lock behaviour for a wall display: state the decision. A kitchen tablet showing the home
- scene should not sleep mid-use, and a phone should not be held awake by a background tab.
-
-## Tasks
-
-| # | Task |
-|---|---|
-| 1 | Add every home route to `tests/e2e/a11y-top-pages.spec.js` (or the lane's own axe spec) and fix every violation. |
-| 2 | The keyboard walkthrough, the focus management on the confirmation card, and the live regions. |
-| 3 | The semantic non-visual equivalent of the 3D scene. |
-| 4 | Reduced motion, colour-independence, target sizes, contrast on the stale state. |
-| 5 | Full i18n extraction and lint, with the never-translate rule for user data. |
-| 6 | Temperature units from the instance. |
-| 7 | RTL pass. |
-| 8 | The four breakpoints on every state, plus the one-handed and safe-area work. |
-| 9 | The wake-lock decision, implemented and documented. |
-
-## Definition of done
-
-- [ ] axe passes on every home route with the `wcag2a`, `wcag2aa`, `wcag21aa` rule sets. Paste the run.
-- [ ] A recorded keyboard-only walkthrough of connect, act, guarded confirm, and disconnect.
-- [ ] A screen-reader transcript (VoiceOver or NVDA) of: a light turning on, a home going stale, and a confirmation appearing. The confirmation must be announced assertively.
-- [ ] The 2D fallback is operable by screen reader and can control the house. Recorded.
-- [ ] `prefers-reduced-motion: reduce` disables scene animation. Screenshot the setting and the behaviour.
-- [ ] Contrast checked on the stale and desaturated states specifically, with the measured ratios.
-- [ ] `npm run i18n:lint` clean. Paste it.
-- [ ] A user-supplied entity name is untouched in a non-English locale. Screenshot in two locales.
-- [ ] A Fahrenheit-configured Home Assistant shows Fahrenheit regardless of browser locale. Screenshot both.
-- [ ] An RTL locale renders connect, manage, scene and floorplan correctly. Four screenshots.
-- [ ] All states at 320px, 375px, 768px, 1440px. The screenshot set.
-- [ ] The confirmation card cannot be dismissed by a stray tap on a phone. Demonstrate.
-- [ ] `npx playwright test tests/e2e/` passes with no new failures.
-- [ ] `npm run check:rules -- --paths <your files>` clean.
-
-## Never blocked
-
-| Blocker | Do this |
-|---|---|
-| No screen reader available in this environment | Use the platform's own tooling where possible and say exactly what you could and could not verify. Never claim a screen-reader pass you did not perform. |
-| axe flags something inside the 3D canvas | A canvas is not accessible by nature; the fallback is the answer, and the canvas gets `aria-hidden` with the equivalent content adjacent. Do not suppress the rule. |
-| The i18n extractor picks up entity names | Fix the call site so the user's data is passed as an interpolated value, never as part of a translatable string. |
-| 87 locales seems like a lot of new strings | The pipeline handles it (`i18n:translate`). Your job is to make sure every string goes through it, not to translate by hand. |
-| A phone cannot hold the frame budget | Route it to the fallback automatically, tell the user why in one sentence, and record the device class in your report. |
-
-## Report format
-
-1. The axe run.
-2. The keyboard and screen-reader recordings and transcripts.
-3. The reduced-motion and contrast evidence.
-4. The i18n lint output and the two-locale entity-name screenshots.
-5. The temperature-unit screenshots.
-6. The RTL set and the four-breakpoint set.
-7. Anything in this file you found to be wrong, and what you changed it to.
-
-## Retire this prompt when it is done (required)
-
-Verify every line against real output, append to `prompts/finish/_context/home-PROGRESS.md`, commit with
-explicit paths, and delete this file in that commit:
-
- git rm prompts/finish/311-home-17-a11y-i18n-mobile.md
-
-Never delete it on a partial.
diff --git a/prompts/finish/_context/home-00-CONTEXT.md b/prompts/finish/_context/home-00-CONTEXT.md
index 077da0bd0..dd0b26122 100644
--- a/prompts/finish/_context/home-00-CONTEXT.md
+++ b/prompts/finish/_context/home-00-CONTEXT.md
@@ -182,7 +182,7 @@ Run in order within a lane; lanes 1 to 4 are mostly parallelizable once lane 1 l
| 14 | [Reliability and the scale envelope](../309-home-14-reliability-scale.md) | enterprise |
| 15 | [Privacy, retention, export and deletion](home-15-privacy-retention.md) | enterprise |
| 16 | [The test program: e2e, HA version matrix, live harness](../310-home-16-test-program.md) | quality |
-| 17 | [Accessibility, 87 locales, mobile and PWA](../311-home-17-a11y-i18n-mobile.md) | quality |
+| 17 | Accessibility, 87 locales, mobile and PWA (home campaign order 17, retired 2026-09-29; the record is entry 17 in [home-PROGRESS.md](home-PROGRESS.md)) | quality |
| 18 | [Docs, SDK publish, the home MCP server package](../312-home-18-docs-and-sdk.md) | quality |
| 19 | [Plans, entitlements and quotas](../313-home-19-plans-entitlements.md) | commercial |
| 20 | [Launch readiness: the go/no-go](../314-home-20-launch-readiness.md) | launch |
diff --git a/prompts/finish/_context/home-PROGRESS.md b/prompts/finish/_context/home-PROGRESS.md
index f63c0116b..083c6bc5d 100644
--- a/prompts/finish/_context/home-PROGRESS.md
+++ b/prompts/finish/_context/home-PROGRESS.md
@@ -46,7 +46,7 @@ One section per finished order, newest at the bottom:
| 14 reliability and scale | done | 2026-09-09 |
| 15 privacy and retention | done | 2026-09-03 |
| 16 test program | done | 2026-09-09 |
-| 17 a11y, i18n, mobile | a11y and mobile done, 84 locales need a backend, see entry | 2026-09-09 |
+| 17 a11y, i18n, mobile | done, retired (screen-reader transcript not producible here, asserted mechanically) | 2026-09-29 |
| 18 docs and SDK | docs done, npm publish owner-gated | 2026-09-03 |
| 19 plans and entitlements | built and verified, browser journeys green, price owner-gated | 2026-09-09 |
| 20 launch readiness | standing | |
@@ -3034,3 +3034,97 @@ recovery path missing: `onConnectSuccess` already stored `connected`.
**Left open:** the campaign, still. This clears blocking finding 1 only. Findings 2 (order 17's
translation) and 3 (orders 17 and 19 open) stand, and order 20 cannot be re-run until they are
retired. The e2e spec has NOT been re-run against a live container from this session.
+
+## 17. Accessibility, 87 locales, mobile and PWA: retired (2026-09-29)
+
+**Shipped:** the last open line of order 17 is closed and the order file is deleted. `npm run
+i18n:lint` passes on all 84 catalogs, `public/locales/manifest.json` lists all 85 languages, and
+`tests/e2e/home-a11y.spec.js` passes 15/15 with the `publishLocale` manifest mock gone
+(`b81fa6d78`): the RTL and never-translate tests now reach Arabic through the real manifest and
+the committed `ar.json`, nothing routed. The lint had regressed after `afdf6ea12` made it clean:
+`c8f2cde3c` and `5abee605c` added 37 English keys (airdrop checker, contributors, derivatives) and
+brought only `es` up to date, so it failed with 3,071 missing keys and the completeness gate cut
+the switcher to English alone, which also broke the RTL test. The 37 keys were filled in the
+other 83 locales on the NVIDIA lane (`a96e7e591`, `2af205a16`; additive only, 2,590 keys added
+in the last commit, 0 changed, 0 removed). Vertex still answers `403` in this workspace; Groq and
+the OpenRouter free model were tried as extra lanes and both throttled, so NVIDIA alone did it,
+two processes, about 75 minutes.
+
+Three things stood between the order and a green run, each fixed at the root:
+
+1. **The lane could not boot.** Vite's watcher tried to watch the ~250,000 files in the nested
+ agent checkouts under `.claude/worktrees/` and died with `ENOSPC: System limit for number of
+ file watchers reached`, killing the API proxy mid global setup. It skips them now
+ (`577c786c0`), and a server with hot reload off (every e2e run) does not watch at all
+ (`f2c8ac2ff`), because the editor's own watcher holds about 430,000 of the 524,288 inotify
+ watches on this box. The main Playwright config sets `VITE_NO_HMR` for the server it starts.
+2. **Every connect was refused.** Since `433581f82` secret-box binds the database to the key that
+ writes into it, and the lane's per-run random `WALLET_ENCRYPTION_KEY` is not that key, so each
+ connect died on `SecretBoxKeyMismatchError`. The run now takes the bound key through
+ `HOME_E2E_ENC_KEY`, and the global setup compares the one-way fingerprints before anything
+ boots and names the command when they differ (`e179f36a7`, documented in
+ `tests/e2e/README.md`). The fingerprint of the Cloud Run service's key matches the binding
+ (`bound_at 2026-09-16T16:31:20Z`); a random key does not.
+3. **Two site-wide axe failures** on pages outside this lane: `/three-launchpad` fact labels at
+ 4.32:1 (translucent tiles over the `--stroke` grid) and `/prompts` chip counts at 3.29:1
+ (`opacity: 0.7`). Both fixed to AA (`7df581bec`), measured with axe before and after.
+
+**Measured** (the recipe, so nobody re-derives it):
+
+ HOME_E2E_ENC_KEY="$(node scripts/read-service-env.mjs '^WALLET_ENCRYPTION_KEY$' --raw)" \
+ HOME_LIVE=1 HOME_LIVE_NAME=a11y17 HOME_E2E_API_PORT=8188 HOME_E2E_WEB_PORT=3088 \
+ HOME_E2E_SCREENSHOTS=1 npm run test:home:e2e -- tests/e2e/home-a11y.spec.js
+
+- `home-a11y.spec.js`: **15 passed** twice (59.0s, then 1.2m on the final catalog), against Home
+ Assistant 2026.9.4. Screenshots of every test, including the Arabic house read through the real
+ manifest, are in `test-results/home-a11y-*` on this machine and reproducible with the flag above.
+- The whole home lane (`npm run test:home:e2e`, 11 specs, 81 tests): **74 passed, 1 failed, 6
+ did not run** in one invocation. The failure is the product's connect limiter (`homeConnect`,
+ 10 per 10 minutes per user): the page says "too many connection attempts, wait a moment" at the
+ first `home-scene` connect, after ten earlier specs had connected on the same account. Re-run on its own after the
+ window, `home-scene.spec.js` + `home-whose-fault.spec.js`: **11 passed**. So every one of the 81
+ passes; the lane just cannot run end to end in one invocation on one account.
+- `tests/e2e/a11y-top-pages.spec.js`: 46/48 before the contrast fix, **48 passed** after, all six
+ home routes green both times.
+- The rest of `tests/e2e/` under `playwright.config.js` (the 216 non-axe tests): **199 passed, 8
+ failed, 5 skipped, 3 did not run.** Baseline at `b81fa6d78^` in a throwaway worktree, same four
+ specs: 7 of the 8 fail identically there (`crews-hq` directory console 503, `launch-coin-page`
+ x3, `launch-token-flow` x2, `play-photo-mode` webkit with no webkit browser installed). The 8th,
+ `crews-hq` "service is unreachable", passed 3 of 3 re-runs at HEAD on its own; it failed only
+ under the full concurrent run's load. **No new failures.** It could not have been otherwise
+ for that config: `b81fa6d78` touched only `home-a11y.spec.js`, which `playwright.config.js`
+ ignores as a live home spec.
+- `npm run i18n:lint`: `✓` on all 84 locales at 19,968 keys each, `i18n lint passed.`
+- `npx vitest run tests/i18n-markup.test.js tests/i18n.test.js tests/i18n-missing-key.test.js`:
+ 56/56. `npm run i18n:home`: 353 keys, 0 missing, 0 drifted.
+- `npm run check:rules -- --paths <each file>`: clean for every file above.
+
+**Definition of done, line by line:** axe on every home route (tests 1 and 2 plus the six routes
+in the site gate); keyboard-only walk (test 3); the 2D fallback operable and in control
+(`home-scene` "a browser with no WebGL gets a house it can read and operate"); reduced motion
+(test 13); stale contrast measured (test 7); lint clean; entity names untouched in two locales
+(test 12); Fahrenheit (test 10); RTL (test 11); four breakpoints (test 8); stray tap (test 14);
+e2e with no new failures; check:rules clean. **The one exception, unchanged from the entry above
+and never claimed:** no VoiceOver or NVDA exists in this environment, so there is no
+screen-reader transcript. What is proved instead, mechanically, is tests 4 and 5: the assertive
+region carries the whole confirmation question and clears once it is answered, the polite region
+narrates a light going on with the device named.
+
+**Deviations:** none from the order. Two references to the order file were rewritten to name the
+campaign and order (`home-00-CONTEXT.md`, `prompts/codex/02-i18n-lint-clean.md`). Two were left
+on purpose: `00-RETIRED-BY-OWNER.md` lists the filename as the argument to its own `git show`
+recovery command, and the order 20 entry above is history in an append-only file.
+
+**Left open, not this order's:**
+
+1. The home lane trips its own connect limiter when all 11 specs run in one invocation on one
+ account. The limiter is correct product behaviour; the fix belongs in the harness (fewer
+ reconnects in `home-scene.spec.js`, or a second owner account per lane). Owner: order 16's
+ test program.
+2. In the Arabic house, raw Home Assistant states such as `off`, `on`, `closed`, `cool` and
+ `heat` render in English next to translated ones (`مُشغَّل · 71%`). Visible in the RTL
+ screenshot; not asserted by any test yet.
+3. `/api/agents/me` still logs `Missing required env var: S3_PUBLIC_DOMAIN` on the local stack.
+
+**Commits:** `a96e7e591` and `2af205a16` (catalogs and manifest), `577c786c0` and `f2c8ac2ff`
+(watcher), `e179f36a7` (encryption-key preflight), `7df581bec` (contrast), plus this entry.