zz-meridian 0.29.0 → 0.30.0

package/dist/adopt.js

@@ -8,7 +8,7 @@
  */
 import fs from 'node:fs';
 import path from 'node:path';
-import { VERSION, brandArgs, effectiveBrand, inside, installArgs, installSkill, jsoncExtras, packageManager, payloadBytes, payloadFiles, readJsonc, readPayload, relativeImports, run, runTool, sha256, writeIn, writeManifest, } from './files.js';
+import { VERSION, brandArgs, effectiveBrand, inside, installArgs, installSkill, jsoncExtras, packageManager, payloadBytes, payloadFiles, readJsonc, readPayload, relativeImports, skillPaths, 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. */
@@ -92,8 +92,15 @@ export function projectConfig(template, pages) {
         .replace(' workspace?: WorkspaceId;', '')
         .replace(/export const nav: NavGroup\[\] = \[[\s\S]*?\n\];/, `/** Written by zz-meridian adopt from the project's pages: give each its own icon and group them. */\nexport const nav: NavGroup[] = [\n  {\n    items: [\n${items}\n    ],\n  },\n];`);
 }
-function verifyConfig() {
-    return readPayload('scripts/verify.config.ts').replace(/const config: VerifyConfig = \{[\s\S]*?\n\};/, `const config: VerifyConfig = {
+/**
+ * `scripts/verify.config.ts` as a project gets it. The sample's persona rows are what used `EVERY_ROUTE`, so replacing the
+ * config object leaves the constant declared and never read — which the gate's own lint fails, in the project adopt just
+ * wrote, 0.7 s after the other steps passed. Exported so a test can hold the rewrite to that.
+ */
+export function verifyConfig() {
+    return readPayload('scripts/verify.config.ts')
+        .replace(/^const EVERY_ROUTE = \[[^\n]*\n/m, '')
+        .replace(/const config: VerifyConfig = \{[\s\S]*?\n\};/, `const config: VerifyConfig = {
   // One detail page per state worth seeing (a normal record, a failed one, a missing one), with ids from your data.
   detailRoutes: [],
   // What a route a persona may not open draws: the product's choice in src/app.config.ts.
@@ -123,6 +130,18 @@ export default defineConfig({
 });
 `;
 }
+/**
+ * The ESLint configuration a project already has, or `null`. A flat `eslint.config.*` is what ESLint 9 reads; an
+ * `.eslintrc.*` is the legacy form it no longer loads. A function rather than a block inside `adopt` because the
+ * question is the project's alone — does it have one, and is it the form the installed ESLint reads — and a test can put
+ * a file in a folder and ask it, where running the whole `adopt` would need the payload a checkout has only after a build.
+ */
+export function eslintConfigOf(root) {
+    const found = ['eslint.config.ts', 'eslint.config.mts', 'eslint.config.js', 'eslint.config.mjs', 'eslint.config.cjs',
+        '.eslintrc.js', '.eslintrc.cjs', '.eslintrc.json', '.eslintrc', '.eslintrc.yml', '.eslintrc.yaml']
+        .find((f) => fs.existsSync(path.join(root, f)));
+    return found ? { file: found, legacy: /^\.eslintrc/.test(found) } : null;
+}
 /**
  * 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
@@ -224,6 +243,14 @@ https://github.com/zhixuan312/zz-meridian/blob/master/skills/zz-meridian/referen
     // Meridian's scripts are ES modules; a project whose package.json is not "type": "module" gets that for scripts/ only.
     if (pkg.type !== 'module')
         own('scripts/package.json', '{\n  "type": "module"\n}\n');
+    // The agent skill is copied in at the end, after every other write. Checking it here is what stops `adopt` replacing a
+    // team's own edited copy of it: the skill was written unconditionally, so an edited `SKILL.md` in the project was lost
+    // without a word and the command still exited 0. It is checked against the same rule as every other file.
+    for (const { rel, payload } of skillPaths()) {
+        const abs = path.join(root, rel);
+        if (fs.existsSync(abs) && !fs.readFileSync(abs).equals(Buffer.from(payloadBytes(payload))))
+            conflicts.push(rel);
+    }
     if (conflicts.length) {
         return fail(`these files already exist with other content, so nothing was written:\n${conflicts.map((c) => `  ${c}`).join('\n')}
 Rename or move them, then run adopt again.`);
@@ -300,6 +327,17 @@ Rename or move them, then run adopt again.`);
         writes.set('vitest.config.ts', vitestConfig(atAlias));
     else
         notes.push('kept your vitest config: add tests/setup.ts to its setupFiles and passWithNoTests for the gate');
+    // The gate's lint step runs `eslint .`, and a project with no configuration fails it 0.7 s in with ESLint's own message
+    // about a missing file — which says nothing about Meridian. Measured on a project created by create-next-app with
+    // --no-eslint and then adopted: every other gate step passed and the lint was the only red.
+    const eslint = eslintConfigOf(root);
+    if (!eslint) {
+        writes.set('eslint.config.ts', readPayload('eslint.config.ts'));
+        notes.push('added eslint.config.ts: the gate runs the lint, and this project had no ESLint configuration');
+    }
+    else if (eslint.legacy) {
+        notes.push(`kept ${eslint.file}, which ESLint 9 no longer reads: the gate's lint fails until it becomes an eslint.config.mjs`);
+    }
     if (!fs.readdirSync(path.join(root, dir)).some((f) => /^(icon|favicon)\./.test(f)))
         writes.set(`${dir}/icon.ts`, exactImports(`${dir}/icon.ts`, readPayload('app/icon.ts'), known));
     const ignore = path.join(root, '.gitignore');

package/dist/files.js

@@ -17,10 +17,25 @@ export const VERSION = JSON.parse(fs.readFileSync(path.resolve(path.dirname(file
  */
 export const shippedPath = (rel) => (rel === '.gitignore' ? 'gitignore' : rel);
 export const projectPath = (rel) => (rel === 'gitignore' ? '.gitignore' : rel);
+/**
+ * The message a checkout gets when it asks for the payload and nobody has built it. `cli/payload/` is a build output, so
+ * a fresh clone has none, and without this the failure was a bare `ENOENT` on whichever file the reader wanted first, or
+ * — worse — an empty list, which a test read as "the template has no skill files".
+ */
+const NOT_BUILT = 'cli/payload/ has not been built: run `node cli/scripts/build-payload.ts` (or `--worktree` to build what the working tree holds) and run this again.';
 /** A payload file's bytes, by its project path. */
-export const payloadBytes = (rel) => fs.readFileSync(path.join(PAYLOAD, shippedPath(rel)));
+export function payloadBytes(rel) {
+    if (!fs.existsSync(PAYLOAD))
+        throw new Error(NOT_BUILT);
+    const abs = path.join(PAYLOAD, shippedPath(rel));
+    if (!fs.existsSync(abs))
+        throw new Error(`${rel} is not in cli/payload/, which was built before that file was added or left it out: run \`node cli/scripts/build-payload.ts\` again.`);
+    return fs.readFileSync(abs);
+}
 /** Every file under a payload folder, as project paths. Symbolic links are never followed. */
 export function payloadFiles(dir = '') {
+    if (!fs.existsSync(PAYLOAD))
+        throw new Error(NOT_BUILT);
     const out = [];
     const walk = (rel) => {
         for (const e of fs.readdirSync(path.join(PAYLOAD, rel), { withFileTypes: true })) {
@@ -153,17 +168,22 @@ export function writeManifest(root, m) {
     const sorted = Object.fromEntries(Object.entries(m.files).sort(([a], [b]) => a.localeCompare(b)));
     writeIn(root, '.meridian/manifest.json', JSON.stringify({ ...m, files: sorted }, null, 2) + '\n');
 }
-/** The agent skill, into the folders each agent reads in a repository: Codex (.agents) and Claude Code (.claude). */
-export function installSkill(root, record) {
+/**
+ * Where the skill goes: the folders each agent reads in a repository, Codex (`.agents`) and Claude Code (`.claude`), and
+ * the file in the payload each is written from. The same list is what `adopt` checks before it writes anything, so a
+ * team's own copy is never overwritten behind their back.
+ */
+export function skillPaths() {
     const files = payloadFiles('skills/zz-meridian');
-    for (const base of ['.agents/skills/zz-meridian', '.claude/skills/zz-meridian']) {
-        for (const f of files) {
-            const rel = `${base}/${f.slice('skills/zz-meridian/'.length)}`;
-            const content = payloadBytes(f);
-            writeIn(root, rel, content);
-            if (record)
-                record[rel] = sha256(content);
-        }
+    return ['.agents/skills/zz-meridian', '.claude/skills/zz-meridian'].flatMap((base) => files.map((f) => ({ rel: `${base}/${f.slice('skills/zz-meridian/'.length)}`, payload: f })));
+}
+/** The agent skill, into the folders each agent reads in a repository. */
+export function installSkill(root, record) {
+    for (const { rel, payload } of skillPaths()) {
+        const content = payloadBytes(payload);
+        writeIn(root, rel, content);
+        if (record)
+            record[rel] = sha256(content);
     }
 }
 /** Brand flags passed through to scripts/brand.ts, in the order it reads them. */

package/dist/migrations.js

@@ -540,7 +540,34 @@ export const RELEASE_MIGRATIONS = [
         instructions: `Read "The four layers" and "The path an existing product follows" in references/data-layers.md. Thirty-eight modules moved into the logic layer, and each import of one in your own \`src/views/\` producers and pages names the path it left: ${MOVED_LIST}. Rewrite each import to the path the module has now, or move your own module beside the work it does. Two symbols left a card of Meridian's, and both must be rewritten because the update replaces the card: \`afterStart\`, which the incident card exported, is \`@/logic/after-start\`, and \`summarise\`, which the status list re-exported, is \`@/logic/summarise\`. Every other path your own files name is still there, so a project that imported neither symbol keeps building as it was. The six layer rules stay off until your own \`scripts/check.local.ts\` exports \`fourLayers = true\`; turn them on once your figures have moved, and the gate and the build are what show the work is done.`,
         checks: GATE_AND_BUILD,
     },
+    {
+        id: 'direct-query-escape',
+        since: '0.30.0',
+        applies: (root) => matching(root, (rel, src) => /^(?:app|src\/(?:logic|views|lib))\//.test(rel) && SOURCE.test(rel) && /\.query\s*\(/.test(src.replace(/\/\/[^\n]*/g, '')) && !/allow-no-direct-query:/.test(src)),
+        summary: 'A direct `.query(` call is allowed only where the call states its own escape: `// allow-no-direct-query: <why>`, on that line.',
+        instructions: 'Since 0.30.0 `node scripts/check.ts` reports every `.query(` call in `app/`, `src/logic/`, `src/views/` and `src/lib/`, and keeps the run passing only where the call\'s own line carries the escape the check prints — `// allow-no-direct-query: read() cannot serve this — <why>`. Before this release the rule allowed five sites of the template\'s by line number, so a file of your own that read a collection directly passed as long as the call sat on one of those lines; that list is gone, because a comment added above a call moved it off the line and turned a passing project red for no reason. Read every file named above. Where the read has to be direct — a server action reading the record it is about to change, a streamed export, the sign-in resolving a person before an `AccessScope` exists — state the reason on that line in the form the check prints. Everywhere else, read through `read()`, `readAll()` or `aggregate()` from `@/data/read`, which ask the caller\'s grant.',
+        checks: ['gate'],
+    },
+    {
+        id: 'app-description',
+        since: '0.30.0',
+        applies: appDescriptionMissing,
+        summary: 'The product describes itself in one sentence: `description` in the `app` object of `src/app.config.ts`.',
+        instructions: 'The release\'s `app/layout.tsx` shows `app.description` as the document\'s description — the line a search engine and a link preview put under the name — where it used to write a sentence of the template\'s own. `src/app.config.ts` is yours and an update does not touch it, so the key is missing there until you add it. Add `description: \'<one sentence about your product>\',` to the `app` object beside `name`. A project that keeps its own `app/layout.tsx` needs the key all the same, because the layout a project brings over from the release reads it.',
+        checks: ['gate'],
+    },
 ];
+/** The `app` object of a project's configuration, as `src/app.config.ts` writes it. */
+const APP_OBJECT = /^export const app = \{[\s\S]*?^\} as const;$/m;
+/** 0.30.0: the release's layout reads `app.description`, and a project's own configuration has no such key. */
+function appDescriptionMissing(root) {
+    const rel = 'src/app.config.ts';
+    const body = text(root, rel);
+    if (body === null)
+        return null;
+    const object = APP_OBJECT.exec(body)?.[0];
+    return object && !/\bdescription\s*:/.test(object) ? [rel] : null;
+}
 /**
  * A test of the rail that stands over a fake `ResizeObserver` answering `observe` with nothing (0.16.2). The lookbehind
  * keeps `unobserve() {}` out of it: a fake that answers the callback and also stubs `unobserve` is the release's own

package/dist/session.js

@@ -69,12 +69,28 @@ const pidAlive = (pid) => {
         return e.code === 'EPERM';
     }
 };
+/**
+ * The session folders under `.meridian/update/`, oldest name first. Only folders: the same folder holds whatever else a
+ * person's tools leave there — Finder's `.DS_Store`, an editor's swap file — and one of those read as a session is a
+ * version that does not exist. `loadSession` filtered for that and this did not, so a stray file made `status` report a
+ * session of version `.DS_Store` and made `update` prescribe `npx zz-meridian@.DS_Store update --resume`, which then
+ * refused, leaving no way forward. One list, read the same way by both.
+ */
+export function sessionDirs(root) {
+    const base = path.join(root, '.meridian', 'update');
+    if (!fs.existsSync(base))
+        return [];
+    return fs.readdirSync(base).filter((n) => { try {
+        return fs.lstatSync(path.join(base, n)).isDirectory();
+    }
+    catch {
+        return false;
+    } }).sort();
+}
 /** The phase of the one session folder under `.meridian/update/`, or a note when it cannot be read. */
 function sessionState(root) {
     const base = path.join(root, '.meridian', 'update');
-    if (!fs.existsSync(base))
-        return null;
-    const [first] = fs.readdirSync(base).sort();
+    const [first] = sessionDirs(root);
     if (!first)
         return null;
     let phase = 'unreadable';
@@ -506,7 +522,7 @@ function serializeManifest(m) {
  */
 function loadSession(ctx) {
     const base = path.join(ctx.root, '.meridian', 'update');
-    const names = fs.existsSync(base) ? fs.readdirSync(base).filter((n) => fs.lstatSync(path.join(base, n)).isDirectory()).sort() : [];
+    const names = sessionDirs(ctx.root);
     if (names.length === 0)
         return 'there is no update session in .meridian/update/; start one with npx zz-meridian@latest update';
     if (names.length > 1)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "zz-meridian",
-  "version": "0.29.0",
+  "version": "0.30.0",
   "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/.env.example

@@ -14,3 +14,11 @@
 
 # The provider's address. Required for "openai-compatible"; optional for "anthropic".
 # ASSISTANT_BASE_URL=
+
+# The demo gate: see src/lib/demo-gate.ts. The Docker image (Dockerfile) refuses to start without a password, and the
+# product is ungated without one, so this is the whole of "run the demo". It is server-only and read on every request.
+# DEMO_PASSWORD=
+
+# What the session cookie is signed with. Left unset it is derived from DEMO_PASSWORD, so a session survives a restart
+# either way; set it to sign everyone out when the password changes, or to keep a session across a password change.
+# DEMO_SECRET=

package/payload/AGENTS.md

@@ -1,6 +1,6 @@
 <!-- BEGIN:nextjs-agent-rules -->
 
-# This is NOT the Next.js you know
+## This is NOT the Next.js you know
 
 This version has breaking changes — APIs, conventions, and file structure may all differ from your training data. Read the relevant guide in `node_modules/next/dist/docs/` (resolved from this file's directory; in monorepos the `next` package may not be visible from the repo root) before writing any code. Heed deprecation notices.
 

package/payload/CHANGELOG.md

@@ -2,6 +2,44 @@
 
 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.30.0] · 2026-10-25
+
+### Breaking
+
+- **A direct `.query(` call states its own escape, on the line it is on.** `noDirectQuery` allowed five sites of the template's by absolute line number, and each was wrong the moment a comment above it changed length — this release moved `src/lib/assistant/tools.ts`'s call from 132 to 135 with an unrelated fix. The list is gone: the rule reports every `.query(` call in `app/`, `src/logic/`, `src/views/` and `src/lib/`, and keeps the run passing only where the call's own line carries `// allow-no-direct-query: read() cannot serve this — <why>`, the escape the check prints.
+  - **What a team does.** Run `update`; it reports `migration:direct-query-escape` for each of your files that queries directly. Where the read must be direct — a server action reading the record it is about to change, a streamed export, the sign-in resolving a person before an `AccessScope` exists — put the escape on that line with the reason. Everywhere else read through `read()`, `readAll()` or `aggregate()` from `@/data/read`, which ask the caller's grant.
+  - **Doing nothing.** Your own file that queries directly fails `node scripts/check.ts` on the next `pnpm gate`, in the check's own words, naming the line. Nothing else changes: the rule governs the same four folders it did, and a project with no direct read at all is unaffected.
+- **`src/app.config.ts` gains `description`, the product's one sentence.** The release's `app/layout.tsx` shows `app.description` where it wrote a sentence of the template's own, and that layout is the one a project brings over when it takes the release's pages. The configuration is yours, and an update does not touch it.
+  - **What a team does.** Run `update`; it reports `migration:app-description` for your configuration. Add `description: '<one sentence about your product>',` to the `app` object beside `name`.
+  - **Doing nothing.** A project that keeps its own `app/layout.tsx` sees no failure, and the key costs it nothing. A project that brings the release's layout over fails `pnpm gate` on the type check — `Property 'description' does not exist` — until the key is there.
+
+### New
+
+- **The accent picker is a radio group.** `AccentSwatches` in `@/components/ui/radio-group` is one row of swatches built on the radio primitive: the row is one Tab stop, the arrow keys move the choice, and the chosen swatch is announced as chosen. Settings and the Atlas's card stage both draw it, where three hand-built rows of `role="radio"` buttons each drew their own — every swatch a stop, and an arrow key that did nothing. The appearance menu keeps pressed buttons (`role="group"` with `aria-pressed`), because inside a menu the arrow keys belong to the menu.
+- **`app.description` names the product in a sentence.** It is the line a search engine and a link preview show under the name, and it sits in `src/app.config.ts` beside `name`, `workspace` and `accent` instead of being written into `app/layout.tsx`. Both files are yours, so a project that has already set its own sentence keeps it; `update` reports `migration:app-description` where the configuration has no such key (see **Breaking**).
+- **The README carries the prompt that models a product's data first.** One paragraph to hand the agent before the build sentence: the collections with their key, tenant, hidden, page-only and derived fields; the day and the time zone it is counted in; the money and its currency; each figure with its unit, its window and a definition a stranger could apply to a row; the grants in the `resource:operation` form; the three questions a page must be able to answer; and what an agent may propose against what stays the page's own. It asks for one table the build reads, so a wrong rendering can be told from a wrong model.
+
+### Fixed
+
+- **An approval a guard refused is still yours to send.** A tool call's id was marked used before the change ran, so a change that threw — the grant withdrawn between the approval and the run, a record that no longer fits — wrote nothing and still answered "This change was already applied." to the second try. The id is released when the change throws.
+- **A screen never says a thing was copied before it was.** Four Copy controls on a request's page raised "copied" without waiting for the clipboard, on the page whose whole purpose is handing somebody an exact command or id. One helper awaits the write and says what to do when the browser refuses it.
+- **A page is told the assistant is on only where the route serves it.** `scripts/lib/settle.ts` read every answer but 404 from `/api/assistant` as "on", so a page behind a refused session waited its whole bound for a slot that was never coming.
+- **`brand` refuses a contrast run that measured nothing.** A `scripts/contrast.ts` that crashed printed no summary, and its empty output read as "no failures": the accent shipped unchecked. A hue still failing after the eighth step stops the command too.
+- **The check states the direct read's escape on the call's own line.** `noDirectQuery` allowed five sites by absolute line number, and each was wrong the moment a comment above it changed length. The five state `// allow-no-direct-query: read() cannot serve this — …` where the call is, the escape the check already prints, so the rule no longer has a list to fall behind.
+- **A walk goes on after a route that stops answering.** `scripts/interactions.ts` and `scripts/keyboard.ts` ended the suite at the first page that stopped answering, losing the evidence for every route after it. Each route is walked in a guard of its own, as `scripts/audit.ts` measures each route.
+- **The Atlas reads its entries once per request, not twice.** The walk reads 73 specifications and a request-rendered Atlas page asked for them from the sidebar and again from the article. React's `cache` is the request's scope, so one read serves both and an edited README is still read again on the next request.
+- **An Atlas page whose view tool threw is drawn without the tool's output.** A `Suspense` covers a read that is pending, not one that rejected, so one failing tool took the whole entry page.
+- **`verify` names `--shard` among the options it takes**, and a shard is passed with `--perf` alone: it cannot be combined with `--full` or `--timed`, which `docs/testing.md` now says where it said "beside the other tiers".
+- **The request page asks its reads at once.** The record, the grant behind Replay and the endpoints were three waits in a row; only the customer's address depends on the record.
+- **The tab icon reads the accent the product picks.** `app/icon.ts` took the resolver's default, which is the shipped preset only until a product changes one of the two by hand.
+- **Three routes lose a `Suspense` that wraps nothing**, and the product's one-line description moves into its config (above).
+- **Seven components, each corrected where a reader named the defect.** A copy field's label sat on an element that takes no accessible name; a progress bar with a drawn label was unnamed; a toast raised before `Toaster` mounted was never shown; two incident updates stamped in one millisecond collided; the pager drew for a list that fits its page; two chart memos omitted the geometry they draw with; and a checkbox's and a switch's `className` are documented for the element they style.
+- **Two timers outlived what set them.** The front door's sweep cleared its start timeout and left the interval running, and a host request held its timer for the whole bound after its answer arrived.
+- **The skill's copy of the agent guide is the template's guide again.** It had drifted by four passages — the `data-assistant="omit"` rule, the 409 a thread answers when the session changed hands, the questions a view may offer, and how `pnpm verify --full` walks the assistant — and nothing compared the two. `tests/cli-skill-agents-sync.test.ts` does now, and `update` replaces an unedited copy with this one.
+- **The skill and the docs name the paths the code has.** A prepared query beside a view is `src/logic/<view>-explore.ts` and a view's context file `src/logic/*-context.ts`, both moved in 0.28.0 while the skill still said `src/views/`; `assistantTools` takes `(collections, writer, guard, views?, explore?)`; `brand` is run through the package, not as `node scripts/brand.ts`.
+- **`.env.example` names `DEMO_PASSWORD` and `DEMO_SECRET`**, and `AGENTS.md`'s generated block starts at the level Next writes it, so `next dev` stops re-creating the file as a change.
+- **Three things nothing read are gone**: `scripts/lib/atlas.ts`'s `hasAtlas`, `verify`'s unused `reportSuite` return, and jade's empty `light: {}` token override.
+
 ## [0.29.0] · 2026-10-25
 
 ### New

package/payload/README.md

@@ -118,6 +118,41 @@ call a live API, say so in the sentence: `verify --full` presses every control,
 fake API first. The package (`cli/`, decision 0009) copies files and nothing depends on it afterwards; its commands are
 in `cli/README.md`.
 
+## Model your data before a page is built
+
+A Meridian page is only as good as the model under it: a figure needs a definition, a unit and a window; a table needs a
+key and a grant; an agent needs to know what it may count and what it may only propose. One prompt settles that before
+anything is drawn, and its answer outlives the build — it is the file the next person reads.
+
+Paste this into the same agent, before the build sentence:
+
+> Model my data for Meridian, before any page is built. Read this folder first — a schema, a migration, an OpenAPI file
+> or an existing data layer answers most of this — and ask me only what the folder does not say, in one batch of at most
+> twelve questions. Then write the model into `docs/brief.md` (the file `adopt` and `create` leave for it), answering:
+>
+> 1. **Collections.** Each one's name, its key, the tenant it belongs to, every field with its type, and which of them a
+>    reader may not see, which only a page may write, and which are derived rather than stored. The contract is the one
+>    `src/lib/collection.ts` declares.
+> 2. **The day.** Which field says when a record happened, and what a day means for it — the time zone the product
+>    counts in, so "today" and "the last 7 complete days" mean one thing on every figure.
+> 3. **Money.** Which fields are amounts, in which currency, and whether one row can be in a different currency from the
+>    next.
+> 4. **Figures.** For every figure the dashboard will show: its name, its unit, what it changes against (the window
+>    before, a target, a baseline), and its definition in one sentence a stranger could apply to a row.
+> 5. **Grants.** What each role may read and write, in the `resource:operation` form `src/data/access.ts` asks, and which
+>    collection each grant names. Say what a person with the smallest role still has to see for the product to make
+>    sense — that is what decides which views they get.
+> 6. **Questions.** For each page: the three questions someone on that page would ask that the page's own text does not
+>    answer — what must be countable, groupable or comparable, and over which collections.
+> 7. **Writes.** What an agent may propose on each page, and what stays the page's own — the fields a change must never
+>    set.
+>
+> Where the answer is a choice, give me the two or three options with the figure each produces, and recommend one. End
+> with one table: figure · definition · source · unit · window. The build reads that table, not the prose above it.
+
+Then give the build sentence above. The agent reads the brief first, and every figure on the page it builds is one the
+brief defines — which is also how you tell a wrong rendering from a wrong model.
+
 ## Privacy and feedback
 
 Meridian takes nothing from you. The package, the template and the skill have no telemetry, no analytics and no

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

@@ -4,7 +4,7 @@ import { ExportButton } from '@/components/patterns/export-button';
 import { Freshness } from '@/components/patterns/freshness';
 import { PeriodSelect } from '@/components/patterns/period-select';
 import { HomeBody } from '@/views/home';
-import { PeriodActionsRoom, PeriodRoom } from '@/views/period-actions';
+import { PeriodActionsRoom } from '@/views/period-actions';
 import { gate, gatedMetadata } from '@/data/access';
 import { RefusalScreen } from '@/views/refusal';
 import { DEMO_NOW, DEMO_UPDATED_AT } from '@/data/sample';
@@ -83,7 +83,7 @@ async function Actions({ searchParams }: { searchParams: SearchParams }) {
   const { data } = await readHome(searchParams);
   return (
     <>
-      <Suspense fallback={<PeriodRoom />}><PeriodSelect value={data.period} /></Suspense>
+      <PeriodSelect value={data.period} />
       <ExportButton rows={dayRows(data.series)} filename={`home-${data.period}.csv`} noun="days" />
     </>
   );

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

@@ -9,7 +9,7 @@ import { Freshness } from '@/components/patterns/freshness';
 import { Busy, LeadRoom } from '@/components/patterns/page-loading';
 import { PeriodSelect } from '@/components/patterns/period-select';
 import { parsePeriod } from '@/lib/period';
-import { PeriodActionsRoom, PeriodRoom } from '@/views/period-actions';
+import { PeriodActionsRoom } from '@/views/period-actions';
 import { dayRows } from '@/logic/home-context';
 import { RevenueBody } from '@/views/revenue';
 import { revenueTool } from '@/logic/tools';
@@ -75,7 +75,7 @@ async function Actions({ searchParams }: { searchParams: SearchParams }) {
   const { data } = await readPeriod(period);
   return (
     <>
-      <Suspense fallback={<PeriodRoom />}><PeriodSelect value={period} /></Suspense>
+      <PeriodSelect value={period} />
       <ExportButton rows={dayRows(data.days?.series ?? [])} filename={`revenue-${period}.csv`} noun="days" />
     </>
   );

package/payload/app/(dashboard)/keys/README.md

@@ -32,7 +32,7 @@ The body (rows 1 and 2 and the line on rotating a key under them, under the mast
 
 ## Data
 
-The keys are the `keys` collection (`src/data/collections.ts`), read through `read('keys')` on every request. Create and Revoke are server actions (`actions.ts`) that write the caller's own collection (`collectionFor(scope, 'keys')`), then the view refreshes the route. A rejected create is said inside the sheet; a rejected revoke shows a critical toast and puts the row back. The secret is generated on the server and returned once, to the banner, which is the only place it is ever shown. Its Copy field is marked `data-assistant="omit"`, so a question asked or an Ask pressed while the banner is up sends the page text without it: the assistant reads that a key was created, never its value. The collection stores the key's hint (its prefix and last four characters) and the secret's SHA-256, never the secret, so the table shows the hint and nothing in the browser or the cache can reveal or copy a listed key. To replace a key, create a new one and revoke the old.
+The keys are the `keys` collection (`src/data/collections.ts`), read through `readAll('keys')` on every request. Create and Revoke are server actions (`actions.ts`) that write the caller's own collection (`collectionFor(scope, 'keys')`), then the view refreshes the route. A rejected create is said inside the sheet; a rejected revoke shows a critical toast and puts the row back. The secret is generated on the server and returned once, to the banner, which is the only place it is ever shown. Its Copy field is marked `data-assistant="omit"`, so a question asked or an Ask pressed while the banner is up sends the page text without it: the assistant reads that a key was created, never its value. The collection stores the key's hint (its prefix and last four characters) and the secret's SHA-256, never the secret, so the table shows the hint and nothing in the browser or the cache can reveal or copy a listed key. To replace a key, create a new one and revoke the old.
 
 ## Embed view
 

package/payload/app/(dashboard)/members/README.md

@@ -35,7 +35,7 @@ The body (rows 1 and 2) is the records template, `Records` from `src/components/
 
 ## Data
 
-The `members` collection in `src/data/collections.ts`, read through `read('members')` at request time, so the person's grant is asked on the path every page reads by. Server actions in `actions.ts` call `members.create` (status `Invited`, joined today by the data's clock, never active), `members.update` (status), `members.remove` and `assignRole`; the view refreshes the page after each and keeps no copy of the rows. Last active is relative to the data's clock.
+The `members` collection in `src/data/collections.ts`, read through `readAll('members', { sort: { field: 'joined', dir: 'desc' } })` at request time, so the person's grant is asked on the path every page reads by. Server actions in `actions.ts` call `members.create` (status `Invited`, joined today by the data's clock, never active), `members.update` (status), `members.remove` and `assignRole`; the view refreshes the page after each and keeps no copy of the rows. Last active is relative to the data's clock.
 
 Every one of those writes passes `src/data/member-mutations.ts`, which re-resolves the caller, checks the operation's grant and refuses a change or removal of an Owner without `workspace:update`, one's own role or add-ons, suspending or removing oneself, and any change that would leave no active Owner. The page reads that boundary per row, once, and is handed only what it allows: `memberAccess(id)` gives the row's booleans, its role choices, its add-on choices and its reason, and `invitableRoles()` gives the roles an invitation may carry. The page decides nothing from a role of its own. A role or add-on change is one `assignRole` write, with its Activity line in the same step; the matrix in row 2 asks `whoCan` over the same `GRANTS` the boundary uses.
 

package/payload/app/(dashboard)/members/actions.ts

@@ -2,16 +2,18 @@
 
 import { clock } from '@/data/collections';
 import { can, collectionFor, resolveAccess, Unauthenticated } from '@/data/access';
-import { assignMemberRole, REFUSALS } from '@/data/member-mutations';
+import { assignMemberRole, MemberRefusal, REFUSALS } from '@/data/member-mutations';
 import type { AnyCollection } from '@/lib/collection';
 import { dayOf } from '@/lib/format-date';
 import type { Result } from '@/views/members';
 import { STATUSES, TEAMS, type Member } from '@/data/sample';
 import { MAIN_ROLES, type AddOn, type MainRole } from '@/data/roles';
 
+// A refusal the boundary wrote for the person is shown as it is; anything else that threw — a collection that rejected a
+// shape, a connection that dropped — is not theirs to read, and says only that it did not go through.
 const fail = (e: unknown): Result => ({
   ok: false,
-  error: e instanceof Unauthenticated ? REFUSALS.signIn : e instanceof Error ? e.message : 'The change did not go through.',
+  error: e instanceof Unauthenticated ? REFUSALS.signIn : e instanceof MemberRefusal && e.message ? e.message : 'The change did not go through.',
 });
 
 /**

package/payload/app/(dashboard)/requests/[id]/actions.ts

@@ -20,7 +20,7 @@ export async function replayRequest(id: string): Promise<ReplayResult> {
     const scope = await resolveAccess();
     if (!(await can(scope, 'requests', 'create'))) return { ok: false, error: 'You do not have permission to replay requests.' };
     const requests = collectionFor(scope, 'requests');
-    const original = (await requests.query({ where: [{ field: 'id', op: 'eq', value: id }] })).rows[0] as RequestRow | undefined; // read() cannot serve this: a server action reads the record it is about to change, uncached
+    const original = (await requests.query({ where: [{ field: 'id', op: 'eq', value: id }] })).rows[0] as RequestRow | undefined; // allow-no-direct-query: read() cannot serve this — a server action reads the record it is about to change, uncached
     if (!original) return { ok: false, error: `No request with id ${id}.` };
     const status = original.method === 'POST' ? 201 : 200;
     const replay = await requests.create!({
@@ -31,6 +31,8 @@ export async function replayRequest(id: string): Promise<ReplayResult> {
     updateTag(collectionTag(scope.tenantId, 'requests'));
     return { ok: true, id: String(replay.id), status };
   } catch (e) {
-    return { ok: false, error: e instanceof Unauthenticated ? 'Sign in again to replay this request.' : e instanceof Error ? e.message : 'The request was not replayed.' };
+    // Only the answer written for the person: a collection that rejected the record says why in its own words, which are
+    // not theirs to read, so anything but the missing session is a sentence this action chose.
+    return { ok: false, error: e instanceof Unauthenticated ? 'Sign in again to replay this request.' : 'The request was not replayed.' };
   }
 }

package/payload/app/(dashboard)/requests/[id]/page.tsx

@@ -52,13 +52,15 @@ export default async function RequestPage({ params }: { params: Promise<{ id: st
   const { id } = await params;
   const denied = await gate('request');
   if (denied) return RefusalScreen(denied);
-  const { request: r, observedAt } = await byId(id);
-  // Rendered here rather than thrown, so the screen is in the first HTML (see MissingPage).
-  if (!r) return <MissingPage />;
+  // Everything the page needs that does not depend on the record is asked beside it, in one wait: the record, the
+  // grant behind Replay and the endpoints that give the route its p95 were three waits in a row before.
+  //
   // After the gate: what this person may do with the record, so Replay is drawn only where it may be used. A Viewer
   // holds `requests:read` without `requests:create`, so it is withheld for them and nothing is drawn in its place.
-  const mayReplay = await may(ACTIONS['replay-request'].needs);
-  const [endpoints, customerHref] = await Promise.all([readEndpoints(), customerPage(r.customer)]);
+  const [{ request: r, observedAt }, mayReplay, endpoints] = await Promise.all([byId(id), may(ACTIONS['replay-request'].needs), readEndpoints()]);
+  // Rendered here rather than thrown, so the screen is in the first HTML (see MissingPage).
+  if (!r) return <MissingPage />;
+  const customerHref = await customerPage(r.customer);
   const route = endpoints.find((e) => e.method === r.method && e.route === r.route);
   return <RequestView request={r} trace={traceOf(r)} payloads={payloadsOf(r)} routeP95={route?.p95 ?? null} now={observedAt} mayReplay={mayReplay} replay={replayRequest} customerHref={customerHref} />;
 }

package/payload/app/(dashboard)/settings/actions.ts

@@ -9,11 +9,13 @@ import type { Result } from '@/views/members';
 /** The name a Settings save carries; the address is not editable here. */
 export type WorkspaceInput = { name: string };
 
+// The refusals this action chose are shown as they are; a write that threw anything else — a collection rejecting a
+// shape, a connection dropping — is not the person's to read, and says only that it did not go through.
 const fail = (e: unknown): Result => ({
   ok: false,
   error: e instanceof Unauthenticated ? 'Sign in again to make this change.'
     : e instanceof AccessDenied ? 'You do not have permission to make this change.'
-    : e instanceof Error ? e.message : 'The change did not go through.',
+    : 'The change did not go through.',
 });
 
 /**

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

@@ -29,15 +29,17 @@ async function workspaceMay(): Promise<SettingsMay> {
 /**
  * The workspace record, through `read()` like every other collection, so the `workspace:*` grants the role table freezes
  * are asked on the one path. It is read only for someone who may read it, and a policy that does not bind the collection
- * leaves the form on its own defaults rather than failing the page: Settings renders for everyone.
+ * leaves the form on its own defaults rather than failing the page: Settings renders for everyone. A read that *threw*
+ * is a different answer from a collection that holds no row, and says so, so the form is never handed the template's
+ * name where the workspace's could not be read.
  */
-async function workspaceRecord(): Promise<WorkspaceValues | null> {
+async function workspaceRecord(): Promise<{ values: WorkspaceValues | null; unreadable: boolean }> {
   try {
     const { rows } = await read('workspace');
     const row = rows[0];
-    return row ? { name: String(row.name), slug: String(row.slug) } : null;
+    return { values: row ? { name: String(row.name), slug: String(row.slug) } : null, unreadable: false };
   } catch {
-    return null;
+    return { values: null, unreadable: true };
   }
 }
 
@@ -49,7 +51,7 @@ export default async function SettingsPage() {
   // The flags are computed here, on the server, because the view is a client module and never asks the policy itself;
   // the workspace record and the action that saves it are handed over together, so the section edits what the page read.
   const permissions = await workspaceMay();
-  const workspace = permissions.workspaceRead ? await workspaceRecord() : null;
+  const workspace = permissions.workspaceRead ? await workspaceRecord() : { values: null, unreadable: false };
   return (
     <PageFrame
       width="form"
@@ -57,7 +59,7 @@ export default async function SettingsPage() {
       title="Settings"
       description={`The workspace, how ${app.name} looks, and what assistants may do.`}
     >
-      <SettingsBody may={permissions} workspace={workspace} save={saveWorkspace} />
+      <SettingsBody may={permissions} workspace={workspace.values} unreadable={workspace.unreadable} save={saveWorkspace} />
     </PageFrame>
   );
 }

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

@@ -9,7 +9,7 @@ import { Freshness } from '@/components/patterns/freshness';
 import { Busy, LeadRoom } from '@/components/patterns/page-loading';
 import { PeriodSelect } from '@/components/patterns/period-select';
 import { parsePeriod } from '@/lib/period';
-import { PeriodActionsRoom, PeriodRoom } from '@/views/period-actions';
+import { PeriodActionsRoom } from '@/views/period-actions';
 import { dayRows } from '@/logic/home-context';
 import { UsageBody } from '@/views/usage';
 import { usageTool } from '@/logic/tools';
@@ -82,7 +82,7 @@ async function Actions({ searchParams }: { searchParams: SearchParams }) {
   const { data } = await readPeriod(period, day);
   return (
     <>
-      <Suspense fallback={<PeriodRoom />}><PeriodSelect value={period} /></Suspense>
+      <PeriodSelect value={period} />
       <ExportButton rows={dayRows(data.days?.series ?? [])} filename={`usage-${period}.csv`} noun="days" />
     </>
   );

package/payload/app/api/export/requests/route.ts

@@ -35,12 +35,19 @@ export async function GET(request: Request): Promise<Response> {
         return;
       }
       try {
-        const batch = await collection.query({ where: query.where, sort: query.sort, limit: BATCH, offset }); // read() cannot serve this: a streamed export must not be cached
+        const batch = await collection.query({ where: query.where, sort: query.sort, limit: BATCH, offset }); // allow-no-direct-query: read() cannot serve this — a streamed export must not be cached
         total = batch.total;
-        const lines = batch.rows.map((r) => csvRow(COLUMNS, line(r)));
         const head = offset === 0 ? csvHeader(COLUMNS) + '\r\n' : '';
-        offset += BATCH;
-        controller.enqueue(encoder.encode(head + lines.map((l) => l + '\r\n').join('')));
+        const lines = batch.rows.map((r) => csvRow(COLUMNS, line(r)));
+        // How far the stream has come is what the collection answered, not what it was asked for: a collection that
+        // answers fewer rows than the batch asked for would otherwise leave a gap between the last row written and the
+        // next one read, and the export would silently miss them.
+        offset += batch.rows.length;
+        if (head) controller.enqueue(encoder.encode(head));
+        if (lines.length) controller.enqueue(encoder.encode(lines.map((l) => l + '\r\n').join('')));
+        // Nothing back means the export is over, whatever the total says, so a collection that counts rows it will not
+        // return cannot ask the stream for the same batch forever.
+        if (!lines.length && !cancelled) controller.close();
       } catch (e) {
         controller.error(e);
       }