zz-meridian 0.36.0 → 0.37.0

package/README.md

@@ -37,17 +37,26 @@ npx zz-meridian@latest skill [--global]           # install only the agent skill
 Brand flags: `--name "Acme Ops"`, `--hex '#2E6BE4'` (or `--hue 250 --chroma 0.14`, or `--accent indigo|cobalt|jade|graphite`), `--theme dark|light`,
 `--workspace`, `--timezone`, `--currency`, `--user`, `--role`. `--workspace` sets `app.workspace`, the environment named
 in a page's kicker ("Production"); it does not touch the navigation workspaces.
+`--timezone` must be accepted by `Intl.DateTimeFormat`, for example `UTC` or `Europe/London`; an unsupported zone is refused rather than saved.
+Quoted brand strings remain literal values across repeated rebranding; changing a role does not rewrite the person's existing name.
+Every valued flag needs its own value, including with the standalone `pnpm brand`: missing values and a following flag used as a value are refused before any configuration changes.
+Commands reject extra positional arguments before changing files: only `create` takes a folder argument.
 
 **adopt** copies Meridian's tokens, styles, components, gates and scripts into `src/`, `tokens/` and `scripts/`;
 merges the dependencies and scripts it needs into your `package.json`; adds the `@meridian/*` alias to your
 `tsconfig.json` (yours is kept as `tsconfig.before.json` when it carries comments or trailing commas, which JSON
 cannot hold); replaces your global stylesheet (yours is kept
-beside it as `*.before.css`); brands it; adds Meridian's managed block to your `AGENTS.md` between two markers, keeping your own text there byte
+beside it as `*.before.css`); preserves string keys and values in your TypeScript configuration, including punctuation;
+brands it; adds Meridian's managed block to your `AGENTS.md` between two markers, keeping your own text there byte
 for byte; writes an empty `docs/brief.md` (your product, users, data, decisions and glossary) if you have none; installs the skill into
 `.agents/skills/` (Codex) and `.claude/skills/` (Claude Code); records every Meridian file it copied in `.meridian/manifest.json`;
-installs and type checks. Your routes, your data layer and your own components are not touched. Meridian's files
-import each other by relative path, so a `components/ui/button` of your own is never confused with Meridian's; your
-code imports Meridian as `@meridian/…`.
+installs and reports route-generation and TypeScript diagnostics. An installation failure exits nonzero; diagnostic
+failures are reported as `types: fails` but adoption still exits zero, because your existing routes may need repairs.
+This is not a clean-typecheck guarantee: fix those diagnostics before running the gate. Your routes, your data layer
+and your own components are not touched. Meridian's files import each other by relative path, so a
+`components/ui/button` of your own is never confused with Meridian's; your code imports Meridian as `@meridian/…`.
+Supported dependency specifications below Meridian's required floor are raised, including within the same major;
+newer versions are kept. Custom specifications are kept with a note to confirm compatibility.
 
 It refuses, and writes nothing, when the git tree has uncommitted changes (so its change is one reviewable diff), when
 the project is not Next.js with the App Router, or when a file it would copy already exists with other content.
@@ -68,10 +77,12 @@ writes nothing; run it first.
 - It reports a migration for each interface the release changed where one of your own files still has the old shape,
   such as `cache-components-config` or `nav-needs`. `cli/src/migrations.ts` holds every one; resolve them as the skill's
   `references/update.md` says.
+- Team-owned sample files are checked again on every forward upgrade, even after their migration's introduction, so newer managed tests do not silently outrun the sample they exercise. They remain team-owned: the migration asks for review and never overwrites them.
 - Everything it did and everything left to do is in `.meridian/update/<version>/MERGE.md`. Resolve the items, then run
   the pinned `npx zz-meridian@<version> update --finalize`; `--resume` continues an interrupted run and `--abort` restores
   what it changed. Only finalize records the new version. `--finalize --verify` validates with the project's default
   `verify` instead of the gate and the build, and reports its coverage line.
+- Failure and coverage metadata is recorded literally in the report, including `$` sequences; it is not interpreted as report-template syntax.
 - It refuses, writing nothing, on a dirty git tree (unless `--allow-dirty`) or while another update is open. `--verbose`
   lists every file.
 
@@ -80,6 +91,9 @@ styles) and `src/app.config.ts` for the new flags and records them in the manife
 refuses when one of those outputs was edited, while an update is open, or on a dirty tree (unless `--allow-dirty`). Run
 it with the version the manifest records. The project's own `pnpm brand` still works, but its changes count as your edits.
 
+**skill** checks both `.agents/skills/zz-meridian` and `.claude/skills/zz-meridian` before writing either. Identical files are retained; different content or symlinks are refused. Move a customized copy aside, install the shipped skill, then reconcile the customization manually rather than losing it to an overwrite.
+An incomplete package without its `SKILL.md` is refused before either destination is written.
+
 The standard a project on Meridian is built to is
 [data-layers.md](https://github.com/zhixuan312/zz-meridian/blob/master/docs/data-layers.md): the four layers between a
 database and the screen, the contract a backend answers, and the six rules a project switches on in its own
@@ -102,6 +116,14 @@ telemetry. It talks to npm only, when `npx` fetches it and when `update` reads r
 public, so leave out anything that identifies you, your organisation or your product, and describe the problem with
 Meridian's own template or sample data.
 
+## Maintaining this package
+
+From the repository root, run `node cli/scripts/build-payload.ts` before `pnpm exec tsc -p cli/tsconfig.json` and packing. The producer reads committed `HEAD` by default; use `--worktree` to try uncommitted tracked changes. It also generates `cli/src/update-session.ts` from the canonical standalone `scripts/lib/update-session.ts`, using the same source provenance as the payload. Edit only the canonical module, never its generated CLI companion.
+The payload excludes `.env` and its variants at every directory depth, even when tracked; deliberate `.env.example`
+files remain available as public configuration templates. Never put credentials in an example file.
+
+The template's copied-command regression runs real cURL on loopback and needs a POSIX shell and `curl`, with no external endpoint or credentials.
+
 ## License
 
 MIT: the text is `payload/LICENSE` in the package and `LICENSE` in a project `create` makes.

package/dist/adopt.js

@@ -12,9 +12,41 @@ import path from 'node:path';
 import { VERSION, brandArgs, effectiveBrand, inside, installArgs, installSkill, jsoncExtras, packageManager, payloadBytes, payloadFiles, readJsonc, readPayload, relativeImports, skillPaths, run, runTool, sha256, writeIn, writeManifest, } from './files.js';
 import { BRIEF_TEMPLATE, managedBlock, upsertManagedBlock } from './context.js';
 import { FIXED, adoptSetOf, managedPaths, parseManifest } from './ownership.js';
-import { MERIDIAN_SCRIPTS, TOOLCHAIN, needOf } from './reconcile.js';
-const major = (spec) => Number(/(\d+)/.exec(spec)?.[1] ?? NaN);
+import { MERIDIAN_SCRIPTS, TOOLCHAIN, compareMinimum, needOf } from './reconcile.js';
 const TS = /\.(ts|tsx)$/;
+/** Raise known dependency floors in place; custom specifications stay the team's decision. */
+export function adoptDependencies(pkg, tpl, field, names) {
+    const notes = [];
+    pkg[field] ??= {};
+    for (const n of names) {
+        const want = tpl.dependencies?.[n] ?? tpl.devDependencies?.[n];
+        if (!want)
+            continue;
+        const have = pkg.dependencies?.[n] ?? pkg.devDependencies?.[n];
+        if (!have) {
+            pkg[field][n] = want;
+            continue;
+        }
+        const order = compareMinimum(have, want);
+        if (order === null) {
+            notes.push(`kept ${n} ${have}, which Meridian cannot compare: confirm it meets ${want} before running the gate`);
+        }
+        else if (order < 0) {
+            const at = pkg.dependencies?.[n] ? 'dependencies' : 'devDependencies';
+            pkg[at][n] = want;
+            notes.push(`raised ${n} from ${have} to ${want} (Meridian needs this floor; read its upgrade guide)`);
+        }
+    }
+    return notes;
+}
+/** Adoption is installed even when a team's existing routes need type repairs; report both diagnostic stages. */
+function adoptionTypes(root) {
+    const route = runTool(root, 'next/dist/bin/next', ['typegen']);
+    const tsc = runTool(root, 'typescript/bin/tsc', ['--noEmit']);
+    const failures = [['next typegen', route], ['tsc', tsc]];
+    const failed = failures.filter(([, result]) => result.status !== 0);
+    return failed.length ? `fails:\n${failed.map(([name, result]) => `${name}:\n${(result.stdout + result.stderr).trim().split('\n').slice(0, 30).join('\n')}`).join('\n')}` : 'passes';
+}
 /** A specifier inside a copied file, pinned to the exact module so a team file of a similar name can never win. */
 function exactImports(rel, source, known) {
     const pin = (spec) => {
@@ -267,29 +299,11 @@ Rename or move them, then run adopt again.`);
     }
     // ── Merged files: the project's own, changed only where Meridian needs it ────────────────────────────
     const tpl = JSON.parse(readPayload('package.json'));
-    const merge = (field, names) => {
-        pkg[field] ??= {};
-        for (const n of names) {
-            const want = tpl.dependencies?.[n] ?? tpl.devDependencies?.[n];
-            if (!want)
-                continue;
-            const have = pkg.dependencies?.[n] ?? pkg.devDependencies?.[n];
-            if (!have) {
-                pkg[field][n] = want;
-                continue;
-            }
-            if (major(have) < major(want)) {
-                const at = pkg.dependencies?.[n] ? 'dependencies' : 'devDependencies';
-                pkg[at][n] = want;
-                notes.push(`raised ${n} from ${have} to ${want} (Meridian needs the newer major; read its upgrade guide)`);
-            }
-        }
-    };
     // The packages the adopted modules import, and the framework: the rule `update` applies to a created project.
     const sources = new Map(set.filter((rel) => TS.test(rel)).map((rel) => [rel, payloadBytes(rel).toString('utf8')]));
     sources.set('src/app.config.ts', config);
-    merge('dependencies', needOf(tpl, sources).runtime);
-    merge('devDependencies', TOOLCHAIN);
+    notes.push(...adoptDependencies(pkg, tpl, 'dependencies', needOf(tpl, sources).runtime));
+    notes.push(...adoptDependencies(pkg, tpl, 'devDependencies', TOOLCHAIN));
     pkg.scripts ??= {};
     for (const s of MERIDIAN_SCRIPTS) {
         const want = tpl.scripts[s];
@@ -406,16 +420,14 @@ Rename or move them, then run adopt again.`);
             files[rel] = sha256(fs.readFileSync(inside(root, rel)));
     installSkill(root, files);
     writeManifest(root, { version: VERSION, route: 'adopt', brand, files });
-    // ── Install and prove it compiles ─────────────────────────────────────────────────────────────────────
+    // ── Install and report type diagnostics (existing team code may still need repairs) ──────────────────
     let typed = 'not run (--no-install)';
     if (o.install) {
         say(`\nInstalling with ${pm}…`);
         if (run(pm, installArgs(pm), root).status !== 0)
             return fail(`${pm} install failed (above). Fix it, then run ${pm} install and ${pm} run typecheck.`);
-        // Route types first (LayoutProps, PageProps), as the gate does.
-        runTool(root, 'next/dist/bin/next', ['typegen']);
-        const tsc = runTool(root, 'typescript/bin/tsc', ['--noEmit']);
-        typed = tsc.status === 0 ? 'passes' : `fails:\n${(tsc.stdout + tsc.stderr).trim().split('\n').slice(0, 30).join('\n')}`;
+        // Route types first (LayoutProps, PageProps), as the gate does; neither failure may be reported as passing.
+        typed = adoptionTypes(root);
     }
     say(`
 Meridian ${VERSION} is in ${root}.

package/dist/cli.js

@@ -37,6 +37,7 @@ const HELP = `zz-meridian ${VERSION}
 
 Brand flags: --name "Acme Ops" --workspace Production --timezone Europe/London --currency EUR
              --user "Ada Park" --role Admin --accent indigo|cobalt|jade|graphite | --hex '#2E6BE4' | --hue 250 --chroma 0.14
+             --theme dark|light
 
 Then give your coding agent the skill: .agents/skills/zz-meridian/SKILL.md.`;
 const read = readFlags(process.argv.slice(2));
@@ -69,6 +70,11 @@ function main() {
         console.error(`zz-meridian ${command}: --${wrong.flag} belongs to ${wrong.belongsTo}`);
         return 1;
     }
+    const extra = positionals[command === 'create' ? 2 : 1];
+    if (extra !== undefined) {
+        console.error(`zz-meridian ${command}: unexpected argument ${JSON.stringify(extra)}`);
+        return 1;
+    }
     if (command === 'adopt')
         return adopt({ root: process.cwd(), brand, allowDirty: Boolean(flags['allow-dirty']), install });
     if (command === 'create') {
@@ -95,8 +101,14 @@ function main() {
         return brandCommand({ root: process.cwd(), flags: brand, allowDirty: Boolean(flags['allow-dirty']) });
     if (command === 'skill') {
         const roots = flags.global ? [os.homedir()] : [process.cwd()];
-        for (const r of roots)
-            installSkill(r);
+        try {
+            for (const r of roots)
+                installSkill(r);
+        }
+        catch (error) {
+            console.error(`zz-meridian skill: ${error instanceof Error ? error.message : String(error)}`);
+            return 1;
+        }
         const skill = path.join(roots[0], '.claude/skills/zz-meridian/SKILL.md');
         console.log(`The zz-meridian skill is in ${flags.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.`);

package/dist/create.js

@@ -73,7 +73,7 @@ export function create(o) {
     if (hasCommand('git'))
         run('git', ['init', '-q'], root);
     if (o.install && run(install[0], install[1], root).status !== 0)
-        return fail(`${install.join(' ')} failed (above); run it again in ${root}`);
+        return fail(`${install[0]} ${install[1].join(' ')} failed (above); run it again in ${root}`);
     console.log(`
 ${name} is a new Meridian ${VERSION} dashboard in ${root}.
   skill: .agents/skills/zz-meridian (Codex) and .claude/skills/zz-meridian (Claude Code)

package/dist/files.js

@@ -140,7 +140,8 @@ function strippedJsonc(text) {
         }
         out += c;
     }
-    const json = out.replace(/,(\s*[}\]])/g, '$1');
+    // Consume strings whole before removing trailing commas: their keys and values may themselves contain ",]" or ",}".
+    const json = out.replace(/"(?:\\.|[^"\\])*"|,(\s*[}\]])/g, (match, end) => end ?? match);
     return { json, dropped: dropped || json.length !== out.length };
 }
 /** JSON with the comments and trailing commas a tsconfig may carry. */
@@ -184,13 +185,29 @@ export function writeManifest(root, m) {
  */
 export function skillPaths() {
     const files = payloadFiles('skills/zz-meridian');
+    if (!files.includes('skills/zz-meridian/SKILL.md'))
+        throw new Error('skills/zz-meridian/SKILL.md is not in cli/payload/: rebuild the payload or reinstall a complete package before installing the skill.');
     return ['.agents/skills/zz-meridian', '.claude/skills/zz-meridian'].flatMap((base) => files.map((f) => ({ rel: `${base}/${f.slice('skills/zz-meridian/'.length)}`, payload: f })));
 }
-/** The agent skill, into the folders each agent reads in a repository. */
+/** Refuse a different existing skill before writing either agent's copy. Identical copies need no write. */
 export function installSkill(root, record) {
-    for (const { rel, payload } of skillPaths()) {
-        const content = payloadBytes(payload);
-        writeIn(root, rel, content);
+    const contents = new Map();
+    const plan = skillPaths().map(({ rel, payload }) => {
+        const abs = inside(root, rel);
+        let content = contents.get(payload);
+        if (!content) {
+            content = payloadBytes(payload);
+            contents.set(payload, content);
+        }
+        const existing = fs.lstatSync(abs, { throwIfNoEntry: false });
+        if (existing && (!existing.isFile() || !fs.readFileSync(abs).equals(content))) {
+            throw new Error(`refusing to overwrite ${rel}: it differs from the packaged skill. Move your copy aside before installing again; no skill files were written.`);
+        }
+        return { rel, content, exists: Boolean(existing) };
+    });
+    for (const { rel, content, exists } of plan) {
+        if (!exists)
+            writeIn(root, rel, content);
         if (record)
             record[rel] = sha256(content);
     }

package/dist/migrations.js

@@ -106,8 +106,16 @@ function removedVerifyFlags(root) {
     const hits = [...new Set(files)].filter((rel) => removed.test(text(root, rel) ?? ''));
     return hits.length > 0 ? hits : null;
 }
+const APP_DIRS = ['app', 'src/app'];
+/** The route's path within either supported App Router folder, or null outside one. */
+const appPath = (rel) => rel.startsWith('app/') ? rel.slice(4) : rel.startsWith('src/app/') ? rel.slice(8) : null;
+const appFiles = (root, rel) => APP_DIRS.flatMap((dir) => {
+    const file = `${dir}/${rel}`;
+    const src = text(root, file);
+    return src === null ? [] : [{ rel: file, src }];
+});
 const base = (rel) => rel.slice(rel.lastIndexOf('/') + 1);
-const isPageOrLayout = (rel) => rel.startsWith('app/') && /^(?:page|layout)\.tsx?$/.test(base(rel));
+const isPageOrLayout = (rel) => appPath(rel) !== null && /^(?:page|layout)\.tsx?$/.test(base(rel));
 const isActionsFile = (rel) => /^actions\.tsx?$/.test(base(rel));
 const isServerFile = (src) => /^\s*(['"])use server\1/m.test(src);
 /** The tag `<name …>` bodies in a file, with `=>` inside an attribute not ending the tag. */
@@ -434,7 +442,7 @@ export const RELEASE_MIGRATIONS = [
     {
         id: 'authorized-read',
         since: '0.5.0',
-        applies: (root) => matching(root, (rel, src) => rel.startsWith('app/') && /^page\.tsx?$/.test(base(rel)) && /\.query\(/.test(src)),
+        applies: (root) => matching(root, (rel, src) => appPath(rel) !== null && /^page\.tsx?$/.test(base(rel)) && /\.query\(/.test(src)),
         summary: 'A page reads a collection through the authorized, cached read(), not by querying it directly.',
         instructions: 'Read "Authorized, scoped reads" in references/cache.md. Replace `collection.query(q)` in the page with `read(name, q)` from `src/data/read.ts`, format any freshness against the returned `observedAt`, and add `src/data/access.ts` and `src/data/read.ts` from the reference, bound to your own sign-in and database predicates.',
         checks: GATE_AND_BUILD,
@@ -452,13 +460,12 @@ export const RELEASE_MIGRATIONS = [
         since: '0.5.0',
         applies: (root) => {
             const out = [];
-            const layout = 'app/(dashboard)/layout.tsx';
             const collections = 'src/data/collections.ts';
             if (text(root, collections) !== null && text(root, 'src/data/live-actions.ts') === null)
                 out.push(collections);
-            const src = text(root, layout);
-            if (src !== null && !/\b(?:LiveProvider|ConsoleLive)\b/.test(src))
-                out.push(layout);
+            for (const { rel, src } of appFiles(root, '(dashboard)/layout.tsx'))
+                if (!/\b(?:LiveProvider|ConsoleLive)\b/.test(src))
+                    out.push(rel);
             return out.length > 0 ? out : null;
         },
         summary: 'The console has a live route, a refresh action and a provider.',
@@ -468,7 +475,7 @@ export const RELEASE_MIGRATIONS = [
     {
         id: 'authorized-endpoints',
         since: '0.5.0',
-        applies: (root) => matching(root, (rel, src) => (rel === 'app/api/assistant/route.ts' || (isActionsFile(rel) && isServerFile(src))) && !/\bresolveAccess\(/.test(src)),
+        applies: (root) => matching(root, (rel, src) => (appPath(rel) === 'api/assistant/route.ts' || (isActionsFile(rel) && isServerFile(src))) && !/\bresolveAccess\(/.test(src)),
         summary: 'The assistant route and every actions file resolve the caller before they act.',
         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,
@@ -485,13 +492,13 @@ export const RELEASE_MIGRATIONS = [
         id: 'assistant-view-tools',
         since: '0.10.0',
         applies: (root) => {
-            const route = text(root, 'app/api/assistant/route.ts');
+            const routes = appFiles(root, '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)
+            if (routes.length === 0 || 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'])];
+            const stale = [...(/\bViewTool\b/.test(tools) ? [] : ['src/lib/assistant/tools.ts']), ...(/\blimitsOf\b/.test(respond) ? [] : ['src/lib/assistant/respond.ts']), ...routes.filter(({ src }) => !/\bviews\s*:/.test(src)).map(({ rel }) => rel)];
             return stale.length > 0 ? stale : null;
         },
         summary: "The assistant's route-side code predates view tools and its limits.",
@@ -573,7 +580,10 @@ export const RELEASE_MIGRATIONS = [
     {
         id: 'view-page-matched-as-next',
         since: '0.16.3',
-        applies: (root) => (/\bfunction onPage\s*\(/.test(text(root, 'app/api/assistant/route.ts') ?? '') ? ['app/api/assistant/route.ts'] : null),
+        applies: (root) => {
+            const paths = appFiles(root, 'api/assistant/route.ts').filter(({ src }) => /\bfunction onPage\s*\(/.test(src)).map(({ rel }) => rel);
+            return paths.length > 0 ? paths : null;
+        },
         summary: 'The assistant route finds the view of the page a person is on with `viewAt` from `src/lib/shared-context.ts`, which matches a catch-all `page` as Next.js does.',
         instructions: 'In `app/api/assistant/route.ts`, delete the local `onPage` and find the view with `viewAt` from `@/lib/shared-context` (`@meridian/lib/shared-context` in an adopted project): `const at = viewAt(viewTools, path); const view = at && views.includes(at) ? at : undefined;`, where `views` are the view tools the person may use. `onPage` matched a `[...name]` segment as one segment and a `[[...name]]` never, so a view whose `page` is a catch-all (`/docs/[...path]`) was handed its prepared query at one depth only. `viewAt` matches as Next.js does — `[...name]` one or more segments, `[[...name]]` zero or more — and where two views match one address it takes the one Next.js renders, before asking whether the person may use it, so a less specific view never stands in for the page.',
         checks: ['gate'],
@@ -589,7 +599,7 @@ export const RELEASE_MIGRATIONS = [
     {
         id: 'today-in-timezone',
         since: '0.16.3',
-        applies: (root) => matching(root, (rel, src) => (rel === 'app/api/assistant/route.ts' || rel === 'src/data/metrics.ts') && /\bconst today = clock\(\)\.toISOString\(\)\.slice\(0, 10\)|\btoday: clock\(\)\.toISOString\(\)\.slice\(0, 10\)/.test(src)),
+        applies: (root) => matching(root, (rel, src) => (appPath(rel) === 'api/assistant/route.ts' || rel === 'src/data/metrics.ts') && /\bconst today = clock\(\)\.toISOString\(\)\.slice\(0, 10\)|\btoday: clock\(\)\.toISOString\(\)\.slice\(0, 10\)/.test(src)),
         summary: "Today is the day in `app.timezone` wherever a day is cut: `dayOf(clock())` from `src/lib/format-date.ts`, not the UTC date.",
         instructions: "Replace `clock().toISOString().slice(0, 10)` with `dayOf(clock())` (`dayOf` in `src/lib/format-date.ts`) in each file listed: the prepared query's `today` in `app/api/assistant/route.ts`, and `readDays`'s today in `src/data/metrics.ts`. The prompt has told the model today in `app.timezone` all along, while the prepared query and the page cut their periods at the UTC date, so east of UTC after local midnight (west of UTC in the evening) the model's today and its `7d` window's end were a day apart. A day row is kept under its day in `app.timezone`, so a file of your own that compares an instant's day with one — `now.slice(0, 10)`, `at.slice(0, 10)` — asks `dayOf` too. A product whose `app.timezone` is UTC sees no change. A project that kept the sample's views brings `src/views/now-parts.ts`, `src/views/revenue-parts.ts`, `src/views/customer-context.ts`, `src/views/customer.tsx` and `src/views/members.tsx` over from the release.",
         checks: ['gate'],
@@ -615,7 +625,7 @@ export const RELEASE_MIGRATIONS = [
         since: '0.26.0',
         applies: (root) => matching(root, (rel, src) => importsOf(rel, src).some(({ from }) => from === 'src/components/ui/table' || from === 'src/components/patterns/data-table') && (/@min-\[672px\]:min-w-64/.test(src) || /<TableCell\b[^>]*\bcolSpan\s*=/.test(src))),
         summary: 'A table is a grid since 0.26.0: its spare width sits in the gaps, a `grow` column\'s floor is 160px at every width, and a cell spans no columns.',
-        instructions: 'Bring `tests/table-cut-cell.test.tsx` over from the release as it has it. Since 0.26.0 `src/components/ui/table/index.tsx` lays a table out as a grid whose rows are subgrids: every column is as wide as its content, the spare is shared equally between the gaps, and a `grow` column\'s floor is `min-w-40` at every width, without the `@min-[672px]:min-w-64` it had from a 672px table. A test of your own that expects that class expects `min-w-40` alone. A `TableCell` of your own with a `colSpan` takes one track of the grid, so it draws in the first column only: a row that should run the width of the table, such as an empty state, is drawn outside the table, or as a `DataTable` `empty`.',
+        instructions: 'Bring `tests/table-cut-cell.test.tsx` over from the release as it has it. Since 0.26.0 `src/components/ui/table/index.tsx` lays a table out as a grid whose rows are subgrids: every column is as wide as its content, the spare is shared equally between the gaps, and a `grow` column has a 160px floor at every width. Remove tests that pin the old or new utility-class strings rather than repinning them; check truncation, full-value access and the rendered responsive grid. A `TableCell` of your own with a `colSpan` takes one track of the grid, so it draws in the first column only: a row that should run the width of the table, such as an empty state, is drawn outside the table, or as a `DataTable` `empty`.',
         checks: ['gate'],
     },
     {
@@ -626,12 +636,20 @@ export const RELEASE_MIGRATIONS = [
         instructions: `Read "The four layers" and "The path an existing product follows" in references/data-layers.md. Thirty-eight modules moved into the logic layer, and each import of one in your own \`src/views/\` producers and pages names the path it left: ${MOVED_LIST}. Rewrite each import to the path the module has now, or move your own module beside the work it does. Two symbols left a card of Meridian's, and both must be rewritten because the update replaces the card: \`afterStart\`, which the incident card exported, is \`@/logic/after-start\`, and \`summarise\`, which the status list re-exported, is \`@/logic/summarise\` (\`@meridian/logic/…\` in an adopted project, where \`@/\` is your own). Every other path your own files name is still there, so a project that imported neither symbol keeps building as it was. The six layer rules stay off until your own \`scripts/check.local.ts\` exports \`fourLayers = true\`; turn them on once your figures have moved, and the gate and the build are what show the work is done.`,
         checks: GATE_AND_BUILD,
     },
+    {
+        id: 'env-reset-before-each',
+        since: '0.29.0',
+        applies: (root) => matching(root, (rel, src) => /\.test\.[cm]?[jt]sx?$/.test(rel) && setsEnvInBeforeAll(src)),
+        summary: '`tests/setup.ts` puts `process.env` back before every test, so a value a test file sets in `beforeAll` is gone when its first test runs.',
+        instructions: "Since 0.29.0 the shipped `tests/setup.ts` restores the environment before each test, so a stub in one file can no longer reach the file beside it. A test file of your own that sets `process.env` (or calls `vi.stubEnv`) inside `beforeAll` loses the value before its first test, and fails with no reason given. In each file listed, keep the costly start (a fake backend, a server) in `beforeAll` and keep what it returns in a variable, then set the environment from it in a `beforeEach`: `beforeEach(() => { process.env.API_URL = started.base; })`.",
+        checks: ['gate'],
+    },
     {
         id: 'direct-query-escape',
         since: '0.30.0',
-        applies: (root) => matching(root, (rel, src) => /^(?:app|src\/(?:logic|views|lib))\//.test(rel) && SOURCE.test(rel) && /\.query\s*\(/.test(src.replace(/\/\/[^\n]*/g, '')) && !/allow-no-direct-query:/.test(src)),
+        applies: (root) => matching(root, (rel, src) => (appPath(rel) !== null || /^src\/(?:logic|views|lib)\//.test(rel)) && SOURCE.test(rel) && /\.query\s*\(/.test(src.replace(/\/\/[^\n]*/g, '')) && !/allow-no-direct-query:/.test(src)),
         summary: 'A direct `.query(` call is allowed only where the call states its own escape: `// allow-no-direct-query: <why>`, on that line.',
-        instructions: 'Since 0.30.0 `node scripts/check.ts` reports every `.query(` call in `app/`, `src/logic/`, `src/views/` and `src/lib/`, and keeps the run passing only where the call\'s own line carries the escape the check prints — `// allow-no-direct-query: read() cannot serve this — <why>`. Before this release the rule allowed five sites of the template\'s by line number, so a file of your own that read a collection directly passed as long as the call sat on one of those lines; that list is gone, because a comment added above a call moved it off the line and turned a passing project red for no reason. Read every file named above. Where the read has to be direct — a server action reading the record it is about to change, a streamed export, the sign-in resolving a person before an `AccessScope` exists — state the reason on that line in the form the check prints. Everywhere else, read through `read()`, `readAll()` or `aggregate()` from `@/data/read`, which ask the caller\'s grant.',
+        instructions: 'Since 0.30.0 `node scripts/check.ts` reports every `.query(` call in `app/`, `src/app/`, `src/logic/`, `src/views/` and `src/lib/`, and keeps the run passing only where the call\'s own line carries the escape the check prints — `// allow-no-direct-query: read() cannot serve this — <why>`. Before this release the rule allowed five sites of the template\'s by line number, so a file of your own that read a collection directly passed as long as the call sat on one of those lines; that list is gone, because a comment added above a call moved it off the line and turned a passing project red for no reason. Read every file named above. Where the read has to be direct — a server action reading the record it is about to change, a streamed export, the sign-in resolving a person before an `AccessScope` exists — state the reason on that line in the form the check prints. Everywhere else, read through `read()`, `readAll()` or `aggregate()` from `@/data/read`, which ask the caller\'s grant.',
         checks: ['gate'],
     },
     {
@@ -658,6 +676,14 @@ export const RELEASE_MIGRATIONS = [
         instructions: 'The audit, the presses, the keyboard walk, the vitals and `scripts/shot.ts` now read what a route answered: one that answered an error status or draws the not-found screen (`[data-missing-page]`) was measured as that screen and not as the route, so it fails. In `scripts/verify.config.ts`, which is yours, move every entry of `detailRoutes` that names a record that does not exist (the sample\'s `/requests/req_missing` and `/customers/missing`) into a new `missingRoutes` list; each must be the not-found screen, and one that renders a page fails. A not-found screen of your own carries `data-missing-page` on its root, as `MissingPage` does: inside a streamed shell a missing record has already answered 200.',
         checks: ['verify'],
     },
+    {
+        id: 'computed-series-slot',
+        since: '0.32.0',
+        applies: (root) => matching(root, (rel, src) => SOURCE.test(rel) && importsOf(rel, src).some(({ from }) => SLOT_CHARTS.includes(from)) && computesSlot(src)),
+        summary: "A chart's `color` is a palette slot, `SeriesSlot` (1 to 6), where it took any number: a computed one fails the type check.",
+        instructions: "Since 0.32.0 `ColumnPart`, a Composition bar's `Part`, `Sparkline` and a Trend chart's series take `color` as a `SeriesSlot`, `1 | 2 | 3 | 4 | 5 | 6` from `src/components/charts/scale.ts`, because a slot past six named a colour no theme defines and drew nothing. A file of your own that computes the slot (`color: i + 1`) fails `tsc` at `--finalize`. In each file listed, type the value as a `SeriesSlot` where it is computed, or fold the parts past the palette into one \"Other\" part, as the Composition bar does past six. A file that already types it so has nothing to change.",
+        checks: ['gate'],
+    },
     {
         id: 'use-size-callback-ref',
         since: '0.33.0',
@@ -669,7 +695,7 @@ export const RELEASE_MIGRATIONS = [
     {
         id: 'self-hosted-fonts',
         since: '0.34.0',
-        applies: (root) => matching(root, (rel, src) => /^app\//.test(rel) && SOURCE.test(rel) && /from\s+['"]next\/font\/google['"]/.test(src) && /--font-face-(?:sans|mono)/.test(src)),
+        applies: (root) => matching(root, (rel, src) => appPath(rel) !== null && SOURCE.test(rel) && /from\s+['"]next\/font\/google['"]/.test(src) && /--font-face-(?:sans|mono)/.test(src)),
         summary: "Meridian's faces ship with the release under `src/styles/fonts/`: a build loads them from there and fetches nothing from Google Fonts.",
         instructions: "Your `app/layout.tsx` is yours, so an update does not touch it, and yours hands `--font-face-sans` and `--font-face-mono` their faces through `next/font/google`, which `next build` fetches from fonts.googleapis.com: with that host unreachable and no build cache, the build fails (`Build error occurred`). The update has delivered the two faces, `src/styles/fonts/Geist-Variable.woff2` and `src/styles/fonts/GeistMono-Variable.woff2`, with their licence. In the layout, replace the `next/font/google` import with `import localFont from 'next/font/local';` and each face's call with `localFont({ src: '../src/styles/fonts/Geist-Variable.woff2', weight: '100 900', variable: '--font-face-sans', display: 'swap' })` and `localFont({ src: '../src/styles/fonts/GeistMono-Variable.woff2', weight: '100 900', variable: '--font-face-mono', display: 'swap' })`, keeping the class names on `<html>` as they are. A layout that gives the tokens faces of its own from Google Fonts is the same case: ship the files and load them with `next/font/local`.",
         checks: GATE_AND_BUILD,
@@ -693,11 +719,28 @@ export const RELEASE_MIGRATIONS = [
     {
         id: 'sample-with-its-tests',
         since: '0.36.0',
+        recurring: true,
         applies: sampleBehindItsTests,
-        summary: "The sample's files changed with the shipped tests that pin them: the update brings the tests, and each file named here is still the copy they no longer pass.",
-        instructions: "A project `create` made holds the template's sample (its pages, views, data, figures, their helpers and the demo gate in `proxy.ts`) as its own files, which an update never touches, while the shipped tests that pin how they behave are Meridian's and arrive with it. This release changed both together: the API keys actions answer a result, the error screens take `retry`, the request page names its cURL and its payload sizes in characters, the demo gate leaves open only the icon files, a member never seen is said to be, the past-due alert is timed by the latest customer to fall past due, and the period totals moved to the new `src/lib/totals.ts`. Each file named above differs from the release's copy, or is a sample module the release added, and the gate fails on it as it is. Write the release's copies into a scratch folder with `npx zz-meridian@<the version you are updating to> create <scratch folder> --no-install`. Then, for each file named: when your team never changed it (no commit of yours touches it), copy the release's file over it, and copy each module the release added. When your team made it its own, keep yours and make each shipped test that pins it yours too: change the test to your behaviour, which the next update stages for your decision as an edited file, or delete it and name it in `.meridian/keep.json`. A sample file your team deleted is not named.",
+        summary: "The release's sample differs from team-owned files, while its shipped tests are managed. Review those differences before finalizing.",
+        instructions: "A project `create` made holds the template's sample (its pages, views, data, figures, their helpers and the demo gate in `proxy.ts`) as its own files, which an update never touches, while the shipped tests are Meridian's and arrive with it. The update reports differing sample files on every upgrade, even when a previous release already reported this migration. Each named file differs from the release's copy, or is a sample module introduced after your project's recorded version; the gate may depend on its changes. Write the release's copies into a scratch folder with `npx zz-meridian@<the version you are updating to> create <scratch folder> --no-install`. For a file your team never changed, copy the release's file over it, and copy each module the release added. For a file your team made its own, preserve the intended product behavior while updating its contracts and meaningful behavior and security tests. Keep coverage for functionality the product still exposes; do not delete failures merely to finalize. Retire tests with removed sample features, or when they only pin wording or implementation details, and record intentionally deleted managed tests in `.meridian/keep.json`. A sample file your team deleted after its introduction is not named.",
         checks: GATE_AND_BUILD,
     },
+    {
+        id: 'proposal-approve-required',
+        since: '0.37.0',
+        applies: (root) => matching(root, (rel, src) => SOURCE.test(rel) && importsOf(rel, src).some(({ from }) => from === 'src/components/patterns/proposal') && tags(src, 'Proposal').some((t) => !/\bstate\s*=/.test(t) && !/\bonApprove\s*=/.test(t) && !/\{\s*\.\.\./.test(t))),
+        summary: 'An uncontrolled `Proposal` requires `onApprove`: without it, Approve claimed Applied for a change nothing ran.',
+        instructions: 'Since 0.37.0 `src/components/patterns/proposal/index.tsx` types `onApprove` as required when no `state` is passed, so a `<Proposal>` of your own without either fails `tsc` at `--finalize`. In each file listed, pass the function that runs the change as `onApprove`, or pass `state` and own the card\'s states yourself. A card that only shows a change it cannot run is not a proposal: show it in a Card instead.',
+        checks: ['gate'],
+    },
+    {
+        id: 'open-command-moved',
+        since: '0.37.0',
+        applies: (root) => matching(root, (rel, src) => SOURCE.test(rel) && importsOf(rel, src).some(({ from, names }) => from === 'src/components/patterns/command-palette' && names.some((n) => n === 'openCommand' || n === 'usePaletteKey'))),
+        summary: '`openCommand` and `usePaletteKey` moved to `src/components/patterns/command-palette/open.ts`, so the palette can be a chunk of its own.',
+        instructions: 'Since 0.37.0 the Command palette loads with `next/dynamic` and is in no page\'s first load, so the two things a page needs before it opens, `openCommand` and `usePaletteKey`, live in `src/components/patterns/command-palette/open.ts` and the palette\'s own file no longer exports them. In each file listed, import them from `@/components/patterns/command-palette/open`. Mount the palette the way `src/views/console-chrome.tsx` does, through `dynamic()`, or importing it puts it back in every page\'s first load.',
+        checks: ['gate'],
+    },
 ];
 /**
  * The template's sample as `create` writes it: the team's own sources among the pages, views, data, logic and library,
@@ -707,10 +750,10 @@ const isSample = (rel) => SOURCE.test(rel) && isTeamOwned(rel) && ((rel.startsWi
 /** The sample modules 0.36.0 added: a project created before has none, and the release's pages and tests import them. */
 const SAMPLE_ADDED = ['src/lib/totals.ts'];
 /**
- * 0.36.0: in a project `create` made, each sample file that differs from the release's, and each sample module the
- * release added that the project lacks. A sample file the team deleted is its decision and is not named.
+ * In a project `create` made, each sample file that differs from the release's, and each sample module introduced
+ * after the source release that the project lacks. A file the team deleted after its introduction is not named.
  */
-function sampleBehindItsTests(root) {
+function sampleBehindItsTests(root, source) {
     if (!/"route"\s*:\s*"create"/.test(text(root, '.meridian/manifest.json') ?? ''))
         return null;
     const hits = payloadFiles().filter(isSample).filter((rel) => {
@@ -718,7 +761,7 @@ function sampleBehindItsTests(root) {
             return !fs.readFileSync(path.join(root, rel)).equals(payloadBytes(rel));
         }
         catch {
-            return SAMPLE_ADDED.includes(rel);
+            return SAMPLE_ADDED.includes(rel) && isNewer('0.36.0', source);
         }
     });
     return hits.length > 0 ? hits : null;
@@ -757,12 +800,14 @@ function navItemWithoutFields(root) {
  * A configuration's own `NavItem` as written, comments blanked: its declaration's line, and when that line does not end
  * the statement with a `;`, every line after it that is blank, indented, or opens with a closing bracket or an operator
  * that continues it (`}`, `]`, `)`, `>`, `|`, `&`, `?`, `:`), up to the first that starts at the margin with anything
- * else. A declaration inside a comment is not the type unless it is the only one. Undefined when there is none. No
- * type is parsed: a shape this cuts short is reported rather than passed, since a migration line with nothing to do costs
- * a look, and a missed one is the type error with no line it exists to prevent.
+ * else. The type is read whether it is exported or not: one local to the module still types the items of an exported
+ * `NavGroup`, so the rail reads its fields all the same (#103). A declaration inside a comment is not the type unless it
+ * is the only one. Undefined when there is none. No type is parsed: a shape this cuts short is reported rather than
+ * passed, since a migration line with nothing to do costs a look, and a missed one is the type error with no line it
+ * exists to prevent.
  */
 function navItemType(body) {
-    const declaration = /^export\s+(?:interface|type)\s+NavItem\b/m;
+    const declaration = /^(?:export\s+)?(?:interface|type)\s+NavItem\b/m;
     // A regular expression is not told from a comment here, so one that opens `/*` can blank the type: then the raw text.
     const m = declaration.exec(uncommented(body)) ?? declaration.exec(body);
     if (!m)
@@ -842,7 +887,7 @@ function renamedSampleFiles(root) {
     const modules = new Set([...old.flatMap((n) => [`src/views/${n}`, `src/views/${n}-context`]), `src/data/${old[1]}`]);
     const group = `(${old[0]})`;
     const named = new RegExp(`\\b(?:FEATURES\\.|view_)(?:${old.join('|')})\\b`);
-    const isOld = (rel) => modules.has(rel.replace(/\.[mc]?[jt]sx?$/, '')) || (/^(?:src\/)?app\//.test(rel) && rel.split('/').includes(group));
+    const isOld = (rel) => modules.has(rel.replace(/\.[mc]?[jt]sx?$/, '')) || (appPath(rel) !== null && rel.split('/').includes(group));
     const sources = teamSources(root);
     if (!sources.some((f) => isOld(f.rel)))
         return null;
@@ -854,7 +899,7 @@ function renamedSampleFiles(root) {
     // of the old, and are as much the sample's. A file that imports one of the old files, such as a test that renders the
     // page, names it too; a file that only names one, such as the configuration, is not itself the old.
     const oldFiles = new Set(sources.map((f) => f.rel).filter(isOld));
-    const pages = sources.filter(({ rel, src }) => /^(?:src\/)?app\//.test(rel) && /^(?:page|view)\.tsx?$/.test(base(rel)) && (isOld(rel) || importsOf(rel, src).some((i) => modules.has(i.from))));
+    const pages = sources.filter(({ rel, src }) => appPath(rel) !== null && /^(?:page|view)\.tsx?$/.test(base(rel)) && (isOld(rel) || importsOf(rel, src).some((i) => modules.has(i.from))));
     for (const { rel } of pages) {
         const dir = path.posix.dirname(rel);
         try {
@@ -915,6 +960,31 @@ function navItemObjects(nav) {
     }
     return found;
 }
+/** The chart cards whose `color` is a `SeriesSlot` since 0.32.0. */
+const SLOT_CHARTS = ['src/components/charts/column-chart', 'src/components/charts/column-chart/grouped', 'src/components/charts/composition-bar', 'src/components/charts/sparkline', 'src/components/charts/trend-chart'];
+/**
+ * Whether a file computes a chart colour by arithmetic (`color: i + 1`) without typing it `SeriesSlot`: the shape the
+ * 0.32.0 narrowing fails. A slot held in a variable typed `number` is not read; a named colour or a literal slot passes.
+ */
+function computesSlot(src) {
+    return [...src.matchAll(/\bcolor\s*(?::|=\s*\{)([^,}\n]*)/g)].some((m) => /[-+*%]\s*\d|\d\s*[-+*%]/.test(m[1]) && !/\bas\s+SeriesSlot\b/.test(m[1]));
+}
+/**
+ * Whether a test file sets the environment inside a `beforeAll`: the hook's own parentheses, read by their nesting, hold
+ * an assignment to `process.env` or a `vi.stubEnv` call. Strings are not told from code; a missed shape is a test
+ * that fails at `--finalize`, a false one a line to read.
+ */
+function setsEnvInBeforeAll(src) {
+    for (const m of src.matchAll(/\bbeforeAll\s*\(/g)) {
+        let depth = 1;
+        let i = m.index + m[0].length;
+        for (; i < src.length && depth > 0; i++)
+            depth += src[i] === '(' ? 1 : src[i] === ')' ? -1 : 0;
+        if (/\bprocess\.env(?:\.\w+|\[[^\]]+\])\s*=(?!=)|\bvi\.stubEnv\s*\(/.test(src.slice(m.index, i)))
+            return true;
+    }
+    return false;
+}
 /** The project's own nav, with any item still missing the `needs` that 0.13.0 requires of it. */
 function navItemsWithoutNeeds(root) {
     const rel = 'src/app.config.ts';
@@ -941,7 +1011,7 @@ function navItemsWithoutNeeds(root) {
  */
 function ownGroupPagesWithoutAgentReads(root) {
     const dirs = [];
-    for (const app of ['app', 'src/app']) {
+    for (const app of APP_DIRS) {
         try {
             dirs.push(...fs.readdirSync(path.join(root, app), { withFileTypes: true }).filter((e) => e.isDirectory() && /^\(.+\)$/.test(e.name) && e.name !== '(dashboard)').map((e) => `${app}/${e.name}`));
         }
@@ -951,7 +1021,7 @@ function ownGroupPagesWithoutAgentReads(root) {
 }
 /** The page specifications under the console and embed folders that lack the part the 0.9.0 check requires. */
 function pagesWithoutAgentReads(root) {
-    return specsWithoutAgentReads(root, ['app/(dashboard)', 'app/embed']);
+    return specsWithoutAgentReads(root, APP_DIRS.flatMap((app) => [`${app}/(dashboard)`, `${app}/embed`]));
 }
 /** The page specifications under `dirs` without `## Agents` and its `### What the agent reads`. */
 function specsWithoutAgentReads(root, dirs) {
@@ -963,13 +1033,15 @@ function specsWithoutAgentReads(root, dirs) {
 }
 /** The registry entries that apply to a project moving from `source` to `target`, as journal migrations. */
 export function releaseMigrations(root, source, target) {
+    if (!isNewer(target, source))
+        return [];
     const out = [];
     sources = new Map();
     try {
         for (const m of RELEASE_MIGRATIONS) {
-            if (!isNewer(m.since, source) || isNewer(m.since, target))
+            if (isNewer(m.since, target) || (!m.recurring && !isNewer(m.since, source)))
                 continue;
-            const paths = m.applies(root);
+            const paths = m.applies(root, source);
             if (paths)
                 out.push({ id: m.id, summary: m.summary, paths, instructions: m.instructions, checks: m.checks });
         }

package/dist/reconcile.js

@@ -20,6 +20,11 @@ function range(spec) {
 }
 const minimum = (spec) => range(spec)?.v ?? null;
 const compare = (a, b) => a[0] - b[0] || a[1] - b[1] || a[2] - b[2];
+/** Compare supported dependency floors; null means the specification needs a person's judgment. */
+export function compareMinimum(have, want) {
+    const a = minimum(have), b = minimum(want);
+    return a && b ? compare(a, b) : null;
+}
 /** Whether `version` satisfies a specification `range` reads. A specification it cannot read is not judged. */
 export function satisfies(spec, version) {
     const want = range(spec);

package/dist/session.js

@@ -598,9 +598,9 @@ function patchReport(l, outcome, coverage = null) {
         .replace(/^- Coverage: .*\n/m, '')
         .replace(/^## Failure\n\n[\s\S]*?\n\n(?=## )/m, '');
     if (coverage)
-        text = text.replace(/^(- Outcome: .*)$/m, `$1\n- Coverage: ${coverage.replace(/^coverage: /, '')}`);
+        text = text.replace(/^(- Outcome: .*)$/m, (line) => `${line}\n- Coverage: ${coverage.replace(/^coverage: /, '')}`);
     if (j.failure)
-        text = text.replace(/^## What needs you$/m, `## Failure\n\n${j.failure}\n\n## What needs you`);
+        text = text.replace(/^## What needs you$/m, () => `## Failure\n\n${j.failure}\n\n## What needs you`);
     writeAtomic(file, text);
 }
 /** Drops the temporary copies and moves the session to `.meridian/history/<version>/<id>/`. */