zz-meridian 0.9.0 → 0.11.0

package/README.md

@@ -9,7 +9,15 @@ dashboard depends on it afterwards.
 Give your coding agent (Codex, Claude Code, or any agent that can run a shell) this, with what you want in your own
 words at the end:
 
-> Run `npx zz-meridian@latest skill --global`, then follow the zz-meridian skill it installs to: [what you want, in your own words].
+> Run `npx zz-meridian@latest skill --global`, then follow the zz-meridian skill it installs to: [what you want, in your own words]. Done when its hand-over says the Meridian standard is met, or names what only I can decide or provide.
+
+In Claude Code or Codex, send it as a goal (`/goal Run npx zz-meridian@latest skill --global, then …`): the agent keeps
+working until the condition holds, and a separate model checks it after every turn against the hand-over, which quotes
+its evidence. The sentence says what you want; the skill carries how good it has to be. It builds, renders every view
+at phone and desktop width in both themes, scores each one on a scoreboard of floors (measured by `pnpm verify --full`)
+and craft (judged on the renders), and improves it round by round until nothing is weak, deciding what it can find out
+and recording each decision it made for you. You get the finished product, the renders, and the few questions only you
+can answer.
 
 The skill picks the command from what you said and what is in the folder, and names it before running anything:
 `adopt` to change this Next.js App Router project in place ("make this admin panel look professional"), `create` for a

package/dist/adopt.js

@@ -324,7 +324,8 @@ Meridian ${VERSION} is in ${root}.
   agent context: AGENTS.md has the managed block; docs/brief.md ${briefWritten ? 'is the empty brief to fill in' : 'was kept as it is'}
   types: ${typed}${notes.length ? `\n  notes:\n${notes.map((n) => `    - ${n}`).join('\n')}` : ''}
 
-Next: follow .agents/skills/zz-meridian/references/existing-project.md, Route A, from step 2 (step 1 was this). The
+Next: follow .agents/skills/zz-meridian/references/existing-project.md, Route A, from step 2 (step 1 was this), to the
+standard in references/standard.md. The
 template to read from is https://github.com/zhixuan312/zz-meridian/tree/v${VERSION}. Import Meridian's components as
 '@meridian/components/…'. Before the first ${pm} run verify, read step 5: verify presses every control, Delete included.`);
     return 0;

package/dist/cli.js

@@ -103,7 +103,9 @@ function main() {
         const roots = values.global ? [os.homedir()] : [process.cwd()];
         for (const r of roots)
             installSkill(r);
+        const skill = path.join(roots[0], '.claude/skills/zz-meridian/SKILL.md');
         console.log(`The zz-meridian skill is in ${values.global ? path.join(os.homedir(), '.agents/skills') + ' and ' + path.join(os.homedir(), '.claude/skills') : '.agents/skills and .claude/skills'}. Codex may need a restart to list it.`);
+        console.log(`To follow it now, read ${skill} and the references beside it: it says how to build what was asked and when it is done.`);
         return 0;
     }
     console.error(`zz-meridian: unknown command "${command}"\n\n${HELP}`);

package/dist/create.js

@@ -76,8 +76,9 @@ export function create(o) {
 ${name} is a new Meridian ${VERSION} dashboard in ${root}.
   skill: .agents/skills/zz-meridian (Codex) and .claude/skills/zz-meridian (Claude Code)
 
-Next: follow .agents/skills/zz-meridian/SKILL.md from step 5 (the template is fetched and branded): data first, then
-the pages, then ${pm} run verify until it passes.`);
+Next: follow .agents/skills/zz-meridian/SKILL.md from step 3's brief (the template is fetched and branded): the brief,
+step 4's colour check, then data and the pages, then the loop in references/standard.md until ${pm} run verify --full ends with "the project meets the
+Meridian standard" and no view on the scoreboard is Weak.`);
     return 0;
 }
 function fail(msg) {

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) });
@@ -296,9 +307,13 @@ export function start(ctx, o) {
             return refuse(`updates start from 0.3.0; this project is on ${manifest.version}`);
         if (!/^\d+\.\d+\.\d+$/.test(ctx.version))
             return refuse(`the running version ${JSON.stringify(ctx.version)} must look like 1.2.3`);
-        if (!isNewer(ctx.version, manifest.version)) {
-            return refuse(manifest.version === ctx.version ? `already at ${ctx.version}` : `this project is on ${manifest.version}, newer than this package (${ctx.version}); run npx zz-meridian@latest update`);
+        // Already current is not a refusal: there is nothing to do, and the run that asked has its answer.
+        if (manifest.version === ctx.version) {
+            log(`zz-meridian update: already at ${ctx.version}; nothing to update`);
+            return 0;
         }
+        if (!isNewer(ctx.version, manifest.version))
+            return refuse(`this project is on ${manifest.version}, newer than this package (${ctx.version}); run npx zz-meridian@latest update`);
         const git = spawn('git', ['status', '--porcelain'], root, true);
         const dirty = git.status === 0 ? (git.stdout ?? '').split('\n').filter(Boolean).length : 0;
         if (o.dryRun) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "zz-meridian",
-  "version": "0.9.0",
+  "version": "0.11.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,69 @@
 
 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.11.0] · 2026-10-08
+
+### Added
+
+- **The standard the sentence never states.** The skill's `references/standard.md` holds what one sentence leaves out: the register a product UI answers to, the defaults that read as generated, and a scoreboard kept in `out/standard/` for every view. The scoreboard has floors measured by `pnpm verify --full`, and craft judged on renders at 1440 and 390px in both themes (fit, hierarchy, typography, whitespace, colour, motion, responsive, navigation, copy, states, agents, originality). The agent runs the loop until `--full` ends with `the project meets the Meridian standard` and no view is Weak. Mechanical questions it settles itself; judgment calls it records with a recommendation, proceeding when cheap to reverse. Push, release, deploy, production data and the feedback issue wait for a yes.
+
+- **How the skill is evaluated.** `docs/skill-evals.md`: four levels by cost (static checks every change; decision probes, an agent reading the skill in a scenario's folder and stopping before the first write, for a change to the route, the decisions or the standard; planted defects for a change to the loop; end to end weekly), seven scenarios with what a right answer does, and how a finding is counted. Two fixture apps for them in `cli/test/`: `fixture-crumb-ops` (Next.js App Router over its own orders API, with server actions that delete) and `fixture-vite-rota` (Vite and React Router, one browser read); neither ships.
+
+- **One protagonist is a rule, not only a judgement.** `check.ts` fails a file that renders a second `FeaturedMetric`. A planted second one went unscored when an agent judged the renders by eye.
+- **The console's rail takes the request's data from the layout.** `ConsoleRail` passes its props through (`user`, `signOut`, `workspace`, `scopes`) and both it and `ConsolePalette` take `only`, the hrefs a person may see. A product filtered `nav` or set its session's person by editing `src/views/console-chrome.tsx`, a file Meridian manages; a console with no sign-in showed the sample person and a Sign out to nowhere. Now the team's own layout passes them.
+- **`shot.ts --press "<name>"`** opens a dialog, sheet, menu or popover before the shot, with the mouse, as a person does; repeated, it presses in order. A view that only a press shows can now be rendered and scored.
+
+### Changed
+
+- **An update already on the running version has nothing to do, and says so.** `update` and its dry run print `already at <version>; nothing to update` and exit 0, where they refused with exit 1 as if something were wrong.
+- **The sentence ends with its condition, and is meant for `/goal`.** `… to: [what you want]. Done when its hand-over says the Meridian standard is met, or names what only I can decide or provide.` The model a goal uses to check the work reads the sentence and the transcript, never the skill, so the hand-over quotes verify's last line, the coverage line, the scoreboard count, the decisions made, what did not run, and the commits.
+- **The skill decides from its drafts instead of asking.** Step 2 turns the homework into recorded decisions; the one question left is the route, when two fit. A brand hue too near a status hue moves to the nearest safe hue, with the brand kept in the logo mark. A missing tool no longer stops the build: what cannot run is reported as not run, and the standard as not yet proven.
+- **`skill` prints the path to read.** After installing, it names the `SKILL.md` to read now, since a running agent may not list a skill installed mid-session.
+
+### Fixed
+
+- **What the agents are told about freshness names the right zone.** `freshnessOf` wrote the time in the product's reporting zone and labelled it "UTC", so a product in Asia/Singapore told both agents that 17:30 local was 17:30 UTC. It names `app.timezone`.
+- **An amount keeps one precision.** `formatCost` gave two decimals under 1,000 and none above, so a column read "$997.00" over "$1,269"; it gives two at every size ("$1,269.40"). `formatCostCompact` stays for dense tiles.
+- **The gate reads an adopted project's imports.** `check.ts` took `@/` to mean `src/`, so in an adopted project, where `@/` is the team's root and Meridian is `@meridian/`, every module imported the documented way read as dormant ("exports X, which nothing a product keeps imports"), and a project had to rewrite its imports as relative paths to pass. It now resolves imports through the project's tsconfig `paths` (`scripts/lib/aliases.ts`).
+- **verify reports a bad configuration instead of crashing on it.** An early exit (a `navigationChecks` or `smokeRoutes` entry naming a route that is gone) threw `Cannot access 'suites' before initialization` and hid the reason; it now prints each configuration failure and the coverage line.
+- **The coverage line says which suites failed.** A suite that ran and failed was listed under `not run`, as if skipped; it is now `failed: <suites>`, after `not run`.
+- **A phone card's status and facts stay in their place.** The status badge took one of the card's six tracks, narrower than a badge at 390px, so it ran left over a long title and sat short of the card's edge; it takes two, as the layout meant. A long fact ends in an ellipsis instead of running over the fact beside it. The sample's customer column caps its width, so a long name no longer pushes the Requests table past its card at 1440px.
+- **A product can reach "the project meets the Meridian standard".** The assistant walk-through and the live checks drove the template's own sample pages (Overview, Members, API keys, Settings), so a product that replaced them — every product the skill builds — failed the walk-through or ended `not run: live`, and `--full` could never print the outcome its stop condition asks for. The walk-through now checks what every product shares on its own rail: no agent control while off, on every rail route and embed view, 12 in the template where it was 8; the panel, a reply, the page the model was told, markdown, the thread across navigation, Clear, the layout, a refused key, the key never reaching the browser. It drives each sample page only while its files are there (`scripts/lib/sample.ts`), printing `n/a` with the reason otherwise; Meridian's own repository, which has every one, walks all of them. Without the sample Members page, verify prints `n/a live data` instead of running the live checks, and it no longer counts against the outcome; a product's own live pages prove themselves through `browserChecks`.
+- **The skill names what its route needs, from what the probes met.** `create .` works in an empty folder; timezone, currency and the meaning of the request's own terms are recorded decisions; a view's verdict is its lowest criterion; the error state without a fake API is shown by making the read throw for one render. An update already on the running version stops there. The `optional:` and `example:` path prefixes are explained, a project's own copy of the skill is the one to follow, and Route A2 no longer names a `--product` flag `create` does not have. An existing product is learned first, its production addresses found before anything runs, its pages shot "before", and what must survive listed as a floor; Route B renders its "before" from a copy, and a read moved from the browser to the server carries neither cookies nor CORS. `create` and `adopt` end by pointing at the standard, not at `verify` passing. From the second round: the last round needs no round after it; originality comes from how asked-for content is shown, never from adding content; a view's states are scored under it and the shell is one row; the dev server is stopped by its own process id; the rail's signed-in person is never the sample's; an API address overrides `.env` through the environment and is not a `dataUrls` entry; a rebrand that lands near a status hue runs `brand` again with the nearest safe hue. From a built brownfield run and a planted-defect run: an adopted project turns on Cache Components and wraps its shell in `<Suspense>` when detail ids come at request time; a product formatter lives in a file of its own, and a Meridian file it must change goes in the keep register; the theme default is set through `brand --theme`; a navigation probe works at 390px; a request to evaluate only has a route of its own; a criterion not yet judged is not a pass. From the built greenfield run: `create` points at step 3's brief, not step 5; a page specification has a shape to start from; the shared context's 2,400-character budget is stated; the dev server is started as Next itself, so stopping its id stops it. From a third round of decision probes: the existing-project route starts with "Before you change anything", not with `adopt`; Cache Components means `partialPrefetching` too; a render server in a project with a fake API is started with its address; an npm project passes flags after `--`; a currency is evidence of the zone; a browser-fetching app's "before" needs a time budget and a fake API that allows its origin; Route B's new project takes Route A's verify steps.
+- **The skill's screenshots reach the dev server.** Step 6 started `pnpm dev`, on port 3000, then ran `scripts/shot.ts`, which reads port 3100. It now starts `pnpm dev --port 3100`.
+
+### Breaking
+
+- **`formatCost` prints cents at every size.** An amount of 1,000 or more reads "$1,269.40" where it read "$1,269". A product that pinned the old string in a test, or laid a column out for the shorter figure, updates it; `formatCostCompact` is the short form.
+
+## [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/README.md

@@ -72,8 +72,8 @@ Dark is the default, written on `:root`; the light theme follows the operating s
 | `docs/` | Guides: surfaces, agents, the assistant, starting a dashboard, data display, voice, the benchmark |
 | `decisions/` | One record per lasting decision |
 | `scripts/` | Generators, gates, `brand.ts` and `verify.ts` (see `CONTRIBUTING.md`) |
-| `skills/zz-meridian/` | The agent skill (Claude Code, Codex) that builds dashboards on this template or brings it into yours |
-| `cli/` | The `zz-meridian` npm package: `create`, `adopt`, `update`, `brand` and `skill`, its build, its smoke test and the fixture app (`docs/distribution.md`) |
+| `skills/zz-meridian/` | The agent skill (Claude Code, Codex) that builds dashboards on this template or brings it into yours, to the standard in `references/standard.md`; how it is evaluated is `docs/skill-evals.md` |
+| `cli/` | The `zz-meridian` npm package: `create`, `adopt`, `update`, `brand` and `skill`, its build, its smoke test and the fixture apps (`docs/distribution.md`) |
 | `.github/workflows/release.yml` | The release, each check once: a timed default verify and the consumer path from the tarball (the release before updated; the last three weekly), then npm with provenance, the registry's bytes and provenance checked, then the tag (`.claude/commands/release.md`) |
 | `.github/workflows/weekly.yml` | Weekly, never at release: `verify --full --perf` (perf a report) and the consumer smoke's recovery and failure cases; nothing waits on it |
 | `Dockerfile`, `captain-definition` | The demo deployment: the template and the Atlas behind `DEMO_PASSWORD` (`proxy.ts`, `app/sign-in/README.md`), deployed to CapRover from this repository; never in the package |
@@ -83,7 +83,15 @@ Dark is the default, written on `:root`; the light theme follows the operating s
 Give your coding agent (Codex, Claude Code, or any agent that can run a shell) this, with what you want in your own
 words at the end:
 
-> Run `npx zz-meridian@latest skill --global`, then follow the zz-meridian skill it installs to: [what you want, in your own words].
+> Run `npx zz-meridian@latest skill --global`, then follow the zz-meridian skill it installs to: [what you want, in your own words]. Done when its hand-over says the Meridian standard is met, or names what only I can decide or provide.
+
+In Claude Code or Codex, send it as a goal (`/goal Run npx zz-meridian@latest skill --global, then …`): the agent keeps
+working until the condition holds, and a separate model checks it after every turn against the hand-over, which quotes
+its evidence. The sentence says what you want; the skill carries how good it has to be. It builds, renders every view
+at phone and desktop width in both themes, scores each one on a scoreboard of floors (measured by `pnpm verify --full`)
+and craft (judged on the renders), and improves it round by round until nothing is weak, deciding what it can find out
+and recording each decision it made for you. You get the finished product, the renders, and the few questions only you
+can answer.
 
 You do not choose between the package's commands; the skill does, from what you said and what is in the folder, and
 names the route before it runs anything:

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/distribution.md

@@ -6,7 +6,7 @@ Status: v1 (`create`, `adopt`, `skill`) shipped in 0.2.0 (decision 0009). v2 (`u
 
 A team gives its coding agent this, with what it wants in its own words at the end:
 
-> Run `npx zz-meridian@latest skill --global`, then follow the zz-meridian skill it installs to: [what you want, in your own words].
+> Run `npx zz-meridian@latest skill --global`, then follow the zz-meridian skill it installs to: [what you want, in your own words]. Done when its hand-over says the Meridian standard is met, or names what only I can decide or provide.
 
 The sentence names no command, because people do not: "change this product into our dashboard", "a new one based on
 this folder, in another folder" and "build an orders console" all ask for a dashboard on Meridian and differ only in
@@ -15,6 +15,14 @@ which folder holds it. The skill's "Choose the route" table maps what was said,
 written) or `update` and `brand` (a project that already has Meridian), and says the route before the first command.
 An earlier sentence named `adopt`, the wrong command for every request for a new dashboard.
 
+The sentence is written to be sent as a goal (`/goal` in Claude Code and Codex), which keeps the agent working until a
+separate model, reading the conversation after every turn, finds the condition met. That model sees the sentence, not
+the skill, so the sentence ends with a condition the transcript can show: the hand-over (SKILL.md, step 7) quotes
+`pnpm verify --full`'s last line and the scoreboard's count, or names what only the person can decide or provide. The
+degree lives in the skill, never in the sentence: `skills/zz-meridian/references/standard.md` holds the register, the
+scoreboard of floors and craft kept for every view, the loop run until nothing is weak, and which decisions the agent
+makes and records and which wait for the person. People do not say how good it has to be, so the skill does not ask.
+
 The split follows what each part is good at. The package does the settled work, the same way every time, and proves it
 built: what to copy, which dependencies to merge, the alias, the stylesheet, the brand. The agent does the judgement:
 rebuilding each page on Meridian's components, the fake API, and reading what `pnpm verify` finds.

package/payload/docs/skill-evals.md

@@ -0,0 +1,65 @@
+# Evaluating the skill
+
+A person gives their agent one sentence (`docs/distribution.md`), and the skill carries everything the sentence leaves
+out: the standard, the definition of done, and how the agent evaluates its own work
+(`skills/zz-meridian/references/standard.md`). When those three are right, an agent that follows the skill reaches the
+standard on the person's project. So a change to the skill is judged by whether an agent reading it chooses the right
+route, decides instead of asking, knows what done means and how it will know, and finds the defects that keep a product
+from it. Rebuilding a whole dashboard to judge a change in wording is not needed.
+
+## Four levels
+
+| Level | What it shows | Cost | When |
+|---|---|---|---|
+| L0 static | Every path, command and flag the skill names exists (`node scripts/check.ts`); the text has no dated or contradictory instruction (a prompt audit, `/claude-api prompt-audit`) | seconds | every change to the skill |
+| L1 decisions | An agent reads the skill in a scenario's folder and stops before the first command that writes: its route, its announcement, its decisions, its brief, the views it will score, its definition of done and how it will evaluate | 2 to 5 minutes each, run side by side | a change to the route, the decisions, the brief or the standard |
+| L2 planted defects | An agent runs the loop on a built Meridian project with known defects planted (a clipped name, a missing empty state, a literal colour, a wrong total, a page with no protagonist, a stale `verify.config.ts` route): which it finds, which it fixes, and whether it stops only when `--full` prints the outcome | about 15 minutes | a change to the standard or the loop |
+| L3 end to end | The sentence, a fresh agent and a real request, from nothing (greenfield) or an existing app (brownfield) to the hand-over | 1 to 2 hours each | weekly, never per change |
+
+## L1 scenarios
+
+Each runs in a scratch folder. A scenario that starts from an existing app copies its fixture there, renames
+`fixture.env` to `.env` (an address on a reserved domain that stands for production), and commits it, so the folder is
+the clean repository a team would have.
+
+| Scenario | Folder | The request after "to:" | What a right answer does |
+|---|---|---|---|
+| Greenfield | empty | build an orders console for our bakery chain, three shops; today's orders, late pickups, which cakes sell best | `create .`; pages that answer the three questions; timezone, currency and "late" recorded as decisions; deletes the sample pages it does not need |
+| Next.js brownfield | `cli/test/fixture-crumb-ops` | make our ops console look and work like a professional product, and let the shop leads see late pickups at a glance | `adopt` in place; finds `API_URL` is production before running anything; fake API first, committed, with a request log; "before" renders; lists every route and action that must survive; keeps `lib/api.ts` |
+| Vite brownfield | `cli/test/fixture-vite-rota` | turn our rota app into a proper dashboard for the ward managers | `create` beside it, never in it; ports both routes and the one request; "before" from a copy; names the cookie and CORS change of a read moved to the server; switching over is the person's |
+| Update | a project made with `create --no-install`, committed | update Meridian to the latest | `update --dry-run` first; already current means it says so and stops |
+| Rebrand | the same | change our brand colour to #D97706 | `brand` with the manifest's version; sees the amber is 10° from the warning hue; nearest safe hue as the accent, the exact colour in the logo, recorded, no question |
+| Ambiguous | `cli/test/fixture-crumb-ops` | build me a dashboard for this | one question at most, the route, with the recommendation first; without an answer it takes the recommendation and says so |
+| Based on | `cli/test/fixture-crumb-ops` | based on this folder, make a new dashboard in ../crumb-v2 | `create ../crumb-v2`; reads the source and never writes it; ports its data layer and its contract |
+
+Every scenario is also held to what is true of all of them: the agent reads `standard.md` before building, asks nothing
+but the route, says the route before the first command, records decisions with their reasons, lists every view it will
+score, and states the definition of done as the commands and lines that will prove it.
+
+The probe is given the sentence, told where the skill and the local CLI are, told to write nothing, and asked for, in
+order: its announcement, the route and first commands, its decisions, the brief, the views, the definition of done and
+how it will know, how it will evaluate each view, its questions, and what in the skill was unclear, contradictory or
+missing, with `file:line`. Run at least one scenario on a smaller model than the one the skill is written with: the
+skill is for anyone's agent.
+
+## Reading the results
+
+Write what a right answer does before the probes run, and grade against it. A finding counts when the skill caused it:
+a contradiction, a path that does not resolve, a case it does not cover, a step that would stop an unattended run, a
+definition of done that cannot be reached. A finding that comes from the probe's own context (a memory or rule of the
+machine it ran on) is not the skill's. Fix each counted finding in the skill or in Meridian's code, and run the
+scenarios it touched again.
+
+## What each level finds
+
+Each level finds what the ones below it cannot, which is why none replaces another:
+
+- **L1** finds what reading the skill against the code shows: a definition of done the scripts make unreachable (the
+  first round found that the walk-throughs drove the template's own sample pages, so no product could pass), a step
+  that would stop an unattended run, a contradiction between two files, a case no route covers.
+- **L2** finds where judging by eye is not enough. Of six planted defects an agent found five; the one it missed, a
+  second featured metric, became a rule in `scripts/check.ts`. A rule the code can check is checked there, not left to
+  the scoreboard.
+- **L3** finds what only building shows: the gate misreading an adopted project's imports, a phone card's badge over
+  a long name, a verify that crashed on its own early exit. Each became a fix with a test, so the weekly run that
+  found it does not have to find it again.

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.11.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.",