@struq/skill 0.2.2 → 0.4.0

package/skills/struq/references/stack-targets.md

@@ -1,78 +1,27 @@
-# Stack Targets: detect Vite vs Next.js, then adapt
+# Vite and other React stacks
 
-Every other reference file is written for **Next.js App Router** (Struq's default
-stack). Most of the doctrine is framework-agnostic, but a handful of primitives are
-Next-specific and will break or mislead in a Vite project. **Detect the stack before
-writing any wiring code**, then translate the Next-only pieces.
+The blocks are written for Next.js App Router. Only four things tie them to it; everything else (GSAP, Lenis, the
+kit, the CSS, the tokens) is plain React and Tailwind v4. Detect the stack first: `next` in package.json and an `app/`
+folder is Next; `vite.config.*` with `src/main.tsx` is Vite.
 
----
+`blocks.mjs` refuses a project without `next`: copy the files by hand instead, keeping the layout of `blocks/` under
+`src/components/struq/` so the relative imports hold (each block's files are listed in `blocks/catalog.json`).
 
-## 1. Detect first
-
-| Signal | Stack |
+| Next.js | Vite |
 |---|---|
-| `next.config.{js,ts,mjs}` present, or an `app/` directory with `layout.tsx` | **Next.js App Router**: use the reference files as written |
-| `next.config` present but `pages/` not `app/` | **Next Pages Router**: providers wrap in `_app.tsx`; `template.tsx` patterns use route events instead |
-| `vite.config.{js,ts}` present | **Vite**: translate per §2 (React assumed; Vue/Svelte share the concepts, different syntax) |
-| neither (CRA, Astro island, Webflow, plain Vite-less) | framework-agnostic core only: Lenis/GSAP provider + CSS; skip Next primitives |
-
-Check `package.json` deps to confirm: `next` vs `vite` + `react-dom`. If a router is
-present in Vite, it is almost always `react-router-dom`, and that is what the transition
-patterns below assume.
-
-Then read the installed majors (`vite`, `react`, `tailwindcss`, `gsap`, `lenis`, the router) and record them on the `Stack:` line; the installed version beats this file whenever they disagree ([setup.md](setup.md) §0, Known API shifts). Scaffold an empty folder with `npm create vite@latest`.
-
----
-
-## 2. Translation table: Next App Router → Vite
-
-| Concern | Next App Router | Vite (React SPA) |
-|---|---|---|
-| **Fonts** | `next/font/google` / `next/font/local` exposing CSS vars | `@fontsource/<face>` (npm) **or** self-hosted `@font-face` in CSS; `<link rel="preload">` the woff2 in `index.html`. Map the same `--font-display-face` / `--font-body-face` vars. (Pairing and weight decisions: [typography.md](typography.md).) |
-| **Lazy / SSR-free island** (WebGL) | `next/dynamic(() => import("./X"), { ssr: false })` | `React.lazy(() => import("./X"))` + `<Suspense fallback={poster}>`. A Vite SPA is already client-only, so there is no SSR tree to exclude; the lazy boundary is purely for bundle-splitting. |
-| **Client/server boundary** | `"use client"` directive on leaf components | **Drop it.** It is a no-op in Vite; everything is a client component. Remove the directive when porting snippets. |
-| **Providers mount point** | `app/layout.tsx` wrapping `{children}` | `src/main.tsx` (or `App.tsx`) wrapping `<App/>`: `<SmoothScrollProvider>`, etc. Same component, different host file. |
-| **Per-navigation remount** (page-transition entrance) | `app/template.tsx` (re-mounts each navigation) | a wrapper keyed on `useLocation().pathname`, e.g. `<motion.div key={pathname}>` or an `<AnimatePresence mode="wait">` around the routed outlet. Same effect: fresh mount per route. |
-| **Route-change transitions** | `template.tsx` + `PageTransitionProvider` ([route-transitions.md](route-transitions.md)) | `AnimatePresence` driven by the router location; the curtain/overlay logic is identical, only the trigger source changes. |
-| **Images** | `next/image` (auto sizing, lazy, AVIF/WebP) | `<img>` with **explicit `width`/`height`** (or aspect-ratio box) + `loading="lazy"` + `decoding="async"`; for responsive sources use `srcset` or `vite-imagetools`. Keep explicit dims for CLS regardless. |
-| **Metadata / head** | `metadata` export / `generateMetadata` | `react-helmet-async` or set tags in `index.html`. |
-| **Icons** | `@struq/icons` (the default; Phosphor light the fallback) | The same React package and root CSS imports in `src/main.tsx`; non-React or Iconify-based stacks use its `iconify.json` (prefix `struq`) or `sprite.svg` ([iconography.md](iconography.md) §2). |
-| **Env / public assets** | `/public`, `process.env.NEXT_PUBLIC_*` | `/public`, `import.meta.env.VITE_*`. |
-
----
-
-## 3. What is identical on both (do NOT re-derive)
-
-These carry over unchanged. Only the *mount file* differs:
-
-- **The smooth-scroll provider**: Lenis driven by `gsap.ticker` with `autoRaf: false` +
-  `lagSmoothing(0)` ([setup.md](setup.md) §2). One RAF clock. Identical code; mount it in
-  `app/layout.tsx` (Next) or `main.tsx` (Vite).
-- **The GSAP registry module** (`lib/gsap.ts`), `gsap.defaults`, and **all `useGSAP`
-  rules**: scope ref, `contextSafe`, `autoAlpha`, animate `from` so the SSR/initial HTML
-  is the final state ([setup.md](setup.md) §1, §3). The same registry covers the plugins used by [svg-motion.md](svg-motion.md) (DrawSVG, MorphSVG).
-- **`gsap.matchMedia` reduced-motion guard** ([setup.md](setup.md) §4).
-- **The WebGL island's `frameloop:"never"` + GSAP-ticker bridge** ([webgl-r3f.md](webgl-r3f.md) §2,
-  scene recipes in [webgl-scenes.md](webgl-scenes.md)). R3F is router-agnostic; the single-clock
-  wiring is the same. Only the lazy-boundary primitive changes (`next/dynamic` → `React.lazy`, per §2).
-- **The scaling knob**: one CSS rule in the global stylesheet ([scaling.md](scaling.md)),
-  `app/globals.css` vs `src/index.css`.
-- **All Iconify usage**, the token/`@theme` system, every ScrollTrigger/scrub/pin
-  technique (including every recipe in [showcase.md](showcase.md)), and all motion *values* ([feel-layer.md](feel-layer.md)).
-
-The rule of thumb: **anything that touches the DOM, the GSAP ticker, or CSS is portable;
-anything that says `next/...` or `"use client"` needs the §2 translation.**
-
----
-
-## 4. Vite gotchas worth flagging
-
-- **No SSR safety net by default.** Code that reads `window` at module scope is fine in a
-  Vite SPA (no server render), but keep it in effects anyway for correctness and so the
-  component stays portable back to Next.
-- **`ScrollTrigger.refresh()`** is still needed after route changes and after fonts/images
-  settle. Wire it to the router's location change (the App Router note in
-  [setup.md](setup.md) §6 applies, just via `react-router` instead of `template.tsx`).
-- **StrictMode double-invoke** in dev re-runs effects twice. `useGSAP` cleanup handles
-  it, but raw `useEffect` GSAP setup will leak, which is another reason never to write raw
-  `useEffect` for GSAP ([setup.md](setup.md) §3).
+| `next/image` (`<Image fill sizes priority>`) | `<img>` with `width`, `height`, `loading`, `decoding="async"`, and `object-cover` on a positioned box for `fill`. `getImageProps` (page-transition-stack) becomes the plain `src`. |
+| `next/link` | `<a>`, or your router's `Link`. |
+| `next/navigation` in the page transitions (`usePathname`, `useRouter`, `useSearchParams`) | Your router's location and navigate (React Router `useLocation`, `useNavigate`). The transitions only need the current path and a push. |
+| `"use client"` | Delete it, or leave it: Vite ignores it. |
+
+The shell, in Vite terms:
+
+- `index.html`: in `<head>`, the gate script `<script>document.documentElement.classList.add('sq-js')</script>` before
+  any stylesheet, and one `<link rel="stylesheet">` per URL that `canon.mjs print <palette> <pairing>` prints;
+  `<body data-blocks>`.
+- `src/index.css`: `@import "tailwindcss";`, the kit import, the `@theme inline` names and the STRUQ TOKENS block from
+  `recipes/app/globals.css` (the block comes from `canon.mjs print`).
+- `src/main.tsx`: wrap the app in `SmoothScroll` from the kit.
+
+`check.mjs` reads `app/layout.tsx` for the gate; on Vite it reports that line as missing. Check `index.html` by eye
+and note it under Verify in STRUQ.md.

package/skills/struq/references/tells.md

@@ -0,0 +1,52 @@
+# The tell list
+
+One list: Struq's tells, the slop audit and Roy's rules. Each is something a generator does by reflex and a studio
+never does. `check.mjs` detects the marked ones (and `struq_controle` returns the same rules when the MCP is
+connected); the rest are judged by eye. The fix is beside each.
+
+## Type and labels
+
+- **Eyebrows:** a small label above a heading ("OUR APPROACH", "PREMIUM SERVICE"), any uppercase tracked label or
+  marquee. Fix: the heading carries itself; wayfinding is a hairline, a change of surface step, a jump in scale. A
+  caption under or on an image (`<figcaption>` or `data-caption`) is media metadata and allowed. (check)
+- **Numbered steps** (01 / 02 / 03) and section numbers. Fix: hairline rows or a sequence the layout makes obvious. (check)
+- **Mono on marketing:** monospace as a design face. Fix: mono only for literal code. (check)
+- **The generator faces:** Inter, Roboto, Arial, Helvetica, Open Sans, Poppins, Montserrat, Lato, Geist, Space
+  Grotesk, and Playfair, Anton, Oswald, Cormorant or Manrope as a display. Fix: a canon pairing. (check)
+- **Heavy display** outside the poster pairings, `font-bold` on headings, raw sizes (`text-5xl`) and breakpoint size
+  ladders. Fix: the type roles and `--display-weight`. (check)
+
+## Colour and surface
+
+- **Gradients of any kind,** gradient text, glass, tinted translucent fills. Fix: flat tokens; a flat veil over a
+  photo is the only translucent layer. (check)
+- **Glow:** coloured shadows, neon edges, blurred light behind a card. Fix: none. (check)
+- **Default purple or blue:** an indigo or violet accent nobody chose. Fix: a canon palette; blue only when the brand
+  is blue, declared in STRUQ.md as `Cool hue: declared because <the brand colour>`. (check)
+- **Pills,** above all a pill with a dot; pulsing live dots; pastel status badges. Fix: a text link or a rectangular
+  button. (check)
+- **Drop-shadow elevation** and side-stripe borders. Fix: a surface step and a hairline.
+
+## Layout and motion
+
+- **Icon grids:** three or six identical cards, each an icon, a heading and two grey lines. Fix: hairline rows,
+  `hover-list`, `panel-accordion`, or one statement. (check)
+- **Stat banners** ("20+", "99%", "51+") the brief did not give. Fix: leave them out. (check)
+- Uniform section padding, the same hover on everything, opacity-only entrances, single-layer parallax. Fix: the
+  craft rules in [craft.md](craft.md).
+- An empty or placeholder frame, a grey box, "photo to come". Fix: a beeldbank photo. (check)
+
+## Copy and icons
+
+- **Em and en dashes** in any form, in copy, comments and alt text. Fix: restructure the sentence: a comma, a colon, a
+  full stop. (check)
+- Generic CTAs ("Learn more", "Get started", "Lees meer"), generic headings ("Our Services", "Over ons"), hype words
+  ("seamless", "naadloos", "next-level"), lorem, Acme, leftover template text. Fix: specific words from the brief. (check)
+- Emoji and the cliche icons (sparkles, rocket, lightning, bulb, wand). Fix: Struq Icons, functional only. (check)
+- Invented facts: testimonials, client logos, stats, awards, prices, addresses, hours, bios, quotes the brief did not
+  give. Fix: leave them out and list them under Assumptions.
+
+## Judged by eye
+
+The hero-metric template (big number, small label, three times), category-reflex colours (green for eco, blue for
+finance), a heading the paragraph restates, a page that reads as a SaaS template in a studio's palette.

package/skills/struq/references/triage.md

@@ -37,25 +37,25 @@ change its dress.
 ## Fair game: fix freely (this is what you were called for)
 
 - **Layout / structure / IA**: restructure sections, reorder, break the grid, fix the
-  symmetric "SaaS stack." Layout is execution, not identity. ([page-architecture.md](page-architecture.md))
+  symmetric "SaaS stack." Layout is execution, not identity: swap in blocks where the page is weakest (the hero, the work, the footer first).
 - **Spacing rhythm**: kill uniform `py-16`, vary padding by section role.
 - **Type scale + weight**: fix the five-mid-sizes problem, lighten hero weights, enforce
-  the readable floor and contrast minimums ([anti-patterns.md](anti-patterns.md) §12). If the
+  the readable floor and contrast minimums. If the
   brand already owns its typefaces, keep them and change how they are set, not which they are
-  ([typography.md](typography.md)).
+  (their faces go into --face-display and --face-body).
 - **Surfaces / elevation**: replace `shadow-lg` cards with the tonal ladder.
 - **Motion / reveals**: replace opacity-only fades, add transform+stagger, fix easing.
 - **Scaling**: convert px-everything + per-breakpoint size ladders to the fluid root-rem
-  system ([scaling.md](scaling.md)).
+  system ([craft.md](craft.md)).
 - **Icon misuse**: remove Sparkles/Rocket/Zap/emoji, colored chips, decorative filler;
   consolidate to one icon family ([iconography.md](iconography.md)): the brand's own set if it has one, else Struq Icons (`@struq/icons`). A redesign that already uses one coherent non-Lucide family keeps it (preserve by default); one family per site, never mixed.
-- **Everything in [anti-patterns.md](anti-patterns.md)**: that gallery is the fix list.
+- **Everything in [tells.md](tells.md)**: that list is the fix list.
 
 ---
 
 ## Workflow
 
-1. **Scan** with [anti-patterns.md](anti-patterns.md) and collect every tell.
+1. **Scan** with check.mjs (and struq_controle when connected) and [tells.md](tells.md); collect every tell.
 2. **Filter** the findings through the preserve-list above. A "fix" that reassigns brand
    color, rewrites copy, or replaces a component primitive is dropped (or downgraded to a
    *suggestion* the user can opt into), not applied.
@@ -68,4 +68,3 @@ change its dress.
 When unsure whether something is identity or execution, **ask** rather than assume, but
 default to preserving the three categories above.
 
-If the work started from a brief, [brief-router.md](brief-router.md) still runs, with this file's rules overriding it: identity is preserved and the router only re-decides execution.

package/skills/struq/scripts/blocks.mjs

@@ -0,0 +1,156 @@
+#!/usr/bin/env node
+// Struq blocks, offline: the skill's own copy of Struq's admitted blocks (blocks/, catalog.json), installed into a
+// Next.js App Router project. The same files the MCP's struq_blok returns.
+//
+//   node <skill-dir>/scripts/blocks.mjs list [kind]          the catalogue, one line per block with its variants
+//   node <skill-dir>/scripts/blocks.mjs init                 the kit, the app shell (on a starter) and the base packages
+//   node <skill-dir>/scripts/blocks.mjs add <slug> [<slug>]  a block and every file it imports, plus its packages
+//   flags: --dir <project>, --force (replace files you already have), --no-install
+//
+// Everything lands under components/struq/ in the layout of Struq's blocks/ (kit/, heroes/, sections/ ...), so the
+// relative imports between them hold. A layout or stylesheet you wrote yourself is never overwritten.
+import { spawnSync } from "node:child_process";
+import { copyFileSync, existsSync, mkdirSync, readdirSync, readFileSync, rmSync, statSync } from "node:fs";
+import { dirname, join, relative, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+import { appendLog } from "./log.mjs";
+
+const here = dirname(fileURLToPath(import.meta.url));
+const BLOCKS = join(here, "..", "blocks");
+const RECIPES = join(here, "..", "recipes");
+const CATALOG = JSON.parse(readFileSync(join(BLOCKS, "catalog.json"), "utf8")).blocks;
+
+const args = process.argv.slice(2);
+const dirAt = args.indexOf("--dir");
+const root = resolve(dirAt >= 0 ? args[dirAt + 1] : process.cwd());
+const force = args.includes("--force");
+const install = !args.includes("--no-install");
+const [cmd, ...rest] = args.filter((x, i) => !x.startsWith("--") && (dirAt < 0 || i !== dirAt + 1));
+
+const src = existsSync(join(root, "src", "app")) ? "src" : "";
+const target = (...p) => join(root, src, "components", "struq", ...p);
+const copied = [];
+const kept = [];
+const notes = [];
+
+function place(from, to, overwrite = force) {
+  if (existsSync(to) && !overwrite) return kept.push(relative(root, to));
+  mkdirSync(dirname(to), { recursive: true });
+  copyFileSync(from, to);
+  copied.push(relative(root, to).split("\\").join("/"));
+}
+
+function walk(dir) {
+  return readdirSync(dir).flatMap((n) => (statSync(join(dir, n)).isDirectory() ? walk(join(dir, n)) : [join(dir, n)]));
+}
+
+function project() {
+  const pkgPath = join(root, "package.json");
+  if (!existsSync(pkgPath)) {
+    console.error(`FAIL no package.json in ${root}. Scaffold first: npx create-next-app@latest . --ts --tailwind --app --eslint --yes`);
+    process.exit(2);
+  }
+  const pkg = JSON.parse(readFileSync(pkgPath, "utf8"));
+  const deps = { ...pkg.dependencies, ...pkg.devDependencies };
+  if (!deps.next) {
+    console.error("FAIL not a Next.js project. The blocks use next/image and next/link; for Vite read references/stack-targets.md.");
+    process.exit(2);
+  }
+  return deps;
+}
+
+function installMissing(deps, wanted) {
+  const need = [...wanted].filter((d) => !deps[d]);
+  const dev = need.filter((d) => d.startsWith("@types/"));
+  const runtime = need.filter((d) => !d.startsWith("@types/"));
+  for (const [list, flag] of [[runtime, ""], [dev, "-D "]]) {
+    if (!list.length) continue;
+    const line = `npm install ${flag}${list.join(" ")}`;
+    if (!install) {
+      notes.push(`Run: ${line}`);
+      continue;
+    }
+    console.log(`> ${line}`);
+    if (spawnSync(line, { cwd: root, stdio: "inherit", shell: true }).status !== 0) notes.push(`The install failed. Run it yourself: ${line}`);
+  }
+}
+
+function report(step, what) {
+  console.log(`\nCopied ${copied.length} file(s)${copied.length ? ":" : "."}`);
+  for (const f of copied) console.log(`  ${f}`);
+  if (kept.length) console.log(`Kept ${kept.length} existing file(s) (--force replaces them).`);
+  for (const n of notes) console.log(`NOTE ${n}`);
+  appendLog(root, step, [what, ...(notes.length ? [`Notes: ${notes.join(" ")}`] : [])]);
+}
+
+const commands = {
+  list() {
+    const kind = rest[0];
+    const rows = CATALOG.filter((b) => !kind || b.kind === kind);
+    if (!rows.length) throw new Error(`No blocks of kind "${kind}". Kinds: ${[...new Set(CATALOG.map((b) => b.kind))].join(", ")}`);
+    for (const b of rows) {
+      console.log(`${b.kind.padEnd(16)} ${b.slug.padEnd(24)} ${b.title}${b.variants.length ? `  [${b.variants.map((v) => v.id).join(", ")}]` : ""}`);
+    }
+    console.log(`\n${rows.length} block(s). What each does and its variants: blocks/CATALOG.md.`);
+  },
+
+  init() {
+    const deps = project();
+    // The kit, minus the WebGL hero layer: HeroCanvas and its scenes need three, so they come with hero-opener.
+    for (const f of walk(join(BLOCKS, "kit"))) {
+      const r = relative(join(BLOCKS, "kit"), f).split("\\").join("/");
+      if (r === "HeroCanvas.tsx" || r.startsWith("scenes/")) continue;
+      place(f, target("kit", r));
+    }
+    const appDir = join(root, src, "app");
+    const read = (p) => (existsSync(p) ? readFileSync(p, "utf8") : "");
+    const layout = read(join(appDir, "layout.tsx"));
+    if (!layout || /Create Next App|Geist/.test(layout) || force) place(join(RECIPES, "app", "layout.tsx"), join(appDir, "layout.tsx"), true);
+    else if (!/data-blocks/.test(layout)) {
+      notes.push("app/layout.tsx is your own: add the sq-js script, the font links, data-blocks on <body> and <SmoothScroll> (recipes/app/layout.tsx).");
+    }
+    const css = read(join(appDir, "globals.css"));
+    if (!css || (!css.includes("STRUQ TOKENS") && /--background|--foreground|Arial|prefers-color-scheme/.test(css)) || force) {
+      place(join(RECIPES, "app", "globals.css"), join(appDir, "globals.css"), true);
+    } else if (!css.includes("STRUQ TOKENS")) notes.push("app/globals.css is your own: add the kit import and the STRUQ TOKENS block from recipes/app/globals.css.");
+    place(join(RECIPES, "app", "fonts.ts"), join(appDir, "fonts.ts"));
+    for (const starter of ["next.svg", "vercel.svg", "file.svg", "globe.svg", "window.svg"]) rmSync(join(root, "public", starter), { force: true });
+    installMissing(deps, ["gsap", "@gsap/react", "lenis"]);
+    report("Step 1 Project", `blocks.mjs init copied the kit and ${copied.length} file(s) in all, kept ${kept.length}.`);
+    console.log("OK init ready");
+  },
+
+  add() {
+    if (!rest.length) throw new Error("Usage: blocks.mjs add <slug> [<slug> ...]. The slugs: blocks.mjs list");
+    const deps = project();
+    const wanted = new Set();
+    const added = [];
+    for (const slug of rest) {
+      const b = CATALOG.find((x) => x.slug === slug);
+      if (!b) throw new Error(`Unknown block "${slug}". Run: blocks.mjs list`);
+      for (const f of b.files) place(join(BLOCKS, f), target(f));
+      for (const p of b.packages) wanted.add(p);
+      added.push(b);
+    }
+    installMissing(deps, wanted);
+    for (const b of added) {
+      const from = `@/components/struq/${b.file.replace(/\.tsx?$/, "")}`;
+      console.log(`\n${b.slug}: import { ${b.exports.join(", ")} } from "${from}";`);
+      if (b.variants.length) console.log(`  variant: ${b.variants.map((v) => `"${v.id}"`).join(" | ")} (default "${b.variants[0].id}")`);
+    }
+    report("Step 5 Blocks", `blocks.mjs added ${added.map((b) => b.slug).join(", ")}.`);
+    console.log("OK blocks added");
+  },
+};
+
+const run = commands[cmd];
+if (!run) {
+  console.error("Usage: blocks.mjs list [kind] | init | add <slug> [<slug> ...]   [--dir <project>] [--force] [--no-install]");
+  process.exit(2);
+}
+try {
+  run();
+} catch (e) {
+  console.error(`FAIL ${e.message}`);
+  process.exitCode = 1;
+}

package/skills/struq/scripts/canon.mjs

@@ -0,0 +1,134 @@
+#!/usr/bin/env node
+// Struq canon, offline: Struq's palettes and type pairings, written into the project as the one token block the
+// blocks read. The same block, derivation and font requests as Struq's block lab and the MCP's struq_richting
+// (scripts/tokens.mjs), from the snapshot in canon/canon.json that the skill's release copies from Struq.
+//
+//   node <skill-dir>/scripts/canon.mjs list                       every palette and pairing
+//   node <skill-dir>/scripts/canon.mjs palette <id>               writes the STRUQ TOKENS block in app/globals.css
+//   node <skill-dir>/scripts/canon.mjs type <id>                  the same block with the pairing, and app/fonts.ts
+//   node <skill-dir>/scripts/canon.mjs print <palette> <pairing>  prints the block and the font URLs, writes nothing
+//   add --dir <project> to run from elsewhere
+//
+// Node 18 or later, no network, no dependencies.
+import { existsSync, readFileSync, writeFileSync } from "node:fs";
+import { dirname, join, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+import { appendLog } from "./log.mjs";
+import { fontHrefs, headFamily, lightness, paletteTokens } from "./tokens.mjs";
+
+const here = dirname(fileURLToPath(import.meta.url));
+const CANON = JSON.parse(readFileSync(join(here, "..", "canon", "canon.json"), "utf8"));
+const args = process.argv.slice(2);
+const dirAt = args.indexOf("--dir");
+const root = resolve(dirAt >= 0 ? args[dirAt + 1] : process.cwd());
+const [cmd, a, b] = args.filter((_, i) => dirAt < 0 || (i !== dirAt && i !== dirAt + 1));
+
+const palette = (id) => {
+  const p = CANON.palettes.find((x) => x.id === id);
+  if (!p) throw new Error(`Unknown palette "${id}". Run: canon.mjs list`);
+  return p;
+};
+const pairing = (id) => {
+  const t = CANON.pairings.find((x) => x.id === id);
+  if (!t) throw new Error(`Unknown pairing "${id}". Run: canon.mjs list`);
+  return t;
+};
+const faces = (t) => [t.display, t.body, t.accentItalic].filter(Boolean).map(headFamily);
+
+export function tokenBlock(p, t) {
+  const lines = paletteTokens(p, t).map(([k, v]) => `  ${k}: ${v};`);
+  return `/* STRUQ TOKENS: palette ${p.id}, type ${t.id}. Written by canon.mjs, the block Struq's lab and struq_richting give. */\n[data-blocks] {\n${lines.join("\n")}\n}`;
+}
+
+const BLOCK = /\/\* STRUQ TOKENS[^*]*\*\/\s*\[data-blocks\]\s*\{[\s\S]*?\n\}/;
+
+function cssFile() {
+  const path = ["app/globals.css", "src/app/globals.css"].map((f) => join(root, f)).find(existsSync);
+  if (!path) throw new Error("No app/globals.css. Run blocks.mjs init first.");
+  return path;
+}
+
+function write(p, t) {
+  const path = cssFile();
+  const css = readFileSync(path, "utf8");
+  if (!BLOCK.test(css)) throw new Error(`No STRUQ TOKENS block in ${path}. Run blocks.mjs init, or copy the block from recipes/app/globals.css.`);
+  writeFileSync(path, css.replace(BLOCK, tokenBlock(p, t)));
+  return path;
+}
+
+function current() {
+  const css = readFileSync(cssFile(), "utf8");
+  const m = css.match(/STRUQ TOKENS: palette (\S+), type (\S+?)\./);
+  return { palette: m?.[1] ?? CANON.palettes[0].id, type: m?.[2] ?? CANON.pairings[0].id };
+}
+
+function writeFonts(t) {
+  const hrefs = fontHrefs(t, CANON);
+  const file = join(root, existsSync(join(root, "src", "app")) ? "src/app" : "app", "fonts.ts");
+  writeFileSync(
+    file,
+    `// app/fonts.ts: written by the Struq skill (canon.mjs type ${t.id}): ${faces(t).join(", ")}.
+// Each Google face is asked for its real weight range, then as the bare family as a fallback, because Google refuses a
+// request for a weight the family lacks. The layout puts one <link> per URL in <head>; the token block in globals.css
+// names the faces (--face-display, --face-body, --face-accent), so the blocks measure with the real face.
+export const fontHrefs: string[] = ${JSON.stringify(hrefs, null, 2)};
+`,
+  );
+  return { file, hrefs };
+}
+
+const commands = {
+  list() {
+    console.log(`PALETTES (${CANON.palettes.length}): id, mood, ground. "kept out" means kept for a brand that asks, never picked unasked.`);
+    for (const p of CANON.palettes) {
+      const ground = lightness(p.colors.background) < 0.5 ? "dark" : "light";
+      console.log(`  ${p.id.padEnd(40)} ${(p.mood ?? "").padEnd(44)} ${ground}${p.autoPick === false ? "  kept out" : ""}`);
+    }
+    console.log(`\nPAIRINGS (${CANON.pairings.length}): id, display + body (+ italic accent), display weight`);
+    for (const t of CANON.pairings) {
+      const [d, bo, ac] = [t.display, t.body, t.accentItalic].map((s) => (s ? headFamily(s) : null));
+      console.log(`  ${t.id.padEnd(26)} ${d} + ${bo}${ac ? ` (+ ${ac} italic)` : ""}, ${t.displayScale?.weight ?? 300}${t.autoPick === false ? "  kept out" : ""}`);
+    }
+    console.log(`\nSnapshot: Struq ${CANON.source.ref} ${CANON.source.commit}.`);
+  },
+  palette() {
+    const p = palette(a);
+    const t = pairing(current().type);
+    const path = write(p, t);
+    console.log(`Wrote palette ${p.id} (${p.mood}) to ${path.replace(root, ".")}, with type ${t.id}.`);
+    console.log(`STRUQ.md line:  Palette: ${p.id} (${p.mood})`);
+    appendLog(root, "Step 3 Canon palette", [`canon.mjs wrote palette ${p.id} (${p.mood}) into the STRUQ TOKENS block.`]);
+    console.log("OK palette written");
+  },
+  type() {
+    const t = pairing(a);
+    const p = palette(current().palette);
+    const path = write(p, t);
+    const { file, hrefs } = writeFonts(t);
+    console.log(`Wrote type ${t.id} (${faces(t).join(" + ")}) to ${path.replace(root, ".")} and ${file.replace(root, ".")} (${hrefs.length} font URLs).`);
+    console.log(`STRUQ.md line:  Type: ${t.id}: ${faces(t).join(" + ")}`);
+    appendLog(root, "Step 3 Canon type", [`canon.mjs wrote type ${t.id}: ${faces(t).join(" + ")}, display weight ${t.displayScale?.weight ?? 300}.`]);
+    console.log("OK type written");
+  },
+  print() {
+    const p = palette(a);
+    const t = pairing(b ?? CANON.pairings[0].id);
+    console.log(tokenBlock(p, t));
+    console.log("");
+    for (const h of fontHrefs(t, CANON)) console.log(h);
+  },
+};
+
+if (process.argv[1] && resolve(process.argv[1]) === fileURLToPath(import.meta.url)) {
+  const run = commands[cmd];
+  if (!run || (cmd !== "list" && !a)) {
+    console.error("Usage: canon.mjs list | palette <id> | type <id> | print <palette> [pairing]   [--dir <project>]");
+    process.exit(2);
+  }
+  try {
+    run();
+  } catch (e) {
+    console.error(`FAIL ${e.message}`);
+    process.exitCode = 1;
+  }
+}