zz-meridian 0.35.0 → 0.37.0

package/README.md

@@ -34,20 +34,29 @@ npx zz-meridian@<version> brand [brand flags]     # rebrand this project, with t
 npx zz-meridian@latest skill [--global]           # install only the agent skill
 ```
 
-Brand flags: `--name "Acme Ops"`, `--hex '#2E6BE4'` (or `--accent indigo|cobalt|jade|graphite`), `--theme dark|light`,
+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,8 +91,11 @@ 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/main/docs/data-layers.md): the four layers between a
+[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
 `scripts/check.local.ts`.
 
@@ -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
+MIT: the text is `payload/LICENSE` in the package and `LICENSE` in a project `create` makes.

package/dist/adopt.js

@@ -3,20 +3,50 @@
  * its data layer. Everything here is the settled part of the skill's Route A; rebuilding each page on Meridian's
  * components is the agent's work, and the printed next step hands it over.
  *
- * Nothing is written until every check has passed: a dirty tree, a project that is not Next.js with the App Router,
- * or a file of the same name with other content stops it before the first write.
+ * Nothing is written until every check has passed: a project already on Meridian (its manifest: update is the command),
+ * a dirty tree, a project that is not Next.js with the App Router, or a file of the same name with other content stops
+ * it before the first write.
  */
 import fs from 'node:fs';
 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 } from './ownership.js';
-/** The template's dependencies a dashboard built from these files needs. */
-const DEPS = ['next', 'react', 'react-dom', 'radix-ui', 'lucide-react', 'clsx', 'tailwind-merge', 'react-markdown', 'remark-gfm', 'ai', '@ai-sdk/react', 'zod'];
-const DEV_DEPS = ['typescript', '@types/node', '@types/react', '@types/react-dom', 'tailwindcss', '@tailwindcss/postcss', 'eslint', 'eslint-config-next', 'vitest', '@vitejs/plugin-react', 'jsdom', '@testing-library/react', '@testing-library/dom', '@testing-library/jest-dom'];
-const SCRIPTS = ['typecheck', 'test', 'tokens', 'check', 'contrast', 'gate', 'audit', 'verify', 'brand', 'shot', 'interactions', 'keyboard', 'vitals'];
-const major = (spec) => Number(/(\d+)/.exec(spec)?.[1] ?? NaN);
+import { FIXED, adoptSetOf, managedPaths, parseManifest } from './ownership.js';
+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) => {
@@ -93,13 +123,14 @@ export function projectConfig(template, pages) {
         .replace(/export const nav: NavGroup\[\] = \[[\s\S]*?\n\];/, `/** Written by zz-meridian adopt from the project's pages: give each its own icon and group them. */\nexport const nav: NavGroup[] = [\n  {\n    items: [\n${items}\n    ],\n  },\n];`);
 }
 /**
- * `scripts/verify.config.ts` as a project gets it. The sample's persona rows are what used `EVERY_ROUTE`, so replacing the
- * config object leaves the constant declared and never read — which the gate's own lint fails, in the project adopt just
- * wrote, 0.7 s after the other steps passed. Exported so a test can hold the rewrite to that.
+ * `scripts/verify.config.ts` as a project gets it. The sample's persona rows are what used `EVERY_ROUTE` and `ROLE_ROUTES`,
+ * so replacing the config object leaves them declared and never read — which the gate's own lint fails, in the project
+ * adopt just wrote, 0.7 s after the other steps passed — and names the sample's routes in the team's file. Each goes
+ * with its doc line. Exported so a test can hold the rewrite to that.
  */
 export function verifyConfig() {
     return readPayload('scripts/verify.config.ts')
-        .replace(/^const EVERY_ROUTE = \[[^\n]*\n/m, '')
+        .replace(/^\/\*\*[^\n]*\*\/\nconst (?:EVERY_ROUTE|ROLE_ROUTES) = \[[^\n]*\n\n?/gm, '')
         .replace(/const config: VerifyConfig = \{[\s\S]*?\n\};/, `const config: VerifyConfig = {
   // One detail page per state worth seeing (a normal record, a failed one, a missing one), with ids from your data.
   detailRoutes: [],
@@ -182,6 +213,17 @@ export function adopt(o) {
     // ── Checks: nothing is written until all of them pass ─────────────────────────────────────────────────
     if (!fs.existsSync(pkgPath))
         return fail(`no package.json in ${root}: run adopt in the project's folder`);
+    // A project adopt or create already set up holds Meridian's files as its manifest records them, and whatever the team
+    // changed since; adopted again, every edited one would be listed as a conflict. Moving it to this release is update's.
+    const manifestPath = path.join(root, '.meridian/manifest.json');
+    if (fs.existsSync(manifestPath)) {
+        let at = '';
+        try {
+            at = ` ${parseManifest(fs.readFileSync(manifestPath, 'utf8')).version}`;
+        }
+        catch { /* the version is only named */ }
+        return fail(`this project is already on Meridian${at} (.meridian/manifest.json): run npx zz-meridian@latest update to move it to this release`);
+    }
     const pkg = JSON.parse(fs.readFileSync(pkgPath, 'utf8'));
     const deps = { ...pkg.dependencies, ...pkg.devDependencies };
     const dir = appDir(root);
@@ -257,28 +299,13 @@ 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)`);
-            }
-        }
-    };
-    merge('dependencies', DEPS);
-    merge('devDependencies', DEV_DEPS);
+    // 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);
+    notes.push(...adoptDependencies(pkg, tpl, 'dependencies', needOf(tpl, sources).runtime));
+    notes.push(...adoptDependencies(pkg, tpl, 'devDependencies', TOOLCHAIN));
     pkg.scripts ??= {};
-    for (const s of SCRIPTS) {
+    for (const s of MERIDIAN_SCRIPTS) {
         const want = tpl.scripts[s];
         if (!pkg.scripts[s])
             pkg.scripts[s] = want;
@@ -364,8 +391,11 @@ Rename or move them, then run adopt again.`);
     const brandDirs = () => ['tokens', 'src/styles'].flatMap((d) => listFiles(root, d));
     const existed = new Set(brandDirs());
     const b = run(process.execPath, ['scripts/brand.ts', ...brandArgs(brand), '--existing'], root);
-    if (b.status !== 0)
-        return fail('scripts/brand.ts failed (above); the files are copied, so fix the cause and run it again with the same flags');
+    if (b.status !== 0) {
+        // From a clean tree, git takes back exactly what adopt wrote; with --allow-dirty it would take the team's changes too.
+        const back = o.allowDirty ? 'remove what adopt wrote (git status shows it beside your own changes)' : 'put the tree back (git restore . && git clean -fd removes only what adopt wrote, since it started clean)';
+        return fail(`scripts/brand.ts failed (above) after the files were copied, and the manifest and agent files are not written. Fix the cause, ${back}, and run zz-meridian adopt again with the same flags`);
+    }
     // The project's own AGENTS.md keeps every byte and gains the managed block; the brief is the team's, written only when absent.
     // Neither is a Meridian file, so neither is recorded in the manifest.
     const pm = packageManager(root);
@@ -390,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

@@ -5,9 +5,8 @@
  */
 import os from 'node:os';
 import path from 'node:path';
-import { parseArgs } from 'node:util';
 import { adopt } from './adopt.js';
-import { misapplied } from './command-flags.js';
+import { misapplied, readFlags } from './command-flags.js';
 import { create } from './create.js';
 import { BRAND_FLAGS, VERSION, installSkill } from './files.js';
 import { brandCommand } from './rebrand.js';
@@ -38,31 +37,20 @@ 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 { values, positionals } = parseArgs({
-    allowPositionals: true,
-    options: {
-        ...Object.fromEntries(BRAND_FLAGS.map((f) => [f, { type: 'string' }])),
-        'allow-dirty': { type: 'boolean' },
-        'no-install': { type: 'boolean' },
-        'dry-run': { type: 'boolean' },
-        resume: { type: 'boolean' },
-        finalize: { type: 'boolean' },
-        abort: { type: 'boolean' },
-        verify: { type: 'boolean' },
-        verbose: { type: 'boolean' },
-        global: { type: 'boolean' },
-        help: { type: 'boolean', short: 'h' },
-        version: { type: 'boolean', short: 'v' },
-    },
-});
-const flags = values;
+const read = readFlags(process.argv.slice(2));
+if ('error' in read) {
+    console.error(`zz-meridian: ${read.error}. zz-meridian --help lists the commands and their flags.`);
+    process.exit(1);
+}
+const { values: flags, positionals } = read;
 const brand = Object.fromEntries(BRAND_FLAGS.flatMap((f) => (typeof flags[f] === 'string' ? [[f, flags[f]]] : [])));
-const install = !values['no-install'];
+const install = !flags['no-install'];
 const [command, arg] = positionals;
 function main() {
-    if (values.version) {
+    if (flags.version) {
         console.log(VERSION);
         return 0;
     }
@@ -72,9 +60,9 @@ function main() {
         console.error(`zz-meridian: --${unsafe[0]} may not contain a backslash or a line break`);
         return 1;
     }
-    if (values.help || !command) {
+    if (flags.help || !command) {
         console.log(HELP);
-        return command || values.help ? 0 : 1;
+        return command || flags.help ? 0 : 1;
     }
     // A flag a command does not read is refused, never ignored: `adopt --dry-run` wrote the project rather than previewing it.
     const wrong = misapplied(command, flags);
@@ -82,8 +70,13 @@ 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(values['allow-dirty']), install });
+        return adopt({ root: process.cwd(), brand, allowDirty: Boolean(flags['allow-dirty']), install });
     if (command === 'create') {
         if (!arg) {
             console.error('zz-meridian create: name the folder for the new dashboard');
@@ -92,26 +85,32 @@ function main() {
         return create({ dir: arg, brand, install });
     }
     if (command === 'update') {
-        const modes = ['dry-run', 'resume', 'finalize', 'abort'].filter((m) => values[m]);
+        const modes = ['dry-run', 'resume', 'finalize', 'abort'].filter((m) => flags[m]);
         if (modes.length > 1) {
             console.error(`zz-meridian update: ${modes.map((m) => `--${m}`).join(' and ')} cannot be combined`);
             return 1;
         }
-        if (values.verify && !values.finalize) {
+        if (flags.verify && !flags.finalize) {
             console.error('zz-meridian update: --verify belongs to --finalize');
             return 1;
         }
         const mode = modes[0] ?? 'update';
-        return update({ root: process.cwd(), mode, flags: { verbose: Boolean(values.verbose), allowDirty: Boolean(values['allow-dirty']), install, verify: Boolean(values.verify) } });
+        return update({ root: process.cwd(), mode, flags: { verbose: Boolean(flags.verbose), allowDirty: Boolean(flags['allow-dirty']), install, verify: Boolean(flags.verify) } });
     }
     if (command === 'brand')
-        return brandCommand({ root: process.cwd(), flags: brand, allowDirty: Boolean(values['allow-dirty']) });
+        return brandCommand({ root: process.cwd(), flags: brand, allowDirty: Boolean(flags['allow-dirty']) });
     if (command === 'skill') {
-        const roots = values.global ? [os.homedir()] : [process.cwd()];
-        for (const r of roots)
-            installSkill(r);
+        const roots = flags.global ? [os.homedir()] : [process.cwd()];
+        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 ${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(`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.`);
         return 0;
     }

package/dist/command-flags.js

@@ -3,7 +3,39 @@
  * else it is refused by name rather than accepted and ignored, so `adopt --dry-run` never modifies a project while the
  * person waits for a preview.
  */
+import { parseArgs } from 'node:util';
 import { BRAND_FLAGS } from './files.js';
+/**
+ * The command line, read: its flags and positionals, or the reason it cannot be read (an unknown flag, a value-less one),
+ * as one line for the person rather than a stack trace.
+ */
+export function readFlags(args) {
+    try {
+        const { values, positionals } = parseArgs({
+            args,
+            allowPositionals: true,
+            options: {
+                ...Object.fromEntries(BRAND_FLAGS.map((f) => [f, { type: 'string' }])),
+                'allow-dirty': { type: 'boolean' },
+                'no-install': { type: 'boolean' },
+                'dry-run': { type: 'boolean' },
+                resume: { type: 'boolean' },
+                finalize: { type: 'boolean' },
+                abort: { type: 'boolean' },
+                verify: { type: 'boolean' },
+                verbose: { type: 'boolean' },
+                global: { type: 'boolean' },
+                help: { type: 'boolean', short: 'h' },
+                version: { type: 'boolean', short: 'v' },
+            },
+        });
+        return { values: { ...values }, positionals };
+    }
+    catch (e) {
+        // Node's first sentence names the flag; the rest is about positionals that start with a dash.
+        return { error: e.message.split('. ')[0] };
+    }
+}
 /** Every command reads these. */
 const EVERYWHERE = ['help', 'version'];
 /** The brand flags, read by the commands that write a brand. */

package/dist/context.js

@@ -41,8 +41,8 @@ Brand, layout and behaviour choices already made, one line each with its reason,
 ## Glossary
 The team's own words for things, one per line: term and what it means here.
 `;
-/** One `pnpm <script> [flags]` command, spelled for the package manager; npm needs `--` before flags. */
-function command(pm, script, flags) {
+/** A package script with flags, as the package manager runs it: npm passes flags on only after `--`. */
+export function command(pm, script, flags) {
     if (pm === 'pnpm')
         return `pnpm ${script}${flags}`;
     if (pm === 'npm')

package/dist/create.js

@@ -6,10 +6,12 @@
 import fs from 'node:fs';
 import path from 'node:path';
 import { managedPaths } from './ownership.js';
-import { BRIEF_TEMPLATE, managedBlock, upsertManagedBlock } from './context.js';
+import { BRIEF_TEMPLATE, command, managedBlock, upsertManagedBlock } from './context.js';
 import { VERSION, brandArgs, effectiveBrand, hasCommand, inside, installSkill, payloadBytes, payloadFiles, run, sha256, writeIn, writeManifest } from './files.js';
 export function create(o) {
     const root = path.resolve(o.dir);
+    if (fs.existsSync(root) && !fs.statSync(root).isDirectory())
+        return fail(`${root} is a file: name a new folder`);
     if (fs.existsSync(root) && fs.readdirSync(root).length)
         return fail(`${root} exists and is not empty: name a new folder`);
     let brand;
@@ -27,7 +29,7 @@ export function create(o) {
     const name = brand.name ?? path.basename(root).replace(/[-_]+/g, ' ').replace(/\b\w/g, (c) => c.toUpperCase());
     brand = effectiveBrand({ ...brand, name });
     if (run(process.execPath, ['scripts/brand.ts', ...brandArgs(brand), '--product'], root).status !== 0) {
-        return fail('scripts/brand.ts failed (above); the template is copied, so fix the cause and run it again with the same flags');
+        return fail(`scripts/brand.ts failed (above). ${root} holds the unbranded template and nothing else: fix the cause, delete the folder and run zz-meridian create again with the same flags`);
     }
     // pnpm installs from the template's lockfile, with install scripts off (pnpm-workspace.yaml). Without pnpm, corepack
     // (bundled with Node 22) runs it; only without both does npm install, from the version ranges, with scripts off too.
@@ -71,16 +73,20 @@ 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)
 
-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 --timed ends with "the project meets the
-Meridian standard" and no view on the scoreboard is Weak.`);
+${nextStep(pm)}`);
     return 0;
 }
+/** What the person does next, with the full verify written so their package manager passes its flags on. */
+export function nextStep(pm) {
+    return `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 ${command(pm, 'verify', ' --full --timed')} ends with "the project meets the
+Meridian standard" and no view on the scoreboard is Weak.`;
+}
 function fail(msg) {
     console.error(`zz-meridian create: ${msg}`);
     return 1;

package/dist/files.js

@@ -7,7 +7,7 @@ import { spawnSync } from 'node:child_process';
 import fs from 'node:fs';
 import path from 'node:path';
 import { fileURLToPath } from 'node:url';
-/** The template snapshot this package carries, built from `git ls-files` at the release commit. */
+/** The template snapshot this package carries, extracted from the release commit by `git archive` (cli/scripts/build-payload.ts). */
 export const PAYLOAD = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..', 'payload');
 export const VERSION = JSON.parse(fs.readFileSync(path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..', 'package.json'), 'utf8')).version;
 /**
@@ -73,6 +73,8 @@ export function writeIn(root, rel, content) {
     fs.writeFileSync(abs, content);
 }
 export const sha256 = (content) => `sha256-${createHash('sha256').update(content).digest('hex')}`;
+/** What a quiet command may print and still be read whole: past Node's 1 MiB default the child is killed, and a long gate reads as exit 1. */
+const OUTPUT = 256 * 1024 * 1024;
 /**
  * A command with its arguments, without a shell, so nothing in a name or a path is ever interpreted. The one exception
  * is a Windows .cmd shim (npm, pnpm, tsc), which Node runs only through a shell: those calls pass fixed arguments
@@ -80,7 +82,7 @@ export const sha256 = (content) => `sha256-${createHash('sha256').update(content
  */
 export function run(cmd, args, cwd, quiet = false) {
     const shim = process.platform === 'win32' && cmd !== process.execPath;
-    return spawnSync(shim && cmd.includes(' ') ? `"${cmd}"` : cmd, args, { cwd, encoding: 'utf8', stdio: quiet ? 'pipe' : 'inherit', shell: shim });
+    return spawnSync(shim && cmd.includes(' ') ? `"${cmd}"` : cmd, args, { cwd, encoding: 'utf8', stdio: quiet ? 'pipe' : 'inherit', shell: shim, maxBuffer: OUTPUT });
 }
 /** The package manager a project already uses, from its lockfile; npm when it has none. */
 export function packageManager(root) {
@@ -99,7 +101,7 @@ export function packageManager(root) {
 export const installArgs = (pm) => (pm === 'pnpm' ? ['install', '--no-frozen-lockfile'] : ['install']);
 /** A tool in the project's node_modules, run as `node <its script>`: no shell and no .cmd shim on any platform. */
 export function runTool(root, entry, args, quiet = true) {
-    return spawnSync(process.execPath, [path.join(root, 'node_modules', entry), ...args], { cwd: root, encoding: 'utf8', stdio: quiet ? 'pipe' : 'inherit' });
+    return spawnSync(process.execPath, [path.join(root, 'node_modules', entry), ...args], { cwd: root, encoding: 'utf8', stdio: quiet ? 'pipe' : 'inherit', maxBuffer: OUTPUT });
 }
 export const hasCommand = (cmd) => spawnSync(cmd, ['--version'], { stdio: 'ignore', shell: process.platform === 'win32' }).status === 0;
 /** A JSONC document's text with the comments dropped, and whether anything had to be dropped to read it. */
@@ -138,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. */
@@ -164,9 +167,16 @@ export function relativeImports(rel, source) {
         return `${lead}${q}${to}${q}`;
     });
 }
+/**
+ * The manifest file as every writer writes it: paths sorted by code unit (never the machine's collation), two-space
+ * indent, a final newline. Finalize tells an interrupted rename by comparing the file with this, byte for byte.
+ */
+export function manifestText(m) {
+    const files = Object.fromEntries(Object.entries(m.files).sort(([a], [b]) => (a < b ? -1 : 1)));
+    return `${JSON.stringify({ ...m, files }, null, 2)}\n`;
+}
 export function writeManifest(root, m) {
-    const sorted = Object.fromEntries(Object.entries(m.files).sort(([a], [b]) => a.localeCompare(b)));
-    writeIn(root, '.meridian/manifest.json', JSON.stringify({ ...m, files: sorted }, null, 2) + '\n');
+    writeIn(root, '.meridian/manifest.json', manifestText(m));
 }
 /**
  * Where the skill goes: the folders each agent reads in a repository, Codex (`.agents`) and Claude Code (`.claude`), and
@@ -175,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);
     }