zz-meridian 0.6.1 → 0.8.0

package/README.md

@@ -6,10 +6,15 @@ dashboard depends on it afterwards.
 
 ## The one sentence
 
-Give your coding agent (Codex, Claude Code, or any agent that can run a shell) this, from your frontend's folder:
+Give your coding agent (Codex, Claude Code, or any agent that can run a shell) this, with what you want in your own
+words at the end:
 
-> Run `npx zz-meridian@latest adopt` here, then follow the zz-meridian skill it installs: keep our data layer and
-> routes, restyle every page with Meridian's components and tokens, and run pnpm verify until it passes.
+> Run `npx zz-meridian@latest skill --global`, then follow the zz-meridian skill it installs to: [what you want, in your own words].
+
+The skill picks the command from what you said and what is in the folder, and names it before running anything:
+`adopt` to change this Next.js App Router project in place ("make this admin panel look professional"), `create` for a
+new dashboard in a new folder ("build an ops dashboard", "a new one based on this folder, in another folder"), and
+`update` or `brand` for a project that already has Meridian.
 
 ## Commands
 
@@ -72,6 +77,14 @@ sends nothing anywhere; the only network access is your package manager's instal
 `--no-install`. 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
+
+The package collects nothing: no telemetry, no analytics, no account, and the template turns off Next.js's anonymous
+telemetry. It talks to npm only, when `npx` fetches it and when `update` reads releases. Feedback reaches us only as a
+[GitHub issue](https://github.com/zhixuan312/zz-meridian/issues/new/choose), a Bug or a Feature request; issues are
+public, so leave out anything that identifies you, your organisation or your product, and describe the problem with
+Meridian's own template or sample data.
+
 ## License
 
 MIT

package/dist/adopt.js

@@ -258,8 +258,12 @@ Rename or move them, then run adopt again.`);
         writes.set(`${dir}/icon.ts`, exactImports(`${dir}/icon.ts`, readPayload('app/icon.ts'), known));
     const ignore = path.join(root, '.gitignore');
     const ignored = fs.existsSync(ignore) ? fs.readFileSync(ignore, 'utf8') : '';
-    if (!/^\/?out\/?$/m.test(ignored))
-        writes.set('.gitignore', `${ignored.trimEnd()}\n\n# zz-meridian: verify's report and the screenshots\n/out/\n`);
+    // verify's report and screenshots, and an update in progress: Meridian's own, never the team's to commit. The manifest,
+    // keep.json and history/ are committed, since the next update reads them.
+    const bare = (l) => l.trim().replace(/^\//, '').replace(/\/$/, '');
+    const unignored = ['/out/', '/.meridian/update/', '/.meridian/update.lock'].filter((l) => !ignored.split('\n').some((x) => bare(x) === bare(l)));
+    if (unignored.length)
+        writes.set('.gitignore', `${ignored.trimEnd()}\n\n# zz-meridian: verify's report and an update in progress\n${unignored.join('\n')}\n`);
     // ── Write: every target checked first, so a bad one stops it before anything changes ─────────────────
     try {
         for (const rel of writes.keys())

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "zz-meridian",
-  "version": "0.6.1",
+  "version": "0.8.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",

package/payload/CHANGELOG.md

@@ -2,6 +2,29 @@
 
 Every release of ZZ Meridian, newest first. Versions follow semver: a removed or renamed token, prop or card is major; a new card, token or variant is minor; a corrected value is a patch. Each entry says what breaks and what to do instead.
 
+## [0.8.0] · 2026-10-06
+
+### Added
+
+- **A demo password in front of the whole product.** With `DEMO_PASSWORD` set at run time, `proxy.ts` sends every route to the sign-in page (an API answers 401), whose panel becomes "Open the demo": one password field, a 30-day signed session (`src/lib/demo-gate.ts`, keyed by `DEMO_SECRET` when set), and opening the page again signs out. Without it nothing changes: the panel is the product's sign-in and nothing is gated. The sign-in panel now streams in behind a Suspense boundary, so the rest of the page still prerenders. Meridian's own demo deploys to CapRover from this repository (`Dockerfile`, `captain-definition`, neither in the package).
+
+### Changed
+
+- **`update` is tested from the last three releases.** The release updates a project of the release before, adopted and created, through finalize; the weekly run the last three. Every published origin used to run at each release, which took 11 of its 18 minutes and grew with every release. From an older project, update in steps (`references/update.md`).
+
+### Fixed
+
+- **A project leaves an update in progress and each person's agent settings out of git.** Its `.gitignore` (the template's, for a created project; three lines `adopt` adds, for an adopted one) ignores `.meridian/update/` and `.meridian/update.lock`, the staged copies, backups and lock of an unfinished update, which a commit mid-session used to take in; a created project also ignores `.claude/settings.local.json` and `.claude/*.lock`. The manifest, `keep.json`, `.meridian/history/` and both copies of the skill stay committed: the next update and the team's agents read them. In a project made before 0.8.0, add those lines to `.gitignore`.
+- **The one sentence shows its blank.** It ended in `<what you want>`, which GitHub and npm read as an HTML tag and dropped, so it read "installs to: .". It ends in `[what you want, in your own words]`.
+
+## [0.7.0] · 2026-10-06
+
+### Changed
+
+- **One sentence for every route, and the skill chooses the command.** The README's sentence is `Run npx zz-meridian@latest skill --global, then follow the zz-meridian skill it installs to: <what you want>`. The skill opens with "Choose the route": a table from what the person said and what is in the folder to `adopt` (this Next.js App Router project, in place), `create` (a new folder, reading any folder named as the source and never writing it) or `update` and `brand`, and it says the route before the first command. The old sentence named `adopt`, which is wrong for a new dashboard.
+- **Next.js telemetry is off.** The template's `next.config.ts` sets `NEXT_TELEMETRY_DISABLED` for `next dev` and `next build`, and Meridian's scripts set it for every `next` they run, an adopted project's included. Delete the line in `next.config.ts` to send it.
+- **Feedback is an offer, and it identifies no one.** The skill's last step drafts a Bug or a Feature request issue only when the run found something about Meridian, removes every name, address, URL, record, schema and path of the person's own, shows the draft, and files nothing without a yes. The repository has Bug and Feature request issue forms that say the same, and no blank issues. The README and the npm page say what reaches the network (npm, the font download at build, what the team configures) and that an issue is the only way anything reaches Meridian.
+
 ## [0.6.1] · 2026-10-06
 
 ### Fixed

package/payload/README.md

@@ -74,31 +74,50 @@ Dark is the default, written on `:root`; the light theme follows the operating s
 | `scripts/` | Generators, gates, `brand.ts` and `verify.ts` (see `CONTRIBUTING.md`) |
 | `skills/zz-meridian/` | The agent skill (Claude Code, Codex) that builds dashboards on this template or brings it into yours |
 | `cli/` | The `zz-meridian` npm package: `create`, `adopt`, `update`, `brand` and `skill`, its build, its smoke test and the fixture app (`docs/distribution.md`) |
-| `.github/workflows/release.yml` | The release, each check once: a timed default verify and the consumer path from the tarball (every published origin updated), then npm with provenance, the registry's bytes and provenance checked, then the tag (`.claude/commands/release.md`) |
+| `.github/workflows/release.yml` | The release, each check once: a timed default verify and the consumer path from the tarball (the release before updated; the last three weekly), then npm with provenance, the registry's bytes and provenance checked, then the tag (`.claude/commands/release.md`) |
 | `.github/workflows/weekly.yml` | Weekly, never at release: `verify --full --perf` (perf a report) and the consumer smoke's recovery and failure cases; nothing waits on it |
+| `Dockerfile`, `captain-definition` | The demo deployment: the template and the Atlas behind `DEMO_PASSWORD` (`proxy.ts`, `app/sign-in/README.md`), deployed to CapRover from this repository; never in the package |
 
-## Bring Meridian into your dashboard, in one sentence
+## Get a dashboard on Meridian, in one sentence
 
-Give your coding agent (Codex, Claude Code, or any agent that can run a shell) this, from your frontend's folder:
+Give your coding agent (Codex, Claude Code, or any agent that can run a shell) this, with what you want in your own
+words at the end:
 
-> Run `npx zz-meridian@latest adopt` here, then follow the zz-meridian skill it installs: keep our data layer and routes, restyle every page with Meridian's components and tokens, and run pnpm verify until it passes.
+> Run `npx zz-meridian@latest skill --global`, then follow the zz-meridian skill it installs to: [what you want, in your own words].
 
-`adopt` does the settled part, the same way every time, and proves it type checks: it copies the components, tokens
-and gates in, merges the dependencies, brands it, adds Meridian's managed block to your `AGENTS.md` (your own text there is kept byte
-for byte) and an empty `docs/brief.md` for your product's own context, and installs the skill. The agent does the judgement: rebuilding each page on Meridian, and running
-`pnpm verify` until the project meets the standard (and `pnpm verify --full` after a change to shared components, the shell or
-data). It needs Node 22.18+, and Google Chrome for the browser checks. If your pages call a live API, say so in the sentence:
-`verify --full` presses every control, Delete included, so the agent builds a fake API first. For a new dashboard: `npx zz-meridian@latest create <dir>`. To move a project to a newer
-Meridian, run `npx zz-meridian@latest update --dry-run`, then follow the skill's `references/update.md`. The package
-(`cli/`, decision 0009) copies files and nothing depends on it afterwards.
+You do not choose between the package's commands; the skill does, from what you said and what is in the folder, and
+names the route before it runs anything:
 
-## Install the skill once, for every project
-
-```sh
-npx zz-meridian@latest skill --global
-```
-
-That puts the skill in `~/.agents/skills/zz-meridian` (Codex) and `~/.claude/skills/zz-meridian` (Claude Code). Then tell your agent what you need, in your own words: "build an ops dashboard for our shipments", "make this admin panel look professional", "turn this schema into a dashboard". The skill reads what you already have, asks only what it cannot find out, creates the project (or brings Meridian into yours) with the package, builds the pages, and runs `pnpm verify` until the project meets the standard.
+| You say | The skill |
+|---|---|
+| "Make this admin panel look professional", "change this product into our new dashboard" | `adopt` here, keeping your data layer and routes, when it is Next.js with the App Router; otherwise `create` next to it and port your pages |
+| "Build an ops dashboard for our shipments", "turn this schema into a dashboard" | `create` in a new folder |
+| "Based on this folder, make a new dashboard in another folder" | `create` in that folder, reading this one and leaving it untouched |
+| "Update Meridian", "change our brand colour" | `update` or `brand`, in a project that already has Meridian |
+
+`adopt` copies the components, tokens and gates in, merges the dependencies, brands it, adds Meridian's managed block to
+your `AGENTS.md` (your own text there is kept byte for byte) and an empty `docs/brief.md` for your product's own
+context, and installs the skill into the project. `create` writes a new, branded project with the same skill. The
+agent then does the judgement: building each page on Meridian, and running `pnpm verify` until the project meets the
+standard (`pnpm verify --full` after a change to shared components, the shell or data). It needs Node 22.18+, and
+Google Chrome for the browser checks. If your pages call a live API, say so in the sentence: `verify --full` presses
+every control, Delete included, so the agent builds a fake API first. The package (`cli/`, decision 0009) copies files
+and nothing depends on it afterwards; its commands are in `cli/README.md`.
+
+## Privacy and feedback
+
+Meridian takes nothing from you. The package, the template and the skill have no telemetry, no analytics and no
+account, and the template turns off Next.js's own anonymous telemetry (`next.config.ts`; Meridian's scripts turn it off
+for every `next` they run). What reaches the network is what you would expect: npm, when you run `npx` and when `update`
+reads releases from it; Google Fonts, which `next/font` downloads the typefaces from at build time; and whatever you
+configure yourself, such as the assistant's model provider.
+
+The one way to tell us anything is a [GitHub issue](https://github.com/zhixuan312/zz-meridian/issues/new/choose): a
+**Bug** (something in Meridian did the wrong thing) or a **Feature request** (something it should do, or do more
+easily). Issues are public, so leave out anything that identifies you, your organisation or your product: names,
+email addresses, URLs, your data and schemas, screenshots of your pages. Describe the problem with Meridian's own
+template or sample data instead. At the end of a build the skill may offer to draft one with all of that removed; it
+files nothing unless you say yes.
 
 ## Commands
 

package/payload/app/sign-in/README.md

@@ -25,6 +25,16 @@ Two columns from 1024px; one below, the panel under the sentence.
 | Invalid email | The field's error: "Enter your work email, like maya@zz-meridian.example." |
 | Sending | The primary button is busy |
 | Sent | The panel says "Check your inbox", names the address, and offers "Use another email" |
+| Demo | With `DEMO_PASSWORD` set at run time, the panel is "Open the demo": one password field (Field, Input `lg`) and "Open the demo" (primary, block, `lg`); a wrong password reads "That is not the demo password." in the field after 600 ms. A match sets a 30-day session and opens the console |
+| Loading | While the panel streams in, its surface holds its place, empty |
+
+## The demo gate
+
+`proxy.ts` and `src/lib/demo-gate.ts` put a password in front of the whole product when `DEMO_PASSWORD` is set: every
+route but this one redirects here (303), and an API answers 401. Opening this page signs the demo out, which is the
+rail's Sign out. `DEMO_SECRET`, when set, keys the session instead of the password. Without `DEMO_PASSWORD` nothing is
+gated and the panel is the product's sign-in. The panel is the only part of the page that reads the request; the rest
+prerenders (`gated-panel.tsx`, behind a Suspense boundary).
 
 ## Data
 

package/payload/app/sign-in/actions.ts

@@ -0,0 +1,19 @@
+'use server';
+
+import { cookies, headers } from 'next/headers';
+import { redirect } from 'next/navigation';
+import { COOKIE, MAX_AGE, samePassword, token } from '@/lib/demo-gate';
+
+export type DemoSignInState = { error: boolean };
+
+/** Checks the demo password: a match sets the session and opens the console, a miss comes back after 600 ms. */
+export async function demoSignIn(_: DemoSignInState, form: FormData): Promise<DemoSignInState> {
+  const given = String(form.get('password') ?? '').slice(0, 512);
+  if (!samePassword(given)) {
+    await new Promise((r) => setTimeout(r, 600));
+    return { error: true };
+  }
+  const secure = (await headers()).get('x-forwarded-proto') === 'https';
+  (await cookies()).set(COOKIE, token(), { httpOnly: true, path: '/', sameSite: 'lax', maxAge: MAX_AGE, secure });
+  redirect('/');
+}

package/payload/app/sign-in/gated-panel.tsx

@@ -0,0 +1,9 @@
+import { connection } from 'next/server';
+import { PasswordPanel, SignInPanel } from './panel';
+import { gated } from '@/lib/demo-gate';
+
+/** The demo's password when `DEMO_PASSWORD` is set at run time, the product's sign-in otherwise; the page around it prerenders. */
+export async function GatedPanel() {
+  await connection();
+  return gated() ? <PasswordPanel /> : <SignInPanel />;
+}

package/payload/app/sign-in/page.tsx

@@ -1,4 +1,6 @@
-import { SignInPanel } from './panel';
+import { Suspense } from 'react';
+import { GatedPanel } from './gated-panel';
+import { PanelFrame } from './panel';
 import { SampleFooter } from '@/views/sample-footer';
 import { Standalone } from '@/views/standalone';
 import { Meridian } from '@/components/charts/meridian';
@@ -18,7 +20,7 @@ export default function SignInPage() {
       kicker={`${app.name} · Console`}
       sentence="Know your API before your customers do."
       lead="Traffic, latency, spend and health for every endpoint, on your desk, on your phone, and inside the assistant you already use."
-      aside={<SignInPanel />}
+      aside={<Suspense fallback={<PanelFrame />}><GatedPanel /></Suspense>}
     >
       {/* The proof is the signature itself: point at a day and the line reads it, as every chart in the console does. */}
       <figure className="mt-12 max-w-xl rounded-xl border border-line bg-surface/60 p-5 backdrop-blur-md max-lg:hidden">

package/payload/app/sign-in/panel.tsx

@@ -1,11 +1,43 @@
 'use client';
 
-import { useState, type FormEvent } from 'react';
-import { ArrowRight, KeyRound, Mail } from 'lucide-react';
+import { useActionState, useState, type FormEvent, type ReactNode } from 'react';
+import { ArrowRight, KeyRound, LockKeyhole, Mail } from 'lucide-react';
 import { Button } from '@/components/ui/button';
 import { Field } from '@/components/ui/field';
 import { Input } from '@/components/ui/input';
 import { app, domain } from '@/app.config';
+import { demoSignIn } from './actions';
+
+/** The panel's surface, shared by both panels and the placeholder that holds their place while one streams in. */
+export function PanelFrame({ children }: { children?: ReactNode }) {
+  return (
+    <section aria-labelledby={children ? 'sign-in' : undefined} aria-hidden={children ? undefined : true} className="relative overflow-hidden rounded-xl border border-line bg-surface/80 p-7 shadow-overlay backdrop-blur-xl sm:p-8">
+      <span aria-hidden className="absolute inset-x-8 top-0 h-px bg-linear-to-r from-transparent via-accent-ink/60 to-transparent" />
+      {children ?? <div className="min-h-[22rem]" />}
+    </section>
+  );
+}
+
+/** The demo's panel, when `DEMO_PASSWORD` is set: one password field and one primary action. */
+export function PasswordPanel() {
+  const [state, action, pending] = useActionState(demoSignIn, { error: false });
+  return (
+    <PanelFrame>
+      <form action={action}>
+        <span className="grid size-11 place-items-center rounded-full bg-accent-tint text-accent-ink"><LockKeyhole className="size-5" /></span>
+        <h2 id="sign-in" className="t-section mt-5">Open the demo</h2>
+        <p className="t-small mt-2 text-ink-2">{app.name} on sample data. Enter the password you were given.</p>
+        <input type="text" name="username" value="demo" autoComplete="username" readOnly hidden />
+        <div className="mt-7 flex flex-col gap-4">
+          <Field label="Demo password" error={state.error ? 'That is not the demo password.' : undefined}>
+            {(p) => <Input {...p} name="password" type="password" size="lg" autoComplete="current-password" required autoFocus leading={<KeyRound className="size-4" />} />}
+          </Field>
+          <Button type="submit" variant="primary" size="lg" block busy={pending} trailing={<ArrowRight />}>Open the demo</Button>
+        </div>
+      </form>
+    </PanelFrame>
+  );
+}
 
 /** The sign-in panel: one field, one primary action, SSO beside it. A sent link replaces the form, never a toast. */
 export function SignInPanel() {
@@ -27,8 +59,7 @@ export function SignInPanel() {
     setState('sso');
   };
   return (
-    <section aria-labelledby="sign-in" className="relative overflow-hidden rounded-xl border border-line bg-surface/80 p-7 shadow-overlay backdrop-blur-xl sm:p-8">
-      <span aria-hidden className="absolute inset-x-8 top-0 h-px bg-linear-to-r from-transparent via-accent-ink/60 to-transparent" />
+    <PanelFrame>
       {state === 'sent' ? (
         <div role="status">
           <span className="grid size-11 place-items-center rounded-full bg-accent-tint text-accent-ink"><Mail className="size-5" /></span>
@@ -60,6 +91,6 @@ export function SignInPanel() {
           <p className="t-caption mt-6 text-pretty">By continuing you agree to the Terms and the Privacy notice. We never post anything for you.</p>
         </form>
       )}
-    </section>
+    </PanelFrame>
   );
 }

package/payload/decisions/0010-the-adopter-contract.md

@@ -54,8 +54,10 @@ this is the reason they agree.
   refuses, keeping every backup, when a path it wrote was edited since.
 - `--resume`, `--finalize` and `--abort` belong to the package version that began the session. They read the session's
   own copies and never ask the registry.
-- Updates start from 0.3.0. The four published origins, a project adopted and a project created with 0.3.0 and with
-  0.4.0, are the supported starting points, and the release smoke runs every one of them through update and finalize.
+- Updates start from 0.3.0. An update is tested from the last three releases, adopted and created: the release smoke
+  runs the release before through update and finalize, and the weekly smoke the last three. The window moves with each
+  release and never grows; from an older project, update in steps (`references/update.md`). Every published origin was
+  tested at release until 0.7.0, when the smoke took 11 of the release's 18 minutes and grew with each release.
 
 ### The access seam, scoped caching and live data
 
@@ -96,9 +98,9 @@ this is the reason they agree.
 - Weekly is weekly, release is release, and nothing runs twice. The release gates, each once, on the default verify
   from a clean `.next` on the GitHub-hosted ubuntu-24.04 4-CPU runner (at most 120 s, raised to 180 s in 0.6.0 because the runner's CPU varies, with its browser smoke; the gate
   and its unit tests run inside it) and on the consumer smoke from the tarball: adopt, create with its default verify,
-  and all four published origins updated through finalize. After publishing it checks the registry serves the tested
+  and the release before updated through finalize (the last three weekly). After publishing it checks the registry serves the tested
   tarball (equal sha256) with provenance, and tags last. A weekly workflow runs `verify --full --perf` (the perf part a
-  report) and the consumer smoke's adopted default-verify cases and recovery and failure cases; a failure notifies and
+  report) and the consumer smoke's adopted default-verify cases, the update from the last three releases, and its recovery and failure cases; a failure notifies and
   nothing waits on it.
 
 ### Every breaking interface, with its migration

package/payload/docs/distribution.md

@@ -4,12 +4,16 @@ Status: v1 (`create`, `adopt`, `skill`) shipped in 0.2.0 (decision 0009). v2 (`u
 
 ## The one sentence
 
-A team gives its coding agent this, from its frontend's folder:
+A team gives its coding agent this, with what it wants in its own words at the end:
 
-> Run `npx zz-meridian@latest adopt` here, then follow the zz-meridian skill it installs: keep our data layer and
-> routes, restyle every page with Meridian's components and tokens, and run pnpm verify until it passes.
+> Run `npx zz-meridian@latest skill --global`, then follow the zz-meridian skill it installs to: [what you want, in your own words].
 
-For a new dashboard: `npx zz-meridian@latest create <dir>`, then the same skill.
+The sentence names no command, because people do not: "change this product into our dashboard", "a new one based on
+this folder, in another folder" and "build an orders console" all ask for a dashboard on Meridian and differ only in
+which folder holds it. The skill's "Choose the route" table maps what was said, and what is in the folder, to `adopt`
+(this Next.js App Router project, in place), `create` (a new folder; a folder named as the source is read, never
+written) or `update` and `brand` (a project that already has Meridian), and says the route before the first command.
+An earlier sentence named `adopt`, the wrong command for every request for a new dashboard.
 
 The split follows what each part is good at. The package does the settled work, the same way every time, and proves it
 built: what to copy, which dependencies to merge, the alias, the stylesheet, the brand. The agent does the judgement:
@@ -214,13 +218,17 @@ Modelled on the release pipeline of the owner's earlier packages, one package in
    - `adopt` into `cli/test/fixture-next-app` (a minimal App Router app with one page and its own stylesheet), then
      install, `tsc --noEmit` and `next build`, all green. This is the test that keeps the Route A list complete.
    - `create` into a clean folder, then its default `pnpm verify`. The smoke quotes the coverage line.
-   - `update` from every published origin since 0.3.0 (adopted and created) through finalize, as above. A 0.5.0 origin
-     reports no migration; a created one with nothing to resolve completes in the update itself.
+   - `update` from the release before (adopted and created, read from the registry): a dry-run that writes nothing, the
+     update, what it reports resolved, finalize with the gate and the build, and the team's bytes unchanged. One origin
+     at release and the last three weekly, so the time stays the same however many releases there are; the updater's
+     own stages and each migration have their tests (`--update-all`, `tests/cli-*`).
 5. **Publish** the tarball with `npm` 11.5.1 or newer through trusted publishing (OIDC), with `--provenance`. `pnpm
    publish` does not perform the OIDC exchange.
 6. **The registry's package**: `npx zz-meridian@<version> --version` answers the version, the registry's tarball has the
-   tested tarball's sha256, and it carries a provenance attestation. The bytes passed step 4 already, so nothing runs
-   them twice. A failure here is an unsuccessful release, not a rollback: the version stays published and untagged
+   tested tarball's sha256, and it carries a provenance attestation. The bytes passed step 4 already; two paths still
+   change once the version is published, and run here, in about 10 seconds: `create` from the registry (npm renames a
+   packed `.gitignore` on install, so the project must have one), and `update` to the version in a project created
+   with the release before (it compares the running package with the registry's only once that one exists). A failure here is an unsuccessful release, not a rollback: the version stays published and untagged
    until a fix is released.
 7. **Tag `v<version>` last**, then the GitHub Release with the version's `CHANGELOG.md` section as its body.
 
@@ -228,8 +236,10 @@ Modelled on the release pipeline of the owner's earlier packages, one package in
 
 **Weekly** (`.github/workflows/weekly.yml`, Mondays and on demand, master's current commit): the template's
 `verify --full --perf`, one gate and one build for both (the perf part a report: a p95 over budget is a warning, a
-broken sample a failure), and the consumer smoke's `--adopt --update-all --verify` from a tarball packed from that
-commit: the adopted project's default verify cases and every recovery and failure case of the update. Weekly is weekly
+broken sample a failure), and the consumer smoke's `--adopt --update --origins 3 --update-all --verify` from a tarball packed from that
+commit, labelled as the next patch so `update` treats it as unpublished: the adopted project's default verify cases,
+the update from each of the last three releases, the updater's stages on the 0.3.0 fixture, and every recovery and
+failure case of the update. Weekly is weekly
 and release is release: neither runs what the other does. Each job keeps its log as an artifact. A failure notifies;
 nothing waits on it.
 

package/payload/gitignore

@@ -28,6 +28,16 @@ test-results
 # deployment
 .vercel
 
+# zz-meridian: an update in progress (its staged copies, backups and lock). .meridian/manifest.json, keep.json and
+# history/ are committed: the next update reads them.
+/.meridian/update/
+/.meridian/update.lock
+
+# agents: each person's own settings and runtime files. The skills under .claude/skills and .agents/skills are
+# committed: they are the version of the skill that matches this project's Meridian, and update keeps them so.
+/.claude/settings.local.json
+/.claude/*.lock
+
 # logs
 *-debug.log*
 *-error.log*

package/payload/next.config.ts

@@ -1,5 +1,8 @@
 import type { NextConfig } from 'next';
 
+// Next.js's anonymous usage telemetry is off for `next dev` and `next build`; delete this line to send it.
+process.env.NEXT_TELEMETRY_DISABLED ??= '1';
+
 const config: NextConfig = {
   reactStrictMode: true,
   cacheComponents: true,

package/payload/package.json

@@ -1,6 +1,6 @@
 {
   "name": "zz-meridian-template",
-  "version": "0.6.1",
+  "version": "0.8.0",
   "private": true,
   "license": "MIT",
   "description": "ZZ Meridian: a dashboard design system and starter. DTCG tokens, five layers of React components and a Design Atlas, in a light and a dark theme.",

package/payload/proxy.ts

@@ -0,0 +1,37 @@
+import { NextResponse, type NextRequest } from 'next/server';
+import { COOKIE, MAX_AGE, expiresOf, gated, token } from '@/lib/demo-gate';
+
+/**
+ * The demo's password gate (`src/lib/demo-gate.ts`), open unless `DEMO_PASSWORD` is set. Every route needs a live
+ * session except the sign-in page and the files a browser fetches for it; an API answers 401 instead of redirecting.
+ * Opening the sign-in page signs the demo out, which is what the rail's Sign out does. A visit past half the session's
+ * life renews it.
+ */
+export function proxy(req: NextRequest) {
+  if (!gated()) return NextResponse.next();
+  const { pathname } = req.nextUrl;
+  const value = req.cookies.get(COOKIE)?.value;
+  if (pathname === '/sign-in') {
+    const res = NextResponse.next();
+    // A POST here is the sign-in itself, which sets the session; only a visit clears it.
+    if (req.method === 'GET' && value) res.cookies.set(COOKIE, '', { path: '/', maxAge: 0 });
+    return res;
+  }
+  const expires = expiresOf(value);
+  if (!expires) {
+    if (pathname.startsWith('/api/')) return NextResponse.json({ error: 'Sign in to the demo first.' }, { status: 401 });
+    const to = req.nextUrl.clone();
+    to.pathname = '/sign-in';
+    to.search = '';
+    return NextResponse.redirect(to, 303);
+  }
+  const res = NextResponse.next();
+  if (expires - Date.now() / 1000 < MAX_AGE / 2) {
+    res.cookies.set(COOKIE, token(), { httpOnly: true, path: '/', sameSite: 'lax', maxAge: MAX_AGE, secure: req.headers.get('x-forwarded-proto') === 'https' });
+  }
+  return res;
+}
+
+export const config = {
+  matcher: ['/((?!_next/static|_next/image|favicon|icon|apple-icon).*)'],
+};

package/payload/scripts/check.ts

@@ -281,11 +281,12 @@ const retirements: Retirement[] = [];
 }
 
 // ── The template's request boundaries ────────────────────────────────────────────────────────────────
-// Two places read the request: the console layout, which hands the shell a promise, and the not-found page, which streams
-// the address in. A `connection()` anywhere else makes the page behind it wait for the request, and a template whose
+// Three places read the request: the console layout, which hands the shell a promise, the not-found page, which streams
+// the address in, and the sign-in page's panel, which streams in as the demo's password or the product's sign-in, set by
+// DEMO_PASSWORD at run time. A `connection()` anywhere else makes the page behind it wait for the request, and a template whose
 // pages all prerender has none. In a product those pages are the team's, so the rule is the template's alone.
 if (!fs.existsSync(manifestFile)) {
-  const BOUNDARIES = [`${APP_DIR}/(dashboard)/layout.tsx`, `${APP_DIR}/not-found.tsx`];
+  const BOUNDARIES = [`${APP_DIR}/(dashboard)/layout.tsx`, `${APP_DIR}/not-found.tsx`, `${APP_DIR}/sign-in/gated-panel.tsx`];
   /** Comments blanked, not removed, so a line number is the file's. */
   const blanked = (f: string) => read(f).replace(/\/\*[\s\S]*?\*\//g, (c) => c.replace(/[^\n]/g, ' ')).replace(/(^|[^:])\/\/[^\n]*/g, '$1');
   const lineOf = (src: string, at: number) => src.slice(0, at).split('\n').length;
@@ -293,7 +294,7 @@ if (!fs.existsSync(manifestFile)) {
   for (const f of sources) {
     if (BOUNDARIES.includes(f)) continue;
     blanked(f).split('\n').forEach((line, i) => {
-      if (/\bconnection\s*\(/.test(line)) problems.push(`${f}:${i + 1}: connection() outside the template's two request boundaries`);
+      if (/\bconnection\s*\(/.test(line)) problems.push(`${f}:${i + 1}: connection() outside the template's three request boundaries`);
     });
   }
   // A page and a view read the sample through src/data, so the day it becomes an API is one file's change. Every
@@ -339,7 +340,8 @@ const TOOLKIT = /^src\/lib\/(format|color|collection|live)\.ts$/;
 // release may add an export the team's code does not use yet. Only the project's own src/lib and src/data are swept.
 // The template, with no manifest, is swept whole.
 const meridians = new Set(Object.keys(effective?.files ?? {}));
-const kept = ['src', 'app', 'scripts'].flatMap((d) => walk(d, /\.tsx?$/)).filter((f) => !/(^|\/)preview\.tsx$/.test(f) && !f.startsWith('app/system/') && !atlasOnly.includes(f));
+// A root proxy.ts is the product's own code too: Next runs it before every request.
+const kept = [...['src', 'app', 'scripts'].flatMap((d) => walk(d, /\.tsx?$/)), ...(fs.existsSync(path.join(ROOT, 'proxy.ts')) ? ['proxy.ts'] : [])].filter((f) => !/(^|\/)preview\.tsx$/.test(f) && !f.startsWith('app/system/') && !atlasOnly.includes(f));
 const resolveSpec = (from: string, spec: string) => {
   const base = spec.startsWith('@/') ? path.join('src', spec.slice(2)) : spec.startsWith('.') ? path.join(path.dirname(from), spec) : null;
   if (!base) return null;

package/payload/scripts/lib/bin.ts

@@ -5,4 +5,8 @@ import path from 'node:path';
 
 const ROOT = path.resolve(import.meta.dirname, '../..');
 
+// The gate, verify and the live check run `next` in the project: Meridian's own runs send no Next.js telemetry, whatever
+// the project's next.config says.
+process.env.NEXT_TELEMETRY_DISABLED ??= '1';
+
 export const bin = (name: string) => path.join(ROOT, 'node_modules', '.bin', process.platform === 'win32' ? `${name}.cmd` : name);

package/payload/skills/zz-meridian/SKILL.md

@@ -38,6 +38,35 @@ These hold in every project, however it started, and nothing below overrides the
   API or read a database names a `fakeApi` (or says `noLiveApi`) in `scripts/verify.config.ts` first
   (`references/existing-project.md`, step 5).
 
+## Choose the route before anything else
+
+Whatever the words, the person wants one thing: a dashboard on Meridian. What you decide is **where its code lives**
+and **which folder you may write to**, and that picks one of four commands. People rarely name the command, so read
+the intent, not the verb: "change this product into our new dashboard", "redo this with Meridian", "make a new one
+based on this folder in another folder" and "build me an orders console" are all requests for a dashboard; they
+differ only in which folder ends up holding it.
+
+| What is true | The route | The command |
+|---|---|---|
+| `optional:.meridian/manifest.json` exists in the folder they point at | Already on Meridian: update, rebrand or keep building | `update` or `brand` (the next section), or straight to step 5 |
+| They want **this** project changed in place ("restyle this", "change this product into our dashboard", "make our admin look professional"), and it is Next.js with the App Router | Adopt, here | `npx zz-meridian@latest adopt` (`references/existing-project.md`, Route A) |
+| They want this project changed, and it is another stack (Vite, CRA, Remix, Vue, a static page) | A new project next to it, ported from it | `create <sibling folder>` (`references/existing-project.md`, Routes A2, B, C) |
+| They want a **new** dashboard: in another folder, "based on" or "from" this folder, a schema, a CSV, a spec or nothing | Create, elsewhere; what they pointed at is input you read, never a folder you write | `npx zz-meridian@latest create <new folder>` |
+
+Rules that settle the hard cases:
+
+- **The folder they name to read from is not the folder you write to unless they said "this", "here" or "in place".**
+  "Based on this folder", "use this as the source", "copy what this does" mean: read it, create next to it, leave it
+  untouched.
+- **`create` writes only into a folder that does not exist or is empty**, and **`adopt` changes the project it runs in**.
+  Never run `adopt` in a folder they asked you to leave alone, and never `create` inside an existing project.
+- **Two routes fit and nothing decides between them** (an existing Next.js app here and "build me a dashboard for
+  this"): ask once, with in place (`adopt`) as the recommended option when they said "this" or "our", and a new folder
+  (`create`) when they said "new" or "another". With no way to ask, take that recommendation and say so in the
+  hand-over.
+- **Say the route in one sentence before the first command**: "This is a Next.js App Router project you want changed
+  in place, so I am running `adopt` here." A wrong route is cheap to stop before the command and costly after it.
+
 ## Updating or rebranding a project that already has Meridian
 
 When `optional:.meridian/manifest.json` exists and the person asks to update Meridian, or to change the brand, do not
@@ -70,8 +99,8 @@ Before asking anything, look at what you already have:
 Ask in a single round (AskUserQuestion when available), only the questions your homework could not answer, and offer
 your draft as the recommended option so the person can accept it in one click. Usually that is:
 
-1. **New project or this one?** Only when a frontend already exists here: create a new Meridian project next to it, or
-   bring Meridian into the existing one (`references/existing-project.md`).
+1. **New project or this one?** Only when "Choose the route" above left two routes open: create a new Meridian project
+   in another folder, or bring Meridian into the existing one (`references/existing-project.md`).
 2. **What it is and for whom.** The product name, who uses it, and the one question the home page must answer.
 3. **Pages.** Your drafted list, mapped to Meridian presets (Overview, list, detail, analytics, health, settings, sign-in).
 4. **Brand and surfaces.** A brand colour (a hex, or "no preference" for indigo), light or dark first (dark is the
@@ -230,49 +259,57 @@ Pages: <list, one line each, with what each answers>.
 Brand: <accent and how it was derived>. Surfaces: console, mobile<, MCP views: …>.
 Validation: pnpm verify passed; coverage line: <the line verify printed>.
 Next steps: replace the sample data in src/data/ with <their API>; run pnpm verify after every change.
-Feedback: <the issue URL from step 8, or "nothing to report">.
+Feedback: <the issue URL from step 8, "nothing to report", or "declined">.
 ```
 
 Attach or show the screenshots of the main pages in both themes. Say plainly what is sample data and what is not. If
 the Atlas stays, say that `/system` is the live specification and that `node scripts/brand.ts --no-atlas` removes it
 before the product goes public.
 
-## 8. Report back to Meridian
+## 8. Offer feedback to Meridian
 
-Every build teaches Meridian something. Before you finish, write down everything this run found about Meridian itself
-and file it as **one** GitHub issue on `zhixuan312/zz-meridian`, so the next person does not hit the same thing.
+Meridian collects nothing from the people who use it: no telemetry, no analytics, no account. A GitHub issue the person
+chooses to open is the only way anything reaches Meridian, so this step is an offer, never a requirement, and it
+happens only when the run found something about Meridian itself.
 
-Collect, from the whole session (not only the last step):
+Collect, from the whole session (not only the last step), and sort each finding into one of two kinds:
 
-- **Bugs**: a component, pattern, script, check or doc that did the wrong thing: a gate that failed on correct code, a
+- **Bug**: a component, pattern, script, check or doc that did the wrong thing: a gate that failed on correct code, a
   check that passed broken code, a component that clipped, overflowed or did nothing, a doc that sent you the wrong way.
-- **Improvements**: anything that worked but cost you a workaround, a second try, or a guess, and how it could be easier.
-- **Not covered**: what the product needed that Meridian has no answer for: a missing component, pattern, state, page
-  kind, surface rule, or a question this skill and the docs never answered.
+- **Feature request**: anything that worked but cost a workaround, a second try or a guess, and the change that would
+  have saved it; and what the product needed that Meridian has no answer for (a component, pattern, state, page kind,
+  surface rule, or a question this skill and the docs never answered).
 
-Each item gets what someone needs to act on it without asking you: what happened, where (`file:line`, the route, the
-command), how to see it again, and what you did instead. Leave out what is the person's own (their product name, data,
-URLs, credentials, screenshots of their pages); describe the shape of the problem with Meridian's sample instead.
+Each finding gets what someone needs to act on it without asking: what happened, where in Meridian (its `file:line`,
+the Meridian command, the Meridian route), how to see it again in Meridian's own template or sample data, and what you
+did instead.
 
-Draft it in this shape:
+**Nothing in it may identify the person, their organisation or their product.** Before showing a draft, remove:
 
-```
-Title: Field report: <one line on the most important finding>
+- the product's, company's, team's and people's names, email addresses and accounts;
+- their URLs, hostnames, IP addresses, API routes and environment variable values;
+- their data, records, schemas, field names and screenshots of their pages;
+- file paths outside Meridian's own files, and anything from `optional:docs/brief.md`.
+
+Describe the shape of the problem with Meridian's sample instead ("a Data table with 40 columns", not their table). If
+a finding cannot be told without one of these, leave it out.
 
-Meridian <commit or version> · Next <version> · <what was built, in generic terms: "an orders console, 6 pages">
+Draft one issue per kind, in the shape of Meridian's two issue forms, Bug and Feature request:
+
+```
+Title: <one line on the most important finding>
 
-## Bugs
-- <what, where, how to reproduce, what you did instead>
+Meridian <version from .meridian/manifest.json> · Next <version> · Route <adopt | create>
 
-## Improvements
-- <what cost time, and the change that would have saved it>
+## What happened
+- <finding: what, where in Meridian, how to see it again, what you did instead>
 
-## Not covered
-- <what was needed, and how you filled the gap>
+## What would fix it
+- <the change you would make to Meridian>
 ```
 
-Show the draft to the person and file it only when they agree: it is published under their account. File it with
-`gh issue create --repo zhixuan312/zz-meridian --title "<title>" --body-file <draft>`. Without `gh`, give them a link
-that opens the form filled in: `https://github.com/zhixuan312/zz-meridian/issues/new?title=<encoded title>&body=<encoded
-body>`. Put the issue's URL in the hand-over. If the run truly found nothing, say "nothing to report" rather than filing
-an empty issue.
+Show the draft to the person and ask whether to open it: it is published under their account, in public. Only on a
+yes, file it with `gh issue create --repo zhixuan312/zz-meridian --label bug|enhancement --title "<title>" --body-file
+<draft>`, or, without `gh`, give them `https://github.com/zhixuan312/zz-meridian/issues/new/choose` and the draft to
+paste. Put the issue's URL in the hand-over. When the run found nothing about Meridian, or they decline, say so in one
+line and file nothing.

package/payload/skills/zz-meridian/references/update.md

@@ -5,6 +5,10 @@ Meridian would change, and which of those changes need the team's decision. It w
 `npx zz-meridian@latest update` then applies the safe changes and stages the rest. Do not copy files by hand to make up
 for either.
 
+An update is tested from the last three releases. When the manifest's version is older than that (`npm view
+zz-meridian versions` lists them), update in steps: first with the release three after it,
+`npx zz-meridian@<that version> update`, through finalize, then again with `latest`.
+
 ## What it does
 
 It works from `optional:.meridian/manifest.json`, which records the release the project was copied from and a hash of

package/payload/src/lib/demo-gate.ts

@@ -0,0 +1,39 @@
+/**
+ * A password in front of the whole product, for a demo deployment: an HttpOnly cookie holding an expiry and its HMAC.
+ * It is closed only when `DEMO_PASSWORD` is set; without it (local development, and every product that never sets it)
+ * nothing is gated. The key is derived from `DEMO_SECRET` (or, without it, from `DEMO_PASSWORD`), so a session survives
+ * restarts and redeploys, and changing either signs everyone out. A session lasts 30 days and is renewed when a visit
+ * finds it past half its life. Server only.
+ */
+import crypto from 'node:crypto';
+
+export const COOKIE = 'zz_meridian_demo';
+export const MAX_AGE = 30 * 24 * 3600;
+
+const password = () => process.env.DEMO_PASSWORD ?? '';
+/** Whether the gate is closed: only when a password is configured. */
+export const gated = () => password() !== '';
+const key = () => crypto.createHmac('sha256', process.env.DEMO_SECRET || password()).update('zz-meridian-demo-session-v1').digest();
+const sign = (expires: number | string) => crypto.createHmac('sha256', key()).update(String(expires)).digest('hex');
+
+/** A fresh session value: expiry.signature. */
+export function token(): string {
+  const expires = Math.floor(Date.now() / 1000) + MAX_AGE;
+  return `${expires}.${sign(expires)}`;
+}
+
+/** The session's expiry in seconds when the cookie value is genuine and unexpired, else 0. */
+export function expiresOf(value: string | undefined): number {
+  const m = value?.match(/^([0-9]+)\.([0-9a-f]{64})$/);
+  if (!m || Number(m[1]) < Date.now() / 1000) return 0;
+  const a = Buffer.from(m[2]!, 'hex');
+  const b = Buffer.from(sign(m[1]!), 'hex');
+  return a.length === b.length && crypto.timingSafeEqual(a, b) ? Number(m[1]) : 0;
+}
+
+/** Compares with the configured password in constant time, whatever the lengths. */
+export function samePassword(given: string): boolean {
+  const a = crypto.createHash('sha256').update(given).digest();
+  const b = crypto.createHash('sha256').update(password()).digest();
+  return gated() && crypto.timingSafeEqual(a, b);
+}

package/payload/tests/demo-gate.test.ts

@@ -0,0 +1,64 @@
+// @vitest-environment node
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+import { NextRequest } from 'next/server';
+import { COOKIE, MAX_AGE, expiresOf, gated, samePassword, token } from '@/lib/demo-gate';
+import { proxy } from '../proxy';
+
+const request = (path: string, { cookie, method = 'GET' }: { cookie?: string; method?: string } = {}) =>
+  new NextRequest(`https://demo.example${path}`, { method, headers: cookie ? { cookie: `${COOKIE}=${cookie}` } : {} });
+
+afterEach(() => { delete process.env.DEMO_PASSWORD; delete process.env.DEMO_SECRET; });
+
+describe('the demo gate, without DEMO_PASSWORD', () => {
+  it('is open: every route passes and no password matches', () => {
+    expect(gated()).toBe(false);
+    expect(samePassword('')).toBe(false);
+    expect(proxy(request('/')).headers.get('location')).toBeNull();
+    expect(proxy(request('/api/export/requests')).status).toBe(200);
+  });
+});
+
+describe('the demo gate, with DEMO_PASSWORD', () => {
+  beforeEach(() => { process.env.DEMO_PASSWORD = 'open sesame'; });
+
+  it('accepts the password and nothing else', () => {
+    expect(samePassword('open sesame')).toBe(true);
+    expect(samePassword('open sesam')).toBe(false);
+    expect(samePassword('')).toBe(false);
+  });
+  it('signs a session it can read back, and refuses a forged, an expired or a re-keyed one', () => {
+    const t = token();
+    expect(expiresOf(t)).toBeGreaterThan(Date.now() / 1000 + MAX_AGE - 5);
+    expect(expiresOf(`${Number(t.split('.')[0]) + 1}.${t.split('.')[1]}`)).toBe(0);
+    expect(expiresOf(`1.${t.split('.')[1]}`)).toBe(0);
+    expect(expiresOf(undefined)).toBe(0);
+    process.env.DEMO_SECRET = 'rotated';
+    expect(expiresOf(t)).toBe(0);
+  });
+  it('sends a visitor without a session to the sign-in page, and answers an API with 401', () => {
+    const page = proxy(request('/system'));
+    expect(page.status).toBe(303);
+    expect(new URL(page.headers.get('location')!).pathname).toBe('/sign-in');
+    expect(proxy(request('/api/assistant', { method: 'POST' })).status).toBe(401);
+  });
+  it('lets a session through, and renews one past half its life', () => {
+    const fresh = proxy(request('/', { cookie: token() }));
+    expect(fresh.headers.get('location')).toBeNull();
+    expect(fresh.cookies.get(COOKIE)).toBeUndefined();
+    vi.useFakeTimers();
+    try {
+      const t = token();
+      vi.setSystemTime(Date.now() + 20 * 24 * 3600 * 1000);
+      const renewed = proxy(request('/', { cookie: t })).cookies.get(COOKIE)?.value;
+      expect(renewed).not.toBe(t);
+      expect(expiresOf(renewed)).toBeGreaterThan(expiresOf(t));
+    } finally {
+      vi.useRealTimers();
+    }
+  });
+  it('signs the demo out when the sign-in page is opened, and leaves the sign-in itself alone', () => {
+    expect(proxy(request('/sign-in')).status).toBe(200);
+    expect(proxy(request('/sign-in', { cookie: token() })).cookies.get(COOKIE)?.value).toBe('');
+    expect(proxy(request('/sign-in', { cookie: token(), method: 'POST' })).cookies.get(COOKIE)).toBeUndefined();
+  });
+});

package/payload/tests/telemetry.test.ts

@@ -0,0 +1,15 @@
+// @vitest-environment node
+import { beforeEach, describe, expect, it, vi } from 'vitest';
+
+beforeEach(() => { vi.resetModules(); delete process.env.NEXT_TELEMETRY_DISABLED; });
+
+describe('Next.js telemetry', () => {
+  it("is off in the template's next.config, which next dev and next build load before they send any", async () => {
+    await import('../next.config.ts');
+    expect(process.env.NEXT_TELEMETRY_DISABLED).toBe('1');
+  });
+  it("is off for every next the gate, verify and the live check run, whatever the project's own config says", async () => {
+    await import('../scripts/lib/bin.ts');
+    expect(process.env.NEXT_TELEMETRY_DISABLED).toBe('1');
+  });
+});