zz-meridian 0.10.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/session.js

@@ -307,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.10.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,41 @@
 
 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

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/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/package.json

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