zz-meridian 0.34.0 → 0.35.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "zz-meridian",
-  "version": "0.34.0",
+  "version": "0.35.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,21 @@
 
 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.35.0] · 2026-10-29
+
+A third level in the rail: a navigation item can have sub pages, drawn in a branch under it, and the sample shows one (Traffic, Usage, Requests).
+
+### Breaking
+
+- **`PageFrame` draws its kicker in a `div`, not a `p`.** A kicker can now hold block content such as a `Breadcrumb`, which inside a `p` was invalid HTML and a hydration mismatch. The `t-kicker` class and the look are unchanged. A test of your own that asserts the kicker's tag name expects `DIV`, and a selector written as `p.t-kicker` is written `.t-kicker`.
+
+### Added
+
+- **A navigation item can have sub pages, drawn as a third level in the rail.** Set `under` on a `NavItem` to the `href` of another item of the same group, and the rail draws the item in that item's branch, on a guide line and without an icon. The parent stays a link to its own page, with a button beside it named `<label> pages` that opens and closes the branch. A branch is open on arrival when the current page is its parent or one of its sub pages, and a closed branch draws none of its links. A closed branch that holds the current page puts the pill on its parent, so the rail always shows where the person is. A sub page the person may not open is not drawn, and one whose parent they may not open is drawn as a plain item. No migration is needed: `under` is optional, and a navigation without it draws as before.
+- **The gate refuses a sub page the rail cannot draw.** `node scripts/check.ts` refuses an `under` that names no item of the same group, the item itself, or an item that is itself under another (three levels, never four). It also refuses a sub page in another workspace than its parent, and more than 7 sub pages under one parent. Each refusal names the item's `href`.
+- **The palette and the masthead say where a sub page sits.** The command palette's hint for a sub page is its parent's label, so typing a parent's label finds its sub pages. `navTrail(href, nav)` in `src/components/patterns/rail/trail.ts` derives a page's crumbs from the navigation: for a sub page, its parent as a link, then the page. The sample's Requests page draws it as its kicker, Usage then Requests.
+- **The sample shows all three levels.** Business is now two labelled groups: Accounts (Revenue, Customers) and Traffic (Usage, with Requests under it). The Rail preview draws every branch state.
+
 ## [0.34.0] · 2026-10-29
 
 ### Changed

package/payload/app/(dashboard)/requests/README.md

@@ -8,7 +8,7 @@ Status: beta
 
 | Row | Pattern | Console (1024px and wider) | Mobile |
 |---|---|---|---|
-| Masthead | PageFrame: kicker "ZZ Meridian · Production", title "Requests", one sentence, Freshness, Export CSV | One band | Title, sentence, then Freshness and Export on their own row |
+| Masthead | PageFrame: kicker its trail in the navigation (Usage, then Requests), from `navTrail`, title "Requests", one sentence, Freshness, Export CSV | One band | Title, sentence, then Freshness and Export on their own row |
 | 1 | Row `tiles`: three Metric tiles for what the filters let through: requests, errors and limits, latency p95, each with its 5-minute shape over the last hour and the last half hour against the one before | Three across | One column |
 | 2 | Data table with a Filter bar in its toolbar: search, Status, Method, Region, the result count | Columns: Request (grow), Status, Latency, Customer and Region (once the table is 896px wide), Size (1152px), Received; a table under 640px wide is the card list. A row opens its request; its Customer opens the customer's page | Card list: route and status, then latency, customer and when |
 

package/payload/app/(dashboard)/requests/loading.tsx

@@ -1,3 +1,6 @@
+import { nav } from '@/app.config';
+import { navTrail } from '@/components/patterns/rail/trail';
+import { Breadcrumb } from '@/components/ui/breadcrumb';
 import { LoadingPage } from '@/components/patterns/page-loading';
 import { gatedLoading } from '@/data/refusal';
 import { RecordsSkeleton } from '@/components/templates/records';
@@ -5,7 +8,7 @@ import { RecordsSkeleton } from '@/components/templates/records';
 /** Requests on its way: three tiles over a few table rows; the page's own fallback is the same, so a navigation does not jump. */
 export default function RequestsLoading() {
   return (
-    <LoadingPage {...gatedLoading({ name: 'requests', title: 'Requests' })}>
+    <LoadingPage {...gatedLoading({ name: 'requests', title: 'Requests', kicker: <Breadcrumb items={navTrail('/requests', nav)} /> })}>
       <RecordsSkeleton tiles={3} rows={3} filters={false} />
     </LoadingPage>
   );

package/payload/app/(dashboard)/requests/page.tsx

@@ -1,6 +1,8 @@
 import { Suspense, cache } from 'react';
-import { app } from '@/app.config';
+import { nav } from '@/app.config';
 import { PageFrame } from '@/components/base/shell';
+import { navTrail } from '@/components/patterns/rail/trail';
+import { Breadcrumb } from '@/components/ui/breadcrumb';
 import { ExportButton } from '@/components/patterns/export-button';
 import { Freshness } from '@/components/patterns/freshness';
 import { gate, gatedMetadata } from '@/data/access';
@@ -26,7 +28,7 @@ export default async function RequestsPage({ searchParams }: { searchParams: Sea
   if (denied) return RefusalScreen(denied);
   return (
     <PageFrame
-      kicker={<>{app.name} · {app.workspace}</>}
+      kicker={<Breadcrumb items={navTrail('/requests', nav)} />}
       title="Requests"
       description="The most recent calls that reached the gateway, newest first. Open one to see where its time went."
       meta={<Suspense fallback={<span className="inline-block h-4 w-28" />}><RequestsFreshness searchParams={searchParams} /></Suspense>}

package/payload/journeys/workspaces.ts

@@ -128,8 +128,11 @@ async function press(page: Page, spec: Spec) {
   await page.send('Input.dispatchMouseEvent', { type: 'mouseReleased', x: at.x, y: at.y, button: 'left', clickCount: 1 });
 }
 
-const key = (page: Page, k: string, code: string, vk: number, text?: string) => page.send('Input.dispatchKeyEvent', { type: 'keyDown', key: k, code, windowsVirtualKeyCode: vk, ...(text ? { text, unmodifiedText: text } : {}) })
-  .then(() => page.send('Input.dispatchKeyEvent', { type: 'keyUp', key: k, code, windowsVirtualKeyCode: vk }));
+const key = (page: Page, k: string, code: string, vk: number, text?: string, modifiers?: number) => {
+  const mods = modifiers ? { modifiers } : {};
+  return page.send('Input.dispatchKeyEvent', { type: 'keyDown', key: k, code, windowsVirtualKeyCode: vk, ...mods, ...(text ? { text, unmodifiedText: text } : {}) })
+    .then(() => page.send('Input.dispatchKeyEvent', { type: 'keyUp', key: k, code, windowsVirtualKeyCode: vk, ...mods }));
+};
 
 /** Type into the focused field, one key at a time. */
 async function type(page: Page, s: string) {
@@ -169,7 +172,54 @@ const ownerOf = (path: string): string | null => {
 
 /** A person's routes: the ones the verification configuration says they may open, written there by hand. */
 const routesOf = (name: string) => [...persona(name).expectedRoutes];
-const railHrefs = (ws: string, routes: string[]) => items.filter((i) => i.workspace === ws && routes.includes(i.href)).map((i) => i.href);
+
+/** The held items of one navigation group in a workspace, for a person who may open `routes`. */
+const heldIn = (g: (typeof nav)[number], ws: string, routes: string[]) => g.items.filter((i) => i.workspace === ws && routes.includes(i.href));
+/**
+ * The parent a held item hangs under, as the rail reads it: the held item of the same group that `under` names, when that
+ * is not itself a sub page; otherwise null and the item stands at the top level.
+ */
+const parentIn = (held: (typeof items)[number][], it: (typeof items)[number]): string | null => {
+  const under = 'under' in it && typeof it.under === 'string' ? it.under : undefined;
+  const parent = under === undefined ? undefined : held.find((p) => p.href === under && p !== it);
+  if (!parent) return null;
+  const grand = 'under' in parent && typeof parent.under === 'string' ? parent.under : undefined;
+  return grand !== undefined && held.some((x) => x.href === grand && x !== parent) ? null : parent.href;
+};
+/** The parent a destination hangs under for a person who may open `routes`; null when it stands at the top level. */
+const parentOfHref = (href: string, routes: string[]) => {
+  const g = nav.find((x) => x.items.some((i) => i.href === href));
+  const it = g?.items.find((i) => i.href === href);
+  if (!g || !it?.workspace) return null;
+  return parentIn(heldIn(g, it.workspace, routes), it);
+};
+
+/**
+ * The parents whose branch each page has open, as the rail keeps its own: every full load empties it, arriving at a page
+ * opens the branch that holds its current entry, pressing a branch's button toggles it, and a client navigation leaves it.
+ */
+const branches = new WeakMap<Page, Set<string>>();
+const openIn = (page: Page) => { let s = branches.get(page); if (!s) branches.set(page, (s = new Set())); return s; };
+const loaded = (page: Page) => openIn(page).clear();
+
+/**
+ * What the rail draws for a workspace, in the order of the page: each group's top-level destinations, and after a parent
+ * its sub pages when its branch is open. A sub page whose parent is not held stands at the top level.
+ */
+const railHrefs = (ws: string, routes: string[], open: Set<string>) =>
+  nav.flatMap((g) => {
+    const held = heldIn(g, ws, routes);
+    return held.filter((i) => !parentIn(held, i)).flatMap((i) => [i.href, ...(open.has(i.href) ? held.filter((s) => parentIn(held, s) === i.href).map((s) => s.href) : [])]);
+  });
+/** The branch that holds the address's current entry: the parent whose own page it is, or whose sub page it is. */
+const branchOf = (ws: string, routes: string[], path: string) => {
+  const all = nav.flatMap((g) => heldIn(g, ws, routes));
+  const cur = currentIn(path, all.map((i) => i.href));
+  if (cur === null) return null;
+  const parent = parentOfHref(cur, routes);
+  if (parent) return parent;
+  return nav.some((g) => { const held = heldIn(g, ws, routes); return held.some((s) => parentIn(held, s) === cur); }) ? cur : null;
+};
 const currentIn = (path: string, hrefs: string[]) => hrefs.filter((h) => (h === '/' ? path === '/' : path === h || path.startsWith(`${h}/`))).sort((a, b) => b.length - a.length)[0] ?? null;
 
 /**
@@ -179,19 +229,25 @@ const currentIn = (path: string, hrefs: string[]) => hrefs.filter((h) => (h ===
  */
 async function settle(page: Page, who: string, path: string | RegExp, ws?: string) {
   const routes = routesOf(who);
+  const open = openIn(page);
   let found = 'nothing read';
   let expected = '';
   try {
     await until('', async () => {
       const r = await railOf(page);
       const owner = ws ?? ownerOf(r.path) ?? 'main';
-      const hrefs = railHrefs(owner, routes);
-      const cur = currentIn(r.path, hrefs);
+      const at = path instanceof RegExp ? path.test(r.path) : r.path === path;
+      // Arriving at a page opens the branch that holds its entry.
+      const arrival = at ? branchOf(owner, routes, r.path) : null;
+      if (arrival) open.add(arrival);
+      const hrefs = railHrefs(owner, routes, open);
+      // The current entry is the longest held one; when its branch is closed it is not drawn, and the rail marks nothing as the page.
+      const entry = currentIn(r.path, nav.flatMap((g) => heldIn(g, owner, routes).map((i) => i.href)));
+      const cur = entry !== null && hrefs.includes(entry) ? entry : null;
       expected = `${path} with the rail on "${W[owner].label}" showing ${hrefs.join(' ')} (current ${cur})`;
       const seen = r.links?.map((l) => l.href) ?? null;
       const now = r.links?.find((l) => l.current)?.href ?? null;
       found = `${r.path}${r.search} with the rail on "${railWorkspace(r)}" showing ${seen?.join(' ') ?? 'no links'} (current ${now})`;
-      const at = path instanceof RegExp ? path.test(r.path) : r.path === path;
       return at && railWorkspace(r) === W[owner].label && seen?.join(' ') === hrefs.join(' ') && now === cur;
     });
   } catch {
@@ -200,6 +256,21 @@ async function settle(page: Page, who: string, path: string | RegExp, ws?: strin
   return (await railOf(page)).path;
 }
 
+/**
+ * Press a destination's link in the rail. A sub page's link is not drawn while its parent's branch is closed, so a person
+ * first presses the parent's `<label> pages` button, and the branch is then open.
+ */
+async function pressRail(page: Page, who: string, href: string) {
+  const link: Spec = { role: 'link', name: labelOf(href), within: 'nav[aria-label="Main"]' };
+  const parent = parentOfHref(href, routesOf(who));
+  if (parent && !(await ask<boolean>(page, `return find(${JSON.stringify(link)}).length > 0;`))) {
+    await press(page, { role: 'button', name: `${labelOf(parent)} pages`, within: 'nav[aria-label="Main"]' });
+    const open = openIn(page);
+    if (!open.delete(parent)) open.add(parent);
+  }
+  await press(page, link);
+}
+
 /** Choose a workspace in the rail's menu, as a person does: open the menu, press the row. */
 async function choose(page: Page, id: string) {
   await press(page, { role: 'button', re: `${MENU_END}$` });
@@ -216,6 +287,7 @@ const opened: Page[] = [];
 const browser = async () => { const p = await launch(); opened.push(p); return p; };
 const go = async (page: Page, who: string, path: string) => {
   quiet(page, 'the page before');
+  loaded(page);
   await page.open(base + path, { width: 1440, height: 900, theme: 'dark', wait: 300, cookie: persona(who).cookie });
 };
 
@@ -336,8 +408,34 @@ if (import.meta.main) {
       // Home's Business card opens the Business home; the rail then names Business and offers Requests.
       await press(a, { role: 'link', hrefRe: '^/business$', within: '[role="region"][aria-label="Business"]' });
       await settle(a, 'member', '/business', 'business');
-      await press(a, { role: 'link', name: labelOf(REQUESTS), within: 'nav[aria-label="Main"]' });
+      await pressRail(a, 'member', REQUESTS);
       await settle(a, 'member', REQUESTS, 'business');
+      // The masthead's trail names the parent as a link, then the page as the current one; the palette hints the parent.
+      const parentHref = parentOfHref(REQUESTS, routesOf('member'));
+      const parentLabel = parentHref === null ? null : labelOf(parentHref);
+      const groupLabel = nav.find((g) => g.items.some((i) => i.href === REQUESTS))?.label ?? '';
+      const label = labelOf(REQUESTS);
+      const crumbs = await ask<{ links: { href: string; label: string }[]; current: string | null }>(a, `
+        const bc = document.querySelector('nav[aria-label="Breadcrumb"]');
+        if (!bc) return { links: [], current: null };
+        const cur = bc.querySelector('[aria-current="page"]');
+        return { links: [...bc.querySelectorAll('a[href]')].map((l) => ({ href: l.getAttribute('href'), label: text(l) })), current: cur ? text(cur) : null };`);
+      const wantLinks = parentHref === null ? [] : [{ href: parentHref, label: parentLabel }];
+      if (JSON.stringify(crumbs.links) !== JSON.stringify(wantLinks) || crumbs.current !== label) {
+        throw new Error(`expected the Breadcrumb to hold ${JSON.stringify(wantLinks)} and then "${label}" as the current page; found links ${JSON.stringify(crumbs.links)} and current ${JSON.stringify(crumbs.current)}`);
+      }
+      // The palette listens on window for Ctrl or Command with K; a button would be ambiguous, the not-found view has a second one.
+      await key(a, 'k', 'KeyK', 75, undefined, 2);
+      await until('the palette search field', () => centre(a, { role: 'combobox', name: 'Search pages and commands' }));
+      await type(a, label);
+      const hint = await until(`the palette option "${label}"`, () => ask<{ hint: string | null } | null>(a, `
+        const row = [...document.querySelectorAll('[role="option"]')].find((o) => [...o.querySelectorAll('span[title]')].some((t) => t.getAttribute('title') === ${JSON.stringify(label)}));
+        if (!row) return null;
+        const h = row.querySelector('span.text-xs');
+        return { hint: h ? text(h) : null };`));
+      const wantHint = parentLabel ?? groupLabel;
+      if (hint.hint !== wantHint) throw new Error(`expected the palette option "${label}" to carry the hint "${wantHint}"; found ${JSON.stringify(hint.hint)}`);
+      await key(a, 'Escape', 'Escape', 27);
       await press(a, { role: 'link', hrefRe: '^/requests/[^/]+$', within: 'main table tbody' });
       const at = await settle(a, 'member', /^\/requests\/[^/]+$/, 'business');
       return `(${at})`;
@@ -400,13 +498,14 @@ if (import.meta.main) {
       await settle(a, 'member', HOME, 'main');
       await choose(a, 'business');
       await settle(a, 'member', W.business.homeHref, 'business');
-      await press(a, { role: 'link', name: labelOf(REQUESTS), within: 'nav[aria-label="Main"]' });
+      await pressRail(a, 'member', REQUESTS);
       await settle(a, 'member', REQUESTS, 'business');
       await press(a, { role: 'link', hrefRe: '^/requests/[^/]+$', within: 'main table tbody' });
       const request = await settle(a, 'member', /^\/requests\/[^/]+$/, 'business');
       // A refresh: the page is marked first, so that only the new document can satisfy the wait.
       await a.eval('window.__before = true');
       await a.send('Page.reload');
+      loaded(a);
       await until('the page to reload', () => a.eval<boolean>('window.__before === undefined && document.readyState !== "loading"'));
       await settle(a, 'member', request, 'business');
       for (const path of trail) {

package/payload/package.json

@@ -1,6 +1,6 @@
 {
   "name": "zz-meridian-template",
-  "version": "0.34.0",
+  "version": "0.35.0",
   "private": true,
   "license": "MIT",
   "description": "ZZ Meridian: a dashboard design system and starter. Six layers, from DTCG tokens through four layers of React components to product workspaces, and a Design Atlas, in a light and a dark theme.",

package/payload/scripts/check.ts

@@ -23,12 +23,15 @@
  *   `drift:` line, a warning the gate carries: nothing else says so between releases.
  * - Every nav item's `needs` has the shape the rail can read: 'public', a grant `object:read|create|update|remove`, or an
  *   `{ allOf: [...] }` of them.
+ * - Every nav item's `under` names an item of its own group that is not itself under another, in the same workspace, and
+ *   no item has more than seven sub pages: the rail draws three levels and nothing it cannot draw.
  */
 import { createHash } from 'node:crypto';
 import fs from 'node:fs';
 import path from 'node:path';
 import { importTarget, projectAliases } from './lib/aliases.ts';
 import { checkBrief, scanReferences } from './lib/context-check.ts';
+import { navUnderProblems } from './lib/nav-under.ts';
 import { blankedText, noDirectQuery, presentationDoesNotRead, resolveSpec as resolveProjectSpec, valueImports } from './lib/layer-rules.ts';
 import { APP_DIR, agentPageSpec, agentSection, specRoute, viewToolPages } from './lib/routes.ts';
 import { keepProblems, unresolved, parseJournal, parseKeep, parseResolutions, verifiedRetirements, type Hash, type Retirement } from './lib/update-session.ts';
@@ -360,6 +363,13 @@ for (const item of nav.flatMap((g) => g.items)) {
   if (why) problems.push(`src/app.config.ts: nav item ${item.href} ${why}`);
 }
 
+// ── A sub page names a parent the rail can draw ───────────────────────────────────────────────────────
+// A nav item may name its parent with `under`, and the rail draws it as one list nested under that parent. An `under`
+// that names nothing of its group, the item itself, an item that is already a sub page (a fourth level), or an item of
+// another workspace has no place in that list, so the page would vanish from the rail or hang in the wrong one. A parent
+// with more than seven sub pages is a group of its own. The rule is pure and lives in scripts/lib/nav-under.ts.
+problems.push(...navUnderProblems(nav));
+
 // ── The update session, the keep register and the logo ────────────────────────────────────────────────
 // A session under .meridian/update/ must be resolved before the gate passes. With one ready, its candidate manifest
 // stands in for the original: the files it will own are what keep, retirements and the dormant-code sweep read.

package/payload/scripts/lib/nav-under.ts

@@ -0,0 +1,35 @@
+/**
+ * The gate's rule for a sub page: a nav item that names its parent with `under`. The rail draws one list nested under
+ * the parent, so a navigation it cannot draw is refused here. Pure, and imports nothing from the project, so a test can
+ * feed it navigations of its own.
+ */
+type Item = { href: string; workspace?: string; under?: string };
+type Group = { label?: string; items: Item[] };
+
+const MAX_SUB_PAGES = 7;
+
+/** The `under` an item names, or undefined: a project whose `NavItem` has no such field passes. */
+const underOf = (it: Item): string | undefined => ('under' in it && typeof it.under === 'string' ? it.under : undefined);
+
+/** One line per refused item in item order, then per group the parents with too many sub pages. */
+export function navUnderProblems(groups: Group[]): string[] {
+  const out: string[] = [];
+  const at = (href: string) => `src/app.config.ts: nav item ${href}`;
+  for (const g of groups) {
+    const byHref = new Map(g.items.map((it) => [it.href, it]));
+    for (const it of g.items) {
+      const under = underOf(it);
+      if (under === undefined) continue;
+      const parent = byHref.get(under);
+      if (under === it.href) out.push(`${at(it.href)} is under itself`);
+      else if (!parent) out.push(`${at(it.href)} is under ${under}, which is no item of its group`);
+      else if (underOf(parent) !== undefined) out.push(`${at(it.href)} is under ${under}, which is itself under ${underOf(parent)}; the rail has three levels, never four`);
+      else if (it.workspace !== parent.workspace) out.push(`${at(it.href)} is in workspace ${it.workspace ?? 'none'} under ${under}, which is in workspace ${parent.workspace ?? 'none'}`);
+    }
+    for (const it of g.items) {
+      const n = g.items.filter((s) => underOf(s) === it.href).length;
+      if (n > MAX_SUB_PAGES) out.push(`${at(it.href)} has ${n} sub pages; at most ${MAX_SUB_PAGES}, past that the item is a group of its own`);
+    }
+  }
+  return out;
+}

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

@@ -67,6 +67,23 @@ timezone, currency and the signed-in user the rail shows (all but the descriptio
 palette: groups of `{ href, label, icon, needs }`, plus a `workspace` while the workspaces stay (icons from `lucide-react`, 1.75 stroke is applied by the rail). A badge
 is a short string, used only for something that needs attention ("1").
 
+**Sub pages.** An item may be a sub page of another item of the same group: give it `under`, the `href` of its parent.
+The rail draws the parent as its link plus a button named `<label> pages`, and the sub pages in a list under it; the
+branch is open on arrival when the current page is the parent or one of its sub pages. Nothing else reads a hierarchy:
+every module that reads `nav` still sees a flat list of items, each with its own `needs` and `workspace`, and a
+navigation with no `under` draws as before. `node scripts/check.ts` refuses, naming the item's `href`:
+
+- an `under` that names no item of the same group;
+- an `under` that names the item itself;
+- an `under` that names an item which itself has an `under` (three levels, never four);
+- a sub page whose `workspace` differs from its parent's, where a declared workspace and an undeclared one count as differing;
+- more than 7 sub pages under one parent (past that, the item is a group of its own).
+
+Use `under` for destinations: pages with their own address, access and place in the palette. Use in-page tabs (`Tabs`)
+instead for the views of one record, under one header. For a sub page's masthead to show its path, pass
+`<Breadcrumb items={navTrail(href, nav)} />` (from `@/components/patterns/rail/trail`) as the kicker; the crumbs are
+derived from `nav`, never written out.
+
 `needs` is required, and in a created project it is a feature's own need **by reference** — `needs: FEATURES.home.needs`,
 from `optional:src/data/features.ts` — never a grant written a second time: the rail and the palette draw only the
 destinations the signed-in person satisfies, and a test fails an item that restates a need. That filtering is

package/payload/src/app.config.ts

@@ -52,8 +52,10 @@ export type WorkspaceId = keyof typeof workspaces;
  * `prefetch` asks for the item's page to be prefetched in full, its URL data with it, where Next's default prefetches the
  * route's App Shell only. It is for a destination whose content is its URL data (a document page under a dynamic
  * segment), and every visible such link makes a request of its own, so it is for one or two items.
+ *
+ * `under` is the href of an item in the same group that this item is a sub page of.
  */
-export type NavItem = { href: string; label: string; icon: LucideIcon; badge?: string; workspace?: WorkspaceId; needs: Need; feature?: string; prefetch?: true };
+export type NavItem = { href: string; label: string; icon: LucideIcon; badge?: string; workspace?: WorkspaceId; needs: Need; feature?: string; prefetch?: true; under?: string };
 export type NavGroup = { label?: string; items: NavItem[] };
 
 export const nav: NavGroup[] = [
@@ -67,11 +69,17 @@ export const nav: NavGroup[] = [
     ],
   },
   {
+    label: 'Accounts',
     items: [
       { href: '/business', label: 'Revenue', icon: CircleDollarSign, workspace: 'business', needs: FEATURES.revenue.needs },
       { href: '/customers', label: 'Customers', icon: Users, workspace: 'business', needs: FEATURES.customers.needs },
+    ],
+  },
+  {
+    label: 'Traffic',
+    items: [
       { href: '/usage', label: 'Usage', icon: BarChart3, workspace: 'business', needs: FEATURES.usage.needs },
-      { href: '/requests', label: 'Requests', icon: Activity, workspace: 'business', needs: FEATURES.requests.needs },
+      { href: '/requests', label: 'Requests', icon: Activity, workspace: 'business', needs: FEATURES.requests.needs, under: '/usage' },
     ],
   },
   {

package/payload/src/components/base/shell/index.tsx

@@ -490,7 +490,7 @@ export function PageFrame({
         {name === undefined ? (
           <div className="flex flex-wrap items-end gap-x-8 gap-y-5">
             <div className="min-w-0 flex-1 basis-[28rem]">
-              {kicker ? <p className="t-kicker mb-4">{kicker}</p> : null}
+              {kicker ? <div className="t-kicker mb-4">{kicker}</div> : null}
               <PageTitle ref={head} title={title} />
               {description ? <p className="t-lead mt-3 max-w-[60ch]">{description}</p> : null}
             </div>
@@ -503,7 +503,7 @@ export function PageFrame({
                 state has none, so the block kept two lines while the page loaded and three once it had, and
                 everything under it dropped. Now its width follows the viewport, the rail and the assistant alone. */}
             <div>
-              {kicker ? <p className="t-kicker mb-4">{kicker}</p> : null}
+              {kicker ? <div className="t-kicker mb-4">{kicker}</div> : null}
               <PageTitle ref={head} name={name} title={title} speaksName={speaksName} />
             </div>
             {/* The description grows, so the meta and the actions end the row on its last line; with no description

package/payload/src/components/patterns/command-palette/README.md

@@ -7,7 +7,7 @@ Status: beta
 ## Anatomy
 
 1. **Query**: a 56px input with a search icon, `text-md`, and an Esc hint.
-2. **Results**: commands grouped under mono eyebrows ("Go to", "Appearance"), each a 40px row with an icon, a label, an optional hint (its group) and, on the highlighted row, an Enter glyph.
+2. **Results**: commands grouped under mono eyebrows ("Go to", "Appearance"), each a 40px row with an icon, a label, an optional hint (its group, or its parent's label for a sub page) and, on the highlighted row, an Enter glyph.
 3. **Key hints**: a `surface-sunk` band at the foot: ↑ ↓ move, ↵ open, ⌘K toggle.
 
 ## Composition
@@ -16,7 +16,7 @@ A Dialog (`surface-raised`, `radius-xl` 24px, `shadow-overlay`, 600px wide, 14%
 
 ## Data
 
-Commands are built from the `nav` prop, the same groups the Rail gets (one "Go to" per destination, its group as the hint) and the appearance actions. A match ranks by where the query starts in the label, then by the original order; the group hint also matches where a navigation names its groups ("billing" finds every entry under Billing; the sample's groups carry no name). Like the Rail's, `nav` carries each entry's icon as a component, so it cannot be built in a server component — see the Rail's README.
+Commands are built from the `nav` prop, the same groups the Rail gets (one "Go to" per destination, its group as the hint, or for a sub page its parent's label) and the appearance actions. A match ranks by where the query starts in the label, then by the original order; the hint also matches, so typing a parent's label finds its sub pages, and where a navigation names its groups ("billing" finds every entry under Billing; the sample's groups carry no name). Like the Rail's, `nav` carries each entry's icon as a component, so it cannot be built in a server component — see the Rail's README.
 
 ## States
 

package/payload/src/components/patterns/command-palette/index.tsx

@@ -9,6 +9,7 @@ import type { NavGroup } from '@/app.config';
 import { cn } from '@/lib/cn';
 import { usePreferences } from '@/components/base/providers';
 import { Kbd } from '@/components/ui/kbd';
+import { parentOf } from '@/components/patterns/rail/trail';
 
 export type Command = { id: string; group: string; label: string; hint?: string; icon: ReactNode; run: () => void };
 
@@ -55,7 +56,7 @@ export function CommandPalette({ nav }: { /** Every destination the rail offers,
       ...nav.flatMap((g) =>
         g.items.map((it) => {
           const Icon = it.icon;
-          return { id: it.href, group: 'Go to', label: it.label, hint: g.label, icon: <Icon />, run: () => leave(() => router.push(it.href)) };
+          return { id: it.href, group: 'Go to', label: it.label, hint: parentOf(g, it)?.label ?? g.label, icon: <Icon />, run: () => leave(() => router.push(it.href)) };
         }),
       ),
       { id: 'theme-light', group: 'Appearance', label: 'Use the light theme', icon: <Sun />, run: () => set({ theme: 'light' }) },

package/payload/src/components/patterns/rail/README.md

@@ -9,8 +9,9 @@ Status: beta
 1. **Brand**: the App mark at 28px, the product name (`text-md`, 600) and the workspace as an eyebrow; the whole row opens the account menu: Workspace settings, Sign out, and — where the product may be read as someone else — the View as group. A product with several workspaces or scopes (one team, the whole platform) passes them as `scopes` (`{ id, label, active, onSelect, href }`, `href` where choosing it goes); the menu then lists them as radio items under "Show", the row's glyph is the switcher's `ChevronsUpDown`, and `workspace` sets the eyebrow to the one in view. With one scope or none there is nothing to switch between, so there is no `Show` group and no checked row of its own: the row is the account menu, its glyph is a plain `ChevronDown`, and its label says so.
 2. **Groups**: an optional mono eyebrow (`t-eyebrow`, `ink-3`) over a list of items; groups sit `space-6` 24px apart.
 3. **Item**: a 16px icon at a 1.75 stroke, the label, and an optional count badge.
-4. **Marker**: one pill behind the current item, `accent-tint` with an inset `accent-line` ring and a 2px `accent` edge on the left that carries a soft glow.
-5. **Account**: the person's avatar, name and role, and the Appearance menu, in a hairline card at the foot.
+4. **Branch**: an item that other items name with `under` is a parent. Its row holds two controls: the item's link, to the parent's own page, and a button at the row's right end named `<label> pages`, whose one `ChevronRight` turns a quarter to point down while the branch is open. Its sub pages are a nested list under the row, on a 1px `line` guide line hung under the parent's icon; a sub page has no icon and its label lines up with the parent's label. A navigation has three levels at most: group, item, sub page.
+5. **Marker**: one pill behind the current item, `accent-tint` with an inset `accent-line` ring and a 2px `accent` edge on the left that carries a soft glow.
+6. **Account**: the person's avatar, name and role, and the Appearance menu, in a hairline card at the foot.
 
 ## Composition
 
@@ -37,6 +38,11 @@ App mark, Avatar and Appearance menu, on `frame` (a translucent wash with `backd
 | Hover | `fill-hover` behind, label `ink` | `ink-2` |
 | Current | the marker behind, label `ink` 500 | `accent-ink` |
 | Focus (keyboard) | 2px `accent` outline | as rest |
+| Branch open, a sub page current | the sub page takes the marker, and the guide line beside it lights in `accent`; the parent's label is `ink` and its icon `accent-ink`, with no pill | |
+| Branch closed, a sub page current | the parent's link takes the marker, with `aria-current="true"` | `accent-ink` |
+| Parent's own page current | the parent's link takes the marker, whether the branch is open or closed | `accent-ink` |
+| Sub pages the person may not open | the parent is a plain item, with no button | |
+| Parent the person may not open | the sub page is a plain item in the group, with its own icon | |
 
 The preview's specimens are the real Rail, so rest and current are drawn in them, and hover and focus are seen by using them: point at an item, or tab to it.
 
@@ -48,13 +54,19 @@ Colours change over `dur-hover` 160ms. The marker moves (`transform`, `height`)
 - While a destination's page is on the way (a page that renders on request and is not prefetched), its icon turns into a 14px Spinner in the same 16px slot (`useLinkStatus`), named "Opening Members", so the click is answered at once and nothing shifts. A prefetched page is never pending, so it never shows.
 - An item is current when the path equals its route or sits beneath it (`/requests/req_…` keeps Requests current); Home (`/`) only matches itself. The current page is the longest such route among every destination the product declares (`declared`, which `ConsoleRail` passes from the whole navigation), and it is lit only when this person's rail holds it: an address under a destination they may not open (`/admin/audit` for someone who holds `/admin` only) lights nothing, never the shorter one above it.
 - Navigation from the account menu (Workspace settings and Sign out) asks first while a form on the page has unsaved changes, through the shell's `useLeave`; a link is held by the shell itself. Outside a shell it goes at once. Opening the menu prefetches each other scope's `href`: a row is a press, so nothing fetches its page before, and a phone's closed drawer prefetches nothing. A workspace chosen from the switcher runs the `onSelect` the product passed, so the product's own handler asks (the sample's does, in `src/views/workspace-chrome.tsx`); choosing a person under View as is not a navigation and is not held.
+- A parent's button opens and closes its branch: Enter or Space, or a click. A closed branch mounts none of its links, so nothing in it is prefetched, tabbed to or read by a suite. The marker is measured again whenever a branch opens or closes.
+- The button's chevron is one icon that turns a quarter by the hover duration (right when closed, down when open) rather than swapping, and reduced motion stills it through the system-wide reset. Focus stays on the button after a toggle, because a toggle never remounts it.
+- Beside a current sub page the marker draws no lit edge of its own: the guide line's lit stretch is the only accent line there. Over a second-level item, including the parent of a closed branch, the marker keeps its lit edge.
+- A branch is open on arrival when the current page is its parent's page or one of its sub pages, and closed otherwise. Every navigation that lands on a parent or one of its sub pages opens that branch again, even one the person closed. Otherwise a person's open or close stands for as long as the rail stays mounted, which spans every navigation inside the console: a branch they opened stays open elsewhere, and one they closed from inside stays closed until a navigation lands inside it. The state is not stored, so a reload starts from the arrival rule. The phone drawer mounts its rail each time it opens, so it applies the arrival rule afresh.
+- Only one element in the rail carries `aria-current` at a time: `page` on the current link, or `true` on the parent of a closed branch that holds the current page.
+- `nav` is what this person may open. A sub page whose parent is not in `nav` is drawn as a plain item in its group, with its icon; a parent with none of its sub pages in `nav` is a plain item. `declared` still lists every href, so an address under a destination the person may not open lights nothing.
 - `current` overrides the pathname (previews and tests); products leave it unset.
 - View as: the personas are radio items, so the arrows move through them and Enter switches. The one in view carries the check; a persona who is not Active is listed but disabled. A `choose` that rejects shows its message in a critical toast and changes nothing — the check stays on the person who is still signed in.
 
 ## Surfaces
 
 - **Console**: fixed at the left edge, its own scroll when the list outgrows the window.
-- **Mobile**: under 1024px the same node opens as a drawer from the top bar's menu button: 260px (at most 86% of the screen), over a blurred scrim; it closes on Escape, on the scrim and on navigation, and returns focus to the trigger.
+- **Mobile**: under 1024px the same node opens as a drawer from the top bar's menu button: 260px (at most 86% of the screen), over a blurred scrim; it closes on Escape, on the scrim and on navigation, and returns focus to the trigger. On a touch screen (`pointer: coarse`) every parent, sub page and button row is 44px tall and the button's target is 44 by 44; on a fine pointer a sub page row is 32px and the button 28px.
 - **Embed**: absent. A view in a host has one job and no navigation; it links out with Open in ZZ Meridian.
 
 ## Agents
@@ -64,6 +76,7 @@ Not applicable: navigation is how a person moves. An agent opens a view by its a
 ## Accessibility
 
 - `nav` with the name "Main"; the current item carries `aria-current="page"`.
+- A parent's button has the accessible name `<label> pages` ("Usage pages"), `aria-expanded` set to `true` or `false`, and `aria-controls` naming the branch's list. It is a separate control from the parent's link, so the parent's page stays reachable from the rail. The parent of a closed branch that holds the current page carries `aria-current="true"`.
 - Contrast (dark, indigo): inactive label `ink-2` on the rail 8.7:1, group label `ink-3` 7.0:1, current label on the marker 9.2:1; light 6.6, 4.9 and 5.7:1.
 - The count badge repeats a number the page states in words; it is never the only signal.
 
@@ -75,7 +88,8 @@ Not applicable: navigation is how a person moves. An agent opens a view by its a
 
 ## Do and do not
 
-- Do keep the rail to about ten items; a product with more needs a second level on its pages (Tabs), not a longer rail.
+- Do keep the rail to about ten items; a product with more needs sub pages under an item (`under`), or a second level on its pages (Tabs), not a longer rail.
+- Do use `under` for sub pages that are destinations of their own, each with its own page and access. Use Tabs in the page for the views of one record, under one header.
 - Do not put actions in the rail; it holds places only.
 - Do not use the count badge for anything but something that needs attention now.
 
@@ -94,4 +108,15 @@ import { Rail } from '@/components/patterns/rail';
 <AppShell rail={<Rail />} tools={<ShellTools />} assistant={assistant}>{children}</AppShell>
 ```
 
-Edit `nav` in `src/app.config.ts` to change the destinations: `{ label?, items: [{ href, label, icon, badge?, prefetch? }] }`; set `prefetch: true` on an item whose page is its URL data (a document under a dynamic segment), for one or two items at most.
+Edit `nav` in `src/app.config.ts` to change the destinations: `{ label?, items: [{ href, label, icon, badge?, prefetch?, under? }] }`; set `prefetch: true` on an item whose page is its URL data (a document under a dynamic segment), for one or two items at most.
+
+`under` makes an item a sub page: it is the `href` of an item of the same group, and the rail draws the item in that item's branch.
+
+```ts
+{ label: 'Traffic', items: [
+  { href: '/usage', label: 'Usage', icon: BarChart3, needs: FEATURES.usage.needs },
+  { href: '/requests', label: 'Requests', icon: Activity, needs: FEATURES.requests.needs, under: '/usage' },
+] }
+```
+
+`node scripts/check.ts` refuses a navigation it cannot draw, naming the item's `href`: an `under` that names no item of the same group, an `under` that names the item itself, an `under` that names an item that is itself under another (three levels, never four), a sub page whose `workspace` differs from its parent's (a declared workspace and an undeclared one differ), and more than 7 sub pages under one parent.