zz-meridian 0.14.1 → 0.16.0

package/README.md

@@ -35,13 +35,14 @@ 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`,
-`--workspace`, `--timezone`, `--currency`, `--user`, `--role`.
+`--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.
 
 **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; 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/…`.
@@ -60,10 +61,11 @@ 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.
-- 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.
+  `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.
 - 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
@@ -82,7 +84,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

@@ -72,21 +72,32 @@ function routes(root, dir) {
     return [...new Set(out)].filter((r) => /^\/[\w/.-]*$/.test(r)).sort((a, b) => (a === '/' ? -1 : b === '/' ? 1 : a.localeCompare(b)));
 }
 const label = (route) => (route === '/' ? 'Home' : route.split('/').pop().replace(/[-_]+/g, ' ').replace(/^./, (c) => c.toUpperCase()));
-function appConfig(pages) {
-    const template = readPayload('src/app.config.ts');
+/**
+ * The configuration `adopt` writes: the template's own file with the project's pages as its navigation. Everything that
+ * belongs to the sample is left out, because the project does not have it: the feature table (so every item is `public`,
+ * the honest default, until the fourth step of "Decide who may do what" in the Start guide points each at a feature of its own), every icon but the one the
+ * items use, and the sample's workspaces with the field that names one. It throws when the template has no navigation
+ * block to replace, since a configuration that still listed the sample's pages would be wrong without saying so.
+ */
+export function projectConfig(template, pages) {
+    if (!/export const nav: NavGroup\[\] = \[[\s\S]*?\n\];/.test(template))
+        throw new Error('the template\'s src/app.config.ts has no `export const nav: NavGroup[] = [ … ];` block to replace');
     const items = pages.map((r) => `      { href: ${JSON.stringify(r)}, label: ${JSON.stringify(label(r))}, icon: LayoutGrid, needs: 'public' },`).join('\n');
     return template
         .replace(/^import \{[\s\S]*?\} from 'lucide-react';/m, "import { LayoutGrid, type LucideIcon } from 'lucide-react';")
-        // The project's pages have no feature entry yet, so every item is `public` — the honest default — and step 4 of the
-        // Start guide points each at its own feature once it has one. The template's own `FEATURES` import would name a file
-        // this project's `src/data/` need not have, and a nav item without a `needs` is a type error since 0.13.0.
+        // The template's own `FEATURES` import would name a file this project's `src/data/` need not have, and a nav item
+        // without a `needs` is a type error since 0.13.0.
         .replace(/^import \{ FEATURES \} from '\.\/data\/features\.ts';\n/m, '')
+        .replace(/\/\*\*(?:(?!\*\/)[\s\S])*\*\/\nexport const workspaces = \{[\s\S]*?\n\} as const;\nexport type WorkspaceId = [^\n]*\n\n/, '')
+        .replace(' workspace?: WorkspaceId;', '')
         .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];`);
 }
 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. */
@@ -168,7 +179,14 @@ https://github.com/zhixuan312/zz-meridian/blob/master/skills/zz-meridian/referen
         const raw = payloadBytes(rel);
         own(rel, TS.test(rel) ? exactImports(rel, raw.toString('utf8'), known) : raw);
     }
-    own('src/app.config.ts', exactImports('src/app.config.ts', appConfig(routes(root, dir)), known));
+    let config;
+    try {
+        config = projectConfig(readPayload('src/app.config.ts'), routes(root, dir));
+    }
+    catch (e) {
+        return fail(e.message);
+    }
+    own('src/app.config.ts', exactImports('src/app.config.ts', config, known));
     own('scripts/verify.config.ts', verifyConfig());
     // Meridian's scripts are ES modules; a project whose package.json is not "type": "module" gets that for scripts/ only.
     if (pkg.type !== 'module')

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 = [
@@ -243,10 +371,146 @@ export const RELEASE_MIGRATIONS = [
         since: '0.13.0',
         applies: navItemsWithoutNeeds,
         summary: 'Every item in the project\'s `nav` carries a `needs`, so the rail shows only the destinations a person may reach.',
-        instructions: 'Read "Roles and access" in the Start guide (docs/start-a-dashboard.md). For each item in `src/app.config.ts`\'s `nav`, add `needs: \'public\'` when everyone may open that page, or point it at its feature (`needs: FEATURES.<id>.needs`); step 4 of that guide has the four steps, and `scripts/check.ts` fails the project\'s gate, naming the href, on an item without one. `adopt` writes `needs: \'public\'` for a project it sets up from now on.',
+        instructions: 'Read "5. Decide who may do what" in the Start guide (docs/start-a-dashboard.md). For each item in `src/app.config.ts`\'s `nav`, add `needs: \'public\'` when everyone may open that page, or point it at its feature (`needs: FEATURES.<id>.needs`); the fourth of its four steps covers it, and `scripts/check.ts` fails the project\'s gate, naming the href, on an item without one. `adopt` writes `needs: \'public\'` for a project it sets up from now on.',
         checks: ['gate'],
     },
+    {
+        id: 'agent-reads-own-group',
+        since: '0.15.0',
+        applies: ownGroupPagesWithoutAgentReads,
+        summary: 'A page under the route group the project keeps its console in says what the agent reads.',
+        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 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';
@@ -267,6 +531,24 @@ function navItemsWithoutNeeds(root) {
     const typeHasNeeds = /export type NavItem[^;]*\bneeds\s*:/.test(body);
     return items.some((l) => !/\bneeds\s*:/.test(l)) || (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
+ * gate asks for there from 0.15.0. The template's `(dashboard)` is left out: the rule has covered it since 0.9.0.
+ */
+function ownGroupPagesWithoutAgentReads(root) {
+    const files = [];
+    for (const app of ['app', 'src/app']) {
+        let groups = [];
+        try {
+            groups = fs.readdirSync(path.join(root, app), { withFileTypes: true }).filter((e) => e.isDirectory() && /^\(.+\)$/.test(e.name) && e.name !== '(dashboard)').map((e) => e.name);
+        }
+        catch { /* no such folder */ }
+        for (const g of groups)
+            walk(root, `${app}/${g}`, files, /^README\.md$/);
+    }
+    const hits = files.filter((rel) => !/^## Agents\n[\s\S]*?^### What the agent reads$/m.test(text(root, rel) ?? ''));
+    return hits.length > 0 ? hits : null;
+}
 /** The page specifications under the console and embed folders that lack the part the 0.9.0 check requires. */
 function pagesWithoutAgentReads(root) {
     const files = [];

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

@@ -289,6 +289,29 @@ function install(ctx, session, j, pm) {
     return { ms, failure: r.status === 0 ? null : `${pm} install exited with ${r.status}; see evidence/0-install.log` };
 }
 const isInstall = (v) => v.command.endsWith(' install');
+/**
+ * The managed files that are not the release's bytes and that no keep entry explains, as lines to print; none when
+ * there are none. Nothing else reports them between releases, and the next update would meet each as an edit nobody
+ * recorded a reason for. A keep register that cannot be read explains nothing, and the gate already says why.
+ */
+function unrecordedEdits(root, manifest) {
+    let kept = new Set();
+    try {
+        kept = new Set(parseKeep(fs.readFileSync(path.join(root, '.meridian', 'keep.json'), 'utf8')).map((k) => k.path));
+    }
+    catch { /* no register, or one the gate reports */ }
+    const edited = Object.entries(manifest.files)
+        .filter(([p, hash]) => !kept.has(p) && (!fs.existsSync(path.join(root, p)) || sha256(fs.readFileSync(path.join(root, p))) !== hash))
+        .map(([p]) => p)
+        .sort();
+    if (edited.length === 0)
+        return [];
+    return [
+        `${edited.length} managed ${edited.length === 1 ? 'file differs' : 'files differ'} from the release and ${edited.length === 1 ? 'is' : 'are'} not in .meridian/keep.json:`,
+        ...edited.map((p) => `  ${p}${fs.existsSync(path.join(root, p)) ? '' : ' (missing)'}`),
+        'The next update will ask about each. Restore a file to the release, or name it in .meridian/keep.json with the reason it differs.',
+    ];
+}
 export function start(ctx, o) {
     const { root, log } = ctx;
     const refuse = (cause) => { log(`zz-meridian update: ${cause}`); return 1; };
@@ -310,6 +333,8 @@ export function start(ctx, o) {
         // Already current is not a refusal: there is nothing to do, and the run that asked has its answer.
         if (manifest.version === ctx.version) {
             log(`zz-meridian update: already at ${ctx.version}; nothing to update`);
+            for (const line of unrecordedEdits(root, manifest))
+                log(line);
             return 0;
         }
         if (!isNewer(ctx.version, manifest.version))

package/package.json

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