@atlashub/smartstack-cli 3.28.0 → 3.29.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@atlashub/smartstack-cli",
-  "version": "3.28.0",
+  "version": "3.29.0",
   "description": "SmartStack Claude Code automation toolkit - GitFlow, EF Core migrations, prompts and more",
   "author": {
     "name": "SmartStack",
@@ -111,6 +111,5 @@
     "tsup": "^8.0.1",
     "typescript": "^5.3.3",
     "vitest": "^2.1.0"
-  },
-  "optionalDependencies": {}
+  }
 }

package/templates/project/api.ts.template

@@ -1,10 +1,12 @@
 // Re-export SmartStack's shared API client
 // IMPORTANT: Do NOT create a custom axios instance — use the SmartStack-provided client
 // which handles authentication, token refresh, and session management automatically.
-import { apiClient } from '@atlashub/smartstack';
+import { apiClient, api } from '@atlashub/smartstack';
 
+export { api };
 export default apiClient;
 
 // For module-specific API calls, extend from the shared client:
 // import apiClient from './api';
-// export const getEmployees = () => apiClient.get('/api/business/humanresources/employees');
+// import { api } from './api';
+// export const getEmployees = () => api.get('/api/business/human-resources/employees');

package/templates/project/appsettings.json.template

@@ -43,7 +43,7 @@
     "EnableValidation": true,
     "RefreshTokenExpirationDays": 7,
     "CleanupBatchSize": 100,
-    "MaxConcurrentSessions": 1,
+    "MaxConcurrentSessions": 3,
     "CleanupIntervalMinutes": 5
   },
   "Serilog": {

package/templates/skills/apex/_shared.md

@@ -32,6 +32,19 @@
 |------|---------|------|
 | `validate_conventions` | Validate SmartStack conventions | 00 (check), 04 (examine) |
 
+### Permission Path Format
+
+| Level | Permission format | Segments |
+|-------|------------------|----------|
+| Module | `{context}.{app}.{module}.{action}` | 3+1 segments |
+| Section | `{context}.{app}.{module}.{section}.{action}` | 4+1 segments |
+| Resource | `{context}.{app}.{module}.{section}.{resource}.{action}` | 5+1 segments |
+
+**Examples:**
+- Module: `business.humanresources.employees.read` (3+1)
+- Section: `business.humanresources.employees.departments.read` (4+1)
+- Resource: `business.humanresources.employees.departments.export.execute` (5+1)
+
 ### Generation (step-03)
 
 | Tool | Purpose | Condition |

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

@@ -41,7 +41,7 @@ if [ -n "$SERVICE_FILES" ]; then
 fi
 ```
 
-### POST-CHECK 3: Controllers must use [RequirePermission], not just [Authorize]
+### POST-CHECK 3: Controllers must use [RequirePermission], not just [Authorize] (BLOCKING)
 
 ```bash
 # Find all controller files
@@ -50,8 +50,10 @@ if [ -n "$CTRL_FILES" ]; then
   for f in $CTRL_FILES; do
     # Check controller has at least one RequirePermission attribute
     if grep -q "\[Authorize\]" "$f" && ! grep -q "\[RequirePermission" "$f"; then
-      echo "WARNING: Controller uses [Authorize] without [RequirePermission]: $f"
-      echo "Use [RequirePermission(Permissions.{Module}.{Action})] on each endpoint"
+      echo "BLOCKING: Controller uses [Authorize] without [RequirePermission]: $f"
+      echo "[Authorize] alone provides NO RBAC enforcement — any authenticated user has access"
+      echo "Fix: Add [RequirePermission(Permissions.{Module}.{Action})] on each endpoint"
+      exit 1
     fi
   done
 fi
@@ -271,6 +273,10 @@ if [ -n "$APP_TSX" ] && [ -n "$SEED_ROUTES" ]; then
       SEED_NORM=$(echo "$SEED_SUFFIX" | tr '[:upper:]' '[:lower:]' | tr -d '-')
       MATCH_FOUND=false
       for FE_PATH in $FRONTEND_PATHS; do
+        # Flag FORBIDDEN /list suffix BEFORE normalization
+        if echo "$FE_PATH" | grep -qP '/list$'; then
+          echo "WARNING: Frontend route ends with /list — should use index route instead: $FE_PATH"
+        fi
         FE_BASE=$(echo "$FE_PATH" | sed 's|/list$||;s|/new$||;s|/:id.*||;s|/create$||')
         FE_NORM=$(echo "$FE_BASE" | tr '[:upper:]' '[:lower:]' | tr -d '-')
         if [ "$SEED_NORM" = "$FE_NORM" ]; then
@@ -291,6 +297,37 @@ if [ -n "$APP_TSX" ] && [ -n "$SEED_ROUTES" ]; then
 fi
 ```
 
+### POST-CHECK 14b: Frontend routes must use kebab-case (BLOCKING)
+
+```bash
+# POST-CHECK 14 normalizes hyphens for existence check, but does NOT catch kebab-case mismatches.
+# This supplementary check detects concatenated multi-word route segments without hyphens.
+APP_TSX=$(find src/ -name "App.tsx" -not -path "*/node_modules/*" 2>/dev/null | head -1)
+if [ -n "$APP_TSX" ]; then
+  # Extract route path strings from App.tsx
+  FE_PATHS=$(grep -oP "path:\s*['\"]([^'\"]+)['\"]" "$APP_TSX" | grep -oP "['\"][^'\"]+['\"]" | tr -d "'" | tr -d '"')
+  for FE_PATH in $FE_PATHS; do
+    # Split path by / and check each segment
+    for SEG in $(echo "$FE_PATH" | tr '/' '\n'); do
+      # Skip dynamic segments (:id, :slug) and single words (< 10 chars likely single word)
+      echo "$SEG" | grep -qP '^:' && continue
+      # Detect multi-word segments without hyphens: 2+ consecutive lowercase sequences
+      # e.g., "humanresources" (human+resources), "timemanagement" (time+management)
+      if echo "$SEG" | grep -qP '^[a-z]{10,}$'; then
+        # Potential concatenated multi-word — cross-check with seed data
+        SEED_MATCH=$(echo "$SEED_ROUTES" | tr '/' '\n' | grep -P "^[a-z]+-[a-z]+" | tr -d '-' | grep -x "$SEG")
+        if [ -n "$SEED_MATCH" ]; then
+          echo "BLOCKING: Frontend route segment '$SEG' appears to be missing hyphens"
+          echo "Seed data uses kebab-case (e.g., 'human-resources') but frontend has '$SEG'"
+          echo "Fix: Use kebab-case in App.tsx route paths to match seed data exactly"
+          exit 1
+        fi
+      fi
+    done
+  done
+fi
+```
+
 ### POST-CHECK 15: HasQueryFilter must not use Guid.Empty (OWASP A01)
 
 ```bash
@@ -441,17 +478,202 @@ SERVICE_FILES=$(find src/ -path "*/Services/*" -name "*Service.cs" ! -name "I*Se
 if [ -n "$SERVICE_FILES" ]; then
   BAD_PATTERN=$(grep -Pn 'TenantId!\s*\.Value|TenantId!\s*\.ToString|\.TenantId!' $SERVICE_FILES 2>/dev/null)
   if [ -n "$BAD_PATTERN" ]; then
-    echo "BLOCKING: Services use TenantId!.Value — causes 500 instead of 401 when tenant context is missing"
+    echo "BLOCKING: Services use TenantId!.Value — causes 500 instead of 400 when tenant context is missing"
     echo "$BAD_PATTERN"
     echo ""
     echo "Fix: Replace with guard clause at the start of every method:"
     echo "  var tenantId = _currentTenant.TenantId"
-    echo "      ?? throw new UnauthorizedAccessException(\"Tenant context is required\");"
+    echo "      ?? throw new TenantContextRequiredException();"
     echo ""
-    echo "This produces a clean 401 via GlobalExceptionHandlerMiddleware instead of an opaque 500."
+    echo "This produces a clean 400 Bad Request via GlobalExceptionHandlerMiddleware."
+    echo "NEVER use UnauthorizedAccessException for tenant context — it returns 401 which clears the frontend token."
+    exit 1
+  fi
+fi
+
+# POST-CHECK: Services must NOT use UnauthorizedAccessException for tenant context (causes token clearing)
+if [ -n "$SERVICE_FILES" ]; then
+  BAD_UNAUTH=$(grep -Pn 'UnauthorizedAccessException.*[Tt]enant' $SERVICE_FILES 2>/dev/null)
+  if [ -n "$BAD_UNAUTH" ]; then
+    echo "BLOCKING: Services use UnauthorizedAccessException for tenant context — causes 401 which clears the frontend token"
+    echo "$BAD_UNAUTH"
+    echo ""
+    echo "Fix: Replace with:"
+    echo "  var tenantId = _currentTenant.TenantId"
+    echo "      ?? throw new TenantContextRequiredException();"
+    echo ""
+    echo "TenantContextRequiredException returns 400 Bad Request (does not clear token)."
+    echo "UnauthorizedAccessException returns 401 Unauthorized (clears token + redirects to login)."
+    exit 1
+  fi
+fi
+```
+
+### POST-CHECK 22: Permissions.cs static constants must exist (BLOCKING)
+
+```bash
+# Every module with controllers MUST have a Permissions.cs with static constants
+CTRL_FILES=$(find src/ -path "*/Controllers/*" -name "*Controller.cs" 2>/dev/null)
+if [ -n "$CTRL_FILES" ]; then
+  PERM_REFS=$(grep -ohP 'Permissions\.\w+\.\w+' $CTRL_FILES 2>/dev/null | sed 's/Permissions\.\([^.]*\)\..*/\1/' | sort -u)
+  for MODULE in $PERM_REFS; do
+    PERM_FILE=$(find src/ -name "Permissions.cs" -exec grep -l "static class $MODULE" {} \; 2>/dev/null)
+    if [ -z "$PERM_FILE" ]; then
+      echo "BLOCKING: Controller references Permissions.${MODULE}.* but no Permissions.cs defines static class ${MODULE}"
+      echo "Fix: Create Application/Authorization/Permissions.cs with: public static class ${MODULE} { public const string Read = \"...\"; ... }"
+      exit 1
+    fi
+  done
+fi
+```
+
+### POST-CHECK 23: ApplicationRolesSeedData.cs must exist (BLOCKING)
+
+```bash
+# If any RolesSeedData exists, ApplicationRolesSeedData MUST also exist
+ROLE_SEED=$(find src/ -path "*/Seeding/Data/*" -name "*RolesSeedData.cs" 2>/dev/null | head -1)
+if [ -n "$ROLE_SEED" ]; then
+  APP_ROLE_SEED=$(find src/ -path "*/Seeding/Data/ApplicationRolesSeedData.cs" 2>/dev/null | head -1)
+  if [ -z "$APP_ROLE_SEED" ]; then
+    echo "BLOCKING: RolesSeedData exists but ApplicationRolesSeedData.cs NOT FOUND"
+    echo "ApplicationRolesSeedData defines the 4 application-scoped roles (admin, manager, contributor, viewer)"
+    echo "Without it, SeedRolesAsync() has no role entries to create → RBAC broken"
+    echo "Fix: Create src/Infrastructure/Persistence/Seeding/Data/ApplicationRolesSeedData.cs"
     exit 1
   fi
 fi
 ```
 
+### POST-CHECK 24b: Section route completeness (NavigationSection → frontend route + permissions)
+
+```bash
+# Every NavigationSection seed data route MUST have a corresponding frontend route in App.tsx
+# and section-level permissions MUST exist for each section defined in seed data
+SECTION_SEED_FILES=$(find src/ -path "*/Seeding/Data/*" -name "*NavigationSectionSeedData.cs" 2>/dev/null)
+APP_TSX=$(find src/ -name "App.tsx" -not -path "*/node_modules/*" 2>/dev/null | head -1)
+if [ -n "$SECTION_SEED_FILES" ] && [ -n "$APP_TSX" ]; then
+  # Extract section routes from seed data
+  SECTION_ROUTES=$(grep -Poh '"/[a-z][a-z0-9/-]+"' $SECTION_SEED_FILES 2>/dev/null | tr -d '"' | sort -u)
+  for SECTION_ROUTE in $SECTION_ROUTES; do
+    # Extract the last segment (section-kebab) for frontend route matching
+    SECTION_SEG=$(echo "$SECTION_ROUTE" | rev | cut -d'/' -f1 | rev)
+    if ! grep -q "'$SECTION_SEG'" "$APP_TSX" && ! grep -q "\"$SECTION_SEG\"" "$APP_TSX"; then
+      echo "BLOCKING: NavigationSection seed data route has no matching frontend route: $SECTION_ROUTE"
+      echo "Expected path segment '$SECTION_SEG' in App.tsx contextRoutes"
+      echo "Fix: Add section child routes to the module's children array in App.tsx"
+    fi
+  done
+fi
+
+# Controllers with section-level [NavRoute] (4 segments) must have matching [RequirePermission]
+CTRL_FILES=$(find src/ -path "*/Controllers/*" -name "*Controller.cs" 2>/dev/null)
+if [ -n "$CTRL_FILES" ]; then
+  for f in $CTRL_FILES; do
+    # Match NavRoute with 4 dot-separated segments (section-level)
+    SECTION_NAVROUTE=$(grep -oP 'NavRoute\("[a-z]+\.[a-z]+\.[a-z]+\.[a-z]+"\)' "$f" 2>/dev/null)
+    if [ -n "$SECTION_NAVROUTE" ] && ! grep -q "\[RequirePermission" "$f"; then
+      echo "BLOCKING: Section controller has [NavRoute] but no [RequirePermission]: $f"
+      echo "Fix: Add [RequirePermission(Permissions.{Section}.{Action})] on each endpoint"
+      exit 1
+    fi
+  done
+fi
+
+# Section-level permissions must exist for each section in seed data
+PERM_FILE=$(find src/ -name "Permissions.cs" -path "*/Authorization/*" 2>/dev/null | head -1)
+if [ -n "$SECTION_SEED_FILES" ] && [ -n "$PERM_FILE" ]; then
+  SECTION_CODES=$(grep -oP 'Code\s*=\s*"([a-z]+)"' $SECTION_SEED_FILES 2>/dev/null | grep -oP '"[^"]+"' | tr -d '"' | sort -u)
+  for CODE in $SECTION_CODES; do
+    PASCAL=$(echo "$CODE" | sed 's/^./\U&/')
+    if ! grep -q "static class $PASCAL" "$PERM_FILE" 2>/dev/null; then
+      echo "WARNING: Section '$CODE' in seed data has no matching Permissions.$PASCAL static class"
+      echo "Fix: Add section-level permissions via MCP generate_permissions with 4-segment navRoute"
+    fi
+  done
+fi
+```
+
+### POST-CHECK 25: FORBIDDEN route patterns — /list and /detail/:id (BLOCKING)
+
+```bash
+# 1. Check seed data for FORBIDDEN suffixes
+SEED_NAV_FILES=$(find src/ -path "*/Seeding/Data/*" -name "*NavigationSeedData.cs" -o -name "*NavigationSectionSeedData.cs" 2>/dev/null)
+if [ -n "$SEED_NAV_FILES" ]; then
+  BAD_ROUTES=$(grep -Pn 'Route\s*=\s*.*"[^"]*/(list|detail)["/]' $SEED_NAV_FILES 2>/dev/null | grep -v '//.*Route')
+  if [ -n "$BAD_ROUTES" ]; then
+    echo "BLOCKING: FORBIDDEN route pattern in seed data"
+    echo "  - 'list' section route = module route (NO /list suffix)"
+    echo "  - 'detail' section route = module route + /:id (NOT /detail/:id)"
+    echo "$BAD_ROUTES"
+    exit 1
+  fi
+fi
+
+# 2. Check frontend routes for FORBIDDEN path segments
+APP_TSX=$(find src/ -name "App.tsx" -not -path "*/node_modules/*" 2>/dev/null | head -1)
+if [ -n "$APP_TSX" ]; then
+  BAD_FE=$(grep -Pn "path:\s*['\"](?:list|detail)" "$APP_TSX" 2>/dev/null)
+  if [ -n "$BAD_FE" ]; then
+    echo "BLOCKING: FORBIDDEN frontend route path"
+    echo "  - list = index: true (no 'list' path segment)"
+    echo "  - detail = ':id' (no 'detail' path segment)"
+    echo "$BAD_FE"
+    exit 1
+  fi
+fi
+echo "OK: No forbidden /list or /detail route patterns found"
+```
+
+### POST-CHECK 26: Permission path segment count (WARNING)
+
+```bash
+PERM_FILES=$(find src/ -path "*/Seeding/Data/*" -name "PermissionsSeedData.cs" 2>/dev/null)
+if [ -n "$PERM_FILES" ]; then
+  while IFS= read -r line; do
+    PATH_VAL=$(echo "$line" | grep -oP '"[^"]*\.[^"]*"' | tr -d '"')
+    if [ -n "$PATH_VAL" ]; then
+      DOTS=$(echo "$PATH_VAL" | tr -cd '.' | wc -c)
+      # Module permissions: 3 dots (context.app.module.action = 4 segments = 3+1)
+      # Section permissions: 4 dots (context.app.module.section.action = 5 segments = 4+1)
+      # Wildcard: ends with .* (valid at any level)
+      if echo "$PATH_VAL" | grep -qP '\.\*$'; then
+        continue  # Wildcards are valid
+      elif [ "$DOTS" -lt 3 ] || [ "$DOTS" -gt 5 ]; then
+        echo "WARNING: Permission path has unexpected segment count ($((DOTS+1)) segments): $PATH_VAL"
+      fi
+    fi
+  done < <(grep -n 'Path\s*=' $PERM_FILES 2>/dev/null)
+fi
+```
+
+### POST-CHECK 24: IClientSeedDataProvider must have 4 methods + DI registration (BLOCKING)
+
+```bash
+PROVIDER=$(find src/ -path "*/Seeding/*SeedDataProvider.cs" 2>/dev/null | head -1)
+if [ -n "$PROVIDER" ]; then
+  METHODS_FOUND=0
+  for METHOD in SeedNavigationAsync SeedRolesAsync SeedPermissionsAsync SeedRolePermissionsAsync; do
+    if grep -q "$METHOD" "$PROVIDER"; then
+      METHODS_FOUND=$((METHODS_FOUND + 1))
+    else
+      echo "BLOCKING: IClientSeedDataProvider missing method: $METHOD in $PROVIDER"
+    fi
+  done
+  if [ "$METHODS_FOUND" -lt 4 ]; then
+    echo "Fix: IClientSeedDataProvider must implement all 4 methods: SeedNavigationAsync, SeedRolesAsync, SeedPermissionsAsync, SeedRolePermissionsAsync"
+    exit 1
+  fi
+
+  # Check DI registration
+  DI_FILE=$(find src/ -name "DependencyInjection.cs" -path "*/Infrastructure/*" 2>/dev/null | head -1)
+  if [ -n "$DI_FILE" ]; then
+    if ! grep -q "IClientSeedDataProvider" "$DI_FILE"; then
+      echo "BLOCKING: IClientSeedDataProvider not registered in DependencyInjection.cs"
+      echo "Fix: Add services.AddScoped<IClientSeedDataProvider, {App}SeedDataProvider>()"
+      exit 1
+    fi
+  fi
+fi
+```
+
 **If ANY POST-CHECK fails → fix in step-03, re-validate.**

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

@@ -238,9 +238,9 @@ public class {Name}Service : I{Name}Service
         int pageSize = 20,
         CancellationToken ct = default)
     {
-        // MANDATORY guard — throws 401 if no tenant context (e.g., missing X-Tenant-Slug header)
+        // MANDATORY guard — throws 400 if no tenant context (e.g., missing X-Tenant-Slug header)
         var tenantId = _currentTenant.TenantId
-            ?? throw new UnauthorizedAccessException("Tenant context is required");
+            ?? throw new TenantContextRequiredException();
 
         var query = _db.{Name}s
             .Where(x => x.TenantId == tenantId)  // MANDATORY tenant filter
@@ -268,7 +268,7 @@ public class {Name}Service : I{Name}Service
     public async Task<{Name}ResponseDto?> GetByIdAsync(Guid id, CancellationToken ct)
     {
         var tenantId = _currentTenant.TenantId
-            ?? throw new UnauthorizedAccessException("Tenant context is required");
+            ?? throw new TenantContextRequiredException();
 
         return await _db.{Name}s
             .Where(x => x.Id == id && x.TenantId == tenantId)  // MANDATORY
@@ -280,7 +280,7 @@ public class {Name}Service : I{Name}Service
     public async Task<{Name}ResponseDto> CreateAsync(Create{Name}Dto dto, CancellationToken ct)
     {
         var tenantId = _currentTenant.TenantId
-            ?? throw new UnauthorizedAccessException("Tenant context is required");
+            ?? throw new TenantContextRequiredException();
 
         var entity = {Name}.Create(
             tenantId: tenantId,  // MANDATORY — never Guid.Empty
@@ -301,7 +301,7 @@ public class {Name}Service : I{Name}Service
     public async Task DeleteAsync(Guid id, CancellationToken ct)
     {
         var tenantId = _currentTenant.TenantId
-            ?? throw new UnauthorizedAccessException("Tenant context is required");
+            ?? throw new TenantContextRequiredException();
 
         var entity = await _db.{Name}s
             .FirstOrDefaultAsync(x => x.Id == id && x.TenantId == tenantId, ct)
@@ -321,12 +321,14 @@ public class {Name}Service : I{Name}Service
 **MANDATORY guard clause (first line of every method):**
 ```csharp
 var tenantId = _currentTenant.TenantId
-    ?? throw new UnauthorizedAccessException("Tenant context is required");
+    ?? throw new TenantContextRequiredException();
 ```
-This converts a null TenantId into a clean 401 response via `GlobalExceptionHandlerMiddleware`.
+This converts a null TenantId into a clean 400 Bad Request response via `GlobalExceptionHandlerMiddleware`.
+**IMPORTANT:** Uses `TenantContextRequiredException` (400), NOT `UnauthorizedAccessException` (401). A missing tenant is a bad request, not an auth failure — the JWT is valid, `[Authorize]` passed.
 
 **FORBIDDEN in services:**
-- `_currentTenant.TenantId!.Value` — throws `InvalidOperationException` (500) instead of clean 401
+- `_currentTenant.TenantId!.Value` — throws `InvalidOperationException` (500) instead of clean 400
+- `UnauthorizedAccessException("Tenant context is required")` — throws 401, triggers frontend token clearing
 - `tenantId: Guid.Empty` — always use validated tenantId from guard clause
 - Queries WITHOUT `.Where(x => x.TenantId == tenantId)` — data leak
 - Missing `ILogger<T>` — undiagnosable in production
@@ -383,6 +385,14 @@ public class {Name}Controller : ControllerBase
         return CreatedAtAction(nameof(GetById), new { id = result.Id }, result);
     }
 
+    [HttpPut("{id:guid}")]
+    [RequirePermission(Permissions.{Module}.Update)]
+    public async Task<ActionResult<{Name}ResponseDto>> Update(Guid id, [FromBody] Update{Name}Dto dto, CancellationToken ct)
+    {
+        var result = await _service.UpdateAsync(id, dto, ct);
+        return result is null ? NotFound() : Ok(result);
+    }
+
     [HttpDelete("{id:guid}")]
     [RequirePermission(Permissions.{Module}.Delete)]
     public async Task<ActionResult> Delete(Guid id, CancellationToken ct)
@@ -395,6 +405,35 @@ public class {Name}Controller : ControllerBase
 
 **CRITICAL:** Use `[RequirePermission(Permissions.{Module}.{Action})]` on EVERY endpoint — NEVER `[Authorize]` alone (no RBAC enforcement).
 
+### Section-Level Controller (NavRoute with 4 segments)
+
+When a module has sections, each section gets its own controller with a 4-segment navRoute:
+
+```csharp
+// Section-level controller: navRoute has 4 segments
+[ApiController]
+[NavRoute("{context}.{app}.{module}.{section}")]
+[Authorize]
+public class {Section}Controller : ControllerBase
+{
+    // Example: business.humanresources.employees.departments
+    [HttpGet]
+    [RequirePermission(Permissions.{Section}.Read)]
+    public async Task<ActionResult<PaginatedResult<{Section}ResponseDto>>> GetAll(
+        [FromQuery] string? search = null,
+        [FromQuery] int page = 1,
+        [FromQuery] int pageSize = 20,
+        CancellationToken ct = default)
+        => Ok(await _service.GetAllAsync(search, page, pageSize, ct));
+}
+```
+
+**NavRoute segment rules:**
+| Level | NavRoute format | Example |
+|-------|----------------|---------|
+| Module | `{context}.{app}.{module}` (3 segments) | `business.humanresources.employees` |
+| Section | `{context}.{app}.{module}.{section}` (4 segments) | `business.humanresources.employees.departments` |
+
 **Namespace:** `SmartStack.Api.Routing` (NOT `SmartStack.Api.Core.Routing`)
 
 **NavRoute resolves at startup from DB:** `platform.administration.users` → `api/platform/administration/users`
@@ -412,8 +451,16 @@ public class {Name}Controller : ControllerBase
 |-------|-------------|---------|
 | Application | `/{context}/{app-kebab}` | `/business/human-resources` |
 | Module | `/{context}/{app-kebab}/{module-kebab}` | `/business/human-resources/employees` |
-| Section | `/{context}/{app-kebab}/{module-kebab}/{section-kebab}` | `/business/human-resources/employees/list` |
-| Resource | `/{context}/{app-kebab}/{module-kebab}/{section-kebab}/{resource-kebab}` | `/business/human-resources/employees/list/export` |
+| Section | `/{context}/{app-kebab}/{module-kebab}/{section-kebab}` | `/business/human-resources/employees/departments` |
+| Resource | `/{context}/{app-kebab}/{module-kebab}/{section-kebab}/{resource-kebab}` | `/business/human-resources/employees/departments/export` |
+
+**ROUTE SPECIAL CASES (list and detail sections):**
+> The `list` and `detail` sections are NOT functional sub-areas — they are view modes of the module itself.
+> Their navigation routes MUST NOT add extra segments:
+> - `list` section route = module route (e.g., `/business/human-resources/employees`)
+> - `detail` section route = module route + `/:id` (e.g., `/business/human-resources/employees/:id`)
+> - FORBIDDEN: `/employees/list`, `/employees/detail/:id`
+> - Other sections (dashboard, approve, import, etc.) = module route + `/{section-kebab}` (normal behavior)
 
 **Rules:**
 - Routes ALWAYS start with `/`
@@ -426,7 +473,7 @@ public class {Name}Controller : ControllerBase
 ```csharp
 private static string ToKebabCase(string value)
     => System.Text.RegularExpressions.Regex
-        .Replace(value, "(?<!^)([A-Z])", "-$1")
+        .Replace(value, "([a-z])([A-Z])", "$1-$2")
         .ToLowerInvariant();
 ```
 
@@ -446,7 +493,7 @@ public static class SeedConstants
     //       Context IDs are NOT — they are pre-seeded by SmartStack core.
     public static readonly Guid ApplicationId = DeterministicGuid("nav:business.humanresources");
     public static readonly Guid ModuleId = DeterministicGuid("nav:business.humanresources.employees");
-    public static readonly Guid SectionId = DeterministicGuid("nav:business.humanresources.employees.list");
+    public static readonly Guid SectionId = DeterministicGuid("nav:business.humanresources.employees.departments");
 
     // FORBIDDEN — Context IDs are NOT deterministic, they come from SmartStack core:
     // public static readonly Guid BusinessContextId = DeterministicGuid("nav:business"); // WRONG!
@@ -545,7 +592,8 @@ services.AddValidatorsFromAssemblyContaining<Create{Name}DtoValidator>();
 | `tenantId: Guid.Empty` in services | OWASP A01 — always use validated `_currentTenant.TenantId` |
 | Service without `ICurrentTenantService` | All tenant data leaks — inject `ICurrentTenantService` |
 | `ICurrentUser` in service code | Does NOT exist — use `ICurrentUserService` + `ICurrentTenantService` |
-| `_currentTenant.TenantId!.Value` | Crashes with 500 — use `?? throw new UnauthorizedAccessException(...)` |
+| `_currentTenant.TenantId!.Value` | Crashes with 500 — use `?? throw new TenantContextRequiredException()` |
+| `UnauthorizedAccessException("Tenant context is required")` | Returns 401 → clears frontend token. Use `TenantContextRequiredException()` (400) |
 | Route `"humanresources"` in seed data | Must be full path `"/business/human-resources"` |
 | Route without leading `/` | All routes must start with `/` |
 | `Permission.Create()` | Does NOT exist — use `CreateForModule()`, `CreateForSection()`, etc. |
@@ -712,16 +760,18 @@ public async Task<PaginatedResult<MyEntityDto>> GetAllAsync(...)
 }
 ```
 
-**CORRECT — Clean 401 via GlobalExceptionHandlerMiddleware:**
+**CORRECT — Clean 400 via GlobalExceptionHandlerMiddleware:**
 ```csharp
-// CORRECT: Throws UnauthorizedAccessException → middleware converts to 401
+// CORRECT: Throws TenantContextRequiredException → middleware converts to 400 Bad Request
 public async Task<PaginatedResult<MyEntityDto>> GetAllAsync(...)
 {
     var tenantId = _currentTenant.TenantId
-        ?? throw new UnauthorizedAccessException("Tenant context is required");
+        ?? throw new TenantContextRequiredException();
     var query = _db.MyEntities.Where(x => x.TenantId == tenantId);
     // ...
 }
 ```
 
-**Why it's wrong:** When a user hits an API via Swagger with a valid JWT but no tenant context (missing `X-Tenant-Slug` header), `TenantId` is null. The `!.Value` pattern produces an opaque `500 Internal Server Error` instead of a clear `401 Unauthorized` with an actionable message. The `?? throw new UnauthorizedAccessException(...)` pattern is caught by `GlobalExceptionHandlerMiddleware` and returned as a proper 401 response.
+**Why `!.Value` is wrong:** When a user hits an API via Swagger with a valid JWT but no tenant context (missing `X-Tenant-Slug` header), `TenantId` is null. The `!.Value` pattern produces an opaque `500 Internal Server Error` instead of a clear `400 Bad Request` with an actionable message.
+
+**Why `UnauthorizedAccessException` is wrong:** A missing tenant is NOT an auth failure — the JWT is valid, `[Authorize]` passed. Using `UnauthorizedAccessException` returns 401, which triggers the frontend interceptor to clear the token and redirect to login. Use `TenantContextRequiredException` instead (returns 400, does not clear the token).

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

@@ -326,7 +326,7 @@ export function EntityDetailPage() {
   }, [activeTab]);
 
   // Edit button navigates to /:id/edit route (NEVER opens a modal)
-  const handleEdit = () => navigate(`/${basePath}/${entityId}/edit`);
+  const handleEdit = () => navigate(`edit`);
 
   // ... loading/error/content pattern
 }
@@ -341,6 +341,11 @@ export function EntityDetailPage() {
 
 ### Route Convention
 
+> **CRITICAL:** Route paths MUST use **kebab-case** matching the navigation seed data (which uses `ToKebabCase()`).
+> - Single word: `employees` (no change needed)
+> - Multi-word: `human-resources`, `time-management` (kebab-case with hyphens)
+> - **FORBIDDEN:** `humanresources`, `timemanagement` (concatenated words without hyphens)
+
 | Action | Route pattern | Page component | File location |
 |--------|--------------|----------------|---------------|
 | Create | `/{module}/create` | `EntityCreatePage` | `src/pages/{Context}/{App}/{Module}/EntityCreatePage.tsx` |
@@ -498,6 +503,41 @@ const EntityEditPage = lazy(() =>
     { path: ':id/edit', element: <Suspense fallback={<PageLoader />}><EntityEditPage /></Suspense> },
   ]
 }
+
+// Section-level routes — children of the module route (when module has sections)
+//
+// > **IMPORTANT:** The `list` and `detail` sections do NOT generate additional route entries.
+// > They are already covered by the module's `index: true` (list) and `path: ':id'` (detail) routes above.
+// > Only sections like `dashboard`, `approve`, `import`, etc. generate the section-kebab child routes below.
+// > FORBIDDEN: `path: 'list'`, `path: 'detail'` — these would create unreachable duplicate routes.
+//
+{
+  path: '{module-kebab}',
+  children: [
+    { index: true, element: <Suspense fallback={<PageLoader />}><{Module}Page /></Suspense> },
+    { path: 'create', element: <Suspense fallback={<PageLoader />}><Create{Module}Page /></Suspense> },
+    { path: ':id', element: <Suspense fallback={<PageLoader />}><{Module}DetailPage /></Suspense> },
+    { path: ':id/edit', element: <Suspense fallback={<PageLoader />}><Edit{Module}Page /></Suspense> },
+    // Section routes as children of module:
+    // IMPORTANT: "list" and "detail" are NOT separate path segments.
+    // - "list" section = already handled by the module's index route above (index: true)
+    // - "detail" section = already handled by the module's :id route above (path: ':id')
+    // - Only OTHER sections (dashboard, approve, import, etc.) add path segments:
+    { path: '{section-kebab}', element: <Suspense fallback={<PageLoader />}><{Section}Page /></Suspense> },
+    { path: '{section-kebab}/create', element: <Suspense fallback={<PageLoader />}><Create{Section}Page /></Suspense> },
+    { path: '{section-kebab}/:id', element: <Suspense fallback={<PageLoader />}><{Section}DetailPage /></Suspense> },
+    { path: '{section-kebab}/:id/edit', element: <Suspense fallback={<PageLoader />}><Edit{Section}Page /></Suspense> },
+  ]
+}
+
+// PermissionGuard for section-level routes
+element: (
+  <Suspense fallback={<PageLoader />}>
+    <PermissionGuard permissions={ROUTES['business.app.module.section'].permissions}>
+      <SectionPage />
+    </PermissionGuard>
+  </Suspense>
+)
 ```
 
 ### Rules