zz-meridian 0.16.0 → 0.16.1

package/README.md

@@ -39,7 +39,9 @@ Brand flags: `--name "Acme Ops"`, `--hex '#2E6BE4'` (or `--accent indigo|cobalt|
 in a page's kicker ("Production"); it does not touch the navigation workspaces.
 
 **adopt** copies Meridian's tokens, styles, components, gates and scripts into `src/`, `tokens/` and `scripts/`;
-merges the dependencies and scripts it needs into your `package.json`; replaces your global stylesheet (yours is kept
+merges the dependencies and scripts it needs into your `package.json`; adds the `@meridian/*` alias to your
+`tsconfig.json` (yours is kept as `tsconfig.before.json` when it carries comments or trailing commas, which JSON
+cannot hold); replaces your global stylesheet (yours is kept
 beside it as `*.before.css`); brands it; adds Meridian's managed block to your `AGENTS.md` between two markers, keeping your own text there byte
 for byte; writes an empty `docs/brief.md` (your product, users, data, decisions and glossary) if you have none; installs the skill into
 `.agents/skills/` (Codex) and `.claude/skills/` (Claude Code); records every Meridian file it copied in `.meridian/manifest.json`;

package/dist/adopt.js

@@ -8,7 +8,7 @@
  */
 import fs from 'node:fs';
 import path from 'node:path';
-import { VERSION, brandArgs, effectiveBrand, inside, installSkill, packageManager, payloadBytes, payloadFiles, readJsonc, readPayload, relativeImports, run, runTool, sha256, writeIn, writeManifest, } from './files.js';
+import { VERSION, brandArgs, effectiveBrand, inside, installSkill, jsoncExtras, packageManager, payloadBytes, payloadFiles, readJsonc, readPayload, relativeImports, run, runTool, sha256, writeIn, writeManifest, } from './files.js';
 import { BRIEF_TEMPLATE, managedBlock, upsertManagedBlock } from './context.js';
 import { FIXED, adoptSetOf, managedPaths } from './ownership.js';
 /** The template's dependencies a dashboard built from these files needs. */
@@ -123,6 +123,39 @@ export default defineConfig({
 });
 `;
 }
+/**
+ * What `adopt` writes for a team's `tsconfig.json`, and what it must say about it: the file Meridian's code needs (its
+ * scripts import with `.ts` extensions, its code is ES2022, `@meridian/*` reaches its files), the team's own kept beside
+ * it when it carries what `JSON.stringify` cannot hold, and what their `@/*` alias stands for. A function rather than a
+ * block inside `adopt` so a test can hold it to those three: a test that ran the whole `adopt` would need the template
+ * the payload carries, which a checkout has only after a build, and it would be testing the copy, not this decision.
+ */
+export function tsconfigWrites(tsPath) {
+    const writes = new Map();
+    const notes = [];
+    const ts = readJsonc(tsPath);
+    ts.compilerOptions ??= {};
+    ts.compilerOptions.allowImportingTsExtensions = true;
+    ts.compilerOptions.noEmit = true;
+    if (!/^es20(2[2-9]|[3-9]\d)|^esnext$/i.test(ts.compilerOptions.target ?? '')) {
+        notes.push(`raised tsconfig target from ${ts.compilerOptions.target ?? 'its default'} to ES2022`);
+        ts.compilerOptions.target = 'ES2022';
+    }
+    ts.compilerOptions.paths ??= {};
+    ts.compilerOptions.paths['@meridian/*'] = ['./src/*'];
+    const at = ts.compilerOptions.paths['@/*']?.[0];
+    const atAlias = typeof at === 'string' ? at.replace(/\/\*$/, '').replace(/^\.\//, '') || '.' : null;
+    // A tsconfig may carry comments and trailing commas, which `next dev` keeps (`comment-json`) and `JSON.stringify`
+    // cannot hold. What the team wrote is kept beside the rewritten file, as the stylesheet and the postcss config are,
+    // rather than dropped in silence — the note says so, and there is no backup to explain when there was nothing to lose.
+    const was = fs.readFileSync(tsPath, 'utf8');
+    writes.set('tsconfig.json', JSON.stringify(ts, null, 2) + '\n');
+    if (jsoncExtras(was)) {
+        writes.set('tsconfig.before.json', was);
+        notes.push('tsconfig.json carried comments or trailing commas, which the rewritten file cannot: yours is tsconfig.before.json');
+    }
+    return { writes, notes, atAlias };
+}
 export function adopt(o) {
     const { root } = o;
     const say = (s) => console.log(s);
@@ -230,20 +263,11 @@ Rename or move them, then run adopt again.`);
     const tsPath = path.join(root, 'tsconfig.json');
     let atAlias = null;
     if (fs.existsSync(tsPath)) {
-        const ts = readJsonc(tsPath);
-        ts.compilerOptions ??= {};
-        ts.compilerOptions.allowImportingTsExtensions = true;
-        ts.compilerOptions.noEmit = true;
-        if (!/^es20(2[2-9]|[3-9]\d)|^esnext$/i.test(ts.compilerOptions.target ?? '')) {
-            notes.push(`raised tsconfig target from ${ts.compilerOptions.target ?? 'its default'} to ES2022`);
-            ts.compilerOptions.target = 'ES2022';
-        }
-        ts.compilerOptions.paths ??= {};
-        ts.compilerOptions.paths['@meridian/*'] = ['./src/*'];
-        const at = ts.compilerOptions.paths['@/*']?.[0];
-        if (typeof at === 'string')
-            atAlias = at.replace(/\/\*$/, '').replace(/^\.\//, '') || '.';
-        writes.set('tsconfig.json', JSON.stringify(ts, null, 2) + '\n');
+        const ts = tsconfigWrites(tsPath);
+        for (const [f, text] of ts.writes)
+            writes.set(f, text);
+        notes.push(...ts.notes);
+        atAlias = ts.atAlias;
     }
     else {
         return fail('no tsconfig.json: Meridian is TypeScript. Add one (next dev writes it), then run adopt again.');

package/dist/cli.js

@@ -7,6 +7,7 @@ import os from 'node:os';
 import path from 'node:path';
 import { parseArgs } from 'node:util';
 import { adopt } from './adopt.js';
+import { misapplied } from './command-flags.js';
 import { create } from './create.js';
 import { BRAND_FLAGS, VERSION, installSkill } from './files.js';
 import { brandCommand } from './rebrand.js';
@@ -75,6 +76,12 @@ function main() {
         console.log(HELP);
         return command || values.help ? 0 : 1;
     }
+    // A flag a command does not read is refused, never ignored: `adopt --dry-run` wrote the project rather than previewing it.
+    const wrong = misapplied(command, flags);
+    if (wrong) {
+        console.error(`zz-meridian ${command}: --${wrong.flag} belongs to ${wrong.belongsTo}`);
+        return 1;
+    }
     if (command === 'adopt')
         return adopt({ root: process.cwd(), brand, allowDirty: Boolean(values['allow-dirty']), install });
     if (command === 'create') {

package/dist/command-flags.js

@@ -0,0 +1,38 @@
+/**
+ * Which flags each command reads. A flag that names a mode or a value belongs to the command that acts on it: anywhere
+ * else it is refused by name rather than accepted and ignored, so `adopt --dry-run` never modifies a project while the
+ * person waits for a preview.
+ */
+import { BRAND_FLAGS } from './files.js';
+/** Every command reads these. */
+const EVERYWHERE = ['help', 'version'];
+/** The brand flags, read by the commands that write a brand. */
+const BRAND = BRAND_FLAGS;
+/** What each command reads, beyond the two above. */
+const ACCEPTS = {
+    adopt: [...BRAND, 'allow-dirty', 'no-install'],
+    create: [...BRAND, 'no-install'],
+    update: ['allow-dirty', 'no-install', 'dry-run', 'resume', 'finalize', 'abort', 'verify', 'verbose'],
+    brand: [...BRAND, 'allow-dirty'],
+    skill: ['global'],
+};
+/** The commands that read one flag, in the CLI's own order, for the sentence that sends the person to the right one. */
+function commandsReading(flag) {
+    return Object.keys(ACCEPTS).filter((c) => ACCEPTS[c].includes(flag));
+}
+/**
+ * The first flag a command does not read, with the command it belongs to; null when every flag is the command's own.
+ * `update` is the one command with no spelling of its own, so a flag only it reads is named as its own.
+ */
+export function misapplied(command, flags) {
+    const accepted = ACCEPTS[command];
+    if (!accepted)
+        return null;
+    for (const [flag, value] of Object.entries(flags)) {
+        if (value === undefined || EVERYWHERE.includes(flag) || accepted.includes(flag))
+            continue;
+        const others = commandsReading(flag);
+        return { flag, belongsTo: others.length ? `zz-meridian ${others.join(' or ')}` : 'no command' };
+    }
+    return null;
+}

package/dist/files.js

@@ -82,10 +82,10 @@ export function runTool(root, entry, args, quiet = true) {
     return spawnSync(process.execPath, [path.join(root, 'node_modules', entry), ...args], { cwd: root, encoding: 'utf8', stdio: quiet ? 'pipe' : 'inherit' });
 }
 export const hasCommand = (cmd) => spawnSync(cmd, ['--version'], { stdio: 'ignore', shell: process.platform === 'win32' }).status === 0;
-/** JSON with the comments and trailing commas a tsconfig may carry. */
-export function readJsonc(file) {
-    const text = fs.readFileSync(file, 'utf8');
+/** A JSONC document's text with the comments dropped, and whether anything had to be dropped to read it. */
+function strippedJsonc(text) {
     let out = '';
+    let dropped = false;
     for (let i = 0, str = false; i < text.length; i++) {
         const c = text[i];
         if (str) {
@@ -102,12 +102,14 @@ export function readJsonc(file) {
             continue;
         }
         if (c === '/' && text[i + 1] === '/') {
+            dropped = true;
             while (i < text.length && text[i] !== '\n')
                 i++;
             out += '\n';
             continue;
         }
         if (c === '/' && text[i + 1] === '*') {
+            dropped = true;
             i += 2;
             while (i < text.length && !(text[i] === '*' && text[i + 1] === '/'))
                 i++;
@@ -116,8 +118,19 @@ export function readJsonc(file) {
         }
         out += c;
     }
-    return JSON.parse(out.replace(/,(\s*[}\]])/g, '$1'));
+    const json = out.replace(/,(\s*[}\]])/g, '$1');
+    return { json, dropped: dropped || json.length !== out.length };
 }
+/** JSON with the comments and trailing commas a tsconfig may carry. */
+export function readJsonc(file) {
+    return JSON.parse(strippedJsonc(fs.readFileSync(file, 'utf8')).json);
+}
+/**
+ * Whether a project's file carries what plain JSON cannot hold: a comment, or a trailing comma. `next dev` writes a
+ * tsconfig through `comment-json`, which keeps both, so a tool that re-serialises one drops what the team's own
+ * toolchain preserves — and this is the question to ask before doing it.
+ */
+export const jsoncExtras = (text) => strippedJsonc(text).dropped;
 /**
  * Meridian's own `@/` imports, made relative to the file. An adopting project may map `@/` somewhere else, or already
  * have a `components/ui/button`; a relative import can never resolve to the team's file instead of Meridian's.

package/dist/migrations.js

@@ -511,6 +511,37 @@ function refusalUndeclared(root) {
         return null;
     return /^export const refusal\b/m.test(body) ? null : [rel];
 }
+/** The nav item objects of a nav array, by brace: an object naming an `href` of its own, however many lines it is over. Braces inside a quoted value are not braces. */
+function navItemObjects(nav) {
+    const found = [];
+    const open = [];
+    let quote = null;
+    for (let i = 0; i < nav.length; i++) {
+        const ch = nav[i];
+        if (quote) {
+            if (ch === '\\')
+                i++;
+            else if (ch === quote)
+                quote = null;
+            continue;
+        }
+        if (ch === "'" || ch === '"' || ch === '`')
+            quote = ch;
+        else if (ch === '{')
+            open.push(i);
+        else if (ch === '}') {
+            const start = open.pop();
+            if (start === undefined)
+                continue;
+            const inner = nav.slice(start + 1, i);
+            // What is left once the objects inside it are taken out: a group's `href`s are all in its items, so a group has
+            // none of its own left and is not an item.
+            if (/\bhref\s*:/.test(inner.replace(/\{[^{}]*\}/g, '')))
+                found.push(inner);
+        }
+    }
+    return found;
+}
 /** The project's own nav, with any item still missing the `needs` that 0.13.0 requires of it. */
 function navItemsWithoutNeeds(root) {
     const rel = 'src/app.config.ts';
@@ -520,16 +551,17 @@ function navItemsWithoutNeeds(root) {
     const nav = /export const nav\b[^=]*=\s*\[([\s\S]*?)\n\];/.exec(body)?.[1];
     if (nav === undefined)
         return null;
-    // One item per line, as `adopt` writes them and as a hand-kept nav keeps them, so the item is the line naming its
-    // `href`: a group's opening line — every project groups its nav — names no `href` and carries no `needs` of its own,
-    // so counting it as an item would report a change no edit can settle. Anything the file does beyond that is the
-    // team's own shape, and none of it is read.
-    const items = nav.split('\n').filter((l) => /\bhref\s*:/.test(l));
+    // The item is the object naming its `href`, read by its braces rather than by its line: a team that spreads an item
+    // over its keys put the `needs` two lines below the `href`, and a line-based read reported the migration for a file
+    // with none of the old shape left in it. A group is not a destination and carries no `needs`: its own `href`s belong
+    // to the items inside it, so an object whose braces hold only other objects is not read. Anything the file does
+    // beyond that is the team's own shape, and none of it is read.
+    const items = navItemObjects(nav);
     // A project of 0.12.3's vintage also declares `NavItem` itself, without the property: an item that names a `needs` its
     // own type does not have is the type error the gate prints next, so the change is not done until the type carries it.
     const declaredType = /export type NavItem[^;]*\};/.test(body);
     const typeHasNeeds = /export type NavItem[^;]*\bneeds\s*:/.test(body);
-    return items.some((l) => !/\bneeds\s*:/.test(l)) || (declaredType && !typeHasNeeds) ? [rel] : null;
+    return items.some((item) => !/\bneeds\s*:/.test(item)) || (declaredType && !typeHasNeeds) ? [rel] : null;
 }
 /**
  * The page specifications under a route group of the project's own, at the top of its app folder, that lack the part the

package/dist/rebrand.js

@@ -165,8 +165,19 @@ function attempt(ctx, change, allowDirty) {
 }
 /** The command: the real context, which replays the running release and runs its branding script in scratch. */
 export function brandCommand({ root, flags, allowDirty }) {
-    const scratch = fs.mkdtempSync(path.join(os.tmpdir(), 'zz-meridian-brand-'));
     const log = (line) => (line.startsWith('zz-meridian brand:') ? console.error(line) : console.log(line));
+    // The flags are read before anything is copied, and a value the branding script refuses is refused here with the
+    // command's own sentence: `adopt` and `create` read the same flags through `effectiveBrand` and answer its Error
+    // (`adopt.ts:153`, `create.ts:19`), where `brand` let it out as a stack trace.
+    let brand;
+    try {
+        brand = effectiveBrand(flags);
+    }
+    catch (e) {
+        log(`zz-meridian brand: ${e.message}`);
+        return 1;
+    }
+    const scratch = fs.mkdtempSync(path.join(os.tmpdir(), 'zz-meridian-brand-'));
     const replays = new Map();
     let n = 0;
     try {
@@ -204,7 +215,7 @@ export function brandCommand({ root, flags, allowDirty }) {
                 return fs.readFileSync(path.join(copy, APP_CONFIG), 'utf8');
             },
         };
-        return rebrand(ctx, effectiveBrand(flags), { allowDirty });
+        return rebrand(ctx, brand, { allowDirty });
     }
     finally {
         fs.rmSync(scratch, { recursive: true, force: true });

package/dist/session.js

@@ -265,8 +265,11 @@ function install(ctx, session, j, pm) {
     const { root } = ctx;
     const lock = lockfileFor(root, pm);
     const prior = j.operations.find((o) => o.path === lock && o.disposition === 'team-preserved' && o.applied);
-    const before = prior ? prior.base : probe(root, lock).side;
     const backup = path.join(session, 'backup', lock);
+    // The preimage is what the lockfile was before this update's install, and the first run wrote it here before running
+    // one. A resumed run that probed the project instead takes whatever a killed install left behind as "ours", and an
+    // abort would then put a half-written lockfile back in place of the team's.
+    const before = prior ? prior.base : fs.existsSync(backup) ? sideOf(sha(fs.readFileSync(backup))) : probe(root, lock).side;
     if (before.exists && !fs.existsSync(backup))
         writeAtomic(backup, fs.readFileSync(inside(root, lock)));
     const t0 = performance.now();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "zz-meridian",
-  "version": "0.16.0",
+  "version": "0.16.1",
   "description": "Bring ZZ Meridian, a dashboard design system, into a Next.js project, or start a new dashboard on it. Copies the files in; nothing depends on this package at runtime.",
   "license": "MIT",
   "type": "module",

package/payload/CHANGELOG.md

@@ -2,6 +2,42 @@
 
 Every release of ZZ Meridian, newest first. Versions follow semver: a removed or renamed token, prop or card is major; a new card, token or variant is minor; a corrected value is a patch. Each entry says what breaks and what to do instead.
 
+## [0.16.1] · 2026-10-16
+
+### Breaking
+
+- **The literal-colour rule reads more forms.** `scripts/check.ts` matched `#rrggbb`, `#rgb`, `rgb(`/`rgba(` and `hsl(`/`hsla(`. It now reads a hex of four or eight digits too — `#0a5F`, `#0a58caFF` — and `oklch()`, `oklab()`, `lab()`, `lch()` and `color()`. A gate that passed can fail on a line that writes one of them: use a role or a token (`text-ink`, `border-line`, `var(--…)`), or mark the line `allow-literal-colour` where the colour is genuinely a literal of its own, as an embed's simulated host and a third party's brand are. A colour composed from tokens is not a literal and is not reported, so `color-mix(in oklch, var(--ink) 40%, transparent)` stays as it is.
+- **A flag a command does not read is refused, not ignored.** `zz-meridian adopt --dry-run` — and any other flag named outside the command that reads it — exits 1, naming the command it belongs to. A CI step that passed one did nothing quietly; it fails now, which is what it should have done.
+- **A figure nobody measured is `null`, not zero.** `RequestSummary.p95` and `RequestSummary.errorShare` (`src/data/requests.ts`) are `null` when the set is empty, and `MetricTile.points` is `(number | null)[]`; `NowData`'s per-model `p95` and `errorRate` are `null` for a model with no usage row. A page, a fixture or a test of yours that builds one of them adds the `null` case; a tile whose point is `null` draws a gap where it drew a fall to zero, and the request log says "not measured" where it said `0ms` and `0.0%`.
+- **The audit's two truncated-value rules mean what the card contract says.** `scripts/audit.ts` accepted any `title` anywhere near a cut value without comparing it with the text, and read `aria-labelledby` as the attribute's own value instead of resolving the ids it names. Both compare now, so a `verify --full` that passed can fail: put the whole of a cut value in a `title` that *holds* it (a title of something else keeps none of it), and name a real element with `aria-labelledby` — an id that is nowhere is a control with no name. `CONTRIBUTING.md` promised both all along.
+- **The backend gate refuses a data URL it cannot read the host of.** `unsafeBackend` (`scripts/verify.ts`) skipped a value it could not read the host of, which is how a DSN written without a scheme (`user:pass@db.prod.example.com:5432/app`), a password holding a `/` or a `#`, or a libpq line (`host=… user=…`) reached the presses. The authority is read with its credentials dropped, a value whose host still cannot be read is refused rather than skipped, and a host named in the query string is read the way libpq reads it — `postgres:///app?host=db.prod.example.com` reaches that host, since libpq takes the host from the query and lets it override the authority, dials `hostaddr` when both are named, keeps the last value of a keyword it is given twice, and treats `/…` as a Unix socket, which stays local. A file scheme that names a host is another machine's file (`file://db.prod.example.com/share/app.db`) or a database over the network (`libsql://…`) rather than a file of this machine's. A refusal names the way out: point the value at a local copy for the run, or set `allowRemoteData: true` in `scripts/verify.config.ts`.
+
+### New
+
+- **`readAll(name, q)`** (`src/data/read.ts`) answers with every row a collection holds, asking the same question of every page: a list that counts, totals or claims "every" starts there, and a `limit` passed to it is ignored, because its answer means every row. `readEndpoints`, `readServices` and the incident read that joins each ticket go through it, and so do the Members and the Keys view tools and the three pages that list them: the endpoint list, the incidents the bell and Services count, every member, every key and every service are now all of them, where each was the first hundred. A page of yours that read one page of a collection and called it every row reads through `readAll` too.
+
+### Changed
+
+- **Home says no service is monitored yet.** A services read that succeeded and returned no rows had the page's title and its line say "every service is operational" while the page's own fact said "0 of 0 operational". Both say the empty state now, in the words the Services and Now pages already use.
+- **`adopt` keeps a commented tsconfig beside the rewritten one.** `adopt` rewrites `tsconfig.json` to raise the target and add the `@meridian/*` path, and `JSON.stringify` cannot hold a comment or a trailing comma. When the team's file carries either, it is kept as `tsconfig.before.json` and the notes say so; a plain tsconfig gets no backup.
+- **`brand` reports a flag it cannot use.** `brand --theme purple` printed an uncaught `Error` where `adopt` and `create` answer the same value with a sentence. All three report it the same way now, before anything is copied.
+- **The standard names three motion loops.** The token layer defines three (`--dur-loop-spin`, `--dur-loop-shimmer`, `--dur-loop-pulse`) and the Motion floor and the Skeleton card named two. All three are named everywhere now, and `tests/motion-loops.test.ts` holds the count to the tokens.
+
+### Fixed
+
+- **A held-back answer agrees with itself.** The line an answer ends with when the 3,000-character cap holds part of it back read "1 more line are not shown."; it reads "1 more line is not shown.", and the row messages follow.
+- **A resumed update keeps the lockfile preimage a killed install left behind.** `--resume` probed the project for the team's lockfile, so a lockfile a killed install had rewritten stood in as "ours" and an abort would have put a half-written file back in place of the team's. It comes from the session's backup now.
+- **The prepared query's 3,000-character cap bounds the whole answer.** It bounded the drilled rows, the one part it could shorten, so a summary over budget by itself came back over.
+- **`nav-needs` reads a nav item by its braces.** An item a team had spread over its keys was reported as missing a `needs` that was two lines below its `href`.
+- **Copy says "Copied" only when the copy happened.** A refused clipboard write left the button saying it had copied.
+- **The short date is one function.** `formatShortDate` (`01 Oct`) and `formatDay` (`3 Oct`) in `src/lib/format-date.ts`; six copies of the same expression in five views and a chart preview are gone, and four sentences that wrote the day in two different ways agree.
+- **A project created in another timezone passes its own gate.** A shipped test pinned the template's timezone; it states the project's own now, so `create --timezone Europe/London` no longer fails the gate it ships with.
+- **A credit reads as a credit.** `formatCost` wrote `$-0.0050` for an amount under a cent; the sign goes before the currency, as `-$0.0050`.
+- **Home's focus line states no ratio against a median of zero**, where it printed `NaN×`.
+- **A required control inside a `Field` is announced as required.** A `Select` given `required`, or inside `<Field required>`, carries `aria-required` on its trigger, where nothing announced it.
+- **Three checks in `scripts/` say what they measured.** A failed performance run shows in the coverage line rather than only in the phase; the keyboard walk prints "and the same in reverse" only when it compared the reverse walk; and `audit --atlas` reads its key list from this repository rather than from the folder it was run in. The pagination card's README no longer claims a page size in the address that the table does not keep.
+- **The 0.16.0 section below was corrected in place.** Revenue's own needs were stated twice and one of them wrongly; nothing a product renders changed.
+
 ## [0.16.0] · 2026-10-15
 
 ### Breaking
@@ -34,7 +70,6 @@ Every release of ZZ Meridian, newest first. Versions follow semver: a removed or
 - **A request is priced at its model's price.** `usageOf()` prices a request from the `models` records and from no list of its own: its tokens at its model's prices a million, the price of a call when it reached no model, nothing when it was refused. The list of $3 and $15 a million tokens and $0.10 a thousand calls is gone, so every cost on a request's page moved.
 - **The ticket boundary's refusal for a fixed field has new words.** It reads "A ticket's id, its times and its incident are set by the system and cannot be changed." A test of yours that matches the sentence matches the new one.
 - **Home, Usage and Revenue hand their pages a `head`.** `HomeData`, `UsageData` and `RevenueData` each hold `head`, what the page states at its head: `{ title, facts, unknown? }` (`PageHead` in `src/views/fact-insight.ts`), worked out on the server by the view tool's read. Home's `head.facts` are the facts of a year, and `HomeData` holds `line`, the line under its title, where it held `unwell`. A fixture or a test of yours that builds one of the three adds them: `head: { title: null, facts: [] }` draws a page headed by its name, and `unwell: null` says nothing of the services.
-- **Revenue asks for the days.** `FEATURES.revenue.needs` is `{ allOf: ['customers:read', 'days:read'] }`, because its title reads them. Every role of the sample that reads customers reads the days too. A role of yours that holds `customers:read` alone no longer opens `/business`: grant it `days:read`.
 - **Now and Services hand their pages a `head`.** `NowData` and `ServicesData` each hold `head`, the page's title and the days inside the band (`PageHead` in `src/views/fact-insight.ts`), worked out on the server by the view tool's read. A fixture or a test of yours that builds one of them adds it: `head: { title: null, facts: [] }` draws a page headed by its name.
 - **Now and Services ask for more.** `FEATURES.now.needs` is `{ allOf: ['services:read', 'incidents:read', 'releases:read', 'tests:read', 'days:read', 'usage:read', 'models:read', 'compute:read', 'endpoints:read', 'tickets:read', 'activity:read'] }` and `FEATURES.services.needs` is `{ allOf: ['services:read', 'incidents:read', 'days:read'] }`: Now's title counts the releases in testing, which their verification runs decide, and both contexts count the days inside the band. Every role of the sample that reads the services holds them. A role of yours that does not no longer opens `/engineering` or `/services`: grant it what is missing. Now's eleven are what its read states beside the services, the releases and the days: each model, compute in use, the slowest endpoints, the work and the latest changes.
 - **Now's data states what engineering's parts draw.** `NowData` keeps `services`, `head`, `updatedAt` and `now`, loses `current` and `alsoOpen` (`incidents.open` holds every open incident, the most severe first), and adds `line`, `incidents`, `band`, `models`, `compute`, `shipping`, `work`, `endpoints`, `month`, `runs`, `activity` and `unread`, a part being `null` when its read failed. Build it with `nowData(reads)` from `src/views/now-parts.ts`, as `nowTool` does: a fixture or a test of yours that builds a `NowData` by hand builds it there instead. Now's body and its embed take it packed: `PackedNowBody` in `src/views/now.tsx` and `EmbedNow` in `app/embed/now/view.tsx` take `packNow(data)` from `src/views/now-context.ts`, which sends each strip to the browser one character a day; a page or a test of yours that renders either passes its `NowData` through `packNow` first. Now's context no longer lists every service with its latency: it states the services as their summary and each part's figures.

package/payload/app/(dashboard)/keys/page.tsx

@@ -1,6 +1,6 @@
 import { gate, gatedMetadata, may } from '@/data/access';
 import { ACTIONS } from '@/data/features';
-import { read } from '@/data/read';
+import { readAll } from '@/data/read';
 import { KeysView } from '@/views/keys';
 import type { ApiKey } from '@/data/sample';
 import { createKey, revokeKey } from './actions';
@@ -22,7 +22,7 @@ export function generateMetadata() {
 export default async function KeysPage() {
   const denied = await gate('keys');
   if (denied) return denied;
-  const { rows, observedAt } = await read('keys');
+  const { rows, observedAt } = await readAll('keys');
   const mayCreate = await may(ACTIONS['create-key'].needs);
   const mayRevoke = await may(ACTIONS['revoke-key'].needs);
   return (

package/payload/app/(dashboard)/members/page.tsx

@@ -1,6 +1,6 @@
 import { gate, gatedMetadata, may } from '@/data/access';
 import { invitableRoles, memberAccess, type MemberRowAccess } from '@/data/member-mutations';
-import { read } from '@/data/read';
+import { read, readAll } from '@/data/read';
 import { assignRole, inviteMember, removeMember, setMemberStatus } from './actions';
 import { MembersView } from '@/views/members';
 import type { Member } from '@/data/sample';
@@ -34,7 +34,7 @@ async function workspaceName(): Promise<string | undefined> {
 export default async function MembersPage() {
   const denied = await gate('members');
   if (denied) return denied;
-  const { rows, observedAt } = await read('members', { sort: { field: 'joined', dir: 'desc' } });
+  const { rows, observedAt } = await readAll('members', { sort: { field: 'joined', dir: 'desc' } });
   const members = rows as Member[];
   const [access, roles, workspace] = await Promise.all([
     Promise.all(members.map(async (m): Promise<readonly [string, MemberRowAccess]> => [m.id, await memberAccess(m.id)])).then((entries) => Object.fromEntries(entries)),

package/payload/app/(dashboard)/operations-tickets/page.tsx

@@ -1,6 +1,6 @@
 import { gate, gatedMetadata, may } from '@/data/access';
 import { ACTIONS } from '@/data/features';
-import { read } from '@/data/read';
+import { readAll } from '@/data/read';
 import { readTickets } from '@/data/tickets';
 import { TicketsView } from '@/views/tickets';
 import { createTicket, updateTicket } from './actions';
@@ -27,9 +27,9 @@ export default async function TicketsPage() {
     may(ACTIONS['create-ticket'].needs),
     may(ACTIONS['update-ticket'].needs),
     may('members:read'),
-    read('services'),
+    readAll('services'),
   ]);
-  const people = mayReadMembers ? (await read('members', { limit: 500 })).rows : [];
+  const people = mayReadMembers ? (await readAll('members')).rows : [];
   return (
     <TicketsView
       rows={rows}

package/payload/decisions/0006-quiet-light.md

@@ -18,4 +18,4 @@ After 0002, the owner asked for the overall feeling to be more refined and less
 ## Consequences
 
 - Every card picks up the ground's light; contrast is still computed by compositing the surface over the ground (`node scripts/contrast.ts`).
-- Nothing in the interface loops except a live dot and a skeleton.
+- Nothing in the interface loops except a live dot, a skeleton and a spinner's ring. (Amended 2026-10-16: this line named a dot and a skeleton; the spinner's ring is the third loop the token layer defines, and the standard's floor names all three.)

package/payload/docs/distribution.md

@@ -67,7 +67,8 @@ Then, in this order:
    fixture test (below) is what keeps it complete. A file of the same name that differs is never overwritten: `adopt`
    lists the conflicts and stops before writing anything.
 2. Merges dependencies and scripts into their `package.json`, keeping their versions where newer and compatible; adds
-   the `@meridian/* → ./src/*` alias to `tsconfig.json` when theirs differs (their own `@/*` is left as it is).
+   the `@meridian/* → ./src/*` alias to `tsconfig.json` when theirs differs (their own `@/*` is left as it is), keeping
+   theirs as `tsconfig.before.json` when it carries comments or trailing commas, which JSON cannot hold.
 3. Replaces their global stylesheet with the template's `app/globals.css`, keeping theirs as `app/globals.before.css`
    for the agent to port from.
 4. Runs `scripts/brand.ts --existing` with the brand arguments given (or the name from their `package.json`): the name,

package/payload/docs/surfaces.md

@@ -104,6 +104,7 @@ What exists, by layer, and how it changes per surface. "Same" means the card nee
 | Icons | Lucide at 1.75 stroke: 14, 16 and 18px | Same | Same |
 | Motion | Arrive, answer, float; reduced motion collapses all | Same | Arrive only on first render, so a re-render in the thread never replays |
 | App mark | The product mark at 20, 24, 28 and 32px | Same | 20px in the embed head |
+| Surface | Where a view is being read, the console or an MCP host, and what it may ask of that host: the bridge, the host's theme and style variables, and the one shared context both agents are told | The console, with no host: `expand` opens the console page | Started by EmbedFrame on every route under `app/embed/` |
 
 ### Layer 2 · Components
 
@@ -111,7 +112,7 @@ What exists, by layer, and how it changes per surface. "Same" means the card nee
 |---|---|
 | Actions | Button, Icon button, Menu |
 | Input | Field, Input, Textarea, Select, Checkbox, Radio group, Switch, Segmented, Search input |
-| Display | Card, Badge, Status dot, Delta, Avatar, Tooltip, Progress, Key value, Copy field, Kbd |
+| Display | Card, Badge, Status dot, Delta, Avatar, Agent mark, Tooltip, Progress, Key value, Copy field, Kbd, Popover |
 | Navigation | Tabs, Breadcrumb, Pagination |
 | Feedback | Banner, Toast, Dialog, Sheet, Empty state, Skeleton, Spinner |
 | Data | Table |
@@ -123,6 +124,8 @@ All components are surface-agnostic by construction: they size from control toke
 | Pattern | Job | Console | Mobile | Embed |
 |---|---|---|---|---|
 | Rail | Navigation, workspace, account, appearance | Fixed on the frame | In the drawer | None |
+| Shell tools | Search and commands (⌘K) and alerts, in the top bar of every console page | The top bar, one press away while the page scrolls | In the top bar, the same | None |
+| Assistant | The panel beside the page where a person asks about what they are looking at | A third column at `assistant-width` 400px from 1024px, a sheet over the page under it | The panel as a sheet | None: the host has its own conversation, and Ask posts into it |
 | Command palette | Every destination and global action behind ⌘K | Centred, 600px | Centred, the screen's width less 24px | None |
 | Appearance menu | Theme, accent, density | In the rail's foot | In the drawer's foot | None: the host decides the theme |
 | Period select | The reporting period, in the URL or held by the page | Masthead actions | Masthead actions row | None: the period is the tool's argument, named in the embed's title |
@@ -149,6 +152,7 @@ All components are surface-agnostic by construction: they size from control toke
 | Ask about | Hands a card to the agent as a question | On each page's protagonist (its Featured metric, its list or its record's card), when the assistant is on: opens the panel | Same, the panel as a sheet | On cards, when a host is connected |
 | Proposal | An agent's write, waiting for a person's Approve | In the assistant's thread | Same | The tool result's card |
 | Prose | Markdown a person or a model wrote, rendered safely | Reading width, `base` | One column; tables wrap | `sm`, host font |
+| Export button | The rows behind a view as a CSV, with the period and filters already applied, so the file matches the screen | A masthead action, after the period select; the browser reports the download when it has an `href` | Same | None: the console's export is the page's |
 
 ### Layer 4 · Pages
 

package/payload/package.json

@@ -1,6 +1,6 @@
 {
   "name": "zz-meridian-template",
-  "version": "0.16.0",
+  "version": "0.16.1",
   "private": true,
   "license": "MIT",
   "description": "ZZ Meridian: a dashboard design system and starter. Six layers, from DTCG tokens through four layers of React components to product workspaces, and a Design Atlas, in a light and a dark theme.",

package/payload/scripts/assistant.ts

@@ -210,7 +210,7 @@ try {
       const lines: [string, RegExp][] = [
         ['revenue with its definition', new RegExp(String.raw`^- Revenue: [^\d\s]*[\d,]+\.\d{2}${CHANGE}\. \(Billed for metered usage, before credits\.\)$`, 'm')],
         ['the gross margin an Owner reads', new RegExp(String.raw`^- Gross margin: [\d.]+%${POINTS}\. \(Revenue less compute cost, over revenue\.\)$`, 'm')],
-        ['the day in progress, counted in no total', /^- \d{2} [A-Z][a-z]{2} is in progress and counted in no total\.$/m],
+        ['the day in progress, counted in no total', /^- \d{1,2} [A-Z][a-z]{2} is in progress and counted in no total\.$/m],
       ];
       for (const [what, shape] of lines) if (!shape.test(viewContext)) fail(`Home's view context does not state ${what} (${shape})`);
       // It leads with the sentence the page is headed by.

package/payload/scripts/audit.ts

@@ -17,14 +17,17 @@
  * own content is measured like any other. A defined custom element that shows a box but exposes no open root and no
  * light-DOM content, and one that is still undefined after the settle wait, are reported as `unmeasured:` instead of passed.
  *
- * Fails (exit 1) on: sideways scroll, text clipped without an ellipsis, text cut with an ellipsis that keeps the whole
- * of it nowhere, two pieces of text in the same place or a line drawn through one, a control with no accessible name,
- * more than one page scroller, and rendered text under its WCAG minimum, an SVG's text included, read by its `fill`
- * against whatever the SVG paints behind it. Prints the design metrics per page: distinct type
- * sizes, weights and radii, and the hierarchy ratio (largest text over the median), which should be 3 or more on
- * an analytical page.
+ * Fails (exit 1) on: a route that served another page or dropped a parameter it was asked for, a page whose content
+ * region rendered nothing or that threw or logged a failure while it rendered, sideways scroll, text clipped without an
+ * ellipsis, text cut with an ellipsis that keeps the whole of it nowhere, two pieces of text in the same place or a line
+ * drawn through one, a control with no accessible name or one under 44px on touch, a heading two levels below the one
+ * before it, more than one page scroller, and rendered text under its WCAG minimum, an SVG's text included, read by its
+ * `fill` against whatever the SVG paints behind it. Prints the design metrics per page: distinct type sizes, weights and
+ * radii, and the hierarchy ratio (largest text over the median), which should be 3 or more on an analytical page.
+ * Every rule above has a page in `scripts/fixtures/deep/` that makes it fire.
  */
 import fs from 'node:fs';
+import path from 'node:path';
 import { atlasCoverage, atlasEntries } from './lib/atlas.ts';
 import { launch } from './lib/chrome.ts';
 import { DEEP_SOURCE } from './lib/deep.ts';
@@ -53,7 +56,9 @@ const ATLAS = args.includes('--atlas');
  */
 let atlasLine = '';
 async function atlasRoutes(): Promise<string[]> {
-  const file = 'app/system/preview/[section]/[card]/keys.ts';
+  // Resolved from this file, like every other path a check reads: run by hand from another folder, a bare relative path
+  // told a repository with an Atlas that it had none.
+  const file = path.resolve(import.meta.dirname, '../app/system/preview/[section]/[card]/keys.ts');
   if (!fs.existsSync(file)) { console.error('audit --atlas: this project has no Design Atlas to audit'); process.exit(1); }
   const keys = [...fs.readFileSync(file, 'utf8').matchAll(/'([a-z]+\/[a-z0-9-]+)'/g)].map((m) => m[1]);
   const cards = keys.flatMap((k) => [`/system/${k}`, `/system/preview/${k}`]);
@@ -137,9 +142,13 @@ const MEASURE = `(() => {
     }
     return b;
   };
-  // Text cut with an ellipsis has to keep the whole of itself where a pointer can reach it: a title on the element or
-  // on what holds it (a cell, a row, a link), or on the one thing inside it that the pointer is over.
-  const titled = (el) => { for (let n = el, i = 0; n && i < 4; n = deepParent(n), i++) if ((n.getAttribute('title') || '').trim()) return true; return [...el.querySelectorAll('[title]')].some((n) => n.getAttribute('title').trim()); };
+  // Text cut with an ellipsis has to keep the whole of itself where a pointer can reach it: a title attribute on the element or
+  // on what holds it (a cell, a row, a link), or on the one thing inside it that the pointer is over. The title has to
+  // *hold* the text, compared as a whole — a title on any ancestor or descendant used to count whatever it said, so a
+  // cell titled "Orders" over a cut account id passed as keeping it.
+  const whole = (s) => (s || '').replace(/\\s+/g, ' ').trim();
+  const keeps = (el, title) => { const t = whole(title), own = whole(el.textContent); return t.length > 0 && own.length > 0 && t.includes(own); };
+  const titled = (el) => { for (let n = el, i = 0; n && i < 4; n = deepParent(n), i++) if (keeps(el, n.getAttribute('title'))) return true; return [...el.querySelectorAll('[title]')].some((n) => keeps(el, n.getAttribute('title'))); };
   const inked = [];
   const ringSig = (c) => [c.outlineStyle, c.outlineWidth, c.outlineColor, c.boxShadow, c.borderTopStyle, c.borderTopWidth, c.borderTopColor, c.borderBottomColor, c.borderLeftColor, c.borderRightColor].join('|');
   const texts = [];
@@ -181,7 +190,11 @@ const MEASURE = `(() => {
     // A card drawn as a specimen in the Atlas keeps its own scroll regions; only the page's count against the one scroller.
     if (/(auto|scroll)/.test(c.overflowY) && el.scrollHeight > el.clientHeight + 1 && el.clientHeight > 120 && !deepClosest(el, '[data-specimen]')) out.scrollers.push(label(el));
     if (el.matches('button,a[href],[role="button"],[role="tab"],[role="switch"],[role="checkbox"],[role="radio"],input:not([type=hidden]),select,textarea')) {
-      const name = el.getAttribute('aria-label') || el.getAttribute('aria-labelledby') || el.getAttribute('title') || deepText(el).trim() || el.querySelector('img[alt]')?.getAttribute('alt') || (el.id && el.getRootNode().querySelector('label[for="' + el.id + '"]')?.textContent.trim()) || el.closest('label')?.textContent.trim() || el.getAttribute('placeholder') || '';
+      // A name is what the control is announced as. aria-labelledby names elements that hold it, and is worth
+      // nothing until they are looked up — the same lookup a label-for gets two terms later — so an id that names
+      // nothing leaves the control unnamed rather than passing on the attribute's own text.
+      const byIds = (attr) => (el.getAttribute(attr) || '').split(/\\s+/).filter(Boolean).map((id) => { const t = el.getRootNode().querySelector('#' + CSS.escape(id)); return t ? whole(t.textContent) : ''; }).join(' ').trim();
+      const name = el.getAttribute('aria-label') || byIds('aria-labelledby') || el.getAttribute('title') || deepText(el).trim() || el.querySelector('img[alt]')?.getAttribute('alt') || (el.id && el.getRootNode().querySelector('label[for="' + el.id + '"]')?.textContent.trim()) || el.closest('label')?.textContent.trim() || el.getAttribute('placeholder') || '';
       if (!name) out.unnamed.push(label(el));
       // On touch (a phone is emulated as one) every control answers at least 44px: its own box, its field's frame, or
       // the .hit square around it. A link inside running text is exempt, as WCAG exempts it.

package/payload/scripts/check.ts

@@ -7,7 +7,8 @@
  * - Every page specification exists and follows the page anatomy, and a page with a view tool says what the agent does
  *   there: its protagonist and at least three questions its prepared query answers.
  * - Every token a specification names in backticks, and every var(--x) or (--x) a component uses, exists.
- * - No literal colour (hex, rgb, hsl) and no Tailwind default palette in the layers: colours come from roles.
+ * - No literal colour (hex of 3, 4, 6 or 8 digits; rgb, hsl, oklch, oklab, lab, lch, color) and no Tailwind default
+ *   palette in the layers: colours come from roles.
  * - One implementation: the fixtures a collection serves are read through src/data/collections.ts, not imported again.
  * - In the template, `connection()` is called only where the request is meant to be read: the console layout and the
  *   not-found page; pages and views reach the sample through src/data, never src/system/fixtures; and a writer path
@@ -192,7 +193,10 @@ for (const f of LAYERS) {
     if (/allow-literal-colour/.test(line)) return;
     if (f === 'src/system/page-stage.tsx' && /HOST_STYLES|--color-|--border-radius|#2A2A30|#EDEDF0/.test(line)) return; // a simulated foreign host's own colours
     const at = `${f}:${i + 1}`;
-    const lit = line.match(/#[0-9a-fA-F]{6}\b|#[0-9a-fA-F]{3}\b(?![0-9a-fA-F])|\brgba?\(\s*\d|\bhsla?\(/);
+    // Literal colour, in every form a browser takes: hex of 3, 4, 6 or 8 digits, and the colour functions. A function
+    // is matched by its own name and its parenthesis, and not after a dot — so `color-mix(in oklch, var(--ink) 40%,
+    // transparent)`, which is how the layers compose a tint out of tokens, is not a literal and is not reported.
+    const lit = line.match(/#[0-9a-fA-F]{8}\b|#[0-9a-fA-F]{4}\b|#[0-9a-fA-F]{6}\b|#[0-9a-fA-F]{3}\b(?![0-9a-fA-F])|\brgba?\(\s*\d|\bhsla?\(|(?<![\w.$])(?:oklch|oklab|lab|lch|color)\(/);
     if (lit && !/^\s*(\*|\/\/|\/\*)/.test(line)) problems.push(`${at}: literal colour ${lit[0]} (use a role)`);
     // Meridian resets Tailwind's scales; a utility outside them emits no CSS and fails silently.
     const dead = line.match(/\b(?:font-(?:normal|light|bold|extrabold|black|thin)|rounded-(?:2xl|3xl)|shadow-(?:sm|md|lg|xl|2xl)|text-(?:3xl|4xl|5xl))\b/);