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(smart-home): let the release matrix write its own published table

nirholas91893eb2dc5b
diff --git a/docs/smart-home.md b/docs/smart-home.md
index e4e2e0e57..497e24d50 100644
--- a/docs/smart-home.md
+++ b/docs/smart-home.md
@@ -401,18 +401,19 @@ per release, and the set is the current stable, the two releases before it, and
release still in contiguous wide use at or above one percent of installs. The floor moves on its
own as the world upgrades.
-Measured 2026-09-03:
+<!-- home-version-matrix:start -->
+Measured 2026-09-09, by `npm run home:matrix`. This table is written by the runner from
+[`docs/ops/home-version-matrix.json`](ops/home-version-matrix.json); do not edit it by hand.
| Version | Share | Connect | Registries | State stream | Service call | Scenes | `mcp_server` | Notes |
|---|---|---|---|---|---|---|---|---|
-| `2026.9` (current stable) | 4.17% | pass (2026.9.0) | pass (1f/4a/62d/92e) | pass (push) | pass (gated) | pass (scene) | pass (29 tools) | exposes via `homeassistant/expose_entity` |
-| `2026.8` (previous release) | 50.41% | pass (2026.8.3) | pass (1f/4a/62d/92e) | pass (push) | pass (gated) | pass (scene) | pass (29 tools) | exposes via `homeassistant/expose_entity` |
-| `2026.7` (previous release) | 13.21% | pass (2026.7.4) | pass (1f/4a/61d/87e) | pass (push) | pass (gated) | pass (scene) | pass (29 tools) | exposes via `homeassistant/expose_entity` |
-| `2025.10` (oldest in wide use) | 1.05% | pass (2025.10.4) | pass (1f/4a/52d/79e) | pass (push) | pass (gated) | pass (scene) | pass (22 tools) | exposes via `homeassistant/expose_entity` |
-
-**Supported range: 2025.10 and newer.** Every capability the platform depends on works across it.
-The floor is where install share falls below one percent, not where the code stops working;
-nothing was found that a 2025.10 house cannot do.
+| `2026.9` (current stable) | 34.19% | pass (2026.9.1) | pass (1f/4a/62d/92e) | pass (push) | pass (gated) | pass (scene) | pass (29 tools) | exposes via `homeassistant/expose_entity` |
+| `2026.8` (previous release) | 23.60% | pass (2026.8.3) | pass (1f/4a/62d/92e) | pass (push) | pass (gated) | pass (scene) | pass (29 tools) | exposes via `homeassistant/expose_entity` |
+| `2026.7` (previous release) | 11.41% | pass (2026.7.4) | pass (1f/4a/62d/92e) | pass (push) | pass (gated) | pass (scene) | pass (29 tools) | exposes via `homeassistant/expose_entity` |
+| `2025.10` (oldest in wide use) | 1.02% | pass (2025.10.4) | pass (1f/4a/52d/79e) | pass (push) | pass (gated) | pass (scene) | pass (22 tools) | exposes via `homeassistant/expose_entity` |
+
+**Supported range: 2025.10 and newer.** Every capability the platform depends on works across it. The floor is where install share falls below one percent, not where the code stops working; nothing was found that a 2025.10 house cannot do.
+<!-- home-version-matrix:end -->
One version difference was found, and it is handled by asking the house rather than by reading
its version number:
diff --git a/package.json b/package.json
index 202ab8658..4448fd5eb 100644
--- a/package.json
+++ b/package.json
@@ -229,7 +229,7 @@
"audit:route-shadowing": "node scripts/audit-route-shadowing.mjs",
"audit:handlers": "node scripts/audit-empty-handlers.mjs",
"audit:x402-catalog": "node scripts/audit-x402-catalog.mjs",
- "gate": "npm run check:conflicts && npm run check:claude && npm run check:vendored && npm run check:model-viewer && npm run check:gcloudignore && npm run check:fetch-timeouts && npm run check:tdz-bootstrap && npm run check:event && npm run check:cron-syntax && npm run check:studio-openapi && npm run test:gate && npm run test:gate-3d && npm run audit:mcp && npm run audit:mcp-golden && npm run audit:mcp-safety && npm run audit:mcp-catalog && npm run audit:mcp-listing && npm run audit:routes && npm run audit:handlers && npm run audit:pages && npm run audit:links && npm run check:awesome && npm run audit:docs && npm run audit:upstreams && npm run check:tutorials && npm run audit:hidden-guard && npm run audit:inline-handlers && npm run audit:x402-catalog && npm run audit:tokens && npm run audit:states && npm run audit:motion-tokens && npm run audit:guards && npm run audit:tour-atlas && npm run check:ios-icons && npm run check:macos-icon && npm run check:apple-widget && npm run check:windows-widget && npm run check:announce && npm run i18n:home && npm run check:skills-seed && npm run audit:motion && npm run audit:tour-global && npm run check:doc-media && npm run check:images && npm run audit:route-shadowing",
+ "gate": "npm run check:conflicts && npm run check:claude && npm run check:vendored && npm run check:model-viewer && npm run check:gcloudignore && npm run check:fetch-timeouts && npm run check:tdz-bootstrap && npm run check:event && npm run check:cron-syntax && npm run check:home-matrix && npm run check:studio-openapi && npm run test:gate && npm run test:gate-3d && npm run audit:mcp && npm run audit:mcp-golden && npm run audit:mcp-safety && npm run audit:mcp-catalog && npm run audit:mcp-listing && npm run audit:routes && npm run audit:handlers && npm run audit:pages && npm run audit:links && npm run check:awesome && npm run audit:docs && npm run audit:upstreams && npm run check:tutorials && npm run audit:hidden-guard && npm run audit:inline-handlers && npm run audit:x402-catalog && npm run audit:tokens && npm run audit:states && npm run audit:motion-tokens && npm run audit:guards && npm run audit:tour-atlas && npm run check:ios-icons && npm run check:macos-icon && npm run check:apple-widget && npm run check:windows-widget && npm run check:announce && npm run i18n:home && npm run check:skills-seed && npm run audit:motion && npm run audit:tour-global && npm run check:doc-media && npm run check:images && npm run audit:route-shadowing",
"test:gate-3d": "vitest run tests/glb-canonicalize.test.js tests/animation-retarget.test.js tests/animation-retarget-rest-pollution.test.js tests/viewer-framing.test.js",
"audit:mcp-golden": "node scripts/audit-mcp-golden.mjs",
"audit:mcp-safety": "node scripts/audit-mcp-safety.mjs",
@@ -468,6 +468,8 @@
"home:instance:down": "node scripts/home-test-instance.mjs --down --name lane",
"test:home:live": "node scripts/home-live-tests.mjs",
"home:matrix": "node scripts/home-version-matrix.mjs",
+ "home:matrix:sync": "node scripts/home-version-matrix.mjs --sync-doc",
+ "check:home-matrix": "node scripts/home-version-matrix.mjs --check",
"test:home:e2e": "node --env-file=.env.local ./node_modules/@playwright/test/cli.js test --config=playwright.home.config.js",
"deck:inception": "node scripts/build-inception-deck.mjs",
"build:awesome": "node scripts/build-awesome.mjs",
diff --git a/scripts/home-version-matrix.mjs b/scripts/home-version-matrix.mjs
index 9401e4d01..93a937f0c 100644
--- a/scripts/home-version-matrix.mjs
+++ b/scripts/home-version-matrix.mjs
@@ -12,6 +12,8 @@
* node scripts/home-version-matrix.mjs # the derived version set
* node scripts/home-version-matrix.mjs --versions 2026.8,2026.7
* node scripts/home-version-matrix.mjs --keep-images # skip the disk reclaim
+ * node scripts/home-version-matrix.mjs --check # is the published table still the measured one
+ * node scripts/home-version-matrix.mjs --sync-doc # rewrite the published table from the last run
*
* The version set is DERIVED, never hardcoded: Home Assistant's own analytics
* (https://analytics.home-assistant.io/data.json, ~676k opted-in installs)
@@ -36,6 +38,9 @@ const HARNESS = path.join(ROOT, 'scripts', 'home-test-instance.mjs');
const IMAGE = 'ghcr.io/home-assistant/home-assistant';
const ANALYTICS = 'https://analytics.home-assistant.io/data.json';
const OUT_JSON = path.join(ROOT, 'docs', 'ops', 'home-version-matrix.json');
+const OUT_DOC = path.join(ROOT, 'docs', 'smart-home.md');
+const DOC_START = '<!-- home-version-matrix:start -->';
+const DOC_END = '<!-- home-version-matrix:end -->';
/**
* The entry point sits below every declaration it uses. A top-level driver
@@ -45,6 +50,24 @@ const OUT_JSON = path.join(ROOT, 'docs', 'ops', 'home-version-matrix.json');
*/
async function main() {
const args = parse(process.argv.slice(2));
+
+ // --check and --sync-doc read the last run's JSON instead of pulling four
+ // Home Assistant images. They exist because the published table drifted from
+ // the measurements once already: the runner wrote the JSON and left the
+ // markdown to a human, and by the next run the doc claimed shares and entity
+ // counts no release had ever reported.
+ if (args.check || args.syncDoc) {
+ const report = readReport();
+ const written = syncDoc(report, { write: args.syncDoc });
+ if (args.syncDoc) console.error(`[matrix] ${written ? 'updated' : 'left unchanged'} ${path.relative(ROOT, OUT_DOC)}`);
+ else if (!written) console.error(`[matrix] ${path.relative(ROOT, OUT_DOC)} matches ${path.relative(ROOT, OUT_JSON)}`);
+ else {
+ console.error(`[matrix] ${path.relative(ROOT, OUT_DOC)} is stale. Run: npm run home:matrix:sync`);
+ process.exitCode = 1;
+ }
+ return;
+ }
+
const versions = args.versions || (await deriveVersions());
console.error(`[matrix] testing ${versions.map((v) => v.tag).join(', ')}`);
@@ -57,9 +80,10 @@ async function main() {
const report = { measuredAt: new Date().toISOString(), source: ANALYTICS, results };
fs.mkdirSync(path.dirname(OUT_JSON), { recursive: true });
fs.writeFileSync(OUT_JSON, `${JSON.stringify(report, null, '\t')}\n`);
+ syncDoc(report, { write: true });
console.log(renderTable(results));
- console.error(`\n[matrix] wrote ${path.relative(ROOT, OUT_JSON)}`);
+ console.error(`\n[matrix] wrote ${path.relative(ROOT, OUT_JSON)} and ${path.relative(ROOT, OUT_DOC)}`);
// A version that cannot connect at all is the finding this runner exists to
// surface, so it fails the command rather than printing a quiet FAIL cell.
@@ -224,6 +248,54 @@ async function probe(instance, cells, notes) {
home.close();
}
+// ---------------------------------------------------------------- the doc
+
+/**
+ * The published table, rewritten from the measurements.
+ *
+ * `docs/smart-home.md` is where a developer actually reads which releases we
+ * hold, so the runner owns that section rather than trusting someone to
+ * transcribe a JSON file by hand. Returns whether the file's content differs
+ * from what the report says it should be, which is what `--check` reports and
+ * `--sync-doc` acts on.
+ */
+function syncDoc(report, { write }) {
+ const doc = fs.readFileSync(OUT_DOC, 'utf8');
+ const start = doc.indexOf(DOC_START);
+ const end = doc.indexOf(DOC_END);
+ if (start < 0 || end < 0) throw new Error(`${path.relative(ROOT, OUT_DOC)} is missing the ${DOC_START} / ${DOC_END} markers.`);
+
+ const body = renderDocSection(report);
+ const next = `${doc.slice(0, start)}${DOC_START}\n${body}\n${doc.slice(end)}`;
+ const changed = next !== doc;
+ if (changed && write) fs.writeFileSync(OUT_DOC, next);
+ return changed;
+}
+
+function renderDocSection(report) {
+ const measured = report.measuredAt.slice(0, 10);
+ const floor = report.results.reduce((oldest, r) => (compareVersions(r.tag, oldest.tag) < 0 ? r : oldest), report.results[0]);
+ const broken = report.results.filter((r) => Object.values(r.cells).some((c) => c && !c.ok));
+
+ const range = broken.length
+ ? `**Supported range: ${floor.tag} and newer, with exceptions.** ${broken.map((r) => `\`${r.tag}\` fails ${Object.entries(r.cells).filter(([, c]) => c && !c.ok).map(([k]) => k).join(', ')}`).join('; ')}.`
+ : `**Supported range: ${floor.tag} and newer.** Every capability the platform depends on works across it. The floor is where install share falls below one percent, not where the code stops working; nothing was found that a ${floor.tag} house cannot do.`;
+
+ return [
+ `Measured ${measured}, by \`npm run home:matrix\`. This table is written by the runner from`,
+ `[\`docs/ops/home-version-matrix.json\`](ops/home-version-matrix.json); do not edit it by hand.`,
+ '',
+ renderTable(report.results),
+ '',
+ range,
+ ].join('\n');
+}
+
+function readReport() {
+ if (!fs.existsSync(OUT_JSON)) throw new Error(`${path.relative(ROOT, OUT_JSON)} does not exist. Run: npm run home:matrix`);
+ return JSON.parse(fs.readFileSync(OUT_JSON, 'utf8'));
+}
+
// ---------------------------------------------------------------- rendering
function renderTable(rows) {
@@ -314,7 +386,7 @@ async function reclaim(tag) {
}
function parse(argv) {
- const out = { keepImages: false, allowFailures: false };
+ const out = { keepImages: false, allowFailures: false, check: false, syncDoc: false };
for (let i = 0; i < argv.length; i += 1) {
if (argv[i] === '--versions') {
out.versions = argv[++i]
@@ -322,6 +394,8 @@ function parse(argv) {
.map((tag) => ({ tag: tag.trim(), share: 0, role: 'requested', installs: 0 }));
} else if (argv[i] === '--keep-images') out.keepImages = true;
else if (argv[i] === '--allow-failures') out.allowFailures = true;
+ else if (argv[i] === '--check') out.check = true;
+ else if (argv[i] === '--sync-doc') out.syncDoc = true;
else throw new Error(`unknown argument "${argv[i]}"`);
}
return out;