@bongos/core 1.19.850 → 1.19.852

package/docs/copy-registry.json

@@ -3,9 +3,9 @@
   "generator": "scripts/gds/copy-inventory.js",
   "goal": 1000074,
   "counts": {
-    "strings": 1874,
-    "unique_ids": 1627,
-    "certain": 1874,
+    "strings": 1875,
+    "unique_ids": 1628,
+    "certain": 1875,
     "heuristic": 0,
     "duplicate_ids": 171
   },
@@ -13,7 +13,7 @@
     "builders-hall": {
       "at": "modules/hall-ui/public",
       "files": 89,
-      "strings": 1384
+      "strings": 1385
     },
     "status-dashboard": {
       "at": "modules/status-ui/public",
@@ -2371,7 +2371,7 @@
       "surface": "builders-hall",
       "text": "Achievements could not be loaded.",
       "file": "modules/hall-ui/public/builders.js",
-      "line": 1158,
+      "line": 1204,
       "origin": "js-markup",
       "confidence": "certain"
     },
@@ -2488,7 +2488,7 @@
       "surface": "builders-hall",
       "text": "All builders",
       "file": "modules/hall-ui/public/hall-render.js",
-      "line": 1145,
+      "line": 1208,
       "origin": "js-markup",
       "confidence": "certain"
     },
@@ -2569,7 +2569,7 @@
       "surface": "builders-hall",
       "text": "Analytics scope",
       "file": "modules/hall-ui/public/hall-render.js",
-      "line": 1143,
+      "line": 1206,
       "origin": "js-markup",
       "confidence": "certain"
     },
@@ -4792,7 +4792,7 @@
       "surface": "builders-hall",
       "text": "Downvote (−1)",
       "file": "modules/hall-ui/public/builders.js",
-      "line": 739,
+      "line": 785,
       "origin": "js-markup",
       "confidence": "certain"
     },
@@ -5899,7 +5899,7 @@
       "surface": "builders-hall",
       "text": "Ideas awaiting triage",
       "file": "modules/hall-ui/public/builders.js",
-      "line": 859,
+      "line": 905,
       "origin": "js-markup",
       "confidence": "certain"
     },
@@ -6227,12 +6227,21 @@
       "origin": "js-markup",
       "confidence": "certain"
     },
+    {
+      "id": "e3b473af2f69",
+      "surface": "builders-hall",
+      "text": "Kind of work",
+      "file": "modules/hall-ui/public/hall-render.js",
+      "line": 1173,
+      "origin": "js-markup",
+      "confidence": "certain"
+    },
     {
       "id": "7d6eaa8d4514",
       "surface": "builders-hall",
       "text": "Kinds of work shipped",
       "file": "modules/hall-ui/public/hall-render.js",
-      "line": 1194,
+      "line": 1286,
       "origin": "js-markup",
       "confidence": "certain"
     },
@@ -6691,7 +6700,7 @@
       "surface": "builders-hall",
       "text": "Metic rank and above may vote",
       "file": "modules/hall-ui/public/builders.js",
-      "line": 743,
+      "line": 789,
       "origin": "js-markup",
       "confidence": "certain"
     },
@@ -10165,7 +10174,7 @@
       "surface": "builders-hall",
       "text": "The page could not be loaded. Try again.",
       "file": "modules/hall-ui/public/builders.js",
-      "line": 1425,
+      "line": 1484,
       "origin": "js-notice",
       "confidence": "certain"
     },
@@ -10876,7 +10885,7 @@
       "surface": "builders-hall",
       "text": "Upvote (+1)",
       "file": "modules/hall-ui/public/builders.js",
-      "line": 739,
+      "line": 785,
       "origin": "js-markup",
       "confidence": "certain"
     },
@@ -10957,7 +10966,7 @@
       "surface": "builders-hall",
       "text": "Vote on this work",
       "file": "modules/hall-ui/public/builders.js",
-      "line": 739,
+      "line": 785,
       "origin": "js-markup",
       "confidence": "certain"
     },
@@ -12685,7 +12694,7 @@
       "surface": "builders-hall",
       "text": "no data",
       "file": "modules/hall-ui/public/hall-kit.js",
-      "line": 705,
+      "line": 735,
       "origin": "js-markup",
       "confidence": "certain"
     },
@@ -13972,7 +13981,7 @@
       "surface": "builders-hall",
       "text": "— all builders —",
       "file": "modules/hall-ui/public/builders.js",
-      "line": 675,
+      "line": 721,
       "origin": "js-markup",
       "confidence": "certain"
     },
@@ -14107,7 +14116,7 @@
       "surface": "builders-hall",
       "text": "…{…} more open ideas — triage clears them one at a time.",
       "file": "modules/hall-ui/public/builders.js",
-      "line": 857,
+      "line": 903,
       "origin": "js-markup",
       "confidence": "certain"
     },

package/docs/module-api-changelog.md

@@ -2174,5 +2174,9 @@ is load-bearing: the script throws rather than guess if it is missing, and
         landed since 1.19.848 with no explicit bump. run 35269098215. (task 1002620)
   1.19.850 — CI auto-patch (publish-on-merge, ADR 0161): carrier for merges
         landed since 1.19.849 with no explicit bump. run 35271402682. (task 1002620)
+  1.19.851 — CI auto-patch (publish-on-merge, ADR 0161): carrier for merges
+        landed since 1.19.850 with no explicit bump. run 35274042996. (task 1002620)
+  1.19.852 — CI auto-patch (publish-on-merge, ADR 0161): carrier for merges
+        landed since 1.19.851 with no explicit bump. run 35274827497. (task 1002620)
 ---------------------------------------------------------------------------
 ```

package/docs/recipes/core-release-pipeline.md

@@ -95,7 +95,7 @@ node scripts/gds/package-core.js --ref main --self-verify
 
 `package-core` archives the **committed** tree at `--ref`, never your working tree, and stamps the version from `CORE_VERSION` *at that ref*. Full mechanics — the fail-closed no-leak gate, the `tree_sha256` integrity pin, the pruned lockfile — in [packaging-the-core](packaging-the-core.md).
 
-> ⚠️ **Packaging a mid-flight `main` produces a stale version number.** If `CORE_VERSION` at your ref is still the previous value, your tarball is stamped with a version the fleet may already have. `bongos upgrade` refuses only the **equal** case (`already on <v>`, and `--force` bypasses even that) — it has **no downgrade guard**, so a target *below* what is installed proceeds and silently installs older code. Confirm the bump is actually in your ref before packaging.
+> ⚠️ **Packaging a mid-flight `main` produces a stale version number.** If `CORE_VERSION` at your ref is still the previous value, your tarball is stamped with a version the fleet may already have. `bongos upgrade` refuses the **equal** case (`already on <v>`; `--force` bypasses that) and a target **below** what is installed or pinned (task [#1004009](https://cloudbongos.com/builders#/task/1004009); `--allow-downgrade` is the only way through — `--force` is not). That second refusal lives in the **installed** core, so an instance still on a core that predates it has no such guard: there a lower target proceeds and silently installs older code. Confirm the bump is actually in your ref before packaging.
 
 ### 2c. Publish — automatic on merge
 
@@ -246,12 +246,21 @@ git tag --list 'core-v*' --contains <your-merge-sha> | sort -V | head -1
 
 This paste is the **owner’s**: the permission classifier’s treatment of a mutating `sudo` over ssh **varies by session** — some sessions permit it, others block every ssh including read-only probes and `backup.js --trigger`. Don’t retry into a block; hand the owner the line. The `!` prefix also keeps ssh honest: a bare `ssh host` is non-interactive here — it connects, prints the MOTD, and exits — so the command must ride as an argument.
 
+**Re-read `coreVersion` on `/version` immediately before running — a prepared `--to` goes stale within the hour.** Live moves by other paths (another session's bump, the subscription sweep), so the version you picked in Step 1 may already be behind what is serving:
+
+```
+curl -s https://cloudbongos.com/version
+```
+
+If live is **at or past** `<VER>`, stop and pick again. On 2026-09-17 a paste prepared against 1.19.838 ran an hour later against 1.19.841, and `--to 1.19.840` took two merged PRs off live while printing `✓ upgrade complete`. `bongos upgrade` now refuses a `--to` older than the installed core (task [#1004009](https://cloudbongos.com/builders#/task/1004009); `--allow-downgrade` is the deliberate way through) — but the refusal only exists once live is on a core that carries it, and it cannot catch a `--to` that is merely *not the newest*. The re-read is still the step.
+
 ```
-! ssh -i ~/.ssh/otb_builder jaxri@REDACTED_IP "sudo -n bash -c 'set -a; . /etc/cloudbongos/npm.env; set +a; cd /home/lars/cloudbongos-instance && sudo -n -u lars --preserve-env=NPM_TOKEN env PGDATABASE=cloudbongos CLOUDBONGOS_INSTANCE_ROOT=/home/lars/cloudbongos-instance ./node_modules/.bin/bongos upgrade --to <VER> --registry --commit-pin --restart-cmd \"sudo systemctl restart cloudbongos.service\" --health-url http://127.0.0.1:3002/healthz'"
+! ssh -i ~/.ssh/otb_builder jaxri@REDACTED_IP "sudo -n bash -c 'set -a; . /etc/cloudbongos/npm.env; set +a; cd /home/lars/cloudbongos-instance && sudo -n -u lars --preserve-env=NPM_TOKEN env PGDATABASE=cloudbongos BONGOS_INSTANCE_ROOT=/home/lars/cloudbongos-instance ./node_modules/.bin/bongos upgrade --to <VER> --registry --commit-pin --restart-cmd \"sudo systemctl restart cloudbongos.service\" --health-url http://127.0.0.1:3002/healthz'"
 ```
 
 What each piece is for — each guards a failure that actually happened:
 
+- **`BONGOS_INSTANCE_ROOT`, not `CLOUDBONGOS_INSTANCE_ROOT`.** The legacy spelling still works but prints a deprecation warning three times per run and stops being read in core 1.21; the new spelling is verified in this exact line (2026-09-17, twice).
 - **The token lives in root-only `/etc/cloudbongos/npm.env`, and is handed DOWN to `lars`.** This is the step that used to be documented wrongly, so read it before improvising. `NPM_TOKEN` is **not** in lars’s environment, **not** in the interactive profile, and **not** in `/home/lars/.npmrc` — all three probed empty (2026-08-17). An earlier version of this runbook grepped `~/.npmrc` and therefore aborted on its own `[ -n "$NPM_TOKEN" ]` guard every time. Worse, it could not have worked even if that file were populated: the project `.npmrc` says `_authToken=<redacted>, which **overrides** lars’s user `~/.npmrc`, so the variable is the only channel. Hence the shape above: `set -a; . /etc/cloudbongos/npm.env; set +a` reads it as **root** (mode 600), and `--preserve-env=NPM_TOKEN` hands it to the unprivileged `lars` — exactly what systemd does for the sweep unit (`User=lars` + `EnvironmentFile=`). Without it npm falls back to the **public** registry, 404s on the private `@bongos/core`, and rolls back cleanly having taught you nothing.
 - **Never put the token in the command line — `sudo` logs the full argv (task 1003218).** The shape above is safe *because* the token is read INSIDE the quoted script, so only the `grep` reaches argv. The tempting variant is not:
   ```

package/docs/recipes/upgrading-the-core.md

@@ -8,6 +8,7 @@
 
 `bongos upgrade --to <version> --from <tgz>` runs, from a consumer instance root:
 
+0. **downgrade guard** (task [#1004009](https://example.com/builders#/task/1004009)) — a `--to` **older** than this instance's core is refused before anything moves, in one line naming both versions and the newest published release. "This instance's core" is the **newer** of what is installed and what is pinned, because a half-applied bump leaves the two apart and the pin is the thing about to be overwritten. `--force` does not waive it; `--allow-downgrade` does, and the run then says `DOWNGRADE` in its first line, its last line and its `core_upgrades` ledger note. Migrations are never reverted, so going backwards across one leaves the DB ahead of the code; and an instance subscribed to an update channel is taken forward again by the next sweep, so set it to `pinned` first if the downgrade is meant to hold. Auto-rollback (step 8) restores its own pin and is unaffected.
 1. **pre-flight** — module-compat vs the target core + a clean git tree (skip with `--force`).
 2. **bump the pin** — vendor the new `bongos-core-<version>.tgz` and rewrite the `"@bongos/core": "file:vendor/…"` dependency.
 3. **`npm install`** — `node_modules/@bongos/core` becomes the new version.

package/docs/recipes/windows-builders.md

@@ -214,7 +214,7 @@ caught a real bug during task 1003548, so read its assertion before blaming the
 
 - Several hall files (`people.css`, `people.html`, `style.css`, the privacy spec) and every `.claude/skills/*/SKILL.md` are CRLF; `scripts/gds/*.js` and the tests are LF. An exact-string patch must detect the file's EOL before joining lines (`text.includes('\r\n') ? '\r\n' : '\n'`), or the find matches nothing and the edit is a silent no-op (session log 2026-08-24).
 - A `git diff --stat` that touches every line of a file you barely edited is an EOL flip — check with `git diff --stat --ignore-cr-at-eol`, and restore the original EOL before committing.
-- **`copy-inventory.js --check` no longer reds on line endings alone** (task 1003619). It used to: the generator emits LF and the check byte-compared that against a CRLF worktree file, so `/ship-check` showed one permanent red line on every Windows checkout while the committed content was already correct — and a builder who "fixed" it committed a whole-file CRLF diff. `docs/copy-inventory.md` is now pinned `text eol=lf` in `.gitattributes` (its `.json` sibling always was, via `*.json`), and the check compares EOL-blind so an already-CRLF worktree passes without a re-clone. If it reports STALE now, the content really is stale — regenerate, don't reach for `--ignore-cr-at-eol`. Note `*.md` is deliberately NOT pinned repo-wide; only that one generated artifact is.
+- **`copy-inventory.js --check` no longer reds on line endings alone** (task 1003619). It used to: the generator emits LF and the check byte-compared that against a CRLF worktree file, so `/ship-check` showed one permanent red line on every Windows checkout while the committed content was already correct — and a builder who "fixed" it committed a whole-file CRLF diff. `docs/copy-inventory.md` is now pinned `text eol=lf` in `.gitattributes` (its `.json` sibling always was, via `*.json`), and the check compares EOL-blind so an already-CRLF worktree passes without a re-clone. If it reports STALE now, the content really is stale — regenerate, don't reach for `--ignore-cr-at-eol`. Since task 1003981 `*.md` IS pinned repo-wide (`*.md text eol=lf`), so a fresh clone gets LF markdown everywhere and a markdown reader no longer has to be CRLF-aware to be correct. An EXISTING Windows checkout keeps its CRLF copies until git rewrites them — the clean filter still normalises to LF on add, so `git status` stays quiet and nothing is broken; to convert in place, `git rm --cached -r . && git reset --hard`.
 - **A freshness check compares CONTENT, so route it through `sameContent()`** (`scripts/gds/gen-freshness.js`) rather than `===` on file bytes. A pin is the wrong lever on its own: regenerating never clears a byte-wise red, because the write lands LF and git converts it back on the next checkout. `tests/gen_freshness.mjs` enforces this for the four gated generators; `tests/api_client.mjs` was outside that guard and reported the client STALE forever on Windows until task 1003529 (`index.d.ts` and `README.md` are the two generated client files with no `eol=lf` pin).
 
 ## Four Windows traps that make a test lie — all four found in one pass (task 1003529)

package/modules/hall-ui/public/builders.js

@@ -625,27 +625,73 @@
     const scroll = $('#analytics-scroll');
     if (!scroll || !builder?.id) return;
     analyticsState.builderId = builder.id;
-    analyticsState.isArchon = (builder.rank || '').toLowerCase() === 'archon';
     analyticsState.scope = 'self';
+    analyticsState.kind = null;
     try {
       const self = await getJSON(`${API}/analytics/builder/${builder.id}?days=90`);
       analyticsState.self = self;
+      // The picker's options come from THIS first, unfiltered load and are then
+      // left alone — see kindFilterHtml. A later filtered payload's top_kinds is
+      // deliberately not allowed to overwrite them.
+      analyticsState.kinds = Array.isArray(self?.top_kinds) ? self.top_kinds : [];
       // A gated newcomer with nothing shipped: keep the section hidden.
       if (!self || (self.headline?.total_shipped || 0) === 0) { scroll.hidden = true; return; }
       scroll.hidden = false;
       renderCurveBody();
       renderNav(builder, lastMeState?.onboarding || null); // re-show the Curve chip now that the section is visible
-      if (analyticsState.isArchon) {
-        getJSON(`${API}/public/analytics/ecosystem?days=90`)
-          .then((eco) => { analyticsState.eco = eco; if (analyticsState.scope === 'eco') renderCurveBody(); })
-          .catch(() => { /* ecosystem optional */ });
-      }
+      // THE BENCHMARK IS FOR EVERY BUILDER, NOT JUST THE ARCHON (task 1004005).
+      // This fetch used to sit behind `if (analyticsState.isArchon)`, so the
+      // ecosystem average a builder is meant to measure themselves against was
+      // fetched for exactly one of them. The route is `rank: public` — no auth
+      // middleware, CORS '*', per-builder identity stripped server-side — and the
+      // unauthenticated status page already reads it, so the gate protected
+      // nothing and only withheld the comparison. Still fire-and-forget: the
+      // ecosystem feed is optional context, never a reason to hold up the curve.
+      getJSON(`${API}/public/analytics/ecosystem?days=90`)
+        // ALWAYS re-render, not only in the 'eco' scope. That condition was
+        // correct while the two scopes merely SWAPPED which single series was
+        // drawn; now the ecosystem series is also the benchmark overlaid on the
+        // 'self' view, so a self-scoped reader who arrived before this resolved
+        // would sit with no overlay until they touched an unrelated control.
+        .then((eco) => { analyticsState.eco = eco; renderCurveBody(); })
+        .catch(() => { /* ecosystem optional */ });
     } catch (err) {
       console.error('[builders] analytics load failed', err);
       scroll.hidden = true;
     }
   }
 
+  // Re-fetch BOTH series under a kind filter (task 1004005). Both, always: an
+  // overlay that narrowed one side and not the other would compare one kind of
+  // work against all work and still look like a like-for-like benchmark — the
+  // failure this task's own text calls worse than no benchmark at all.
+  //
+  // `kinds` is deliberately not refreshed here; see kindFilterHtml.
+  let curveKindSeq = 0;
+  async function reloadCurveForKind(kind) {
+    const id = analyticsState.builderId;
+    if (!id) return;
+    analyticsState.kind = kind;
+    // A dropdown can be changed faster than a round trip returns, and the two
+    // fetches can land out of order. Only the newest request may write state.
+    const seq = ++curveKindSeq;
+    const q = kind ? `&kind=${encodeURIComponent(kind)}` : '';
+    renderCurveBody(); // reflect the new selection immediately
+    try {
+      const [self, eco] = await Promise.all([
+        getJSON(`${API}/analytics/builder/${id}?days=90${q}`),
+        getJSON(`${API}/public/analytics/ecosystem?days=90${q}`).catch(() => null),
+      ]);
+      if (seq !== curveKindSeq) return;
+      analyticsState.self = self;
+      if (eco) analyticsState.eco = eco;
+      renderCurveBody();
+    } catch (err) {
+      if (seq !== curveKindSeq) return;
+      console.error('[builders] curve kind filter failed', err);
+    }
+  }
+
   // ---- karma feed (V3.R26 #246) -------------------------------------------
   //
   // The recent karma_log entries for the current builder. The /me payload
@@ -1204,6 +1250,19 @@
       renderCurveBody();
     });
 
+    // The kind filter (task 1004005). Delegated like the scope toggle, and for
+    // the same reason: renderCurveBody replaces the control's innerHTML, so a
+    // listener bound to the element itself would not survive the first render.
+    // 'change', not 'input' — a keyboard user arrowing through a native select
+    // fires input per option, and each one would be a pair of round trips.
+    $('#curve-body')?.addEventListener('change', (e) => {
+      const sel = e.target.closest('#curve-kind');
+      if (!sel) return;
+      const kind = sel.value ? sel.value : null;
+      if (kind === analyticsState.kind) return;
+      reloadCurveForKind(kind);
+    });
+
     // task 1723: the Home "show the setup guide again" link re-opens a dismissed
     // welcome banner (the old welcome chip's job) — clears the dismissal flag,
     // re-renders the panel, refreshes the nav, then scrolls to it.

package/modules/hall-ui/public/hall-kit.js

@@ -614,6 +614,12 @@
   const CHART_W = 260;
   const CHART_H = 46;
   const CHART_PAD = 3;
+  // The benchmark line's colour, fixed here and NOT a caller option (task
+  // 1004005). --ink-soft is the hall's existing muted tone, so the overlay is
+  // recessive in both themes without a new token. Keeping it out of `opts` is
+  // the point: if the benchmark could take any colour it would eventually take
+  // an accent one, and then the chart has two subjects and no ground.
+  const OVERLAY_COLOR = 'var(--ink-soft)';
 
   // A CSS length, for a value that lands in a style attribute rather than in
   // text — so it is WHITELISTED, not escaped: escaping would leave a ';' free
@@ -679,15 +685,24 @@
   // There is deliberately no `cumulative` option: `cumulate` is exported, so a
   // running-total line is `sparklineHtml(OTBKit.cumulate(values))` — one way to
   // do it rather than two, and no option whose only exercise is its own test.
+  // `scaleWith` is the ONE knob a two-series plot needs (task 1004005): extra
+  // numbers folded into the min/max so an overlaid series shares this one's
+  // vertical scale. Two lines each fitted to their own range is not a
+  // comparison — it is two unrelated shapes that LOOK like one, which is worse
+  // than no benchmark at all. Omit it and every number below is unchanged, so a
+  // single-series caller's output is byte-for-byte what it was.
   function linePoints(values, opts = {}) {
     const W = opts.width || CHART_W;
     const H = opts.height || CHART_H;
     const pad = opts.pad === undefined ? CHART_PAD : opts.pad;
     const nums = chartNums(values);
     const n = nums.length;
+    // The numbers the SCALE must cover — this series plus anything overlaid on
+    // it. `nums` alone still drives the point COUNT and the x positions.
+    const scaleNums = opts.scaleWith === undefined ? nums : nums.concat(chartNums(opts.scaleWith));
     // A flat series has span 0 and would divide by zero; 1 puts it mid-box.
-    const min = n ? Math.min(...nums) : 0;
-    const span = (n ? Math.max(...nums) : 0) - min || 1;
+    const min = scaleNums.length ? Math.min(...scaleNums) : 0;
+    const span = (scaleNums.length ? Math.max(...scaleNums) : 0) - min || 1;
     const x = (i) => (n === 1 ? W / 2 : pad + (i * (W - 2 * pad)) / (n - 1));
     const y = (v) => H - pad - ((v - min) / span) * (H - 2 * pad);
     return {
@@ -696,9 +711,24 @@
     };
   }
 
-  // A line + filled area. opts: { width, height, color, ariaLabel }
+  // A line + filled area. opts: { width, height, color, ariaLabel, overlay, overlayLabel }
+  //
+  // ONE SERIES IS STILL THE DEFAULT. modules/hall-ui/CLAUDE.md's rule — one
+  // series per chart, drawn in --accent, because a single series has no identity
+  // to encode — stands for every caller that passes no `overlay`. `overlay` is
+  // the owner-decided exception (task 1004005): a BENCHMARK behind the subject,
+  // not a second peer series. So the encoding is fixed here rather than left to
+  // the call site: the overlay is a muted grey line with NO area fill, drawn
+  // FIRST so the subject's own line and area sit on top of it. Grey is the
+  // meaning — it reads as background, so "you" stays the figure and "everyone"
+  // stays the ground. A caller wanting two equal series is asking for a
+  // different chart, and should not reach for this.
   function sparklineHtml(values, opts = {}) {
-    const g = linePoints(values, opts);
+    const overlay = opts.overlay === undefined ? null : chartNums(opts.overlay);
+    const hasOverlay = !!(overlay && overlay.length);
+    // Both series are fitted to the COMBINED range, so the two lines can be read
+    // against each other. See linePoints' `scaleWith`.
+    const g = linePoints(values, hasOverlay ? { ...opts, scaleWith: overlay } : opts);
     const color = opts.color || 'var(--accent)';
     if (!g.nums.length) {
       return `<svg class="kit-spark" viewBox="0 0 ${g.width} ${g.height}" preserveAspectRatio="none"`
@@ -706,9 +736,21 @@
     }
     const last = g.nums[g.nums.length - 1];
     const area = `${g.pad},${g.height - g.pad} ${g.points} ${g.width - g.pad},${g.height - g.pad}`;
-    const label = opts.ariaLabel || `trend, latest ${last}`;
+    // The overlay gets its own x spread (it may have a different number of
+    // points) but the SAME y scale, because each call folds the other series in.
+    const gOver = hasOverlay ? linePoints(overlay, { ...opts, scaleWith: g.nums }) : null;
+    const overLast = gOver ? gOver.nums[gOver.nums.length - 1] : null;
+    const label = opts.ariaLabel
+      || (hasOverlay
+        ? `trend, latest ${last}; ${opts.overlayLabel || 'benchmark'} ${overLast}`
+        : `trend, latest ${last}`);
     return `<svg class="kit-spark" viewBox="0 0 ${g.width} ${g.height}" preserveAspectRatio="none"`
       + ` role="img" aria-label="${esc(label)}">`
+      // Benchmark first = underneath. No area fill: two filled areas would
+      // muddy each other and neither would read as the subject.
+      + (gOver
+        ? `<polyline class="kit-spark__overlay" points="${gOver.points}" fill="none" stroke="${esc(OVERLAY_COLOR)}" />`
+        : '')
       + `<polyline class="kit-spark__area" points="${area}" fill="${esc(color)}" />`
       + `<polyline class="kit-spark__line" points="${g.points}" fill="none" stroke="${esc(color)}" />`
       // One point draws no line, so it gets a dot or the chart reads as empty.
@@ -1002,6 +1044,30 @@
   // Title + chart + optional foot — the frame all four sites drew by hand.
   // `inner` is already-built chart HTML, so the frame never needs to know
   // which shape it holds. That is what makes the fifth chart free.
+  // The legend a two-series plot owes the reader (task 1004005). A single line
+  // needs none — that is why the hall had no legend until the overlay existed —
+  // but two lines and no key is a chart that cannot be read at all, so this
+  // returns '' below two entries rather than drawing a pointless one.
+  //
+  // THE SWATCH IS AN SVG RECT, NOT A STYLED SPAN, and that is a security choice
+  // rather than a stylistic one. A chart colour here is a `var(--token)`, and
+  // CSS_LEN above deliberately REFUSES `var(` — so routing the colour through a
+  // style attribute would blank every swatch. An SVG `fill` attribute is the
+  // pattern sparklineHtml already uses for exactly these values, where esc() is
+  // the correct and sufficient guard.
+  function chartLegendHtml(entries) {
+    const rows = (entries || []).filter((e) => e && e.label);
+    if (rows.length < 2) return '';
+    return '<div class="kit-chart__legend">'
+      + rows.map((e) => '<span class="kit-chart__legend-item">'
+        + '<svg class="kit-chart__legend-swatch" viewBox="0 0 10 10" width="10" height="10" aria-hidden="true">'
+        + `<rect x="0" y="4" width="10" height="2" fill="${esc(e.color || 'var(--accent)')}" />`
+        + '</svg>'
+        + esc(e.label)
+        + '</span>').join('')
+      + '</div>';
+  }
+
   function chartCardHtml(title, inner, foot, emptyMsg) {
     const body = inner || `<div class="kit-chart__empty">${esc(emptyMsg || 'no data in window')}</div>`;
     return '<div class="kit-chart">'
@@ -1150,7 +1216,7 @@
     // charts (task 1003445) — the ONE place the hall draws a series.
     // linePoints/cumulate are the maths on their own, for a chart that wants
     // the geometry without this SVG (the profile's timeChart).
-    sparklineHtml, barSeriesHtml, chartCardHtml, linePoints, cumulate, cumulateByDay,
+    sparklineHtml, barSeriesHtml, chartCardHtml, chartLegendHtml, linePoints, cumulate, cumulateByDay,
     // the year-grid contribution calendar (task 1003572) — the hall's third chart family
     calendarGridHtml,
     calendarWindow,

package/modules/hall-ui/public/hall-render.js

@@ -1107,7 +1107,15 @@
       </tr>
     `).join('');
   }
-  const analyticsState = { builderId: null, isArchon: false, scope: 'self', self: null, eco: null };
+  // No `isArchon` here: the curve's scope was rank-gated until task 1004005, and
+  // the field is gone rather than left write-only — a state flag nothing reads is
+  // how a removed gate quietly grows back.
+  //
+  // `kind` is the active filter (null = all work). `kinds` is the picker's source
+  // — the UNFILTERED fingerprint, held separately because a filtered payload's
+  // top_kinds would otherwise shrink to the one kind selected and strand the
+  // reader there with no way back.
+  const analyticsState = { builderId: null, scope: 'self', kind: null, kinds: [], self: null, eco: null };
   // The line drawing moved to OTBKit.sparklineHtml (task 1003445) — it was one
   // of four chart implementations in this surface. This wrapper keeps the
   // Curve's own default colour, which is NOT the kit's: these four charts each
@@ -1122,10 +1130,53 @@
       ${sub ? `<div class="curve__stat-sub">${escapeHtml(sub)}</div>` : ''}
     </div>`;
   }
-  function chartCard(title, values, color, footer) {
+  // `overlay` is the ecosystem benchmark for this same chart, or null. When it is
+  // present the card also carries a legend — two lines with no key cannot be
+  // read. The legend is built here rather than inside sparklineHtml because the
+  // NAMES are this page's ("You" / "All builders"), not the kit's.
+  function chartCard(title, values, color, footer, overlay) {
     const has = Array.isArray(values) && values.length > 0;
-    return window.OTBKit.chartCardHtml(title, has ? sparkline(values, { color }) : '', footer);
+    const hasOverlay = Array.isArray(overlay) && overlay.length > 0;
+    const body = has
+      ? sparkline(values, hasOverlay ? { color, overlay, overlayLabel: 'all builders' } : { color })
+      : '';
+    const legend = has && hasOverlay
+      ? window.OTBKit.chartLegendHtml([
+        { label: 'You', color },
+        { label: 'All builders', color: 'var(--ink-soft)' },
+      ])
+      : '';
+    return window.OTBKit.chartCardHtml(title, body ? body + legend : '', footer);
+  }
+  // The kind picker (task 1004005) — "how am I doing at THIS kind of work".
+  //
+  // Built from analyticsState.kinds, the UNFILTERED fingerprint captured on the
+  // first load, NOT from the current payload's top_kinds. Under a filter the
+  // payload would list only the selected kind, so a picker built from it would
+  // lose every other option the moment one was chosen — the reader could narrow
+  // once and never move again.
+  //
+  // A <select> rather than a row of chips: the kind list is open-ended (it is a
+  // free-text column with an 'unspecified' bucket), so the control has to cope
+  // with more options than fit on a line, and a native select is also the one
+  // that arrives keyboard- and screen-reader-correct with no work.
+  function kindFilterHtml() {
+    const kinds = Array.isArray(analyticsState.kinds) ? analyticsState.kinds : [];
+    if (kinds.length < 2) return ''; // one kind of work is not a choice
+    const cur = analyticsState.kind;
+    const opt = (value, label, n) => {
+      const sel = (value === null ? cur === null : cur === value) ? ' selected' : '';
+      const count = n === undefined ? '' : ` (${n})`;
+      return `<option value="${escapeHtml(value === null ? '' : value)}"${sel}>${escapeHtml(label)}${escapeHtml(count)}</option>`;
+    };
+    return `<span class="curve__filter">`
+      + `<label class="curve__filter-label" for="curve-kind">Kind of work</label>`
+      + `<select id="curve-kind" class="curve__filter-select">`
+      + opt(null, 'All work')
+      + kinds.map((k) => opt(k.kind, k.kind, k.n)).join('')
+      + `</select></span>`;
   }
+
   function renderCurveBody() {
     const headlineEl = $('#curve-headline');
     const gridEl = $('#curve-grid');
@@ -1137,17 +1188,34 @@
     const isEco = analyticsState.scope === 'eco';
     const data = isEco ? analyticsState.eco : analyticsState.self;
 
-    // Scope toggle (Archon only).
-    if (analyticsState.isArchon && noteEl) {
+    // The controls — scope toggle and kind filter.
+    //
+    // WRITTEN BEFORE EVERY EARLY RETURN BELOW, and that ordering is the whole
+    // reason they are here. A kind with nothing shipped in the window is an
+    // ordinary, reachable state, and it takes the `totalShipped === 0` branch —
+    // which blanks the headline, the grid and the bars. If the filter that
+    // caused the empty view were drawn after that return, the reader would be
+    // left looking at "no data" with no control on screen to undo it, and the
+    // only way out would be a page reload.
+    //
+    // The scope toggle is no longer Archon-gated (task 1004005): the feed behind
+    // "All builders" is a public, identity-stripped aggregate, so the gate
+    // withheld the comparison rather than protecting anything.
+    if (noteEl) {
       noteEl.innerHTML =
         `<span class="curve__scope" role="group" aria-label="Analytics scope">` +
         `<button type="button" class="curve__scope-btn${!isEco ? ' is-active' : ''}" data-scope="self">You</button>` +
         `<button type="button" class="curve__scope-btn${isEco ? ' is-active' : ''}" data-scope="eco">All builders</button>` +
-        `</span>`;
+        `</span>` +
+        kindFilterHtml();
     }
 
     if (!data) { gridEl.innerHTML = ''; headlineEl.innerHTML = ''; kindsEl.innerHTML = ''; return; }
 
+    // Under a kind filter the server cannot answer cost at all (cost_log has no
+    // kind), and says so in `unavailable` rather than sending a misleading zero.
+    const costUnavailable = Array.isArray(data.unavailable) && data.unavailable.includes('cost_trend');
+
     const totalShipped = data.headline?.total_shipped || 0;
     if (totalShipped === 0) {
       if (emptyEl) emptyEl.style.display = '';
@@ -1164,7 +1232,11 @@
       cards.push(statCard('Active builders', h.active_builders ?? 0));
       cards.push(statCard('Avg time / work', mins(h.avg_duration_min)));
     } else {
-      cards.push(statCard('Cost / work', usd(h.cost_per_task)));
+      // '—', never usd(null) → "$0.00". Zero is a measurement; this is the
+      // absence of one, and printing a price here would be a false statement.
+      cards.push(costUnavailable
+        ? statCard('Cost / work', '—', 'not tracked per kind')
+        : statCard('Cost / work', usd(h.cost_per_task)));
       cards.push(statCard('Avg time / work', mins(h.avg_duration_min)));
       cards.push(statCard('Confirmation rate', pct(h.confirmation_rate), `${h.resolved_claims || 0} claims`));
       cards.push(statCard('Grade pass rate', pct(h.grade_pass_rate), `${h.graded_n || 0} graded`));
@@ -1172,14 +1244,34 @@
     headlineEl.innerHTML = cards.join('');
 
     // Sparkline charts.
+    //
+    // THE OVERLAY ONLY EVER RIDES ON THE 'self' VIEW, and only where the
+    // ecosystem publishes the SAME series. Overlaying the benchmark on the
+    // benchmark would draw one line twice; and the ecosystem feed carries only
+    // ship-rate and duration (grade and cost have their own public feeds and are
+    // not part of that payload), so those two are the only charts that CAN
+    // compare. A chart with no counterpart simply draws one line, as before.
+    const eco = (!isEco && analyticsState.eco) ? analyticsState.eco : null;
+    const ecoOf = (rows, pick) => (eco && Array.isArray(eco[rows]) ? eco[rows].map(pick) : null);
     const charts = [];
     charts.push(chartCard('Works shipped / day', (data.ship_rate || []).map((r) => r.n), 'var(--accent-deep)',
-      `${(data.ship_rate || []).reduce((s, r) => s + Number(r.n), 0)} over ${data.window_days}d`));
+      `${(data.ship_rate || []).reduce((s, r) => s + Number(r.n), 0)} over ${data.window_days}d`,
+      ecoOf('ship_rate', (r) => r.n)));
     charts.push(chartCard('Time / work (min)', (data.duration_trend || []).map((r) => r.avg_actual), 'var(--sea)',
-      'actual minutes per shipped work'));
+      'actual minutes per shipped work',
+      ecoOf('duration_trend', (r) => r.avg_actual)));
     if (!isEco) {
-      charts.push(chartCard('Cost / work ($)', (data.cost_trend || []).map((r) => r.per_work), 'var(--terracotta)',
-        `total ${usd(h.total_cost_usd)}`));
+      // COST IS NOT ANSWERABLE PER KIND — cost_log has no kind and reaches tasks
+      // only through a mostly-NULL task_id, so the server returns cost_trend: []
+      // and names it in `unavailable` rather than plotting a near-zero line that
+      // would read as "this kind of work is cheap". Say so where the chart was.
+      if (costUnavailable) {
+        charts.push(window.OTBKit.chartCardHtml('Cost / work ($)', '',
+          '', 'not tracked per kind of work — clear the filter to see cost'));
+      } else {
+        charts.push(chartCard('Cost / work ($)', (data.cost_trend || []).map((r) => r.per_work), 'var(--terracotta)',
+          `total ${usd(h.total_cost_usd)}`));
+      }
       // n counts quality-graded rows only (task 1002652); a day whose grades
       // were all outages has n=0 and must not plot as a 0% dip.
       charts.push(chartCard('Grade pass rate', (data.grade_trend || []).filter((r) => Number(r.n) > 0).map((r) => r.n_passed / r.n), 'var(--accent)',