groundwork-method 0.0.1 → 0.11.0

package/src/engineer-skills/groundwork-nextjs-engineer/references/type-system.md

@@ -0,0 +1,368 @@
+# Type System & Schemas
+
+## Table of Contents
+- [Zod as the Contract](#zod-as-the-contract)
+- [Schema Organisation](#schema-organisation)
+- [Deriving Types](#deriving-types)
+- [Discriminated Unions](#discriminated-unions)
+- [Exhaustive Matching](#exhaustive-matching)
+- [The Result Pattern](#the-result-pattern)
+- [RSC Serialisation Boundary](#rsc-serialisation-boundary)
+- [Type Guards over any](#type-guards-over-any)
+
+---
+
+## Zod as the Contract
+
+Zod schemas are the single source of truth for all data shapes in the codebase. They serve as the type contract between the Go backend API and the React frontend. Every API response is validated against a Zod schema, and all TypeScript types for API data are derived from those schemas.
+
+Standalone TypeScript interfaces for API data are forbidden — they drift from reality. Zod schemas enforce runtime validation and compile-time types simultaneously.
+
+```tsx
+// lib/schemas/meeting.ts
+import { z } from 'zod';
+
+export const meetingSchema = z.object({
+  id: z.string().uuid(),
+  title: z.string().min(1),
+  status: z.enum(['scheduled', 'in_progress', 'completed', 'cancelled']),
+  host_id: z.string().uuid(),
+  starts_at: z.string().datetime(),
+  duration_minutes: z.number().int().positive(),
+  created_at: z.string().datetime(),
+  updated_at: z.string().datetime(),
+});
+
+export type Meeting = z.infer<typeof meetingSchema>;
+
+export const meetingListSchema = z.object({
+  data: z.array(meetingSchema),
+  pagination: z.object({
+    next_cursor: z.string().nullable(),
+    has_more: z.boolean(),
+  }),
+});
+
+export type MeetingList = z.infer<typeof meetingListSchema>;
+```
+
+### Why Zod over Interfaces
+
+- **Runtime validation** — API responses are parsed, not assumed. If the backend changes a field name or type, the schema catches it immediately instead of producing silent runtime bugs.
+- **Single definition** — The schema defines shape, constraints, and TypeScript type in one place.
+- **Form integration** — Zod schemas plug directly into `react-hook-form` via `@hookform/resolvers/zod` for validation.
+
+---
+
+## Schema Organisation
+
+All schemas live in `lib/schemas/` with zero internal application dependencies. A schema file must never import from hooks, components, contexts, or the API client.
+
+```
+lib/schemas/
+├── meeting.ts                 # Meeting entity schemas
+├── meeting-synthesis.ts       # Synthesis-related schemas
+├── user.ts                    # User entity schemas
+├── common.ts                  # Shared schemas (pagination, error responses)
+└── index.ts                   # Barrel export
+```
+
+Each file exports:
+1. The Zod schema object (`meetingSchema`)
+2. The inferred TypeScript type (`Meeting`)
+3. Any sub-schemas needed for forms or partial updates
+
+```tsx
+// lib/schemas/index.ts
+export { meetingSchema, type Meeting, meetingListSchema, type MeetingList } from './meeting';
+export { userSchema, type User } from './user';
+export { paginationSchema, type Pagination } from './common';
+```
+
+---
+
+## Deriving Types
+
+Always derive types from schemas using `z.infer`. Never write parallel TypeScript interfaces.
+
+```tsx
+// Correct — type derived from schema
+export const meetingSchema = z.object({ /* ... */ });
+export type Meeting = z.infer<typeof meetingSchema>;
+
+// Incorrect — standalone interface duplicates the schema and will drift
+export interface Meeting {
+  id: string;
+  title: string;
+  // This will get out of sync with the schema
+}
+```
+
+### Partial and Pick Types
+
+Derive form-specific types from the base schema:
+
+```tsx
+// Schema for creating a meeting (subset of fields)
+export const createMeetingSchema = meetingSchema.pick({
+  title: true,
+  starts_at: true,
+  duration_minutes: true,
+});
+
+export type CreateMeetingInput = z.infer<typeof createMeetingSchema>;
+
+// Schema for updating a meeting (all fields optional)
+export const updateMeetingSchema = meetingSchema.partial().omit({
+  id: true,
+  created_at: true,
+  updated_at: true,
+});
+
+export type UpdateMeetingInput = z.infer<typeof updateMeetingSchema>;
+```
+
+---
+
+## Discriminated Unions
+
+Use discriminated unions to model states that are mutually exclusive. This prevents impossible states at the type level — the compiler enforces that only valid combinations of fields are accessed.
+
+```tsx
+// Correct — discriminated union makes invalid states impossible
+const meetingInputSchema = z.discriminatedUnion('type', [
+  z.object({
+    type: z.literal('recording'),
+    recording_url: z.string().url(),
+    device_id: z.string(),
+  }),
+  z.object({
+    type: z.literal('upload'),
+    file_path: z.string(),
+    file_size: z.number().positive(),
+  }),
+]);
+
+type MeetingInput = z.infer<typeof meetingInputSchema>;
+
+// Usage — the compiler knows which fields exist based on type
+function processMeetingInput(input: MeetingInput) {
+  switch (input.type) {
+    case 'recording':
+      // TypeScript knows recording_url and device_id exist here
+      startRecording(input.recording_url, input.device_id);
+      break;
+    case 'upload':
+      // TypeScript knows file_path and file_size exist here
+      uploadFile(input.file_path, input.file_size);
+      break;
+  }
+}
+```
+
+```tsx
+// Incorrect — loose optional fields allow impossible states
+const meetingInputSchema = z.object({
+  type: z.enum(['recording', 'upload']),
+  recording_url: z.string().url().optional(),      // When is this present?
+  device_id: z.string().optional(),                 // What if type is 'upload'?
+  file_path: z.string().optional(),                 // What if type is 'recording'?
+  file_size: z.number().positive().optional(),
+});
+// Nothing prevents { type: 'recording', file_path: '/foo' }
+```
+
+---
+
+## Exhaustive Matching
+
+Always enforce exhaustive matching on discriminated unions using `default: never`. This catches unhandled cases at compile time when new variants are added.
+
+```tsx
+type MeetingStatus = Meeting['status'];  // 'scheduled' | 'in_progress' | 'completed' | 'cancelled'
+
+function getStatusLabel(status: MeetingStatus): string {
+  switch (status) {
+    case 'scheduled':
+      return 'Upcoming';
+    case 'in_progress':
+      return 'Live';
+    case 'completed':
+      return 'Done';
+    case 'cancelled':
+      return 'Cancelled';
+    default: {
+      // If a new status is added to the enum, this line produces a compile error
+      const _exhaustive: never = status;
+      return _exhaustive;
+    }
+  }
+}
+```
+
+When a fifth status (e.g., `'archived'`) is added to the schema, the compiler flags every switch statement that doesn't handle it.
+
+---
+
+## The Result Pattern
+
+All Server Actions return a strictly typed `ActionResult<T>` to prevent unhandled client-side crashes from failed mutations. A Server Action must never throw — it always returns a result.
+
+### Type Definition
+
+```tsx
+// lib/schemas/common.ts
+type ActionResult<T> =
+  | { data: T; error: null }
+  | { data: null; error: string };
+```
+
+### Server Action Implementation
+
+```tsx
+// app/actions/meeting-actions.ts
+'use server';
+
+import { createMeetingSchema, type Meeting } from '@/lib/schemas';
+import { createMeeting } from '@/lib/api';
+import { revalidatePath } from 'next/cache';
+
+export async function createMeetingAction(
+  formData: FormData
+): Promise<ActionResult<Meeting>> {
+  const parsed = createMeetingSchema.safeParse({
+    title: formData.get('title'),
+    starts_at: formData.get('starts_at'),
+    duration_minutes: Number(formData.get('duration_minutes')),
+  });
+
+  if (!parsed.success) {
+    return { data: null, error: parsed.error.issues[0].message };
+  }
+
+  try {
+    const meeting = await createMeeting(parsed.data);
+    revalidatePath('/meetings');
+    return { data: meeting, error: null };
+  } catch {
+    return { data: null, error: 'Failed to create meeting. Please try again.' };
+  }
+}
+```
+
+### Client Consumption
+
+```tsx
+'use client';
+
+import { createMeetingAction } from '@/app/actions/meeting-actions';
+import { useTransition } from 'react';
+
+function CreateMeetingButton() {
+  const [isPending, startTransition] = useTransition();
+
+  async function handleSubmit(formData: FormData) {
+    startTransition(async () => {
+      const result = await createMeetingAction(formData);
+      if (result.error) {
+        // Show error in UI — never an unhandled throw
+        toast.error(result.error);
+        return;
+      }
+      // Successfully created
+      toast.success(`Created: ${result.data.title}`);
+    });
+  }
+
+  return (
+    <form action={handleSubmit}>
+      {/* form fields */}
+      <button type="submit" disabled={isPending}>
+        {isPending ? 'Creating…' : 'Create Meeting'}
+      </button>
+    </form>
+  );
+}
+```
+
+---
+
+## RSC Serialisation Boundary
+
+When a Server Component passes props to a Client Component, those props must be JSON-serialisable. React serialises them across the server-client boundary, and non-serialisable values either silently corrupt or crash.
+
+### What Can Cross the Boundary
+
+| Type | Serialisable? | Notes |
+|------|-------------|-------|
+| `string`, `number`, `boolean` | Yes | |
+| `null`, `undefined` | Yes | |
+| Plain objects and arrays | Yes | No class instances |
+| Server Actions (`'use server'`) | Yes | The only exception for functions |
+| `Date` | **No** | Silently becomes a string — `.getFullYear()` crashes on the client |
+| `Map`, `Set` | **No** | Silently stripped |
+| Functions (non-Server Action) | **No** | Cannot be serialised |
+| Class instances | **No** | Methods are stripped |
+| `Symbol` | **No** | Unless globally registered |
+
+### Fixing Non-Serialisable Props
+
+```tsx
+// Bad — Date object silently becomes string, then crashes
+export default async function Page() {
+  const meeting = await getMeeting(id);
+  return <MeetingCard createdAt={meeting.created_at} />;  // Date object
+}
+
+// Good — serialise to ISO string on the server
+export default async function Page() {
+  const meeting = await getMeeting(id);
+  return <MeetingCard createdAt={meeting.created_at.toISOString()} />;
+}
+
+// Bad — Map cannot be serialised
+<ClientComponent items={new Map([['a', 1]])} />
+
+// Good — convert to plain object
+<ClientComponent items={Object.fromEntries(map)} />
+
+// Bad — function prop (not a Server Action)
+export default function Page() {
+  const handleClick = () => console.log('clicked');
+  return <ClientButton onClick={handleClick} />;  // Cannot serialise
+}
+
+// Good — define the function inside the client component
+'use client';
+export function ClientButton() {
+  const handleClick = () => console.log('clicked');
+  return <button onClick={handleClick}>Click</button>;
+}
+```
+
+---
+
+## Type Guards over any
+
+The `any` type is forbidden. When dealing with unknown data (external APIs, dynamic content, user input), use `unknown` and narrow the type using type guards or Zod parsing.
+
+```tsx
+// Bad — any bypasses all type checking
+function processResponse(data: any) {
+  return data.meetings[0].title;  // No type safety — runtime explosion
+}
+
+// Good — unknown + Zod parsing
+function processResponse(data: unknown) {
+  const parsed = meetingListSchema.safeParse(data);
+  if (!parsed.success) {
+    throw new Error(`Invalid API response: ${parsed.error.message}`);
+  }
+  return parsed.data.data[0].title;  // Fully typed
+}
+
+// Good — type guard for narrowing
+function isMeeting(value: unknown): value is Meeting {
+  return meetingSchema.safeParse(value).success;
+}
+```

package/src/engineer-skills/groundwork-nextjs-engineer/references/ux-principles.md

@@ -0,0 +1,230 @@
+# UX Principles
+
+## Table of Contents
+- [Speed & Interaction](#speed--interaction)
+- [Navigation & Control](#navigation--control)
+- [Information Architecture](#information-architecture)
+- [Feedback & Motion](#feedback--motion)
+- [Accessibility](#accessibility)
+- [Empty States & Onboarding](#empty-states--onboarding)
+- [Copy & Tone](#copy--tone)
+
+---
+
+## Speed & Interaction
+
+The UI must feel zero-latency for common actions. Speed is not a feature — it is the foundation of trust.
+
+### Principles
+
+- **Focus inputs immediately** — When a form or dialog opens, the primary input field must be focused without the user touching the mouse. Use `autoFocus` or `useRef` + `useEffect`.
+- **Inline editing** — Treat "viewing" and "editing" as the same action. Clicking a text element activates an in-place input. No separate "edit" screens, no confirmation dialogs for routine edits.
+- **Optimistic UI** — Update the interface immediately when the user acts. Show the intended result while the server confirms. Revert only on failure. See `references/data-fetching.md` for the SWR `mutate()` pattern.
+- **Instant resets** — After a successful form submission, clear all fields immediately so the user can submit the next entry without reaching for a mouse or navigating.
+
+### Anti-patterns
+
+| Don't | Why | Do Instead |
+|-------|-----|-----------|
+| Separate "view" and "edit" screens | Forces navigation for simple edits | Inline editing — click to edit in place |
+| Full-page loading spinner for submissions | Blocks the entire UI for a single operation | Optimistic update + subtle loading indicator on the action element |
+| "Are you sure?" confirmation dialogs for reversible actions | Interrupts flow unnecessarily | Allow immediate action; provide "Undo" for 5 seconds |
+| Unfocused form dialogs | User must click to start typing | `autoFocus` on the primary field |
+
+---
+
+## Navigation & Control
+
+### Command Palette
+
+The command palette is the central navigation hub. Users can search for anything — pages, actions, meetings, settings — from a single keyboard-activated overlay.
+
+- Launch with `⌘K` (macOS) / `Ctrl+K`
+- Results group by category (pages, actions, recent items)
+- Keyboard navigation with arrow keys + Enter
+- Uses `.surface-elevated` styling (see `references/visual-language.md`)
+
+### Keyboard Shortcuts
+
+Power users should never be forced to use the mouse. Provide shortcuts for frequent actions:
+
+| Action | Shortcut | Context |
+|--------|----------|---------|
+| Command palette | `⌘K` | Global |
+| Quick search | `/` | When no input is focused |
+| New meeting | `N` | Meeting list view |
+| Close modal/dialog | `Escape` | Any overlay |
+
+### Context Switching
+
+Switching between views should be instantaneous. Use layout-based navigation so the sidebar and header persist while only the content panel changes. Avoid full-page reloads.
+
+---
+
+## Information Architecture
+
+### Content-First Layout
+
+The most important content occupies the largest surface area and appears first in the visual hierarchy. Use the bento grid to establish importance through sizing (see `references/visual-language.md`).
+
+### Progressive Disclosure
+
+Show only what matters right now. Additional details reveal on interaction:
+- Expand/collapse sections for secondary information
+- Hover cards for quick previews
+- Drill-down for detailed views
+
+### Opacity-Based Depth
+
+Use text opacity to create visual hierarchy without additional colours:
+- Primary text: full opacity via `--color-text-primary`
+- Secondary text (metadata, timestamps): reduced opacity via `--color-text-secondary`
+- Disabled/inactive elements: further reduced opacity
+
+### Focal Points
+
+Create clear visual focal points using:
+- **Typography weight** — Bold headings draw the eye before body text
+- **Surface area** — Larger bento grid cells command more attention
+- **Colour contrast** — Accent colour on CTAs, muted tones for everything else
+- **Motion** — The first (and only) animated element on screen is the focal point
+
+---
+
+## Feedback & Motion
+
+### Liquid Transitions
+
+All transitions should feel organic and fluid — never mechanical or jarring.
+
+- **Entry:** Elements fade in and slide from their origin direction (bottom sheet from bottom, sidebar from left, tooltip from near the trigger)
+- **Duration:** 150-300ms for micro-interactions (button press, toggle); 300-500ms for layout transitions (panel open/close)
+- **Easing:** `ease-out` for elements appearing; `ease-in` for elements leaving. Never `linear`.
+
+### Tactile Scale Shifts
+
+Interactive elements respond to press with a subtle scale reduction:
+
+```css
+.interactive-element {
+  transition: transform 150ms ease-out;
+}
+
+.interactive-element:active {
+  transform: scale(0.97);  /* 3% reduction — barely perceptible, deeply satisfying */
+}
+```
+
+Never exceed 5% scale change — larger shifts feel cartoonish.
+
+### Calm Alerts
+
+Notifications and status indicators use the semantic role tokens from the design system — never a hand-picked hex. The specific hue for each role (often muted rather than a harsh stoplight) is the design system's decision; consume the role, not a colour.
+
+| State | Role token |
+|-------|------------|
+| Success | the `success` role |
+| Error | the `error` / `destructive` role |
+| Warning | the `warning` role |
+| Info | the `info` role |
+
+Toasts and banners should be dismissible, auto-fade after a reasonable duration (4-6 seconds for success, persistent for errors), and never stack vertically in a pile of doom.
+
+### Progressive Disclosure of Actions
+
+Actions should reveal contextually — on hover, on selection, or on focus. Don't show every possible action at all times.
+
+```tsx
+// Actions appear on hover/focus
+<div className="group relative">
+  <MeetingCard meeting={meeting} />
+  <div className="absolute top-2 right-2 opacity-0 group-hover:opacity-100 
+                  group-focus-within:opacity-100 transition-opacity">
+    <EditButton />
+    <DeleteButton />
+  </div>
+</div>
+```
+
+---
+
+## Accessibility
+
+Accessibility is a merge gate, not optional polish — semantic HTML, keyboard reachability, WCAG AA contrast, and labelled forms are a baseline requirement on every surface. See `references/accessibility.md` for the full reference.
+
+---
+
+## Empty States & Onboarding
+
+### Day-Zero Experience
+
+When a user first encounters a section with no data, the empty state should:
+1. Explain what this section is for
+2. Provide a single clear action to populate it
+3. Use a friendly illustration or icon (not a blank page)
+
+```tsx
+export function EmptyMeetingList() {
+  return (
+    <div className="surface-glass p-8 text-center">
+      <CalendarPlus size={48} className="mx-auto text-muted-foreground" aria-hidden />
+      <h3 className="text-title mt-4">No meetings yet</h3>
+      <p className="text-muted-foreground mt-2">
+        Schedule your first meeting to get started.
+      </p>
+      <Button className="mt-6">
+        <Plus size={16} aria-hidden />
+        Schedule Meeting
+      </Button>
+    </div>
+  );
+}
+```
+
+### Actionable Error States
+
+Error states must tell the user what went wrong and what they can do about it. Never show raw error codes or technical jargon.
+
+```tsx
+// Bad
+<p>Error 500: ECONNREFUSED</p>
+
+// Good
+<div className="surface-glass p-6 text-center" role="alert">
+  <AlertCircle size={32} className="mx-auto text-destructive" aria-hidden />
+  <h3 className="text-title mt-4">Couldn't load your meetings</h3>
+  <p className="text-muted-foreground mt-2">
+    We're having trouble connecting right now. Your data is safe.
+  </p>
+  <Button onClick={reset} className="mt-4">Try again</Button>
+</div>
+```
+
+### Input Preservation
+
+If a form submission fails, **never clear the user's input**. The react-hook-form + ActionResult pattern handles this automatically — `form.setError()` displays the server error without resetting field values.
+
+---
+
+## Copy & Tone
+
+### Voice Principles
+
+- **Concise** — Say it in fewer words. If a label can be one word, use one word.
+- **Active voice** — "Meeting created" not "A meeting has been created."
+- **Context-sensitive** — Error messages are empathetic. Success messages are brief. Help text is instructional.
+
+| Context | Tone | Example |
+|---------|------|---------|
+| Success | Brief, confident | "Saved" / "Meeting created" |
+| Error | Empathetic, actionable | "Couldn't save. Check your connection and try again." |
+| Empty state | Encouraging, helpful | "No meetings yet. Schedule your first one." |
+| Destructive action | Clear, honest | "Delete this meeting? This can't be undone." |
+| Loading | Invisible preferred | Use skeleton UI, not "Loading..." text |
+
+### Punctuation
+
+- Button labels: no period ("Save", not "Save.")
+- Toast messages: no period ("Meeting created", not "Meeting created.")
+- Error messages: period at end if a full sentence ("Check your connection and try again.")
+- Labels: no period ("Duration", not "Duration:")

package/src/engineer-skills/groundwork-nextjs-engineer/references/visual-language.md

@@ -0,0 +1,69 @@
+# Visual Language & Surfaces
+
+This reference is about **technique** — how to consume the design system and how the surface layer composes depth. It carries **no fixed palette, type, or surface catalogue**. Every concrete value (colours, type scale, shadow stacks, blur radii, gradients, surface treatments) is a per-app decision that lives in `docs/design-system.md` and is projected from `.groundwork/config/brand-tokens.json` into `app/brand.css` and surfaced through `app/globals.css` as token utilities. Read the design system before any visual work; never invent values here.
+
+## Where the values live
+
+The nextjs-app generator projects the design system's `visual` block into `app/brand.css` (regenerated, never hand-edited). `app/globals.css` maps those values into Tailwind token utilities and surface classes. The chain:
+
+| Layer | Owns | You touch |
+|---|---|---|
+| `docs/design-system.md` | The human source of truth — palette, type, elevation, surfaces, motion, at the depth standard | Read it |
+| `.groundwork/config/brand-tokens.json` `visual` block | The machine projection of those decisions | Read it; never hand-edit |
+| `app/brand.css` (generated) | `--gw-*` values + the shadcn structural vars, light and dark | Never hand-edit |
+| `app/globals.css` | Token-utility mappings (`@theme`) + surface classes | Extend structure only, never bake values |
+| Your components | Consume token utilities and surface classes | Here |
+
+**Consume tokens, never literals.** A raw hex/length/shadow/blur/gradient in a component bypasses the design system and fails the token-conformance lint (`eslint.config.mjs`). If you need a raw value, reference the projected custom property (`var(--gw-shadow-mid)`, or the Tailwind var form `shadow-(--gw-shadow-mid)`) — never a literal recipe.
+
+---
+
+## Colour (OKLCH)
+
+The design system defines colour in OKLCH — perceptually uniform lightness, so a colour at `L=0.7` reads equally bright across hues (unlike HSL). **Hex, RGB, and HSL literals are forbidden in components.**
+
+Consume colour through the projected token utilities — `bg-background`, `text-foreground`, `bg-primary`, `text-muted-foreground`, `border-border`, `bg-destructive`, the `chart-*` roles — all backed by the brand's palette in `brand.css`. The semantic role of each (which hue means success, error, accent) is the design system's call, recorded there; honour it rather than reaching for a generic "green."
+
+**Dynamic opacity** — derive a translucent variant of any token without a new variable, via the relative colour function:
+
+```css
+/* technique, not a value: any projected colour var works */
+background-color: oklch(from var(--background) l c h / 0.72);
+```
+
+This keeps one source of truth per colour while allowing per-surface translucency.
+
+---
+
+## Typography
+
+The design system commits a full type scale (families, and per-role size, line-height, weight, tracking) at `docs/design-system.md`; the per-role micro is projected into `--gw-text-<role>-{size,line,weight,tracking}`. Consume the scale through the project's type utilities or those custom properties. Do not invent ad-hoc font sizes — if content does not fit a role, the layout needs adjustment, not a new size. Where figures must align in columns, use the projected tabular-numerals treatment rather than the proportional default.
+
+---
+
+## Spacing (8pt grid)
+
+The design system's spacing scale derives from an 8px base (4px is the optical sub-grid). Consume it through the spacing-scale utilities (`p-4`, `gap-6`, `px-8`) — arbitrary length values (`p-[12px]`) fail lint. Reserve the 4px sub-grid step for optical alignment (icon centring, badge offsets, hairline adjustments), not general spacing. Related elements sit closer than unrelated ones: internal spacing is always tighter than the gap between groups.
+
+---
+
+## Surface depth — the technique
+
+High-end surfaces read as modelled material, not flat boxes. Four techniques compose that depth. The design system decides the *values*; you apply them through the projected tokens and surface classes.
+
+- **Multi-layer shadow.** A single drop shadow reads flat. Depth comes from stacking several shadows — a tight contact layer, a mid ambient layer, a wide diffuse layer — with alpha tapering as each widens, tinted toward the background rather than pure black. The stacks are projected as `--gw-shadow-low/mid/high` and surfaced as the `shadow-low/mid/high` utilities (theme-aware: the dark theme carries deeper variants).
+- **Backdrop blur.** Translucent surfaces over content need `backdrop-filter: blur(...)` (always paired with the `-webkit-` prefix). Blur radii are projected as `--gw-blur-subtle/standard/heavy` and the `backdrop-blur-*` utilities.
+- **Concentric radii.** When nesting rounded elements, keep curves harmonious: `inner radius = outer radius − padding`. Use the radius tokens (`rounded-lg`, `rounded-xl`), not literal pixel radii.
+- **Ambient gradient.** A barely-perceptible mesh/aurora gradient (opacity well under ~0.15, fading to transparent, layered over a solid fallback) adds warmth to large surfaces. Recipes are projected as gradient tokens; the hero surface composes one.
+
+### Surface utilities
+
+The per-app surface vocabulary — the glass/elevated/hero treatments that used to be a fixed catalogue — is projected from the design system's `surface` tokens into composite classes in `globals.css`. Apply them; do not re-author the recipe:
+
+| Class | For | Composes |
+|---|---|---|
+| `.surface-glass` | Regular content cards, panels, list items | standard blur + glass tint + hairline border + `shadow-mid` |
+| `.surface-elevated` | Modals, dialogs, command palette, popovers | heavy blur + denser tint + border + `shadow-high` |
+| `.surface-hero` | Dashboard hero metric, key insight, primary KPI | standard blur + hero tint + ambient gradient + `shadow-high` |
+
+Need a surface the project has not defined? Compose it from the same tokens (`var(--gw-shadow-*)`, `var(--gw-blur-*)`, the palette vars) or add the treatment to the design system and regenerate — never hardcode a one-off stack in a component.

package/src/engineer-skills/groundwork-nextjs-engineer/sync-anchor.md

@@ -0,0 +1,16 @@
+# Sync Anchor
+
+This file pins the principle files this skill embeds — both the per-stack
+TypeScript/frontend idiom doc and the cross-cutting central canon this skill
+distils. When any listed file changes, this skill must be reviewed in the same
+commit. CI verifies the hashes match.
+
+| Principle file | SHA-256 | Last reviewed |
+|---|---|---|
+| src/generators/nextjs-app/docs/principles/stack/typescript/frontend.md | 98232d067ad03c08d6c1ca5f2caec30e7c3400da55c3afb7754482bc121d7554 | 2026-05-26 |
+| src/docs/principles/foundations/testing.md | 205ac40d4c643e7b61cf1e4295df8a7b8b46dcd7c81b857aa8c642ea353f62ef | 2026-06-27 |
+| src/docs/principles/quality/observability.md | 8aa60e213ba03e989c93263153e3a1ac10b2336f6d0360c394f473660d565a0b | 2026-06-26 |
+| src/docs/principles/quality/security.md | 61157d97677142737ec537954dc5aaad7a04012cc8a3dcc855e2d324287fdc64 | 2026-06-26 |
+| src/docs/principles/quality/performance.md | 18b6d3391c57d97342068f9f1da732b24de4221489d0459bb6ad8900fac0a02e | 2026-06-26 |
+| src/docs/principles/quality/accessibility.md | f921e7bf6256bc105b127b841d0a30af8a70ad1ddd7632d492589f052e6501b2 | 2026-06-26 |
+| src/docs/principles/foundations/documentation.md | 8b576072eaf4970f1251b560781e3e755c864a7920faa599b2834c921cbb8734 | 2026-06-26 |