@pavp/wavefront 0.1.0

package/planning-templates/ROADMAP.md

@@ -0,0 +1,12 @@
+# ROADMAP
+
+> Project work-item backlog/sequence. Maintained across `/wavefront-feature|change|fix` runs.
+
+## Now
+- <work item in progress>
+
+## Next
+- <queued work items, ordered>
+
+## Done
+- <shipped items, newest first>

package/planning-templates/STATE.md

@@ -0,0 +1,21 @@
+# STATE
+
+> Current position. Updated by every wavefront command. Lets a run resume after interruption.
+
+## Active work item
+<title> · type · status: intake|planned|executing|verifying|shipping|done
+
+## Last step completed
+<command> — <result> — <timestamp>
+
+## Next step
+<command to run next>
+
+## Execution progress
+<which PHASE_PLAN tasks are done; which is next>
+
+## Decisions log
+- <date> <decision> — <why>
+
+## Blockers
+<anything stopping progress; empty if none>

package/settings.template.json

@@ -0,0 +1,29 @@
+{
+  "hooks": {
+    "PostToolUse": [
+      {
+        "matcher": "Edit|Write|MultiEdit",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "${CLAUDE_PROJECT_DIR}/.claude/hooks/lint-after-edit.sh",
+            "timeout": 60,
+            "statusMessage": "wavefront: lint --fix"
+          }
+        ]
+      }
+    ],
+    "Stop": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "${CLAUDE_PROJECT_DIR}/.claude/hooks/typecheck-on-stop.sh",
+            "timeout": 120,
+            "statusMessage": "wavefront: typecheck"
+          }
+        ]
+      }
+    ]
+  }
+}

package/skills/clean-architecture/SKILL.md

@@ -0,0 +1,46 @@
+---
+name: clean-architecture
+description: Clean Architecture layers, data flow, and dependency rules for scaffold-nextjs-app modules. Read before implementing or reviewing any feature.
+source: scaffold-nextjs-app/docs/module-architecture.md
+source_version: 8edaa0b
+---
+
+# Clean Architecture (frontend)
+
+Feature modules use Clean Architecture: layered separation, dependency inversion, testability. Three layers.
+
+## Layers (top depends on bottom, never reverse)
+
+```
+Views Layer          → Components · Business hooks · Controller hooks
+Application Layer     → Selectors · Repositories · Stores
+Infrastructure Layer  → API · Gateways · Helpers
+```
+
+- **Views** — UI render + interaction. Components are pure render. Business hooks = app logic/transforms/rules. Controller hooks = UI state/interaction.
+- **Application** — Selectors = derived state. Repositories = data access + React Query. Stores = local state (Zustand).
+- **Infrastructure** — API = HTTP + Zod validation. Gateways = data source abstraction (`http | localStorage | mock`). Helpers = pure utils.
+
+## Data flow (one direction)
+
+```
+User → Controller hook → Business hook → Repository → Gateway → API → HTTP
+         ↓                  ↓               ↓            ↓
+     UI state          business logic   React Query   data source
+```
+
+## Dependency rules (hard)
+
+1. **Direction:** Views → Application → Infrastructure. Never skip a layer (no View calling API/gateway directly; always through repository).
+2. **Dependency inversion:** business layer defines interfaces; infrastructure implements them. Business logic never imports UI or infra concretes.
+3. **Boundaries are typed:** every cross-layer contract is a TypeScript interface. Zod validates at the API boundary only.
+4. **Pure where possible:** helpers and business logic are pure/testable; side effects live in hooks/controllers, never in render.
+5. **Hook split is mandatory:** separate business hook (data/logic) from controller hook (UI state). See [[hook-patterns]].
+
+## When this architecture applies
+
+Use for: complex features, multi-data-source, long-lived apps, multi-dev teams, heavily-tested features.
+Simpler approaches OK for: trivial CRUD with no business logic, throwaway prototypes.
+
+## Related skills
+[[module-structure]] · [[naming-conventions]] · [[repository-pattern]] · [[gateway-pattern]] · [[selector-pattern]] · [[hook-patterns]] · [[store-zustand]]

package/skills/component-composition/SKILL.md

@@ -0,0 +1,67 @@
+---
+name: component-composition
+description: Build UI by COMPOSITION not inheritance in scaffold-nextjs-app — decompose views into small components, compose via children/props, use compound components (the @/ui Modal pattern). Read before writing or modifying any view/component.
+source: scaffold-nextjs-app/src/ui/modal, src/modules/todo/components
+source_version: 8edaa0b
+---
+
+# Component composition (over inheritance)
+
+UI is built by **composing small components**, never by inheritance. Views don't cram form+list+states into one file — they compose focused subcomponents. React has no class inheritance here (functional only); reuse comes from composition: children, props, and compound components.
+
+## Rule 1 — decompose, don't monolith
+A view orchestrates; it does NOT contain all the markup. Split by responsibility into `components/`:
+```
+src/modules/<m>/
+├── components/
+│   ├── <m>-form/<m>-form.component.tsx      # the create/edit form
+│   ├── <m>-item/<m>-item.component.tsx      # one row/card
+│   ├── <m>-list/<m>-list.component.tsx      # the list (maps items)
+│   └── index.ts
+└── views/<m>-management/<m>-management.view.tsx   # composes the above + hooks
+```
+Reference: `src/modules/todo/components/{todo-form,todo-item,todo-list,todo-filters}` — each its own dir, `*.component.tsx`, `*.test.tsx`. The view wires them to the business/controller hooks.
+
+## When to extract a subcomponent (decision rule)
+
+Apply to BOTH views and components — a component can (and often must) have its own subcomponents. Extract when ANY of these holds:
+
+1. **Mapped/repeated JSX → ALWAYS extract.** Anything rendered inside `.map()` is a subcomponent. A list that maps rows extracts the row: `contact-list` maps → `contact-item` is its subcomponent, never inline JSX in the `.map()`. (Hard rule — the most common miss.)
+2. **Distinct responsibility.** Form vs list vs item vs toolbar vs card = separate concerns → separate components.
+3. **Reused in >1 place** (or clearly will be) → extract so both consume one component.
+4. **Own state or handlers.** A chunk with its own `useState`/event logic → its own component (keeps the parent thin).
+5. **Size/complexity.** A JSX block past ~30–40 lines, or with nested conditionals, → extract a named piece.
+6. **Independently testable & nameable.** If you can give it a clear name and write a meaningful isolated test → it deserves to be a component.
+
+**Do NOT extract** (keep inline): trivial markup (1–2 elements), no reuse, no own logic, no map. A lone `<Typography>` or a single `<Button>` is inline. Don't over-fragment.
+
+**Components have subcomponents too** — extraction is recursive, not view-only. `contact-list` → `contact-item`; a `contact-item` with a complex actions cluster → `contact-item-actions`. Stop when the leaf is trivial markup.
+
+Quick examples:
+- list mapping rows → extract the row (rule 1). ✅ `contact-list` + `contact-item`.
+- form with several fields + validation → `*-form.component` (rules 2,4,5).
+- a single label + icon, used once → inline (no rule triggers).
+
+## Rule 2 — compose via children + props
+- Pass data/handlers down as props; pass slots as `children`.
+- A parent composes children; it does not extend them.
+- Presentational components are pure (props in → UI out), `memo` + `displayName`.
+
+## Rule 3 — compound components for multi-part UI
+When a component has structural parts (header / body / footer, etc.), use the **compound component** pattern: parent + sub-parts as separate components, attached to the parent with `Object.assign`, composed by the CONSUMER as children. The parent owns the shell; the consumer chooses which parts and in what order — no rigid all-in-one prop API, no inheritance. Each sub-part lives in its own dir (`components/panel-header/panel-header.component.tsx`) with its own colocated test; adding a part later doesn't change the parent's API.
+
+Shape: `export const Panel = Object.assign(memo(PanelRoot), { Header, Body });` then `<Panel><Panel.Header/><Panel.Body/></Panel>`.
+
+**Full worked example** (parent + parts + usage): see [examples/compound-component.md](examples/compound-component.md). In the scaffold, `@/ui` Modal implements this exact pattern (`Object.assign(memo(Modal), { Header, Content, Footer })`) — a live in-repo reference.
+
+## Anti-patterns (never)
+- A 200-line view holding form + list + every state inline (decompose it).
+- Boolean-prop explosion to switch variants (`isHeader`, `isFooter`, `showX`) → use composition/children instead.
+- Trying to "extend" a component (no inheritance) — wrap or compose.
+- Deeply coupled subcomponents that can't be tested alone — each component must be independently renderable + testable.
+
+## Each component is independently testable
+Decomposition exists partly so every piece gets its own colocated test (see [[testing-jest-rtl]]). If a component can't be rendered/tested in isolation, it's too coupled — split responsibilities.
+
+## Related
+[[design-system-inventory]] [[mui-design-tokens]] [[responsive-layouts]] [[hook-patterns]] [[testing-jest-rtl]] [[naming-conventions]]

package/skills/component-composition/examples/compound-component.md

@@ -0,0 +1,62 @@
+# Compound-component example
+
+Parent owns the shell; sub-parts are separate components attached via `Object.assign`; the CONSUMER composes them as children. No rigid all-in-one prop API, no inheritance. Each sub-part lives in its own dir with its own colocated test.
+
+```tsx
+// panel/components/panel-header/panel-header.component.tsx
+import { memo, type ReactNode } from 'react';
+import { Box, Typography } from '@/ui';
+import tokens from '@/styles/tokens';
+
+interface PanelHeaderProps {
+  title: string;
+  action?: ReactNode;
+}
+
+export const PanelHeader = memo(({ title, action }: PanelHeaderProps) => (
+  <Box display="flex" justifyContent="space-between" sx={{ mb: tokens.spacing.scale2 }}>
+    <Typography variant="h6">{title}</Typography>
+    {action}
+  </Box>
+));
+PanelHeader.displayName = 'PanelHeader';
+```
+
+```tsx
+// panel/components/panel-body/panel-body.component.tsx
+import { memo, type PropsWithChildren } from 'react';
+import { Box } from '@/ui';
+import tokens from '@/styles/tokens';
+
+export const PanelBody = memo(({ children }: PropsWithChildren) => (
+  <Box sx={{ py: tokens.spacing.scale2 }}>{children}</Box>
+));
+PanelBody.displayName = 'PanelBody';
+```
+
+```tsx
+// panel/panel.component.tsx — parent shell + attached parts
+import { memo, type PropsWithChildren } from 'react';
+import { Card, CardContent } from '@/ui';
+import { PanelHeader } from './components/panel-header/panel-header.component';
+import { PanelBody } from './components/panel-body/panel-body.component';
+
+const PanelRoot = memo(({ children }: PropsWithChildren) => (
+  <Card>
+    <CardContent>{children}</CardContent>
+  </Card>
+));
+PanelRoot.displayName = 'Panel';
+
+export const Panel = Object.assign(PanelRoot, { Header: PanelHeader, Body: PanelBody });
+```
+
+```tsx
+// usage — consumer COMPOSES the parts (not a giant prop list)
+<Panel>
+  <Panel.Header title={t('settings.title')} action={<Button>{t('common.save')}</Button>} />
+  <Panel.Body>{/* fields */}</Panel.Body>
+</Panel>
+```
+
+Adding a part later (e.g. `Panel.Footer`) doesn't change the parent's API. In the scaffold, `@/ui` Modal implements exactly this: `Object.assign(memo(Modal), { Header, Content, Footer })`.

package/skills/data-fetching-react-query/SKILL.md

@@ -0,0 +1,68 @@
+---
+name: data-fetching-react-query
+description: API layer (httpClient + Zod request/response validation + endpoints) and React Query config in scaffold-nextjs-app. Read before adding HTTP calls.
+source: scaffold-nextjs-app/docs + src/modules/todo/api/todo-api.ts, src/api, src/core/lib/react-query
+source_version: 8edaa0b
+---
+
+# Data fetching: API layer + React Query
+
+Infrastructure layer. The api file is the only place HTTP happens; gateways call it; repositories wrap gateways with React Query.
+
+## API service (per entity)
+
+```ts
+// modules/[entity]/api/[entity]-api.ts
+import { endpoints } from '@/api/endpoints';
+import { httpClient } from '@/api/http-client';
+import type { ApiOptions } from '@/api/api.types';
+import { TodoSchema, TodoArraySchema, CreateTodoSchema, /* ... */ } from '@/modules/todo/todo.types';
+
+export interface TodoApiContract {
+  getAll(filters?: TodoFilters, options?: ApiOptions): Promise<Todo[]>;
+  getById(id: string | number, options?: ApiOptions): Promise<Todo>;
+  create(todo: CreateTodoRequest, options?: ApiOptions): Promise<Todo>;
+  update(id: string | number, todo: UpdateTodoRequest, options?: ApiOptions): Promise<Todo>;
+  delete(id: string | number, options?: ApiOptions): Promise<void>;
+}
+
+const createTodoApiService = (): TodoApiContract => ({
+  async getAll(filters = {}, options) {
+    const response = await httpClient.get<Todo[]>(endpoints.TODO.BASE, {
+      params: filters,
+      requestSchema: TodoFiltersSchema,    // validates outgoing
+      responseSchema: TodoArraySchema,     // validates incoming
+      signal: options?.signal,
+    });
+    return response.data;
+  },
+  async create(todo, options) {
+    const response = await httpClient.post<Todo>(endpoints.TODO.BASE, todo, {
+      requestSchema: CreateTodoSchema, responseSchema: TodoSchema, signal: options?.signal,
+    });
+    return response.data;
+  },
+  // ...
+});
+
+export const todoApi = createTodoApiService();   // singleton
+```
+
+## Key conventions
+- **Define a `XApiContract` interface**, implement via `createXApiService()`, export a **singleton** `xApi`.
+- **Zod at the boundary**: pass `requestSchema` + `responseSchema` to `httpClient`. Schemas live in `[entity].types.ts` (co-located with types). This is the ONLY validation point for shape; domain rules go in the gateway.
+- **Endpoints centralized**: `endpoints.TODO.BASE`, `endpoints.TODO.BY_ID(id)` from `@/api/endpoints`. Never inline URL strings.
+- **httpClient** from `@/api/http-client` (axios-based wrapper). Forward `signal: options?.signal` for cancellation everywhere.
+- `ApiOptions` (`@/api/api.types`) ≈ `{ signal?: AbortSignal }`.
+
+## React Query config / helpers
+- Provider + client in `@/core/lib/react-query` (`getQueryClient`, `createPrefetchFunction`). Use `createPrefetchFunction` for server-component prefetch; `getQueryClient()` for imperative cancel.
+- Query defaults set per-query in query-options (`staleTime`, `gcTime`, `enabled`, `retry`).
+- Repository composes all this — see [[repository-pattern]].
+
+## Rules
+- Components/hooks NEVER import `httpClient` or `xApi` directly → go through repository → gateway → api.
+- One schema source of truth in `[entity].types.ts`; derive TS types from Zod where practical.
+
+## Related skills
+[[repository-pattern]] · [[gateway-pattern]] · [[forms-rhf-zod]]

package/skills/design-intake/SKILL.md

@@ -0,0 +1,69 @@
+---
+name: design-intake
+description: Normalize any design source (Figma — live via MCP or as an export — screenshot, mockup, HTML/CSS, a reference screen, a text description, or NOTHING) into a design-spec mapped to this app's @/ui + tokens. Read when a view/component has a visual to match or needs to stay continuous with the app.
+source: wavefront framework meta — pairs with design-system-inventory
+source_version: 8edaa0b
+---
+
+# Design intake
+
+Turn any design input into a **design-spec** the builder can implement. Every source converges to the same destination: `@/ui` components + `@/styles/tokens`, composed like the existing app. Intake does NOT pixel-perfect-render arbitrary markup — it **translates** to the design system. Always read [[design-system-inventory]] first.
+
+## Accepted sources (8) and how to read each
+1a. **Figma export (image/SVG/PDF)** — `Read` it (multimodal). Infer layout, hierarchy, spacing, component intent. Use when no Figma MCP is configured (the fallback for #1b).
+1b. **Figma via MCP (live)** — when a Figma MCP server is configured, pull exact frames + variables instead of inferring from an image. **Preferred over #1a whenever available** — see the *Figma source detection* rule in Procedure and the *Figma variables → tokens* section below.
+2. **Screenshot (PNG/JPG)** — `Read` (multimodal) → infer components + hierarchy. Estimate spacing → nearest `tokens.spacing.scaleN`.
+3. **Mockup / wireframe (low-fidelity)** — structure only; take layout, apply app's styling.
+4. **HTML/CSS pasted** (v0, codepen, etc) — parse markup/styles → MAP each element to its `@/ui` equivalent + tokens. Discard raw tags/inline styles.
+5. **Reference screen** ("like the todo page") — read that screen's code → replicate its pattern.
+6. **Text description** ("card with title, list, add button") — infer components from description + inventory.
+7. **Existing-app continuity** — no explicit design → derive from inventory + closest existing screen (the no-design path; see [[design-system-inventory]] continuity rule).
+8. **None at all** — same as #7.
+
+## Output: design-spec
+```
+## Design spec: <view/component>
+Source: <which of the 8 — for Figma, note "MCP-live (<server>)" or "image-fallback">
+Layout: <containers/grid/flex structure>
+Components (intent → @/ui): <e.g. "search box → TextField; priority → Selector; add → Button">
+Tokens: <spacing/color/typography tokens to use>
+States: loading | empty | error | populated — <how each renders>
+Interactions: <what triggers what; goes to controller hook>
+Responsive: <MANDATORY — behavior at minMobile/minTablet/minDesktop. If the source is one viewport, ASK the user first, then record it here.>
+Gaps: <design elements with NO @/ui equivalent — see below>
+```
+
+## Procedure
+1. Read [[design-system-inventory]] (component/token catalog + composition patterns).
+2. Identify the source type. If it's an image/Figma export/screenshot → `Read` the file (multimodal). If HTML → read the markup. If a reference screen → read its code. If none → continuity path.
+2b. **Figma source detection (live MCP vs image):** if the source is Figma, check whether Figma MCP tools are available this session:
+   - **Official Figma Dev Mode MCP** — `get_code` (structure/components), `get_variable_defs` (color/spacing/typography variables), `get_image` (visual cross-check). Selection/node-based; needs the Figma desktop app with Dev Mode.
+   - **Framelink (community) figma-mcp** — `get_figma_data` (structure + variables in one call), `download_figma_images` (assets). Figma-link/node-based; uses the Figma API.
+   - **If available → live path (#1b):** pull structure (`get_code` / `get_figma_data`) for layout + component intent, pull variables (`get_variable_defs` / from `get_figma_data`) for exact tokens, optionally pull an image (`get_image` / `download_figma_images`) only to cross-check. Map per *Figma variables → tokens* below. Record `Source: MCP-live (<server>)`.
+   - **If NOT available → image fallback (#1a):** treat the Figma export as an image; infer + estimate. Record `Source: image-fallback`. Never error on missing MCP.
+3. Map every visual element to a real `@/ui` component + tokens. Estimate spacing to the nearest scale token (for #1b, prefer the EXACT variable from `get_variable_defs`/`get_figma_data` over estimation).
+4. Define the four states (loading/empty/error/populated) even if the source only shows the happy path — propose them.
+4b. **Responsive (mandatory):** define behavior at minMobile/minTablet/minDesktop. Most sources are ONE viewport — when responsive isn't specified, ASK the user how key elements adapt (stack/wrap/hide, column counts, nav pattern), offering mobile-first defaults; record the answer. Never ship a single-viewport layout. See [[responsive-layouts]].
+5. **Gap-detection:** list anything the design shows that `@/ui` can't express. For each gap, propose: (a) approximate with existing components, or (b) add a new `@/ui` component (Ask-first — touches the design system). Never hand-roll a raw `<div>`/`<input>` to match a pixel.
+6. Output the design-spec into the work item's plan; the builder implements from it.
+
+## Rules
+- Translate to the design system, don't replicate foreign markup.
+- Spacing/color/typography → tokens, never literals (even if the source has exact px — snap to scale).
+- Always specify the four states.
+- Continuity over fidelity: when in doubt, match the existing app, not the mockup's incidental styling.
+- Gaps are Ask-first if they imply new `@/ui` components.
+
+## Figma variables → tokens (live MCP path, #1b)
+When a Figma MCP yields variables (via `get_variable_defs` or inside `get_figma_data`), map them to `@/styles/tokens` (Style Dictionary; see [[mui-design-tokens]]) — exact, not estimated:
+- **Spacing/size variables** → exact `tokens.spacing.scaleN` (match the value; only snap to nearest if no exact scale exists).
+- **Color variables** → `tokens.colors.*` by role/name. No token equivalent → **Gap** (Ask-first: approximate with an existing token or add to the token set — never a literal hex).
+- **Typography variables** → `tokens.typography.*`.
+- **Breakpoints / auto-layout** → `tokens.breakpoints.*` + flex/grid; feeds the mandatory `Responsive:` line.
+- Rule unchanged: tokens never literals — now sourced from real variables instead of guessed.
+
+## Notes — Figma MCP (live; server-configured by the user)
+A Figma MCP gives exact frames, auto-layout, and design variables (vs inferring from an image). Wavefront ships only the detection + mapping rules — the user configures their own server (official Dev Mode MCP or Framelink). When none is present, Figma degrades to the exported-image path (#1a) with no error. Tracked in `docs/roadmap.md` F6 notes.
+
+## Related
+[[design-system-inventory]] [[responsive-layouts]] [[mui-design-tokens]] [[requirement-intake]] [[hook-patterns]] [[i18n-next-intl]]

package/skills/design-system-inventory/SKILL.md

@@ -0,0 +1,38 @@
+---
+name: design-system-inventory
+description: Catalog of the app's design system (@/ui components, @/styles/tokens, and how real screens compose them) so generated UI is visually continuous with the rest of the app. Read before building any view/component, especially when no design is provided.
+source: scaffold-nextjs-app/src/ui, src/styles, src/modules/*/views + components
+source_version: 8edaa0b
+---
+
+# Design system inventory
+
+The continuity engine. Whatever the design source (or none), generated UI must look like the rest of THIS app. That means: build from `@/ui`, space with `@/styles/tokens`, and compose the way existing screens do. **Build the inventory by reading the real code — do not assume.**
+
+## Step 0 — inventory the actual app (do this each run)
+1. `@/ui` exports: read `src/ui/index.ts` → the available components (Button, TextField, Selector, Dialog, Modal, Card, Box, Typography, Container, Grid, List, Checkbox, RadioButton, Switch, Pagination, Toast, etc. — read the real list, it evolves).
+2. Tokens: read `src/styles/tokens.ts` + subdirs → `tokens.spacing.scaleN`, `tokens.colors.*`, `tokens.typography.*`, `tokens.breakpoints.*`. Use these, never literals.
+3. Composition patterns: read 1–2 existing views (`src/modules/todo/views/...`, `src/modules/about/...`) → how they lay out forms, lists, cards; what wraps what; how loading/empty/error states render.
+
+## Component selection map (intent → @/ui)
+Match design intent to the real component, never raw `@mui/material`:
+- text input → `TextField` (uncontrolled `onChange:(value)=>` or RHF `control`).
+- choice/dropdown → `Selector`; toggle → `Switch`/`ToggleButton`; multi → `Checkbox`/`RadioButton`.
+- action → `Button` (`variant="contained|outlined"`).
+- container/section → `Card`+`CardContent`, `Box`, `Container` (theme breakpoints e.g. `maxWidth="largeScreen"`).
+- layout → `Grid`, `Box` (`display="flex"`, `sx={{ gap: tokens.spacing.scaleN }}`).
+- list → `List` + items; feedback → `Toast`/`Dialog`/`Modal`; loading → `CircularProgress`/`LoadingIndicator`/`Skeleton`.
+If the design needs something with NO `@/ui` equivalent → flag it (see [[design-intake]] gap-detection): propose adding to `@/ui` or approximating, don't hand-roll a raw element.
+
+## Composition conventions (from real screens)
+- Functional components, explicit Props interface, named export, `memo` + `displayName` for presentational, `'use client'` when stateful.
+- Spacing/gap/margins via `tokens.spacing.scaleN`. Colors/typography via tokens.
+- Always cover the **four states**: loading, empty, error, populated (existing views do — match them).
+- View = render only; data via business hook, UI state via controller hook ([[hook-patterns]]).
+- Strings via next-intl `t()` ([[i18n-next-intl]]); never literals.
+
+## Continuity rule (no-design case)
+When no design is supplied: pick the existing screen closest in purpose (a list feature → mirror the todo list; a form → mirror the about form), and reuse its component choices, layout, spacing rhythm, and state handling. Output should be indistinguishable in style from a screen a teammate wrote.
+
+## Related
+[[design-intake]] [[mui-design-tokens]] [[hook-patterns]] [[i18n-next-intl]] [[module-structure]]

package/skills/forms-rhf-zod/SKILL.md

@@ -0,0 +1,75 @@
+---
+name: forms-rhf-zod
+description: React Hook Form + Zod resolver + @/ui controlled inputs + i18n error keys in scaffold-nextjs-app. Read before building a validated form.
+source: scaffold-nextjs-app/src/modules/about/views/about-view + @/ui form components
+source_version: 8edaa0b
+---
+
+# Forms: React Hook Form + Zod
+
+Views layer. Validated forms use `useForm` + `zodResolver`, render `@/ui` inputs wired via `control`, and surface error messages as **i18n keys**.
+
+> Note: simple transient forms (e.g. todo-form) may use local `useState`. Use RHF+Zod when there is real validation. This is the validated-form reference.
+
+## Schema + type, colocated in `*.types.ts`
+
+```ts
+import { z } from 'zod';
+
+export const FormPersonalInfoInputSchema = z.object({
+  name: z.string().min(1, 'validation.name.required'),     // message = i18n key
+  surname: z.string().min(1, 'validation.surname.required'),
+  email: z.string().email('validation.email.invalid'),
+});
+export type FormPersonalInfoInput = z.infer<typeof FormPersonalInfoInputSchema>;
+```
+Zod messages are **translation keys**, resolved with `next-intl` `t()` at render.
+
+## Form component
+
+```tsx
+'use client';
+import { useForm } from 'react-hook-form';
+import { zodResolver } from '@hookform/resolvers/zod';
+import { useTranslations } from 'next-intl';
+import { Box, Button, Grid, TextField } from '@/ui';
+import { FormPersonalInfoInput, FormPersonalInfoInputSchema } from './about-view.types';
+
+export const AboutView = () => {
+  const t = useTranslations();
+  const { control, handleSubmit, formState: { errors, isValid } } = useForm<FormPersonalInfoInput>({
+    mode: 'onTouched',
+    defaultValues: { name: '', surname: '', email: '' },
+    resolver: zodResolver(FormPersonalInfoInputSchema),
+  });
+
+  const onSubmit = (data: FormPersonalInfoInput) => { /* call business hook / mutation */ };
+
+  return (
+    <form noValidate onSubmit={handleSubmit(onSubmit)}>
+      <TextField
+        required
+        control={control}                                   // @/ui TextField is RHF-aware
+        name="name"
+        label="Name"
+        errorMessage={errors.name?.message && t(errors.name.message)}  // key → translation
+      />
+      <Button disabled={!isValid} type="submit" variant="outlined">Submit</Button>
+    </form>
+  );
+};
+```
+
+## Conventions
+- `@/ui` form inputs (`TextField`, `Selector`, `RadioButton`, `TimePicker`, ...) accept RHF `control` + `name`; pass them rather than wiring `register` manually.
+- `mode: 'onTouched'`; gate submit with `formState.isValid`.
+- Error messages: Zod returns a key, render with `t(errors.field?.message)`. See [[i18n-next-intl]].
+- Submit handler delegates to the business hook / repository mutation — no fetching in the form.
+
+## Rules
+- Schema is single source of truth; derive the TS type with `z.infer`.
+- Validation keys are real i18n keys; don't hardcode user-facing strings.
+- `'use client'` on form components.
+
+## Related skills
+[[i18n-next-intl]] · [[mui-design-tokens]] · [[data-fetching-react-query]] · [[hook-patterns]]

package/skills/gateway-pattern/SKILL.md

@@ -0,0 +1,79 @@
+---
+name: gateway-pattern
+description: Data-source abstraction (http | localStorage) via gateway factory in scaffold-nextjs-app. Read before writing a module's data access.
+source: scaffold-nextjs-app/docs/gateway-pattern.md + src/modules/todo/repositories/todo/gateways
+source_version: 8edaa0b
+---
+
+# Gateway pattern
+
+Gateways abstract the data source so the rest of the module is agnostic to http vs localStorage. Infrastructure layer.
+
+## Pieces (per entity)
+
+```
+repositories/[entity]/gateways/
+├── http-gateway/http-gateway.ts
+├── local-storage-gateway/local-storage-gateway.ts   # kebab dir
+│   └── helpers/[name]/[name].helper.ts
+├── [entity].gateway.types.ts        # interface extends BaseGateway
+└── index.ts                         # factory + re-exports
+```
+
+## Interface (extends shared BaseGateway)
+
+```ts
+// [entity].gateway.types.ts
+import type { BaseGateway, GatewayOptions } from '@/types/gateway.types';
+
+export interface TodoGateway extends BaseGateway {
+  findAll(filters?: TodoFilters, options?: GatewayOptions): Promise<Todo[]>;
+  findById(id: string | number, options?: GatewayOptions): Promise<Todo>;
+  create(todo: CreateTodoRequest, options?: GatewayOptions): Promise<Todo>;
+  update(id: string | number, todo: UpdateTodoRequest, options?: GatewayOptions): Promise<Todo>;
+  delete(id: string | number, options?: GatewayOptions): Promise<void>;
+}
+```
+`GatewayOptions` carries `signal?: AbortSignal`. `BaseGateway` provides `getSourceInfo()`.
+
+## Concrete gateway = factory returning the interface
+
+```ts
+// http-gateway/http-gateway.ts
+export const createHttpTodoGateway = (): TodoGateway => ({
+  async findAll(filters, options) { return todoApi.getAll(filters, options); },
+  async create(todo, options) {
+    validateTodoData(todo);          // gateway-level domain validation
+    return todoApi.create(todo, options);
+  },
+  // ...
+  getSourceInfo() {
+    return { type: 'http', name: 'HTTP API Gateway',
+      capabilities: { offline: false, realtime: true, persistence: true } };
+  },
+});
+```
+- HTTP gateway delegates to the **api layer** ([[data-fetching-react-query]] uses the api via gateway). localStorage gateway implements the same interface against `localStorage`, with pure helpers in `helpers/`.
+- Domain validation (e.g. `validateTodoData`) lives in the gateway, not the api.
+
+## Factory selector
+
+```ts
+// gateways/index.ts
+export const createTodoGateway = (source: DataSource = 'http'): TodoGateway => {
+  switch (source) {
+    case 'http': return createHttpTodoGateway();
+    case 'localStorage': return createLocalStorageTodoGateway();
+    default: return createHttpTodoGateway();
+  }
+};
+```
+`DataSource = 'http' | 'localStorage'` from `@/types/gateway.types` (TWO sources in the shipped scaffold — verify the union before assuming `'mock'`). Repository/query-options call `createXGateway(dataSource)` — never import a concrete gateway directly. Keep the long gateway-types import RELATIVE (`../notification.gateway.types`) inside `gateways/` to stay under `max-len 120`.
+
+## Rules
+- One interface per entity extending `BaseGateway`; all sources implement it identically.
+- Gateways return domain types, accept `GatewayOptions` (forward `signal`).
+- No React, no React Query here — pure data access. Repository layer wraps it.
+
+## Related skills
+[[repository-pattern]] · [[data-fetching-react-query]] · [[clean-architecture]]

package/skills/hook-patterns/SKILL.md

@@ -0,0 +1,74 @@
+---
+name: hook-patterns
+description: Mandatory business-hook vs controller-hook separation in scaffold-nextjs-app views. Read before writing any view/feature hook.
+source: scaffold-nextjs-app/docs/hook-patterns.md + src/modules/todo/views/todo-management/hooks
+source_version: 8edaa0b
+---
+
+# Hook patterns (business vs controller)
+
+Views layer. REQUIRED split: business hook (data + domain logic) and controller hook (UI state + interactions). The view component consumes both and stays render-only.
+
+```
+views/[view]/hooks/
+├── use-[view]-business/use-[view]-business.hook.ts
+└── use-[view]-controller/use-[view]-controller.hook.ts
+```
+
+## Business hook — data, logic, transforms
+
+```ts
+'use client';
+import { useCallback, useMemo } from 'react';
+import { todoRepository } from '@/modules/todo/repositories/todo';
+import { useTodoStatsSelector, useFiltersSelector } from '@/modules/todo/selectors';
+import { useTodoActions } from '@/modules/todo/stores/todo.store.actions';
+import type { DataSource } from '@/types/gateway.types';
+
+export const useTodoManagementBusiness = (dataSource: DataSource = 'http') => {
+  const { filters } = useFiltersSelector();
+  const { setFilters } = useTodoActions();
+
+  const todosQuery = todoRepository.queries.useTodos(filters, dataSource);
+  const createMutation = todoRepository.mutations.useCreateTodo(dataSource);
+
+  const createTodo = useCallback(async (data: CreateTodoRequest) => {
+    if (!data.title?.trim()) throw new Error('Todo title is required');   // business rule
+    return createMutation.mutate({ ...data, title: data.title.trim() });
+  }, [createMutation]);
+
+  const todos = useMemo(() => (todosQuery.data ?? []).map((t) => ({ ...t /* presentation shape */ })), [todosQuery.data]);
+
+  return {
+    createTodo, applyFilters: (f) => setFilters({ ...filters, ...f }),   // actions
+    todos, filters,                                                       // data
+    isLoading: todosQuery.isLoading, isCreating: createMutation.isPending, hasError: !!todosQuery.error, // states
+    refetch: todosQuery.refetch,                                          // utilities
+  };
+};
+```
+Business hook = repository + selectors + store actions, wrapped in `useCallback`/`useMemo`, enforcing domain rules. Returns grouped: **actions / data / states / utilities**.
+
+## Controller hook — UI state, interactions
+
+Owns local UI concerns: dialog open/close, selected tab, form-open flags, handlers that translate user events into business calls. Reads business hook output, holds `useState` for view-only state. No data fetching, no API.
+
+## View component — render only
+
+```tsx
+'use client';
+export const TodoManagementView = () => {
+  const business = useTodoManagementBusiness();
+  const controller = useTodoManagementController(business);
+  return (/* JSX wiring business data + controller handlers */);
+};
+```
+
+## Rules
+- Never fetch or mutate in the component body (no side effects in render).
+- Business hook: domain logic + data. Controller hook: UI state + event wiring. Don't mix.
+- `'use client'` on hooks/views that use React state/effects.
+- Shared (non-view) hooks live in `modules/[m]/hooks/[name]/[name].hook.ts`.
+
+## Related skills
+[[repository-pattern]] · [[selector-pattern]] · [[store-zustand]] · [[clean-architecture]]