zz-meridian 0.6.1 → 0.7.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>.
+
+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/package.json

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

@@ -77,28 +77,46 @@ Dark is the default, written on `:root`; the light theme follows the operating s
 | `.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/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 |
 
-## 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>.
 
-`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/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>.
 
-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:
@@ -219,8 +223,10 @@ Modelled on the release pipeline of the owner's earlier packages, one package in
 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.
 

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.7.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/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/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');
+  });
+});