@atlashub/smartstack-cli 4.74.0 → 4.76.0

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

@@ -404,12 +404,11 @@ public static readonly Guid {ResourcePascal}ResourceId = Guid.NewGuid();
 
 ### 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., `/human-resources/employees`) — NO `/list` suffix
-> - `detail` section route = module route + `/:id` (e.g., `/human-resources/employees/:id`) — NOT `/detail/:id`
-> - Do not use: `/{module}/list`, `/{module}/detail/:id`
-> - Other sections (dashboard, approve, import) = module route + `/{section-kebab}` (normal)
+> **ROUTE CONVENTION:**
+> ALL sections use a UNIFORM route pattern: module route + `/{section-code}`.
+> - `list` section route = module route + `/list` (e.g., `/human-resources/employees/list`)
+> - `detail` section route = module route + `/:id` (e.g., `/human-resources/employees/:id`) — NOT `/detail/:id` (detail is an implicit route, not a section)
+> - Other sections (dashboard, approve, import) = module route + `/{section-kebab}` (same rule)
 
 ```csharp
 // --- Add AFTER GetTranslationEntries() in {ModulePascal}NavigationSeedData.cs ---
@@ -434,14 +433,18 @@ public static IEnumerable<NavigationSectionSeedEntry> GetSectionEntries(Guid mod
             Description = "{section1_desc_en}",
             Icon = "{section1_icon}",
             IconType = IconType.Lucide,
-            // ROUTE CONVENTION:
-            // - "list" section → same as module route (no extra segment)
-            // - "detail" section → module route + "/:id"
-            // - Other sections → module route + "/{section-kebab}"
-            // Do not use: "/employees/list", "/employees/detail/:id"
+            // ROUTE CONVENTION: ALL sections use module route + "/{section-code}" (uniform rule)
+            // - "list" section → module route + "/list" (e.g., /human-resources/employees/list)
+            // - Other sections → module route + "/{section-kebab}" (same rule)
+            // Implicit routes (detail, create, edit) are NOT sections — registered by DynamicRouter convention
             Route = "{section_route}",  // From seedDataCore.navigationSections[].route
             DisplayOrder = {section1_sort},
-            IsActive = true
+            // VISIBILITY RULE (MANDATORY):
+            // Reserved codes ("detail", "create", "edit") and codes containing "-detail"
+            // are internal route targets, NOT sidebar menu items.
+            // → IsActive = false for these codes (DynamicRouter resolves them by convention)
+            // → IsActive = true for all other sections (visible in sidebar menu)
+            IsActive = true  // Set to FALSE if section code is "detail", "create", "edit", or "*-detail"
         }
         // Repeat for each section...
     };
@@ -522,15 +525,14 @@ public static IEnumerable<NavigationResourceSeedEntry> GetResourceEntries(Guid s
         {
             // RESOURCE ROUTE CONVENTION:
             // Resources inherit their parent section's resolved route as base:
-            // - Under "list" section → base = module route (no /list)
-            // - Under "detail" section → base = module route (no /detail, resource routes don't include /:id)
+            // - Under "list" section → base = module route + /list
             // - Under other sections → base = module route + /{section-kebab}
             // Then append: /{resource-kebab}
             //
             // Example: resource "export" under section "dashboard":
             //   Route = /human-resources/employees/dashboard/export
             // Example: resource "employees-grid" under section "list":
-            //   Route = /human-resources/employees/employees-grid (NOT /employees/list/employees-grid)
+            //   Route = /human-resources/employees/list/employees-grid
             new NavigationResourceSeedEntry
             {
                 Id = {Resource1Pascal}ResourceId,
@@ -539,7 +541,7 @@ public static IEnumerable<NavigationResourceSeedEntry> GetResourceEntries(Guid s
                 Label = "{resource1_label_en}",
                 EntityType = "{resource1_entity}",
                 // Use parent section's resolved route + /{resource-kebab}
-                // For "list"/"detail" sections, the section route = module route (no /list or /detail segment)
+                // For "list" sections, route = module route + /list. "detail" is implicit (not a section).
                 Route = "{resource_route}",  // From seedDataCore: parent section route + /{resource-kebab}
                 DisplayOrder = 1
             }
@@ -591,10 +593,10 @@ public class NavigationResourceSeedEntry
 | `{section_label_xx}` | `specification.navigation.entries[]` where `level == "section"` → `labels.xx` |
 | `{section_icon}` | `seedDataCore.navigationSections[].icon` |
 | `{section_sort}` | `seedDataCore.navigationSections[].sort` |
-| `{section_route}` | `seedDataCore.navigationSections[].route` — **SPECIAL CASES:** `list` → module route (no `/list`), `detail` → module route + `/:id` (no `/detail/:id`), others → module route + `/{section-kebab}` |
+| `{section_route}` | `seedDataCore.navigationSections[].route` — ALL sections use uniform rule: module route + `/{section-code}` (`list` → module route + `/list`). `detail` is implicit (not a section): module route + `/:id`. |
 | `{resourceCode}` | `seedDataCore.navigationResources[].code` |
 | `{resource_entity}` | `seedDataCore.navigationResources[].entity` |
-| `{resource_route}` | Computed from parent section route + `/{resource-kebab}`. **SPECIAL CASES:** if parent section is `list` → module route + `/{resource-kebab}` (no `/list/`), if parent is `detail` → module route + `/{resource-kebab}` (no `/detail/`). |
+| `{resource_route}` | Computed from parent section route + `/{resource-kebab}`. For `list` parent → module route + `/list/{resource-kebab}`. For other parents → module route + `/{section-kebab}/{resource-kebab}`. |
 | `{parentSectionCode}` | `seedDataCore.navigationResources[].parentCode` |
 
 ---

package/templates/skills/apex/references/frontend-route-wiring-app-tsx.md

@@ -48,6 +48,9 @@ import './extensions/componentRegistry.generated';
 
 ## For Client SDK Pages
 
+> **CRITICAL:** Keys use DOT notation (`rh.employes.list`), NEVER hyphens (`rh-employes-list`).
+> Dots are hierarchy separators matching `NavigationService.ComponentKey` computation at runtime.
+
 Clients register their own pages directly:
 
 ```tsx

package/templates/skills/apex/references/post-checks.md

@@ -39,7 +39,7 @@ bash references/checks/infrastructure-checks.sh
 | S8 | BLOCKING | Write endpoints must NOT use Read permissions | security-checks.sh |
 | S9 | BLOCKING | FK relationships must enforce tenant isolation | security-checks.sh |
 
-### Backend — Entity, Service & Controller Checks (V1-V2, C8, C12, C14, C28-C31, C54)
+### Backend — Entity, Service & Controller Checks (V1-V2, C8, C12, C14, C28-C31, C54, C62)
 
 | ID | Severity | Description | Script |
 |----|----------|-------------|--------|
@@ -53,6 +53,7 @@ bash references/checks/infrastructure-checks.sh
 | C30 | BLOCKING | Code regex must support hyphens | backend-checks.sh |
 | C31 | WARNING | CreateDto must NOT have Code field when service uses ICodeGenerator | backend-checks.sh |
 | C54 | BLOCKING | No helper method calls inside .Select() on IQueryable | backend-checks.sh |
+| C62 | WARNING | Services must use TenantContextRequiredException for tenant check, NOT InvalidOperationException | backend-checks.sh |
 
 ### Frontend — CSS, Forms, Components, I18n (C3a, C3-C7, C9, C11, C24-C27, C36-C37, C49, C52)
 
@@ -74,6 +75,7 @@ bash references/checks/infrastructure-checks.sh
 | C37 | CRITICAL | Detail page tabs must NOT navigate() — content switches locally | frontend-checks.sh |
 | C49 | BLOCKING | Route Ordering in App.tsx — static before dynamic | frontend-checks.sh |
 | C52 | BLOCKING | Frontend route paths must include module segment | frontend-checks.sh |
+| C64 | BLOCKING | ListPages must have Create/New button (navigate to create route) | frontend-checks.sh |
 
 ### Seed Data — Navigation, Roles, Permissions (C1-C2, C10, C15-C23, C32-C35, C44-C48, C53)
 
@@ -88,7 +90,7 @@ bash references/checks/infrastructure-checks.sh
 | C18 | BLOCKING | Permissions.cs static constants must exist | seed-checks.sh |
 | C19 | BLOCKING | ApplicationRolesSeedData.cs must exist | seed-checks.sh |
 | C20 | WARNING | Section route completeness (NavigationSection → frontend route + permissions) | seed-checks.sh |
-| C21 | WARNING | FORBIDDEN route patterns — /list and /detail/:id | seed-checks.sh |
+| C21 | WARNING | FORBIDDEN route patterns — /detail/:id | seed-checks.sh |
 | C22 | WARNING | Permission path segment count (2-4 dots expected) | seed-checks.sh |
 | C23 | BLOCKING | IClientSeedDataProvider must have 4 methods with real implementation (not stubs) + DI registration | seed-checks.sh |
 | C32 | CRITICAL | Translation seed data must have idempotency guard | seed-checks.sh |
@@ -103,6 +105,7 @@ bash references/checks/infrastructure-checks.sh
 | C53 | BLOCKING | Enum serialization — JsonStringEnumConverter required | seed-checks.sh |
 | C57 | BLOCKING | SeedDataProvider Seed*Async methods must NOT be `return Task.CompletedTask` or empty body — stubs cause empty menu | seed-checks.sh |
 | C58 | BLOCKING | File paths in filesToCreate must be valid C# identifiers — no spaces, apostrophes, or accents | seed-checks.sh |
+| C63 | BLOCKING | Reserved section codes (detail/create/edit/*-detail) must NOT be seeded as menu items | seed-checks.sh |
 
 ### Architecture — Clean Architecture Layer Isolation (A1-A8)
 
@@ -117,7 +120,7 @@ bash references/checks/infrastructure-checks.sh
 | A7 | WARNING | No direct repository usage in controllers | architecture-checks.sh |
 | A8 | BLOCKING | API endpoints must match handoff apiEndpointSummary | architecture-checks.sh |
 
-### Infrastructure — Migration & Build (C13, C38-C43, C50-C51, C56)
+### Infrastructure — Migration & Build (C13, C38-C43, C50-C51, C56, C60-C61)
 
 | ID | Severity | Description | Script |
 |----|----------|-------------|--------|
@@ -131,6 +134,23 @@ bash references/checks/infrastructure-checks.sh
 | C50 | BLOCKING | NavRoute Uniqueness — no duplicate NavRoute values | infrastructure-checks.sh |
 | C51 | WARNING | NavRoute Segments vs Controller Hierarchy (depth matching) | infrastructure-checks.sh |
 | C56 | BLOCKING | Hierarchy Artifact Completeness — current run only (entities + sections) | infrastructure-checks.sh |
+| C60 | BLOCKING | Controllers must inject ISender _mediator, NOT direct business services | infrastructure-checks.sh |
+| C61 | BLOCKING | Controllers with [NavRoute] must have [Authorize] attribute | infrastructure-checks.sh |
+
+### PRD Compliance — Delegate Mode Only (PC-1 to PC-6)
+
+> **These checks run ONLY in delegate mode** (when `/apex -d` is used with companion spec files).
+> They validate that generated code matches the PRD specifications from `.ralph/` companion files.
+> Implemented in `step-04-examine.md` section 6d — no separate .sh script needed.
+
+| ID | Severity | Description | Source |
+|----|----------|-------------|--------|
+| PC-1 | BLOCKING | All columns from screens.json SmartTable resources must exist in generated ListPage | step-04 §6d |
+| PC-2 | BLOCKING | All actions from screens.json (create, edit, delete, approve, reject, export) must have handlers in pages | step-04 §6d |
+| PC-3 | WARNING | I18n labels must have correct UTF-8 accents (FR: Employés not Employes, DE: Übersicht not Ubersicht) | step-04 §6d |
+| PC-4 | BLOCKING | All permissionPaths from permissions.json must exist in PermissionsSeedData.cs and Permissions.cs | step-04 §6d |
+| PC-5 | WARNING | Every primary/functional section in screens.json must have a corresponding page file | step-04 §6d |
+| PC-6 | WARNING | Module i18n namespace must be registered in i18n config (prevents raw key display) | step-04 §6d |
 
 ---
 

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

@@ -343,10 +343,10 @@ public class {Name}Controller : ControllerBase
 | Module | `/{app-kebab}/{module-kebab}` | `/human-resources/employees` |
 | Section | `/{app-kebab}/{module-kebab}/{section-kebab}` | `/human-resources/employees/departments` |
 
-**Route special cases:** `list` and `detail` sections are view modes, NOT sub-areas:
-- `list` route = module route (e.g., `/human-resources/employees`)
-- `detail` route = module route + `/:id`
-- Do NOT use: `/employees/list`, `/employees/detail/:id`
+**Route convention:** ALL sections use uniform route = module route + `/{section-code}`:
+- `list` route = module route + `/list` (e.g., `/human-resources/employees/list`)
+- `detail` is an implicit route (not a section): module route + `/:id`
+- Do NOT use: `/employees/detail/:id` (detail is implicit)
 
 **Rules:**
 - Routes ALWAYS start with `/`, include full hierarchy, use kebab-case

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

@@ -121,24 +121,67 @@ t('employees:messages.created', '{{entity}} created', { entity: 'Employee' }) //
 t('common:actions.save', 'Save')                                              // Cross-namespace
 ```
 
-### Namespace Registration (CRITICAL — POST-CHECK C39)
+### Namespace Registration (CRITICAL — POST-CHECK C39 + GATE PG-4)
 
-After creating i18n JSON files, register each namespace in `src/i18n/config.ts`:
+After creating i18n JSON files, register each namespace in `src/i18n/config.ts` or `index.ts`:
 
 ```typescript
-import employees from './locales/fr/employees.json';
-// In resources: fr: { employees, common, navigation, ... }
-// OR in ns array: ns: ['common', 'navigation', 'employees'],
+// CORRECT — Full i18n config with module namespaces registered
+import i18n from 'i18next';
+import { initReactI18next } from 'react-i18next';
+import LanguageDetector from 'i18next-browser-languagedetector';
+
+// Import ALL module translation files for each language
+import frEmployes from './locales/fr/employes.json';
+import enEmployes from './locales/en/employes.json';
+import itEmployes from './locales/it/employes.json';
+import deEmployes from './locales/de/employes.json';
+import frAbsences from './locales/fr/absences.json';
+import enAbsences from './locales/en/absences.json';
+import itAbsences from './locales/it/absences.json';
+import deAbsences from './locales/de/absences.json';
+// ... repeat for each module
+
+i18n
+  .use(LanguageDetector)
+  .use(initReactI18next)
+  .init({
+    fallbackLng: 'fr',
+    ns: ['employes', 'absences'],  // List ALL namespaces
+    defaultNS: 'employes',
+    interpolation: { escapeValue: false },
+    resources: {
+      fr: { employes: frEmployes, absences: frAbsences },
+      en: { employes: enEmployes, absences: enAbsences },
+      it: { employes: itEmployes, absences: itAbsences },
+      de: { employes: deEmployes, absences: deAbsences },
+    },
+  });
+
+export default i18n;
 ```
 
-Root cause (test-apex-007): JSON files existed but namespaces were not registered → `useTranslation(['module'])` returned empty strings.
+```typescript
+// WRONG — Missing namespace imports (keys show as raw strings like "list.title")
+i18n.init({
+  resources: {
+    en: { translation: { welcome: 'Welcome' } },
+    fr: { translation: { welcome: 'Bienvenue' } },
+  },
+});
+// ❌ Module JSON files exist on disk but are NEVER loaded → useTranslation('employes') returns empty
+```
+
+Root cause (test-apex-007, test-ba-010): JSON files existed but namespaces were not registered → `useTranslation(['module'])` returned empty strings. All t() calls displayed raw keys like `list.title`, `form.department` instead of translated text.
 
 **Rules:**
-- Provide fallback value as 2nd argument to `t()`
+- Provide fallback value as 2nd argument to `t()`: `t('employes:list.title', 'Liste des employés')`
 - Use namespace prefix: `t('namespace:key')` — never `t('key')` without namespace
 - Generate 4 language files (fr, en, it, de) with identical key structures
 - Register new namespaces in i18n config file after creating JSON files
 - Do not hardcode user-facing strings in JSX
+- **After writing i18n JSON files:** IMMEDIATELY update i18n config with imports + resources registration
+- **Verify:** `grep -q "{namespace}" src/**/i18n/index.ts` MUST match for EVERY module namespace
 
 ---
 
@@ -213,7 +256,7 @@ const applicationRoutes: ApplicationRouteExtensions = {
 };
 ```
 
-**Section-level routes:** `list` and `detail` do NOT add path segments (handled by `index: true` and `:id`). Only other sections (dashboard, approve, import) add `{section-kebab}` child routes.
+**Section-level routes:** ALL sections add their code as path segment (`list` → `/list`, `dashboard` → `/dashboard`, `approve` → `/approve`). `detail`/`create`/`edit` are implicit routes (`/:id`, `/create`, `/:id/edit`), NOT sections.
 
 **PermissionGuard for sections:**
 ```tsx
@@ -285,9 +328,12 @@ Do NOT use: `bg-white`, `border-gray-200`, `text-gray-900`, hardcoded hex/rgb.
 - Do not use raw `<table>` — use `DataTable`
 - Do not create custom spinners — use `Loader2` from lucide-react
 - Do not import axios directly — use `@/services/api/apiClient`
+- **Do not use raw `fetch()` — use `apiClient` from `@/services/api`** (handles auth, token refresh, tenant isolation)
 - Use `PageLoader` as Suspense fallback
 - Use `EntityLookup` for FK Guid fields (not `<select>` or `<input>` for GUIDs)
 
+> **API access rule:** ALL API calls in hooks and pages MUST use `apiClient` (or the typed API service generated by MCP `scaffold_api_client`). Using raw `fetch()` bypasses authentication, token refresh, and tenant isolation — the page will fail silently when the user is logged in. This applies to custom hooks in `src/hooks/` as well as inline API calls in pages.
+
 ---
 
 ## 6. Foreign Key Fields & Entity Lookup

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

@@ -175,12 +175,12 @@ var sectionRoute = $"{moduleRoute}/{ToKebabCase(sectionCode)}";
 // → "/human-resources/employees/departments"
 ```
 
-**Route special cases (list and detail sections):**
-> `list` and `detail` are view modes of the module, NOT functional sub-areas.
-> - `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`
-> - Do not use: `/employees/list`, `/employees/detail/:id`
-> - Other sections (dashboard, approve, import) = module route + `/{section-kebab}` (normal)
+**Route convention:**
+> ALL sections use a UNIFORM route pattern: module route + `/{section-code}`.
+> - `list` section route = module route + `/list` (e.g., `/human-resources/employees/list`)
+> - `detail` is an implicit route (not a section): module route + `/:id` (e.g., `/human-resources/employees/:id`)
+> - Other sections (dashboard, approve, import) = module route + `/{section-kebab}` (same rule)
+> - Do NOT use: `/employees/detail/:id` (detail is implicit, not a section code)
 
 **Do not:**
 - Use deterministic/sequential/fixed GUIDs — always use `Guid.NewGuid()`

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

@@ -164,7 +164,7 @@ IF precision_score < 2:
   ║  Your request looks more like a discovery/design task.      ║
   ║                                                             ║
   ║  Suggestions:                                               ║
-  ║  1. Use /sketch to quickly design your module (~2 min)      ║
+  ║  1. Use /business-analyse-quick to design your module       ║
   ║  2. Use /business-analyse for full analysis (40+ questions) ║
   ║  3. Rewrite your prompt with entities and fields, e.g.:     ║
   ║     /apex add employees section with Employee entity        ║
@@ -224,6 +224,79 @@ All naming variants are derived from {app_name}, {module_code}, {sections}. Do N
 
 Call `mcp__smartstack__validate_conventions` after computing derivations. Fix any errors BEFORE step-01.
 
+### 4g. Entity-Section Mapping (DETERMINISTIC)
+
+> Each entity MUST be mapped to a hierarchy level. This determines the entity's NavRoute segment count
+> (2 vs 3 segments) and whether section-level permissions are needed.
+> **This mapping is consumed by:** step-03b (permissions), step-03c (controllers), step-04 (validation).
+
+**Rules:**
+
+1. The entity whose name derives from `{module_code}` is the **module-level entity**.
+   It gets `NavRoute = {app}.{module}` (2 segments). Its permissions are module-level.
+
+2. Every other entity that matches a section from `{sections}` is a **section-level entity**.
+   It gets `NavRoute = {app}.{module}.{section_code}` (3 segments). Its permissions are section-level.
+
+3. Entities that match NO section stay **module-level** (share the module's NavRoute).
+   This is the case for true sub-resources without their own navigation entry (e.g., InvoiceLine).
+
+**Matching algorithm:**
+
+```
+FOR EACH entity in {entities}:
+  entity_kebab = kebab(pluralize(entity.name))  // "Contact" → "contacts", "Department" → "departments"
+
+  IF entity_kebab == {module_code} OR singularize(entity_kebab) == singularize({module_code}):
+    entity.level = "module"
+    entity.navRoute = "{app_name_kebab}.{module_code}"
+    entity.section_code = null
+
+  ELSE:
+    matched = {sections}.find(s =>
+      s.code == entity_kebab                           // exact: "contacts" == "contacts"
+      OR s.code == singularize(entity_kebab)           // singular: "types" for "AbsenceType"
+      OR s.code.endsWith(entity_kebab)                 // suffix: "absence-types" ends with "types"
+      OR entity_kebab.endsWith(s.code)                 // reverse: "project-members" ends with "members"
+    )
+
+    IF matched:
+      entity.level = "section"
+      entity.navRoute = "{app_name_kebab}.{module_code}.{matched.code}"
+      entity.section_code = matched.code
+    ELSE:
+      entity.level = "module"
+      entity.navRoute = "{app_name_kebab}.{module_code}"
+      entity.section_code = null
+```
+
+**Delegate mode override:** When `permissionPaths` companion includes section-level paths
+(3+ dot segments like `app.module.section.action`), use those paths as authoritative source
+to derive entity-section mapping instead of name heuristics.
+
+**Storage:**
+
+```
+{entity_section_map}: [
+  { entity: "Employee",   level: "module",  navRoute: "rh.employes",              section_code: null },
+  { entity: "Department", level: "section", navRoute: "rh.employes.departments",  section_code: "departments" }
+]
+```
+
+Propagated to: step-03b (permissions), step-03c (controllers), step-03-execute (state), step-04 (validation).
+
+**Post-mapping validation:**
+
+```
+# No duplicate NavRoutes among section-level entities
+section_navroutes = {entity_section_map}.filter(e => e.level == "section").map(e => e.navRoute)
+IF duplicates(section_navroutes) → BLOCKING: two entities mapped to same section
+
+# All section_codes exist in {sections}
+FOR EACH entry in {entity_section_map} WHERE section_code != null:
+  IF {sections}.find(s => s.code == entry.section_code) == null → BLOCKING: orphan section_code
+```
+
 ---
 
 ## 5. Collect Technical Parameters
@@ -323,6 +396,7 @@ APEX INIT COMPLETE — v{{SMARTSTACK_VERSION}}
 Task: {task_description}
 Hierarchy: {app_name} → {module_code} → {sections[].code}
 Entities: {entities} | Complexity: {module_complexity} | Deps: {has_dependencies}
+Entity Map: {entity_section_map.map(e => `${e.entity}→${e.navRoute}`).join(', ')}
 Code: {code_patterns summary} | PRD: {prd_path||none} | Feature: {feature_path||none}
 Flags: {active_flags} | MCP: {available|degraded} | Needs: {migration/seed/workflow/notification}
 Specs: {specification_loading_plan ? 'companion files available (layer-specific loading)' : 'none'}

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

@@ -45,7 +45,7 @@ Execute all layers (Layer 0 → Layer 1 → Layer 2 → Layer 3 → Layer 4).
 ```
 BEFORE starting Layer N:
   Verify these variables are still accessible:
-    {app_name}, {module_code}, {sections}, {entities}, {code_patterns}
+    {app_name}, {module_code}, {sections}, {entities}, {code_patterns}, {entity_section_map}
     IF delegate_mode: also verify {delegate_prd_path}, {specification_loading_plan}
 
   IF any variable is missing or empty:
@@ -71,7 +71,12 @@ BEFORE starting Layer N:
        - {entities}: Glob("src/**/Domain/Entities/{module_code}/*.cs") → entity names
        - {sections}: Glob("src/**/Seeding/Data/{module_code}/*NavigationSeedData.cs") → parse
        - {code_patterns}: Read state.json or re-derive from DependencyInjection.cs
-    4. IF recovered: verify consistency with naming derivation rules (step-00 §4f)
+       - {entity_section_map}: IF state.json has it → use directly. ELSE re-derive:
+         For each entity, check controllers for [NavRoute] value:
+           Grep("\[NavRoute\(\"", "src/**/Controllers/**/{Entity}*Controller.cs")
+           → extract navRoute segments → determine level (2 seg = module, 3 seg = section)
+         Fallback: re-apply step-00 §4g matching algorithm with {entities} and {sections}
+    4. IF recovered: verify consistency with naming derivation rules (step-00 §4f, §4g)
     5. IF Layer N-1 already completed: skip to Layer N directly
 
   Cost: ~5-8 tool calls. Only triggered if context was compressed.
@@ -160,14 +165,21 @@ After each layer's build gate passes, write state to `.claude/output/apex/{task_
   "app_name": "HumanResources",
   "module_code": "employee-management",
   "sections": ["employees", "departments"],
-  "entities": ["Employee", "Department"]
+  "entities": ["Employee", "Department"],
+  "entity_section_map": [
+    { "entity": "Employee", "level": "module", "navRoute": "human-resources.employee-management", "section_code": null },
+    { "entity": "Department", "level": "section", "navRoute": "human-resources.employee-management.departments", "section_code": "departments" }
+  ]
 }
 ```
 
-> **Fields `delegate_mode`, `delegate_prd_path`, `app_name`, `module_code`, `sections`, `entities`**
+> **Fields `delegate_mode`, `delegate_prd_path`, `app_name`, `module_code`, `sections`, `entities`, `entity_section_map`**
 > are persisted so that Context Recovery Protocol (above) can restore the full execution context
 > after context compression or resume (`-r`). The `specification_loading_plan` is rebuilt from the
 > PRD file at `delegate_prd_path` — no need to serialize it directly.
+> The `entity_section_map` is critical for Layers 2-3: it determines per-entity NavRoute and
+> section-level permission generation. If lost, it can be re-derived from controller [NavRoute] attributes
+> or by re-applying step-00 §4g matching algorithm.
 
 ---
 

package/templates/skills/apex/steps/step-03b-layer1-seed.md

@@ -100,6 +100,32 @@ IF existing_seed_files is NOT EMPTY:
 
 ---
 
+### Reserved Section Code Guard (MANDATORY — runs before ANY section seeding)
+
+> **CRITICAL RULE:** Reserved section codes must NOT be seeded as menu-visible sections.
+
+```
+RESERVED_SECTION_CODES = ["detail", "create", "edit"]
+
+For each section in {sections} (from PRD or entity_section_map):
+  IF section.code IN RESERVED_SECTION_CODES OR section.code contains "-detail":
+    → Do NOT seed this section in NavigationSeedData at all
+    → "detail" is the /:id route of its parent list section (DynamicRouter convention)
+    → "create" is the /create route (DynamicRouter convention)
+    → "edit" is the /:id/edit route (DynamicRouter convention)
+    → "*-detail" (e.g., "department-detail") is the /:id route of its parent section
+    → Set permissionMode = "inherit" (no dedicated permissions)
+    → LOG: "Skipped reserved section '{section.code}' — resolved by DynamicRouter convention"
+
+  ELSE:
+    → Seed normally with IsActive = true
+
+In delegate mode (-d): PRD data may contain reserved codes that were not challenged.
+This guard catches them regardless of mode.
+```
+
+---
+
 ### Per-Module Seed Data (CREATE or UPDATE)
 
 #### If SEED_MODE = "CREATE"
@@ -113,19 +139,45 @@ Generate all files from scratch using `references/core-seed-data.md` templates:
    → If resources defined: GetResourceEntries() + resource translations
    → Query actual parent from DB for FK (NOT deterministic GUID)
 
-4. Permissions.cs
+4. Permissions.cs — MODULE-LEVEL
    → MCP generate_permissions (PRIMARY tool)
    → Static constants: public static class {Module} { public const string Read = "..."; }
    → Permission paths MUST use kebab-case matching NavRoute codes
 
-5. PermissionsSeedData.cs
+4b. Permissions.cs — SECTION-LEVEL (for each entity in {entity_section_map} where level == "section")
+   → Add nested class per section inside the module class:
+     public static class {SectionPascal} {
+       public const string View = "{navRoute}.{section_code}.read";
+       public const string Create = "{navRoute}.{section_code}.create";
+       ...
+     }
+   → Apply permissionMode inference (core-seed-data.md Step C2):
+     - section code == "detail" → inherit (SKIP — no section permissions)
+     - section code == "dashboard" → read-only (read permission only)
+     - section code == "list" or "kanban" or "calendar" or "weekly" → inherit (SKIP — view of module entity)
+     - otherwise → crud (wildcard + read + create + update + delete)
+   → Reference: core-seed-data.md lines 736-799 for full template
+
+5. PermissionsSeedData.cs — MODULE-LEVEL
    → MCP generate_permissions first, fallback template
    → Paths match Permissions.cs, wildcard + CRUD
 
-6. RolesSeedData.cs
+5b. PermissionsSeedData.cs — SECTION-LEVEL (for each entity where level == "section" AND permissionMode != "inherit")
+   → Add CreateSectionPermissions(Guid {sectionCode}SectionId) method
+   → Section-level entries: wildcard + CRUD matching Permissions.cs nested class
+   → Reference: core-seed-data.md Step C2 lines 758-779 for template
+
+6. RolesSeedData.cs — MODULE-LEVEL
    → Admin=wildcard(*), Manager=CRU, Contributor=CR, Viewer=R
    → Code-based role mapping (not deterministic GUIDs for roles)
    → Look up roles by Code at runtime
+
+6b. RolesSeedData.cs — SECTION-LEVEL (for each entity where level == "section" AND permissionMode != "inherit")
+   → Add section-level mappings in GetRolePermissionMappings():
+     Admin: section wildcard ({navRoute}.{section_code}.*)
+     Manager: read + create + update for section
+     Contributor: read + create for section
+     Viewer: read for section
 ```
 
 #### If SEED_MODE = "UPDATE"
@@ -241,9 +293,16 @@ ELSE IF Program.cs ONLY calls `MigrateAsync()` without seed data execution:
 For each section in {sections} from step-00:
   ✓ NavigationModuleSeedData has section entry + translations (4 langs)
   ✓ NavigationModuleSeedData has route: /{app}/{module}/{section}
-  ✓ Permissions.cs has constants for this section (Read/Create/Update/Delete/Wildcard)
-  ✓ PermissionsSeedData has HasData() for each permission
-  ✓ RolesSeedData maps all 4 roles to section permissions
+
+For each entity in {entity_section_map} where level == "section" AND permissionMode != "inherit":
+  ✓ Permissions.cs has SECTION-LEVEL nested class {SectionPascal} with constants
+  ✓ PermissionsSeedData has CreateSectionPermissions(Guid {section}SectionId) method
+  ✓ RolesSeedData.GetRolePermissionMappings() includes section-level role mappings
+
+Module-level (always):
+  ✓ Permissions.cs has MODULE-LEVEL constants (Read/Create/Update/Delete/Wildcard)
+  ✓ PermissionsSeedData has module-level HasData() for each permission
+  ✓ RolesSeedData maps all 4 roles to module permissions
   ✓ {App}SeedDataProvider references all seed data classes
   ✓ Program.cs executes seed data providers after MigrateAsync()
   ✓ DI registers: services.AddScoped<IClientSeedDataProvider, {App}SeedDataProvider>()