zz-meridian 0.9.0 → 0.10.0

package/dist/imports.js

@@ -0,0 +1,32 @@
+/**
+ * Import specifiers in a common form, so two copies of a module that differ only in how they name the same modules
+ * (`'../../ui/badge/index'` beside `'@/components/ui/badge'`) compare equal. `update` uses it to tell a file the team
+ * only re-styled from one it changed (issue #16). Pure: the caller passes the aliases it read.
+ */
+import path from 'node:path';
+/** The project's `@/*`-style aliases from its tsconfig's `paths` (best effort; a file it cannot read gives none). */
+export function aliasesOf(tsconfig) {
+    const out = new Map([['@meridian/', 'src/']]);
+    if (!tsconfig)
+        return out;
+    // `"@/*": ["./src/*"]` maps `@/` to `src/`; `"@/*": ["./*"]` maps it to the project root.
+    for (const m of tsconfig.matchAll(/"(@[\w-]*)\/\*"\s*:\s*\[\s*"([^"*]*)\*"/g))
+        out.set(`${m[1]}/`, m[2].replace(/^\.\//, ''));
+    return out;
+}
+/** `text` with every literal module specifier rewritten as the project path it names, extension and `/index` dropped. */
+export function canonicalImports(rel, text, aliases) {
+    const canonical = (spec) => {
+        let to = null;
+        if (spec.startsWith('.'))
+            to = path.posix.normalize(path.posix.join(path.posix.dirname(rel), spec));
+        else
+            for (const [alias, dir] of aliases)
+                if (spec.startsWith(alias)) {
+                    to = path.posix.normalize(dir + spec.slice(alias.length));
+                    break;
+                }
+        return to === null ? spec : to.replace(/\.(tsx?|jsx?|mjs)$/, '').replace(/\/index$/, '');
+    };
+    return text.replace(/(\bfrom\s*|\bimport\s*\(\s*|\bimport\s+)(['"])([^'"\n]+)\2/g, (_m, lead, q, spec) => `${lead}${q}${canonical(spec)}${q}`);
+}

package/dist/migrations.js

@@ -213,6 +213,23 @@ export const RELEASE_MIGRATIONS = [
         instructions: 'Read "Legible" in references/agents.md and "A shared context" in references/customize.md. Build the view\'s context with the fields of `SharedContext` from `src/lib/shared-context.ts` (scope, freshness, each figure with its unit, change and definition, what code finds, what the data cannot say) in a pure function beside the view, and pass it alone: `useShareView(context)`. Both agents read it: an MCP host and the console\'s assistant.',
         checks: GATE_AND_BUILD,
     },
+    {
+        id: 'assistant-view-tools',
+        since: '0.10.0',
+        applies: (root) => {
+            const route = text(root, 'app/api/assistant/route.ts');
+            const tools = text(root, 'src/lib/assistant/tools.ts');
+            const respond = text(root, 'src/lib/assistant/respond.ts');
+            if (route === null || tools === null || respond === null)
+                return null;
+            // The 0.9.0 assistant takes the views and tells the model its limits; one kept from before does neither.
+            const stale = [...(/\bViewTool\b/.test(tools) ? [] : ['src/lib/assistant/tools.ts']), ...(/\blimitsOf\b/.test(respond) ? [] : ['src/lib/assistant/respond.ts']), ...(/\bviews\s*:/.test(route) ? [] : ['app/api/assistant/route.ts'])];
+            return stale.length > 0 ? stale : null;
+        },
+        summary: "The assistant's route-side code predates view tools and its limits.",
+        instructions: 'Read "Adding an MCP server later" in example:docs/assistant.md. Bring `src/lib/assistant/tools.ts` and `src/lib/assistant/respond.ts` over from the release: `assistantTools(collections, writer, guard, views)` offers every view in `src/views/tools.ts` as a read-only `view_<name>` tool, `respond` lists what the assistant cannot do or see (`limitsOf`) and passes the views on, and the guard may take a `record`. Then pass `views` from the assistant route to `respond`: the template\'s `viewTools`, an adopted project\'s own view tools (`ViewTool` in `src/lib/shared-context.ts`), or none.',
+        checks: GATE_AND_BUILD,
+    },
     {
         id: 'agent-reads-section',
         since: '0.9.0',

package/dist/session.js

@@ -8,6 +8,7 @@ import fs from 'node:fs';
 import path from 'node:path';
 import { managedBlock } from './context.js';
 import { inside, packageManager, run as spawn, sha256 } from './files.js';
+import { aliasesOf, canonicalImports } from './imports.js';
 import { changedPaths, takeInventory } from './inventory.js';
 import { renderMergeReport } from './merge-report.js';
 import { releaseMigrations } from './migrations.js';
@@ -145,6 +146,7 @@ function plan(ctx, manifest, startedAt) {
         if (!isSafePath(p) || FORBIDDEN.test(p))
             throw new Refusal(`unsafe path ${JSON.stringify(p)}; nothing was written`);
     const sourcePayload = new Set(source.payload);
+    const aliases = aliasesOf(readText(root, 'tsconfig.json'));
     const operations = [];
     const retired = [];
     const targetFiles = {};
@@ -159,7 +161,16 @@ function plan(ctx, manifest, startedAt) {
         const disk = probe(root, p);
         if (disk.unsafe && (managed || keptReason.has(p)))
             throw new Refusal(`${p} is a symbolic link or not a regular file; nothing was written`);
-        const { disposition, action } = classify({ recorded: recorded, target: targetHash, disk: disk.side.hash, managed, kept: keptReason.has(p) });
+        // A managed module the team only re-styled (its imports named another way, nothing else changed) is untouched: the
+        // release's copy replaces it instead of staging a merge nobody needs (issue #16).
+        let diskHash = disk.side.hash;
+        if (managed && recorded && diskHash && diskHash !== recorded && /\.(?:tsx?|jsx?|mjs)$/.test(p) && fs.existsSync(inside(source.tree, p))) {
+            const ours = readText(root, p);
+            const base = fs.readFileSync(inside(source.tree, p), 'utf8');
+            if (ours !== null && canonicalImports(p, ours, aliases) === canonicalImports(p, base, aliases))
+                diskHash = recorded;
+        }
+        const { disposition, action } = classify({ recorded: recorded, target: targetHash, disk: diskHash, managed, kept: keptReason.has(p) });
         operations.push({ path: p, disposition, action, base: sideOf(recorded), ours: disk.side, target: sideOf(targetHash), applied: false, appliedHash: null });
         if (disposition === 'retired-kept')
             retired.push({ path: p, baselineHash: recorded, reason: keptReason.get(p) });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "zz-meridian",
-  "version": "0.9.0",
+  "version": "0.10.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/CHANGELOG.md

@@ -2,6 +2,34 @@
 
 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.10.0] · 2026-10-07
+
+### Added
+
+- **`audit --atlas`.** The browser audit over the Design Atlas: every card's page and its bare preview, at 1440 and 390px in both themes, about ten minutes. Not part of `pnpm verify`, which stays fast (issue #9).
+- **`ShareContext`.** `useShareView` as a component that renders nothing, for a server page with no client view (issue #17).
+- **A database guide.** `references/existing-project.md` covers a pool that survives a dropped connection, a transaction pooler, schema changes on start, and a role that cannot create (issues #16, #17).
+- **`assistant-view-tools` migration.** `update` reports an assistant whose route-side code predates view tools and its limits (issue #17).
+
+### Changed
+
+- **Export is offered on a phone.** The Overview's and Analytics' Export were hidden below 640px; a page's actions are offered on every width (issue #13).
+- **`update` sees past import style.** A managed module whose only difference from its release copy is how its imports are written (`@/…` for `../../…`) is untouched, not a merge (issue #16).
+- **A specimen is not the page.** The audit keeps a card preview's own headings and scroll regions out of the page's outline and its one scroller (issue #8).
+- **A control's role needs its keys.** `scripts/check.ts` fails an element that claims a control's role (`button`, `tab`, `switch` and the rest) with no `onKeyDown` (issue #11).
+
+### Fixed
+
+- **A narrow table becomes cards on any screen.** `DataTable`'s card list follows the table's own width (under 640px), as `hideBelow` does, so a table in a half-width row or beside the assistant's column no longer runs past its frame. Found by the first `audit --atlas`, with the two below.
+- **An active filter's label reads.** A filter that is on keeps its name in `ink-2` on the accent tint; `ink-3` fell to 4.04:1 in light.
+- **A selected row's facts read on a phone.** On the accent wash, a card's facts step up to `ink-2`; `ink-3` fell to 4.43:1 in light.
+- **The presses count a file chooser.** A file picker's button opens the system's chooser, which changes nothing in the DOM; the presses now intercept it and count it as an answer (issue #16).
+- **verify's assistant-off run ignores `.env.local`.** It blanks every name the assistant reads, set in the shell or not (issue #16).
+
+### Breaking
+
+- **`Timeline` is removed.** No page used it, and a card exists because a page needs it (`CONTRIBUTING.md`). Import nothing from `src/components/charts/timeline`.
+
 ## [0.9.0] · 2026-10-07
 
 ### Added

package/payload/CONTRIBUTING.md

@@ -85,9 +85,10 @@ Write the status on the line under the title: `Status: beta`.
 | `pnpm tokens` | Generates the token CSS and the Tailwind bridge from `tokens/` (`--check` only compares) | After any token change |
 | `node scripts/contrast.ts [--all]` | Every specified foreground on its background, in every theme and accent, and the chart palette's colour-vision checks | Gate |
 | `node scripts/registry.ts` | Regenerates the Atlas registry from the card folders (`--check` only compares) | After adding or renaming a card |
-| `node scripts/check.ts` | Every card has its README and preview, every README follows the anatomy, no literal colour in components, every token a spec names exists and is written with its own value, and every embed view a document offers is a route | Gate |
+| `node scripts/check.ts` | Every card has its README and preview, every README follows the anatomy, no literal colour in components, every token a spec names exists and is written with its own value, every embed view a document offers is a route, and an element that claims a control's role has a key handler | Gate |
 | `pnpm typecheck`, `pnpm test` | TypeScript and the behaviour tests | Gate |
 | `node scripts/audit.ts` | With the app running: every page and embed view at 2560, 1440, 1024, 768 and 390px in both themes (embeds at 720 and 420 on a simulated host ground). Fails on sideways scroll, text clipped without an ellipsis, a control with no accessible name, more than one page scroller, rendered text under its WCAG minimum, a Tab stop with no visible focus ring (it presses Tab through the page), and any uncaught exception or console error. Prints the design metrics: type sizes, weights, radii and the hierarchy ratio | Before release |
+| `node scripts/audit.ts --atlas` | With the app running: the same audit over the Design Atlas, every card's page and its bare preview, at 1440 and 390px in both themes, about ten minutes. Not part of `pnpm verify`, which stays fast: a card's preview is where a defect in its own box shows, so run it after changing a component | After changing a component |
 | `node scripts/interactions.ts` | With the app running: presses every control on every page (mouse at 1440px, taps at 390px) and follows every link. Fails on a control that changes nothing, one something covers, and a link that answers 4xx | Before release |
 | `pnpm verify` | The gate once, one production build, the route policy, the size checks and a smoke of up to three routes on desktop and the phone drawer; ends with a coverage line, and the report is in `out/verify.txt` | Before finishing any change |
 | `pnpm verify --full` | The navigation of every rail route, then every exhaustive suite: the audit, every control pressed and link followed, the keyboard walk, the assistant, the live data and Web Vitals | After a change to shared components, the shell or data, and before release |

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

@@ -17,7 +17,7 @@ Status: beta
 
 Everything in rows 1 and 2 shares one Meridian: point at a day in either chart and the featured figure, the tiles and both charts read that day.
 
-Below 1024px every row stacks: the featured card first, then the tiles (two across from 34rem, one below), then the cards. At 390px the masthead's actions wrap under the title and the period select stays visible; Export is not offered on a phone (`max-sm:hidden`), and the command palette carries destinations and appearance, not the page's actions.
+Below 1024px every row stacks: the featured card first, then the tiles (two across from 34rem, one below), then the cards. At 390px the masthead's actions wrap under the title: the period select, then Export. A page's actions are offered on every width, as the request log's export is: a person on a phone may want the CSV too (issue #13).
 
 ## States
 

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

@@ -47,7 +47,7 @@ async function Actions({ searchParams }: { searchParams: SearchParams }) {
   return (
     <>
       <Suspense><PeriodSelect value={period} /></Suspense>
-      <ExportButton rows={data.series} filename={`overview-${period}.csv`} noun="days" className="max-sm:hidden" />
+      <ExportButton rows={data.series} filename={`overview-${period}.csv`} noun="days" />
     </>
   );
 }

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

@@ -47,7 +47,7 @@ async function Actions({ searchParams }: { searchParams: SearchParams }) {
   return (
     <>
       <Suspense><PeriodSelect value={period} /></Suspense>
-      <ExportButton rows={data.series} filename={`analytics-${period}.csv`} noun="days" className="max-sm:hidden" />
+      <ExportButton rows={data.series} filename={`analytics-${period}.csv`} noun="days" />
     </>
   );
 }

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

@@ -10,7 +10,7 @@ Status: beta
 |---|---|---|---|
 | Masthead | PageFrame: kicker "ZZ Meridian · Production", title "Requests", one sentence, Freshness, Export CSV | One band | Title, sentence, then Freshness and Export on their own row |
 | 1 | Row `tiles`: three Metric tiles for what the filters let through: requests (emphasis), errors and limits, latency p95, each with its 5-minute shape over the last hour and the last half hour against the one before | Three across | One column |
-| 2 | Data table with a Filter bar in its toolbar: search, Status, Method, Region, the result count | Columns: Request (grow), Status, Latency, Customer (from 768px), Region (from 1024px), Size (from 1280px), Received | Card list: route and status, then latency, customer and when |
+| 2 | Data table with a Filter bar in its toolbar: search, Status, Method, Region, the result count | Columns: Request (grow), Status, Latency, Customer and Region (once the table is 896px wide), Size (1152px), Received; a table under 640px wide is the card list | Card list: route and status, then latency, customer and when |
 
 ## States
 

package/payload/app/embed/health/view.tsx

@@ -7,7 +7,9 @@ import { EmbedFrame } from '@/components/patterns/embed-frame';
 import { Freshness } from '@/components/patterns/freshness';
 import { AskAbout } from '@/components/patterns/ask-about';
 import { StatusList } from '@/components/patterns/status-list';
-import { HealthBody, ShareHealth } from '@/views/health';
+import { ShareContext } from '@/components/base/use-share-view';
+import { HealthBody } from '@/views/health';
+import { healthContext } from '@/views/health-context';
 import { formatRelative } from '@/lib/format-date';
 import type { Incident } from '@/components/patterns/incident-card';
 import type { Service } from '@/components/patterns/status-list';
@@ -22,7 +24,7 @@ export function EmbedHealth(p: Props) {
         <HealthBody {...p} />
       ) : (
         <div className="flex flex-col gap-3">
-          <ShareHealth data={p} />
+          <ShareContext context={healthContext(p)} />
           {p.current ? (
             <Banner
               tone="warning"

package/payload/app/system/preview/[section]/[card]/keys.ts

@@ -70,7 +70,6 @@ export const PREVIEW_KEYS: string[] = [
   'patterns/heatmap',
   'patterns/meridian',
   'patterns/sparkline',
-  'patterns/timeline',
   'patterns/trend-chart',
   'patterns/uptime-bars',
 ];

package/payload/app/system/preview/[section]/[card]/stage.tsx

@@ -17,7 +17,7 @@ function Inner({ id }: { id: string }) {
       data-density={q.get('density') ?? undefined}
       className="min-h-dvh bg-ground p-8 text-ink max-sm:p-4"
     >
-      <div className="mx-auto max-w-5xl"><Suspense><P /></Suspense></div>
+      <div data-specimen className="mx-auto max-w-5xl"><Suspense><P /></Suspense></div>
     </div>
   );
 }

package/payload/docs/surfaces.md

@@ -25,7 +25,7 @@ Below 1024px the rail becomes a drawer (the same node, so nothing is defined twi
 | Navigation | Rail | Drawer from the masthead's menu button; closes on Escape, on the scrim and on navigation | AppShell |
 | Masthead | Title, head-note, actions on one band | Title row with the menu button; head-note under it; actions wrap to their own row, the primary last | PageFrame |
 | Metric tiles | Four across | Two across from 34rem of row width, one below | Row `tiles` |
-| Tables | Columns, sortable heads | A list of cards, one per row: the primary column as the title, two or three facts under it, the status at the end; low-value columns drop first (`hideBelow`) | DataTable |
+| Tables | Columns, sortable heads | A list of cards, one per row: the primary column as the title, two or three facts under it, the status at the end; low-value columns drop first (`hideBelow`). Both read the table's own width, so a table in a narrow frame on a wide screen becomes cards too | DataTable |
 | Dialogs | Centred, 520px | A bottom sheet, full width, safe-area padding | Dialog |
 | Menus and selects | Popover | Popover, at least 44px rows on touch | Menu, Select |
 | Charts | Full height, 6 to 8 date labels | Shorter (180px), 3 to 4 date labels; the Meridian follows the finger and the tooltip pins to the top edge | TrendChart |

package/payload/package.json

@@ -1,6 +1,6 @@
 {
   "name": "zz-meridian-template",
-  "version": "0.9.0",
+  "version": "0.10.0",
   "private": true,
   "license": "MIT",
   "description": "ZZ Meridian: a dashboard design system and starter. DTCG tokens, five layers of React components and a Design Atlas, in a light and a dark theme.",

package/payload/scripts/audit.ts

@@ -1,16 +1,22 @@
 /**
  * The browser audit: every page and embed view, at every width, in both themes, measured.
  *
- *   node scripts/audit.ts [--base http://localhost:3100] [--routes /,/requests] [--embeds-only]
+ *   node scripts/audit.ts [--base http://localhost:3100] [--routes /,/requests] [--embeds-only] [--atlas]
  *
  * Routes are discovered from app/ (every static page; embeds under /embed), with the detail pages in
  * scripts/verify.config.ts beside them; --routes replaces the pages for one run.
  *
+ * --atlas audits the Design Atlas instead: every card's page and its bare preview, at 1440 and 390px in both themes.
+ * A card's preview is the one place it is drawn alone, so a defect in its own box shows there and nowhere else. It is
+ * not part of `pnpm verify` (the default stays fast); run it when the question is the component surface. It takes
+ * about ten minutes, and a project without the Atlas has nothing for it to read.
+ *
  * Fails (exit 1) on: sideways scroll, text clipped without an ellipsis, a control with no accessible name, more than
  * one page scroller, and rendered text under its WCAG minimum. 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.
  */
+import fs from 'node:fs';
 import { launch } from './lib/chrome.ts';
 import { discover } from './lib/routes.ts';
 import config from './verify.config.ts';
@@ -19,13 +25,22 @@ const args = process.argv.slice(2);
 const opt = (k: string, d: string) => { const i = args.indexOf(k); return i >= 0 ? args[i + 1] : d; };
 const base = opt('--base', process.env.BASE ?? 'http://localhost:3100');
 const EMBEDS_ONLY = args.includes('--embeds-only');
+const ATLAS = args.includes('--atlas');
+
+/** Every card's Atlas page and bare preview, from the keys scripts/registry.ts generates; only the template has them. */
+function atlasRoutes(): string[] {
+  const file = '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]);
+  return keys.flatMap((k) => [`/system/${k}`, `/system/preview/${k}`]);
+}
 
 const found = discover();
 // verify.config.ts is the team's, so read the one field this needs through its own type.
 const detailRoutes = (config as { detailRoutes?: string[] }).detailRoutes ?? [];
-const ROUTES = EMBEDS_ONLY ? [] : (opt('--routes', '') ? opt('--routes', '').split(',') : [...found.filter((r) => !r.startsWith('/embed')), ...detailRoutes]);
-const EMBEDS = found.filter((r) => r.startsWith('/embed/'));
-const WIDTHS = [2560, 1440, 1024, 768, 390];
+const ROUTES = EMBEDS_ONLY ? [] : ATLAS ? atlasRoutes() : (opt('--routes', '') ? opt('--routes', '').split(',') : [...found.filter((r) => !r.startsWith('/embed')), ...detailRoutes]);
+const EMBEDS = ATLAS ? [] : found.filter((r) => r.startsWith('/embed/'));
+const WIDTHS = ATLAS ? [1440, 390] : [2560, 1440, 1024, 768, 390];
 const THEMES = ['dark', 'light'];
 
 type Report = {
@@ -89,7 +104,8 @@ const MEASURE = `(() => {
     }
     const rad = parseFloat(c.borderTopLeftRadius);
     if (rad > 0 && rad < 999) out.radii.push(Math.round(rad));
-    if (/(auto|scroll)/.test(c.overflowY) && el.scrollHeight > el.clientHeight + 1 && el.clientHeight > 120) out.scrollers.push(label(el));
+    // 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 && !el.closest('[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') || el.textContent.trim() || el.querySelector('img[alt]')?.getAttribute('alt') || (el.id && document.querySelector('label[for="' + el.id + '"]')?.textContent.trim()) || el.closest('label')?.textContent.trim() || el.getAttribute('placeholder') || '';
       if (!name) out.unnamed.push(label(el));
@@ -109,7 +125,8 @@ const MEASURE = `(() => {
     }
   }
   // Headings descend one level at a time, so a screen reader's outline has no holes.
-  const levels = [...document.querySelectorAll('h1,h2,h3,h4,h5,h6')].filter((h) => !h.closest('[aria-hidden="true"]')).map((h) => +h.tagName[1]);
+  // A specimen's headings are the card's own, at the level the card uses where it is placed, not the documentation page's.
+  const levels = [...document.querySelectorAll('h1,h2,h3,h4,h5,h6')].filter((h) => !h.closest('[aria-hidden="true"]') && !h.closest('[data-specimen]')).map((h) => +h.tagName[1]);
   levels.forEach((l, i) => { if (i && l > levels[i - 1] + 1) out.headings.push('h' + levels[i - 1] + ' then h' + l); });
   out.focusless = [];
   const sorted = texts.sort((a, b) => a - b);

package/payload/scripts/check.ts

@@ -229,6 +229,24 @@ if (fs.existsSync(path.join(ROOT, COLLECTIONS))) {
   for (const f of LAYERS) if (/\brehype-?raw\b/i.test(code(read(f)))) problems.push(`${f}: reaches for rehype-raw; render markdown with Prose, where raw HTML stays text`);
 }
 
+// ── A control a keyboard can use ─────────────────────────────────────────────────────────────────────
+// A native button, link or field answers Enter and Space by itself, and Radix's primitives carry their own keys. An
+// element that only claims a control's role does not: it needs its own key handler, or a keyboard user can reach it,
+// see its ring and still not use it, past every browser check (issue #11). An option is left out: its listbox's owner,
+// the combobox that holds focus, moves through the options and picks one (aria-activedescendant).
+{
+  const ROLES = /\brole=["'](button|link|menuitem|menuitemcheckbox|menuitemradio|tab|checkbox|switch|radio)["']/;
+  const NATIVE = new Set(['button', 'a', 'input', 'select', 'textarea', 'summary']);
+  for (const f of [APP_DIR, 'src'].flatMap((d) => walk(d, /\.tsx$/))) {
+    const src = read(f);
+    for (const m of src.matchAll(/<([a-z][a-z0-9]*)\b((?:=>|[^>])*)>/g)) {
+      const [, tag, attrs] = m;
+      const role = ROLES.exec(attrs)?.[1];
+      if (role && !NATIVE.has(tag) && !/\bonKeyDown\s*=/.test(attrs)) problems.push(`${f}: <${tag} role="${role}"> has no onKeyDown; use a <button>, or handle Enter and Space`);
+    }
+  }
+}
+
 // ── The update session, the keep register and the logo ────────────────────────────────────────────────
 // A session under .meridian/update/ must be resolved before the gate passes. With one ready, its candidate manifest
 // stands in for the original: the files it will own are what keep, retirements and the dormant-code sweep read.

package/payload/scripts/interactions.ts

@@ -88,9 +88,12 @@ for (const width of WIDTHS) {
       if (!armed) continue;
       if (armed.covered) { failures.push(`${route} @${width}: "${controls[i]}" is covered by ${armed.covered}`); continue; }
       await sleep(100);
+      const choosers = page.fileChoosers();
       await press(page, armed.x, armed.y, touch);
       await sleep(600);
       pressed++;
+      // A file picker answers by opening the system's file chooser, which changes nothing on the page (issue #16).
+      if (page.fileChoosers() > choosers) continue;
       const tip = touch || /^About /.test(controls[i]);
       const r = await page.eval<{ changes: number; moved: boolean }>(`({ changes: window.__changes + (${tip} ? document.querySelectorAll('[role=tooltip]').length : 0), moved: location.href !== window.__href })`);
       if (!r.changes && !r.moved) failures.push(`${route} @${width}: "${controls[i]}" does nothing when ${touch ? 'tapped' : 'pressed'}`);

package/payload/scripts/keyboard.ts

@@ -8,9 +8,11 @@
  * something else such as the sticky top bar (WCAG 2.4.11), or when a visible control is never reached at all.
  * The audit (scripts/audit.ts) checks the first eighteen stops of every page at every width; this walks all of them.
  *
- * KNOWN GAP: this proves every control is REACHABLE and ringed; it never ACTIVATES one with the keyboard. A control
- * that answers a click but not Enter or Space passes both this and scripts/interactions.ts (which presses with the
- * mouse and with touch). The gap is deliberate until a check can be trusted not to cry wolf: what a key should do
+ * This proves every control is REACHABLE and ringed; it never ACTIVATES one with the keyboard. The activation is held
+ * where it can be held without guessing: a native button, link or field answers Enter and Space by itself, Radix's
+ * primitives carry their own keys, and scripts/check.ts fails any element that only claims a control's role
+ * (role="button", "tab", "switch" and the rest) with no onKeyDown (issue #11). A pass that presses keys here is left
+ * out on purpose, so it cannot cry wolf: what a key should do
  * depends on the role — Enter activates a button and a menu item, Space toggles a checkbox and a switch, and an arrow
  * key moves within a radio group — so a blanket "something must change on Enter" fails honest controls and teaches
  * people to ignore the check. Two things a future check needs: send the key as

package/payload/scripts/lib/chrome.ts

@@ -13,6 +13,8 @@ const sleep = (ms: number) => new Promise((r) => setTimeout(r, ms));
 export type Page = {
   /** Uncaught exceptions and console errors since the last open(). */
   errors: string[];
+  /** How many native file choosers the page has opened: intercepted, so none is shown, and counted, since opening one changes nothing in the DOM. */
+  fileChoosers: () => number;
   send: (method: string, params?: Record<string, unknown>) => Promise<any>;
   eval: <T = unknown>(expression: string) => Promise<T>;
   open: (url: string, opts: { width: number; height?: number; theme?: 'light' | 'dark'; reduced?: boolean; wait?: number }) => Promise<void>;
@@ -59,8 +61,10 @@ async function attach(proc: ChildProcess, dir: string, handle: { proc: ChildProc
   let id = 0;
   const pending = new Map<number, (m: any) => void>();
   const errors: string[] = [];
+  let choosers = 0;
   ws.addEventListener('message', (e) => {
     const m = JSON.parse(String(e.data));
+    if (m.method === 'Page.fileChooserOpened') choosers++;
     if (m.id && pending.has(m.id)) { pending.get(m.id)!(m); pending.delete(m.id); return; }
     if (m.method === 'Runtime.exceptionThrown') errors.push('exception: ' + (m.params.exceptionDetails?.exception?.description ?? m.params.exceptionDetails?.text ?? '').split('\n')[0]);
     if (m.method === 'Runtime.consoleAPICalled' && m.params.type === 'error') errors.push('console.error: ' + m.params.args.map((a: any) => a.value ?? a.description ?? '').join(' ').slice(0, 200));
@@ -75,8 +79,10 @@ async function attach(proc: ChildProcess, dir: string, handle: { proc: ChildProc
     });
   await send('Page.enable');
   await send('Runtime.enable');
+  await send('Page.setInterceptFileChooserDialog', { enabled: true });
   const page: Page = {
     errors,
+    fileChoosers: () => choosers,
     send,
     async eval(expression) {
       const r = await send('Runtime.evaluate', { expression, returnByValue: true, awaitPromise: true });

package/payload/scripts/verify.ts

@@ -266,9 +266,10 @@ const freePort = () => new Promise<number>((res) => { const s = net.createServer
 // BLANKED, not deleted: `next start` loads `.env.local` itself, where a person keeps their own model, and Next does not
 // overwrite a variable that is already set — so a deleted `ASSISTANT_*` came straight back from that file and the
 // "assistant off" start failed with "the page has 1 assistant element(s)" while nothing was wrong (`assistantConfig`
-// treats a blank value as unset). Reported in issue #7 against `e4a6225`.
+// treats a blank value as unset). Reported in issue #7 against `e4a6225`. Every name the assistant reads is blanked,
+// set in the shell or not: a variable kept only in `.env.local` is absent here and would come back from it (issue #16).
 const clean: NodeJS.ProcessEnv = { ...process.env };
-for (const k of Object.keys(clean)) if (k.startsWith('ASSISTANT_')) clean[k] = '';
+for (const k of ['ASSISTANT_PROVIDER', 'ASSISTANT_API_KEY', 'ASSISTANT_MODEL', 'ASSISTANT_BASE_URL', ...Object.keys(clean).filter((k) => k.startsWith('ASSISTANT_'))]) clean[k] = '';
 
 function step(name: string, cmd: string, args: string[], env = clean, last = false) {
   current = name;

package/payload/skills/zz-meridian/references/customize.md

@@ -67,12 +67,16 @@ Rules that make every page look like it belongs:
   open their record. Below 768px a data table becomes a card list by itself.
 - **Every state**: loading (`loading.tsx` with skeletons shaped like the page), empty (Empty state with the one action),
   error (`error.tsx`, what failed and Retry).
+- **A file picker** is a visible `Button` that calls `input.click()` on an `<input type="file">` with `tabIndex={-1}`
+  and `aria-hidden`, so the keyboard reaches the button and never the hidden input; give the press a state of its own
+  ("Choosing the files…") until the change event arrives. The presses count a file chooser that opens as an answer.
 - **A page spec** next to each route (`README.md`: summary, Structure, States, Surfaces, Agents), so the next person, or
   agent, knows what the page is for. `node scripts/check.ts` requires Structure and States, and under `## Agents` a
   `### What the agent reads` part for every page in `optional:app/(dashboard)/` and `optional:app/embed/`.
 - **A shared context** for each page (decision 0011): a pure function beside the view builds it from the page's data
   (copy `optional:src/views/overview-context.ts`: scope, freshness, each figure with its unit, change and definition,
-  what `optional:src/lib/insight.ts` finds, what the data cannot say), and the view passes it to `useShareView`. Both
+  what `optional:src/lib/insight.ts` finds, what the data cannot say), and the view passes it to `useShareView`; a
+  server page with no client view places `<ShareContext context={…} />` among its cards instead. Both
   agents read it: an MCP host and the console's assistant. Add the page's tool to `optional:src/views/tools.ts` so the
   assistant can open it at an address.
 
@@ -92,7 +96,11 @@ The layout hands the shell whether it is on as a promise it does not await, `ass
   records from several places (the layout's shell tools, a page strip, the page and its freshness stamp), and `read()`
   caches per caller's scope and refreshes exactly the tenant a write touched, so do not wrap the read in a second cache;
   writes call `updateTag` after the commit (`cache.md`). Raise the pool's idle timeout too: `pg` drops an idle connection after 10s, and a remote Postgres with TLS
-  costs hundreds of milliseconds to reconnect. Issue #7 has the numbers.
+  costs hundreds of milliseconds to reconnect. Issue #7 has the numbers. A pool that keeps connections idle must also
+  listen for their loss: `pool.on('error', (e) => console.error('db: an idle connection closed', e))`. Without it, the
+  database or its pooler closing an idle connection is an uncaught `error` event and the server exits (issue #16); the
+  pool has already dropped the broken client, so logging is enough. Set `connectionTimeoutMillis` too, so a database
+  that does not answer fails a read instead of hanging it.
 - **Sign-in check** goes in three places, the same check: `optional:app/(dashboard)/layout.tsx`, `optional:app/api/assistant/route.ts` and every server action (each `actions.ts`), because a server action is a public endpoint the layout does not guard
   (before the model is reached).
 - **The switch** ("Show the assistant") is in `optional:src/views/settings.tsx`. A product that deletes Settings moves it, or the

package/payload/skills/zz-meridian/references/existing-project.md

@@ -83,6 +83,27 @@ cache; writes call `updateTag` after the commit (`cache.md`, "Authorized, scoped
 invalidate"). And raise the connection pool's idle timeout past `pg`'s 10-second default, since a cache miss is a round
 trip each. Issue #7 has the numbers.
 
+## The database behind the collections
+
+Meridian's sample serves fixtures; a product's collections read a database. What adopters met, and what held (issues #16 and #17):
+
+- **The pool survives a dropped connection.** Keep idle connections for minutes (`idleTimeoutMillis`, `customize.md`), and
+  listen for their loss: `pool.on('error', (e) => console.error('db: an idle connection closed', e))`. Without the
+  listener, the database or its pooler closing an idle connection is an uncaught error and the server exits. Set
+  `connectionTimeoutMillis` so a database that does not answer fails a read rather than hanging it.
+- **Behind a transaction pooler** (PgBouncer, Neon's pooled endpoint, Supabase's): pass no session setting to the pool. A
+  `statement_timeout` or any startup option is refused at connect ("unsupported startup parameter") and every connection
+  fails; set limits with `SET LOCAL` inside each transaction instead. A session advisory lock does not hold across
+  transaction pooling: take a start-up lock with `pg_try_advisory_lock`, try it once, and carry on without it. Connect
+  migrations, and anything that needs a session, to the direct endpoint.
+- **Schema changes run on start, never in the build.** Apply the product's own migrations from `instrumentation.ts`
+  (`register`, on the Node.js runtime) under that non-blocking lock, so one instance migrates and the rest serve; keep the
+  migrator's bookkeeping in a schema the role may write (`public`); never stop the server on a failure, and report the
+  outcome at a health route so a deploy can read it. A build has no database to migrate and must not need one.
+- **A role that may read and write but not create.** Deployed roles often lack `CREATE`, and a migrator that starts with
+  `CREATE SCHEMA` is refused even where tables may be created. Ship the schema as a one-off SQL file a person with the
+  owner's role runs once, and let the application role only migrate within what it may do.
+
 ## Route A2: a static HTML page (data fetched as JSON)
 
 The simplest case. Create a new Meridian project (SKILL.md steps 3 and 4, with `--product`) and point a module in

package/payload/skills/zz-meridian/references/update.md

@@ -161,12 +161,13 @@ update (`2` pending, `0` finalized, `1` failure). `--abort`: `0` aborted, `1` re
 
 ## Resolving 0.9.0's migrations
 
-Moving a project to 0.9.0 can report two more `migration:<id>` items, resolved the same way as those below:
+Moving a project to 0.9.0 can report two more `migration:<id>` items, and to 0.10.0 a third for an assistant kept from before, resolved the same way as those below:
 
 | Id | The old shape it found | The change |
 |----|------------------------|------------|
 | `share-view-context` | `useShareView(text, structured)`, a sentence and an object | one shared context per view, `useShareView(context)`: `agents.md`, "Legible", and `customize.md`, "A shared context" |
 | `agent-reads-section` | a page README under `optional:app/(dashboard)/` or `optional:app/embed/` with no `### What the agent reads` | add the part under `## Agents`: `customize.md`, "A page spec"; checked by the gate |
+| `assistant-view-tools` (0.10.0) | an assistant route, `optional:src/lib/assistant/tools.ts` or `optional:src/lib/assistant/respond.ts` kept from before view tools | bring the two files over from the release and pass `views` to `respond` (the template's `viewTools`, your own, or none): `example:docs/assistant.md`, "Adding an MCP server later" |
 
 A created project that never changed the template's pages brings the release's version of each affected file over, with
 the files that arrived with them: the view contexts `optional:src/views/overview-context.ts` and its siblings, the view

package/payload/src/components/base/surface/README.md

@@ -9,7 +9,7 @@ Status: beta
 1. **`useSurface()`**: `kind` (`console` | `embed`), `connected`, `mode` (`inline` | `fullscreen` | `pip`), the host context, and four actions: `expand`, `ask` (absent when no agent listens), `share` and `openLink`.
 2. **`EmbedSurface`**: wraps every route under `app/embed/`. It starts the host bridge, applies the host's theme (`data-theme`), style variables and safe-area insets, marks the root `data-surface="embed"`, and reports the body's height.
 3. **When the host refuses.** A refused `ui/update-model-context` is sent once more a second later; refused again, every Ask from the view carries the context's first line (the view, its scope and its address), so the question keeps its referent. A refused `ui/message` tells the person in a toast, with the question to ask in the chat themselves. A refused fullscreen opens the console page.
-4. **`useShareView(context)`**: keeps both agents told what is on screen, with one shared context (decision 0011). In an MCP host it is re-sent as `ui/update-model-context` 250ms after it settles; on the console `share` publishes it for the assistant, which reads it with the next question (`sharedContextOn`). `SurfaceOverride` shares with nobody unless given a `share`, so an Atlas specimen never speaks for the page.
+4. **`useShareView(context)`**: keeps both agents told what is on screen, with one shared context (decision 0011). In an MCP host it is re-sent as `ui/update-model-context` 250ms after it settles; on the console `share` publishes it for the assistant, which reads it with the next question (`sharedContextOn`). `SurfaceOverride` shares with nobody unless given a `share`, so an Atlas specimen never speaks for the page. `<ShareContext context={…} />` is the same hook as a component, for a server page with no client view to call it from.
 4. **`SurfaceOverride`**: puts a subtree on a given surface without a host, for the Atlas and tests.
 
 ## The host bridge

package/payload/src/components/base/use-share-view.ts

@@ -21,3 +21,12 @@ export function useShareView(context: SharedContext) {
     // eslint-disable-next-line react-hooks/exhaustive-deps
   }, [key, kind, connected, share]);
 }
+
+/**
+ * The same, as a component that renders nothing: a server page that awaits its record and renders cards has no client
+ * view to call the hook from, so it places `<ShareContext context={…} />` among them (issue #17).
+ */
+export function ShareContext({ context }: { context: SharedContext }) {
+  useShareView(context);
+  return null;
+}

package/payload/src/components/patterns/data-table/README.md

@@ -1,6 +1,6 @@
 # Data table
 
-A list of records in one card: a toolbar, the table, and pagination, with its loading, empty and error states built in. On phones the same rows become cards, in CSS, so nothing ever scrolls sideways.
+A list of records in one card: a toolbar, the table, and pagination, with its loading, empty and error states built in. On phones, and in any frame too narrow for its columns, the same rows become cards, in CSS, so nothing ever scrolls sideways.
 
 Status: beta
 
@@ -13,7 +13,7 @@ Status: beta
 5. **Rows**: `row-height` 52px (38px compact), a `line` divider between rows. The title column (`mobile: 'title'`, or the first) is the row's link when the row opens a record. The whole row takes the `fill-hover` tint on hover; the title keeps its colour and is never underlined.
 6. **Selection column** (optional): 40px with a Checkbox; the head's checkbox selects the page and shows indeterminate when part of it is chosen.
 7. **Footer**: Pagination, under a `line` divider, shown only when the rows do not fit on one page.
-8. **Cards, not a second list** (under 768px): the same table's rows lay out as cards — the title and the status on one line, two or three facts under it in `text-xs` `ink-3`, separated by dots. It is the SAME tree: the row becomes a six-column grid and each cell says which part of the card it is (`data-mobile`), so nothing is built twice and no device downloads a tree it cannot show.
+8. **Cards, not a second list** (when the table is under 640px wide, a phone or a half-width row on a wide screen): the same table's rows lay out as cards — the title and the status on one line, two or three facts under it in `text-xs` `ink-3`, separated by dots. It is the SAME tree: the row becomes a six-column grid and each cell says which part of the card it is (`data-mobile`), so nothing is built twice and no device downloads a tree it cannot show.
 
 ## Variants
 
@@ -55,7 +55,7 @@ Arrival: rows rise with the page (`arrive`); under reduced motion they are simpl
 ## Surfaces
 
 - **Console**: as specified; low-value columns drop with `hideBelow` as the window narrows.
-- **Mobile**: under 768px each row becomes a card, and the columns not wanted there are hidden. Facts that need their header to make sense use `mobileCell` ("Used 1 min ago", not "1 min ago"); the phone reads a smaller size in `ink-3`.
+- **Mobile, and any narrow frame**: once the table itself is under 640px wide each row becomes a card (a container query, as `hideBelow` reads the table's width, so a table in a split row or beside the assistant's column never runs past its frame), and the columns not wanted there are hidden. Facts that need their header to make sense use `mobileCell` ("Used 1 min ago", not "1 min ago"); the phone reads a smaller size in `ink-3`.
 - **Embed**: inline views show at most five rows as a compact list and offer Expand; fullscreen shows the full table.
 
 ## Agents

package/payload/src/components/patterns/data-table/index.tsx

@@ -73,14 +73,18 @@ const CELLS = [
   '[&_tbody_tr]:transition-colors [&_tbody_tr]:duration-(--dur-hover) [&_tbody_td]:border-b [&_tbody_td]:border-line [&_tbody_tr:last-child_td]:border-0',
 ].join(' ');
 
-/** What a row becomes below 768px: a six-column grid, a card's padding, a hairline between cards. */
+/**
+ * What a row becomes when the TABLE is under 640px wide: a six-column grid, a card's padding, a hairline between cards.
+ * The table's own width, not the window's, as `hideBelow` reads it: a table in a half-width row on a wide screen, or
+ * beside the assistant's column, becomes cards instead of running past its frame (issue #9's Atlas audit).
+ */
 const PHONE_ROWS = [
-  'max-md:[&_tbody_tr]:grid max-md:[&_tbody_tr]:grid-cols-6 max-md:[&_tbody_tr]:items-center max-md:[&_tbody_tr]:gap-x-3 max-md:[&_tbody_tr]:gap-y-1',
-  'max-md:[&_tbody_tr]:px-(--card-pad) max-md:[&_tbody_tr]:py-3.5 max-md:[&_tbody_td]:border-0 max-md:[&_tbody_tr]:border-b max-md:[&_tbody_tr]:border-line max-md:[&_tbody_tr:last-child]:border-b-0',
+  '@max-[640px]:[&_tbody_tr]:grid @max-[640px]:[&_tbody_tr]:grid-cols-6 @max-[640px]:[&_tbody_tr]:items-center @max-[640px]:[&_tbody_tr]:gap-x-3 @max-[640px]:[&_tbody_tr]:gap-y-1',
+  '@max-[640px]:[&_tbody_tr]:px-(--card-pad) @max-[640px]:[&_tbody_tr]:py-3.5 @max-[640px]:[&_tbody_td]:border-0 @max-[640px]:[&_tbody_tr]:border-b @max-[640px]:[&_tbody_tr]:border-line @max-[640px]:[&_tbody_tr:last-child]:border-b-0',
 ].join(' ');
 
 /** The resets a cell needs once the row is a grid: not a row height, not a padding box, free to shrink and to clip. */
-const PHONE_CELLS = 'max-md:[&_td:not([data-mobile=hidden])]:!h-auto max-md:[&_td:not([data-mobile=hidden])]:!max-w-none max-md:[&_td:not([data-mobile=hidden])]:!p-0 max-md:[&_td:not([data-mobile=hidden])]:min-w-0 max-md:[&_td:not([data-mobile=hidden])]:!block max-md:[&_[data-sep]]:inline';
+const PHONE_CELLS = '@max-[640px]:[&_td:not([data-mobile=hidden])]:!h-auto @max-[640px]:[&_td:not([data-mobile=hidden])]:!max-w-none @max-[640px]:[&_td:not([data-mobile=hidden])]:!p-0 @max-[640px]:[&_td:not([data-mobile=hidden])]:min-w-0 @max-[640px]:[&_td:not([data-mobile=hidden])]:!block @max-[640px]:[&_[data-sep]]:inline';
 
 /** Where a role sits in the card, and how it reads there.
  *
@@ -89,13 +93,15 @@ const PHONE_CELLS = 'max-md:[&_td:not([data-mobile=hidden])]:!h-auto max-md:[&_t
  * card's own rule is the role, not the width. The title takes one column fewer when a checkbox leads the row: six
  * columns, and the status keeps the last two. */
 const PHONE_ROLES = [
-  'max-md:[&_td[data-mobile=check]]:col-span-1 max-md:[&_td[data-mobile=check]]:row-start-1',
-  'max-md:[&_td[data-mobile=title]]:row-start-1 max-md:[&_td[data-mobile=title]]:font-medium',
-  'max-md:[&_td[data-mobile=status]]:row-start-1 max-md:[&_td[data-mobile=status]]:justify-self-end',
-  'max-md:[&_td[data-mobile=fact]]:row-start-2 max-md:[&_td[data-mobile=fact]]:col-span-2 max-md:[&_td[data-mobile=fact]]:text-xs max-md:[&_td[data-mobile=fact]]:text-ink-3',
-  'max-md:[&_td[data-mobile=hidden]]:hidden',
+  '@max-[640px]:[&_td[data-mobile=check]]:col-span-1 @max-[640px]:[&_td[data-mobile=check]]:row-start-1',
+  '@max-[640px]:[&_td[data-mobile=title]]:row-start-1 @max-[640px]:[&_td[data-mobile=title]]:font-medium',
+  '@max-[640px]:[&_td[data-mobile=status]]:row-start-1 @max-[640px]:[&_td[data-mobile=status]]:justify-self-end',
+  '@max-[640px]:[&_td[data-mobile=fact]]:row-start-2 @max-[640px]:[&_td[data-mobile=fact]]:col-span-2 @max-[640px]:[&_td[data-mobile=fact]]:text-xs @max-[640px]:[&_td[data-mobile=fact]]:text-ink-3',
+  '@max-[640px]:[&_td[data-mobile=hidden]]:hidden',
+  // On the accent wash of a selected row, a fact steps up to ink-2: ink-3 on it falls under 4.5:1 in light.
+  '@max-[640px]:[&_tr[aria-selected]_td[data-mobile=fact]]:text-ink-2',
 ].join(' ');
-const PHONE_TITLE_SPAN = { plain: 'max-md:[&_td[data-mobile=title]]:col-span-4', selectable: 'max-md:[&_td[data-mobile=title]]:col-span-3' };
+const PHONE_TITLE_SPAN = { plain: '@max-[640px]:[&_td[data-mobile=title]]:col-span-4', selectable: '@max-[640px]:[&_td[data-mobile=title]]:col-span-3' };
 
 /* Literal strings, as in the Table: Tailwind finds classes by reading the source. */
 const HIDE: Record<Breakpoint, string> = { sm: '@max-[512px]:hidden', md: '@max-[672px]:hidden', lg: '@max-[896px]:hidden', xl: '@max-[1152px]:hidden' };
@@ -253,7 +259,7 @@ export function DataTable<R>({
   } else {
     const roleOf = (c: Column<R>): Mobile => (c === titleColumn ? 'title' : c === status ? 'status' : facts.includes(c) ? 'fact' : 'hidden');
     body = (
-      <Table caption={caption} aria-busy={loading || undefined} className={cn('max-md:block max-md:[&>thead]:hidden max-md:[&>tbody]:block', CELLS, PHONE_ROWS, PHONE_CELLS, PHONE_ROLES, PHONE_TITLE_SPAN[selectable ? 'selectable' : 'plain'])}>
+      <Table caption={caption} aria-busy={loading || undefined} className={cn('@max-[640px]:block @max-[640px]:[&>thead]:hidden @max-[640px]:[&>tbody]:block', CELLS, PHONE_ROWS, PHONE_CELLS, PHONE_ROLES, PHONE_TITLE_SPAN[selectable ? 'selectable' : 'plain'])}>
         <TableHead>
           <tr>
             {selectable ? (
@@ -301,8 +307,8 @@ export function DataTable<R>({
                               both are rendered and one is hidden: a few words each, never a second copy of the row. */}
                           {c.mobileCell ? (
                             <>
-                              <span className="max-md:hidden">{content}</span>
-                              <span className="hidden max-md:contents">{c.mobileCell(r)}</span>
+                              <span className="@max-[640px]:hidden">{content}</span>
+                              <span className="hidden @max-[640px]:contents">{c.mobileCell(r)}</span>
                             </>
                           ) : content}
                           {/* The dot that separates two facts, on a phone only — the table has a column for each of

package/payload/src/components/patterns/filter-bar/index.tsx

@@ -66,7 +66,7 @@ export function FilterBar({
           value={f.value}
           onValueChange={f.onChange}
           options={f.options}
-          leading={<span className="text-xs text-ink-3">{f.label}</span>}
+          leading={<span className={cn('text-xs', on ? 'text-ink-2' : 'text-ink-3')}>{f.label}</span>}
           className={cn(!block && 'w-auto min-w-0', on && !block && 'border-accent-line bg-accent-tint text-ink')}
         />
       );

package/payload/src/data/collections.ts

@@ -11,7 +11,9 @@
  *    directly, so a validation never sees an earlier answer. That product's three heaviest pages answered 44-46% sooner.
  * 2. Raise the connection pool's idle timeout. `pg` drops an idle connection after 10 seconds, and against a remote
  *    Postgres with TLS a new one cost that product 330 ms to 1.5 s — paid again on the next click by anybody who reads
- *    a page for a moment. `idleTimeoutMillis: 300_000` is what they settled on.
+ *    a page for a moment. `idleTimeoutMillis: 300_000` is what they settled on. A pool that keeps connections idle must
+ *    also listen for their loss, `pool.on('error', (e) => console.error('db: an idle connection closed', e))`, or the
+ *    database closing one is an uncaught error and the server exits (issue #16); add `connectionTimeoutMillis` too.
  */
 import { z } from 'zod';
 import { arrayCollection, type AnyCollection, type Collection } from '@/lib/collection';

package/payload/src/system/atlas-shell.tsx

@@ -123,7 +123,7 @@ function Shelf({ nav }: { nav: AtlasNav }) {
                         <Link href={it.href} aria-current={on ? 'page' : undefined} className={cn('relative flex h-8 items-center gap-2 rounded-sm px-2.5 text-sm', on ? 'bg-accent-tint font-medium text-ink' : 'text-ink-2 hover:bg-fill-hover hover:text-ink')}>
                           {on ? <span aria-hidden className="absolute top-1.5 bottom-1.5 -left-[9px] w-0.5 rounded-full bg-accent" /> : null}
                           <span className="flex-1 truncate">{it.title}</span>
-                          {/* Only the exception is marked: most cards are beta, so a mark on every row says nothing. */}{it.status === 'draft' ? <span className="font-mono text-2xs tracking-[0.08em] text-ink-3 uppercase">{it.status}</span> : null}
+                          {/* Only the exception is marked: most cards are beta, so a mark on every row says nothing. */}{it.status === 'draft' ? <span className="font-mono text-2xs tracking-[0.08em] text-ink-2 uppercase">{it.status}</span> : null}
                         </Link>
                       </li>
                     );

package/payload/src/system/card-stage.tsx

@@ -58,7 +58,8 @@ export function CardStage({ id }: { id: string }) {
   const pane = (t: 'dark' | 'light') => (
     <Scope key={t} theme={t} accent={accent} density={density} className="px-5 py-8 sm:px-10">
       {theme === 'both' ? <p className="t-kicker mb-6">{t}</p> : null}
-      <div className={cn('mx-auto', width === 'phone' ? 'max-w-[390px]' : 'max-w-none')}><Suspense><P /></Suspense></div>
+      {/* A specimen, not the page: its own headings and scroll regions are the card's (a Detail head is an h1 where it is used), so the audit keeps them out of the page's outline and its one scroller (issue #8). */}
+      <div data-specimen className={cn('mx-auto', width === 'phone' ? 'max-w-[390px]' : 'max-w-none')}><Suspense><P /></Suspense></div>
     </Scope>
   );
   return (

package/payload/src/system/fixtures/sample.ts

@@ -2,6 +2,10 @@
  * The sample product: this template presented as a fictional API platform under the name in app.config, so the template's pages, the Design Atlas and every card preview
  * run with no backend and look like a real product.
  *
+ * Every customer, person, region and incident in it is invented: Northwind Labs, Parallax AI, Maya Chen and the rest
+ * name nobody this work came from, and a name that matches a real company does so by chance. Plausible names keep the
+ * examples readable, as a placeholder like "Customer 1" would not (issue #14).
+ *
  * It is not your data seam. A product built on the template reads its own module in src/data/ and leaves this one in
  * place for the Atlas and the previews.
  *

package/payload/src/system/preview-loaders.ts

@@ -74,7 +74,6 @@ export const PREVIEW_LOADERS: Record<string, () => Promise<{ default: ComponentT
   'patterns/heatmap': () => import('@/components/charts/heatmap/preview'),
   'patterns/meridian': () => import('@/components/charts/meridian/preview'),
   'patterns/sparkline': () => import('@/components/charts/sparkline/preview'),
-  'patterns/timeline': () => import('@/components/charts/timeline/preview'),
   'patterns/trend-chart': () => import('@/components/charts/trend-chart/preview'),
   'patterns/uptime-bars': () => import('@/components/charts/uptime-bars/preview'),
 };

package/payload/src/system/registry.ts

@@ -74,7 +74,6 @@ export const CARDS: Card[] = [
   { id: 'heatmap', layer: 3, section: 'patterns', dir: 'src/components/charts/heatmap', Preview: dynamic(() => import('@/components/charts/heatmap/preview')) },
   { id: 'meridian', layer: 3, section: 'patterns', dir: 'src/components/charts/meridian', Preview: dynamic(() => import('@/components/charts/meridian/preview')) },
   { id: 'sparkline', layer: 3, section: 'patterns', dir: 'src/components/charts/sparkline', Preview: dynamic(() => import('@/components/charts/sparkline/preview')) },
-  { id: 'timeline', layer: 3, section: 'patterns', dir: 'src/components/charts/timeline', Preview: dynamic(() => import('@/components/charts/timeline/preview')) },
   { id: 'trend-chart', layer: 3, section: 'patterns', dir: 'src/components/charts/trend-chart', Preview: dynamic(() => import('@/components/charts/trend-chart/preview')) },
   { id: 'uptime-bars', layer: 3, section: 'patterns', dir: 'src/components/charts/uptime-bars', Preview: dynamic(() => import('@/components/charts/uptime-bars/preview')) },
 ];

package/payload/src/system/sample-cells.tsx

@@ -60,7 +60,7 @@ export const requestColumns: Column<RequestRow>[] = [
     key: 'latency', header: 'Latency', numeric: true, mobile: 'fact', sortValue: (r) => r.latency,
     cell: (r) => <span className={r.latency > 1000 ? 'font-medium text-warning-ink' : undefined}>{formatDuration(r.latency)}</span>,
   },
-  { key: 'customer', header: 'Customer', muted: true, mobile: 'fact', hideBelow: 'md', cell: (r) => <span className="whitespace-nowrap">{r.customer}</span>, sortValue: (r) => r.customer },
+  { key: 'customer', header: 'Customer', muted: true, mobile: 'fact', hideBelow: 'lg', cell: (r) => <span className="whitespace-nowrap">{r.customer}</span>, sortValue: (r) => r.customer },
   { key: 'region', header: 'Region', muted: true, hideBelow: 'lg', cell: (r) => <span className="font-mono text-xs whitespace-nowrap">{r.region}</span> },
   { key: 'size', header: 'Size', numeric: true, muted: true, hideBelow: 'xl', cell: (r) => formatBytes(r.bytes), sortValue: (r) => r.bytes },
   {

package/payload/src/views/health.tsx

@@ -18,15 +18,9 @@ import { StatusDot } from '@/components/ui/status-dot';
 import type { Tone } from '@/components/ui/badge';
 import { cn } from '@/lib/cn';
 import { formatDuration } from '@/lib/format';
-import { useShareView } from '@/components/base/use-share-view';
+import { ShareContext } from '@/components/base/use-share-view';
 import { healthContext, type HealthData } from './health-context';
 
-/** Tells both agents what Health shows (decision 0011). */
-export function ShareHealth({ data }: { data: HealthData }) {
-  useShareView(healthContext(data));
-  return null;
-}
-
 const RANK: Record<DayState, number> = { operational: 0, none: 0, degraded: 1, outage: 2 };
 const TONE: Record<DayState, Tone> = { operational: 'positive', none: 'neutral', degraded: 'warning', outage: 'critical' };
 
@@ -37,7 +31,7 @@ export function HealthBody(data: HealthData) {
   if (services.length === 0) {
     return (
       <Card>
-        <ShareHealth data={data} />
+        <ShareContext context={healthContext(data)} />
         <EmptyState title="No services yet" className="py-16">Every service you monitor appears here with its state now and its last 90 days.</EmptyState>
       </Card>
     );
@@ -50,7 +44,7 @@ export function HealthBody(data: HealthData) {
   const affected = services.filter((x) => x.status !== 'operational').map((x) => x.name);
   return (
     <Stack>
-      <ShareHealth data={data} />
+      <ShareContext context={healthContext(data)} />
       <Row split={current ? '2/3' : 'full'}>
         <FeaturedMetric
           kicker="Uptime · all services · 90 days"

package/payload/src/components/charts/timeline/README.md

@@ -1,74 +0,0 @@
-# Timeline
-
-The timeline shows work over months: one bar per item from its start day to its end day, grouped by workstream, on month hairlines with a line for today.
-
-Status: beta
-
-## Anatomy
-
-1. **Month scale**: a 44px row: month names in `text-2xs` `ink-3` along its foot (the year, short, on January and on the first month shown: "Jul ’26"), the Today chip above them.
-2. **Today**: a 1px `accent` line through every row, labelled "Today" on the scale in a small accent chip.
-3. **Heat row** (optional): one cell per month, the accent at 12% to 100% by the month's value, with its label on the left.
-4. **Group head**: the workstream in `t-eyebrow`, 16px above its first row.
-5. **Rows**: a label column (7rem, 11rem from 512px) and a 36px plot row with a 1px `line` hairline under it.
-6. **Bar**: 10px tall, `radius-full`, at least 6px wide, from the start day to the end of the end day.
-7. **Screen-reader table**: every item with its group, start and end dates.
-
-## Variants
-
-| Tone | Fill | Use |
-|---|---|---|
-| `neutral` (default) | `chart-neutral-strong` | Work in the plan |
-| `accent` | `accent` | The item in focus, at most one or two |
-| `positive`, `warning`, `critical` | status fills | Done, at risk, late, with the word in the label or the record |
-
-## Sizes
-
-The plot is in percent of the span from `from` to `to`, so it fits its container at any width and never scrolls sideways. The label column is 7rem under 512px of its own width and 11rem from there.
-
-Leave `from` and `to` out and the span is the items' own extent. A roadmap usually wants the other thing: a fixed planning window — this half-year and the next — so the same rows sit in the same place from week to week, and an item that starts before the window or runs past it is clipped and squared off (see Outside the span, below).
-
-## States
-
-| State | Spec |
-|---|---|
-| Rest | as above |
-| Linked | an item with `href` makes its label a link (`row-link`: it takes the accent on hover, with no underline) |
-| Outside the span | a bar is clipped to the span and the side that continues is squared off (`rounded-l-none` when it started before `from`, `rounded-r-none` when it ends after `to`), so work that runs past the window does not read as work that began at its edge; Today is drawn only when it falls inside |
-
-## Behaviour
-
-Static: no cursor, no zoom. The label is the item's link; the bar is drawn for the eye and carries its dates in a title.
-
-## Surfaces
-
-- **Console**: a full-width card, or a 2/3 cell on a wide screen.
-- **Mobile**: the label column narrows and month names stay short; a phone reads a quarter or two well.
-- **Embed**: same, inline at the host's width; keep the span to a quarter so bars stay wide enough to read.
-
-## Agents
-
-An agent may read the items and the span; a change of dates is a Proposal ("Move Gateway v5 to start 16 Nov"), never a drag.
-
-## Accessibility
-
-- The plot is decorative (`aria-hidden`); the screen-reader table lists every item with its group and dates, and each linked label is a real link in the tab order.
-- Contrast: bars are `chart-neutral-strong`, the accent or a status fill, each at least 3:1 on `surface` in both themes; month labels are `ink-3` text.
-
-## Content
-
-- Labels name the work, not the ticket: "Regional failover", not "PLAT-1432". Months are "Oct", "Jan 2027".
-
-## Do and do not
-
-- Do keep one or two accent bars: the accent is the focus, not a category.
-- Do not encode a status by colour alone: say it in the label or the linked record.
-- Do not show a span longer than a year in one card; split it, or zoom to quarters.
-
-## Implementation
-
-```tsx
-import { Timeline } from '@/components/charts/timeline';
-
-<Timeline items={roadmap} from="2026-07-01" to="2027-01-31" today={today} label="Roadmap, July to January" />
-```

package/payload/src/components/charts/timeline/index.tsx

@@ -1,148 +0,0 @@
-import Link from 'next/link';
-import { Fragment } from 'react';
-import { cn } from '@/lib/cn';
-
-/** One piece of work from a start day to an end day (both inclusive, ISO dates), in a group such as a workstream. */
-export type TimelineItem = {
-  id: string;
-  label: string;
-  group?: string;
-  start: string;
-  end: string;
-  /** What the bar means: the accent for work in focus, a status for a judgement, neutral for the rest. */
-  tone?: 'accent' | 'neutral' | 'positive' | 'warning' | 'critical';
-  href?: string;
-};
-
-const DAY = 86_400_000;
-const day = (iso: string) => Date.UTC(+iso.slice(0, 4), +iso.slice(5, 7) - 1, +iso.slice(8, 10));
-const MONTH = new Intl.DateTimeFormat('en-US', { month: 'short', timeZone: 'UTC' });
-const LONG = new Intl.DateTimeFormat('en-US', { day: '2-digit', month: 'short', year: 'numeric', timeZone: 'UTC' });
-const TONE = { accent: 'bg-accent', neutral: 'bg-chart-neutral-strong', positive: 'bg-positive', warning: 'bg-warning', critical: 'bg-critical' } as const;
-
-/**
- * Work over months: one bar per item from its start to its end, grouped by workstream, on month hairlines with a
- * line for today. The label column never scrolls; the plot is in percent, so it fits any width without scrolling
- * sideways. An optional heat row shades each month by a value (load, spend, incidents).
- */
-export function Timeline({
-  items,
-  from,
-  to,
-  today,
-  heat,
-  heatLabel = 'Load',
-  label,
-  className,
-}: {
-  items: TimelineItem[];
-  /** The first and last day shown (ISO dates); default to the earliest start and the latest end. */
-  from?: string;
-  to?: string;
-  /** Today's date (ISO), from the data's clock: the line that says where the plan stands. */
-  today?: string;
-  /** One value per month, keyed "YYYY-MM", for the heat row above the bars. */
-  heat?: Record<string, number>;
-  heatLabel?: string;
-  label: string;
-  className?: string;
-}) {
-  const lo = day(from ?? items.reduce((m, it) => (it.start < m ? it.start : m), items[0]?.start ?? '2026-01-01'));
-  const hi = day(to ?? items.reduce((m, it) => (it.end > m ? it.end : m), items[0]?.end ?? '2026-12-31')) + DAY;
-  const pct = (t: number) => `${Math.max(0, Math.min(100, ((t - lo) / (hi - lo)) * 100))}%`;
-
-  // Month starts inside the span, for hairlines, labels and the heat row.
-  const months: { key: string; t: number; next: number; label: string }[] = [];
-  for (let d = new Date(lo); d.getTime() < hi; d = new Date(Date.UTC(d.getUTCFullYear(), d.getUTCMonth() + 1, 1))) {
-    const start = Date.UTC(d.getUTCFullYear(), d.getUTCMonth(), 1);
-    const next = Date.UTC(d.getUTCFullYear(), d.getUTCMonth() + 1, 1);
-    const m = d.getUTCMonth();
-    months.push({ key: `${d.getUTCFullYear()}-${String(m + 1).padStart(2, '0')}`, t: Math.max(start, lo), next: Math.min(next, hi), label: m === 0 || months.length === 0 ? `${MONTH.format(d)} \u2019${String(d.getUTCFullYear()).slice(2)}` : MONTH.format(d) });
-  }
-  const groups = [...new Set(items.map((it) => it.group ?? ''))];
-  const heatMax = heat ? Math.max(1, ...Object.values(heat)) : 1;
-  const now = today ? day(today) : null;
-
-  const Guides = () => (
-    <>
-      {months.slice(1).map((m) => <span key={m.key} aria-hidden className="absolute inset-y-0 w-px bg-chart-grid" style={{ left: pct(m.t) }} />)}
-      {now !== null && now >= lo && now < hi ? <span aria-hidden className="absolute inset-y-0 z-10 w-px bg-accent" style={{ left: pct(now) }} /> : null}
-    </>
-  );
-
-  return (
-    <figure aria-label={label} className={cn('@container w-full min-w-0', className)}>
-      <div className="grid grid-cols-[7rem_minmax(0,1fr)] text-sm @lg:grid-cols-[11rem_minmax(0,1fr)]">
-        {/* Month scale, and Today above its line */}
-        <span aria-hidden />
-        <div aria-hidden className="relative h-11 text-2xs text-ink-3">
-          {months.map((m) => (
-            <span key={m.key} className="absolute bottom-1 truncate pl-1.5" style={{ left: pct(m.t), width: pct(lo + (m.next - m.t)) }}>{m.label}</span>
-          ))}
-          {now !== null && now >= lo && now < hi ? <span className="absolute top-0 z-10 -translate-x-1/2 rounded-xs bg-accent px-1 text-on-accent" style={{ left: pct(now) }}>Today</span> : null}
-        </div>
-
-        {heat ? (
-          <>
-            <span aria-hidden className="t-caption self-center truncate pr-3">{heatLabel}</span>
-            <div aria-hidden className="relative flex h-4 gap-px overflow-hidden rounded-xs">
-              {months.map((m) => (
-                <span key={m.key} className="h-full bg-accent" style={{ width: pct(lo + (m.next - m.t)), opacity: 0.12 + 0.88 * ((heat[m.key] ?? 0) / heatMax) }} title={`${m.label}: ${heat[m.key] ?? 0}`} />
-              ))}
-            </div>
-          </>
-        ) : null}
-
-        {groups.map((g) => (
-          <Fragment key={g || 'all'}>
-            {g ? (
-              <>
-                <span aria-hidden className="t-eyebrow col-span-2 pt-4 pb-1.5">{g}</span>
-              </>
-            ) : null}
-            {items.filter((it) => (it.group ?? '') === g).map((it) => {
-              const a = day(it.start), b = day(it.end) + DAY;
-              // A bar that reaches past a fixed window keeps its rounded end only where the work really ends. Squaring
-              // the side that continues is what says "this started before, or runs past" — without it the plan reads as
-              // if nothing was under way before the window opened, which is the opposite of what a roadmap is for.
-              const bar = (
-                <span
-                  className={cn('absolute top-1/2 h-2.5 -translate-y-1/2 rounded-full', TONE[it.tone ?? 'neutral'], a < lo && 'rounded-l-none', b > hi && 'rounded-r-none')}
-                  style={{ left: pct(a), width: `calc(${pct(lo + (Math.min(b, hi) - Math.max(a, lo)))} - 2px)`, minWidth: 6 }}
-                />
-              );
-              return (
-                <Fragment key={it.id}>
-                  {/* The label is the item's one link: visible, focusable, and read with the table's dates. */}
-                  {it.href ? (
-                    <Link href={it.href} title={it.label} className="row-link self-center truncate py-2 pr-3 text-ink-2 hover:text-accent-ink">{it.label}</Link>
-                  ) : (
-                    <span aria-hidden className="self-center truncate py-2 pr-3 text-ink-2" title={it.label}>{it.label}</span>
-                  )}
-                  <div aria-hidden className="relative h-9 border-b border-line" title={`${it.label}: ${LONG.format(a)} to ${LONG.format(b - DAY)}`}>
-                    <Guides />
-                    {bar}
-                  </div>
-                </Fragment>
-              );
-            })}
-          </Fragment>
-        ))}
-      </div>
-      <table className="sr-only">
-        <caption>{label}</caption>
-        <thead><tr><th>Item</th><th>Group</th><th>Start</th><th>End</th></tr></thead>
-        <tbody>
-          {items.map((it) => (
-            <tr key={it.id}>
-              <td>{it.label}</td>
-              <td>{it.group ?? ''}</td>
-              <td>{LONG.format(day(it.start))}</td>
-              <td>{LONG.format(day(it.end))}</td>
-            </tr>
-          ))}
-        </tbody>
-      </table>
-    </figure>
-  );
-}

package/payload/src/components/charts/timeline/preview.tsx

@@ -1,27 +0,0 @@
-'use client';
-
-import { Specimen, State } from '@/system/specimen';
-import { Timeline, type TimelineItem } from '.';
-
-const ROADMAP: TimelineItem[] = [
-  { id: 'r1', group: 'Platform', label: 'Regional failover', start: '2026-08-04', end: '2026-10-16', tone: 'accent' },
-  { id: 'r2', group: 'Platform', label: 'Rate limits per key', start: '2026-09-14', end: '2026-11-27' },
-  { id: 'r3', group: 'Platform', label: 'Gateway v5', start: '2026-11-02', end: '2027-01-29' },
-  { id: 'r4', group: 'Console', label: 'Alerts and on-call', start: '2026-07-20', end: '2026-09-04', tone: 'positive' },
-  { id: 'r5', group: 'Console', label: 'Usage-based billing', start: '2026-09-28', end: '2026-12-18', tone: 'warning' },
-  { id: 'r6', group: 'Assistants', label: 'MCP views for every page', start: '2026-10-05', end: '2027-01-15' },
-];
-const HEAT = { '2026-07': 2, '2026-08': 3, '2026-09': 5, '2026-10': 6, '2026-11': 5, '2026-12': 4, '2027-01': 2 };
-
-export default function TimelinePreview() {
-  return (
-    <>
-      <Specimen label="Roadmap" note="Bars run from start to end, grouped by workstream, on month hairlines; the accent line is today. The label column stays put; the plot is in percent, so it never scrolls sideways." stack>
-        <State label="With a heat row (projects in flight)" className="w-full"><Timeline items={ROADMAP} from="2026-07-01" to="2027-01-31" today="2026-10-03" heat={HEAT} heatLabel="In flight" label="Roadmap, July 2026 to January 2027" /></State>
-      </Specimen>
-      <Specimen label="Narrow" note="Under 512px the label column narrows to 7rem and month labels shorten; nothing scrolls.">
-        <State label="Phone width" className="w-90 max-w-full"><Timeline items={ROADMAP.slice(0, 3)} from="2026-08-01" to="2026-12-31" today="2026-10-03" label="Platform roadmap" /></State>
-      </Specimen>
-    </>
-  );
-}