@atlashub/smartstack-cli 3.33.0 → 3.35.0

package/templates/skills/apex/references/smartstack-frontend.md

@@ -187,11 +187,38 @@ t('common:actions.save', 'Save')
 t('common:errors.network', 'Network error')
 ```
 
+### Namespace Registration (CRITICAL)
+
+> **After creating i18n JSON files, you MUST register each namespace in the i18n config.**
+> Root cause (test-apex-007): JSON files existed but namespaces were not registered → `useTranslation(['module'])` returned empty strings.
+
+In the i18n config file (`src/i18n/config.ts` or `src/i18n/index.ts`), add each new namespace:
+
+```typescript
+// Example: registering new module namespaces
+import employees from './locales/fr/employees.json';
+import projects from './locales/fr/projects.json';
+import clients from './locales/fr/clients.json';
+
+// In resources configuration:
+resources: {
+  fr: { employees, projects, clients, common, navigation },
+  en: { employees: employeesEn, projects: projectsEn, clients: clientsEn, ... },
+  // ... it, de
+}
+
+// OR with ns array:
+ns: ['common', 'navigation', 'employees', 'projects', 'clients'],
+```
+
+POST-CHECK 45 validates this. Unregistered namespaces → BLOCKING.
+
 ### Rules
 
 - **ALWAYS** provide a fallback value as 2nd argument to `t()`
 - **ALWAYS** use namespace prefix: `t('namespace:key')`
 - **ALWAYS** generate 4 language files (fr, en, it, de) with identical key structures
+- **ALWAYS** register new namespaces in i18n config file after creating JSON files
 - **NEVER** hardcode user-facing strings in JSX
 - **NEVER** use `t('key')` without namespace prefix
 
@@ -325,7 +352,7 @@ export function EntityDetailPage() {
   useEffect(() => {
     if (!visitedTabsRef.current.has(activeTab)) {
       visitedTabsRef.current.add(activeTab);
-      // Load tab-specific data here
+      // Load tab-specific data here (e.g., fetch leaves for this employee)
     }
   }, [activeTab]);
 
@@ -336,6 +363,52 @@ export function EntityDetailPage() {
 }
 ```
 
+### Tab Behavior Rules (CRITICAL)
+
+> **CRITICAL: Tabs on detail pages switch content LOCALLY — they NEVER navigate to other pages.**
+> Each tab renders its content INLINE within the same page component.
+> Sub-resource data (e.g., an employee's leaves) loads via API call filtered by the parent entity ID.
+
+**Tab state management:**
+- Tabs use `useState<TabKey>('info')` for the active tab — LOCAL React state only
+- Tab click handler: `onClick={() => setActiveTab(tabKey)}` — NEVER `navigate()`
+- Tab content: conditional rendering `{activeTab === 'tabKey' && <TabContent />}`
+- Lazy loading: `visitedTabsRef` tracks which tabs have been visited to avoid redundant API calls
+
+**Tab content for sub-resources:**
+```tsx
+// CORRECT — sub-resource data loaded INLINE within the tab
+{activeTab === 'leaves' && (
+  <div>
+    <LeaveRequestsTable employeeId={entity.id} />
+    {/* Optional "View all" link INSIDE the tab content area */}
+    <Link to={`../leaves?employee=${entity.id}`}>
+      {t('employees:tabs.viewAllLeaves', 'View all leave requests')}
+    </Link>
+  </div>
+)}
+```
+
+**FORBIDDEN tab patterns:**
+```tsx
+// FORBIDDEN — tab click handler navigates to another page
+const handleTabClick = (tab: TabKey) => {
+  setActiveTab(tab);
+  if (tab === 'leaves') navigate(`../leaves?employee=${id}`);  // ← BREAKS tab UX
+};
+
+// FORBIDDEN — tab content is empty because navigation already left the page
+{activeTab === 'info' && <div>...</div>}
+// Leaves tab: nothing renders here, user is already on another page
+```
+
+**Why this matters:**
+- Navigating away loses the detail page context (entity data, scroll position, other tab state)
+- Users expect tabs to switch content in-place, not redirect to a different page
+- The browser back button should go to the list page, not toggle between tabs
+
+**POST-CHECK 43 enforces this rule.**
+
 ---
 
 ## 3b. Form Pages Pattern (Create / Edit)

package/templates/skills/apex/references/smartstack-layers.md

@@ -51,6 +51,11 @@
 
 **BLOCKING:** `dotnet build --no-restore` MUST pass after migration.
 
+> **CRITICAL — Migration must cover ALL entities (POST-CHECK 44, 49):**
+> Create/update migration AFTER ALL entities and EF configs are registered in DbContext.
+> Verify with `dotnet ef migrations has-pending-model-changes` — must report NO pending changes.
+> If entities are added incrementally across modules, create a NEW migration for each batch.
+
 ---
 
 ## Layer 1 — Application (parallel with API)
@@ -75,10 +80,13 @@
 - **ALL services MUST inject `ICurrentUserService`** for audit trails
 - **ALL services MUST inject `ILogger<T>`** for production diagnostics
 - CQRS with MediatR
-- FluentValidation for all commands
+- FluentValidation for all commands — **MUST register validators via DI:**
+  `services.AddValidatorsFromAssemblyContaining<Create{Entity}DtoValidator>();`
+  Without DI registration, `[FromBody]` DTOs are never validated (POST-CHECK 46)
+- **Date fields in DTOs MUST use `DateOnly`**, not `string` (POST-CHECK 47). See `smartstack-api.md` DTO Type Mapping.
 - DTOs separate from domain entities
 - Service interfaces in Application, implementations in Infrastructure
-- **FORBIDDEN:** `tenantId: Guid.Empty`, `TenantId!.Value`, queries without TenantId filter, `ICurrentUser` (does not exist — use `ICurrentUserService` + `ICurrentTenantService`)
+- **FORBIDDEN:** `tenantId: Guid.Empty`, `TenantId!.Value`, queries without TenantId filter, `ICurrentUser` (does not exist — use `ICurrentUserService` + `ICurrentTenantService`), `string` type for date fields
 
 ---
 
@@ -101,6 +109,16 @@
 
 **Rules:**
 - `[RequirePermission(Permissions.{Module}.{Action})]` on EVERY endpoint
+- **NavRoute values MUST use kebab-case for ALL multi-word segments:**
+  - `[NavRoute("business.human-resources.employees")]` (CORRECT)
+  - `[NavRoute("business.humanresources.employees")]` (WRONG — missing hyphens)
+  - `[NavRoute("business.project-management.projects")]` (CORRECT)
+  - `[NavRoute("business.projectmanagement.projects")]` (WRONG)
+- Permission paths MUST use kebab-case matching NavRoute codes (e.g., `business.human-resources.employees.read`)
+- FORBIDDEN: concatenated segments like `humanresources` — must be `human-resources`
+- POST-CHECK 48 detects non-kebab-case NavRoute values. POST-CHECK 41 detects non-kebab-case permissions.
+- **FORBIDDEN:** `[Route("api/...")]` alongside `[NavRoute]` — causes 404s (POST-CHECK 50)
+- `[NavRoute]` is the ONLY route attribute needed — resolves routes from DB at startup
 - NEVER use `[Authorize]` without specific permission
 - Swagger XML documentation
 - Return DTOs, never domain entities
@@ -178,7 +196,7 @@ private static Guid GenerateDeterministicGuid(string input)
 
 | Level | Code (C#) | Route (DB) |
 |-------|-----------|-----------|
-| Application | `humanresources` | `/business/human-resources` |
+| Application | `human-resources` | `/business/human-resources` |
 | Module | `employees` | `/business/human-resources/employees` |
 | Section | `departments` | `/business/human-resources/employees/departments` |
 | Resource | `export` | `/business/human-resources/employees/departments/export` |

package/templates/skills/apex/steps/step-00-init.md

@@ -28,7 +28,7 @@ Extract flags from the raw input:
 ```
 Input: "{raw_input}"
 
-Flags to detect: -a, -x, -s, -e, -r, -pr
+Flags to detect: -a, -x, -s, -e, -r, -pr, -d {path}
 Remaining text after flag removal = {task_description}
 ```
 
@@ -41,6 +41,53 @@ save_mode: false
 economy_mode: false
 pr_mode: false
 resume_mode: false
+delegate_mode: false
+delegate_prd_path: null
+```
+
+**If `-d {path}` detected:** set `delegate_mode = true`, `delegate_prd_path = {path}`, force `auto_mode = true`, `economy_mode = true`.
+
+---
+
+## 1b. Delegate Mode Fast Path (if -d)
+
+> **When `/ralph-loop` invokes `/apex -d {prd_path}`, all context is extracted from the PRD file.**
+> Skip interactive sections (hierarchy definition, challenge questions).
+
+```
+IF delegate_mode:
+  Read prd.json from {delegate_prd_path}
+
+  Extract context:
+    {context_code}      = prd.project.context          (e.g., "business")
+    {app_name}          = prd.project.application       (e.g., "HumanResources")
+    {module_code}       = prd.project.module            (e.g., "EmployeeManagement")
+    {prd_path}          = {delegate_prd_path}
+    {feature_path}      = prd.source.feature_json_path  (if exists)
+
+  Extract sections from infrastructure tasks with _seedDataMeta:
+    Find task where _seedDataMeta.coreSeedData.navigationSections exists
+    {sections} = _seedDataMeta.coreSeedData.navigationSections[]
+    → map to: { code, label, description, route, displayOrder, navigation }
+
+  Extract entities from domain tasks:
+    {entities} = prd.tasks.filter(t => t.category == 'domain').map(t => entity name from t.description)
+
+  Extract complexity:
+    {module_complexity} = heuristic from task count:
+      <= 10 tasks → "simple-crud"
+      <= 20 tasks → "crud-rules"
+      <= 30 tasks → "crud-workflow"
+      > 30 tasks  → "complex"
+
+  Set needs:
+    {needs_seed_data}    = prd.tasks.some(t => t.category == 'seedData' || t.category == 'infrastructure')
+    {needs_migration}    = prd.tasks.some(t => t._migrationMeta != null)
+    {has_dependencies}   = prd.tasks.some(t => t.dependencies.length > 0) ? "references" : "none"
+    {key_properties}     = [] (extracted during step-01 from feature.json if available)
+
+  SKIP sections 2 (detect context), 4 (hierarchy), 5 (challenge questions)
+  Jump to section 3 (MCP verify) → then section 6 (determine needs, already set) → section 9 (summary)
 ```
 
 ---
@@ -147,6 +194,79 @@ These values are propagated to:
 
 ---
 
+## 5d. Scope Complexity Guard (BLOCKING)
+
+> **Root cause (test-apex-007):** `/apex` was invoked with 3 applications and 7 entities.
+> The model's context window saturated, causing: incomplete migrations, lost conventions,
+> missing pages, unregistered i18n, forgotten DI registrations.
+>
+> `/apex` is designed for **incremental** development (1 module at a time).
+> Multi-module projects should use `/ralph-loop` which calls `/apex -d` per module.
+
+### Scope Detection
+
+```
+entity_count = {entities}.length
+section_count = {sections}.length
+app_count = number of DISTINCT applications detected in {task_description}
+           (heuristics: "application X et application Y", "module X, module Y, module Z"
+            with different app names, "3 apps", etc.)
+
+scope_score = entity_count + (section_count * 0.5) + (app_count * 3)
+```
+
+### Guard Rules
+
+```
+IF delegate_mode (-d flag):
+  → SKIP guard (ralph-loop already handles scope per module)
+
+ELSE IF app_count > 1:
+  → BLOCKING: "Multiple applications detected ({app_count} apps, {entity_count} entities).
+     /apex handles 1 module at a time. For multi-module projects, use:
+     - /ralph-loop (automated: reads PRD, generates all modules sequentially)
+     - Multiple /apex calls (manual: one /apex per module)
+
+     To override this guard, split your request:
+       /apex -e add HR employee management
+       /apex -e add CRM client management
+       /apex -e add Project management"
+
+ELSE IF scope_score > 8:
+  → WARNING: "Large scope detected ({entity_count} entities, {section_count} sections).
+     /apex works best with ≤ 4 entities per invocation.
+     Consider splitting into smaller iterations.
+     Proceeding, but expect higher risk of omissions."
+
+  AskUserQuestion:
+    header: "Scope"
+    question: "Le périmètre est large ({entity_count} entités). Réduire le scope ou continuer ?"
+    options:
+      - label: "Continue anyway"
+        description: "Proceed with full scope (higher risk of omissions)"
+      - label: "Split into iterations"
+        description: "Focus on the first module/app, then run /apex again for the rest"
+      - label: "Use /ralph-loop"
+        description: "Switch to /ralph-loop for automated multi-module orchestration"
+
+  IF "Split" → ask user which module to focus on first, update {entities}/{sections}
+  IF "/ralph-loop" → display command to run, STOP execution
+
+ELSE:
+  → PASS (scope is manageable)
+```
+
+### Recommended Scope per /apex Invocation
+
+| Metric | Safe | Warning | Blocking |
+|--------|------|---------|----------|
+| Applications | 1 | 1 (large) | >1 |
+| Entities | 1-4 | 5-6 | >6 without -d |
+| Sections | 1-3 | 4-5 | >5 without -d |
+| Sub-resources | 0-2 | 3-4 | >4 without -d |
+
+---
+
 ## 6. Determine Needs
 
 ```

package/templates/skills/apex/steps/step-01-analyze.md

@@ -34,6 +34,43 @@ This saves ~2 minutes of Glob searches on an empty project.
 
 ---
 
+## 0b. Delegate Mode Fast Path (if delegate_mode)
+
+> **When called via `/ralph-loop -d`, PRD tasks provide pre-computed scope. Reduce exploration to verification only.**
+
+```
+IF delegate_mode:
+  Read PRD from {delegate_prd_path} (already loaded in step-00)
+
+  1. Extract entity list from domain tasks:
+     entities[] = prd.tasks.filter(category == 'domain').map(entity name from description)
+
+  2. Extract FK relationships from frontend tasks with _frontendMeta:
+     fkFields[] = _frontendMeta.fkFields[] (e.g., ["DepartmentId→Department", "CompanyId→Company"])
+
+  3. Determine tenant modes per entity:
+     IF feature.json exists at {feature_path}:
+       Read entity definitions → extract tenantMode per entity
+     ELSE:
+       Default all entities to tenantMode: "strict"
+
+  4. Read feature.json for wireframes/componentMapping if {feature_path} exists:
+     → enriches frontend generation in step-03
+
+  5. Perform LIGHTWEIGHT code exploration (verification only):
+     - Glob("**/Domain/Entities/**/{module_code}/**/*.cs") → what already exists?
+     - Glob("**/Infrastructure/Persistence/Seeding/Data/**/*SeedData*.cs") → existing seed data?
+     - Glob("src/pages/**/{module_code}/**/*.tsx") → existing pages?
+     → Only to determine create vs modify vs skip (NOT deep analysis)
+
+  6. Gap Analysis: Mark all PRD tasks as "create" unless existing code found
+
+  SKIP: Full Agent Teams exploration (section 2), challenge question follow-up
+  Jump to section 5 (Gap Analysis summary) → section 7 (Analysis Summary)
+```
+
+---
+
 ## 1. Context Sources
 
 Read available context (in order of priority):
@@ -174,6 +211,27 @@ Cross-reference with step-00 challenge responses:
 
 ---
 
+## 5b. Scope Re-Check (after exploration)
+
+> **Re-validate scope after code exploration reveals the true entity count.**
+> Step-00 guard uses the user's description (may undercount). Now we know the actual entities.
+
+```
+IF NOT delegate_mode:
+  actual_entities = count of entities marked "create" in gap analysis
+  actual_sections = count of sections marked "create"
+
+  IF actual_entities > 6:
+    WARNING: "Code exploration reveals {actual_entities} entities to create.
+     This exceeds the recommended maximum (4) for a single /apex invocation.
+     Risk: incomplete migrations, lost conventions, missing pages.
+     Consider: split into {ceil(actual_entities/4)} iterations of ~4 entities each."
+
+    AskUserQuestion: (same options as step-00 section 5d)
+```
+
+---
+
 ## 6. Analysis Validation (User Checkpoint)
 
 > **Objective:** Present findings and validate scope with the user BEFORE planning.

package/templates/skills/apex/steps/step-02-plan.md

@@ -16,6 +16,42 @@ Read `references/smartstack-layers.md` for layer execution rules and skill/MCP m
 
 ---
 
+## 0. Delegate Mode Fast Path (if delegate_mode)
+
+> **When called via `/ralph-loop -d`, PRD tasks already define the scope. Map directly to layers.**
+
+```
+IF delegate_mode:
+  Read PRD from {delegate_prd_path}
+
+  Map each PRD task to a layer based on task.category:
+    domain          → Layer 0
+    infrastructure  → Layer 0
+    application     → Layer 1
+    api             → Layer 1
+    seedData        → Layer 1
+    frontend        → Layer 2
+    test            → Layer 3
+
+  For each task:
+    file_path    = task.files_changed.created[0] (primary file)
+    action       = "create" (default for delegate mode)
+    tool         = infer from category:
+                   domain/infrastructure → MCP scaffold_extension
+                   api → /controller skill or MCP scaffold_extension
+                   seedData → MCP generate_permissions + ref core-seed-data.md
+                   frontend → /ui-components skill + MCP scaffold_api_client + MCP scaffold_routes
+                   test → MCP scaffold_tests
+    acceptance_criteria = task.acceptance_criteria
+
+  Use task._seedDataMeta, _frontendMeta, _migrationMeta for enriched context.
+
+  SKIP: User checkpoint (section 6) — auto_mode implied
+  Jump to section 5 (Estimated Commits) → NEXT STEP
+```
+
+---
+
 ## 1. Map Changes to Layers
 
 For each element identified in step-01 (create or modify), assign to a SmartStack layer:

package/templates/skills/apex/steps/step-03-execute.md

@@ -17,6 +17,8 @@ All code goes through skills (/controller, /application, /ui-components, /efcore
 - **ALWAYS** read `references/smartstack-frontend.md` — lazy loading, i18n, page structure, CSS variables
 - Read `references/smartstack-layers.md` for execution rules per layer
 - If NOT `{economy_mode}` AND Layer 1 has parallel work: read `references/agent-teams-protocol.md`
+- If `{delegate_mode}` AND seedData tasks exist: read `references/core-seed-data.md` — comprehensive seed data templates
+- If build failure during execution: read `references/error-classification.md` — error diagnosis categories A-F
 
 ---
 
@@ -42,16 +44,26 @@ For each entity:
 
 ### Migration (BLOCKING)
 
+> **CRITICAL — Migration must cover ALL entities, not just the first batch.**
+> Root cause (test-apex-007): Migration was created once for 3 entities, then 4 more entities
+> were added later without re-running migration → 4 entities had no database tables.
+> **RULE:** Create/update migration AFTER ALL entities and EF configs are registered in DbContext.
+> If entities are added incrementally, create a NEW migration for each batch.
+
 ```
-1. MCP suggest_migration → get standardized name
-2. dotnet ef migrations add {Name} --project src/{Infra}.csproj --startup-project src/{Api}.csproj -o Persistence/Migrations
-3. Cleanup corrupted EF Core artifacts:
+1. Verify ALL entities have been added as DbSet in ExtensionsDbContext
+2. Verify ALL EF configurations are registered (ApplyConfigurationsFromAssembly or individual)
+3. MCP suggest_migration → get standardized name
+4. dotnet ef migrations add {Name} --project src/{Infra}.csproj --startup-project src/{Api}.csproj -o Persistence/Migrations
+5. Cleanup corrupted EF Core artifacts:
    for d in src/*/bin?Debug; do [ -d "$d" ] && rm -rf "$d"; done
-4. dotnet ef database update (if local DB)
-5. dotnet build → MUST PASS
+6. dotnet ef database update (if local DB)
+7. dotnet build → MUST PASS
+8. Verify: dotnet ef migrations has-pending-model-changes → MUST report "No pending model changes"
 ```
 
 **BLOCKING:** If build fails after migration, fix EF configs before proceeding.
+**BLOCKING:** If `has-pending-model-changes` reports pending changes, entities are missing from the migration — create a new migration.
 
 ### Post-Layer 0 Build Gate
 
@@ -65,10 +77,66 @@ dotnet build
 
 ## Layer 1 — Application + API + Seed Data
 
+### NavRoute and Permission Kebab-Case (CRITICAL)
+
+> **ALL NavRoute segments and permission codes MUST use kebab-case for multi-word identifiers.**
+> Root cause (test-apex-007): Controllers had `[NavRoute("business.humanresources.employees")]`
+> instead of `[NavRoute("business.human-resources.employees")]`. This mismatched seed data routes
+> and permission codes, causing 404s and permission denials at runtime.
+
+**Rules:**
+- NavRoute: `business.human-resources.employees` (NEVER `business.humanresources.employees`)
+- Permissions: `business.human-resources.employees.read` (segments MATCH NavRoute exactly)
+- Seed data codes: `human-resources` (NEVER `humanresources`)
+- C# class names stay PascalCase (`HumanResourcesController`) — only route/permission strings use kebab-case
+- POST-CHECKs 41 + 48 validate this. Fix BEFORE committing.
+
+### Controller Route Attribute (BLOCKING)
+
+> **Controllers with `[NavRoute]` must NOT have `[Route]` attribute.**
+> Root cause (test-apex-007): ALL 7 controllers had BOTH `[Route("api/...")]` AND `[NavRoute("...")]`.
+> In SmartStack, `[NavRoute]` resolves routes dynamically from Navigation entities in the database at startup.
+> Having `[Route]` alongside causes route conflicts → all endpoints return 404.
+
+**Rules:**
+- `[NavRoute("context.app.module")]` is the ONLY route attribute needed on controllers
+- **FORBIDDEN:** `[Route("api/business/human-resources/employees")]` alongside `[NavRoute]`
+- **FORBIDDEN:** `[Route("api/[controller]")]` alongside `[NavRoute]`
+- If generating via MCP `scaffold_extension` with `navRoute` option → output is correct (NavRoute only)
+- If generating via `/controller` skill → verify NO `[Route]` is added
+- POST-CHECK 50 validates this. Fix BEFORE committing.
+
+### Validators DI Registration (CRITICAL)
+
+> After creating validators, they MUST be registered in DI. Without registration, `[FromBody]` DTOs are never validated.
+
+```
+In DependencyInjection.cs (or ServiceCollectionExtensions.cs):
+  services.AddValidatorsFromAssemblyContaining<Create{Entity}DtoValidator>();
+```
+
+POST-CHECK 46 validates this. If validators exist but no DI registration → BLOCKING.
+
 ### If economy_mode: Sequential execution
 
 Execute each item from the plan sequentially using skills and MCP.
 
+### Date Fields — Use DateOnly (CRITICAL)
+
+> **ALL date-only fields in DTOs MUST use `DateOnly`, NEVER `string`.**
+> Root cause (test-apex-007): WorkLog DTO had `string Date` instead of `DateOnly Date`.
+> This causes: no date validation, inconsistent date formats, parsing errors.
+
+**Type mapping for DTOs:**
+| Domain type | DTO type | Example |
+|-------------|----------|---------|
+| `DateTime` | `DateTime` | `CreatedAt`, `UpdatedAt` |
+| Date-only field | `DateOnly` | `Date`, `StartDate`, `EndDate`, `BirthDate` |
+| `string` for date | **FORBIDDEN** | Never use `string` for dates |
+| `DateTime` for date-only | **Avoid** | Use `DateOnly` when no time component needed |
+
+POST-CHECK 47 validates this. If a DTO has `string` type for a property named `*Date*` → BLOCKING.
+
 ### Code Generation (if entities have codePattern != "manual")
 
 For each entity with auto-generated code pattern (from feature.json or step-02 decisions):
@@ -92,15 +160,27 @@ Code stays in CreateDto, user provides it, validator has regex rule.
 **For frontend tasks (economy_mode):** Follow the same rules as exec-frontend above:
 - `MCP scaffold_api_client` → API client + types + React Query hook
 - `MCP scaffold_routes` with `outputFormat: 'clientRoutes'` for lazy imports
-- Pages: use `/ui-components` skill — MANDATORY for entity lists, grids, tables, dashboards
-- **Form pages: Create `EntityCreatePage.tsx` (route: `/create`) and `EntityEditPage.tsx` (route: `/:id/edit`)**
+- **INVOKE `/ui-components` skill** (read SKILL.md + ALL patterns) — MANDATORY for ALL page types
+- **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)
 - **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.
 - **ZERO modals/popups/drawers for forms — ALL forms are full pages with their own URL**
+- **TABS ON DETAIL PAGES (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".
 - **Form tests: Generate `EntityCreatePage.test.tsx` and `EntityEditPage.test.tsx` (co-located)**
 - **SECTION PERMISSIONS:** After calling `MCP generate_permissions` for the module navRoute (3 segments: `{context}.{app}.{module}`), also call it for EACH section navRoute (4 segments: `{context}.{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 COMPLETENESS:** If a section controller has sub-resource endpoints (e.g., `[HttpGet("types")]` for LeaveTypes inside LeavesController), you MUST EITHER:
+  - Create dedicated frontend pages for the sub-resource (ListPage, CreatePage, EditPage) with routes wired in App.tsx, OR
+  - 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)
 - Read `references/smartstack-frontend.md` for mandatory patterns (sections 3b + 8)
 - Generate i18n JSON files for all 4 languages (fr, en, it, de) — `src/i18n/locales/{lang}/{module}.json`
+- **I18n REGISTRATION (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.
 - All pages must follow loading → error → content pattern with CSS variables
 
 ### If NOT economy_mode: Agent Teams (parallel)
@@ -146,6 +226,12 @@ Spawn 2 teammates (Opus, full tools):
       → ZERO modals/popups/drawers/dialogs for forms
       → Back button with navigate(-1) on every form page
       → See smartstack-frontend.md section 3b for templates
+    - **TABS ON DETAIL PAGES (CRITICAL):** Tabs MUST switch content LOCALLY:
+      → Tab click handler: setActiveTab(tabKey) ONLY — NEVER navigate() to another page
+      → Tab content: render inline with {activeTab === 'tabKey' && <TabContent />}
+      → Sub-resource data: fetch via API filtered by parent ID, display in tab panel
+      → FORBIDDEN: navigate('../leaves?employee=${id}') in tab handler
+      → See smartstack-frontend.md section 3 'Tab Behavior Rules'
     - **FK FIELDS (CRITICAL):** Foreign key Guid fields (e.g., EmployeeId) MUST use EntityLookup:
       → NEVER render FK fields as `<input>` — users cannot type GUIDs
       → NEVER render FK fields as `<select>` — even with API-loaded options, `<select>` is NOT acceptable
@@ -382,6 +468,27 @@ Each file MUST contain these keys: `title`, `description`, `actions`, `labels`,
 
 ---
 
+## PRD State Update (delegate mode only)
+
+> **After completing EACH layer**, update the PRD file so `/ralph-loop` can track progress.
+
+```
+IF delegate_mode:
+  After each layer completes successfully:
+    Read {delegate_prd_path}
+    For each task executed in this layer:
+      task.status = 'completed'  (or 'failed' if errors)
+      task.completed_at = new Date().toISOString()
+      task.iteration = 1  (delegate mode = single iteration)
+      task.commit_hash = $(git rev-parse --short HEAD)
+      task.files_changed = { created: [...files created...], modified: [...files modified...] }
+      task.validation = "APEX_PASS" (or error details)
+    prd.updated_at = new Date().toISOString()
+    Write back to {delegate_prd_path}
+```
+
+---
+
 ## Commits Per Layer
 
 After each layer completes, gates pass, and builds pass: