create-rigel 0.1.0

package/templates/nextjs/QUICKSTART.md

@@ -0,0 +1,128 @@
+# QUICKSTART — Your First 30 Minutes
+
+This is an **agent-first** Next.js template. You don't scaffold or wire it by hand — you
+drive [Claude Code](https://claude.com/claude-code) through a fixed set of slash commands,
+and a gate enforces the architecture on every step. This page gets you from clone to a
+running, contract-typed app.
+
+> New here? Read in order: this file → `AGENTS.md` (navigation map) → `ARCHITECTURE.md`
+> (layer rules) → `.claude/CLAUDE.md` (the agent's standing instructions).
+
+---
+
+## 0. Prerequisites
+
+- **Node.js** (latest LTS) and **npm**
+- **Claude Code** installed — CLI (`npm i -g @anthropic-ai/claude-code`), the desktop/web
+  app, or the VS Code / JetBrains extension
+- **bash** available on PATH (Git Bash on Windows) — the hooks and the infra script run in bash
+- A backend that exposes an **`openapi.json`** spec (needed before you build features)
+
+This template ships **only** the harness (`.claude/`, `docs/`, root docs). There is no
+`package.json` yet — that's deliberate. `/infra-setup` generates the app.
+
+---
+
+## 1. Open the project in Claude Code
+
+```bash
+cd harness-nextjs
+claude            # or open the folder in the IDE extension
+```
+
+Claude reads `.claude/CLAUDE.md` automatically and follows the Session Start Checklist.
+The model is pinned to **Opus 4.8** in `.claude/settings.json`.
+
+---
+
+## 2. Run Phase 0 — infrastructure (once)
+
+```
+/infra-setup
+```
+
+This runs the deterministic scaffold (`bash .claude/scripts/infra-setup.sh`) —
+`create-next-app@latest`, all deps at latest LTS (no version pins), `shadcn/ui`, the
+directory tree, and `package.json` scripts — then Claude hand-authors the harness glue
+(`src/lib/env.ts`, `src/lib/api-client.ts`, utils, store, providers, configs, and the
+`tests/architecture/layers.test.ts` gate). Ends with a passing gate + ADR-000 committed.
+
+You now have a runnable app:
+
+```bash
+npm run dev        # http://localhost:3000
+npm run typecheck
+npm test
+```
+
+---
+
+## 3. Plan the whole product (once, before the feature loop)
+
+For a real multi-screen product, decompose it into an ordered set of specs first — don't
+free-style screen-by-screen. With the product brief and the backend's `openapi.json` in the repo:
+
+```
+/api-sync          → generate src/types/api.generated.ts from the backend openapi.json
+/write-roadmap     → brief + contract → docs/product-specs/ROADMAP.md
+                     (feature areas + personas, dependency order, a walking-skeleton first slice,
+                      and an `Implements (backend SPEC)` column so each row is gated on the
+                      backend capability being shipped)
+```
+
+This is the altitude above specs. It's a LIVING doc — re-run `/write-roadmap` when the backend
+contract grows. (Small one-off feature? Skip it and go straight to `/write-spec`.)
+
+---
+
+## 4. The feature loop (every feature, forever)
+
+```
+/write-spec        → describe the feature (roadmap-guided); output lands in docs/product-specs/draft/
+   (you review the spec and move it to docs/product-specs/ready/)
+/write-plan        → turns the READY spec into a layered execution plan
+/api-sync          → regenerate src/types/api.generated.ts from the backend openapi.json
+/build-layer       → builds the next unchecked layer, then the gate-checker runs (PASS/FAIL)
+   (repeat /build-layer until every layer is checked)
+/garbage-collect   → end-of-feature cleanup; plan moves to docs/exec-plans/completed/
+```
+
+`/build-layer` builds **one layer at a time** (types → lib → hooks → features → app →
+tests) and will not let you commit until the gate is green.
+
+---
+
+## 5. The rules the harness enforces for you
+
+You don't have to memorise these — the post-write hook and `gate-checker` catch them —
+but knowing them explains the guardrails (full list in `AGENTS.md`):
+
+- No `fetch()` in components/pages — all API calls go through `src/hooks/`
+- `src/types/api.generated.ts` is **READ ONLY** — regenerated by `/api-sync`
+- `process.env` only inside `src/lib/env.ts`
+- Access tokens live in memory (React context), never `localStorage`
+- No file > 400 lines; no `console.log` in `src/`
+- Every `'use client'` needs a `// Client: <reason>` comment
+
+---
+
+## 6. Useful agents (invoke by asking Claude)
+
+| Agent | When |
+|---|---|
+| `reviewer` | "Use the reviewer agent to review current changes" — before a PR |
+| `security-auditor` | before any auth / token / data-exposure change |
+| `perf-auditor` | before adding new routes/components (Core Web Vitals + bundle) |
+| `contract-checker` | after the OpenAPI spec changes |
+
+---
+
+## Troubleshooting
+
+- **`/infra-setup` says package.json exists** — infra runs once; it's already set up.
+- **Hook prints nothing** — it only warns on `.ts`/`.tsx` under `src/`/`app/`; that's normal.
+- **Gate fails on architecture tests** — `tests/architecture/layers.test.ts` enforces layer
+  imports; the failure message names the offending `file → import`. Fix the import direction.
+- **A skill looks out of date** — check its `Verified:` header; if stale, Claude refreshes
+  the relevant library docs via `ctx7` before following it (see the Skill Freshness Rule in
+  `.claude/CLAUDE.md`).

package/templates/nextjs/docs/PLANS.md

@@ -0,0 +1,23 @@
+# PLANS.md — Execution Plan Format
+
+## Roadmap → Specs (the altitude above plans)
+/write-roadmap creates → docs/product-specs/ROADMAP.md (brief + backend openapi.json →
+feature-area- and persona-ordered frontend specs, each gated on the backend spec it `Implements`).
+The roadmap plans the SET of specs; /write-spec then authors each one. A large feature area may
+span MULTIPLE plans — its spec's `**Plan:**` field then lists them all (e.g. PLAN-003, PLAN-007).
+
+## Lifecycle
+/write-plan creates → docs/exec-plans/active/PLAN-XXX.md [IN_PROGRESS]
+  → layers built one by one, checkboxes ticked
+  → /garbage-collect closes → docs/exec-plans/completed/ [COMPLETE]
+
+Plans are NEVER deleted. They are the project memory.
+
+## Pre-Build Requirement
+Always run /api-sync before the first /build-layer to ensure the contract is current.
+
+## Escalation Rule
+Escalate to human only when judgment is required:
+- Ambiguous acceptance criteria
+- API contract has breaking changes requiring design decisions
+- Performance budget impossible without architecture change

package/templates/nextjs/docs/QUALITY_SCORE.md

@@ -0,0 +1,27 @@
+# QUALITY_SCORE.md — Domain Health Grades
+
+Updated by /garbage-collect after every feature.
+
+## Grading Rubric
+| Grade | Meaning |
+|---|---|
+| A | All invariants met, coverage above threshold, zero known debt |
+| B | Minor issues, coverage at threshold, low-priority debt logged |
+| C | Layer violation OR coverage below threshold OR unresolved debt |
+| D | Multiple violations, significant coverage gaps |
+
+## Architecture Health
+| Check | Status |
+|---|---|
+| No cross-layer imports | — |
+| No files > 400 lines | — |
+| No process.env outside env.ts | — |
+| No console.log in src/ | — |
+| No direct fetch() in components | — |
+| api.generated.ts not manually edited | — |
+| Utils: 100% test coverage | — |
+
+## Domain Grades
+| Domain | Grade | Coverage | Last Updated | Notes |
+|---|---|---|---|---|
+| *(no domains yet)* | — | — | — | — |

package/templates/nextjs/docs/design-docs/core-beliefs.md

@@ -0,0 +1,43 @@
+# Core Beliefs — The Engineering Constitution
+
+Rules without reasons get bent under pressure.
+
+## 1. The Repo Is Reality
+If it isn't in this repository, it doesn't exist.
+**Consequence:** Every decision → ADR. Every product → ROADMAP.md. Every intent → spec. Every plan → PLAN-XXX.md.
+
+## 2. The API Contract Is the Source of Truth
+api.generated.ts is generated from the backend OpenAPI spec. Never hand-write types that duplicate it.
+**Consequence:** /api-sync runs before every feature. TypeScript errors after sync = contract drift to fix.
+
+## 3. Hooks Are the Only API Gateway
+No component or page calls fetch() directly. All API calls go through TanStack Query hooks in src/hooks/.
+**Consequence:** One place to add auth headers, one place to handle errors, one place to add retries.
+
+## 4. Enforce Mechanically, Not Aspirationally
+ESLint rules, hooks, and structural tests enforce the architecture. Docs alone do not.
+**Consequence:** Every constraint is a linter rule, a hook warning, or a failing test.
+
+## 5. Server Components Are the Default
+Every component is a Server Component unless it explicitly needs browser APIs or React hooks.
+**Consequence:** Every 'use client' directive requires a comment explaining why.
+
+## 6. Layers Protect Concerns
+Features don't call fetch(). Pages don't contain business logic. Utils don't import domain code.
+**Consequence:** ESLint import rules + structural tests enforce this mechanically.
+
+## 7. Tokens Live in Memory
+Access tokens are stored in React context only. Never localStorage, never sessionStorage.
+**Consequence:** Post-hook catches this. Tokens are wiped on page refresh by design (refresh token in httpOnly cookie handles re-auth).
+
+## 8. All Three States, Every Time
+Every component that fetches data must handle: loading, error, and empty. Silence is not acceptable.
+**Consequence:** Gate-checker scans for isPending/isError patterns on data-fetching components.
+
+## 9. Gate Before Commit — Always
+TypeScript must compile. ESLint must pass. Architecture tests must pass. Before every commit.
+**Consequence:** /push-layer runs typecheck + lint before committing. No exceptions.
+
+## 10. Technical Debt Is a High-Interest Loan
+Log debt immediately. Pay it in small daily amounts. Garbage collect after every feature.
+**Consequence:** tech-debt-tracker.md updated after every feature.

package/templates/nextjs/docs/design-docs/decisions/ADR-000-infrastructure.md

@@ -0,0 +1,72 @@
+# ADR-000 — Infrastructure & Stack Choices
+
+**Status:** ACCEPTED
+**Date:** *(fill when /infra-setup is run)*
+**Plan:** Phase 0
+
+---
+
+## Context
+Starting a new Next.js frontend project. Stack choices made here are expensive to change.
+
+---
+
+## Decisions
+
+### Framework: Next.js 16.2 + React 19.2
+- Next.js 16 is the current stable with React Compiler stable
+- App Router (not Pages Router) — RSC, streaming, better performance
+- React Compiler enabled — automatic memoisation, zero manual useMemo/useCallback
+- Turbopack as bundler — significantly faster dev server than Webpack
+- Alternatives rejected: Remix (less ecosystem), Vite SPA (no SSR/RSC benefits)
+
+### API Contract: openapi-typescript + openapi-fetch
+- openapi-typescript generates types from backend OpenAPI spec — zero runtime overhead
+- openapi-fetch: type-safe fetch client, 6kb, infers types from generated schema
+- Together: full end-to-end type safety from backend response to component props
+- Alternatives rejected: axios (no OpenAPI integration), React Query with manual types (error-prone)
+
+### Server State: TanStack Query 5
+- Industry standard for async server state management
+- Built-in caching, background refetch, optimistic updates, devtools
+- Version 5: simplified API (one object argument), smaller bundle
+- Alternatives rejected: SWR (less features), Redux RTK Query (more boilerplate)
+
+### Client State: Zustand 5
+- Minimal (~1kb), TypeScript-native, no boilerplate
+- Used ONLY for UI state that genuinely belongs on the client (sidebar, modals)
+- NOT for server data — that's in TanStack Query
+- Alternatives rejected: Redux (overkill), Jotai (less ecosystem), Context (re-render issues)
+
+### Components: shadcn/ui
+- Copy-owned model — components are in your repo, you control them
+- Built on Radix UI primitives (accessibility built-in)
+- Tailwind CSS 4 styling — no runtime CSS-in-JS
+- No upgrade hell — you own the code
+- Alternatives rejected: MUI (heavy, hard to customise), Chakra (JSX props model)
+
+### Forms: React Hook Form 7 + Zod 3
+- React Hook Form: uncontrolled, minimal re-renders, best performance
+- Zod: same validation library as backend — consistent error messages
+- @hookform/resolvers bridges them
+- Alternatives rejected: Formik (slow, too many re-renders), Yup (less TypeScript support)
+
+### Testing: Vitest 4 + Playwright + MSW 2
+- Vitest 4: 3.8x faster than Jest, native TypeScript, same Jest API
+- Playwright: E2E + visual regression in one tool, 80%+ new project adoption
+- MSW 2: intercept at network level, works in both browser and node
+- Alternatives rejected: Jest (slower), Cypress (less capable than Playwright)
+
+### Auth Token Strategy
+- Access token in React context (memory) — wiped on refresh
+- Refresh token in httpOnly cookie (set by backend) — never accessible to JS
+- On 401: call /api/auth/refresh → backend reads cookie → issues new access token
+- No localStorage/sessionStorage — XSS attack surface reduction
+
+---
+
+## Consequences
+- openapi-typescript: api.generated.ts is READ ONLY — must regenerate on backend changes
+- React Compiler: no manual useMemo/useCallback needed (but don't remove existing ones without testing)
+- Server Components: most pages are async by default — data fetching happens at render time on server
+- Zustand for UI only: if it lives in TanStack Query cache, don't duplicate in Zustand

package/templates/nextjs/docs/design-docs/decisions/index.md

@@ -0,0 +1,7 @@
+# ADR Index
+
+| ID | Title | Status | Date | Plan |
+|---|---|---|---|---|
+| ADR-000 | Infrastructure & Stack Choices | ACCEPTED | *(fill on /infra-setup)* | — |
+
+Add a row after every new ADR.

package/templates/nextjs/docs/design-docs/index.md

@@ -0,0 +1,7 @@
+# Design Docs Index
+
+| Document | Purpose |
+|---|---|
+| core-beliefs.md | Engineering constitution — WHY every rule exists |
+| decisions/index.md | ADR registry |
+| decisions/ADR-000-infrastructure.md | Stack choices and rationale |

package/templates/nextjs/docs/design-docs/team-workflow.md

@@ -0,0 +1,66 @@
+# Team Workflow — Branch Protection & Review Policy
+
+Referenced by `.github/CODEOWNERS`. This documents how the harness is operated by a
+team: branch protection, who reviews what, and the merge rules. Adjust to your org.
+
+---
+
+## Branch model
+
+- `main` is protected and always deployable. No direct pushes.
+- All work lands via pull request from a short-lived branch:
+  `feat/<scope>`, `fix/<scope>`, `chore/<scope>`.
+- One execution plan → one (or a few) PRs; one layer per commit where practical.
+
+## Branch protection rules (GitHub → Settings → Branches → `main`)
+
+Enable:
+
+- [ ] **Require a pull request before merging**
+- [ ] **Require approvals** — at least **1** (2 for security-sensitive paths)
+- [ ] **Require review from Code Owners** — activates `.github/CODEOWNERS`
+- [ ] **Require status checks to pass** → select the **CI / verify** check
+      (typecheck · lint · format · test · build) and **Lighthouse CI** for UI PRs
+- [ ] **Require branches to be up to date before merging**
+- [ ] **Require conversation resolution before merging**
+- [ ] **Do not allow bypassing the above** (applies to admins too)
+
+## Who reviews what (CODEOWNERS)
+
+| Path | Owner | Why |
+|---|---|---|
+| `*` (default) | `@your-team/engineers` | Any engineer can review ordinary changes |
+| `.claude/hooks/`, `src/lib/env.ts`, `src/lib/api-client.ts`, `src/features/auth/`, `app/api/`, `next.config.ts` | `@your-team/leads` | Security-sensitive: auth, token handling, env, headers |
+| `src/types/api.generated.ts` | `@your-team/leads` | Contract drift / accidental hand-edit (file is generated) |
+| `.github/workflows/`, `Dockerfile` | `@your-team/platform` | CI/CD and container surface |
+
+> Replace the placeholder team slugs in `CODEOWNERS` with real GitHub teams/usernames,
+> then tick "Require review from Code Owners" above. Until then they are inert.
+
+## Approve vs merge
+
+- **Approve**: any code owner for the touched paths.
+- **Merge**: the PR author after all required approvals + green checks, using
+  **Squash and merge**. The squash title must follow conventional commits
+  (`feat(scope): …`) — enforced locally by the commit-msg hook and reviewed against
+  the PR template.
+
+## Local quality gates (run before you push)
+
+The harness enforces these automatically; this is what runs and when:
+
+| When | What | How |
+|---|---|---|
+| On save (optional) | format + eslint | editor / `npm run format` |
+| On `git commit` | eslint --fix + prettier on staged files | Husky `pre-commit` → `lint-staged` |
+| On `/build-layer` | full layer gate (PASS/FAIL) | `gate-checker` agent |
+| On PR | typecheck, lint, format check, tests+coverage, build | `.github/workflows/ci.yml` |
+| On UI PR | Core Web Vitals budget | `.github/workflows/lighthouse.yml` |
+
+## Definition of done for a PR
+
+- Gate is green (`/validate-layer` passes locally).
+- CI is green.
+- PR template fully checked, including the **cross-user isolation test** for any new
+  user-owned resource.
+- An ADR exists for any non-obvious decision (`docs/design-docs/decisions/`).

package/templates/nextjs/docs/exec-plans/tech-debt-tracker.md

@@ -0,0 +1,19 @@
+# Technical Debt Tracker
+
+## Severity
+| Level | Fix by |
+|---|---|
+| P0 | Immediately — security/XSS/token exposure |
+| P1 | Within 2 sprints — blocks features or causes bugs |
+| P2 | Within quarter — degrades quality or DX |
+| P3 | When in area — code smell |
+
+## Open Debt
+| ID | Severity | Area | Description | Created By | Date |
+|---|---|---|---|---|---|
+| *(none yet)* | — | — | — | — | — |
+
+## Resolved Debt
+| ID | Description | Resolved By | Date |
+|---|---|---|---|
+| *(none yet)* | — | — | — |

package/templates/nextjs/docs/product-specs/ROADMAP.md

@@ -0,0 +1,59 @@
+# Product Roadmap (Frontend)
+
+**Product:** *(name)* · **Brief:** *(one-line, or link to the brief)* · **Last updated:** *(YYYY-MM-DD)*
+**Walking skeleton:** *(SPEC-001 — login + app shell + one auth-gated route that fetches via the generated client; build first)*
+
+> LIVING document — the altitude ABOVE specs. `/write-roadmap` writes it from the product brief
+> + the backend `openapi.json`. `/write-spec` reads it to pick the next spec (one whose
+> `Implements` backend spec is SHIPPED) and flips a row's **Spec ID** + **Status** as specs are
+> created. Update in place; never delete history.
+>
+> This is NOT a mirror of the backend roadmap — it re-decomposes the product along **frontend
+> axes** (screens, flows, personas, real-time). The OpenAPI is the *contract*, not the roadmap:
+> one screen composes many endpoints, and many endpoints have no UI.
+
+---
+
+## Feature Areas & Personas
+
+| Feature Area | Persona(s) | What the user does here |
+|---|---|---|
+| *(none yet)* | — | — |
+
+> Personas (e.g. agent / supervisor / admin) are often different surfaces over the same API.
+
+---
+
+## Spec Roadmap (dependency-ordered)
+
+| Order | Spec ID | Name | Feature Area | Implements (backend SPEC/domain) | Depends On | Skeleton | Status |
+|---|---|---|---|---|---|---|---|
+| *(none yet)* | — | — | — | — | — | — | — |
+
+> `Spec ID` is `—` until `/write-spec` creates the file and assigns the real number.
+> `Implements` = the backend spec/domain this UI consumes; a row is only **buildable** once that
+> backend spec is SHIPPED. `Depends On` references other *frontend* rows. Exactly one row is the
+> `✅ yes` skeleton, and it depends on nothing.
+
+---
+
+## Build Sequence Rationale
+
+1. *(walking skeleton — why first: proves auth + app shell + generated client + TanStack Query, and the WS client for a real-time product)*
+2. *(shared design-system / layout / real-time client — what it unblocks)*
+3. *(first persona surface, gated on its backend specs being shipped)*
+
+---
+
+## Roadmap Statuses
+
+| Status | Meaning |
+|---|---|
+| NOT_STARTED | On the roadmap, no spec file yet |
+| BLOCKED | Backend spec it `Implements` is not SHIPPED yet |
+| DRAFT | `/write-spec` wrote a SPEC-XXX (in `draft/`) |
+| READY | Spec approved — plannable |
+| PLANNED | `/write-plan` created a plan |
+| IN_PROGRESS | Being built |
+| SHIPPED | Complete and live |
+| CANCELLED | Removed from the roadmap |

package/templates/nextjs/docs/product-specs/index.md

@@ -0,0 +1,18 @@
+# Product Specs Index
+
+> Whole-product decomposition (feature areas → dependency-ordered specs, each gated on the backend
+> spec it implements) lives in [`ROADMAP.md`](ROADMAP.md). `/write-spec` fills this index per spec.
+
+| ID | Name | Status | Plan | Created |
+|---|---|---|---|---|
+| *(no specs yet)* | — | — | — | — |
+
+## Statuses
+| Status | Meaning |
+|---|---|
+| DRAFT | Written, not reviewed |
+| READY | Approved — plannable |
+| PLANNED | Plan created |
+| IN_PROGRESS | Being built |
+| SHIPPED | Complete and live |
+| CANCELLED | Not being built |

package/templates/nextjs/eslint.config.mjs

@@ -0,0 +1,150 @@
+// eslint.config.mjs — committed by the harness; OVERRIDES the create-next-app default
+// (the park-and-restore in /infra-setup restores this on top of the generated one).
+// This is what makes the layer-import matrix and the "no direct fetch / no process.env"
+// rules MECHANICAL — `npm run lint` (= `eslint .`) fails CI on a violation, instead of
+// the rules only living in prose. Mirrors .claude/rules/architecture.md.
+//
+// Uses the Next 16+ native flat-config imports (eslint-config-next/core-web-vitals),
+// NOT the legacy FlatCompat bridge — that bridge crashes against eslint-config-next 16.
+import { defineConfig, globalIgnores } from 'eslint/config'
+import nextVitals from 'eslint-config-next/core-web-vitals'
+import nextTs from 'eslint-config-next/typescript'
+import eslintConfigPrettier from 'eslint-config-prettier'
+
+// Direct fetch() is forbidden outside the hooks layer (call the API through a hook).
+const noFetch = {
+  selector: "CallExpression[callee.name='fetch']",
+  message: 'Direct fetch() is forbidden here — call the API through a hook in src/hooks/.',
+}
+// process.env is forbidden outside src/lib/ (env.ts is the single validated boundary).
+const noProcessEnv = {
+  selector: "MemberExpression[object.name='process'][property.name='env']",
+  message: 'process.env is only allowed in src/lib/ — read validated env from src/lib/env.ts.',
+}
+
+const eslintConfig = defineConfig([
+  ...nextVitals,
+  ...nextTs,
+
+  globalIgnores([
+    '.next/**',
+    'node_modules/**',
+    'coverage/**',
+    'playwright-report/**',
+    'next-env.d.ts',
+    'src/types/api.generated.ts',
+    'src/components/ui/**',
+    'tests/load/**', // k6 scripts run in the k6 runtime, not linted as app code
+  ]),
+
+  // Harness-wide rules
+  {
+    rules: {
+      'no-console': ['warn', { allow: ['warn', 'error'] }],
+    },
+  },
+
+  // The structured logger IS the sanctioned console boundary — allow all console here.
+  {
+    files: ['src/lib/logger.ts'],
+    rules: { 'no-console': 'off' },
+  },
+
+  // ── Layer import boundaries (the matrix in .claude/rules/architecture.md) ──
+  // Each block's `files` glob is a distinct directory, so no file matches two
+  // no-restricted-imports blocks (flat config REPLACES rules across blocks).
+  {
+    files: ['src/types/**/*.{ts,tsx}'],
+    rules: {
+      'no-restricted-imports': [
+        'error',
+        { patterns: ['@/lib/*', '@/hooks/*', '@/features/*', '@/store/*', '@/components/*', '@/utils/*'] },
+      ],
+    },
+  },
+  {
+    files: ['src/utils/**/*.{ts,tsx}'],
+    rules: {
+      'no-restricted-imports': [
+        'error',
+        { patterns: ['@/lib/*', '@/hooks/*', '@/features/*', '@/store/*', '@/components/*'] },
+      ],
+    },
+  },
+  {
+    files: ['src/lib/**/*.{ts,tsx}'],
+    rules: {
+      'no-restricted-imports': [
+        'error',
+        { patterns: ['@/hooks/*', '@/features/*', '@/store/*', '@/components/*'] },
+      ],
+    },
+  },
+  {
+    files: ['src/store/**/*.{ts,tsx}'],
+    rules: {
+      'no-restricted-imports': [
+        'error',
+        { patterns: ['@/lib/*', '@/hooks/*', '@/features/*', '@/components/*'] },
+      ],
+    },
+  },
+  {
+    files: ['src/hooks/**/*.{ts,tsx}'],
+    rules: {
+      'no-restricted-imports': ['error', { patterns: ['@/features/*', '@/components/*'] }],
+    },
+  },
+  {
+    files: ['src/components/**/*.{ts,tsx}'],
+    rules: {
+      'no-restricted-imports': [
+        'error',
+        { patterns: ['@/lib/*', '@/hooks/*', '@/features/*', '@/store/*'] },
+      ],
+    },
+  },
+
+  // ── App router pages/layouts: render features, never call data hooks directly ──
+  {
+    files: ['src/app/**/page.tsx', 'src/app/**/layout.tsx', 'app/**/page.tsx', 'app/**/layout.tsx'],
+    rules: { 'no-restricted-imports': ['error', { patterns: ['@/hooks/*', '@/store/*'] }] },
+  },
+
+  // ── no-restricted-syntax: fetch + process.env ──
+  // NOTE: ESLint flat config REPLACES (does not merge) a rule's value across matching
+  // config objects — last match wins. So every file that needs `no-restricted-syntax`
+  // must get ALL its selectors in a SINGLE block, or earlier selectors are lost.
+  //
+  // Render layers (features/components/app): forbid BOTH direct fetch() AND process.env.
+  {
+    files: [
+      'src/features/**/*.{ts,tsx}',
+      'src/components/**/*.{ts,tsx}',
+      'src/app/**/*.{ts,tsx}',
+      'app/**/*.{ts,tsx}',
+    ],
+    rules: { 'no-restricted-syntax': ['error', noFetch, noProcessEnv] },
+  },
+  // Non-render src layers (hooks/store/utils): forbid process.env only.
+  // (fetch isn't restricted in hooks — that's where the typed api-client lives.)
+  {
+    files: ['src/hooks/**/*.{ts,tsx}', 'src/store/**/*.{ts,tsx}', 'src/utils/**/*.{ts,tsx}'],
+    rules: { 'no-restricted-syntax': ['error', noProcessEnv] },
+  },
+
+  // ── Tests cross layers by design — relax the boundary + console rules there ──
+  {
+    files: ['tests/**/*.{ts,tsx}', 'src/**/*.test.{ts,tsx}'],
+    rules: {
+      'no-restricted-imports': 'off',
+      'no-restricted-syntax': 'off',
+      'no-console': 'off',
+    },
+  },
+
+  // Prettier LAST — disable formatting rules that fight Prettier.
+  eslintConfigPrettier,
+])
+
+export default eslintConfig