@atlashub/smartstack-cli 3.37.0 → 3.39.0

package/templates/skills/apex/references/core-seed-data.md

@@ -26,15 +26,14 @@ const permissions = coreSeedData.permissions || [];
 const rolePerms = coreSeedData.rolePermissions || [];
 
 // Derived context (from guardrail or PRD)
-const navRoute = meta.navRoute;         // e.g. "business.human-resources.projects"
-const contextCode = meta.contextCode;   // e.g. "business"
+const navRoute = meta.navRoute;         // e.g. "human-resources.projects"
 const appCode = meta.appCode;           // e.g. "human-resources"
 const moduleCode = task.module;         // e.g. "projects"
 
 // If _seedDataMeta is absent, fallback to PRD source
 if (!navRoute) {
   const prd = readJSON('.ralph/prd.json');
-  const navRoute = `${prd.source?.context || 'business'}.${prd.source?.application || prd.metadata?.module}.${task.module}`;
+  const navRoute = `${prd.source?.application || prd.metadata?.module}.${task.module}`;
 }
 ```
 
@@ -42,8 +41,7 @@ if (!navRoute) {
 
 | Variable | Example | Source |
 |----------|---------|--------|
-| `navRoute` | `business.human-resources.projects` | `_seedDataMeta.navRoute` |
-| `contextCode` | `business` | `_seedDataMeta.contextCode` |
+| `navRoute` | `human-resources.projects` | `_seedDataMeta.navRoute` |
 | `appCode` | `human-resources` | `_seedDataMeta.appCode` |
 | `moduleCode` | `projects` | `task.module` |
 | `navModules[]` | `[{code, label, icon, route, translations}]` | `coreSeedData.navigationModules` |
@@ -72,24 +70,15 @@ From `seedDataCore.navigationApplications[0]` in feature.json (generated by BA s
 | `{appLabel_xx}` | `navigationApplications[0].labels.xx` (fr, en, it, de) |
 | `{appDesc_xx}` | `navigationApplications[0].description.xx` |
 | `{appIcon}` | `navigationApplications[0].icon` |
-| `{contextCode}` | `navigationApplications[0].context` or `_seedDataMeta.contextCode` |
 
 ### GUID Generation Rule
 
-> **CRITICAL — NavigationContext IDs are NEVER generated as deterministic GUIDs.**
-> Contexts (`business`, `platform`, `personal`) are pre-seeded by SmartStack core with hardcoded GUIDs.
-> The `contextId` parameter in `GetApplicationEntry(Guid contextId)` is resolved at runtime
-> by querying `db.NavigationContexts.FirstOrDefaultAsync(c => c.Code == "business", ct)`.
-> **FORBIDDEN:** `GenerateDeterministicGuid("nav:business")` or any ContextId constant in SeedConstants.
 
 ```csharp
-// Deterministic GUID for APPLICATION (not context — contexts are pre-seeded by SmartStack core)
+// Deterministic GUID for APPLICATION
 public static readonly Guid ApplicationId =
-    GenerateDeterministicGuid("navigation-application-{contextCode}.{appCode}");
-// Example: GenerateDeterministicGuid("navigation-application-business.human-resources")
-//
-// FORBIDDEN — Context IDs must NOT be generated:
-// public static readonly Guid BusinessContextId = GenerateDeterministicGuid("nav:business"); // WRONG!
+    GenerateDeterministicGuid("navigation-application-{appCode}");
+// Example: GenerateDeterministicGuid("navigation-application-human-resources")
 ```
 
 ### Template
@@ -108,23 +97,22 @@ public static class NavigationApplicationSeedData
 {
     // Deterministic GUID for this application
     public static readonly Guid ApplicationId =
-        GenerateDeterministicGuid("navigation-application-{contextCode}.{appCode}");
+        GenerateDeterministicGuid("navigation-application-{appCode}");
 
     /// <summary>
     /// Returns navigation application entry for seeding into core.nav_Applications.
     /// </summary>
-    public static NavigationApplicationSeedEntry GetApplicationEntry(Guid contextId)
+    public static NavigationApplicationSeedEntry GetApplicationEntry()
     {
         return new NavigationApplicationSeedEntry
         {
             Id = ApplicationId,
-            ContextId = contextId,
             Code = "{appCode}",
             Label = "{appLabel_en}",
             Description = "{appDesc_en}",
             Icon = "{appIcon}",              // Lucide React icon name
             IconType = IconType.Lucide,
-            Route = ToKebabCase("/{contextCode}/{appCode}"),
+            Route = ToKebabCase("/{appCode}"),
             DisplayOrder = 1,
             IsActive = true
         };
@@ -212,7 +200,6 @@ public static class NavigationApplicationSeedData
 public class NavigationApplicationSeedEntry
 {
     public Guid Id { get; init; }
-    public Guid ContextId { get; init; }
     public string Code { get; init; } = null!;
     public string Label { get; init; } = null!;
     public string? Description { get; init; }
@@ -245,7 +232,7 @@ private static Guid GenerateDeterministicGuid(string seed)
 
 // Usage: GUIDs are derived from the navigation path
 public static readonly Guid ModuleId = GenerateDeterministicGuid("navigation-module-{navRoute}");
-// Example: GenerateDeterministicGuid("navigation-module-business.human-resources.projects")
+// Example: GenerateDeterministicGuid("navigation-module-human-resources.projects")
 ```
 
 ### Template
@@ -279,7 +266,7 @@ public static class {ModulePascal}NavigationSeedData
             Description = "{desc_en}",
             Icon = "{icon}",              // Lucide React icon name
             IconType = IconType.Lucide,
-            Route = ToKebabCase($"/{contextCode}/{appCode}/{moduleCode}"),
+            Route = ToKebabCase($"/{appCode}/{moduleCode}"),
             DisplayOrder = {displayOrder},
             IsActive = true
         };
@@ -337,7 +324,7 @@ public static class {ModulePascal}NavigationSeedData
 
     /// <summary>
     /// Converts PascalCase route segments to kebab-case for web URLs.
-    /// Example: /business/HumanResources/TimeManagement → /business/human-resources/time-management
+    /// Example: /HumanResources/TimeManagement → /human-resources/time-management
     /// </summary>
     private static string ToKebabCase(string route)
     {
@@ -406,20 +393,20 @@ public class NavigationTranslationSeedEntry
 // Section GUID: deterministic from navRoute + section code
 public static readonly Guid {SectionPascal}SectionId =
     GenerateDeterministicGuid("navigation-section-{navRoute}.{sectionCode}");
-// Example: GenerateDeterministicGuid("navigation-section-business.human-resources.employees.list")
+// Example: GenerateDeterministicGuid("navigation-section-human-resources.employees.list")
 
 // Resource GUID: deterministic from navRoute + section code + resource code
 public static readonly Guid {ResourcePascal}ResourceId =
     GenerateDeterministicGuid("navigation-resource-{navRoute}.{sectionCode}.{resourceCode}");
-// Example: GenerateDeterministicGuid("navigation-resource-business.human-resources.employees.list.employees-grid")
+// Example: GenerateDeterministicGuid("navigation-resource-human-resources.employees.list.employees-grid")
 ```
 
 ### Section Methods (add to {ModulePascal}NavigationSeedData.cs)
 
 > **ROUTE SPECIAL CASES (list and detail):**
 > The `list` and `detail` sections are view modes of the module, NOT functional sub-areas.
-> - `list` section route = module route (e.g., `/business/human-resources/employees`) — NO `/list` suffix
-> - `detail` section route = module route + `/:id` (e.g., `/business/human-resources/employees/:id`) — NOT `/detail/:id`
+> - `list` section route = module route (e.g., `/human-resources/employees`) — NO `/list` suffix
+> - `detail` section route = module route + `/:id` (e.g., `/human-resources/employees/:id`) — NOT `/detail/:id`
 > - FORBIDDEN: `/{module}/list`, `/{module}/detail/:id`
 > - Other sections (dashboard, approve, import) = module route + `/{section-kebab}` (normal)
 
@@ -542,9 +529,9 @@ public static IEnumerable<NavigationResourceSeedEntry> GetResourceEntries(Guid s
             // Then append: /{resource-kebab}
             //
             // Example: resource "export" under section "dashboard":
-            //   Route = /business/human-resources/employees/dashboard/export
+            //   Route = /human-resources/employees/dashboard/export
             // Example: resource "employees-grid" under section "list":
-            //   Route = /business/human-resources/employees/employees-grid (NOT /employees/list/employees-grid)
+            //   Route = /human-resources/employees/employees-grid (NOT /employees/list/employees-grid)
             new NavigationResourceSeedEntry
             {
                 Id = {Resource1Pascal}ResourceId,
@@ -678,22 +665,20 @@ MCP returns:
 ### Step B: Write Permissions.cs (Application layer)
 
 > **CRITICAL — Permission paths use the SAME kebab-case as NavRoute codes.**
-> `{navRoute}` is already kebab-case (e.g., `business.human-resources.employees`).
+> `{navRoute}` is already kebab-case (e.g., `human-resources.employees`).
 > NEVER strip hyphens or derive codes from C# class names.
-> FORBIDDEN: `business.humanresources.employees.read` → CORRECT: `business.human-resources.employees.read`
-> SmartStack.app reference: `business.support-client.my-tickets.read`
+> FORBIDDEN: `humanresources.employees.read` → CORRECT: `human-resources.employees.read`
+> SmartStack.app reference: `support-client.my-tickets.read`
 
 ```csharp
 // Add to Application/Common/Authorization/Permissions.cs
-// IMPORTANT: {navRoute} uses kebab-case segments (e.g., "business.human-resources.employees")
+// IMPORTANT: {navRoute} uses kebab-case segments (e.g., "human-resources.employees")
 // Do NOT derive permission codes from C# identifiers — use navRoute directly
-public static class {ContextPascal}
+public static class {AppPascal}
 {
-    public const string Access = "{contextCode}.{appCode}";
-
     public static class {ModulePascal}
     {
-        public const string View = "{navRoute}.read";       // e.g., "business.human-resources.employees.read"
+        public const string View = "{navRoute}.read";       // e.g., "human-resources.employees.read"
         public const string Create = "{navRoute}.create";
         public const string Update = "{navRoute}.update";
         public const string Delete = "{navRoute}.delete";
@@ -949,11 +934,9 @@ public class ApplicationRoleSeedEntry
 
 ### Context-Based Role Mapping
 
-| Context | Admin | Manager | Contributor | Viewer |
-|---------|-------|---------|-------------|--------|
-| `platform.*` | CRUD | CRU | CR | R |
-| `business.*` | CRUD | CRU | CR | R |
-| `personal.*` | CRUD | CRU | CR | R |
+| Application | Admin | Manager | Contributor | Viewer |
+|-------------|-------|---------|-------------|--------|
+| Any | CRUD | CRU | CR | R |
 
 ### Template
 
@@ -1059,7 +1042,7 @@ public class {AppPascalName}SeedDataProvider : IClientSeedDataProvider
         // NOTE: Idempotence is at MODULE level (not application level).
         // If the application already exists, we load it and continue to seed any missing modules.
         // This allows adding Module 2+ to an existing application without re-running the full seed.
-        var appEntry = NavigationApplicationSeedData.GetApplicationEntry(Guid.Empty); // contextId resolved below
+        var appEntry = NavigationApplicationSeedData.GetApplicationEntry();
         var existingApp = await context.NavigationApplications
             .FirstOrDefaultAsync(a => a.Code == appEntry.Code, ct);
 
@@ -1070,13 +1053,8 @@ public class {AppPascalName}SeedDataProvider : IClientSeedDataProvider
         }
         else
         {
-            var parentContext = await context.NavigationContexts
-                .FirstAsync(c => c.Code == "{contextCode}", ct);
-
-            // Re-get entry with resolved contextId
-            appEntry = NavigationApplicationSeedData.GetApplicationEntry(parentContext.Id);
             app = NavigationApplication.Create(
-                appEntry.ContextId, appEntry.Code, appEntry.Label,
+                appEntry.Code, appEntry.Label,
                 appEntry.Description, appEntry.Icon, appEntry.IconType,
                 appEntry.Route, appEntry.DisplayOrder);
             context.NavigationApplications.Add(app);
@@ -1218,12 +1196,12 @@ public class {AppPascalName}SeedDataProvider : IClientSeedDataProvider
     public async Task SeedPermissionsAsync(ICoreDbContext context, CancellationToken ct)
     {
         var exists = await context.Permissions
-            .AnyAsync(p => p.Path == "{contextCode}.{appCode}.*", ct);
+            .AnyAsync(p => p.Path == "{appCode}.*", ct);
         if (exists) return;
 
         // Application-level wildcard
         var appWildcard = Permission.CreateWildcard(
-            "{contextCode}.{appCode}.*", PermissionLevel.Application,
+            "{appCode}.*", PermissionLevel.Application,
             "Full {appLabel_en} access");
         context.Permissions.Add(appWildcard);
 
@@ -1245,7 +1223,7 @@ public class {AppPascalName}SeedDataProvider : IClientSeedDataProvider
     public async Task SeedRolePermissionsAsync(ICoreDbContext context, CancellationToken ct)
     {
         var exists = await context.RolePermissions
-            .AnyAsync(rp => rp.Permission!.Path.StartsWith("{contextCode}.{appCode}."), ct);
+            .AnyAsync(rp => rp.Permission!.Path.StartsWith("{appCode}."), ct);
         if (exists) return;
 
         // CRITICAL: Resolve roles by Code from DB — NEVER use deterministic GUIDs.
@@ -1258,7 +1236,7 @@ public class {AppPascalName}SeedDataProvider : IClientSeedDataProvider
 
         // Resolve permissions
         var permissions = await context.Permissions
-            .Where(p => p.Path.StartsWith("{contextCode}.{appCode}."))
+            .Where(p => p.Path.StartsWith("{appCode}."))
             .ToListAsync(ct);
 
         // Apply role-permission mappings from all modules
@@ -1349,9 +1327,8 @@ Before marking the task as completed, verify ALL:
 
 **Application-Level (FIRST — before modules):**
 - [ ] `NavigationApplicationSeedData.cs` created (once per application, at `Infrastructure/Persistence/Seeding/Data/`)
-- [ ] Application GUID is deterministic (SHA256 of `"navigation-application-{contextCode}.{appCode}"`)
-- [ ] **NO ContextId constant in SeedConstants** — Context IDs are pre-seeded by SmartStack core (hardcoded GUIDs, NOT deterministic)
-- [ ] **SeedDataProvider queries context by code at runtime:** `db.NavigationContexts.FirstOrDefaultAsync(c => c.Code == "{contextCode}", ct)`
+- [ ] Application GUID is deterministic (SHA256 of `"navigation-application-{appCode}"`)
+- [ ] GetApplicationEntry() takes no parameters (no contextId)
 - [ ] Application translations created (4 languages: fr, en, it, de, EntityType = Application)
 - [ ] `IClientSeedDataProvider.SeedNavigationAsync()` uses `NavigationApplicationSeedData` (NO hardcoded `{appLabel_en}` / `{appIcon}` placeholders)
 - [ ] `ApplicationRolesSeedData.ApplicationId` references `NavigationApplicationSeedData.ApplicationId` (NO `{ApplicationGuid}` placeholder)

package/templates/skills/apex/references/examine-build-validation.md

@@ -0,0 +1,82 @@
+# Examine Build & Migration Validation
+
+> **Loaded by:** step-04-examine.md (sections 4-5)
+> **Purpose:** Build verification, migration validation, database testing procedures.
+
+---
+
+## Build Verification
+
+```bash
+# Backend
+dotnet clean && dotnet restore && dotnet build
+# Note: WSL bin\Debug cleanup handled by PostToolUse hook (wsl-dotnet-cleanup.sh)
+
+# Frontend (if applicable)
+npm run typecheck
+```
+
+**BLOCKING:** Both must pass. If failure, classify error per `references/error-classification.md`:
+- Category A (missing package) → `dotnet add package` → rebuild
+- Category B (assembly conflict) → resolve version → rebuild
+- Category C (DI missing) → fix DI registration → rebuild
+- Category D (migration broken) → fix migration → rebuild
+- Category E (config) → fix config → rebuild
+- Category F (source code) → fix code → rebuild
+
+---
+
+## Migration Validation (if needs_migration)
+
+### Pending Model Changes Check
+
+```bash
+INFRA_PROJECT=$(ls src/*Infrastructure*/*.csproj 2>/dev/null | head -1)
+API_PROJECT=$(ls src/*Api*/*.csproj 2>/dev/null | head -1)
+
+dotnet ef migrations has-pending-model-changes \
+  --project "$INFRA_PROJECT" \
+  --startup-project "$API_PROJECT"
+```
+
+**BLOCKING** if pending changes detected → migration is missing.
+
+### Migration Application Test (SQL Server LocalDB)
+
+```bash
+DB_NAME="SmartStack_Apex_Examine_$(date +%s)"
+CONN_STRING="Server=(localdb)\\MSSQLLocalDB;Database=$DB_NAME;Integrated Security=true;TrustServerCertificate=true;Connect Timeout=120;"
+
+dotnet ef database update \
+  --connection "$CONN_STRING" \
+  --project "$INFRA_PROJECT" \
+  --startup-project "$API_PROJECT"
+```
+
+**BLOCKING** if migration fails on SQL Server. Common issues:
+- SQLite-only syntax in migrations (fix: regenerate migration)
+- Column type mismatches (fix: update EF configuration)
+- Missing foreign key targets (fix: reorder migrations)
+
+### Integration Tests on Real SQL Server
+
+```bash
+# Integration tests use DatabaseFixture → real SQL Server LocalDB
+# This validates: LINQ→SQL, multi-tenant isolation, soft delete, EF configs
+INT_TEST_PROJECT=$(ls tests/*Tests.Integration*/*.csproj 2>/dev/null | head -1)
+if [ -n "$INT_TEST_PROJECT" ]; then
+  dotnet test "$INT_TEST_PROJECT" --no-build --verbosity normal
+fi
+```
+
+Tests running against SQL Server catch issues that SQLite misses:
+- Case sensitivity in string comparisons
+- Date/time function differences
+- IDENTITY vs AUTOINCREMENT behavior
+- Global query filter translation to T-SQL
+
+### Cleanup
+
+```bash
+sqlcmd -S "(localdb)\MSSQLLocalDB" -Q "IF DB_ID('$DB_NAME') IS NOT NULL BEGIN ALTER DATABASE [$DB_NAME] SET SINGLE_USER WITH ROLLBACK IMMEDIATE; DROP DATABASE [$DB_NAME]; END" 2>/dev/null
+```

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

@@ -0,0 +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/`."

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

@@ -0,0 +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).