zz-meridian 0.3.0 → 0.5.0

package/README.md

@@ -16,15 +16,18 @@ Give your coding agent (Codex, Claude Code, or any agent that can run a shell) t
 ```sh
 npx zz-meridian@latest adopt [brand flags]        # bring Meridian into this Next.js App Router project
 npx zz-meridian@latest create <dir> [brand flags] # start a new dashboard
+npx zz-meridian@latest update [--dry-run] [--verbose] # update this project (the dry-run writes nothing)
+npx zz-meridian@<version> brand [brand flags]     # rebrand this project, with the version in .meridian/manifest.json
 npx zz-meridian@latest skill [--global]           # install only the agent skill
 ```
 
-Brand flags: `--name "Acme Ops"`, `--hex '#2E6BE4'` (or `--accent indigo|cobalt|jade|graphite`), `--workspace`,
-`--timezone`, `--currency`, `--user`, `--role`.
+Brand flags: `--name "Acme Ops"`, `--hex '#2E6BE4'` (or `--accent indigo|cobalt|jade|graphite`), `--theme dark|light`,
+`--workspace`, `--timezone`, `--currency`, `--user`, `--role`.
 
 **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`; replaces your global stylesheet (yours is kept
-beside it as `*.before.css`); brands it; appends Meridian's rules to your `AGENTS.md`; installs the skill into
+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
+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 copied file 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
@@ -36,7 +39,31 @@ the project is not Next.js with the App Router, or when a file it would copy alr
 **create** copies the template into a new folder, branded as your product, with the Design Atlas and the design
 system's own documents left out.
 
-Requires Node 22.18 or newer. The checks (`pnpm verify`) also need Google Chrome.
+**update** moves a project adopted or created with 0.3.0 or later to this release. `update --dry-run` shows the plan and
+writes nothing; run it first.
+- It fetches the release the project was copied from, checks it against the registry's integrity record, and replays
+  that release and this one in a scratch folder. If a file the manifest recorded does not match the replay, it stops.
+- It replaces every Meridian file you have not touched, adds the new ones and removes the retired ones. A file you edited,
+  deleted or kept (`.meridian/keep.json`) is never overwritten: an edited or deleted one is staged as base/ours/new copies
+  for you to merge.
+- It adds the dependencies and scripts this release needs to `package.json` and updates Meridian's managed block in
+  `AGENTS.md`; a version or script you chose yourself becomes a migration to resolve, never a silent change.
+- It reports a migration for each interface the release changed where one of your own files still has the old shape;
+  moving to 0.5.0 can report ten, such as `cache-components-config`. Resolve them as the skill's
+  `references/update.md` says; `docs/distribution.md` lists 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.
+- It refuses, writing nothing, on a dirty git tree (unless `--allow-dirty`) or while another update is open. `--verbose`
+  lists every file.
+
+**brand** changes the brand of a project built on Meridian with no hand edits: it rebuilds the brand outputs (tokens and
+styles) and `src/app.config.ts` for the new flags and records them in the manifest together, or changes nothing. It
+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.
+
+Requires Node 22.18 or newer. The default `pnpm verify` runs without Google Chrome and reports the browser checks as not run; `--full` and `--perf` need it.
 
 ## What this package does not do
 

package/dist/adopt.js

@@ -8,25 +8,11 @@
  */
 import fs from 'node:fs';
 import path from 'node:path';
-import { PAYLOAD, VERSION, brandArgs, inside, installSkill, packageManager, payloadFiles, readJsonc, readPayload, relativeImports, run, runTool, sha256, writeIn, writeManifest, } from './files.js';
-/** The library modules Meridian's components and gates import; the rest of src/lib belongs to the template's pages. */
-const LIB = ['cn', 'format', 'format-date', 'period', 'color', 'host', 'preferences', 'csv', 'safe-markdown'].map((n) => `src/lib/${n}.ts`);
-/** What adopt copies from the template, as payload paths. The fixture build in CI is what keeps this list complete. */
-export function adoptSet() {
-    const own = (f) => !/(^|\/)(README\.md|preview\.tsx)$/.test(f);
-    return [
-        ...payloadFiles('tokens'),
-        ...payloadFiles('src/styles'),
-        ...payloadFiles('src/components').filter(own),
-        ...payloadFiles('scripts').filter((f) => f !== 'scripts/verify.config.ts'),
-        ...LIB,
-        'src/lib/assistant/prompt.ts',
-        'src/views/console-chrome.tsx',
-        'tests/setup.ts',
-    ];
-}
+import { PAYLOAD, VERSION, brandArgs, effectiveBrand, inside, installSkill, packageManager, payloadFiles, readJsonc, readPayload, relativeImports, 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'];
+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/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);
@@ -45,6 +31,22 @@ function exactImports(rel, source, known) {
     };
     return relativeImports(rel, source).replace(/(\bfrom\s*|\bimport\s*\(\s*|\bimport\s+)(['"])([\w@./()[\]-]+)\2/g, (_m, lead, q, spec) => `${lead}${q}${pin(spec)}${q}`);
 }
+/** Every file under one folder of the project, as posix paths; none when the folder is absent. */
+function listFiles(root, dir) {
+    const out = [];
+    const walk = (rel) => {
+        if (!fs.existsSync(path.join(root, rel)))
+            return;
+        for (const e of fs.readdirSync(path.join(root, rel), { withFileTypes: true })) {
+            if (e.isDirectory())
+                walk(`${rel}/${e.name}`);
+            else if (e.isFile())
+                out.push(`${rel}/${e.name}`);
+        }
+    };
+    walk(dir);
+    return out;
+}
 function appDir(root) {
     for (const d of ['app', 'src/app'])
         if (['tsx', 'jsx', 'ts', 'js'].some((x) => fs.existsSync(path.join(root, d, `layout.${x}`))))
@@ -128,7 +130,18 @@ https://github.com/zhixuan312/zz-meridian/blob/master/skills/zz-meridian/referen
         if (git.stdout.trim())
             return fail('the git tree has uncommitted changes. Commit or stash them first, so adopt\'s change is one reviewable diff (or pass --allow-dirty).');
     }
-    const set = adoptSet();
+    let brand;
+    try {
+        brand = effectiveBrand(o.brand);
+    }
+    catch (e) {
+        return fail(e.message);
+    }
+    const all = payloadFiles();
+    const missing = FIXED.filter((f) => !all.includes(f));
+    if (missing.length)
+        return fail(`this package's template is missing files adopt needs, so nothing was written:\n${missing.map((m) => `  ${m}`).join('\n')}\nReinstall zz-meridian, or report this if it persists.`);
+    const set = adoptSetOf(all);
     const known = new Set(set);
     const writes = new Map();
     const owned = [];
@@ -257,18 +270,39 @@ Rename or move them, then run adopt again.`);
     }
     for (const [rel, content] of writes)
         writeIn(root, rel, content);
-    const name = o.brand.name ?? String(pkg.name ?? path.basename(root)).replace(/^@[^/]+\//, '').replace(/[-_]+/g, ' ').replace(/\b\w/g, (c) => c.toUpperCase());
-    const brand = { ...o.brand, name };
+    const name = brand.name ?? String(pkg.name ?? path.basename(root)).replace(/^@[^/]+\//, '').replace(/[-_]+/g, ' ').replace(/\b\w/g, (c) => c.toUpperCase());
+    brand = effectiveBrand({ ...brand, name });
+    // The brand outputs this run creates under tokens/ and src/styles/ (absent before it) are Meridian's, so the manifest records them.
+    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');
+    // 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);
+    const agentsAbs = path.join(root, 'AGENTS.md');
+    try {
+        const text = fs.existsSync(agentsAbs) ? fs.readFileSync(agentsAbs, 'utf8') : '';
+        writeIn(root, 'AGENTS.md', upsertManagedBlock(text, managedBlock(VERSION, pm)));
+    }
+    catch (e) {
+        return fail(`AGENTS.md: ${e.message} The files are copied; fix AGENTS.md by hand, then add the managed block.`);
+    }
+    const briefWritten = !fs.existsSync(path.join(root, 'docs/brief.md'));
+    if (briefWritten)
+        writeIn(root, 'docs/brief.md', BRIEF_TEMPLATE);
+    const generated = brandDirs().filter((f) => !existed.has(f));
+    if (owned.includes('scripts/package.json'))
+        generated.push('scripts/package.json');
+    const managed = managedPaths(all, 'adopt', generated);
     const files = {};
-    for (const rel of owned)
-        files[rel] = sha256(fs.readFileSync(inside(root, rel)));
+    for (const rel of [...owned, ...generated])
+        if (managed.has(rel))
+            files[rel] = sha256(fs.readFileSync(inside(root, rel)));
     installSkill(root, files);
     writeManifest(root, { version: VERSION, route: 'adopt', brand, files });
     // ── Install and prove it compiles ─────────────────────────────────────────────────────────────────────
-    const pm = packageManager(root);
     let typed = 'not run (--no-install)';
     if (o.install) {
         say(`\nInstalling with ${pm}…`);
@@ -283,6 +317,7 @@ Rename or move them, then run adopt again.`);
 Meridian ${VERSION} is in ${root}.
   copied: ${owned.length} files (recorded in .meridian/manifest.json)
   skill: .agents/skills/zz-meridian (Codex) and .claude/skills/zz-meridian (Claude Code)
+  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

package/dist/cli.js

@@ -9,6 +9,8 @@ import { parseArgs } from 'node:util';
 import { adopt } from './adopt.js';
 import { create } from './create.js';
 import { BRAND_FLAGS, VERSION, installSkill } from './files.js';
+import { brandCommand } from './rebrand.js';
+import { update } from './update.js';
 const HELP = `zz-meridian ${VERSION}
 
   npx zz-meridian@latest adopt [brand flags] [--allow-dirty] [--no-install]
@@ -17,6 +19,19 @@ const HELP = `zz-meridian ${VERSION}
   npx zz-meridian@latest create <dir> [brand flags] [--no-install]
       Start a new dashboard on Meridian in <dir>.
 
+  npx zz-meridian@latest update --dry-run [--verbose]
+      Show what updating this project to the running version would change, and what needs your decision. Writes nothing.
+
+  npx zz-meridian@latest update [--allow-dirty] [--no-install] [--verbose]
+      Apply the safe changes, stage everything you changed with base/ours/new copies, and write .meridian/update/<version>/MERGE.md.
+
+  npx zz-meridian@<version> update --resume [--no-install] | --finalize [--verify] | --abort
+      Continue, complete or roll back the update in progress. Use the version named in MERGE.md.
+
+  npx zz-meridian@<installed version> brand [brand flags] [--allow-dirty]
+      Change this project's brand with no hand edits: the brand outputs, src/app.config.ts and the manifest move together, or nothing changes.
+      Use the version in .meridian/manifest.json; a project on an older release runs update first.
+
   npx zz-meridian@latest skill [--global]
       Install only the agent skill: into this project, or for every project (~/.agents/skills, ~/.claude/skills).
 
@@ -30,6 +45,12 @@ const { values, positionals } = parseArgs({
         ...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' },
@@ -63,6 +84,21 @@ function main() {
         }
         return create({ dir: arg, brand, install });
     }
+    if (command === 'update') {
+        const modes = ['dry-run', 'resume', 'finalize', 'abort'].filter((m) => values[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) {
+            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) } });
+    }
+    if (command === 'brand')
+        return brandCommand({ root: process.cwd(), flags: brand, allowDirty: Boolean(values['allow-dirty']) });
     if (command === 'skill') {
         const roots = values.global ? [os.homedir()] : [process.cwd()];
         for (const r of roots)

package/dist/context.js

@@ -0,0 +1,82 @@
+/**
+ * The agent-facing context a project carries: the frozen managed block in `AGENTS.md` and the brief template.
+ * Pure text in, text out; the caller does the reading and writing.
+ */
+export const BEGIN = '<!-- BEGIN:zz-meridian-agent-rules -->';
+export const END = '<!-- END:zz-meridian-agent-rules -->';
+const BLOCK = `${BEGIN}
+# Built on ZZ Meridian <version>
+
+Follow the zz-meridian skill in \`.agents/skills/zz-meridian/SKILL.md\`.
+Read \`optional:docs/brief.md\` for this team's product, users, data and decisions.
+When it is absent, use the skill's brief template with the person's answers; do not invent product facts.
+
+- What is yours: product pages, data, other team files, \`src/app.config.ts\` and \`scripts/verify.config.ts\`.
+  Managed paths are recorded in \`.meridian/manifest.json\`; declared kept divergences are in
+  \`optional:.meridian/keep.json\`. Explicit shared-file operations are described by the skill.
+- Extend rather than edit: follow \`.agents/skills/zz-meridian/references/customize.md\`.
+- Update: follow \`.agents/skills/zz-meridian/references/update.md\`. Installed files do not mean a completed
+  upgrade: resolve the report and run the pinned finalization command.
+- Before finishing: safely configured \`pnpm verify\` for the default gate/build/smoke path; report any partial coverage.
+  Use \`pnpm gate\` alone for static feedback. Do not automatically chain it before verify, which already runs it.
+  Use \`pnpm verify --full\` or \`pnpm verify --perf\` when deep checks are requested; release CI runs both.
+- Agents in the product read through authorized collections and write only through an approved Proposal.
+${END}`;
+/** The brief a team keeps at `docs/brief.md`; its guidance lines equal `BRIEF_GUIDANCE` in the assistant prompt. */
+export const BRIEF_TEMPLATE = `# Product name
+
+## Product
+What this dashboard is for, in two or three sentences: who opens it, what decision it helps them make.
+
+## Users
+Who uses it and how often; what they know already; what they must never be shown.
+
+## Data
+Where the numbers come from (systems, tables, APIs), how fresh they are, and what now means for this product.
+
+## Decisions
+Brand, layout and behaviour choices already made, one line each with its reason, so no session re-decides them.
+
+## 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) {
+    if (pm === 'pnpm')
+        return `pnpm ${script}${flags}`;
+    if (pm === 'npm')
+        return `npm run ${script}${flags ? ` --${flags}` : ''}`;
+    return `${pm === 'bun' ? 'bun run' : 'yarn'} ${script}${flags}`;
+}
+/** The frozen managed block for a version, with every script command in the project's package manager. */
+export function managedBlock(version, pm) {
+    return BLOCK.replace('<version>', () => version).replace(/`pnpm ([a-z]+)((?: [^`]+)?)`/g, (_m, script, flags) => `\`${command(pm, script, flags)}\``);
+}
+const count = (text, needle) => text.split(needle).length - 1;
+/** Put the block into an `AGENTS.md` text: replace the marked span, else an exact legacy section, else append. Refuses anything ambiguous. */
+export function upsertManagedBlock(text, block, legacy) {
+    const begins = count(text, BEGIN);
+    const ends = count(text, END);
+    const legacies = legacy ? count(text, legacy) : 0;
+    if (begins > 1 || ends > 1)
+        throw new Error('AGENTS.md has a duplicate managed block marker; remove the extra one and run again.');
+    if (legacies > 1)
+        throw new Error('AGENTS.md has a duplicate legacy section; remove the extra copy and run again.');
+    const begin = text.indexOf(BEGIN);
+    const end = text.indexOf(END);
+    if (begins !== ends || end < begin)
+        throw new Error('AGENTS.md has an unterminated managed block; each marker needs its partner, BEGIN first.');
+    if (begins === 1 && legacies === 1)
+        throw new Error('AGENTS.md has both a managed block and a legacy section; remove one and run again.');
+    if (begins === 1)
+        return text.slice(0, begin) + block + text.slice(end + END.length);
+    if (legacy && legacies === 1) {
+        const at = text.indexOf(legacy);
+        return text.slice(0, at) + block + text.slice(at + legacy.length);
+    }
+    if (legacy && text.includes(legacy.split('\n')[0]))
+        throw new Error('AGENTS.md has an edited legacy section; replace it by hand with the managed block.');
+    if (text === '')
+        return `${block}\n`;
+    return `${text}${text.endsWith('\n') ? '' : '\n'}\n${block}\n`;
+}

package/dist/create.js

@@ -5,18 +5,27 @@
  */
 import fs from 'node:fs';
 import path from 'node:path';
-import { PAYLOAD, VERSION, brandArgs, hasCommand, inside, installSkill, payloadFiles, run, sha256, writeIn, writeManifest } from './files.js';
+import { managedPaths } from './ownership.js';
+import { BRIEF_TEMPLATE, managedBlock, upsertManagedBlock } from './context.js';
+import { PAYLOAD, VERSION, brandArgs, effectiveBrand, hasCommand, inside, installSkill, payloadFiles, run, sha256, writeIn, writeManifest } from './files.js';
 export function create(o) {
     const root = path.resolve(o.dir);
     if (fs.existsSync(root) && fs.readdirSync(root).length)
         return fail(`${root} exists and is not empty: name a new folder`);
+    let brand;
+    try {
+        brand = effectiveBrand(o.brand);
+    }
+    catch (e) {
+        return fail(e.message);
+    }
     for (const rel of payloadFiles()) {
         if (rel.startsWith('skills/'))
             continue;
         writeIn(root, rel, fs.readFileSync(path.join(PAYLOAD, rel)));
     }
-    const name = o.brand.name ?? path.basename(root).replace(/[-_]+/g, ' ').replace(/\b\w/g, (c) => c.toUpperCase());
-    const brand = { ...o.brand, name };
+    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');
     }
@@ -29,6 +38,15 @@ export function create(o) {
             fs.rmSync(path.join(root, f), { force: true });
         console.log('pnpm is not available: installing with npm from the version ranges, without a lockfile.');
     }
+    // The managed block goes in only now that the installer is known, so its commands match; the template's own lines
+    // above `# Working in Meridian` stay. The brief is the template. The manifest walk below records both.
+    try {
+        writeIn(root, 'AGENTS.md', upsertManagedBlock(fs.readFileSync(path.join(root, 'AGENTS.md'), 'utf8'), managedBlock(VERSION, pm)));
+    }
+    catch (e) {
+        return fail(`AGENTS.md: ${e.message}`);
+    }
+    writeIn(root, 'docs/brief.md', BRIEF_TEMPLATE);
     const files = {};
     const walk = (rel) => {
         for (const e of fs.readdirSync(inside(root, rel || '.'), { withFileTypes: true })) {
@@ -42,6 +60,12 @@ export function create(o) {
         }
     };
     walk('');
+    // The managed set over what is on disk after branding: the payload rule for the files still there, plus the brand outputs.
+    const onDisk = Object.keys(files);
+    const managed = managedPaths([...payloadFiles().filter((f) => f.startsWith('skills/') || onDisk.includes(f))], 'create', onDisk);
+    for (const rel of onDisk)
+        if (!managed.has(rel))
+            delete files[rel];
     installSkill(root, files);
     writeManifest(root, { version: VERSION, route: 'create', brand, files });
     if (hasCommand('git'))

package/dist/files.js

@@ -140,5 +140,12 @@ export function installSkill(root, record) {
     }
 }
 /** Brand flags passed through to scripts/brand.ts, in the order it reads them. */
-export const BRAND_FLAGS = ['name', 'workspace', 'timezone', 'currency', 'user', 'role', 'accent', 'hex', 'hue', 'chroma'];
+export const BRAND_FLAGS = ['name', 'workspace', 'timezone', 'currency', 'user', 'role', 'theme', 'accent', 'hex', 'hue', 'chroma'];
 export const brandArgs = (brand) => BRAND_FLAGS.flatMap((k) => (brand[k] ? [`--${k}`, brand[k]] : []));
+/** The brand a run effectively applied: one accent choice (hex over hue over a preset), flags in order, empty ones dropped. */
+export function effectiveBrand(flags) {
+    if (flags.theme && flags.theme !== 'dark' && flags.theme !== 'light')
+        throw new Error(`--theme must be dark or light, got ${JSON.stringify(flags.theme)}`);
+    const drop = flags.hex ? ['hue', 'chroma', 'accent'] : flags.hue ? ['accent'] : [];
+    return Object.fromEntries(BRAND_FLAGS.flatMap((k) => (flags[k] && !drop.includes(k) ? [[k, flags[k]]] : [])));
+}

package/dist/inventory.js

@@ -0,0 +1,131 @@
+/**
+ * The typed inventory finalize validates against: every path the checks must leave alone (protected inputs), and the
+ * few outputs a gate and a build are expected to write (permitted outputs). A fingerprint is existence plus a SHA-256
+ * and lives in memory only; the inventory is never written anywhere, and only the names of changed paths are reported.
+ */
+import fs from 'node:fs';
+import path from 'node:path';
+import { readJsonc, run, sha256 } from './files.js';
+/** Folders that are never walked: the repository, dependency contents, and the updater's own state. */
+const SKIPPED_DIRS = new Set(['.git', 'node_modules']);
+const UPDATER = ['.meridian/update', '.meridian/history', '.meridian/update.lock'];
+const NEXT_CONFIGS = ['next.config.ts', 'next.config.mts', 'next.config.js', 'next.config.mjs', 'next.config.cjs'];
+const overlaps = (a, b) => a === b || a.startsWith(`${b}/`) || b.startsWith(`${a}/`);
+/** The Next build folder: `distDir` when `next.config` sets it as a string literal, else `.next`. */
+function distDir(root) {
+    for (const name of NEXT_CONFIGS) {
+        const file = path.join(root, name);
+        if (!fs.existsSync(file))
+            continue;
+        const m = /\bdistDir\s*:\s*(['"`])([^'"`$]+)\1/.exec(fs.readFileSync(file, 'utf8'));
+        if (m)
+            return m[2];
+    }
+    return '.next';
+}
+/** The build-info file TypeScript writes: the configured one, or `tsconfig.tsbuildinfo` when the build is incremental. */
+function buildInfo(root) {
+    let options;
+    try {
+        options = readJsonc(path.join(root, 'tsconfig.json')).compilerOptions ?? {};
+    }
+    catch {
+        return null;
+    }
+    if (typeof options.tsBuildInfoFile === 'string')
+        return options.tsBuildInfoFile;
+    if (options.incremental !== true && options.composite !== true)
+        return null;
+    return `${typeof options.outDir === 'string' ? `${options.outDir.replace(/\/+$/, '')}/` : ''}tsconfig.tsbuildinfo`;
+}
+/** The permitted outputs, as project-relative posix paths. A path that leaves the project is reported as a conflict. */
+function outputsOf(root) {
+    const outputs = [];
+    const conflicts = [];
+    const add = (spec, directory) => {
+        const abs = path.resolve(root, spec);
+        const rel = path.relative(root, abs).split(path.sep).join('/');
+        if (rel === '' || rel.startsWith('..') || path.isAbsolute(rel))
+            conflicts.push(`${spec}: an output path outside the project is not exempt`);
+        else
+            outputs.push({ rel, directory });
+    };
+    add(distDir(root), true);
+    add('out', true);
+    add('coverage', true);
+    const info = buildInfo(root);
+    if (info)
+        add(info, false);
+    const env = path.join(root, 'next-env.d.ts');
+    const canonical = !fs.existsSync(env) || fs.readFileSync(env, 'utf8').includes('reference types="next');
+    if (canonical)
+        add('next-env.d.ts', false);
+    return { outputs, conflicts };
+}
+/** True when git tracks a file inside `dir`: an output folder that holds the team's own files is not an output. */
+function tracksFiles(root, dir) {
+    if (!fs.existsSync(path.join(root, '.git')))
+        return false;
+    const r = run('git', ['ls-files', '--', dir], root, true);
+    return r.status === 0 && (r.stdout ?? '').trim() !== '';
+}
+/** A symbolic link on the way to `rel` (or at `rel` itself), as the first such project-relative path. */
+function linkOn(root, rel) {
+    let cur = root;
+    for (const seg of rel.split('/')) {
+        cur = path.join(cur, seg);
+        if (fs.lstatSync(cur, { throwIfNoEntry: false })?.isSymbolicLink())
+            return path.relative(root, cur).split(path.sep).join('/');
+    }
+    return null;
+}
+/**
+ * Fingerprints every protected input under `root`. `managed` are the project paths Meridian manages or the team keeps:
+ * an output that overlaps one of them is a conflict, as is an output behind a symbolic link or holding tracked files.
+ */
+export function takeInventory(root, managed) {
+    const { outputs, conflicts } = outputsOf(root);
+    for (const o of outputs) {
+        const clash = managed.find((p) => overlaps(p, o.rel));
+        if (clash)
+            conflicts.push(`${o.rel}: an output path that overlaps ${clash}, a managed or kept file, is not exempt`);
+        const link = linkOn(root, o.rel);
+        if (link)
+            conflicts.push(`${link}: an output path that is a symbolic link is not exempt`);
+        else if (o.directory && tracksFiles(root, o.rel))
+            conflicts.push(`${o.rel}: an output folder that holds tracked files is not exempt`);
+    }
+    const exempt = new Set([...UPDATER, ...outputs.map((o) => o.rel)]);
+    const prints = new Map();
+    const walk = (rel) => {
+        for (const e of fs.readdirSync(path.join(root, rel), { withFileTypes: true })) {
+            const p = rel ? `${rel}/${e.name}` : e.name;
+            if (exempt.has(p))
+                continue;
+            const abs = path.join(root, p);
+            if (e.isDirectory()) {
+                if (!SKIPPED_DIRS.has(e.name))
+                    walk(p);
+            }
+            else if (e.isSymbolicLink())
+                prints.set(p, `link ${fs.readlinkSync(abs)}`);
+            else if (e.isFile())
+                prints.set(p, sha256(fs.readFileSync(abs)));
+            else
+                prints.set(p, 'special');
+        }
+    };
+    walk('');
+    return { prints, conflicts };
+}
+/** The paths that exist in only one inventory or differ between them, sorted. */
+export function changedPaths(before, after) {
+    const out = [];
+    for (const [p, h] of after.prints)
+        if (before.prints.get(p) !== h)
+            out.push(p);
+    for (const p of before.prints.keys())
+        if (!after.prints.has(p))
+            out.push(p);
+    return [...new Set(out)].sort();
+}

package/dist/merge-report.js

@@ -0,0 +1,87 @@
+/**
+ * `MERGE.md`: the report a person (or their agent) reads to finish an update. Pure text out of the journal, so the same
+ * session always renders the same report.
+ */
+import { isNewer } from './update.js';
+/** The sections of a changelog whose version is above `source`, `[Unreleased]` included, each with its own heading line. */
+export function changelogSections(changelog, source) {
+    const parts = changelog.split(/^(?=## \[)/m).filter((s) => s.startsWith('## ['));
+    return parts.filter((s) => {
+        const v = /^## \[([^\]]+)\]/.exec(s)[1];
+        return v === 'Unreleased' || (/^\d+\.\d+\.\d+$/.test(v) && isNewer(v, source));
+    }).map((s) => s.trimEnd());
+}
+/** A fence long enough that nothing inside the text can close it. */
+function fenced(text) {
+    const longest = Math.max(2, ...[...text.matchAll(/`+/g)].map((m) => m[0].length));
+    const fence = '`'.repeat(longest + 1);
+    return `${fence}markdown\n${text}\n${fence}`;
+}
+const json = (v) => `\`\`\`json\n${JSON.stringify(v, null, 2)}\n\`\`\``;
+/** The path of one staged copy, or `absent` when that side does not exist. */
+const copy = (session, folder, side, path) => (side.exists ? `\`${session}/${folder}/${path}\`` : '`absent`');
+const WHAT = {
+    edited: 'You edited this managed file and Meridian changed it too. Combine the two versions.',
+    collision: 'Meridian now ships this path and you already have a different file there. Decide which one stays, or combine them.',
+    removed: 'Meridian removed this file, and you edited it. Decide whether to delete it or keep it.',
+    'local-deletion': 'You deleted this managed file and Meridian still ships it. Decide whether it stays out or comes back.',
+};
+export function renderMergeReport(i) {
+    const j = i.journal;
+    const finalize = `npx zz-meridian@${j.targetVersion} update --finalize`;
+    const resume = `npx zz-meridian@${j.targetVersion} update --resume`;
+    const abort = `npx zz-meridian@${j.targetVersion} update --abort`;
+    const staged = j.operations.filter((o) => o.action === 'stage');
+    const out = [];
+    out.push(`# Update ${j.sourceVersion} to ${j.targetVersion}`, '');
+    out.push(`- Source: ${j.sourceVersion}`, `- Target: ${j.targetVersion}`, `- Route: ${j.route}`, `- Session: ${j.id}`, `- Phase: ${j.phase}`, `- Outcome: ${i.outcome}`, '');
+    out.push('Commands, pinned to the release that started this session:', '', '```', `${finalize}   # when every item below is resolved`, `${resume}     # after an interruption, or to run a skipped install`, `${abort}      # restore what the update changed and archive the session`, '```', '');
+    if (j.failure)
+        out.push('## Failure', '', j.failure, '');
+    out.push('## What needs you', '');
+    if (staged.length === 0 && j.migrations.length === 0)
+        out.push('Nothing was staged and no migration is required.', '');
+    out.push('Resolve each item, then record it in `resolutions.json` next to this file. A resolution is an object with the item id, `resolved`, a reason in a sentence, and the hash each named file has right now. Compute a hash as `sha256-` plus the file\'s SHA-256 (`shasum -a 256 <file>`), or `null` for a file that is absent. A file edited after its resolution needs a new one.', '');
+    for (const o of staged)
+        out.push(...stagedItem(i, o));
+    for (const m of j.migrations) {
+        out.push(`### migration:${m.id}`, '', m.summary, '', `Paths: ${m.paths.map((p) => `\`${p}\``).join(', ') || 'none'}`, '', m.instructions, '');
+        if (m.checks.length)
+            out.push('Checks:', '', ...m.checks.map((c) => `- \`${c}\``), '');
+        out.push('Resolve with `resolved` or `not-applicable`:', '', json({ id: `migration:${m.id}`, status: 'resolved', reason: '', files: Object.fromEntries(m.paths.map((p) => [p, i.hashOf(p)])) }), '');
+    }
+    const warnings = [
+        ...i.keepWarnings,
+        ...j.operations.filter((o) => o.disposition === 'retired-kept').map((o) => `${o.path}: Meridian removed this file; your kept copy stays and is now yours alone. It is recorded as retired.`),
+    ];
+    out.push('## Kept and retired files', '');
+    out.push(...(warnings.length ? warnings.map((w) => `- ${w}`) : ['None.']), '');
+    const team = [...new Set([...j.operations.filter((o) => o.disposition === 'team-preserved' && o.action === 'write').map((o) => o.path), ...j.migrations.flatMap((m) => m.paths)])].sort();
+    out.push('## Team files this update touches or asks you to review', '');
+    out.push(...(team.length ? team.map((p) => `- \`${p}\``) : ['None.']), '', 'Meridian changes a team file only where it says so here: `package.json` (dependencies and scripts), `AGENTS.md` (the managed block) and the lockfile after an install. Everything else is advice in the items above.', '');
+    const counts = new Map();
+    for (const o of j.operations)
+        counts.set(`${o.disposition}/${o.action}`, (counts.get(`${o.disposition}/${o.action}`) ?? 0) + 1);
+    out.push('## Every disposition', '', ...[...counts].sort().map(([k, n]) => `- ${k}: ${n}`), '', '<details><summary>Every path</summary>', '', '```');
+    for (const o of j.operations)
+        out.push(`${o.disposition.padEnd(15)}  ${o.action.padEnd(6)}  ${o.path}`);
+    out.push('```', '', '</details>', '');
+    out.push('## Verify', '', 'Finalizing runs the project gate and one build. To check by hand first:', '', '```', `${i.pm} run gate`, 'node node_modules/next/dist/bin/next build', '```', '');
+    const sections = changelogSections(i.changelog, j.sourceVersion);
+    out.push('## Changelog', '', sections.length ? `The target release's changelog sections above ${j.sourceVersion}:` : `The target release has no changelog section above ${j.sourceVersion}.`, '');
+    if (sections.length)
+        out.push(fenced(sections.join('\n\n')), '');
+    return `${out.join('\n')}\n`;
+}
+function stagedItem(i, o) {
+    const s = i.session;
+    return [
+        `### file:${o.path}`, '',
+        `${o.disposition}: ${WHAT[o.disposition] ?? 'Review this file.'}`, '',
+        `- base: ${copy(s, 'base', o.base, o.path)}`,
+        `- ours: ${copy(s, 'ours', o.ours, o.path)}`,
+        `- new: ${copy(s, 'new', o.target, o.path)}`, '',
+        'Resolution stub:', '',
+        json({ id: `file:${o.path}`, status: 'resolved', reason: '', files: { [o.path]: i.hashOf(o.path) } }), '',
+    ];
+}