zz-meridian 0.15.0 → 0.16.1

package/README.md

@@ -39,10 +39,12 @@ Brand flags: `--name "Acme Ops"`, `--hex '#2E6BE4'` (or `--accent indigo|cobalt|
 in a page's kicker ("Production"); it does not touch the navigation workspaces.
 
 **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
+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
 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`;
+`.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/…`.
@@ -61,7 +63,8 @@ writes nothing; run it first.
   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.
+  `AGENTS.md`; an older version of the same major is raised, and a newer version, an older major or a 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,
   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.
@@ -83,7 +86,7 @@ Requires Node 22.18 or newer. The default `pnpm verify` runs without Google Chro
 
 It has no dependencies and no install scripts: running it executes only its own code, and only when you call it. It
 sends nothing anywhere; the only network access is your package manager's install, which you can skip with
-`--no-install`. Every release is built and published by GitHub Actions with npm provenance, so the registry shows the
+`--no-install`, and `update` reading releases from npm. Every release is built and published by GitHub Actions with npm provenance, so the registry shows the
 commit and workflow each version came from.
 
 ## Privacy and feedback

package/dist/adopt.js

@@ -8,7 +8,7 @@
  */
 import fs from 'node:fs';
 import path from 'node:path';
-import { VERSION, brandArgs, effectiveBrand, inside, installSkill, packageManager, payloadBytes, payloadFiles, readJsonc, readPayload, relativeImports, run, runTool, sha256, writeIn, writeManifest, } from './files.js';
+import { VERSION, brandArgs, effectiveBrand, inside, installSkill, jsoncExtras, packageManager, payloadBytes, 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. */
@@ -96,6 +96,8 @@ function verifyConfig() {
     return readPayload('scripts/verify.config.ts').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: [],
+  // What a route a persona may not open draws: the product's choice in src/app.config.ts.
+  refusal,
 };`);
 }
 /** The template's stylesheet, with its paths made relative to where the project keeps its own. */
@@ -121,6 +123,39 @@ export default defineConfig({
 });
 `;
 }
+/**
+ * What `adopt` writes for a team's `tsconfig.json`, and what it must say about it: the file Meridian's code needs (its
+ * scripts import with `.ts` extensions, its code is ES2022, `@meridian/*` reaches its files), the team's own kept beside
+ * it when it carries what `JSON.stringify` cannot hold, and what their `@/*` alias stands for. A function rather than a
+ * block inside `adopt` so a test can hold it to those three: a test that ran the whole `adopt` would need the template
+ * the payload carries, which a checkout has only after a build, and it would be testing the copy, not this decision.
+ */
+export function tsconfigWrites(tsPath) {
+    const writes = new Map();
+    const notes = [];
+    const ts = readJsonc(tsPath);
+    ts.compilerOptions ??= {};
+    ts.compilerOptions.allowImportingTsExtensions = true;
+    ts.compilerOptions.noEmit = true;
+    if (!/^es20(2[2-9]|[3-9]\d)|^esnext$/i.test(ts.compilerOptions.target ?? '')) {
+        notes.push(`raised tsconfig target from ${ts.compilerOptions.target ?? 'its default'} to ES2022`);
+        ts.compilerOptions.target = 'ES2022';
+    }
+    ts.compilerOptions.paths ??= {};
+    ts.compilerOptions.paths['@meridian/*'] = ['./src/*'];
+    const at = ts.compilerOptions.paths['@/*']?.[0];
+    const atAlias = typeof at === 'string' ? at.replace(/\/\*$/, '').replace(/^\.\//, '') || '.' : null;
+    // A tsconfig may carry comments and trailing commas, which `next dev` keeps (`comment-json`) and `JSON.stringify`
+    // cannot hold. What the team wrote is kept beside the rewritten file, as the stylesheet and the postcss config are,
+    // rather than dropped in silence — the note says so, and there is no backup to explain when there was nothing to lose.
+    const was = fs.readFileSync(tsPath, 'utf8');
+    writes.set('tsconfig.json', JSON.stringify(ts, null, 2) + '\n');
+    if (jsoncExtras(was)) {
+        writes.set('tsconfig.before.json', was);
+        notes.push('tsconfig.json carried comments or trailing commas, which the rewritten file cannot: yours is tsconfig.before.json');
+    }
+    return { writes, notes, atAlias };
+}
 export function adopt(o) {
     const { root } = o;
     const say = (s) => console.log(s);
@@ -228,20 +263,11 @@ Rename or move them, then run adopt again.`);
     const tsPath = path.join(root, 'tsconfig.json');
     let atAlias = null;
     if (fs.existsSync(tsPath)) {
-        const ts = readJsonc(tsPath);
-        ts.compilerOptions ??= {};
-        ts.compilerOptions.allowImportingTsExtensions = true;
-        ts.compilerOptions.noEmit = true;
-        if (!/^es20(2[2-9]|[3-9]\d)|^esnext$/i.test(ts.compilerOptions.target ?? '')) {
-            notes.push(`raised tsconfig target from ${ts.compilerOptions.target ?? 'its default'} to ES2022`);
-            ts.compilerOptions.target = 'ES2022';
-        }
-        ts.compilerOptions.paths ??= {};
-        ts.compilerOptions.paths['@meridian/*'] = ['./src/*'];
-        const at = ts.compilerOptions.paths['@/*']?.[0];
-        if (typeof at === 'string')
-            atAlias = at.replace(/\/\*$/, '').replace(/^\.\//, '') || '.';
-        writes.set('tsconfig.json', JSON.stringify(ts, null, 2) + '\n');
+        const ts = tsconfigWrites(tsPath);
+        for (const [f, text] of ts.writes)
+            writes.set(f, text);
+        notes.push(...ts.notes);
+        atAlias = ts.atAlias;
     }
     else {
         return fail('no tsconfig.json: Meridian is TypeScript. Add one (next dev writes it), then run adopt again.');

package/dist/cli.js

@@ -7,6 +7,7 @@ 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 { create } from './create.js';
 import { BRAND_FLAGS, VERSION, installSkill } from './files.js';
 import { brandCommand } from './rebrand.js';
@@ -75,6 +76,12 @@ function main() {
         console.log(HELP);
         return command || values.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);
+    if (wrong) {
+        console.error(`zz-meridian ${command}: --${wrong.flag} belongs to ${wrong.belongsTo}`);
+        return 1;
+    }
     if (command === 'adopt')
         return adopt({ root: process.cwd(), brand, allowDirty: Boolean(values['allow-dirty']), install });
     if (command === 'create') {

package/dist/command-flags.js

@@ -0,0 +1,38 @@
+/**
+ * Which flags each command reads. A flag that names a mode or a value belongs to the command that acts on it: anywhere
+ * 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 { BRAND_FLAGS } from './files.js';
+/** Every command reads these. */
+const EVERYWHERE = ['help', 'version'];
+/** The brand flags, read by the commands that write a brand. */
+const BRAND = BRAND_FLAGS;
+/** What each command reads, beyond the two above. */
+const ACCEPTS = {
+    adopt: [...BRAND, 'allow-dirty', 'no-install'],
+    create: [...BRAND, 'no-install'],
+    update: ['allow-dirty', 'no-install', 'dry-run', 'resume', 'finalize', 'abort', 'verify', 'verbose'],
+    brand: [...BRAND, 'allow-dirty'],
+    skill: ['global'],
+};
+/** The commands that read one flag, in the CLI's own order, for the sentence that sends the person to the right one. */
+function commandsReading(flag) {
+    return Object.keys(ACCEPTS).filter((c) => ACCEPTS[c].includes(flag));
+}
+/**
+ * The first flag a command does not read, with the command it belongs to; null when every flag is the command's own.
+ * `update` is the one command with no spelling of its own, so a flag only it reads is named as its own.
+ */
+export function misapplied(command, flags) {
+    const accepted = ACCEPTS[command];
+    if (!accepted)
+        return null;
+    for (const [flag, value] of Object.entries(flags)) {
+        if (value === undefined || EVERYWHERE.includes(flag) || accepted.includes(flag))
+            continue;
+        const others = commandsReading(flag);
+        return { flag, belongsTo: others.length ? `zz-meridian ${others.join(' or ')}` : 'no command' };
+    }
+    return null;
+}

package/dist/files.js

@@ -82,10 +82,10 @@ 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' });
 }
 export const hasCommand = (cmd) => spawnSync(cmd, ['--version'], { stdio: 'ignore', shell: process.platform === 'win32' }).status === 0;
-/** JSON with the comments and trailing commas a tsconfig may carry. */
-export function readJsonc(file) {
-    const text = fs.readFileSync(file, 'utf8');
+/** A JSONC document's text with the comments dropped, and whether anything had to be dropped to read it. */
+function strippedJsonc(text) {
     let out = '';
+    let dropped = false;
     for (let i = 0, str = false; i < text.length; i++) {
         const c = text[i];
         if (str) {
@@ -102,12 +102,14 @@ export function readJsonc(file) {
             continue;
         }
         if (c === '/' && text[i + 1] === '/') {
+            dropped = true;
             while (i < text.length && text[i] !== '\n')
                 i++;
             out += '\n';
             continue;
         }
         if (c === '/' && text[i + 1] === '*') {
+            dropped = true;
             i += 2;
             while (i < text.length && !(text[i] === '*' && text[i + 1] === '/'))
                 i++;
@@ -116,8 +118,19 @@ export function readJsonc(file) {
         }
         out += c;
     }
-    return JSON.parse(out.replace(/,(\s*[}\]])/g, '$1'));
+    const json = out.replace(/,(\s*[}\]])/g, '$1');
+    return { json, dropped: dropped || json.length !== out.length };
 }
+/** JSON with the comments and trailing commas a tsconfig may carry. */
+export function readJsonc(file) {
+    return JSON.parse(strippedJsonc(fs.readFileSync(file, 'utf8')).json);
+}
+/**
+ * Whether a project's file carries what plain JSON cannot hold: a comment, or a trailing comma. `next dev` writes a
+ * tsconfig through `comment-json`, which keeps both, so a tool that re-serialises one drops what the team's own
+ * toolchain preserves — and this is the question to ask before doing it.
+ */
+export const jsoncExtras = (text) => strippedJsonc(text).dropped;
 /**
  * Meridian's own `@/` imports, made relative to the file. An adopting project may map `@/` somewhere else, or already
  * have a `components/ui/button`; a relative import can never resolve to the team's file instead of Meridian's.

package/dist/migrations.js

@@ -100,6 +100,134 @@ function callArity(src, fn) {
     }
     return out;
 }
+/** Where an import of the team's file `rel` points, as a project path with no extension; null for a package. */
+const resolvedImport = (rel, spec) => {
+    const bare = spec.replace(/\.[mc]?[jt]sx?$/, '');
+    if (bare.startsWith('@/'))
+        return `src/${bare.slice(2)}`;
+    return bare.startsWith('.') ? path.posix.join(path.posix.dirname(rel), bare) : null;
+};
+/** Each import of a file of the team's: the module it resolves to, the names it takes and its namespace, if it has one. */
+function importsOf(rel, src) {
+    const out = [];
+    for (const m of src.matchAll(/^\s*import\s+(?:type\s+)?([^'"]*?)\s+from\s+(['"])([^'"]+)\2/gm)) {
+        const from = resolvedImport(rel, m[3]);
+        if (from === null)
+            continue;
+        const names = (/\{([^}]*)\}/.exec(m[1])?.[1] ?? '').split(',').map((s) => s.trim().replace(/^type\s+/, '').split(/\s+as\s+/)[0]).filter(Boolean);
+        out.push({ from, names, namespace: /\*\s*as\s+([\w$]+)/.exec(m[1])?.[1] ?? null });
+    }
+    return out;
+}
+/**
+ * The index just past the string, template or comment that starts at `i`, or `i` when none does. A regular expression is
+ * not told from a division here: a view tool's object holds none whose brackets or quotes do not balance.
+ */
+function skipLiteral(src, i) {
+    const c = src[i], next = src[i + 1];
+    if (c === '/' && next === '/') {
+        const e = src.indexOf('\n', i);
+        return e < 0 ? src.length : e;
+    }
+    if (c === '/' && next === '*') {
+        const e = src.indexOf('*/', i + 2);
+        return e < 0 ? src.length : e + 2;
+    }
+    if (c === "'" || c === '"') {
+        let j = i + 1;
+        while (j < src.length && src[j] !== c && src[j] !== '\n')
+            j += src[j] === '\\' ? 2 : 1;
+        return j + 1;
+    }
+    if (c === '`') {
+        let j = i + 1;
+        while (j < src.length && src[j] !== '`') {
+            if (src[j] === '\\')
+                j += 2;
+            else if (src[j] === '$' && src[j + 1] === '{')
+                j = closeOf(src, j + 1) + 1;
+            else
+                j++;
+        }
+        return j + 1;
+    }
+    return i;
+}
+/** The index of the bracket that closes the `{`, `(` or `[` at `open`, passing over strings and comments. */
+function closeOf(src, open) {
+    let depth = 0;
+    for (let i = open; i < src.length;) {
+        const past = skipLiteral(src, i);
+        if (past !== i) {
+            i = past;
+            continue;
+        }
+        const c = src[i];
+        if ('{(['.includes(c))
+            depth++;
+        else if ('})]'.includes(c) && --depth === 0)
+            return i;
+        i++;
+    }
+    return src.length;
+}
+/**
+ * Each `defineViewTool({ … })` call of a file, as the keys of its object's own level, each with its value when that is a
+ * string and null otherwise; a key inside a nested object, call or function body, such as an input's `page`, is not
+ * the tool's. An object that spreads another has the key `...`, since what it spreads cannot be read here.
+ */
+function viewToolCalls(src) {
+    const out = [];
+    const call = /defineViewTool\s*(?:<[^>]*>)?\s*\(\s*\{/y;
+    const key = /(?:async\s+)?([A-Za-z_$][\w$]*)(?:\s*:\s*(['"])((?:\\.|(?!\2)[^\\\n])*)\2)?/y;
+    for (let i = 0; i < src.length;) {
+        const past = skipLiteral(src, i);
+        if (past !== i) {
+            i = past;
+            continue;
+        }
+        call.lastIndex = i;
+        const m = call.exec(src);
+        if (!m || /[\w$.]/.test(src[i - 1] ?? '')) {
+            i++;
+            continue;
+        }
+        const open = i + m[0].length - 1;
+        const close = closeOf(src, open);
+        const keys = new Map();
+        let prev = '{';
+        for (let k = open + 1; k < close;) {
+            const lit = skipLiteral(src, k);
+            if (lit !== k) {
+                k = lit;
+                continue;
+            }
+            const c = src[k];
+            if (/\s/.test(c)) {
+                k++;
+                continue;
+            }
+            if (prev === '{' || prev === ',') {
+                if (src.startsWith('...', k))
+                    keys.set('...', null);
+                key.lastIndex = k;
+                const found = key.exec(src);
+                if (found && !keys.has(found[1]))
+                    keys.set(found[1], found[3] ?? null);
+            }
+            if ('{(['.includes(c)) {
+                k = closeOf(src, k) + 1;
+                prev = '}';
+                continue;
+            }
+            prev = c;
+            k++;
+        }
+        out.push(keys);
+        i = close + 1;
+    }
+    return out;
+}
 // ── The registry ─────────────────────────────────────────────────────────────────────────────────────
 const GATE_AND_BUILD = ['gate', 'build'];
 export const RELEASE_MIGRATIONS = [
@@ -254,7 +382,166 @@ export const RELEASE_MIGRATIONS = [
         instructions: 'The gate asked this of pages under `app/(dashboard)/` only; from 0.15.0 it asks it under whatever route group sits at the top of the app folder. Read "A page spec" in references/customize.md. Under `## Agents` in each page\'s README.md listed here, add `### What the agent reads`: what the page\'s shared context tells each agent, with a real line of it, and what the MCP App and the console assistant do with it. A copy of the rule kept in `scripts/check.local.ts` for the project\'s own group can be deleted.',
         checks: ['gate'],
     },
+    {
+        id: 'refusal-declared',
+        since: '0.16.0',
+        applies: refusalUndeclared,
+        summary: 'The product says what an address a person may not open draws: `refusal` in `src/app.config.ts`.',
+        instructions: 'Read "Navigation: `src/app.config.ts`" in references/customize.md. Add `export const refusal: \'explain\' | \'absent\' = \'explain\';` to `src/app.config.ts`, beside `facts`: `explain` keeps the no-access page a refused page draws today, and `absent` answers as an address that names nothing. A project that keeps the sample\'s access seam brings `src/data/access.ts` and `src/data/refusal.ts` over from the release (`gate` reads `refusal`, with `gatedMetadata` and `withheldEntries` beside it, and `gatedLoading` reads it alone), titles each gated page with `export function generateMetadata() { return gatedMetadata(\'<feature>\', { title: \'<its title>\' }); }` in place of a static `metadata`, passes its loading state\'s `name` and `title` through `gatedLoading`, and adds `refusal,` to the config object of `scripts/verify.config.ts`, imported from `../src/app.config.ts`, so `verify --as` expects the page the product chose.',
+        checks: GATE_AND_BUILD,
+    },
+    {
+        id: 'managed-exports-removed',
+        since: '0.16.0',
+        applies: removedExportReaders,
+        summary: 'A file of the team\'s imports an export the release removed from a managed module: `deviations`, `largest`, `runs` or `weekendRatio` from `src/lib/insight.ts`, or `queryInput` from `src/lib/collection.ts`.',
+        instructions: 'The update brought `src/lib/insight.ts` and `src/lib/collection.ts` without them, so each file listed here fails the type check. A file of the sample\'s comes over from the release: the Overview context is Home\'s, `src/views/home-context.ts` (see `sample-pages-renamed`); the assistant reads through `view_<name>` and `explore_<view>` and has no `query_<name>` tools, so bring `src/lib/assistant/tools.ts` and `src/lib/assistant/respond.ts` over and pass `readable`, every collection the person may read, from the assistant route to `respond` beside `collections` (read "Prepared queries" in references/agents.md); and a shipped test that imports one, such as `tests/shared-context.test.tsx` or `tests/collection.test.ts`, comes over as the release has it. A file of your own that still needs one of the functions writes it in that file, from its 0.15.0 source.',
+        checks: GATE_AND_BUILD,
+    },
+    {
+        id: 'view-tool-page-explore',
+        since: '0.16.0',
+        applies: (root) => matching(root, (_, src) => viewToolCalls(src).some((k) => !k.has('...') && !(k.has('page') && k.has('explore')))),
+        summary: 'Every view tool names the page it renders and its prepared query: `page` and `explore` on `defineViewTool`.',
+        instructions: 'Read "Prepared queries" in references/agents.md. Add to each `defineViewTool` call in the files listed here `page`, the console route of the page the view renders (a rail destination\'s `href` in `nav`, or a detail page\'s route with its segment, such as `/customers/[id]`), and `explore`, its prepared query (`PreparedQuery` in `src/lib/explore.ts`), declared beside the view as the sample\'s are in `src/views/<view>-explore.ts`. `ViewTool` in `src/lib/shared-context.ts` requires both, so a tool without them fails the type check. A project that kept the sample\'s view tools brings `src/views/tools.ts` and the `src/views/*-explore.ts` files over from the release. Once a tool names its page, the gate asks that page\'s specification what the agent does there (`agent-does-here-section`).',
+        checks: GATE_AND_BUILD,
+    },
+    {
+        id: 'agent-does-here-section',
+        since: '0.16.0',
+        applies: viewToolPagesWithoutAgentDoes,
+        summary: 'The specification of a page a view tool renders says what the agent does there.',
+        instructions: 'Read "Prepared queries" in references/agents.md. Under `## Agents` in the README.md of each page a view tool\'s `page` names, add `### What the agent does here`: a line `Protagonist: <the card\'s name>.`, then at least three questions a person on the page asks that its context does not answer alone, each `- "<question>" — <what the prepared query is asked>`, and mark that card on the page with `data-protagonist="<name>"`. `scripts/check.ts` fails the gate on such a page without the part. While a view tool in `src/views/tools.ts` names no page yet (`view-tool-page-explore`), every console page specification without the part is listed: one that no tool comes to name needs nothing.',
+        checks: ['gate'],
+    },
+    {
+        id: 'sample-pages-renamed',
+        since: '0.16.0',
+        applies: renamedSampleFiles,
+        summary: 'The project holds the sample\'s pages and views under their 0.15.0 names: Overview is Home, Analytics is Usage at `/usage` and Operations is Services at `/services`.',
+        instructions: 'The release renamed them with no redirect, and an update writes none of the team\'s pages, views or tests. Each file listed is one of them or names one: a page or a view, the view tools, `src/app.config.ts`\'s nav and the feature ids it names, the routes of `scripts/verify.config.ts`, or a shipped test that expects them. A project that kept the sample\'s pages as they were brings the release\'s over: `app/(dashboard)/` and `app/embed/`, `src/views/`, `src/data/`, `src/lib/assistant/` beside `prompt.ts`, `src/app.config.ts` with its own `app` kept, and each shipped test as the release has it; a file listed here that the release no longer has is deleted. A project that made the pages its own keeps its own names, makes the changes this release\'s other migrations list in them, and reads "not applicable" for the assistant walk-through\'s steps on Home and Now (`scripts/lib/sample.ts`).',
+        checks: GATE_AND_BUILD,
+    },
 ];
+/** The team's files that import an export 0.16.0 removed from a managed module, by name or through a namespace. */
+function removedExportReaders(root) {
+    const removed = { 'src/lib/insight': ['deviations', 'largest', 'runs', 'weekendRatio'], 'src/lib/collection': ['queryInput'] };
+    return matching(root, (rel, src) => importsOf(rel, src).some(({ from, names, namespace }) => {
+        const gone = removed[from] ?? [];
+        return names.some((n) => gone.includes(n)) || (namespace !== null && gone.some((g) => new RegExp(`(?<![\\w$.])${namespace.replace(/\$/g, '\\$')}\\.${g}\\b`).test(src)));
+    }));
+}
+/**
+ * The specifications of the pages the view tools of `src/views/tools.ts` render, as the gate reads them from 0.16.0,
+ * that lack "What the agent does here". While a tool names no page, the gate cannot tell its page, and neither can this:
+ * every console page specification without the part is listed then.
+ */
+function viewToolPagesWithoutAgentDoes(root) {
+    const tools = text(root, 'src/views/tools.ts');
+    if (tools === null)
+        return null;
+    const calls = viewToolCalls(tools).filter((k) => !k.has('...'));
+    if (calls.length === 0)
+        return null;
+    const pages = new Set(calls.map((k) => k.get('page')).filter((p) => typeof p === 'string'));
+    const unnamed = calls.some((k) => !k.has('page'));
+    const app = fs.existsSync(path.join(root, 'app')) ? 'app' : 'src/app';
+    const specs = [];
+    walk(root, app, specs, /^README\.md$/);
+    const hits = specs.filter((rel) => {
+        const rest = rel.slice(app.length + 1);
+        if (!/^\([^/)]+\)\//.test(rest))
+            return false;
+        const route = `/${path.posix.dirname(rest).split('/').filter((s) => !/^\(.*\)$/.test(s)).join('/')}`;
+        return (unnamed || pages.has(route)) && !/^## Agents$(?:\n(?!## ).*)*\n### What the agent does here$/m.test(text(root, rel) ?? '');
+    });
+    return hits.length > 0 ? hits : null;
+}
+/**
+ * The sample's pages and views under the names 0.16.0 replaced, and every file of the team's that names one: an import
+ * of one of their modules, a feature id or view tool of theirs, the walk-through's surfaces as they were, and the
+ * verify config's routes for them. Only a project that still holds one of the sample's old files is read, so a page of
+ * a product's own at the same address, or a feature of its own of the same name, is never taken for the sample's. The
+ * names are put together from their parts: the repository holds them out of everything but its history.
+ */
+function renamedSampleFiles(root) {
+    const old = ['overview', 'analytics', 'health'];
+    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 sources = teamSources(root);
+    if (!sources.some((f) => isOld(f.rel)))
+        return null;
+    const seeds = sources.filter(({ rel, src }) => isOld(rel)
+        || importsOf(rel, src).some((i) => modules.has(i.from))
+        || named.test(src)
+        || (/\bsampleSurfaces\b/.test(src) && new RegExp(`\\b${old[0]}\\s*:|\\.${old[0]}\\b`).test(src))).map((f) => f.rel);
+    // A page or an embed view of the sample's goes with its folder: its loading state and its specification name nothing
+    // 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))));
+    for (const { rel } of pages) {
+        const dir = path.posix.dirname(rel);
+        try {
+            for (const e of fs.readdirSync(path.join(root, dir), { withFileTypes: true }))
+                if (e.isFile())
+                    oldFiles.add(`${dir}/${e.name}`);
+        }
+        catch { /* gone since it was read */ }
+    }
+    const oldPaths = new Set([...oldFiles].map((r) => r.replace(/\.[mc]?[jt]sx?$/, '')));
+    const found = new Set([...seeds, ...oldFiles]);
+    for (const { rel, src } of sources)
+        if (importsOf(rel, src).some((i) => oldPaths.has(i.from)))
+            found.add(rel);
+    const hits = [...found].sort();
+    const verifyConfig = 'scripts/verify.config.ts';
+    const routes = new RegExp(`'/(?:${old[1]}|${old[2]})'|title:\\s*'(?:Overview|Analytics|Operations)'`);
+    if (routes.test(text(root, verifyConfig) ?? ''))
+        hits.push(verifyConfig);
+    return hits;
+}
+/** The project's configuration, when it does not yet say what an address a person may not open draws (0.16.0). */
+function refusalUndeclared(root) {
+    const rel = 'src/app.config.ts';
+    const body = text(root, rel);
+    if (body === null)
+        return null;
+    return /^export const refusal\b/m.test(body) ? null : [rel];
+}
+/** The nav item objects of a nav array, by brace: an object naming an `href` of its own, however many lines it is over. Braces inside a quoted value are not braces. */
+function navItemObjects(nav) {
+    const found = [];
+    const open = [];
+    let quote = null;
+    for (let i = 0; i < nav.length; i++) {
+        const ch = nav[i];
+        if (quote) {
+            if (ch === '\\')
+                i++;
+            else if (ch === quote)
+                quote = null;
+            continue;
+        }
+        if (ch === "'" || ch === '"' || ch === '`')
+            quote = ch;
+        else if (ch === '{')
+            open.push(i);
+        else if (ch === '}') {
+            const start = open.pop();
+            if (start === undefined)
+                continue;
+            const inner = nav.slice(start + 1, i);
+            // What is left once the objects inside it are taken out: a group's `href`s are all in its items, so a group has
+            // none of its own left and is not an item.
+            if (/\bhref\s*:/.test(inner.replace(/\{[^{}]*\}/g, '')))
+                found.push(inner);
+        }
+    }
+    return found;
+}
 /** 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';
@@ -264,16 +551,17 @@ function navItemsWithoutNeeds(root) {
     const nav = /export const nav\b[^=]*=\s*\[([\s\S]*?)\n\];/.exec(body)?.[1];
     if (nav === undefined)
         return null;
-    // One item per line, as `adopt` writes them and as a hand-kept nav keeps them, so the item is the line naming its
-    // `href`: a group's opening line — every project groups its nav — names no `href` and carries no `needs` of its own,
-    // so counting it as an item would report a change no edit can settle. Anything the file does beyond that is the
-    // team's own shape, and none of it is read.
-    const items = nav.split('\n').filter((l) => /\bhref\s*:/.test(l));
+    // The item is the object naming its `href`, read by its braces rather than by its line: a team that spreads an item
+    // over its keys put the `needs` two lines below the `href`, and a line-based read reported the migration for a file
+    // with none of the old shape left in it. A group is not a destination and carries no `needs`: its own `href`s belong
+    // to the items inside it, so an object whose braces hold only other objects is not read. Anything the file does
+    // beyond that is the team's own shape, and none of it is read.
+    const items = navItemObjects(nav);
     // A project of 0.12.3's vintage also declares `NavItem` itself, without the property: an item that names a `needs` its
     // own type does not have is the type error the gate prints next, so the change is not done until the type carries it.
     const declaredType = /export type NavItem[^;]*\};/.test(body);
     const typeHasNeeds = /export type NavItem[^;]*\bneeds\s*:/.test(body);
-    return items.some((l) => !/\bneeds\s*:/.test(l)) || (declaredType && !typeHasNeeds) ? [rel] : null;
+    return items.some((item) => !/\bneeds\s*:/.test(item)) || (declaredType && !typeHasNeeds) ? [rel] : null;
 }
 /**
  * The page specifications under a route group of the project's own, at the top of its app folder, that lack the part the

package/dist/ownership.js

@@ -1,14 +1,14 @@
 const HASH = /^sha256-[0-9a-f]{64}$/;
 const SEMVER = /^\d+\.\d+\.\d+$/;
 /** The library modules Meridian's components and gates import; the rest of src/lib belongs to the template's pages. */
-export const LIB = ['cn', 'format', 'format-date', 'period', 'color', 'host', 'preferences', 'csv', 'safe-markdown', 'logo', 'collection', 'live', 'shared-context', 'agent-guidance', 'insight'].map((n) => `src/lib/${n}.ts`);
+export const LIB = ['cn', 'format', 'format-date', 'period', 'color', 'host', 'preferences', 'csv', 'safe-markdown', 'logo', 'collection', 'explore', 'live', 'shared-context', 'agent-guidance', 'insight', 'facts'].map((n) => `src/lib/${n}.ts`);
 /** The single files adopt copies besides the folders and the library: all of them must be in a payload that is whole. */
 export const FIXED = [...LIB, 'src/lib/assistant/prompt.ts', 'src/views/console-chrome.tsx', 'tests/setup.ts'];
 /** The one rule, a plain-English line per clause. `references/ownership.md` renders it, so the guidance cannot drift. */
 export const OWNERSHIP = [
     'Managed: the payload files under `tokens/`, `src/styles/` and `src/components/`, except each component\'s `README.md` and `preview.tsx`.',
     'Managed: the distributed scripts under `scripts/`, except `scripts/verify.config.ts`, the first-load baseline `optional:scripts/verify.baseline.json` and a team-local `optional:scripts/check.local.ts`.',
-    'Managed: the library helpers `src/lib/cn.ts`, `src/lib/format.ts`, `src/lib/format-date.ts`, `src/lib/period.ts`, `src/lib/color.ts`, `src/lib/host.ts`, `src/lib/preferences.ts`, `src/lib/csv.ts`, `src/lib/safe-markdown.ts`, `src/lib/logo.ts`, `src/lib/collection.ts`, `src/lib/live.ts`, `src/lib/shared-context.ts`, `src/lib/agent-guidance.ts` and `src/lib/insight.ts`, and the assistant prompt `src/lib/assistant/prompt.ts`.',
+    'Managed: the library helpers `src/lib/cn.ts`, `src/lib/format.ts`, `src/lib/format-date.ts`, `src/lib/period.ts`, `src/lib/color.ts`, `src/lib/host.ts`, `src/lib/preferences.ts`, `src/lib/csv.ts`, `src/lib/safe-markdown.ts`, `src/lib/logo.ts`, `src/lib/collection.ts`, `src/lib/explore.ts`, `src/lib/live.ts`, `src/lib/shared-context.ts`, `src/lib/agent-guidance.ts`, `src/lib/insight.ts` and `src/lib/facts.ts`, and the assistant prompt `src/lib/assistant/prompt.ts`.',
     'Managed: `src/views/console-chrome.tsx` and `tests/setup.ts`.',
     'Managed: `optional:scripts/package.json`, only when the adopt or create that set the project up generated it for this project shape.',
     'Managed: both installed skill trees, `optional:.agents/skills/zz-meridian/` and `optional:.claude/skills/zz-meridian/`, taken from the release\'s skill payload.',

package/dist/rebrand.js

@@ -165,8 +165,19 @@ function attempt(ctx, change, allowDirty) {
 }
 /** The command: the real context, which replays the running release and runs its branding script in scratch. */
 export function brandCommand({ root, flags, allowDirty }) {
-    const scratch = fs.mkdtempSync(path.join(os.tmpdir(), 'zz-meridian-brand-'));
     const log = (line) => (line.startsWith('zz-meridian brand:') ? console.error(line) : console.log(line));
+    // The flags are read before anything is copied, and a value the branding script refuses is refused here with the
+    // command's own sentence: `adopt` and `create` read the same flags through `effectiveBrand` and answer its Error
+    // (`adopt.ts:153`, `create.ts:19`), where `brand` let it out as a stack trace.
+    let brand;
+    try {
+        brand = effectiveBrand(flags);
+    }
+    catch (e) {
+        log(`zz-meridian brand: ${e.message}`);
+        return 1;
+    }
+    const scratch = fs.mkdtempSync(path.join(os.tmpdir(), 'zz-meridian-brand-'));
     const replays = new Map();
     let n = 0;
     try {
@@ -204,7 +215,7 @@ export function brandCommand({ root, flags, allowDirty }) {
                 return fs.readFileSync(path.join(copy, APP_CONFIG), 'utf8');
             },
         };
-        return rebrand(ctx, effectiveBrand(flags), { allowDirty });
+        return rebrand(ctx, brand, { allowDirty });
     }
     finally {
         fs.rmSync(scratch, { recursive: true, force: true });

package/dist/session.js

@@ -265,8 +265,11 @@ function install(ctx, session, j, pm) {
     const { root } = ctx;
     const lock = lockfileFor(root, pm);
     const prior = j.operations.find((o) => o.path === lock && o.disposition === 'team-preserved' && o.applied);
-    const before = prior ? prior.base : probe(root, lock).side;
     const backup = path.join(session, 'backup', lock);
+    // The preimage is what the lockfile was before this update's install, and the first run wrote it here before running
+    // one. A resumed run that probed the project instead takes whatever a killed install left behind as "ours", and an
+    // abort would then put a half-written lockfile back in place of the team's.
+    const before = prior ? prior.base : fs.existsSync(backup) ? sideOf(sha(fs.readFileSync(backup))) : probe(root, lock).side;
     if (before.exists && !fs.existsSync(backup))
         writeAtomic(backup, fs.readFileSync(inside(root, lock)));
     const t0 = performance.now();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "zz-meridian",
-  "version": "0.15.0",
+  "version": "0.16.1",
   "description": "Bring ZZ Meridian, a dashboard design system, into a Next.js project, or start a new dashboard on it. Copies the files in; nothing depends on this package at runtime.",
   "license": "MIT",
   "type": "module",