@pavp/wavefront 0.1.0

package/skills/i18n-next-intl/SKILL.md

@@ -0,0 +1,59 @@
+---
+name: i18n-next-intl
+description: next-intl usage in scaffold-nextjs-app — useTranslations, locale routing via @/i18n/routing, remote-fetched messages, validation keys. Read before adding user-facing strings.
+source: scaffold-nextjs-app/docs/intl.md + src/i18n/request.ts, src/i18n/routing.ts
+source_version: 8edaa0b
+---
+
+# i18n: next-intl
+
+All user-facing strings go through next-intl. No hardcoded copy in components.
+
+## Translating strings
+
+```tsx
+'use client';
+import { useTranslations } from 'next-intl';
+
+export const Greeting = () => {
+  const t = useTranslations();           // or useTranslations('namespace')
+  return <Typography>{t('home.title')}</Typography>;
+};
+```
+- Client components: `useTranslations()` hook.
+- Server components: `getTranslations()` from `next-intl/server`.
+- Keys are dot-paths (`home.title`, `validation.email.invalid`).
+
+## Locale-aware navigation (use @/i18n/routing, NOT next/link)
+
+```ts
+import { Link, redirect, usePathname, useRouter } from '@/i18n/routing';
+```
+`routing` is built with `defineRouting({ locales, defaultLocale })` + `createNavigation`. Locales come from `config.translation`. Routes use the `[locale]` App Router segment.
+
+## Messages are remote-fetched
+
+`src/i18n/request.ts` (`getRequestConfig`) fetches messages from the settings API per locale into the `common` namespace (with `revalidate`). There is **no local `messages/en.json`** to edit by default — translation strings live server-side. When adding a key:
+- Reference it in code (`t('feature.key')`).
+- Coordinate the actual translation value with the settings/translation backend (per `docs/intl.md`), not a local file — unless the project has been changed to local messages.
+
+## Validation messages = i18n keys
+
+Zod schemas return translation keys; render with `t()`:
+```ts
+z.string().email('validation.email.invalid')
+// in form: errorMessage={errors.email?.message && t(errors.email.message)}
+```
+See [[forms-rhf-zod]].
+
+## Conventions
+- Namespace keys by feature/module (`todo.*`, `auth.*`, `validation.*`).
+- Never hardcode visible text or error strings.
+- In tests, next-intl is mocked (`test/__mocks__/next-intl`) — `t('key')` typically returns the key; assert accordingly.
+
+## Rules
+- Components stay copy-free: text via `t()`, links via `@/i18n/routing`.
+- New keys: add usage in code + register the value with the translation source.
+
+## Related skills
+[[forms-rhf-zod]] · [[mui-design-tokens]] · [[testing-jest-rtl]]

package/skills/module-structure/SKILL.md

@@ -0,0 +1,98 @@
+---
+name: module-structure
+description: Exact folder/file shape of a feature module and the src/ tree in scaffold-nextjs-app. Read before scaffolding or placing any file.
+source: scaffold-nextjs-app/docs/project-structure.md
+source_version: 8edaa0b
+---
+
+# Module structure
+
+## Module shape (every feature module)
+
+```
+src/modules/[module-name]/
+├── api/                          # HTTP integration + Zod validation
+├── components/                   # module-specific UI
+├── repositories/
+│   └── [entity]/
+│       ├── gateways/
+│       │   ├── http-gateway/
+│       │   ├── local-storage-gateway/    # kebab (NOT localStorage-gateway)
+│       │   │   └── helpers/[name]/[name].helper.ts
+│       │   ├── index.ts
+│       │   └── [entity].gateway.types.ts
+│       ├── helpers/[name]/[name].helper.ts   # pure business utils, one dir each
+│       ├── index.ts
+│       ├── [entity].query-options.ts
+│       ├── [entity].repository.keys.ts       # React Query key factory
+│       ├── [entity].repository.types.ts
+│       ├── [entity].repository.queries.ts
+│       └── [entity].repository.mutations.ts
+├── selectors/[name]-selector/[name]-selector.hook.ts   # one dir per selector
+├── stores/
+│   ├── [module].store.ts
+│   ├── [module].store.actions.ts
+│   └── [module].store.types.ts
+├── views/
+│   └── [view]/
+│       ├── [view].view.tsx
+│       ├── hooks/use-[view]-business/use-[view]-business.hook.ts
+│       ├── hooks/use-[view]-controller/use-[view]-controller.hook.ts
+│       └── helpers/[name]/[name].helper.ts             # view-scoped helpers
+├── hooks/[name]/[name].hook.ts   # shared module hooks
+├── index.ts                      # public API (barrel)
+└── [module].types.ts             # module types
+```
+
+Reference modules in scaffold: `src/modules/todo` (full: stores, repositories, components, hooks, api, selectors, views), `src/modules/auth` (stores, repositories, api, selectors, views). Mirror their shape.
+
+Nesting note: components, views, selectors, hooks each use a **one-dir-per-unit** pattern (`use-x-selector/use-x-selector.hook.ts`). Views and components may nest their own `hooks/` (business+controller) and `helpers/`. Tests colocate next to source as `*.test.ts(x)`.
+
+## Surrounding src/ tree (do not put module code here)
+
+```
+src/
+├── api/            # SHARED api config: endpoints.ts, http-client.ts, types.ts
+├── app/            # Next.js App Router; [locale]/ i18n routes; layout.tsx
+├── components/     # project-wide reusable components (not design-system-generic)
+├── core/           # cross-project shared: components, hooks, helpers, layouts,
+│                   #   lib/ (react-query/, zustand/)
+├── hooks/          # app-wide custom hooks
+├── i18n/           # internationalization config
+├── modules/        # ← feature modules live here
+├── navigation/     # routing helpers
+├── shared/         # api/, gateways/ (base gateway types), types/
+├── styles/         # design tokens + styling
+├── types/          # global TS types
+└── ui/             # design system components (Button, Modal, Form, ...)
+test/               # utils/ (provider wrappers), entities/ (faker factories), __mocks__/
+```
+
+## Import aliases (tsconfig paths)
+
+```
+@/*            → ./src/*
+@/components/* → ./src/components/*
+@/modules/*    → ./src/modules/*
+@/core/*       → ./src/core/*
+@/shared/*     → ./src/shared/*
+@/ui/*         → ./src/ui/*
+@test/*        → ./test/*
+```
+
+Always use absolute imports. Examples:
+```ts
+import { Button } from '@/ui';
+import { todoRepository } from '@/modules/todo';
+import type { Todo } from '@/modules/todo';
+import { renderWithProviders, createMockTodo } from '@test/utils';
+```
+
+## Placement rules
+
+- Module-only code → inside the module. Cross-module reusable → `core/` (no business logic) or `components/`.
+- Generic design-system UI → `ui/`. Base gateway types → `shared/gateways/`.
+- Each dir exports via `index.ts` barrel; module's `index.ts` is its only public API.
+
+## Related skills
+[[clean-architecture]] · [[naming-conventions]] · [[repository-pattern]] · [[gateway-pattern]]

package/skills/mui-design-tokens/SKILL.md

@@ -0,0 +1,60 @@
+---
+name: mui-design-tokens
+description: Build UI from the @/ui design system + @/styles/tokens (Style Dictionary), never raw @mui/material or hardcoded values, in scaffold-nextjs-app.
+source: scaffold-nextjs-app/docs/design-tokens.md, project-structure.md + src/modules/todo/components
+source_version: 8edaa0b
+---
+
+# MUI + design tokens
+
+Views layer. Components are built from the project design system, not MUI directly, and spacing/scale come from tokens, not magic numbers.
+
+## Import from `@/ui`, not `@mui/material`
+
+```tsx
+import { Box, Button, Card, CardContent, Selector, TextField, Typography } from '@/ui';  // ✅
+// import { Button } from '@mui/material';                                                // ❌
+```
+`@/ui` exposes wrapped/themed design-system components (Button, Modal, TextField, Selector, Dialog, etc.). MUI icons (`@mui/icons-material`) are imported directly. Layout primitives (`Box`, `Typography`, `Card`) also come from `@/ui`.
+
+## Tokens for spacing/scale, not literals
+
+```tsx
+import tokens from '@/styles/tokens';
+
+<Card sx={{ mb: tokens.spacing.scale6 }}>
+  <Box sx={{ gap: tokens.spacing.scale4 }} display="flex" />
+  <Box sx={{ mt: tokens.spacing.scale4 }} />
+</Card>
+```
+- Use `tokens.spacing.scaleN` (and other token groups) instead of hardcoded `8`, `'16px'`, etc.
+- Tokens are generated by Style Dictionary (`yarn build:dictionary`) into `@/styles/tokens`.
+- One-off layout values that are genuinely not design-system concerns (e.g. a fixed control height) may stay inline, but prefer tokens for spacing/color/typography.
+
+## Component conventions
+
+```tsx
+'use client';
+import { memo } from 'react';
+
+interface TodoFormProps { isCreating: boolean; onSubmit: (todo: CreateTodoRequest) => void; }
+
+export const TodoForm = memo(({ isCreating, onSubmit }: TodoFormProps) => { /* ... */ });
+TodoForm.displayName = 'TodoForm';
+```
+- Functional components only. Explicit `Props` interface. Named export.
+- `memo` for pure presentational components; set `displayName` when memo-wrapped.
+- `'use client'` when using state/handlers.
+- No `any` in props. No render-time side effects.
+
+## Theme breakpoints (Container maxWidth)
+
+The theme augments MUI breakpoints with custom names. `Container maxWidth` accepts the THEME names (e.g. `"largeScreen"`), NOT MUI defaults (`"sm"`/`"md"` → type error). Match existing usage (`about-view` uses `maxWidth="largeScreen"`) or omit `maxWidth`.
+
+## Rules
+- UI from `@/ui`; icons from `@mui/icons-material`; never raw `@mui/material` in feature code.
+- Spacing/scale/color via `@/styles/tokens`; avoid hardcoded values.
+- i18n strings via next-intl, not literals — see [[i18n-next-intl]].
+
+## Related skills
+[[responsive-layouts]] · [[design-system-inventory]] · [[i18n-next-intl]] · [[naming-conventions]] · [[hook-patterns]]

package/skills/naming-conventions/SKILL.md

@@ -0,0 +1,65 @@
+---
+name: naming-conventions
+description: File/folder naming + suffixes + code casing enforced by eslint-plugin-check-file in scaffold-nextjs-app. Read before creating or renaming any file.
+source: scaffold-nextjs-app/docs/file-naming-conventions.md, docs/rules-conventions.md, eslint.config.mjs
+source_version: 8edaa0b
+---
+
+# Naming conventions
+
+ESLint-enforced (`eslint-plugin-check-file`). Violations = lint error, not style preference.
+
+## Enforced by lint (hard)
+
+- **File names:** `KEBAB_CASE` for all `*.{js,jsx,ts,tsx}` (`ignoreMiddleExtensions: true` → middle ext like `.component` allowed).
+- **Folders in `src/`:** `NEXT_JS_APP_ROUTER_CASE` (kebab, plus App Router segments like `[locale]`, `(group)`).
+- **Folders in `test/`:** `KEBAB_CASE`.
+- **`__mocks__/`:** exempt from filename rule.
+
+## File suffixes (descriptive type tags)
+
+| Suffix | Meaning | Example |
+|---|---|---|
+| `*.component.tsx` | React component | `todo-form.component.tsx` |
+| `*.view.tsx` | page/screen view | `todo-management.view.tsx` |
+| `*.hook.ts` | React hook (incl. business/controller/selector) | `use-todo-business.hook.ts` |
+| `*.helper.ts` | pure util (no React) | `validation.helper.ts` |
+| `*.store.ts` | Zustand store/actions | `todo.store.ts` |
+| `*.types.ts` | type definitions | `todo.types.ts` |
+
+Repository-layer files use dotted descriptors: `[entity].repository.queries.ts`, `[entity].repository.mutations.ts`, `[entity].repository.keys.ts`, `[entity].repository.types.ts`, `[entity].query-options.ts`, `[entity].gateway.types.ts`. Store: `[m].store.ts`, `[m].store.actions.ts`, `[m].store.types.ts`.
+
+Tests colocate next to source: `*.test.ts` / `*.test.tsx`. Test filenames may carry the source suffix (`todo-form.component.test.tsx`) or just `.test` on plain TS files (`local-storage-gateway.test.ts`) — both pass lint (`ignoreMiddleExtensions`).
+
+Do NOT skip the suffix (`button.tsx` ❌ → `button.component.tsx` ✅). No generic `utils.ts`.
+
+## Code element casing
+
+| Element | Case | Example |
+|---|---|---|
+| Variables / functions | `camelCase` | `userName`, `handleSubmit` |
+| Components | `PascalCase` | `TodoManagementView` |
+| Constants | `SCREAMING_SNAKE_CASE` | `MAX_RETRY_ATTEMPTS` |
+| Types / interfaces | `PascalCase` | `TodoRepository` |
+
+## Barrels
+
+Every dir has `index.ts` re-exporting its public items → enables `import { X } from '@/...'`.
+```ts
+// components/index.ts
+export { TodoForm } from './todo-form/todo-form.component';
+```
+
+## Exceptions to suffix rule
+
+`index.ts`, `package.json`, framework files (`layout.tsx`, `page.tsx`), config files.
+
+## Other enforced lint (relevant)
+
+- TS strict; `array-simple` array style; `record` indexed-object style; prefer optional chaining.
+- Import sort (`simple-import-sort`): react/externals → `@/` aliases → side-effect → parent → sibling → css.
+- Restricted imports: pull RTL/`react-dom` test bits from `@test/utils/test-utils`, not directly (`ui/` and `test/` exempt).
+- Unused vars: prefix `_` to ignore.
+
+## Related skills
+[[module-structure]] · [[clean-architecture]]

package/skills/repository-pattern/SKILL.md

@@ -0,0 +1,128 @@
+---
+name: repository-pattern
+description: Data-access layer combining React Query hooks + key factory + query/mutation options in scaffold-nextjs-app. Read before wiring a module's data fetching.
+source: scaffold-nextjs-app/docs/repository-pattern.md + src/modules/todo/repositories/todo
+source_version: 8edaa0b
+---
+
+# Repository pattern
+
+Application layer. Wraps gateways with React Query. The View/business hook talks ONLY to the repository, never to gateway/api directly.
+
+## Files (per entity)
+
+```
+repositories/[entity]/
+├── [entity].repository.types.ts       # interfaces for queries/mutations/repository
+├── [entity].repository.keys.ts        # query key factory
+├── [entity].query-options.ts          # queryOptions/mutationOptions factories
+├── [entity].repository.queries.ts     # query hooks object
+├── [entity].repository.mutations.ts   # mutation hooks object
+├── helpers/[name]/[name].helper.ts
+├── gateways/                          # see [[gateway-pattern]]
+└── index.ts                           # combined repository object
+```
+
+## 1. Key factory
+
+```ts
+export const todoQueryKeys = {
+  all: ['todos'] as const,
+  lists: (ds: DataSource = 'http') => [...todoQueryKeys.all, 'list', ds] as const,
+  list: (filters: TodoFilters = {}, ds: DataSource = 'http') =>
+    [...todoQueryKeys.lists(ds), filters] as const,
+  details: (ds: DataSource = 'http') => [...todoQueryKeys.all, 'detail', ds] as const,
+  detail: (id: string | number, ds: DataSource = 'http') =>
+    [...todoQueryKeys.details(ds), id] as const,
+} as const;
+```
+Keys are namespaced by `dataSource` so http/localStorage caches don't collide.
+
+## 2. query/mutation options (reusable, server-component-friendly)
+
+```ts
+const getTodosQueryOptions = (filters = {}, ds: DataSource = 'http') =>
+  queryOptions({
+    queryKey: todoQueryKeys.list(filters, ds),
+    queryFn: ({ signal }) => createTodoGateway(ds).findAll(filters, { signal }),
+    staleTime: 5 * 60 * 1000, gcTime: 10 * 60 * 1000,
+  });
+
+const getCreateTodoMutationOptions = (ds: DataSource = 'http') =>
+  mutationOptions({ mutationFn: (todo) => createTodoGateway(ds).create(todo), retry: 1 });
+
+export const todoQueryOptions = { todos: getTodosQueryOptions, /* ... */ } as const;
+export const todoMutationOptions = { createTodo: getCreateTodoMutationOptions, /* ... */ } as const;
+```
+queryFn forwards `signal`, calls the gateway factory. Reused by both hooks and prefetch.
+
+## 3. Query hooks (compose options)
+
+```ts
+export const todoQueriesRepository: TodoQueriesRepository = {
+  useTodos: (filters = {}, ds = 'http', options) =>
+    useQuery({ ...todoQueryOptions.todos(filters, ds), ...options }),
+  // prefetch: { prefetchTodos: createPrefetchFunction(...) }  // server components
+  // cancel: { cancelTodos: async (...) => queryClient.cancelQueries(...) }
+};
+```
+
+## 4. Mutation hooks (compose options + cache writes)
+
+```ts
+export const todoMutationsRepository: TodoMutationsRepository = {
+  useCreateTodo: (ds = 'http', options) => {
+    const queryClient = useQueryClient();
+    return useMutation({
+      ...todoMutationOptions.createTodo(ds),
+      // eslint-disable-next-line max-params  ← REQUIRED: onSuccess has 4 params, lint cap is 3
+      onSuccess: (newTodo, vars, onMutateResult, ctx) => {
+        queryClient.invalidateQueries({ queryKey: todoQueryKeys.lists(ds) });
+        queryClient.setQueryData<Todo[]>(todoQueryKeys.lists(ds), (old) => old ? [...old, newTodo] : [newTodo]);
+        options?.onSuccess?.(newTodo, vars, onMutateResult, ctx);
+      },
+      ...options,
+    });
+  },
+};
+```
+Mutations own cache invalidation/optimistic writes via `queryKeys`. Always call through user `options?.onSuccess`.
+
+## 5. Combined repository (the public surface)
+
+```ts
+export const todoRepository: TodoRepository = {
+  queries: todoQueriesRepository,
+  mutations: todoMutationsRepository,
+  queryKeys: todoQueryKeys,
+  queryOptions: todoQueryOptions,
+  mutationOptions: todoMutationOptions,
+};
+```
+Consumers: `todoRepository.queries.useTodos(filters, ds)` / `todoRepository.mutations.useCreateTodo(ds)`.
+
+## Repository types (`*.repository.types.ts`)
+
+Interfaces import from `@/core/lib/react-query`: `QueryOptions`, `MutationOptions` (custom option subsets), and queries-repo `extends BaseRepository`. Hook return types use `UseQueryResult<T, Error>` / `UseMutationResult<T, Error, TVars>`.
+```ts
+import { type UseMutationResult, type UseQueryResult } from '@tanstack/react-query';
+import type { BaseRepository } from '@/core/lib/react-query';
+import { MutationOptions, QueryOptions } from '@/core/lib/react-query';
+
+export interface XQueriesRepository extends BaseRepository {
+  useXs: (filters?: XFilters, dataSource?: DataSource, options?: QueryOptions) => UseQueryResult<X[], Error>;
+}
+export interface XMutationsRepository {
+  useCreateX: (dataSource?: DataSource, options?: MutationOptions) => UseMutationResult<X, Error, CreateXRequest>;
+}
+```
+Combined-repo `queryKeys`/`queryOptions`/`mutationOptions` typed via `typeof import('./...')`.
+
+## Rules
+- Every hook accepts `dataSource` (default `'http'`) and passthrough `options`.
+- Keys derive from the factory only; never inline key arrays in components.
+- Repository is the boundary: business hooks/selectors import the repository, not gateways/api.
+- `DataSource = 'http' | 'localStorage'` (the scaffold ships TWO sources, not `'mock'` despite older docs). Confirm in `@/types/gateway.types`.
+
+## Related skills
+[[gateway-pattern]] · [[selector-pattern]] · [[hook-patterns]] · [[data-fetching-react-query]] · [[clean-architecture]]

package/skills/requirement-intake/SKILL.md

@@ -0,0 +1,65 @@
+---
+name: requirement-intake
+description: Normalize a raw work item (prompt, user story, or spec) into a structured REQUIREMENTS doc with acceptance criteria, asking clarifying questions and proactively surfacing gaps. Read at the start of any wavefront feature/change/fix.
+source: wavefront framework meta — used by /wavefront-feature, /wavefront-change, /wavefront-fix
+source_version: 8edaa0b
+---
+
+# Requirement intake
+
+Turn any input shape into a planning-ready spec. The intake is **interactive and proactive** — not a parser. Read like a senior engineer: extract intent, then challenge gaps before any code is planned.
+
+## Accepted inputs
+- **Prompt:** one-liner ("add a notifications module").
+- **User story:** "Como [rol] quiero [acción] para [beneficio]" + optional acceptance criteria.
+- **Spec:** long doc / pasted ticket.
+
+## Output: REQUIREMENTS structure
+```
+## Work item: <short title>
+Type: feature | change | fix
+Source: <prompt | user story | spec>
+
+### Intent
+<1–3 sentences: who, what, why>
+
+### Scope
+- In: <what's included>
+- Out: <explicitly excluded>
+
+### Entities & layers touched
+<entities; which Clean Arch layers (api/gateway/repo/store/selector/hook/view/component) are affected>
+
+### Acceptance criteria  (→ become tests)
+- [ ] <criterion 1, observable/testable>
+- [ ] ...
+
+### Open questions  (must resolve before planning)
+- <question> — <why it matters>
+
+### Suggested additions  (gaps intake spotted, propose to user)
+- <edge case / error state / missing criterion the story didn't mention>
+```
+
+## Procedure
+1. **Classify** the input (prompt/story/spec) and the worktype (feature/change/fix).
+2. **Extract** intent, scope, entities, and any stated acceptance criteria.
+3. **Map to layers:** which Clean Arch layers this likely touches (informs the plan). See [[module-structure]] [[clean-architecture]].
+4. **Challenge — the important part.** Proactively surface what the input left implicit:
+   - Acceptance criteria implied but not written.
+   - **Edge cases:** empty/loading/error states, pagination, permissions, concurrent edits.
+   - **Error handling:** what happens on API failure, validation failure, not-found.
+   - **Ambiguity:** vague terms ("fast", "some", "etc"), undefined entities, unclear ownership.
+   - **i18n/a11y:** user-facing strings, keyboard/screen-reader needs (this stack is i18n-first — see [[i18n-next-intl]]).
+   Put these in **Open questions** (blocking) and **Suggested additions** (proposals).
+5. **Ask** the blocking questions. Use a concise question list; offer recommended answers where you have a strong default. Don't proceed to planning with unresolved blockers.
+6. **Finalize** REQUIREMENTS once questions are answered; write/update `.claude/.planning/REQUIREMENTS.md`.
+
+## Rules
+- Never invent acceptance criteria silently — propose them under Suggested additions and confirm.
+- Acceptance criteria must be observable (a test can assert them).
+- A vague story is a signal to ask, not to guess.
+- Keep it tight: intake produces a spec, not an essay.
+
+## Related
+[[clean-architecture]] [[module-structure]] [[hook-patterns]] [[testing-jest-rtl]] [[i18n-next-intl]]

package/skills/responsive-layouts/SKILL.md

@@ -0,0 +1,64 @@
+---
+name: responsive-layouts
+description: Mobile-first responsive layout in scaffold-nextjs-app — the theme's custom breakpoints, responsive MUI sx, and the useResponsiveScreen hook. Read before building any view/component. Responsive is mandatory, not optional.
+source: scaffold-nextjs-app/src/theme.ts, src/styles/breakpoints, src/core/hooks/use-responsive-screen, src/modules/*/views
+source_version: 8edaa0b
+---
+
+# Responsive layouts
+
+Every view/component is responsive — **mandatory, mobile-first**. A design usually arrives in one viewport (a desktop Figma, one screenshot); the implementation must still work on mobile, tablet, desktop. Never ship a fixed-width layout that breaks on small screens.
+
+## The theme uses CUSTOM breakpoint names (not xs/sm/md)
+From `src/theme.ts` (values from `src/styles/breakpoints`):
+| Key | Width |
+|---|---|
+| `minMobile` | 0px |
+| `maxMobile` | 767px |
+| `minTablet` | 768px |
+| `maxTablet` | 1023px |
+| `minDesktop` | 1024px |
+| `largeScreen` | 1440px |
+| `xlargeScreen` | 2560px |
+
+Use THESE keys in MUI `sx`/breakpoint props — NOT default `xs/sm/md/lg` (the theme replaced them). `Container maxWidth` also takes these (`maxWidth="largeScreen"`).
+
+## Two responsive tools
+
+### 1. CSS-driven via `sx` (preferred — no JS, no re-render)
+```tsx
+<Box
+  display="flex"
+  sx={{
+    flexDirection: { minMobile: 'column', minTablet: 'row' },  // stack on phone, row from tablet
+    gap: { minMobile: tokens.spacing.scale2, minTablet: tokens.spacing.scale4 },
+  }}
+/>
+<Typography sx={{ fontSize: { minMobile: '1rem', minDesktop: '1.25rem' } }} />
+<Grid container columns={{ minMobile: 1, minTablet: 2, minDesktop: 3 }} />
+```
+Object syntax `{ minMobile: A, minTablet: B }` = mobile-first (value applies from that breakpoint up). Default to `sx` responsive for layout/spacing/sizing.
+
+### 2. JS-driven via `useResponsiveScreen` (when you need branching logic)
+```tsx
+import { useResponsiveScreen } from '@/core';
+const { isMobileDevice, isTabletDevice, isDesktopDevice, deviceType, isPortrait, isLandscape } = useResponsiveScreen();
+// e.g. render a Drawer on mobile vs a sidebar on desktop; change column count; swap components
+```
+Use only when CSS `sx` can't express it (different component per device, conditional rendering). Prefer `sx` first.
+
+## Rules (mandatory)
+- Every view/component works at minMobile, minTablet, minDesktop. No fixed pixel widths that overflow mobile — use `%`, `fullWidth`, flex, or breakpoint objects.
+- Mobile-first: base value = smallest screen; scale up with breakpoint keys.
+- Spacing/sizing still via `tokens.spacing.scaleN` (responsive values pick among tokens).
+- Touch targets adequate on mobile; no horizontal scroll on small screens.
+- The four states (loading/empty/error/populated) must each be responsive too.
+
+## When the design source has only ONE viewport
+This is the norm. Do NOT silently guess:
+1. Note that responsive behavior is unspecified.
+2. **Ask** the user how key elements should adapt (stack vs wrap vs hide; column counts; nav pattern) — see [[design-intake]]. Offer sensible defaults (mobile stacks columns, multi-col grids collapse, side-nav → top/drawer).
+3. Only after confirmation, implement. If the user defers, apply mobile-first defaults and flag them.
+
+## Related
+[[design-intake]] [[design-system-inventory]] [[mui-design-tokens]] [[hook-patterns]]

package/skills/selector-pattern/SKILL.md

@@ -0,0 +1,59 @@
+---
+name: selector-pattern
+description: Derived-state selector hooks that combine repository data + store state with useMemo in scaffold-nextjs-app. Read before computing derived data.
+source: scaffold-nextjs-app/docs/selector-pattern.md + src/modules/todo/selectors
+source_version: 8edaa0b
+---
+
+# Selector pattern
+
+Application layer. A selector hook computes derived/aggregated data from repository queries and/or store state, memoized. Keeps business hooks and components thin.
+
+## Shape (one dir per selector)
+
+```
+selectors/
+├── use-[name]-selector/use-[name]-selector.hook.ts
+└── index.ts   # barrel
+```
+
+## Example
+
+```ts
+// use-todo-stats-selector/use-todo-stats-selector.hook.ts
+import { useMemo } from 'react';
+import { todoRepository } from '@/modules/todo/repositories/todo';
+import type { DataSource } from '@/types/gateway.types';
+
+export interface TodoStats { total: number; completed: number; completionRate: number; /* ... */ }
+
+export const useTodoStatsSelector = (dataSource: DataSource = 'http') => {
+  const todosQuery = todoRepository.queries.useTodos({}, dataSource);
+
+  const stats = useMemo((): TodoStats => {
+    const todos = todosQuery.data ?? [];
+    const completed = todos.filter((t) => t.completed).length;
+    return {
+      total: todos.length,
+      completed,
+      completionRate: todos.length ? Math.round((completed / todos.length) * 100) : 0,
+    };
+  }, [todosQuery.data]);
+
+  return { data: stats, isLoading: todosQuery.isLoading, error: todosQuery.error, refetch: todosQuery.refetch };
+};
+```
+
+## Conventions
+- Name `useXSelector`, accept `dataSource` (default `'http'`).
+- Read source data from the **repository** (queries) and/or **store** (`useXStore`). Never fetch directly.
+- Compute in **`useMemo`** keyed on the source data.
+- Return a query-like shape: `{ data, isLoading, error, refetch }` so consumers treat selectors and repo queries uniformly.
+- Pure derivation only — no mutations, no side effects.
+
+## Rules
+- One selector = one derived concern (stats, filtered list, selected item). Compose multiple in a business hook.
+- Selectors are the place for cross-source combination (repo data + store filters), not components.
+
+## Related skills
+[[repository-pattern]] · [[store-zustand]] · [[hook-patterns]] · [[clean-architecture]]

package/skills/store-zustand/SKILL.md

@@ -0,0 +1,63 @@
+---
+name: store-zustand
+description: Module-local Zustand stores with createStoreWithMiddleware (immer + persist) and nested actions in scaffold-nextjs-app. Read before adding local state.
+source: scaffold-nextjs-app/src/modules/todo/stores, src/core/lib/zustand
+source_version: 8edaa0b
+---
+
+# Zustand stores
+
+Application layer. Local UI/domain state per module (selection, filters, transient flags). NOT server data — that's React Query's job ([[repository-pattern]]).
+
+## Files (per module)
+
+```
+stores/
+├── [module].store.ts          # store definition
+├── [module].store.actions.ts  # actions selector hook (useXActions)
+└── [module].store.types.ts    # State + StoreState types
+```
+
+## Store definition
+
+```ts
+// [module].store.ts
+import type { Draft } from 'immer';
+import { createStoreWithMiddleware } from '@/core/lib/zustand';
+import type { TodoState, TodoStoreState } from './todo.store.types';
+
+const initialState: TodoState = { selectedTodo: null, filters: {}, isCreating: false, isEditing: false };
+
+export const useTodoStore = createStoreWithMiddleware<TodoStoreState>(
+  (set, _get) => ({
+    ...initialState,
+    actions: {
+      setSelectedTodo: (todo) => set({ selectedTodo: todo }),
+      setFilters: (newFilters) =>
+        set((draft: Draft<TodoStoreState>) => { Object.assign(draft.filters, newFilters); }),  // immer
+      clearFilters: () => set({ filters: {} }),
+    },
+  }),
+  'todo-store',                                  // store name (persist key / devtools)
+  { persist: true, exclude: ['isCreating', 'isEditing'] },  // persist config
+);
+```
+
+## Conventions
+- **`createStoreWithMiddleware`** from `@/core/lib/zustand` wraps immer + persist + devtools. Never call raw `create` from `zustand`.
+- **Actions nested under `actions`** key (kept out of persisted/selected state).
+- **Immer**: object/array mutations use `set((draft) => {...})` with `Draft<T>`; simple replacements use `set({ ... })`.
+- **Third arg = store name**; **fourth = options** (`persist`, `exclude` keys from persistence).
+- Types split: `XState` (data shape) + `XStoreState` (state + `actions`) in `*.store.types.ts`.
+
+## Consuming
+- State via selector: `const filters = useTodoStore((s) => s.filters)`.
+- Actions via dedicated hook: `useTodoActions()` (in `*.store.actions.ts`) → `const { setFilters } = useTodoActions()`.
+- Derived/cross-source data → use a [[selector-pattern]] hook, not the store.
+
+## Rules
+- Store holds local state only. No fetching, no API.
+- Keep transient flags out of persistence via `exclude`.
+
+## Related skills
+[[selector-pattern]] · [[hook-patterns]] · [[clean-architecture]]