@atlashub/smartstack-cli 3.39.0 → 3.40.0

package/templates/skills/apex/references/execution-frontend-gates.md

@@ -1,177 +1,177 @@
-# Frontend Compliance Gate — 5 Mandatory Checks
-
-> **Loaded by:** step-03-execute.md (FRONTEND COMPLIANCE GATE section)
-> **Condition:** MANDATORY before any frontend commit
-> **Purpose:** Automated checks that catch the most common failures in generated code.
-
----
-
-## Gate 1: CSS Variables (Theme System)
-
-Check for hardcoded Tailwind colors — MUST use CSS variables.
-
-```bash
-ALL_PAGES=$(find src/pages/ src/components/ -name "*.tsx" 2>/dev/null | grep -v node_modules | grep -v "\.test\.")
-if [ -n "$ALL_PAGES" ]; then
-  HARDCODED=$(grep -Pn '(bg|text|border)-(?!\[)(red|blue|green|gray|white|black|slate|zinc|neutral|stone)-' $ALL_PAGES 2>/dev/null)
-  if [ -n "$HARDCODED" ]; then
-    echo "FAIL: Hardcoded Tailwind colors found — must use CSS variables"
-    echo "$HARDCODED"
-  else
-    echo "PASS: CSS variables"
-  fi
-fi
-```
-
-**If hardcoded colors found, replace BEFORE committing:**
-
-| Old | New |
-|-----|-----|
-| `bg-white` | `bg-[var(--bg-card)]` |
-| `bg-gray-50` | `bg-[var(--bg-primary)]` |
-| `text-gray-900` | `text-[var(--text-primary)]` |
-| `text-gray-500/600` | `text-[var(--text-secondary)]` |
-| `border-gray-200` | `border-[var(--border-color)]` |
-| `bg-blue-600` / `text-blue-600` | `bg-[var(--color-accent-500)]` / `text-[var(--color-accent-500)]` |
-| `hover:bg-blue-700` | `hover:bg-[var(--color-accent-600)]` |
-| `text-red-500` | `text-[var(--error-text)]` |
-| `bg-green-500` | `bg-[var(--success-bg)]` |
-
----
-
-## Gate 2: Forms as Pages (ZERO Modals/Drawers/Slide-overs)
-
-Check for modal/dialog/drawer/slide-over imports and inline form patterns — FORBIDDEN.
-
-```bash
-PAGE_FILES=$(find src/pages/ -name "*.tsx" 2>/dev/null)
-if [ -n "$PAGE_FILES" ]; then
-  FAIL=false
-
-  # 2a. Component imports
-  MODAL_IMPORTS=$(grep -Pn "import.*(?:Modal|Dialog|Drawer|Popup|Sheet|SlideOver|Overlay)" $PAGE_FILES 2>/dev/null)
-  if [ -n "$MODAL_IMPORTS" ]; then
-    echo "FAIL: Modal/Dialog/Drawer component imports — forms MUST be full pages"
-    echo "$MODAL_IMPORTS"
-    FAIL=true
-  fi
-
-  # 2b. State variables for inline forms (catches drawers/slide-overs without imports)
-  MODAL_STATE=$(grep -Pn "useState.*(?:isOpen|showModal|showDialog|showCreate|showEdit|showForm|isCreating|isEditing|showDrawer|showPanel|showSlideOver|selectedEntity|editingEntity)" $PAGE_FILES 2>/dev/null)
-  if [ -n "$MODAL_STATE" ]; then
-    echo "FAIL: Inline form state detected — forms MUST be separate page components with own routes"
-    echo "$MODAL_STATE"
-    FAIL=true
-  fi
-
-  if [ "$FAIL" = true ]; then
-    echo "Fix: Create EntityCreatePage.tsx (route: /create) and EntityEditPage.tsx (route: /:id/edit)"
-    echo "See smartstack-frontend.md section 3b"
-  else
-    echo "PASS: No modals/drawers"
-  fi
-fi
-```
-
-**If modals/drawers found:** Replace with separate `EntityCreatePage.tsx` (route: `/{module}/create`) and `EntityEditPage.tsx` (route: `/{module}/:id/edit`). See `smartstack-frontend.md` section 3b.
-
----
-
-## Gate 3: I18n File Structure
-
-Verify translation files exist as separate JSON per language.
-
-```bash
-if [ ! -d "src/i18n/locales" ]; then
-  echo "FAIL: Missing src/i18n/locales/ directory — create it with 4 languages"
-else
-  for LANG in fr en it de; do
-    JSON_FILES=$(find "src/i18n/locales/$LANG" -name "*.json" 2>/dev/null | wc -l)
-    if [ "$JSON_FILES" -eq 0 ]; then
-      echo "FAIL: No JSON files in src/i18n/locales/$LANG/"
-    else
-      echo "PASS: $LANG ($JSON_FILES files)"
-    fi
-  done
-fi
-```
-
-**If i18n structure wrong:** Create `src/i18n/locales/{fr,en,it,de}/{module}.json` following the template in `smartstack-frontend.md` section 2. NEVER embed translations in a single `.ts` file.
-
-**Correct structure:**
-```
-src/i18n/locales/
-├── fr/{module}.json    ← French (primary)
-├── en/{module}.json    ← English
-├── it/{module}.json    ← Italian
-└── de/{module}.json    ← German
-```
-
-Each file MUST contain: `title`, `description`, `actions`, `labels`, `columns`, `form`, `errors`, `validation`, `messages`, `empty`.
-
----
-
-## Gate 4: Lazy Loading
-
-Check for static page imports in route/App files.
-
-```bash
-APP_TSX=$(find src/ -name "App.tsx" -not -path "*/node_modules/*" 2>/dev/null | head -1)
-ROUTE_FILES=$(find src/routes/ -name "*.tsx" -o -name "*.ts" 2>/dev/null)
-if [ -n "$APP_TSX" ]; then
-  STATIC_IMPORTS=$(grep -Pn "^import .+ from '@/pages/" "$APP_TSX" $ROUTE_FILES 2>/dev/null)
-  if [ -n "$STATIC_IMPORTS" ]; then
-    echo "FAIL: Static page imports in App.tsx/routes — MUST use React.lazy()"
-    echo "$STATIC_IMPORTS"
-  else
-    echo "PASS: Lazy loading"
-  fi
-fi
-```
-
----
-
-## Gate 5: useTranslation in Pages
-
-Verify pages use i18n.
-
-```bash
-PAGE_FILES=$(find src/pages/ -name "*.tsx" 2>/dev/null | grep -v "\.test\." | grep -v node_modules)
-if [ -n "$PAGE_FILES" ]; then
-  TOTAL=$(echo "$PAGE_FILES" | wc -l)
-  WITH_I18N=$(grep -l "useTranslation" $PAGE_FILES 2>/dev/null | wc -l)
-  if [ "$WITH_I18N" -eq 0 ]; then
-    echo "FAIL: No pages use useTranslation — all text must be translated"
-  else
-    echo "PASS: $WITH_I18N/$TOTAL pages use useTranslation"
-  fi
-fi
-```
-
----
-
-## Explicit I18n File Creation
-
-When creating i18n files, generate EXACTLY this structure:
-
-```
-src/i18n/locales/
-├── fr/{module}.json    ← French (primary)
-├── en/{module}.json    ← English
-├── it/{module}.json    ← Italian
-└── de/{module}.json    ← German
-```
-
-Each file MUST contain these keys: `title`, `description`, `actions`, `labels`, `columns`, `form`, `errors`, `validation`, `messages`, `empty`. See `smartstack-frontend.md` section 2 for the complete JSON template.
-
----
-
-## ALL 5 Gates MUST PASS
-
-**Before creating the frontend commit:**
-1. Do NOT commit frontend changes until ALL checks pass
-2. If ANY gate fails, fix the issues first
-3. When delegating to `/ui-components` skill, include explicit instructions:
-   - "CSS: Use CSS variables ONLY — `bg-[var(--bg-card)]`, `text-[var(--text-primary)]`. NEVER use hardcoded Tailwind colors."
-   - "Forms: Create/Edit forms are FULL PAGES with own routes (e.g., `/create`, `/:id/edit`). NEVER use modals/dialogs."
-   - "I18n: ALL text must use `t('namespace:key', 'Fallback')`. Generate JSON files in `src/i18n/locales/`."
+# Frontend Compliance Gate — 5 Mandatory Checks
+
+> **Loaded by:** step-03-execute.md (FRONTEND COMPLIANCE GATE section)
+> **Condition:** MANDATORY before any frontend commit
+> **Purpose:** Automated checks that catch the most common failures in generated code.
+
+---
+
+## Gate 1: CSS Variables (Theme System)
+
+Check for hardcoded Tailwind colors — MUST use CSS variables.
+
+```bash
+ALL_PAGES=$(find src/pages/ src/components/ -name "*.tsx" 2>/dev/null | grep -v node_modules | grep -v "\.test\.")
+if [ -n "$ALL_PAGES" ]; then
+  HARDCODED=$(grep -Pn '(bg|text|border)-(?!\[)(red|blue|green|gray|white|black|slate|zinc|neutral|stone)-' $ALL_PAGES 2>/dev/null)
+  if [ -n "$HARDCODED" ]; then
+    echo "FAIL: Hardcoded Tailwind colors found — must use CSS variables"
+    echo "$HARDCODED"
+  else
+    echo "PASS: CSS variables"
+  fi
+fi
+```
+
+**If hardcoded colors found, replace BEFORE committing:**
+
+| Old | New |
+|-----|-----|
+| `bg-white` | `bg-[var(--bg-card)]` |
+| `bg-gray-50` | `bg-[var(--bg-primary)]` |
+| `text-gray-900` | `text-[var(--text-primary)]` |
+| `text-gray-500/600` | `text-[var(--text-secondary)]` |
+| `border-gray-200` | `border-[var(--border-color)]` |
+| `bg-blue-600` / `text-blue-600` | `bg-[var(--color-accent-500)]` / `text-[var(--color-accent-500)]` |
+| `hover:bg-blue-700` | `hover:bg-[var(--color-accent-600)]` |
+| `text-red-500` | `text-[var(--error-text)]` |
+| `bg-green-500` | `bg-[var(--success-bg)]` |
+
+---
+
+## Gate 2: Forms as Pages (ZERO Modals/Drawers/Slide-overs)
+
+Check for modal/dialog/drawer/slide-over imports and inline form patterns — FORBIDDEN.
+
+```bash
+PAGE_FILES=$(find src/pages/ -name "*.tsx" 2>/dev/null)
+if [ -n "$PAGE_FILES" ]; then
+  FAIL=false
+
+  # 2a. Component imports
+  MODAL_IMPORTS=$(grep -Pn "import.*(?:Modal|Dialog|Drawer|Popup|Sheet|SlideOver|Overlay)" $PAGE_FILES 2>/dev/null)
+  if [ -n "$MODAL_IMPORTS" ]; then
+    echo "FAIL: Modal/Dialog/Drawer component imports — forms MUST be full pages"
+    echo "$MODAL_IMPORTS"
+    FAIL=true
+  fi
+
+  # 2b. State variables for inline forms (catches drawers/slide-overs without imports)
+  MODAL_STATE=$(grep -Pn "useState.*(?:isOpen|showModal|showDialog|showCreate|showEdit|showForm|isCreating|isEditing|showDrawer|showPanel|showSlideOver|selectedEntity|editingEntity)" $PAGE_FILES 2>/dev/null)
+  if [ -n "$MODAL_STATE" ]; then
+    echo "FAIL: Inline form state detected — forms MUST be separate page components with own routes"
+    echo "$MODAL_STATE"
+    FAIL=true
+  fi
+
+  if [ "$FAIL" = true ]; then
+    echo "Fix: Create EntityCreatePage.tsx (route: /create) and EntityEditPage.tsx (route: /:id/edit)"
+    echo "See smartstack-frontend.md section 3b"
+  else
+    echo "PASS: No modals/drawers"
+  fi
+fi
+```
+
+**If modals/drawers found:** Replace with separate `EntityCreatePage.tsx` (route: `/{module}/create`) and `EntityEditPage.tsx` (route: `/{module}/:id/edit`). See `smartstack-frontend.md` section 3b.
+
+---
+
+## Gate 3: I18n File Structure
+
+Verify translation files exist as separate JSON per language.
+
+```bash
+if [ ! -d "src/i18n/locales" ]; then
+  echo "FAIL: Missing src/i18n/locales/ directory — create it with 4 languages"
+else
+  for LANG in fr en it de; do
+    JSON_FILES=$(find "src/i18n/locales/$LANG" -name "*.json" 2>/dev/null | wc -l)
+    if [ "$JSON_FILES" -eq 0 ]; then
+      echo "FAIL: No JSON files in src/i18n/locales/$LANG/"
+    else
+      echo "PASS: $LANG ($JSON_FILES files)"
+    fi
+  done
+fi
+```
+
+**If i18n structure wrong:** Create `src/i18n/locales/{fr,en,it,de}/{module}.json` following the template in `smartstack-frontend.md` section 2. NEVER embed translations in a single `.ts` file.
+
+**Correct structure:**
+```
+src/i18n/locales/
+├── fr/{module}.json    ← French (primary)
+├── en/{module}.json    ← English
+├── it/{module}.json    ← Italian
+└── de/{module}.json    ← German
+```
+
+Each file MUST contain: `title`, `description`, `actions`, `labels`, `columns`, `form`, `errors`, `validation`, `messages`, `empty`.
+
+---
+
+## Gate 4: Lazy Loading
+
+Check for static page imports in route/App files.
+
+```bash
+APP_TSX=$(find src/ -name "App.tsx" -not -path "*/node_modules/*" 2>/dev/null | head -1)
+ROUTE_FILES=$(find src/routes/ -name "*.tsx" -o -name "*.ts" 2>/dev/null)
+if [ -n "$APP_TSX" ]; then
+  STATIC_IMPORTS=$(grep -Pn "^import .+ from '@/pages/" "$APP_TSX" $ROUTE_FILES 2>/dev/null)
+  if [ -n "$STATIC_IMPORTS" ]; then
+    echo "FAIL: Static page imports in App.tsx/routes — MUST use React.lazy()"
+    echo "$STATIC_IMPORTS"
+  else
+    echo "PASS: Lazy loading"
+  fi
+fi
+```
+
+---
+
+## Gate 5: useTranslation in Pages
+
+Verify pages use i18n.
+
+```bash
+PAGE_FILES=$(find src/pages/ -name "*.tsx" 2>/dev/null | grep -v "\.test\." | grep -v node_modules)
+if [ -n "$PAGE_FILES" ]; then
+  TOTAL=$(echo "$PAGE_FILES" | wc -l)
+  WITH_I18N=$(grep -l "useTranslation" $PAGE_FILES 2>/dev/null | wc -l)
+  if [ "$WITH_I18N" -eq 0 ]; then
+    echo "FAIL: No pages use useTranslation — all text must be translated"
+  else
+    echo "PASS: $WITH_I18N/$TOTAL pages use useTranslation"
+  fi
+fi
+```
+
+---
+
+## Explicit I18n File Creation
+
+When creating i18n files, generate EXACTLY this structure:
+
+```
+src/i18n/locales/
+├── fr/{module}.json    ← French (primary)
+├── en/{module}.json    ← English
+├── it/{module}.json    ← Italian
+└── de/{module}.json    ← German
+```
+
+Each file MUST contain these keys: `title`, `description`, `actions`, `labels`, `columns`, `form`, `errors`, `validation`, `messages`, `empty`. See `smartstack-frontend.md` section 2 for the complete JSON template.
+
+---
+
+## ALL 5 Gates MUST PASS
+
+**Before creating the frontend commit:**
+1. Do NOT commit frontend changes until ALL checks pass
+2. If ANY gate fails, fix the issues first
+3. When delegating to `/ui-components` skill, include explicit instructions:
+   - "CSS: Use CSS variables ONLY — `bg-[var(--bg-card)]`, `text-[var(--text-primary)]`. NEVER use hardcoded Tailwind colors."
+   - "Forms: Create/Edit forms are FULL PAGES with own routes (e.g., `/create`, `/:id/edit`). NEVER use modals/dialogs."
+   - "I18n: ALL text must use `t('namespace:key', 'Fallback')`. Generate JSON files in `src/i18n/locales/`."

package/templates/skills/apex/references/execution-frontend-patterns.md

@@ -1,105 +1,105 @@
-# Frontend Patterns — Economy Mode Guidelines
-
-> **Loaded by:** step-03-execute.md (Layer 1 section: economy_mode frontend tasks)
-> **Purpose:** Quick reference for frontend creation in sequential (economy) mode.
-> **Detailed patterns:** See `smartstack-frontend.md` (referenced from smartstack-layers.md)
-
----
-
-## Frontend Tasks — Sequential Execution (economy_mode)
-
-For each frontend task in the plan (Layer 1):
-
-1. **API Client:** `MCP scaffold_api_client` → API client + types + React Query hook
-2. **Routes:** `MCP scaffold_routes` with `outputFormat: 'clientRoutes'` for lazy imports
-3. **Pages:** **INVOKE `/ui-components` skill** (read SKILL.md + ALL patterns) — MANDATORY for ALL page types
-
----
-
-## Required Page Types Per Module
-
-Create ALL 4 page types per module:
-- `ListPage.tsx` — entity list with SmartTable/EntityCard
-- `DetailPage.tsx` — entity detail view
-- `EntityCreatePage.tsx` (route: `/create`) — FULL PAGE form, NEVER modal
-- `EntityEditPage.tsx` (route: `/:id/edit`) — FULL PAGE form, NEVER modal
-
-**Wire ALL routes in App.tsx:** `index` (ListPage), `:id` (DetailPage), `create` (CreatePage), `:id/edit` (EditPage)
-
----
-
-## Foreign Key (FK) Fields — CRITICAL
-
-Any Guid FK property (e.g., EmployeeId, DepartmentId) MUST use `EntityLookup` component:
-- **NEVER** a `<select>` dropdown
-- **NEVER** a `<input type="text">`
-- **A `<select>` loaded from API state is NOT a substitute for EntityLookup**
-
-See `smartstack-frontend.md` section 6 for the full EntityLookup pattern. Backend GetAll endpoints MUST support `?search=` parameter (enables EntityLookup on frontend).
-
----
-
-## Forms: ZERO Modals/Popups/Drawers/Slide-overs
-
-**ALL forms are full pages with their own URL:**
-- Create forms: route `/{module}/create`
-- Edit forms: route `/{module}/:id/edit`
-- NEVER embed forms as drawers, panels, or slide-overs
-- Back button with `navigate(-1)` on every form page
-
----
-
-## Detail Pages: Tab Behavior (CRITICAL)
-
-**Tabs MUST switch content LOCALLY via `setActiveTab()` — NEVER `navigate()` to another page.**
-
-Sub-resource data (e.g., employee's leaves) loads inline via API call filtered by parent entity ID. See `smartstack-frontend.md` section 3 "Tab Behavior Rules".
-
----
-
-## Tests (MANDATORY)
-
-Generate form tests as co-located files:
-- `EntityCreatePage.test.tsx` (next to CreatePage.tsx)
-- `EntityEditPage.test.tsx` (next to EditPage.tsx)
-
-Cover: rendering, validation, submit, pre-fill, navigation, errors. See `smartstack-frontend.md` section 8 for test templates.
-
----
-
-## Section-Level Routes (if sections exist)
-
-**SECTION PERMISSIONS:** After calling `MCP generate_permissions` for the module navRoute (2 segments: `{app}.{module}`), also call it for EACH section navRoute (3 segments: `{app}.{module}.{section}`)
-
-**SECTION ROUTES:** After generating module routes, add section child routes to the module's `children` array. Wire `PermissionGuard` for section routes with section-level permissions.
-
----
-
-## Sub-Resource Handling
-
-If a section controller has sub-resource endpoints (e.g., `[HttpGet("types")]` for LeaveTypes inside LeavesController), you MUST EITHER:
-1. Create dedicated frontend pages for the sub-resource (ListPage, CreatePage, EditPage) with routes wired in App.tsx, OR
-2. NOT include any `navigate()` button that links to those sub-resource pages
-
-**Prefer separate controllers** with `[NavRoute(..., Suffix = "types")]` — see `smartstack-api.md` Sub-Resource Pattern. A dead link (navigate to a route with no page) is a BLOCKING issue (POST-CHECK 42).
-
----
-
-## I18n (Translations)
-
-Generate i18n JSON files for all 4 languages (fr, en, it, de):
-- Location: `src/i18n/locales/{lang}/{module}.json`
-- Keys: `actions`, `labels`, `errors`, `validation`, `columns`, `form`, `messages`, `empty`
-- ALL `t()` calls MUST use namespace prefix + fallback: `t('ns:key', 'Default text')`
-
-**CRITICAL:** After creating i18n JSON files, register EACH new namespace in the i18n config file (config.ts/index.ts/i18n.ts). Unregistered namespaces → `useTranslation(['module'])` returns empty strings at runtime. POST-CHECK 45 validates this.
-
----
-
-## Folder Structure
-
-MUST use: `src/pages/{App}/{Module}/` hierarchy (NOT flat).
-
-All pages must follow: **hooks → useEffect(load) → loading state → error state → content**
-
-Use **CSS variables ONLY** for styling — hardcoded Tailwind colors are BLOCKING (POST-CHECK 13).
+# Frontend Patterns — Economy Mode Guidelines
+
+> **Loaded by:** step-03-execute.md (Layer 1 section: economy_mode frontend tasks)
+> **Purpose:** Quick reference for frontend creation in sequential (economy) mode.
+> **Detailed patterns:** See `smartstack-frontend.md` (referenced from smartstack-layers.md)
+
+---
+
+## Frontend Tasks — Sequential Execution (economy_mode)
+
+For each frontend task in the plan (Layer 1):
+
+1. **API Client:** `MCP scaffold_api_client` → API client + types + React Query hook
+2. **Routes:** `MCP scaffold_routes` with `outputFormat: 'clientRoutes'` for lazy imports
+3. **Pages:** **INVOKE `/ui-components` skill** (read SKILL.md + ALL patterns) — MANDATORY for ALL page types
+
+---
+
+## Required Page Types Per Module
+
+Create ALL 4 page types per module:
+- `ListPage.tsx` — entity list with SmartTable/EntityCard
+- `DetailPage.tsx` — entity detail view
+- `EntityCreatePage.tsx` (route: `/create`) — FULL PAGE form, NEVER modal
+- `EntityEditPage.tsx` (route: `/:id/edit`) — FULL PAGE form, NEVER modal
+
+**Wire ALL routes in App.tsx:** `index` (ListPage), `:id` (DetailPage), `create` (CreatePage), `:id/edit` (EditPage)
+
+---
+
+## Foreign Key (FK) Fields — CRITICAL
+
+Any Guid FK property (e.g., EmployeeId, DepartmentId) MUST use `EntityLookup` component:
+- **NEVER** a `<select>` dropdown
+- **NEVER** a `<input type="text">`
+- **A `<select>` loaded from API state is NOT a substitute for EntityLookup**
+
+See `smartstack-frontend.md` section 6 for the full EntityLookup pattern. Backend GetAll endpoints MUST support `?search=` parameter (enables EntityLookup on frontend).
+
+---
+
+## Forms: ZERO Modals/Popups/Drawers/Slide-overs
+
+**ALL forms are full pages with their own URL:**
+- Create forms: route `/{module}/create`
+- Edit forms: route `/{module}/:id/edit`
+- NEVER embed forms as drawers, panels, or slide-overs
+- Back button with `navigate(-1)` on every form page
+
+---
+
+## Detail Pages: Tab Behavior (CRITICAL)
+
+**Tabs MUST switch content LOCALLY via `setActiveTab()` — NEVER `navigate()` to another page.**
+
+Sub-resource data (e.g., employee's leaves) loads inline via API call filtered by parent entity ID. See `smartstack-frontend.md` section 3 "Tab Behavior Rules".
+
+---
+
+## Tests (MANDATORY)
+
+Generate form tests as co-located files:
+- `EntityCreatePage.test.tsx` (next to CreatePage.tsx)
+- `EntityEditPage.test.tsx` (next to EditPage.tsx)
+
+Cover: rendering, validation, submit, pre-fill, navigation, errors. See `smartstack-frontend.md` section 8 for test templates.
+
+---
+
+## Section-Level Routes (if sections exist)
+
+**SECTION PERMISSIONS:** After calling `MCP generate_permissions` for the module navRoute (2 segments: `{app}.{module}`), also call it for EACH section navRoute (3 segments: `{app}.{module}.{section}`)
+
+**SECTION ROUTES:** After generating module routes, add section child routes to the module's `children` array. Wire `PermissionGuard` for section routes with section-level permissions.
+
+---
+
+## Sub-Resource Handling
+
+If a section controller has sub-resource endpoints (e.g., `[HttpGet("types")]` for LeaveTypes inside LeavesController), you MUST EITHER:
+1. Create dedicated frontend pages for the sub-resource (ListPage, CreatePage, EditPage) with routes wired in App.tsx, OR
+2. NOT include any `navigate()` button that links to those sub-resource pages
+
+**Prefer separate controllers** with `[NavRoute(..., Suffix = "types")]` — see `smartstack-api.md` Sub-Resource Pattern. A dead link (navigate to a route with no page) is a BLOCKING issue (POST-CHECK 42).
+
+---
+
+## I18n (Translations)
+
+Generate i18n JSON files for all 4 languages (fr, en, it, de):
+- Location: `src/i18n/locales/{lang}/{module}.json`
+- Keys: `actions`, `labels`, `errors`, `validation`, `columns`, `form`, `messages`, `empty`
+- ALL `t()` calls MUST use namespace prefix + fallback: `t('ns:key', 'Default text')`
+
+**CRITICAL:** After creating i18n JSON files, register EACH new namespace in the i18n config file (config.ts/index.ts/i18n.ts). Unregistered namespaces → `useTranslation(['module'])` returns empty strings at runtime. POST-CHECK 45 validates this.
+
+---
+
+## Folder Structure
+
+MUST use: `src/pages/{App}/{Module}/` hierarchy (NOT flat).
+
+All pages must follow: **hooks → useEffect(load) → loading state → error state → content**
+
+Use **CSS variables ONLY** for styling — hardcoded Tailwind colors are BLOCKING (POST-CHECK 13).