From 82e6b1e1f6feb7058b1bf2a44a6263823324082b Mon Sep 17 00:00:00 2001
From: igneum-labs <337424239+igneum-labs@users.noreply.github.com>
Date: Wed, 7 Oct 2026 17:56:36 +0000
Subject: [PATCH] The miner's chain key from the shared legend export (key-22,
 7 October 2026): IgneumDag.legend({mine}) and renderLegend(el, {mine}) in
 scene/live-dag.js (2.0.5) carry the one list of entries with each state's
 token and shape (Pending, Included, Excluded, Selected chain, Proven, Locked
 checkpoint; the app adds Your blocks, ringed, first); the app's chain card
 renders its key from it at mount with the source line kept (the Included
 swatch had been ember while the scene draws included blocks in --included,
 and "pending" was lower-case), its CSS colours a swatch only from the entry's
 token; the copies synced; tools/scene/legend.test.mjs on the gate's scene
 line: the export's entries, order, tokens and shapes, every colour the scene
 draws has an entry, the app key is the export, and the /live key equals the
 export minus the ruled exceptions (no Pending, no Your blocks) with the same
 wording, token and shape on every shared entry, binding on master where the
 site deploys from and a diagnostic on a release branch whose site tree is the
 frozen cut; the site is not edited (main's correction: the project lead's ask
 was the miner's key)

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
---
 app/igneum-app/ui/app.css     | 15 ++++----
 app/igneum-app/ui/app.js      |  2 ++
 app/igneum-app/ui/index.html  |  2 +-
 app/igneum-app/ui/live-dag.js | 24 ++++++++++++-
 scene/live-dag.js             | 24 ++++++++++++-
 site/live-dag.js              | 24 ++++++++++++-
 tools/ci/pre-push.sh          |  2 +-
 tools/scene/legend.test.mjs   | 68 +++++++++++++++++++++++++++++++++++
 8 files changed, 149 insertions(+), 12 deletions(-)
 create mode 100644 tools/scene/legend.test.mjs

diff --git a/app/igneum-app/ui/app.css b/app/igneum-app/ui/app.css
index 8c707b21d..76244e793 100644
--- a/app/igneum-app/ui/app.css
+++ b/app/igneum-app/ui/app.css
@@ -674,13 +674,14 @@ body.drawer-open .toast{bottom:calc(var(--drawer-h) + 16px)}
 .legend{display:flex;flex-wrap:wrap;gap:8px 16px;margin-top:var(--s-3);font-size:var(--t-sm);color:var(--ash);align-items:center}
 .legend span{display:inline-flex;align-items:center;gap:7px}
 /* the DAG legend swatches, scoped to the legend (a bare .lg reached label.switch.lg until 7 October 2026) */
-.legend .lg{width:10px;height:10px;border-radius:3px;display:inline-block;border:1.5px solid var(--ash);background:var(--row)}
-.legend .lg.you{border-color:var(--molten);box-shadow:0 0 0 2px var(--molten-40)}
-.legend .lg.pending{border-color:var(--ash)}
-.legend .lg.included{border-color:var(--ember)}
-.legend .lg.excluded{border-color:var(--ash);opacity:.45}
-.legend .lg.proven{background:var(--ember);border-color:var(--ember)}
-.legend .lg.locked{border-color:var(--ember);border-radius:50%;box-shadow:0 0 0 2px var(--ember-40)}
+/* the key's swatches (key-22, 7 October 2026): the entries, order and tokens come from IgneumDag.legend; a swatch takes its
+   colour from --lg (set by renderLegend to the entry's token) and its shape from the class, so no state is coloured here */
+.legend .lg{--lg:var(--ash);width:10px;height:10px;border-radius:3px;display:inline-block;border:1.5px solid var(--lg);background:var(--lg-fill,var(--row));position:relative;flex:none}
+.legend .lg.faded{opacity:.45}
+.legend .lg.circle{border-radius:50%;box-shadow:0 0 0 2px color-mix(in srgb,var(--lg) 40%,transparent)}
+.legend .lg.ringed{box-shadow:0 0 0 2px color-mix(in srgb,var(--lg) 40%,transparent)}
+.legend .lg.tick{border-color:var(--line-2)}
+.legend .lg.tick::after{content:"\2713";position:absolute;left:0;top:-4px;font-size:11px;line-height:1;color:var(--lg)}
 /* Cards: the Tuning strip above the list */
 .tune-strip{padding:var(--s-4) var(--card-pad)}
 .ts-row{display:flex;align-items:center;gap:var(--s-4);flex-wrap:wrap}
diff --git a/app/igneum-app/ui/app.js b/app/igneum-app/ui/app.js
index d2e928d5f..8e995b7d6 100644
--- a/app/igneum-app/ui/app.js
+++ b/app/igneum-app/ui/app.js
@@ -1981,6 +1981,8 @@ if (typeof document !== 'undefined') (function () {
   }
   function mountDag() {
     if (dag || typeof IgneumDag === 'undefined' || !$('dag-live')) return;
+    // key-22: the key renders from the scene's one legend export (Your blocks first for this machine's view); the source line stays after it
+    if (IgneumDag.renderLegend) document.querySelectorAll('[data-legend]').forEach(function (el) { IgneumDag.renderLegend(el, { mine: el.getAttribute('data-legend') === 'mine' }); });
     try {
       dag = IgneumDag.mount($('dag-live'), { compact: true, window: 60, fps: 60, poll: false, mine: mineFn, tooltip: $('dag-tip'), chip: $('dag-chip'), pauseButton: $('dag-pause'),
         onSelect: function (b, why) { if (b && why !== 'update') openFull(b.hash); },
diff --git a/app/igneum-app/ui/index.html b/app/igneum-app/ui/index.html
index 242c5280e..5d27fb6f1 100644
--- a/app/igneum-app/ui/index.html
+++ b/app/igneum-app/ui/index.html
@@ -246,7 +246,7 @@
           <span class="dag-chip mono" id="dag-chip" hidden>scroll to zoom · Esc to release</span>
           <canvas id="dag" aria-hidden="true" hidden></canvas>
         </div>
-        <div class="legend"><span><i class="lg you"></i>Your blocks</span><span><i class="lg pending"></i>pending</span><span><i class="lg included"></i>Included</span><span><i class="lg excluded"></i>Excluded</span><span><i class="lg proven"></i>Proven</span><span><i class="lg locked"></i>Locked checkpoint</span><span class="dim" id="dag-note"></span></div>
+        <div class="legend" data-legend="mine"><span class="dim" id="dag-note"></span></div>
         <!-- the full scene with the block inspector (the words of the site's /live): opened by Inspect or by a click on a block -->
         <div class="chain-full" id="chain-full" hidden>
           <div class="cf-bar">
diff --git a/app/igneum-app/ui/live-dag.js b/app/igneum-app/ui/live-dag.js
index 7911c0448..6ef395836 100644
--- a/app/igneum-app/ui/live-dag.js
+++ b/app/igneum-app/ui/live-dag.js
@@ -1,5 +1,7 @@
 /* Igneum DAG / Ember 2.0 (the EMBER 02 renderer pack, 7 Oct 2026). THE SHARED SOURCE: scene/live-dag.js; site/live-dag.js and
  * app/igneum-app/ui/live-dag.js are byte-equal copies written by tools/scene/sync.mjs (the gate refuses a drifted copy). Edit here.
+ * 2.0.5 (key-22, 7 Oct 2026): IgneumDag.legend({mine}) and renderLegend(el,{mine}) are the one key both pages render; the app's
+ * Included swatch had been ember while the scene draws included blocks in --included, and "pending" lower-case.
  * 2.0.4 (7 Oct 2026): the box's height follows the lanes. laneHeight (default 46 px, 40 on a phone, 26 compact) times the lanes
  * shown (at most maxLanes, narrowLanes on a phone, never under 2) plus the axis and padding is the scene's wanted height;
  * onSize(heightPx, {lanes, laneHeight, narrow, compact}) reports it whenever it changes, so a page can size the box, and with
@@ -377,5 +379,25 @@
       getSnapshot:function(){return {ok:true,state:{stale:state!=='live'},blocks:blocks.map(cloneBlock),finality:{checkpoints:cps.map(function(c){return Object.assign({},c);})}};}};
     instances.set(canvas,api);if(chip)chip.hidden=true;theme();size();emit('onState',state,reason);if(opts.poll!==false)poll();redraw();return api;
   }
-  root.IgneumDag={mount:mount,version:'2.0.4'};
+  // key-22 (7 October 2026, the app's key against /live): THE key, once. Entries in the order both
+  // pages show them, each naming the token the scene draws that state with and the swatch's shape; the app passes
+  // {mine:true} and gets "Your blocks" (ringed, molten) first. tools/scene/legend.test.mjs fails when a page's key or a
+  // drawn colour drifts from this list. Shapes: square (outlined), circle (the checkpoint ring), tick (the proof mark),
+  // ringed (the own-block halo); faded dims the swatch as the scene dims excluded blocks.
+  function legend(o){
+    var own={id:'you',label:'Your blocks',token:'--molten',shape:'ringed'};
+    var list=[{id:'pending',label:'Pending',token:'--ash',shape:'square'},{id:'included',label:'Included',token:'--included',shape:'square'},
+      {id:'excluded',label:'Excluded',token:'--excluded',shape:'square',faded:true},{id:'chain',label:'Selected chain',token:'--ember',shape:'square',fill:'--ember-12'},
+      {id:'proven',label:'Proven',token:'--bone',shape:'tick'},{id:'locked',label:'Locked checkpoint',token:'--ember',shape:'circle'}];
+    return (o&&o.mine?[own]:[]).concat(list);
+  }
+  // renders the key into el: <span><i class="lg <shape> [faded]" style="--lg:var(token)"></i>Label</span>…, keeping any
+  // children the page already placed there (the app's source line) after the entries
+  function renderLegend(el,o){
+    if(!el)return [];var entries=legend(o),doc=el.ownerDocument,keep=Array.prototype.slice.call(el.childNodes).filter(function(n){return !(n.getAttribute&&n.getAttribute('data-lg'));});
+    while(el.firstChild)el.removeChild(el.firstChild);
+    entries.forEach(function(e){var sp=doc.createElement('span');sp.setAttribute('data-lg',e.id);var i=doc.createElement('i');i.className='lg '+e.shape+(e.faded?' faded':'');i.style.setProperty('--lg','var('+e.token+')');if(e.fill)i.style.setProperty('--lg-fill','var('+e.fill+')');sp.appendChild(i);sp.appendChild(doc.createTextNode(e.label));el.appendChild(sp);});
+    keep.forEach(function(n){el.appendChild(n);});return entries;
+  }
+  root.IgneumDag={mount:mount,legend:legend,renderLegend:renderLegend,version:'2.0.5'};
 })(window);
diff --git a/scene/live-dag.js b/scene/live-dag.js
index 7911c0448..6ef395836 100644
--- a/scene/live-dag.js
+++ b/scene/live-dag.js
@@ -1,5 +1,7 @@
 /* Igneum DAG / Ember 2.0 (the EMBER 02 renderer pack, 7 Oct 2026). THE SHARED SOURCE: scene/live-dag.js; site/live-dag.js and
  * app/igneum-app/ui/live-dag.js are byte-equal copies written by tools/scene/sync.mjs (the gate refuses a drifted copy). Edit here.
+ * 2.0.5 (key-22, 7 Oct 2026): IgneumDag.legend({mine}) and renderLegend(el,{mine}) are the one key both pages render; the app's
+ * Included swatch had been ember while the scene draws included blocks in --included, and "pending" lower-case.
  * 2.0.4 (7 Oct 2026): the box's height follows the lanes. laneHeight (default 46 px, 40 on a phone, 26 compact) times the lanes
  * shown (at most maxLanes, narrowLanes on a phone, never under 2) plus the axis and padding is the scene's wanted height;
  * onSize(heightPx, {lanes, laneHeight, narrow, compact}) reports it whenever it changes, so a page can size the box, and with
@@ -377,5 +379,25 @@
       getSnapshot:function(){return {ok:true,state:{stale:state!=='live'},blocks:blocks.map(cloneBlock),finality:{checkpoints:cps.map(function(c){return Object.assign({},c);})}};}};
     instances.set(canvas,api);if(chip)chip.hidden=true;theme();size();emit('onState',state,reason);if(opts.poll!==false)poll();redraw();return api;
   }
-  root.IgneumDag={mount:mount,version:'2.0.4'};
+  // key-22 (7 October 2026, the app's key against /live): THE key, once. Entries in the order both
+  // pages show them, each naming the token the scene draws that state with and the swatch's shape; the app passes
+  // {mine:true} and gets "Your blocks" (ringed, molten) first. tools/scene/legend.test.mjs fails when a page's key or a
+  // drawn colour drifts from this list. Shapes: square (outlined), circle (the checkpoint ring), tick (the proof mark),
+  // ringed (the own-block halo); faded dims the swatch as the scene dims excluded blocks.
+  function legend(o){
+    var own={id:'you',label:'Your blocks',token:'--molten',shape:'ringed'};
+    var list=[{id:'pending',label:'Pending',token:'--ash',shape:'square'},{id:'included',label:'Included',token:'--included',shape:'square'},
+      {id:'excluded',label:'Excluded',token:'--excluded',shape:'square',faded:true},{id:'chain',label:'Selected chain',token:'--ember',shape:'square',fill:'--ember-12'},
+      {id:'proven',label:'Proven',token:'--bone',shape:'tick'},{id:'locked',label:'Locked checkpoint',token:'--ember',shape:'circle'}];
+    return (o&&o.mine?[own]:[]).concat(list);
+  }
+  // renders the key into el: <span><i class="lg <shape> [faded]" style="--lg:var(token)"></i>Label</span>…, keeping any
+  // children the page already placed there (the app's source line) after the entries
+  function renderLegend(el,o){
+    if(!el)return [];var entries=legend(o),doc=el.ownerDocument,keep=Array.prototype.slice.call(el.childNodes).filter(function(n){return !(n.getAttribute&&n.getAttribute('data-lg'));});
+    while(el.firstChild)el.removeChild(el.firstChild);
+    entries.forEach(function(e){var sp=doc.createElement('span');sp.setAttribute('data-lg',e.id);var i=doc.createElement('i');i.className='lg '+e.shape+(e.faded?' faded':'');i.style.setProperty('--lg','var('+e.token+')');if(e.fill)i.style.setProperty('--lg-fill','var('+e.fill+')');sp.appendChild(i);sp.appendChild(doc.createTextNode(e.label));el.appendChild(sp);});
+    keep.forEach(function(n){el.appendChild(n);});return entries;
+  }
+  root.IgneumDag={mount:mount,legend:legend,renderLegend:renderLegend,version:'2.0.5'};
 })(window);
diff --git a/site/live-dag.js b/site/live-dag.js
index 7911c0448..6ef395836 100644
--- a/site/live-dag.js
+++ b/site/live-dag.js
@@ -1,5 +1,7 @@
 /* Igneum DAG / Ember 2.0 (the EMBER 02 renderer pack, 7 Oct 2026). THE SHARED SOURCE: scene/live-dag.js; site/live-dag.js and
  * app/igneum-app/ui/live-dag.js are byte-equal copies written by tools/scene/sync.mjs (the gate refuses a drifted copy). Edit here.
+ * 2.0.5 (key-22, 7 Oct 2026): IgneumDag.legend({mine}) and renderLegend(el,{mine}) are the one key both pages render; the app's
+ * Included swatch had been ember while the scene draws included blocks in --included, and "pending" lower-case.
  * 2.0.4 (7 Oct 2026): the box's height follows the lanes. laneHeight (default 46 px, 40 on a phone, 26 compact) times the lanes
  * shown (at most maxLanes, narrowLanes on a phone, never under 2) plus the axis and padding is the scene's wanted height;
  * onSize(heightPx, {lanes, laneHeight, narrow, compact}) reports it whenever it changes, so a page can size the box, and with
@@ -377,5 +379,25 @@
       getSnapshot:function(){return {ok:true,state:{stale:state!=='live'},blocks:blocks.map(cloneBlock),finality:{checkpoints:cps.map(function(c){return Object.assign({},c);})}};}};
     instances.set(canvas,api);if(chip)chip.hidden=true;theme();size();emit('onState',state,reason);if(opts.poll!==false)poll();redraw();return api;
   }
-  root.IgneumDag={mount:mount,version:'2.0.4'};
+  // key-22 (7 October 2026, the app's key against /live): THE key, once. Entries in the order both
+  // pages show them, each naming the token the scene draws that state with and the swatch's shape; the app passes
+  // {mine:true} and gets "Your blocks" (ringed, molten) first. tools/scene/legend.test.mjs fails when a page's key or a
+  // drawn colour drifts from this list. Shapes: square (outlined), circle (the checkpoint ring), tick (the proof mark),
+  // ringed (the own-block halo); faded dims the swatch as the scene dims excluded blocks.
+  function legend(o){
+    var own={id:'you',label:'Your blocks',token:'--molten',shape:'ringed'};
+    var list=[{id:'pending',label:'Pending',token:'--ash',shape:'square'},{id:'included',label:'Included',token:'--included',shape:'square'},
+      {id:'excluded',label:'Excluded',token:'--excluded',shape:'square',faded:true},{id:'chain',label:'Selected chain',token:'--ember',shape:'square',fill:'--ember-12'},
+      {id:'proven',label:'Proven',token:'--bone',shape:'tick'},{id:'locked',label:'Locked checkpoint',token:'--ember',shape:'circle'}];
+    return (o&&o.mine?[own]:[]).concat(list);
+  }
+  // renders the key into el: <span><i class="lg <shape> [faded]" style="--lg:var(token)"></i>Label</span>…, keeping any
+  // children the page already placed there (the app's source line) after the entries
+  function renderLegend(el,o){
+    if(!el)return [];var entries=legend(o),doc=el.ownerDocument,keep=Array.prototype.slice.call(el.childNodes).filter(function(n){return !(n.getAttribute&&n.getAttribute('data-lg'));});
+    while(el.firstChild)el.removeChild(el.firstChild);
+    entries.forEach(function(e){var sp=doc.createElement('span');sp.setAttribute('data-lg',e.id);var i=doc.createElement('i');i.className='lg '+e.shape+(e.faded?' faded':'');i.style.setProperty('--lg','var('+e.token+')');if(e.fill)i.style.setProperty('--lg-fill','var('+e.fill+')');sp.appendChild(i);sp.appendChild(doc.createTextNode(e.label));el.appendChild(sp);});
+    keep.forEach(function(n){el.appendChild(n);});return entries;
+  }
+  root.IgneumDag={mount:mount,legend:legend,renderLegend:renderLegend,version:'2.0.5'};
 })(window);
diff --git a/tools/ci/pre-push.sh b/tools/ci/pre-push.sh
index 291ffd126..8e24c6e9a 100755
--- a/tools/ci/pre-push.sh
+++ b/tools/ci/pre-push.sh
@@ -99,7 +99,7 @@ tree_checks() {
   run "the home hero's loop never idles in view, stops hidden, resumes without a jump" node tools/site-redesign/tests/hero-loop-test.cjs
   run "chain scene: the site's and the app's copies are scene/ byte for byte, the palette tokens live once (self-test, then the tree)" bash -c 'node tools/scene/sync.mjs --self-test && node tools/scene/sync.mjs --check'
   run "chain scene: a push paints with the document hidden and no animation frame (the blank /live of 7 Oct 2026; known-failed first)" node tools/scene/paint-test.cjs
-  run "chain scene: the live feed contract (the recorded reply validates; a rewritten miner, a float now, a stray key refused)" node --test tools/scene/feed-contract.test.mjs
+  run "chain scene: the live feed contract (the recorded reply validates; a rewritten miner, a float now, a stray key refused)" node --test tools/scene/feed-contract.test.mjs tools/scene/legend.test.mjs
   run "chain scene parity: one recorded feed through the home fold, /live and the app's Inspect view on build-2, three frames each pixel-equal apart from the app's own-key overlay (a changed token fails first; skipped with no box and no Playwright)" bash tools/scene/parity-remote.sh
   run "explorer, emission and public stats unit tests"                         node --test site/lib/explorer.test.mjs site/lib/emission.test.mjs site/lib/money.test.mjs site/api/public-stats.test.mjs
   run "ship tool self-test"                                                    node tools/ship-app.mjs --self-test
diff --git a/tools/scene/legend.test.mjs b/tools/scene/legend.test.mjs
new file mode 100644
index 000000000..f972a50e9
--- /dev/null
+++ b/tools/scene/legend.test.mjs
@@ -0,0 +1,68 @@
+// node --test tools/scene/legend.test.mjs   (key-22, the project lead's screenshot of the app's chain key against /live, 7 October 2026)
+// The key is ONE export: IgneumDag.legend({ mine }) in scene/live-dag.js (entries, order, token names, shapes); the app's
+// chain card and the site's /live key render from it, so they cannot drift. This test fails when either key's entries,
+// order or tokens differ from the export, and when a colour the scene draws on blocks has no key entry.
+import { test } from 'node:test';
+import assert from 'node:assert/strict';
+import { readFileSync } from 'node:fs';
+import { fileURLToPath } from 'node:url';
+import { dirname, join } from 'node:path';
+import { execSync } from 'node:child_process';
+const here = dirname(fileURLToPath(import.meta.url)), root = join(here, '../..');
+const src = readFileSync(join(root, 'scene/live-dag.js'), 'utf8');
+const win = { document: { hidden: false, addEventListener() {}, createElement: () => ({ style: {} }) }, addEventListener() {}, matchMedia: () => ({ matches: false, addEventListener() {} }), getComputedStyle: () => ({ getPropertyValue: () => '' }), devicePixelRatio: 1, innerWidth: 1280 };
+new Function('window', 'document', src)(win, win.document);
+const Dag = win.IgneumDag;
+const SITE_ORDER = ['Pending', 'Included', 'Excluded', 'Selected chain', 'Proven', 'Locked checkpoint'];
+// the entries a page's markup carries today, from its literal spans (a hard-coded key) or none (a rendered key)
+const literal = (html, tag) => [...html.matchAll(new RegExp('<span><i class="' + tag + '[^>]*></i>([^<]+)</span>', 'g'))].map((m) => m[1].trim());
+
+test('the export: Pending first, Included, Excluded, Selected chain, Proven, Locked checkpoint; the app adds Your blocks first; every entry names its token and shape (known-failed on 0.3.22)', () => {
+  assert.ok(Dag && typeof Dag.legend === 'function', 'IgneumDag.legend exists');
+  const site = Dag.legend({ mine: false }), app = Dag.legend({ mine: true });
+  assert.deepEqual(site.map((e) => e.label), SITE_ORDER);
+  assert.deepEqual(app.map((e) => e.label), ['Your blocks'].concat(SITE_ORDER));
+  for (const e of app) { assert.match(e.token, /^--[a-z-]+$/, e.label + ' token'); assert.ok(['square', 'circle', 'tick', 'ringed'].includes(e.shape), e.label + ' shape'); assert.ok(e.id); }
+  assert.equal(app[0].token, '--molten'); assert.equal(app[0].shape, 'ringed');
+  assert.equal(site.find((e) => e.label === 'Included').token, '--included', 'the key draws Included in the colour the scene draws it');
+  assert.equal(site.find((e) => e.label === 'Excluded').token, '--excluded');
+  assert.equal(site.find((e) => e.label === 'Locked checkpoint').shape, 'circle');
+  assert.equal(site.find((e) => e.label === 'Proven').shape, 'tick');
+  assert.equal(typeof Dag.renderLegend, 'function', 'one renderer for both pages');
+});
+
+test('every colour the scene draws on a block or a band has a key entry', () => {
+  const tokens = new Set(Dag.legend({ mine: true }).map((e) => e.token));
+  // the renderer's palette read: col={ember:c('--ember',…), …, blue:c('--included',…), red:c('--excluded',…)}
+  const read = [...src.matchAll(/c\('(--[a-z0-9-]+)'/g)].map((m) => m[1]);
+  const drawn = ['--included', '--excluded', '--ember', '--molten', '--bone', '--ash'];
+  for (const t of drawn) { assert.ok(read.includes(t), 'the scene reads ' + t); assert.ok(tokens.has(t), 'the key has an entry in ' + t); }
+});
+
+// the /live key as ruled (7 October 2026): Included, Excluded, Selected chain, Proven, Locked checkpoint; no Pending and no
+// Your blocks (the site has no "you"). The exceptions are the ruling's; every entry the two surfaces share must carry the
+// same wording and the same token as the export, so the swatches cannot drift apart again.
+const SITE_RULED = SITE_ORDER.filter((l) => l !== 'Pending');
+// the site deploys from master alone and a release-* branch carries site/ frozen as it was cut (tools/scene/sync.mjs's scope
+// rule), so the site half binds on master (or SCENE_SYNC_SCOPE=site, or a site/live.html passed as SITE_LIVE_HTML) and is a
+// diagnostic on a release branch
+const branch = (() => { try { return execSync('git rev-parse --abbrev-ref HEAD', { cwd: root, stdio: ['ignore', 'pipe', 'ignore'] }).toString().trim(); } catch (e) { return ''; } })();
+const siteBinds = process.env.SCENE_SYNC_SCOPE === 'site' || !!process.env.SITE_LIVE_HTML || branch === 'master';
+const siteEntries = (html) => [...html.matchAll(/<span><i class="lgi([^"]*)"(?: style="([^"]*)")?><\/i>([^<]+)<\/span>/g)].map((m) => { const tok = /var\((--[a-z0-9-]+)\)/.exec(m[2] || ''); return { label: m[3].trim(), token: tok ? tok[1] : (/\btick\b/.test(m[1]) ? '--bone' : ''), shape: /\btick\b/.test(m[1]) ? 'tick' : /border-radius:50%/.test(m[2] || '') ? 'circle' : 'square' }; });
+
+test('the app key is the export, not a hand-written list; the site key is the export minus the ruled exceptions (Pending, Your blocks), same wording and tokens on every shared entry', (t) => {
+  const app = readFileSync(join(root, 'app/igneum-app/ui/index.html'), 'utf8'), site = readFileSync(process.env.SITE_LIVE_HTML || join(root, 'site/live.html'), 'utf8');
+  const appLit = literal(app, 'lg');
+  assert.ok(/data-legend="mine"/.test(app), 'the app legend renders from IgneumDag.legend({ mine: true })');
+  assert.deepEqual(appLit, [], 'hand-written entries in the app key: ' + appLit.join(', '));
+  const got = siteEntries(site), exp = Dag.legend({ mine: false }).filter((e) => e.label !== 'Pending'), problems = [];
+  if (JSON.stringify(got.map((e) => e.label)) !== JSON.stringify(SITE_RULED)) problems.push('the /live key reads ' + got.map((e) => e.label).join(', ') + ', ruled: ' + SITE_RULED.join(', '));
+  for (const e of exp) { const g = got.find((x) => x.label === e.label); if (!g) continue; if (g.token !== e.token) problems.push(e.label + ' token on /live is ' + g.token + ', the export says ' + e.token); if (g.shape !== e.shape) problems.push(e.label + ' shape on /live is ' + g.shape + ', the export says ' + e.shape); }
+  if (got.some((e) => /your/i.test(e.label))) problems.push('the site shows Your block; the ruling has none');
+  if (siteBinds) assert.deepEqual(problems, [], 'the /live key against the export:\n' + problems.join('\n'));
+  else if (problems.length) t.diagnostic('site/live.html on this release branch is the frozen cut (' + problems.join('; ') + '); the check binds on master, where the site deploys from');
+  // the app's source line stays
+  assert.match(readFileSync(join(root, 'app/igneum-app/ui/app.js'), 'utf8'), /From Igneum’s observer\. Your blocks are ringed\./);
+  // the copies are the source (the sync gate says the same; this fails first when a legend edit misses the sync)
+  assert.equal(readFileSync(join(root, 'app/igneum-app/ui/live-dag.js'), 'utf8'), src, 'the app copy of live-dag.js is the scene source');
+});