zz-meridian 0.8.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

@@ -205,7 +205,48 @@ export const RELEASE_MIGRATIONS = [
         instructions: 'Read "Writes authorize, then invalidate" and "The assistant route" in references/cache.md. Call `resolveAccess()` first in the route and in each Server Action, answer 401 or an error result when there is no session, and hand the assistant only the collections the caller may read. The route passes a guard that authorizes each approved change again when it runs, so `src/lib/assistant/tools.ts` and `src/lib/assistant/respond.ts` take that guard too: bring them over from the release with the route.',
         checks: GATE_AND_BUILD,
     },
+    {
+        id: 'share-view-context',
+        since: '0.9.0',
+        applies: (root) => matching(root, (_, src) => callArity(src, 'useShareView').some((n) => n === 2)),
+        summary: 'useShareView takes one shared context, not a sentence and an object.',
+        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',
+        applies: pagesWithoutAgentReads,
+        summary: 'A page under app/(dashboard)/ or app/embed/ says what the agent reads.',
+        instructions: 'Read "A page spec" in references/customize.md. Under `## Agents` in the page\'s README.md, add `### What the agent reads`: what the page\'s shared context tells each agent, with a real line of it, and what the MCP App and the console\'s assistant each receive. `scripts/check.ts` requires it.',
+        checks: ['gate'],
+    },
 ];
+/** The page specifications under the console and embed folders that lack the part the 0.9.0 check requires. */
+function pagesWithoutAgentReads(root) {
+    const files = [];
+    for (const d of ['app/(dashboard)', 'app/embed'])
+        walk(root, d, files, /^README\.md$/);
+    const hits = files.filter((rel) => !/^## Agents\n[\s\S]*?^### What the agent reads$/m.test(text(root, rel) ?? ''));
+    return hits.length > 0 ? hits : null;
+}
 /** The registry entries that apply to a project moving from `source` to `target`, as journal migrations. */
 export function releaseMigrations(root, source, target) {
     const out = [];

package/dist/ownership.js

@@ -1,14 +1,14 @@
 const HASH = /^sha256-[0-9a-f]{64}$/;
 const SEMVER = /^\d+\.\d+\.\d+$/;
 /** The library modules Meridian's components and gates import; the rest of src/lib belongs to the template's pages. */
-export const LIB = ['cn', 'format', 'format-date', 'period', 'color', 'host', 'preferences', 'csv', 'safe-markdown', 'logo', 'collection', 'live'].map((n) => `src/lib/${n}.ts`);
+export const LIB = ['cn', 'format', 'format-date', 'period', 'color', 'host', 'preferences', 'csv', 'safe-markdown', 'logo', 'collection', 'live', 'shared-context', 'agent-guidance', 'insight'].map((n) => `src/lib/${n}.ts`);
 /** The single files adopt copies besides the folders and the library: all of them must be in a payload that is whole. */
 export const FIXED = [...LIB, 'src/lib/assistant/prompt.ts', 'src/views/console-chrome.tsx', 'tests/setup.ts'];
 /** The one rule, a plain-English line per clause. `references/ownership.md` renders it, so the guidance cannot drift. */
 export const OWNERSHIP = [
     'Managed: the payload files under `tokens/`, `src/styles/` and `src/components/`, except each component\'s `README.md` and `preview.tsx`.',
     'Managed: the distributed scripts under `scripts/`, except `scripts/verify.config.ts`, the first-load baseline `optional:scripts/verify.baseline.json` and a team-local `optional:scripts/check.local.ts`.',
-    'Managed: the library helpers `src/lib/cn.ts`, `src/lib/format.ts`, `src/lib/format-date.ts`, `src/lib/period.ts`, `src/lib/color.ts`, `src/lib/host.ts`, `src/lib/preferences.ts`, `src/lib/csv.ts`, `src/lib/safe-markdown.ts`, `src/lib/logo.ts`, `src/lib/collection.ts` and `src/lib/live.ts`, and the assistant prompt `src/lib/assistant/prompt.ts`.',
+    'Managed: the library helpers `src/lib/cn.ts`, `src/lib/format.ts`, `src/lib/format-date.ts`, `src/lib/period.ts`, `src/lib/color.ts`, `src/lib/host.ts`, `src/lib/preferences.ts`, `src/lib/csv.ts`, `src/lib/safe-markdown.ts`, `src/lib/logo.ts`, `src/lib/collection.ts`, `src/lib/live.ts`, `src/lib/shared-context.ts`, `src/lib/agent-guidance.ts` and `src/lib/insight.ts`, and the assistant prompt `src/lib/assistant/prompt.ts`.',
     'Managed: `src/views/console-chrome.tsx` and `tests/setup.ts`.',
     'Managed: `optional:scripts/package.json`, only when the adopt or create that set the project up generated it for this project shape.',
     'Managed: both installed skill trees, `optional:.agents/skills/zz-meridian/` and `optional:.claude/skills/zz-meridian/`, taken from the release\'s skill payload.',

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.8.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,57 @@
 
 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
+
+- **Every page tells both agents the same thing (decision 0011).** A view builds one shared context (`src/lib/shared-context.ts`, one producer per page in `src/views/*-context.ts`): its scope and freshness, what the person points at, every figure with its unit, its change and its definition, what code computed from them (`src/lib/insight.ts`: a day against its median, a share, a ranking, a run of days, what nothing recorded explains), and what the data cannot say. An MCP host receives it through `ui/update-model-context`, inline and in fullscreen; the console's assistant receives it in its prompt, with the page's address and query. All nine console pages and the four embed views share one.
+- **Every view has a tool.** `src/views/tools.ts` holds each view's contract: its name, its address as input, its `ui://` resource, and one read that returns what it renders and what the agents are told. The console's assistant offers each as a read-only `view_<name>`; `docs/agents.md` registers the same list on an MCP server, with the apply tool of a change registered view-only. The embed routes render from their tool's read.
+- **The assistant is told its limits.** Its prompt lists what it cannot do or see, from each collection's `pageOnly`, `hidden` and missing operations, so it can say why.
+- **Ask hands a card to the console's assistant.** With the assistant on, Ask appears on the featured card of Overview, Requests, Health and Analytics; a press opens the panel and sends the card's question with the page's context (`ConsoleSurface`). Ask renders only after hydration.
+- **An MCP view says when the host refuses.** A refused context is sent once more, and Ask then carries the view's address; a refused Ask tells the person in a toast with the question's words.
+- **The person sees the findings.** `MetricTile` takes `finding` (a line, with a day it points the Meridian there) and `baseline` ("2.7× usual" beside a day being read); `TrendChart` takes `baseline`, a dashed median line. The Overview uses all three.
+- **An agent's change leaves an Activity line.** The assistant's guard takes an optional `record`; the template writes to a new `activity` collection, and the Overview's Activity is live.
+- **The Overview, Analytics and Health read through `read()`.** Daily totals, endpoints, responses, services, incidents and activity are read-only collections (`src/data/metrics.ts`).
+- **An address can name a day.** `?day=2026-09-22` opens the Overview pointed at it (`Meridian day`).
+
+### Breaking
+
+`update` reports the two that touch the team's own files as migrations, `share-view-context` and `agent-reads-section`, with what to change (`references/update.md`, "Resolving 0.9.0's migrations"); `src/lib/shared-context.ts`, `src/lib/agent-guidance.ts` and `src/lib/insight.ts` are Meridian's now and arrive with the update.
+
+- `useShareView(text, structured)` is `useShareView(context)`. Build a context with the fields in `SharedContext`; `contextText` writes the text both agents read.
+- `scripts/check.ts` requires `### What the agent reads` under `## Agents` in the README of every page under `app/(dashboard)/` and `app/embed/`. Add it to a product's own pages, saying what the page's context tells each agent.
+- `src/data/sample.ts` no longer exports `ENDPOINTS`, `STATUS_MIX`, `ACTIVITY`, `INCIDENTS`, `PAST_INCIDENTS`, `SERVICES` or `demoTotals`: read them through `src/data/metrics.ts`. `RequestView` takes `routeP95`.
+- `OverviewBody`, `HealthBody` and `AnalyticsBody` take the period key, `updatedAt` and, for the first and last, the incidents and activity beside the figures; `RequestsView` takes `updatedAt` and `now`.
+
 ## [0.8.0] · 2026-10-06
 
 ### Added

package/payload/CONTRIBUTING.md

@@ -39,7 +39,7 @@ Every card's README follows the same order, so a reader always knows where to lo
 4. **States**: rest, hover, pressed, focus, selected, disabled, loading, empty, error, each with its transition (property, duration token, curve).
 5. **Behaviour**: interaction, keyboard, timing.
 6. **Surfaces**: console, mobile (under 1024px) and embed (an MCP App): what changes on each, or "same", and why.
-7. **Agents**: what an agent may read here, what it may do (and through which proposal), and how its work is marked. Write "Not applicable" for purely presentational parts.
+7. **Agents**: what an agent may read here, what it may do (and through which proposal), and how its work is marked. Write "Not applicable" for purely presentational parts. A page or a view that shares a context (`useShareView`, decision 0011) adds **What the agent reads** under it: what its context says, with a real line of it, and what each consumer receives (the MCP App through `ui/update-model-context`, the console's assistant in its prompt).
 8. **Accessibility**: roles, names, keyboard, and contrast quoted from `node scripts/contrast.ts --all` (the dark theme and the indigo accent, the defaults; add light where it differs in kind).
 9. **Content**: copy rules with real strings.
 10. **Do and do not.**
@@ -75,6 +75,7 @@ Write the status on the line under the title: `Status: beta`.
 - Under reduced motion it shows its final state with nothing moving.
 - Keyboard: every control reachable, operable and visibly focused; focus order follows reading order.
 - An agent's work in it is marked (Agent mark, "via" attribution, or a Proposal); no agent write happens without one.
+- A page shares a context both agents read: its scope and freshness, every figure with its unit, change and definition, what code derived from them, and what the data cannot say, within 2,400 characters. A figure an agent would otherwise recompute is computed in the context.
 
 ## Tools
 
@@ -84,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
 
@@ -41,7 +41,24 @@ From `src/system/fixtures/sample.ts`: `demoSeries(period)` (one point per day, a
 
 ## Agents
 
-The embed view shares the period and its totals, or the day the Meridian points at, with the model. Ask on the trend posts "Why did requests change on <day>?". The Activity feed marks the agent's own changes ("Claude … · for Jonas Weber").
+The page shares one context with both agents (decision 0011), built by `overviewContext` in `src/views/overview-context.ts` from the figures the page draws. The Activity feed marks the agent's own changes ("Claude … · for Jonas Weber").
+
+### What the agent reads
+
+The period with its dates, freshness, the four figures, each with its change against the previous period and its definition (the tiles' `hint`s come from the same `OVERVIEW_METRICS`), the day the Meridian points at against the same weekday and the period's median, and what code computed:
+
+```text
+- Error rate was 2.6× to 2.7× the period's median of 0.81% on 21 and 22 Sept (2.13%, 2.18%); no other day passed 1.2×.
+- Latency p95 rose on the same days: 525ms and 505ms against a median of 296ms.
+Unknown:
+- Nothing is recorded between 20 Sept and 23 Sept: no incident and no activity event, so nothing on this page explains the rise on 21 and 22 Sept.
+```
+
+It also says which endpoint contributes most errors, that requests follow the week, what the status classes mean against the error rate's definition, which incident sits beside a spike when one does (in 90 days: "Upload failures for files over 50 MB"), and that today is partial.
+
+- **MCP App:** the text above as `ui/update-model-context`, with the same context as its structured part, from the inline view and from fullscreen alike, on load and on every change.
+- **Console assistant:** the same text in its prompt's `<view-context>` block, with the page's address and query, and the page text after it for anything the context does not cover.
+- **Handoff:** Ask on the featured card hands the period, or the day the Meridian points at, to the assistant: "What stands out in requests, errors and latency over the last 30 days, and why?"
 
 ## Embed view
 

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

@@ -5,15 +5,20 @@ import { Freshness } from '@/components/patterns/freshness';
 import { PeriodSelect } from '@/components/patterns/period-select';
 import { Skeleton } from '@/components/ui/skeleton';
 import { OverviewBody } from '@/views/overview';
-import { DEMO_NOW, DEMO_UPDATED_AT, demoSeries, demoTotals, ENDPOINTS, STATUS_MIX, ACTIVITY } from '@/data/sample';
-import { parsePeriod, PERIOD_LABEL } from '@/lib/period';
+import { DEMO_NOW, DEMO_UPDATED_AT } from '@/data/sample';
+import { overviewTool } from '@/views/tools';
+import { cache } from 'react';
+import { parsePeriod } from '@/lib/period';
 import { app } from '@/app.config';
 import { Busy } from '../_loading';
 import { OverviewSkeleton } from './loading';
 
 export const metadata = { title: 'Overview' };
 
-type SearchParams = Promise<{ period?: string }>;
+type SearchParams = Promise<{ period?: string; day?: string }>;
+
+/** The page's one read, through the Overview tool (`src/views/tools.ts`), shared by the export and the body. */
+const readPeriod = cache((period: ReturnType<typeof parsePeriod>, day?: string) => overviewTool.read({ period, day: /^\d{4}-\d{2}-\d{2}$/.test(day ?? '') ? day : undefined }));
 
 /** The masthead renders at once; the period select, the export and the body read the address inside their own boundaries. */
 export default function OverviewPage({ searchParams }: { searchParams: SearchParams }) {
@@ -38,15 +43,17 @@ export default function OverviewPage({ searchParams }: { searchParams: SearchPar
 
 async function Actions({ searchParams }: { searchParams: SearchParams }) {
   const period = parsePeriod((await searchParams).period);
+  const { data } = await readPeriod(period);
   return (
     <>
       <Suspense><PeriodSelect value={period} /></Suspense>
-      <ExportButton rows={demoSeries(period).current} filename={`overview-${period}.csv`} noun="days" className="max-sm:hidden" />
+      <ExportButton rows={data.series} filename={`overview-${period}.csv`} noun="days" />
     </>
   );
 }
 
 async function Body({ searchParams }: { searchParams: SearchParams }) {
-  const period = parsePeriod((await searchParams).period);
-  return <OverviewBody period={PERIOD_LABEL[period].toLowerCase()} series={demoSeries(period).current} totals={demoTotals(period)} endpoints={ENDPOINTS} mix={STATUS_MIX} activity={ACTIVITY} now={DEMO_NOW.toISOString()} />;
+  const { period, day } = await searchParams;
+  const { data } = await readPeriod(parsePeriod(period), day);
+  return <OverviewBody {...data} />;
 }

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

@@ -39,7 +39,19 @@ Status: beta
 
 ## Agents
 
-Not applicable: an agent answers analytical questions from the Overview and Requests views' shared context and the API, not by driving this page.
+An agent drives nothing here; it reads the page through its shared context (decision 0011), built by `analyticsContext` in `src/views/analytics-context.ts`.
+
+### What the agent reads
+
+The period, freshness, the busiest hour of the week and of the day, each region's share with its p50, every endpoint in the table's current order, the day the Meridian points at, and what code found: the same error spike as the Overview (by the same code), the slowest and the most failing endpoint against the median, the slowest region, and the weekend's share of a weekday. It says that the weekday-and-hour pattern, the regions and the endpoints are sums over the period, not a day.
+
+```text
+- POST /v1/files fails most: 1.88% of its requests, 5.0× the 0.37% across endpoints. Evidence: /requests?q=%2Fv1%2Ffiles
+```
+
+- **Console assistant:** this text in its prompt's `<view-context>` block, with the page's address and query, and the page text after it for anything the context does not cover.
+- **MCP App:** no embed view yet; an MCP server can return this context as a tool's text (`docs/agents.md`).
+- **Handoff:** Ask on Errors per day hands the pointed day, or the period, to the assistant: "Why did errors change on 22 Sept 2026?"
 
 ## Accessibility
 

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

@@ -6,7 +6,9 @@ import { Freshness } from '@/components/patterns/freshness';
 import { PeriodSelect } from '@/components/patterns/period-select';
 import { Skeleton } from '@/components/ui/skeleton';
 import { AnalyticsBody } from '@/views/analytics';
-import { DEMO_NOW, DEMO_UPDATED_AT, ENDPOINTS, demoHeatmap, demoSeries, REGION_LATENCY, requestsByHour } from '@/data/sample';
+import { DEMO_NOW, DEMO_UPDATED_AT } from '@/data/sample';
+import { analyticsTool } from '@/views/tools';
+import { cache } from 'react';
 import { parsePeriod } from '@/lib/period';
 import { Busy } from '../_loading';
 import { AnalyticsSkeleton } from './loading';
@@ -36,17 +38,21 @@ export default function AnalyticsPage({ searchParams }: { searchParams: SearchPa
   );
 }
 
+/** The page's one read, through the Analytics tool (`src/views/tools.ts`), shared by the export and the body. */
+const readPeriod = cache((period: ReturnType<typeof parsePeriod>) => analyticsTool.read({ period }));
+
 async function Actions({ searchParams }: { searchParams: SearchParams }) {
   const period = parsePeriod((await searchParams).period);
+  const { data } = await readPeriod(period);
   return (
     <>
       <Suspense><PeriodSelect value={period} /></Suspense>
-      <ExportButton rows={demoSeries(period).current} filename={`analytics-${period}.csv`} noun="days" className="max-sm:hidden" />
+      <ExportButton rows={data.series} filename={`analytics-${period}.csv`} noun="days" />
     </>
   );
 }
 
 async function Body({ searchParams }: { searchParams: SearchParams }) {
-  const period = parsePeriod((await searchParams).period);
-  return <AnalyticsBody series={demoSeries(period).current} heat={demoHeatmap()} hours={requestsByHour()} regions={REGION_LATENCY} endpoints={ENDPOINTS} />;
+  const { data } = await readPeriod(parsePeriod((await searchParams).period));
+  return <AnalyticsBody {...data} />;
 }

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

@@ -39,7 +39,18 @@ None yet: a `zz_meridian_customer { name }` view would show one customer's card
 
 ## Agents
 
-An agent reads customers through their requests view; it never changes a plan or invites from here.
+An agent reads customers through this page's shared context and their requests view; it never changes a plan or invites from here. The context is built by `customersContext` in `src/views/customers-context.ts`, and the tiles' `hint`s come from its `CUSTOMER_METRICS`.
+
+### What the agent reads
+
+The three tiles with their definitions, every customer in the table's filter and order (with the columns a narrow screen drops: the error rate and the trend are still the person's to read), and what code found: how concentrated spend is, how combined requests moved over the last 7 days against the 7 before and who departs from that by 10 points or more, and which customers fail at twice the median rate. Lists stop at 25 and say how many more there are.
+
+```text
+- Combined requests are up 15% over the last 7 days against the 7 before. Apart from that: Fernway Bank up 36%.
+```
+
+- **Console assistant:** this text in its prompt's `<view-context>` block, with the page's address and query, and the page text after it for anything the context does not cover.
+- **MCP App:** no embed view yet; an MCP server can return this context as a tool's text (`docs/agents.md`).
 
 ## Content
 

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

@@ -42,7 +42,15 @@ Without a live incident row 1 becomes one full-width featured card.
 
 ## Agents
 
-The page itself takes no agent action. Its embed shares the summary and the open incident with the model; an agent can be asked about the incident from the inline banner.
+The page itself takes no agent action. It shares one context with both agents (decision 0011), built by `healthContext` in `src/views/health-context.ts`.
+
+### What the agent reads
+
+Every service's state, latency now and uptime; the average uptime with its definition; which services carry the days below operational ("Inference API accounts for 3 of them"); the open incident with its latest update by time, not by position; the longest incident resolved in the period. Unknowns: that a monitoring incident is not yet confirmed fixed, and that latency is one reading with no history to call it unusual.
+
+- **MCP App:** the text above as `ui/update-model-context`, with the same context as its structured part, from the inline view and from fullscreen alike, on load and on every change.
+- **Console assistant:** the same text in its prompt's `<view-context>` block, with the page's address and query, and the page text after it for anything the context does not cover.
+- **Handoff:** Ask on the uptime card hands the open incident to the assistant: "Which service is hurting uptime, and is … over?"
 
 ## Embed view
 

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

@@ -2,22 +2,23 @@ import { app } from '@/app.config';
 import { PageFrame } from '@/components/base/shell';
 import { Freshness } from '@/components/patterns/freshness';
 import { PackedHealthBody, SubscribeButton } from '@/views/health';
+import { healthTool } from '@/views/tools';
 import { packServices } from '@/components/patterns/status-list/summarise';
-import { DEMO_NOW, DEMO_UPDATED_AT, INCIDENTS, SERVICES, PAST_INCIDENTS } from '@/data/sample';
 
 export const metadata = { title: 'Health' };
 
-export default function HealthPage() {
-  const current = INCIDENTS.find((i) => i.state !== 'resolved') ?? null;
+/** Rendered from the Health tool's own read (`src/views/tools.ts`): the services and incidents the caller may read. */
+export default async function HealthPage() {
+  const { data } = await healthTool.read({});
   return (
     <PageFrame
       kicker={<>{app.name} · {app.workspace}</>}
       title="Health"
       description="Every service, how it is right now, and what happened in the last 90 days."
-      meta={<Freshness updatedAt={DEMO_UPDATED_AT} now={DEMO_NOW} />}
+      meta={<Freshness updatedAt={new Date(data.updatedAt)} now={new Date(data.now)} />}
       actions={<SubscribeButton />}
     >
-      <PackedHealthBody services={packServices(SERVICES)} current={current} past={PAST_INCIDENTS} now={DEMO_NOW.toISOString()} />
+      <PackedHealthBody {...data} services={packServices(data.services)} />
     </PageFrame>
   );
 }

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

@@ -41,7 +41,14 @@ Not offered. Keys are secrets, and creating one is a page-only operation. In the
 
 ## Agents
 
-An agent may say which keys are unused (from the shared context of other views) and may propose revoking a key (a critical Proposal); it never creates one. The proposal waits for approval, and its approval removes the key through the same collection.
+An agent may propose revoking a key (a critical Proposal); it never creates one, because a key's secret is shown once, on this page (`pageOnly`). The proposal waits for approval, and its approval removes the key through the same collection. The page shares its context through `keysContext` in `src/views/keys-context.ts`.
+
+### What the agent reads
+
+Every key with its id, environment, hint (the first and last characters, never the secret), owner, scopes, when it was created and last used, and what code found: live keys unused for 30 days, live keys with every scope, and an owner holding several live keys. The secret and its hash are never in it (`secretHash` is `hidden`), and the context says so, with the rule that creating a key is the person's.
+
+- **Console assistant:** this text in its prompt's `<view-context>` block, with the page's address and query, and the page text after it for anything the context does not cover.
+- **MCP App:** no embed view yet; an MCP server can return this context as a tool's text (`docs/agents.md`).
 
 ## Content
 

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

@@ -42,7 +42,18 @@ Not offered. Inviting and removing people are decisions for the console, not a c
 
 ## Agents
 
-The assistant reads and proposes changes here through Proposals: it adds, changes and removes members only after a person approves, and what it changed shows on this page after a refresh. A change made here is what the assistant reads next.
+The assistant reads and proposes changes here through Proposals: it adds, changes and removes members only after a person approves, and what it changed shows on this page after a refresh. A change made here is what the assistant reads next. The page shares its context through `membersContext` in `src/views/members-context.ts`.
+
+### What the agent reads
+
+Counts by status, role (with what each role may do) and team, everyone with their role, team, status and when they were last seen (25 at most; `query_members` finds the rest), and what code found: active members unseen for 60 days or more, unanswered invitations, and who can change the workspace. It says that "last active" is a console sign-in, not use of the API.
+
+```text
+- 3 active members have not been seen for 60 days or more: Alice Moreno (Viewer, Support, 94 days), Felix Andersson (Viewer, Engineering, 75 days), Ravi Patel (Viewer, Support, 71 days).
+```
+
+- **Console assistant:** this text in its prompt's `<view-context>` block, with the page's address and query, and the page text after it for anything the context does not cover.
+- **MCP App:** no embed view yet; an MCP server can return this context as a tool's text (`docs/agents.md`).
 
 ## Content
 

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
 
@@ -51,7 +51,21 @@ Export CSV is a link to `/api/export/requests` with the same filters and sort: t
 
 ## Agents
 
-An agent opens this page's views through `zz_meridian_requests`; it reads them through the shared context; it never exports or blocks from here. Its filters are marked until a person changes one.
+An agent opens this page's views through `zz_meridian_requests`; it never exports or blocks from here. Its filters are marked until a person changes one. The page shares one context with both agents (decision 0011), built by `requestsContext` in `src/views/requests-context.ts` from the page's read: the rows on screen and the summary of the whole filtered set.
+
+### What the agent reads
+
+The filters in words and the span of time the log covers; freshness; the three figures with their change against the half hour before and their definitions (the tiles' `hint`s come from `REQUEST_METRICS`); the page, the sort and the rows on screen by id; and what the matching requests and their errors have in common:
+
+```text
+- 5 of the 9 errors and limits are in eu-west-1 (56%). Evidence: /requests?region=eu-west-1
+```
+
+When a half hour holds fewer than 30 requests it says the change is too few to read as a trend, and when the summary reads only the newest 500 it says so.
+
+- **MCP App:** the text above as `ui/update-model-context`, with the same context as its structured part, from the inline view and from fullscreen alike, on load and on every change.
+- **Console assistant:** the same text in its prompt's `<view-context>` block, with the page's address and query, and the page text after it for anything the context does not cover.
+- **Handoff:** Ask in the filter bar hands the filtered set to the assistant: "What do these requests with status 5xx have in common, and why?"
 
 ## Accessibility
 

package/payload/app/(dashboard)/requests/[id]/README.md

@@ -41,7 +41,18 @@ None of its own. An agent shows a request through `zz_meridian_requests` (inline
 
 ## Agents
 
-Replay and blocking a key are a person's actions here. An agent that wants either sends a Proposal.
+Replay is a person's action here: it is `pageOnly`, so no agent can run or propose it. The page shares its context through `requestContext` in `src/views/request-context.ts`.
+
+### What the agent reads
+
+The request, its status, latency (with its definition), customer and region, every phase with its start and duration, the payloads' sizes (their text is in the page text), and what code found: where most of the time went, the latency against the route's p95, and, for a failed request, that it counts in the error rate. It says that one request is one sample, and that replaying it is the person's.
+
+```text
+- Most of its time went to Rate limit (Over 1,200 requests a minute): 159ms, 93% of 171ms.
+```
+
+- **Console assistant:** this text in its prompt's `<view-context>` block, with the page's address and query, and the page text after it for anything the context does not cover.
+- **MCP App:** no embed view yet; an MCP server can return this context as a tool's text (`docs/agents.md`).
 
 ## Accessibility
 

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

@@ -1,4 +1,5 @@
 import { read } from '@/data/read';
+import { readEndpoints } from '@/data/metrics';
 import { FEATURED_REQUEST_IDS, traceOf, payloadsOf, type RequestRow } from '@/data/sample';
 import { MissingPage } from '@/views/missing-page';
 import { RequestView } from '@/views/request';
@@ -23,5 +24,6 @@ export default async function RequestPage({ params }: { params: Promise<{ id: st
   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 />;
-  return <RequestView request={r} trace={traceOf(r)} payloads={payloadsOf(r)} now={observedAt} replay={replayRequest} />;
+  const route = (await readEndpoints()).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} replay={replayRequest} />;
 }

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

@@ -65,6 +65,6 @@ async function RequestsExport({ searchParams }: { searchParams: SearchParams })
 }
 
 async function Requests({ searchParams }: { searchParams: SearchParams }) {
-  const { rows, total, summary, state } = await readPage(await searchParams);
-  return <RequestsView rows={rows} total={total} summary={summary} state={state} pageSize={REQUEST_PAGE} />;
+  const { rows, total, summary, state, observedAt } = await readPage(await searchParams);
+  return <RequestsView rows={rows} total={total} summary={summary} state={state} pageSize={REQUEST_PAGE} updatedAt={DEMO_UPDATED_AT.toISOString()} now={observedAt} />;
 }

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

@@ -42,6 +42,13 @@ Appearance reads and writes `usePreferences()` (stored on the device). Time zone
 
 This is where people govern agents: whether assistants may read, which are connected, and the rule (locked on) that nothing an agent proposes runs without approval, a removal included. The assistant section, shown only where the product has an assistant, holds the person's switch for its panel.
 
+### What the agent reads
+
+Every section's current values, which neither an input's nor a switch's text carries: the workspace's name, address and time zone (and an unsaved edit, when there is one), each notification switch, this device's theme, accent and density, whether the assistant is shown, whether assistants may read dashboards and which are connected with what they may do, and that deleting the workspace is typed, never proposed. Each section reports its own line; `SettingsBody` shares them as one context. None is offered to an agent as a change, and the context says so.
+
+- **Console assistant:** this text in its prompt's `<view-context>` block, with the page's address and query, and the page text after it for anything the context does not cover.
+- **MCP App:** no embed view yet; an MCP server can return this context as a tool's text (`docs/agents.md`).
+
 ## Accessibility
 
 - Each section is a form with its own submit; switches carry their label and description.