@atlashub/smartstack-cli 3.8.0 → 3.10.0

package/templates/skills/application/references/backend-controller-hierarchy.md

@@ -0,0 +1,58 @@
+# Controller NavRoute and Folder Hierarchy
+
+> Referenced from `steps/step-04-backend.md` — Controller file organization and NavRoute conventions.
+
+---
+
+## Controller File Location
+
+Controllers are organized by **context short name** and **application** (matching SmartStack.app pattern):
+
+```
+Api/Controllers/
+├── Admin/                     ← platform.administration
+│   ├── {Application}/         ← Application sub-folder (e.g., AI/, Communications/, Tenants/)
+│   │   └── {EntityName}Controller.cs
+│   └── {EntityName}Controller.cs  ← Direct controllers (no application sub-folder)
+├── Business/                  ← business.*
+│   └── {EntityName}Controller.cs
+├── Support/                   ← platform.support
+│   └── {EntityName}Controller.cs
+├── User/                      ← personal.*
+│   └── {EntityName}Controller.cs
+└── {SharedControllers}.cs     ← Root-level (Auth, Config, Navigation, etc.)
+```
+
+## Context-to-Folder Mapping
+
+| NavRoute Context | Controller Folder | Example |
+|-----------------|-------------------|---------|
+| `platform.administration` | `Admin` | `Controllers/Admin/TenantsController.cs` |
+| `platform.administration.{app}` | `Admin/{App}` | `Controllers/Admin/AI/AiPromptsController.cs` |
+| `platform.support` | `Support` | `Controllers/Support/TicketsController.cs` |
+| `business.*` | `Business` | `Controllers/Business/MyTicketsController.cs` |
+| `personal.*` | `User` | `Controllers/User/PreferencesController.cs` |
+
+## Controller Attributes
+
+The generated controller uses NavRoute attribute:
+
+```csharp
+[NavRoute("{full_path}")]
+[ApiController]
+[Authorize]
+public class {EntityName}Controller : ControllerBase
+{
+    [HttpGet]
+    [RequirePermission(Permissions.{Context}.{Application}.{Module}.Read)]
+    public async Task<ActionResult<IEnumerable<{EntityName}Dto>>> GetAll() { ... }
+
+    // ... other CRUD methods
+}
+```
+
+This ensures:
+- API route is derived from navigation path
+- Permissions use the constants from Permissions.cs
+- Frontend can discover API path from NavRoute registry
+- Controller file is in the correct context/application folder

package/templates/skills/application/references/backend-entity-seeding.md

@@ -0,0 +1,72 @@
+# Entity Seeding Pattern
+
+> Reference: See `templates-seed.md` section "TEMPLATE: ENTITY SEED DATA (SeedData Provider)"
+
+## SeedData File
+
+**`Infrastructure/Persistence/Seeding/Data/{Domain}/{EntityName}SeedData.cs`**
+
+Follow SmartStack.app pattern:
+- Static class with `internal static IEnumerable<{EntityName}SeedItem> GetAll{EntityName}s()`
+- Use deterministic GUIDs (NEVER `Guid.NewGuid()`)
+- Include 3-5 sample entities with varied, realistic data
+- For multi-tenant: organize by tenant using `GetTenant1{EntityName}s()` helpers
+
+```csharp
+public static class {EntityName}SeedData
+{
+    public static readonly Guid Sample1Id = Guid.Parse("...");
+    public static readonly Guid Sample2Id = Guid.Parse("...");
+    public static readonly Guid Sample3Id = Guid.Parse("...");
+
+    internal static IEnumerable<{EntityName}SeedItem> GetAll{EntityName}s()
+    {
+        return new[]
+        {
+            new {EntityName}SeedItem { Id = Sample1Id, /* ... */ },
+            new {EntityName}SeedItem { Id = Sample2Id, /* ... */ },
+            new {EntityName}SeedItem { Id = Sample3Id, /* ... */ }
+        };
+    }
+}
+
+internal class {EntityName}SeedItem
+{
+    public Guid Id { get; init; }
+    // ... all required entity properties
+}
+```
+
+## DevDataSeeder Update
+
+Add to `Infrastructure/Persistence/Seeding/DevDataSeeder.cs`:
+- `using` for the new SeedData namespace
+- `await Seed{EntityName}sAsync(cancellationToken);` in `SeedAsync()` method
+
+```csharp
+private async Task Seed{EntityName}sAsync(CancellationToken cancellationToken)
+{
+    _logger.LogInformation("Seeding demo {EntityName}s...");
+
+    var existingCount = await _context.{EntityName}s.CountAsync(cancellationToken);
+    if (existingCount > 0)
+    {
+        _logger.LogWarning("{EntityName}s already seeded ({Count} exist), skipping.", existingCount);
+        return;
+    }
+
+    var createdCount = 0;
+    foreach (var seedItem in {EntityName}SeedData.GetAll{EntityName}s())
+    {
+        var entity = {EntityName}.Create(/* map seedItem properties */);
+        typeof({EntityName}).GetProperty("Id")?.SetValue(entity, seedItem.Id);
+        _context.{EntityName}s.Add(entity);
+        createdCount++;
+    }
+
+    if (createdCount > 0)
+        await _context.SaveChangesAsync(cancellationToken);
+
+    _logger.LogInformation("Created {Count} demo {EntityName}s.", createdCount);
+}
+```

package/templates/skills/application/references/backend-verification.md

@@ -0,0 +1,88 @@
+# Backend Post-Generation Verification
+
+**Run ALL checks before proceeding to next step.**
+
+## Check 1: Backend Build (BLOCKING)
+
+```bash
+dotnet build {SolutionName}.sln --no-restore
+```
+
+IF build fails: Read errors, fix compilation issues, re-run until success.
+
+## Check 2: DbSet Registration (BLOCKING)
+
+Search for `DbSet<{EntityName}>` in `I{DbContextName}.cs` or `{DbContextName}.cs`.
+
+IF NOT found, add:
+```csharp
+public DbSet<{EntityName}> {EntityName}s => Set<{EntityName}>();
+```
+
+## Check 3: DI Registration (BLOCKING)
+
+Search for `I{EntityName}Service` in `DependencyInjection.cs`.
+
+IF NOT found, add:
+```csharp
+services.AddScoped<I{EntityName}Service, {EntityName}Service>();
+```
+
+## Check 4: RequirePermission Attributes (BLOCKING)
+
+Each HTTP action MUST have `[RequirePermission(Permissions.{Context}.{Application}.{Module}.{Action})]`.
+
+## Check 5: Entity Configuration (BLOCKING)
+
+Verify:
+- `builder.ToTable("{table_prefix}{EntityName}s")` uses correct prefix
+- `builder.HasKey(e => e.Id)` present
+- `builder.HasIndex` for unique fields
+
+## Check 5b: Seeding Infrastructure (first entity only)
+
+**If this is the FIRST entity (no existing DevDataSeeder):**
+
+1. **`Infrastructure/Persistence/Seeding/Data/SeedConstants.cs`**
+```csharp
+namespace {BaseNamespace}.Infrastructure.Persistence.Seeding.Data;
+public static class SeedConstants
+{
+    public static readonly DateTime SeedDate = new(2024, 1, 1, 0, 0, 0, DateTimeKind.Utc);
+}
+```
+
+2. **`Infrastructure/Persistence/Seeding/DevDataSeeder.cs`**
+```csharp
+public class DevDataSeeder : IDevDataSeeder
+{
+    private readonly ExtensionsDbContext _context;
+    private readonly ILogger<DevDataSeeder> _logger;
+    public DevDataSeeder(ExtensionsDbContext context, ILogger<DevDataSeeder> logger) { _context = context; _logger = logger; }
+    public async Task SeedAsync(CancellationToken cancellationToken = default)
+    {
+        _logger.LogInformation("Starting development data seeding...");
+        // Add Seed{Entity}sAsync calls here
+        _logger.LogInformation("Development data seeding complete.");
+    }
+}
+```
+
+3. Register: `services.AddScoped<IDevDataSeeder, DevDataSeeder>();`
+
+## Check 5c: SqlObjects Directory (first entity only)
+
+**If no existing SqlObjectHelper:**
+
+1. **`Infrastructure/Persistence/SqlObjects/SqlObjectHelper.cs`** - Helper for embedded SQL resources
+2. Create `Infrastructure/Persistence/SqlObjects/Functions/` directory
+3. Ensure `.csproj` has: `<EmbeddedResource Include="Persistence\SqlObjects\**\*.sql" />`
+
+## Check 6: Convention Validation (RECOMMENDED)
+
+```
+Tool: mcp__smartstack__validate_conventions
+Args: target: "backend", scope: "{entity_name}"
+```
+
+Verifies naming conventions, architecture layers, required attributes, DTO patterns.

package/templates/skills/application/references/frontend-verification.md

@@ -0,0 +1,111 @@
+# Frontend: Routing Rules & Post-Generation Verification
+
+> Reference for step-05-frontend.md — routing rules and mandatory verification checks.
+
+## Routing Rules
+
+### Rule 1: Routes MUST be inside Layout wrappers
+
+**CRITICAL:** All routes MUST be nested inside the appropriate context layout. This is what provides the SmartStack shell (header with AvatarMenu, sidebar, navigation).
+
+```tsx
+// CORRECT - Inside BusinessLayout (shell renders: header + AvatarMenu + sidebar)
+<Route path="/business" element={<BusinessLayout />}>
+  <Route path="sales/products" element={<ProductsPage />} />
+</Route>
+
+// FORBIDDEN - Outside layout (NO shell, NO header, NO AvatarMenu!)
+<Route path="/business/sales/products" element={<ProductsPage />} />
+```
+
+### Rule 2: Use nested routes (not flat)
+
+**CRITICAL:** SmartStack requires NESTED routes within the layout:
+
+```tsx
+// CORRECT - Nested routes inside layout
+<Route path="/business" element={<BusinessLayout />}>
+  <Route path="sales">
+    <Route index element={<Navigate to="products" replace />} />
+    <Route path="products" element={<ProductsPage />} />
+    <Route path="orders" element={<OrdersPage />} />
+  </Route>
+</Route>
+
+// FORBIDDEN - Flat routes (cause redirect issues + bypass layout)
+<Route path="/business/sales" element={<Navigate to="products" />} />
+<Route path="/business/sales/products" element={<ProductsPage />} />
+```
+
+## Post-Generation Verification (MANDATORY)
+
+**Before proceeding to step-06, run these checks on ALL generated frontend files:**
+
+### 1. CSS Variables Check (BLOCKING)
+
+Scan all generated `.tsx` files for hardcoded Tailwind colors:
+
+```
+FORBIDDEN patterns: bg-blue-, bg-red-, bg-green-, bg-gray-, bg-amber-,
+                    text-blue-, text-red-, text-green-, text-gray-, text-amber-,
+                    border-blue-, border-red-, border-green-, border-gray-
+```
+
+If ANY hardcoded color is found → **FIX IT** using CSS variables from style-guide.md before continuing.
+
+### 2. API Client Check (BLOCKING)
+
+Verify all API service files use the configured client:
+- **CORRECT:** `import { api } from '@/services/api/apiClient'` or `import api from '../api'`
+- **FORBIDDEN:** `import axios from 'axios'`
+
+### 3. EntityCard Check
+
+If a grid/card view is generated, verify it uses `EntityCard` component (not custom divs).
+
+### 4. i18n Check (BLOCKING)
+
+Verify exactly **4 language files** exist with identical key structures:
+- `fr/{entityCode}.json`
+- `en/{entityCode}.json`
+- `it/{entityCode}.json`
+- `de/{entityCode}.json`
+
+### 5. Route Check (BLOCKING)
+
+Verify routes are:
+- **INSIDE** the Layout wrapper (`BusinessLayout`, `AdminLayout`, or `UserLayout`)
+- **NESTED** (not flat)
+- Following path convention: `/{context}/{application}/{module}`
+
+### 6. States Check
+
+Verify the list page includes:
+- Loading state (spinner)
+- Error state (icon + message + retry button)
+- Empty state (icon + message)
+
+### 7. TypeScript Build Check (BLOCKING)
+
+Run the frontend type check to verify all generated files compile:
+
+```bash
+cd web && npx tsc --noEmit 2>&1 | head -50
+```
+
+OR if the project uses a build script:
+
+```bash
+cd web && npm run build 2>&1 | head -80
+```
+
+IF type errors exist **in generated files**: Fix them before proceeding.
+Common issues: missing imports, wrong interface names, incorrect prop types, missing hook return types.
+
+IF type errors exist **in other pre-existing files**: NON-BLOCKING. Note them but proceed.
+
+**Focus only on errors in files generated by this step:**
+- `pages/{context}/{application}/{module}/*.tsx`
+- `services/api/{entityCode}Api.ts`
+- `types/{entityName}.types.ts`
+- `hooks/use{EntityName}*.ts`

package/templates/skills/application/references/nav-fallback-procedure.md

@@ -0,0 +1,200 @@
+# Navigation: Fallback Procedure (When MCP Unavailable)
+
+> Reference for step-01-navigation.md — generates navigation seeds following SmartStack.app patterns.
+> Reference: `templates-seed.md` for code templates.
+>
+> **Branch by Project Type:**
+> - If `{seeding_strategy}` = "hasdata" (core project): Follow F1-F8 below
+> - If `{seeding_strategy}` = "provider" (client project): Follow **CLIENT PROJECT HANDLING** in step file
+
+## F1. Read Existing Configuration Files
+
+**CRITICAL:** Before generating any code, read existing files to determine state:
+
+1. **Find the Navigation Configuration directory:**
+   ```
+   Glob: **/Persistence/Configurations/Navigation/Navigation*Configuration.cs
+   ```
+
+2. **Read NavigationTranslationConfiguration.cs** - Find the last GUID index:
+   ```
+   Search for: the last call to GenerateGuid(index++)
+   The index variable starts at 1 and increments per translation entry.
+   Your new translations MUST continue from the next index value.
+   ```
+
+3. **Read Navigation{Level}Configuration.cs** - Check existing entities:
+   ```
+   Read the Configuration for the target level (Context, Application, Module, Section).
+   Check if it already references a SeedData class: builder.HasData(Navigation{Level}SeedData.GetSeedData())
+   If yes: Read the corresponding SeedData class to find existing entries.
+   If no: You will need to add HasData() call.
+   ```
+
+4. **Read existing SeedData files** (if they exist):
+   ```
+   Glob: **/Seeding/Data/Navigation/Navigation{Level}SeedData.cs
+   Check for existing entity IDs to avoid collisions.
+   ```
+
+## F2. Determine Parent GUID
+
+For non-context levels, find the parent entity GUID:
+
+| Level | Parent | Where to Find Parent GUID |
+|-------|--------|---------------------------|
+| application | context | `NavigationContextSeedData.cs` → e.g. `PlatformContextId` |
+| module | application | `NavigationApplicationSeedData.cs` → e.g. `AdministrationAppId` |
+| section | module | `NavigationModuleSeedData.cs` → e.g. `UsersModuleId` |
+
+Read the parent SeedData class and find the GUID matching `{parent_path}`.
+
+## F3. Generate Navigation Entity GUID
+
+Generate a deterministic GUID for the new navigation entity:
+
+```csharp
+// Use SHA256 hash of the full_path for deterministic generation
+using var sha256 = System.Security.Cryptography.SHA256.Create();
+var hash = sha256.ComputeHash(Encoding.UTF8.GetBytes("navigation-{level}-{full_path}"));
+var guid = new Guid(hash.Take(16).ToArray());
+```
+
+**Rules:**
+- NEVER use `Guid.NewGuid()`
+- Read existing SeedData GUIDs to verify no collision
+- Store result as `{navigation_guid}`
+
+## F4. Write Navigation Entity Seed
+
+Based on `{level}`, write the seed entry.
+
+**Option A: Project uses SeedData classes (SmartStack.app pattern)**
+
+If `Navigation{Level}SeedData.cs` exists, add the new entity:
+
+```csharp
+// In Infrastructure/Persistence/Seeding/Data/Navigation/Navigation{Level}SeedData.cs
+
+// Add static GUID field
+public static readonly Guid {PascalCode}Id = Guid.Parse("{navigation_guid}");
+
+// Add to GetSeedData() return array
+new {
+    Id = {PascalCode}Id,
+    ParentFk = Navigation{ParentLevel}SeedData.{ParentPascalCode}Id,  // FK varies by level
+    Code = "{code}",
+    Label = "{labels.en}",
+    Description = "{descriptions.en}",
+    Icon = "{icon}",
+    IconType = IconType.Lucide,
+    Route = "/{full_path_with_slashes}",
+    DisplayOrder = {display_order},
+    IsActive = true,
+    CreatedAt = SeedConstants.SeedDate
+}
+```
+
+**FK property by level:**
+
+| Level | FK Property | References |
+|-------|-------------|------------|
+| context | (none) | - |
+| application | `ContextId` | NavigationContextSeedData.{Parent}Id |
+| module | `ApplicationId` | NavigationApplicationSeedData.{Parent}Id |
+| section | `ModuleId` | NavigationModuleSeedData.{Parent}Id |
+
+**Option B: Project uses inline HasData**
+
+If no SeedData class exists, add directly to `Navigation{Level}Configuration.cs`:
+
+```csharp
+// In Configure method, add:
+builder.HasData(new {
+    Id = Guid.Parse("{navigation_guid}"),
+    // ... same properties as Option A
+});
+```
+
+## F5. Write Translation Entries
+
+Add 4 translation entries to `NavigationTranslationConfiguration.cs`:
+
+1. Read the file to find the current highest `index` value
+2. Continue from `index + 1`
+3. Use the SAME `GenerateGuid` method already defined in the file:
+
+```csharp
+// In GetSeedData() method, add at the end before return:
+
+// {level}: {code} translations
+translations.Add(new {
+    Id = GenerateGuid(index++),
+    EntityType = NavigationEntityType.{Level},
+    EntityId = Navigation{Level}SeedData.{PascalCode}Id,  // or Guid.Parse("{navigation_guid}")
+    LanguageCode = "fr",
+    Label = "{labels.fr}",
+    Description = "{descriptions.fr}",
+    CreatedAt = seedDate
+});
+translations.Add(new {
+    Id = GenerateGuid(index++),
+    EntityType = NavigationEntityType.{Level},
+    EntityId = Navigation{Level}SeedData.{PascalCode}Id,
+    LanguageCode = "en",
+    Label = "{labels.en}",
+    Description = "{descriptions.en}",
+    CreatedAt = seedDate
+});
+translations.Add(new {
+    Id = GenerateGuid(index++),
+    EntityType = NavigationEntityType.{Level},
+    EntityId = Navigation{Level}SeedData.{PascalCode}Id,
+    LanguageCode = "it",
+    Label = "{labels.it}",
+    Description = "{descriptions.it}",
+    CreatedAt = seedDate
+});
+translations.Add(new {
+    Id = GenerateGuid(index++),
+    EntityType = NavigationEntityType.{Level},
+    EntityId = Navigation{Level}SeedData.{PascalCode}Id,
+    LanguageCode = "de",
+    Label = "{labels.de}",
+    Description = "{descriptions.de}",
+    CreatedAt = seedDate
+});
+```
+
+## F6. Store Result
+
+```
+{navigation_guid} = [generated GUID]
+{seed_method} = "fallback"  // Indicates MCP was not used
+```
+
+## F7. Validation Checklist
+
+Before proceeding, verify:
+- [ ] Deterministic GUID generated (not NewGuid())
+- [ ] 4 languages present (fr, en, it, de)
+- [ ] Translation index continues existing sequence (no gaps, no collisions)
+- [ ] Parent GUID correctly references existing entity
+- [ ] Route path matches `/{context}/{app}/{module}` pattern
+- [ ] DisplayOrder is consistent with existing entities
+- [ ] Code is WRITTEN to files, not just displayed
+
+## F8. Present Summary
+
+```markdown
+## Navigation Seeds Generated (Fallback)
+
+**Entity:** {level} - {code}
+**GUID:** {navigation_guid}
+**Path:** {full_path}
+
+### Files Updated
+
+1. **Navigation{Level}SeedData.cs** (or Configuration.cs) - New entity entry
+2. **NavigationTranslationConfiguration.cs** - 4 translation entries added
+```

package/templates/skills/application/references/provider-template.md

@@ -0,0 +1,158 @@
+# IClientSeedDataProvider Template
+
+> Referenced from `steps/step-03b-provider.md` — C# template for client project seed data providers.
+
+---
+
+## Provider Class Template
+
+**Location:** `Infrastructure/Persistence/Seeding/{AppPascalName}SeedDataProvider.cs`
+
+Where `{AppPascalName}` is derived from the application code (e.g., `free-bike` → `FreeBike`).
+
+```csharp
+using Microsoft.EntityFrameworkCore;
+using SmartStack.Application.Common.Interfaces;
+using SmartStack.Domain.Navigation;
+using SmartStack.Domain.Platform.Administration.Roles;
+
+namespace {BaseNamespace}.Infrastructure.Persistence.Seeding;
+
+/// <summary>
+/// Seeds {AppLabel} navigation, roles, permissions, and role-permission data
+/// into the SmartStack Core schema at application startup.
+/// Implements <see cref="IClientSeedDataProvider"/> for runtime seeding
+/// (no Core migrations required).
+/// </summary>
+public class {AppPascalName}SeedDataProvider : IClientSeedDataProvider
+{
+    public int Order => 100;
+
+    public async Task SeedNavigationAsync(ICoreDbContext context, CancellationToken ct)
+    {
+        // Check idempotence
+        var exists = await context.NavigationApplications
+            .AnyAsync(a => a.Code == "{app_code}", ct);
+        if (exists) return;
+
+        // 1. Retrieve the parent context ("business", "platform", etc.)
+        var parentContext = await context.NavigationContexts
+            .FirstAsync(c => c.Code == "{context_code}", ct);
+
+        // 2. Create the application
+        var app = NavigationApplication.Create(
+            parentContext.Id,
+            "{app_code}",
+            "{app_label_en}",
+            "{app_desc_en}",
+            "{app_icon}",
+            IconType.Lucide,
+            "/{context_code}/{app_code}",
+            {display_order});
+        context.NavigationApplications.Add(app);
+        await ((DbContext)context).SaveChangesAsync(ct);
+
+        // 3. Create modules
+        // Use GUIDs and data from {Module}NavigationSeedData.cs
+        foreach (var moduleData in GetModuleSeedEntries(app.Id))
+        {
+            var module = NavigationModule.Create(
+                moduleData.ApplicationId,
+                moduleData.Code,
+                moduleData.Label,
+                moduleData.Description,
+                moduleData.Icon,
+                IconType.Lucide,
+                moduleData.Route,
+                moduleData.DisplayOrder);
+            context.NavigationModules.Add(module);
+        }
+        await ((DbContext)context).SaveChangesAsync(ct);
+
+        // 4. Create translations (4 languages per entity)
+        // Use data from {Module}NavigationTranslationSeedData.cs
+        // ...
+        await ((DbContext)context).SaveChangesAsync(ct);
+    }
+
+    public async Task SeedRolesAsync(ICoreDbContext context, CancellationToken ct)
+    {
+        // Check idempotence
+        var applicationId = ApplicationRolesSeedData.ApplicationId;
+        var exists = await context.Roles
+            .AnyAsync(r => r.ApplicationId == applicationId, ct);
+        if (exists) return;
+
+        // Create application-scoped roles (Admin, Manager, Contributor, Viewer)
+        // Use data from ApplicationRolesSeedData.cs
+        foreach (var entry in ApplicationRolesSeedData.GetRoleEntries())
+        {
+            var role = Role.Create(
+                entry.Code,
+                entry.Name,
+                entry.Description,
+                entry.ApplicationId,
+                entry.IsSystem);
+            context.Roles.Add(role);
+        }
+        await ((DbContext)context).SaveChangesAsync(ct);
+    }
+
+    public async Task SeedPermissionsAsync(ICoreDbContext context, CancellationToken ct)
+    {
+        // Check idempotence
+        var exists = await context.Permissions
+            .AnyAsync(p => p.Path == "{full_path}.*", ct);
+        if (exists) return;
+
+        // Retrieve modules by Code for FK resolution
+        // Use data from {Module}PermissionSeedData.cs
+        // Create via Permission.CreateForModule(...) and Permission.CreateWildcard(...)
+        // ...
+        await ((DbContext)context).SaveChangesAsync(ct);
+    }
+
+    public async Task SeedRolePermissionsAsync(ICoreDbContext context, CancellationToken ct)
+    {
+        // Check idempotence
+        var exists = await context.RolePermissions
+            .AnyAsync(rp => rp.Permission!.Path.StartsWith("{full_path}."), ct);
+        if (exists) return;
+
+        // Retrieve existing roles and created permissions
+        // Use data from {Module}RolePermissionSeedData.cs
+        // Create via RolePermission.Create(roleId, permissionId, "system")
+        // ...
+        await ((DbContext)context).SaveChangesAsync(ct);
+    }
+
+    // Private helper methods fed by SeedData classes
+    // ...
+}
+```
+
+---
+
+## DI Registration
+
+Modify `Infrastructure/DependencyInjection.cs` of the client project:
+
+```csharp
+// Add using:
+using SmartStack.Application.Common.Interfaces;
+
+// In the registration method:
+services.AddScoped<IClientSeedDataProvider, {AppPascalName}SeedDataProvider>();
+```
+
+---
+
+## Critical Rules
+
+1. **Factory methods mandatory**: `NavigationModule.Create(...)`, `Role.Create(...)`, `Permission.CreateForModule(...)`, `RolePermission.Create(...)` — NEVER `new Entity()`
+2. **Idempotence**: Each Seed method checks existence before inserting
+3. **SaveChangesAsync per group**: Navigation → save → Roles → save → Permissions → save → RolePermissions → save
+4. **Execution order**: `SeedRolesAsync()` MUST be called BEFORE `SeedRolePermissionsAsync()` (roles must exist before mapping)
+5. **Deterministic GUIDs**: Use IDs from SeedData classes (not `Guid.NewGuid()`)
+6. **Resolve FK by Code**: Parent modules and roles are found by `Code`, not hardcoded GUID
+7. **Order property**: Use `100` as default. If multiple providers exist, they run in Order sequence