@atlashub/smartstack-cli 3.21.0 → 3.23.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@atlashub/smartstack-cli",
-  "version": "3.21.0",
+  "version": "3.23.0",
   "description": "SmartStack Claude Code automation toolkit - GitFlow, EF Core migrations, prompts and more",
   "author": {
     "name": "SmartStack",

package/templates/skills/apex/SKILL.md

@@ -91,6 +91,7 @@ Execute incremental SmartStack development using the APEX methodology. This skil
 
 | File | Purpose | Loaded by |
 |------|---------|-----------|
+| `references/smartstack-api.md` | BaseEntity, interfaces, entity/config/controller patterns | step-01, step-03 |
 | `references/smartstack-layers.md` | Layer execution rules, skill/MCP mapping, seed data | step-02, step-03 |
 | `references/agent-teams-protocol.md` | TeamCreate, coordination, shutdown protocol | step-01, step-03 |
 </reference_files>
@@ -108,6 +109,26 @@ Execute incremental SmartStack development using the APEX methodology. This skil
 
 </execution_rules>
 
+<error_handling>
+
+## Error Handling Strategy
+
+| Error | Action | Max Retries |
+|-------|--------|-------------|
+| `dotnet build` fails | Identify error, fix via skill/MCP, rebuild | 3 |
+| `npm run typecheck` fails | Fix TypeScript error, retry | 3 |
+| MCP unavailable | Degraded mode: use `smartstack-api.md` as sole reference, no MCP validation | — |
+| File lock (MSB3021) | Auto-use `--output /tmp/{project}_build` for build verification | — |
+| NuGet restore required | Run `dotnet restore` before first `dotnet build` | 1 |
+| Migration fails | Rollback migration (`dotnet ef migrations remove`), fix entity/config, retry | 2 |
+| MCP scaffold output wrong | Verify against `smartstack-api.md` patterns, fix manually | — |
+| POST-CHECK fails | Return to step-03, fix the issue, re-validate | 2 |
+| Stuck after max retries | AskUserQuestion with options: "Try alternative", "Skip", "Discuss" | — |
+
+**Principle:** Always fix CODE, never bypass checks. If stuck, escalate to user.
+
+</error_handling>
+
 <success_criteria>
 - SmartStack context detected (context/app/module)
 - Plan validated with skill/MCP mapped for each file

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

@@ -0,0 +1,481 @@
+# SmartStack Domain API Reference
+
+> **Source of truth:** `SmartStack.app/src/SmartStack.Domain/Common/`
+> **Loaded by:** step-01 (analyze), step-03 (execute)
+
+---
+
+## BaseEntity
+
+```csharp
+namespace SmartStack.Domain.Common;
+
+public abstract class BaseEntity
+{
+    public Guid Id { get; set; }
+    public DateTime CreatedAt { get; set; }
+    public DateTime? UpdatedAt { get; set; }
+}
+```
+
+**ONLY 3 properties.** No Code, no IsDeleted, no RowVersion, no SoftDelete, no CreatedBy/UpdatedBy.
+
+---
+
+## Interfaces
+
+### ITenantEntity (mandatory tenant isolation)
+
+```csharp
+public interface ITenantEntity
+{
+    Guid TenantId { get; }
+}
+```
+
+### IAuditableEntity (audit trail)
+
+```csharp
+public interface IAuditableEntity
+{
+    string? CreatedBy { get; set; }
+    string? UpdatedBy { get; set; }
+}
+```
+
+### IOptionalTenantEntity (nullable tenant)
+
+```csharp
+public interface IOptionalTenantEntity
+{
+    Guid? TenantId { get; }
+}
+```
+
+### IScopedTenantEntity (tenant + scope visibility)
+
+```csharp
+public interface IScopedTenantEntity : IOptionalTenantEntity
+{
+    EntityScope Scope { get; }
+}
+```
+
+### EntityScope enum
+
+```csharp
+public enum EntityScope
+{
+    Tenant = 0,   // Visible only to specific tenant (TenantId required)
+    Shared = 1,   // Visible to all tenants (TenantId null)
+    Platform = 2  // Visible only to platform admins (HasGlobalAccess)
+}
+```
+
+---
+
+## Entity Pattern (tenant-scoped, most common)
+
+```csharp
+using SmartStack.Domain.Common;
+
+namespace {ProjectName}.Domain.Entities.{Context}.{App}.{Module};
+
+public class {Name} : BaseEntity, ITenantEntity, IAuditableEntity
+{
+    // ITenantEntity
+    public Guid TenantId { get; private set; }
+
+    // IAuditableEntity
+    public string? CreatedBy { get; set; }
+    public string? UpdatedBy { get; set; }
+
+    // Business properties (add your own)
+    public string Code { get; private set; } = null!;
+    public string Name { get; private set; } = null!;
+    public string? Description { get; private set; }
+    public bool IsActive { get; private set; } = true;
+
+    private {Name}() { }
+
+    public static {Name} Create(Guid tenantId, string code, string name)
+    {
+        if (tenantId == Guid.Empty)
+            throw new ArgumentException("TenantId is required", nameof(tenantId));
+
+        return new {Name}
+        {
+            Id = Guid.NewGuid(),
+            TenantId = tenantId,
+            Code = code.ToLowerInvariant(),
+            Name = name,
+            CreatedAt = DateTime.UtcNow
+        };
+    }
+
+    public void Update(string name, string? description)
+    {
+        Name = name;
+        Description = description;
+        UpdatedAt = DateTime.UtcNow;
+    }
+}
+```
+
+---
+
+## Entity Pattern (platform-level, no tenant)
+
+```csharp
+public class {Name} : BaseEntity, IAuditableEntity
+{
+    public string? CreatedBy { get; set; }
+    public string? UpdatedBy { get; set; }
+
+    // Business properties
+    public string Code { get; private set; } = null!;
+    public string Name { get; private set; } = null!;
+
+    private {Name}() { }
+
+    public static {Name} Create(string code, string name)
+    {
+        return new {Name}
+        {
+            Id = Guid.NewGuid(),
+            Code = code.ToLowerInvariant(),
+            Name = name,
+            CreatedAt = DateTime.UtcNow
+        };
+    }
+}
+```
+
+---
+
+## EF Configuration Pattern
+
+```csharp
+using Microsoft.EntityFrameworkCore;
+using Microsoft.EntityFrameworkCore.Metadata.Builders;
+
+public class {Name}Configuration : IEntityTypeConfiguration<{Name}>
+{
+    public void Configure(EntityTypeBuilder<{Name}> builder)
+    {
+        builder.ToTable("{prefix}{Name}s", "{schema}");
+
+        builder.HasKey(x => x.Id);
+
+        // Tenant (if ITenantEntity)
+        builder.Property(x => x.TenantId).IsRequired();
+        builder.HasIndex(x => x.TenantId)
+            .HasDatabaseName("IX_{prefix}{Name}s_TenantId");
+
+        // Business properties
+        builder.Property(x => x.Code).HasMaxLength(50).IsRequired();
+        builder.Property(x => x.Name).HasMaxLength(100).IsRequired();
+        builder.Property(x => x.Description).HasMaxLength(500);
+
+        // Audit (from IAuditableEntity)
+        builder.Property(x => x.CreatedBy).HasMaxLength(256);
+        builder.Property(x => x.UpdatedBy).HasMaxLength(256);
+
+        // Unique indexes
+        builder.HasIndex(x => new { x.TenantId, x.Code })
+            .IsUnique()
+            .HasDatabaseName("IX_{prefix}{Name}s_Tenant_Code");
+
+        // Relationships
+        // builder.HasMany(x => x.Children)
+        //     .WithOne(x => x.Parent)
+        //     .HasForeignKey(x => x.ParentId)
+        //     .OnDelete(DeleteBehavior.Restrict);
+
+        // Seed data (if applicable)
+        // builder.HasData({Name}SeedData.GetSeedData());
+    }
+}
+```
+
+---
+
+## Service Pattern (tenant-scoped, MANDATORY)
+
+> **CRITICAL:** ALL services MUST inject `ICurrentUser` and filter by `TenantId`. Missing TenantId = OWASP A01 vulnerability.
+
+```csharp
+using Microsoft.EntityFrameworkCore;
+using Microsoft.Extensions.Logging;
+using SmartStack.Application.Common.Interfaces.Identity;
+using SmartStack.Application.Common.Interfaces.Persistence;
+
+namespace {ProjectName}.Infrastructure.Services.{Context}.{App}.{Module};
+
+public class {Name}Service : I{Name}Service
+{
+    private readonly IExtensionsDbContext _db;
+    private readonly ICurrentUser _currentUser;
+    private readonly ILogger<{Name}Service> _logger;
+
+    public {Name}Service(
+        IExtensionsDbContext db,
+        ICurrentUser currentUser,
+        ILogger<{Name}Service> logger)
+    {
+        _db = db;
+        _currentUser = currentUser;
+        _logger = logger;
+    }
+
+    public async Task<List<{Name}ResponseDto>> GetAllAsync(CancellationToken ct)
+    {
+        return await _db.{Name}s
+            .Where(x => x.TenantId == _currentUser.TenantId)  // MANDATORY tenant filter
+            .AsNoTracking()
+            .Select(x => new {Name}ResponseDto(x.Id, x.Code, x.Name, x.CreatedAt))
+            .ToListAsync(ct);
+    }
+
+    public async Task<{Name}ResponseDto?> GetByIdAsync(Guid id, CancellationToken ct)
+    {
+        return await _db.{Name}s
+            .Where(x => x.Id == id && x.TenantId == _currentUser.TenantId)  // MANDATORY
+            .AsNoTracking()
+            .Select(x => new {Name}ResponseDto(x.Id, x.Code, x.Name, x.CreatedAt))
+            .FirstOrDefaultAsync(ct);
+    }
+
+    public async Task<{Name}ResponseDto> CreateAsync(Create{Name}Dto dto, CancellationToken ct)
+    {
+        var entity = {Name}.Create(
+            tenantId: _currentUser.TenantId,  // MANDATORY — never Guid.Empty
+            code: dto.Code,
+            name: dto.Name);
+
+        entity.CreatedBy = _currentUser.UserId?.ToString();
+
+        _db.{Name}s.Add(entity);
+        await _db.SaveChangesAsync(ct);
+
+        _logger.LogInformation("Created {Entity} {Id} for tenant {TenantId}",
+            nameof({Name}), entity.Id, _currentUser.TenantId);
+
+        return new {Name}ResponseDto(entity.Id, entity.Code, entity.Name, entity.CreatedAt);
+    }
+
+    public async Task DeleteAsync(Guid id, CancellationToken ct)
+    {
+        var entity = await _db.{Name}s
+            .FirstOrDefaultAsync(x => x.Id == id && x.TenantId == _currentUser.TenantId, ct)
+            ?? throw new KeyNotFoundException($"{Name} {id} not found");
+
+        _db.{Name}s.Remove(entity);
+        await _db.SaveChangesAsync(ct);
+    }
+}
+```
+
+**Key interfaces:**
+- `ICurrentUser` (from `SmartStack.Application.Common.Interfaces.Identity`): provides `TenantId`, `UserId`, `Email`
+- `IExtensionsDbContext` (for client extensions) or `ICoreDbContext` (for platform)
+
+**FORBIDDEN in services:**
+- `tenantId: Guid.Empty` — always use `_currentUser.TenantId`
+- Queries WITHOUT `.Where(x => x.TenantId == _currentUser.TenantId)` — data leak
+- Missing `ILogger<T>` — undiagnosable in production
+
+---
+
+## Controller Pattern (NavRoute)
+
+```csharp
+using Microsoft.AspNetCore.Authorization;
+using Microsoft.AspNetCore.Mvc;
+using SmartStack.Api.Routing;
+using SmartStack.Api.Authorization;
+
+namespace {ProjectName}.Api.Controllers.{Context}.{App};
+
+[ApiController]
+[NavRoute("{context}.{app}.{module}")]
+[Authorize]
+public class {Name}Controller : ControllerBase
+{
+    private readonly I{Name}Service _service;
+    private readonly ILogger<{Name}Controller> _logger;
+
+    public {Name}Controller(I{Name}Service service, ILogger<{Name}Controller> logger)
+    {
+        _service = service;
+        _logger = logger;
+    }
+
+    [HttpGet]
+    [RequirePermission(Permissions.{Module}.Read)]
+    public async Task<ActionResult<List<{Name}ResponseDto>>> GetAll(CancellationToken ct)
+        => Ok(await _service.GetAllAsync(ct));
+
+    [HttpGet("{id:guid}")]
+    [RequirePermission(Permissions.{Module}.Read)]
+    public async Task<ActionResult<{Name}ResponseDto>> GetById(Guid id, CancellationToken ct)
+    {
+        var result = await _service.GetByIdAsync(id, ct);
+        return result is null ? NotFound() : Ok(result);
+    }
+
+    [HttpPost]
+    [RequirePermission(Permissions.{Module}.Create)]
+    public async Task<ActionResult<{Name}ResponseDto>> Create([FromBody] Create{Name}Dto dto, CancellationToken ct)
+    {
+        var result = await _service.CreateAsync(dto, ct);
+        return CreatedAtAction(nameof(GetById), new { id = result.Id }, result);
+    }
+
+    [HttpDelete("{id:guid}")]
+    [RequirePermission(Permissions.{Module}.Delete)]
+    public async Task<ActionResult> Delete(Guid id, CancellationToken ct)
+    {
+        await _service.DeleteAsync(id, ct);
+        return NoContent();
+    }
+}
+```
+
+**CRITICAL:** Use `[RequirePermission(Permissions.{Module}.{Action})]` on EVERY endpoint — NEVER `[Authorize]` alone (no RBAC enforcement).
+
+**Namespace:** `SmartStack.Api.Routing` (NOT `SmartStack.Api.Core.Routing`)
+
+**NavRoute resolves at startup from DB:** `platform.administration.users` → `api/platform/administration/users`
+
+---
+
+## Navigation Seed Data Pattern (CRITICAL — routes must be full paths)
+
+> **The navigation seed data defines menu routes stored in DB. These routes MUST be full paths starting with `/`.**
+> Short routes (e.g., `humanresources`) cause 400 Bad Request on application-tracking.
+
+### Route Convention
+
+| Level | Route Format | Example |
+|-------|-------------|---------|
+| 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` |
+
+**Rules:**
+- Routes ALWAYS start with `/`
+- Routes ALWAYS include the full hierarchy from context to current level
+- Routes ALWAYS use kebab-case (NOT PascalCase, NOT camelCase)
+- Code identifiers stay PascalCase in C# (`HumanResources`) but routes are kebab-case (`human-resources`)
+
+### ToKebabCase Helper (include in SeedConstants or SeedDataProvider)
+
+```csharp
+private static string ToKebabCase(string value)
+    => System.Text.RegularExpressions.Regex
+        .Replace(value, "(?<!^)([A-Z])", "-$1")
+        .ToLowerInvariant();
+```
+
+### SeedConstants Pattern
+
+```csharp
+public static class SeedConstants
+{
+    // Deterministic GUIDs (SHA256-based, reproducible across environments)
+    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");
+
+    private static Guid DeterministicGuid(string input)
+    {
+        var hash = System.Security.Cryptography.SHA256.HashData(
+            System.Text.Encoding.UTF8.GetBytes(input));
+        var bytes = new byte[16];
+        Array.Copy(hash, bytes, 16);
+        bytes[6] = (byte)((bytes[6] & 0x0F) | 0x50); // version 5
+        bytes[8] = (byte)((bytes[8] & 0x3F) | 0x80); // variant
+        return new Guid(bytes);
+    }
+}
+```
+
+### Navigation Seed Data Example
+
+```csharp
+// Application: /business/human-resources
+var app = NavigationApplication.Create(
+    businessCtx.Id, "humanresources", "Human Resources", "HR Management",
+    "Users", IconType.Lucide,
+    "/business/human-resources",  // FULL PATH — starts with /, kebab-case
+    10);
+
+// Module: /business/human-resources/employees
+var module = NavigationModule.Create(
+    app.Id, "employees", "Employees", "Employee management",
+    "UserCheck", IconType.Lucide,
+    "/business/human-resources/employees",  // FULL PATH — includes parent
+    10);
+
+// Section: /business/human-resources/employees/departments
+var section = NavigationSection.Create(
+    module.Id, "departments", "Departments", "Manage departments",
+    "Building2", IconType.Lucide,
+    "/business/human-resources/employees/departments",  // FULL PATH
+    10);
+```
+
+### FORBIDDEN in Seed Data
+
+| Mistake | Reality |
+|---------|---------|
+| `"humanresources"` as route | Must be `"/business/human-resources"` (full path, kebab-case) |
+| `"employees"` as route | Must be `"/business/human-resources/employees"` (includes parent) |
+| `Guid.NewGuid()` in seed data | Must use deterministic GUIDs (SHA256) |
+| Missing translations | Must have 4 languages: fr, en, it, de |
+| Missing NavigationApplicationSeedData | Menu invisible without Application level |
+
+---
+
+## DbContext Pattern (extensions)
+
+```csharp
+// In IExtensionsDbContext.cs:
+public DbSet<{Name}> {Name}s => Set<{Name}>();
+
+// In ExtensionsDbContext.cs (same line):
+public DbSet<{Name}> {Name}s => Set<{Name}>();
+```
+
+---
+
+## DI Registration Pattern
+
+```csharp
+// In DependencyInjection.cs or ServiceCollectionExtensions.cs:
+services.AddScoped<I{Name}Service, {Name}Service>();
+services.AddValidatorsFromAssemblyContaining<Create{Name}DtoValidator>();
+```
+
+---
+
+## Common Mistakes to Avoid
+
+| Mistake | Reality |
+|---------|---------|
+| `entity.SoftDelete()` | Does NOT exist — no soft delete in BaseEntity |
+| `entity.Code` inherited | Code is a business property — add it yourself |
+| `e.RowVersion` in config | Does NOT exist in BaseEntity |
+| `e.IsDeleted` filter | Does NOT exist — no soft delete |
+| `SmartStack.Api.Core.Routing` | Wrong — use `SmartStack.Api.Routing` |
+| `SystemEntity` base class | Does NOT exist — use `BaseEntity` for all |
+| `[Route] + [NavRoute]` | Only `[NavRoute]` needed (resolves route from DB) |
+| `SmartStack.Domain.Common.Interfaces` | Wrong — interfaces are in `SmartStack.Domain.Common` directly |
+| `[Authorize]` without `[RequirePermission]` | No RBAC enforcement — always use `[RequirePermission]` |
+| `tenantId: Guid.Empty` in services | OWASP A01 — always use `_currentUser.TenantId` |
+| Service without `ICurrentUser` | All tenant data leaks — inject `ICurrentUser` |
+| 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. |

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

@@ -17,8 +17,9 @@
 | Validate | MCP `validate_conventions` |
 
 **Rules:**
-- Inherit `AuditableEntity`, implement `IHasData` for multi-tenant
-- Audit fields: CreatedAt, CreatedBy, ModifiedAt, ModifiedBy
+- Inherit `BaseEntity`, implement `ITenantEntity` + `IAuditableEntity`
+- See `references/smartstack-api.md` for exact BaseEntity API (Id, CreatedAt, UpdatedAt only)
+- No Code/IsDeleted/RowVersion in BaseEntity — add business properties yourself
 - Domain events for state changes
 - Value objects for composite values
 
@@ -49,7 +50,8 @@
 
 ## Layer 1 — Application (parallel with API)
 
-**Services:** `Application/Services/{ContextPascal}/{App}/{Module}/`
+**Services:** `Application/Services/{ContextPascal}/{App}/{Module}/` (interface)
+**Service impls:** `Infrastructure/Services/{ContextPascal}/{App}/{Module}/` (implementation)
 **DTOs:** `Application/DTOs/{ContextPascal}/{App}/{Module}/`
 **Validators:** `Application/Validators/{ContextPascal}/{App}/{Module}/`
 
@@ -60,10 +62,13 @@
 | Validate | MCP `validate_conventions` |
 
 **Rules:**
+- **ALL services MUST inject `ICurrentUser` and filter by `TenantId`** (see `smartstack-api.md` Service Pattern)
+- **ALL services MUST inject `ILogger<T>`** for production diagnostics
 - CQRS with MediatR
 - FluentValidation for all commands
 - DTOs separate from domain entities
 - Service interfaces in Application, implementations in Infrastructure
+- **FORBIDDEN:** `tenantId: Guid.Empty`, queries without TenantId filter, services without ICurrentUser
 
 ---
 
@@ -96,27 +101,92 @@
 
 **Folder:** `Infrastructure/Persistence/Seeding/Data/{ModulePascal}/`
 
+> **Detailed templates:** See ralph-loop `references/core-seed-data.md` for complete C# code templates.
+> Navigation hierarchy: Context → Application → Module → Section → Resource (ALL levels need seed data).
+
 | Action | Tool |
 |--------|------|
 | Generate permissions | MCP `generate_permissions` (PRIMARY) |
-| Navigation seed | Template below |
-| Roles seed | Template below |
-| Provider | Template below |
-
-### Seed Data Chain (5 files)
-
-1. **NavigationModuleSeedData.cs** — Deterministic GUIDs (SHA256), 4 languages
-2. **PermissionsSeedData.cs** — MCP `generate_permissions` first, fallback template
-3. **RolesSeedData.cs** — Context-based: Admin=CRUD, Manager=CRU, Contributor=CR, Viewer=R
-4. **SeedConstants.cs** — Shared deterministic GUIDs
-5. **{App}SeedDataProvider.cs** — Implements IClientSeedDataProvider
-   - SeedNavigationAsync + SeedPermissionsAsync + SeedRolePermissionsAsync
+| Navigation seed | Templates below |
+| Roles seed | Templates below |
+| Provider | Templates below |
+
+### Seed Data Chain (7 files minimum)
+
+1. **NavigationApplicationSeedData.cs** — Application-level navigation entry (MUST be first)
+2. **NavigationModuleSeedData.cs** — Deterministic GUIDs (SHA256), 4 languages (fr, en, it, de)
+3. **NavigationSectionSeedData.cs** — Section-level navigation (if sections defined)
+4. **NavigationResourceSeedData.cs** — Resource-level navigation (if resources defined)
+5. **PermissionsSeedData.cs** — MCP `generate_permissions` first, fallback template
+6. **RolesSeedData.cs** — Context-based: Admin=CRUD, Manager=CRU, Contributor=CR, Viewer=R
+7. **{App}SeedDataProvider.cs** — Implements IClientSeedDataProvider
+   - `SeedNavigationAsync()` — seeds Application → Module → Section → Resource + translations
+   - `SeedPermissionsAsync()` + `SeedRolePermissionsAsync()`
    - DI: `services.AddScoped<IClientSeedDataProvider, {App}SeedDataProvider>()`
 
+### Deterministic GUID Pattern
+
+```csharp
+// Use SHA256 for deterministic GUIDs (reproducible across environments)
+public static readonly Guid ModuleId = GenerateDeterministicGuid("nav-module-{app}-{module}");
+
+private static Guid GenerateDeterministicGuid(string input)
+{
+    var hash = System.Security.Cryptography.SHA256.HashData(
+        System.Text.Encoding.UTF8.GetBytes(input));
+    var bytes = new byte[16];
+    Array.Copy(hash, bytes, 16);
+    return new Guid(bytes);
+}
+```
+
+### Route Convention (CRITICAL — Full Paths Required)
+
+> **Routes stored in DB drive the platform menu AND application-tracking.**
+> Short routes (e.g., `humanresources`) cause **400 Bad Request** on every page navigation.
+
+**Route format: `/{context}/{app-kebab}/{module-kebab}/{section-kebab}`**
+
+| Level | Code (C#) | Route (DB) |
+|-------|-----------|-----------|
+| Application | `humanresources` | `/business/human-resources` |
+| Module | `employees` | `/business/human-resources/employees` |
+| Section | `departments` | `/business/human-resources/employees/departments` |
+| Resource | `export` | `/business/human-resources/employees/departments/export` |
+
+**Platform examples (verified from SmartStack.app):**
+- `/platform/administration` (not `administration`)
+- `/platform/administration/users` (not `users`)
+- `/personal/myspace/profile` (not `profile`)
+
+- PascalCase for C# code identifiers (`HumanResources`)
+- **kebab-case** for ALL URL routes in seed data (`human-resources`)
+- **Routes MUST start with `/`** and include full parent hierarchy
+- Helper: `ToKebabCase()` transforms PascalCase → kebab-case
+
+```csharp
+private static string ToKebabCase(string value)
+    => System.Text.RegularExpressions.Regex.Replace(value, "(?<!^)([A-Z])", "-$1").ToLowerInvariant();
+
+// Route construction:
+var appRoute = $"/{ToKebabCase(contextCode)}/{ToKebabCase(appCode)}";
+// → "/business/human-resources"
+
+var moduleRoute = $"{appRoute}/{ToKebabCase(moduleCode)}";
+// → "/business/human-resources/employees"
+
+var sectionRoute = $"{moduleRoute}/{ToKebabCase(sectionCode)}";
+// → "/business/human-resources/employees/departments"
+```
+
 **FORBIDDEN:**
 - `Guid.NewGuid()` → use deterministic GUIDs (SHA256)
 - Missing translations (must have fr, en, it, de)
 - Empty seed classes with no seeding logic
+- PascalCase in route URLs → always kebab-case
+- Missing NavigationApplicationSeedData → menu invisible
+- **Short routes without `/` prefix** → `"humanresources"` must be `"/business/human-resources"`
+- **Routes without parent hierarchy** → `"employees"` must be `"/business/human-resources/employees"`
 
 ---