@atlashub/smartstack-cli 4.75.0 → 4.79.0

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

@@ -109,7 +109,6 @@ public static class NavigationApplicationSeedData
         return new NavigationApplicationSeedEntry
         {
             Id = ApplicationId,
-            Zone = ApplicationZone.Business,
             Code = "{appCode}",
             Label = "{appLabel_en}",
             Description = "{appDesc_en}",
@@ -117,7 +116,9 @@ public static class NavigationApplicationSeedData
             IconType = IconType.Lucide,
             Route = ToKebabCase("/{appCode}"),
             DisplayOrder = 1,
-            IsActive = true
+            IsActive = true,
+            IsOpen = false,                  // true => bypass permission checks (system apps only)
+            IsPersonal = false               // true => belongs to user personal scope (myspace)
         };
     }
 
@@ -199,7 +200,6 @@ public static class NavigationApplicationSeedData
 public class NavigationApplicationSeedEntry
 {
     public Guid Id { get; init; }
-    public ApplicationZone Zone { get; init; }
     public string Code { get; init; } = null!;
     public string Label { get; init; } = null!;
     public string? Description { get; init; }
@@ -208,6 +208,9 @@ public class NavigationApplicationSeedEntry
     public string? Route { get; init; }
     public int DisplayOrder { get; init; }
     public bool IsActive { get; init; }
+    // v3.46+ : ApplicationZone enum removed. Replaced by 2 boolean flags.
+    public bool IsOpen { get; init; }       // true => app accessible without permission checks
+    public bool IsPersonal { get; init; }   // true => app in user personal scope (myspace)
 }
 ```
 
@@ -404,12 +407,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 +436,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 +528,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 +544,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 +596,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` |
 
 ---
@@ -1367,7 +1372,7 @@ Before marking the task as completed, verify ALL:
 **Application-Level (FIRST — before modules):**
 - [ ] `NavigationApplicationSeedData.cs` created (once per application, at `Infrastructure/Persistence/Seeding/Data/`)
 - [ ] Application GUID is random (`Guid.NewGuid()`) — FK resolution is by Code lookup, not fixed ID
-- [ ] GetApplicationEntry() takes no parameters, includes `Zone = ApplicationZone.Business`
+- [ ] GetApplicationEntry() takes no parameters, includes `IsOpen = false` and `IsPersonal = false` (set `IsPersonal = true` only for myspace-scoped apps; set `IsOpen = true` only for public/system apps that should bypass permission checks). v3.46+ : `ApplicationZone` enum is removed — do NOT add `Zone = ...`
 - [ ] Application translations created (4 languages: fr, en, it, de, EntityType = Application), using `app.Id` (actual DB ID) for EntityId
 - [ ] `IClientSeedDataProvider.SeedNavigationAsync()` uses `NavigationApplicationSeedData` (NO hardcoded `{appLabel_en}` / `{appIcon}` placeholders)
 - [ ] `ApplicationRolesSeedData.ApplicationId` references `NavigationApplicationSeedData.ApplicationId` (DTO only — provider code resolves from DB by Code)

package/templates/skills/apex/references/domain-events-pattern.md

@@ -0,0 +1,45 @@
+# Domain Events (lightweight pub-sub)
+
+> Extracted from `smartstack-api.md` for clarity. Loaded only when generating code that needs events.
+
+SmartStack uses a minimal domain event pattern in `SmartStack.Domain.Support.Events`.
+
+## Interface + base class
+
+```csharp
+public interface IDomainEvent
+{
+    DateTime OccurredAt { get; }
+}
+
+public abstract class DomainEvent : IDomainEvent
+{
+    public DateTime OccurredAt { get; } = DateTime.UtcNow;
+}
+```
+
+## When to raise an event vs use a hook
+
+| Use case | Mechanism |
+|---|---|
+| Cross-cutting side effect tied to entity lifecycle (Create/Update/Delete) | Entity hook (`IAfterCreate<T>`, …) — see [entity-hooks-pattern.md](entity-hooks-pattern.md) |
+| Business event independent of CRUD (e.g. `WorkflowExecuted`, `LicenseRenewed`) | Domain event |
+| Need to handle multiple unrelated reactions to the same business fact | Domain event |
+| Reaction must be transactional with the entity write | Neither — code it inline in the handler |
+
+## Convention
+
+- One event class per business fact, named `{PastTense}Event` (e.g. `EmployeeOnboardedEvent`, `WorkflowExecutedEvent`).
+- Place events in `Domain/{Aggregate}/Events/`.
+- Inherit `DomainEvent` (gets `OccurredAt` for free).
+- Dispatched by handlers (no automatic publication from `SaveChangesAsync` in v3.46) — keep dispatch explicit so the handler controls timing.
+
+## Example dispatch (handler)
+
+```csharp
+await _mediator.Publish(new EmployeeOnboardedEvent(employee.Id, employee.TenantId), ct);
+```
+
+## Source
+
+- `D:/01 - projets/SmartStack.app/features/IA-Workflow/src/SmartStack.Domain/Support/Events/IDomainEvent.cs`

package/templates/skills/apex/references/entity-hooks-pattern.md

@@ -0,0 +1,68 @@
+# Entity Lifecycle Hooks (v3.46+)
+
+> Extracted from `smartstack-api.md` for clarity. Loaded only when generating code that needs hooks.
+
+SmartStack exposes 6 typed hook interfaces + 1 executor in `SmartStack.Application.Common.Interfaces.Hooks`.
+
+## Interfaces
+
+```csharp
+public interface IBeforeCreate<in T>  where T : class { int Order => 0; Task ExecuteAsync(T entity, CancellationToken ct = default); }
+public interface IAfterCreate<in T>   where T : class { int Order => 0; Task ExecuteAsync(T entity, CancellationToken ct = default); }
+public interface IBeforeUpdate<in T>  where T : class { int Order => 0; Task ExecuteAsync(T entity, CancellationToken ct = default); }
+public interface IAfterUpdate<in T>   where T : class { int Order => 0; Task ExecuteAsync(T entity, CancellationToken ct = default); }
+public interface IBeforeDelete<in T>  where T : class { int Order => 0; Task ExecuteAsync(T entity, CancellationToken ct = default); }
+public interface IAfterDelete<in T>   where T : class { int Order => 0; Task ExecuteAsync(T entity, CancellationToken ct = default); }
+
+public interface IHookExecutor
+{
+    Task ExecuteBeforeCreateAsync<T>(T entity, CancellationToken ct = default) where T : class;
+    Task ExecuteAfterCreateAsync<T>(T entity,  CancellationToken ct = default) where T : class;
+    Task ExecuteBeforeUpdateAsync<T>(T entity, CancellationToken ct = default) where T : class;
+    Task ExecuteAfterUpdateAsync<T>(T entity,  CancellationToken ct = default) where T : class;
+    Task ExecuteBeforeDeleteAsync<T>(T entity, CancellationToken ct = default) where T : class;
+    Task ExecuteAfterDeleteAsync<T>(T entity,  CancellationToken ct = default) where T : class;
+}
+```
+
+## Semantics
+
+- **`IBefore*`** runs **before** the entity is persisted. May transform the entity. May `throw` to cancel the operation (the calling handler does NOT call `SaveChangesAsync`).
+- **`IAfter*`** runs **after** `SaveChangesAsync` completes. Side-effects only (notifications, indexing, caches, integrations). Throwing here does NOT roll back the DB write — wrap risky calls.
+- **`Order`** (default 0) — lower runs earlier. Use `Order = -100` to pre-empt validation, `Order = 100` to run last.
+
+## DI registration (Infrastructure DependencyInjection.cs)
+
+```csharp
+services.AddScoped<IHookExecutor, HookExecutor>();
+services.AddScoped<IBeforeCreate<Employee>,  EmployeeValidationHook>();
+services.AddScoped<IAfterCreate<Employee>,   EmployeeWelcomeNotificationHook>();
+services.AddScoped<IAfterUpdate<Employee>,   EmployeeUpdatedAuditHook>();
+```
+
+## Usage in service / handler
+
+```csharp
+public async Task<EmployeeDto> CreateAsync(CreateEmployeeDto dto, CancellationToken ct)
+{
+    var entity = Employee.Create(dto.TenantId, dto.Code, dto.Name);
+    await _hooks.ExecuteBeforeCreateAsync(entity, ct);   // may throw → cancel
+    _db.Employees.Add(entity);
+    await _db.SaveChangesAsync(ct);
+    await _hooks.ExecuteAfterCreateAsync(entity, ct);    // post-commit side effects
+    return _mapper.Map<EmployeeDto>(entity);
+}
+```
+
+## DO / DON'T
+
+- DO use hooks for cross-cutting concerns (notifications, audit beyond `IAuditableEntity`, cache invalidation)
+- DO keep hooks small and idempotent — `IAfter*` runs without DB transaction
+- DON'T use hooks for business validation that varies per command — keep that in the handler / FluentValidation
+- DON'T register the same hook twice — DI picks all of them, and they all execute
+
+## Sources
+
+- `D:/01 - projets/SmartStack.app/features/IA-Workflow/src/SmartStack.Application/Common/Interfaces/Hooks/IBeforeCreate.cs`
+- `D:/01 - projets/SmartStack.app/features/IA-Workflow/src/SmartStack.Application/Common/Interfaces/Hooks/IAfterCreate.cs`
+- `D:/01 - projets/SmartStack.app/features/IA-Workflow/src/SmartStack.Application/Common/Interfaces/Hooks/IHookExecutor.cs` (and 4 more)

package/templates/skills/apex/references/licensing-enforcement.md

@@ -0,0 +1,52 @@
+# Licensing — `[RequiresLicense]` attribute (v3.46+)
+
+> Extracted from `smartstack-api.md` for clarity. Loaded only when generating code that needs license gating.
+
+Mark a Command or Query as requiring a valid license / feature / write capability.
+
+## Attribute definition
+
+```csharp
+namespace SmartStack.Application.Common.Licensing;
+
+[AttributeUsage(AttributeTargets.Class, AllowMultiple = true, Inherited = true)]
+public class RequiresLicenseAttribute : Attribute
+{
+    public string? Feature { get; }
+    public bool IsWriteOperation { get; }
+
+    public RequiresLicenseAttribute() { /* just needs valid license */ }
+    public RequiresLicenseAttribute(bool isWriteOperation) { /* blocked in read-only mode */ }
+    public RequiresLicenseAttribute(string feature, bool isWriteOperation = false) { /* both */ }
+}
+```
+
+## Usage on a Command
+
+```csharp
+[RequiresLicense(LicenseFeatures.AdvancedWorkflows, isWriteOperation: true)]
+public record CreateAdvancedWorkflowCommand(string Name, ...) : IRequest<WorkflowDto>;
+```
+
+## Behavior at runtime
+
+- A MediatR pipeline behavior reads the attribute on the request type.
+- `Feature` → checked against the cached `License.Features` (resolved per-tenant from JWT).
+- `IsWriteOperation = true` → blocked when the system is in read-only mode (license expired but in grace period, license downgraded, …).
+- Failures throw a typed exception → 403 Forbidden with a stable error code (`LICENSE_FEATURE_DISABLED`, `LICENSE_READ_ONLY`).
+
+## Where to read feature constants
+
+`SmartStack.Domain.Licensing.LicenseFeatures` (string consts — `Entra`, `AdvancedWorkflows`, `AiAdvanced`, …).
+
+## DO / DON'T
+
+- DO put `[RequiresLicense]` on the request (Command/Query), not on the handler
+- DO use `LicenseFeatures.X` constants — never magic strings
+- DON'T add `[RequiresLicense]` on `[AllowAnonymous]` endpoints — they bypass the pipeline
+- DON'T duplicate the check in the handler body — the pipeline already enforced it
+
+## Sources
+
+- `D:/01 - projets/SmartStack.app/features/IA-Workflow/src/SmartStack.Application/Common/Licensing/RequiresLicenseAttribute.cs`
+- `D:/01 - projets/SmartStack.app/features/IA-Workflow/src/SmartStack.Domain/Licensing/LicenseFeatures.cs`

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

@@ -75,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)
 
@@ -89,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 |
@@ -104,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)
 
@@ -135,6 +137,21 @@ bash references/checks/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 |
+
 ---
 
 ## Summary

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

@@ -16,10 +16,46 @@ public abstract class BaseEntity
     public Guid Id { get; set; }
     public DateTime CreatedAt { get; set; }
     public DateTime? UpdatedAt { get; set; }
+
+    // v3.46+ : JSON storage for SDK extension fields. Default "{}".
+    public string ExtensionData { get; private set; } = "{}";
 }
 ```
 
-**ONLY 3 properties.** No Code, no IsDeleted, no RowVersion, no SoftDelete, no CreatedBy/UpdatedBy.
+**4 inherited properties** (v3.46+). No Code, no IsDeleted, no RowVersion, no SoftDelete, no CreatedBy/UpdatedBy. `Code` is a business property — add it on the concrete entity. `CreatedBy`/`UpdatedBy` come from `IAuditableEntity` (separate interface).
+
+### ExtensionData — SDK custom fields (v3.46+)
+
+`BaseEntity.ExtensionData` is a JSON string allowing SDK clients to attach custom fields to ANY entity without schema migrations. The base class exposes 7 typed methods:
+
+```csharp
+// Read a typed value
+var color = entity.GetExtensionValue<string>("color");
+var meta  = entity.GetExtensionValue<MyMetadata>("meta");
+
+// Write
+entity.SetExtensionValue("color", "blue");
+entity.SetExtensionValue("meta", new MyMetadata { Tag = "vip" });
+
+// Inspect
+if (entity.HasExtensionValue("color")) { ... }
+var all = entity.GetAllExtensionData();           // IReadOnlyDictionary<string, JsonElement>
+
+// Bulk replace
+entity.SetAllExtensionData(new Dictionary<string, object?> { ["a"] = 1, ["b"] = 2 });
+
+// Cleanup
+entity.RemoveExtensionValue("color");             // returns bool
+entity.ClearExtensionData();                      // resets to "{}"
+```
+
+**Conventions:**
+- Serialization uses `JsonNamingPolicy.CamelCase` — `MyField` is stored as `"myField"`. Frontend consumers see camelCase.
+- Mutating methods automatically update `UpdatedAt`.
+- Backed by SQL Server `nvarchar(max)`. Map with `builder.Property(x => x.ExtensionData).HasColumnType("nvarchar(max)").HasDefaultValue("{}");` in EF config.
+- `ExtensionData` is for **client SDK extensions** — NOT for storing application-controlled data (use real columns for those).
+
+> Source : `D:/01 - projets/SmartStack.app/features/IA-Workflow/src/SmartStack.Domain/Common/BaseEntity.cs`
 
 ---
 
@@ -90,6 +126,38 @@ Verify in `Program.cs`: `JsonSerializerOptions.Converters.Add(new JsonStringEnum
 
 ---
 
+## File Storage — `StorageType` enum (v3.46+)
+
+```csharp
+namespace SmartStack.Domain.Common;
+
+public enum StorageType
+{
+    Normal = 0,   // Standard Azure Blob — deletable any time
+    Legal  = 1    // Azure Legal Hold — immutable, 10-year retention (Swiss law Art. 958f CO)
+}
+```
+
+**When to use `Legal`:**
+- Contracts, invoices, accounting documents (Swiss CO art. 958f → 10 years)
+- Audit logs that must survive deletion attempts (compliance, GDPR Art. 30)
+- Anything required by regulation to outlive the user's delete intent
+
+**When `Normal` is enough:**
+- User-uploaded avatars, attachments to tickets, message attachments, theme assets
+- Anything the user owns and can legitimately delete
+
+**Storage routing (Infrastructure):**
+- `Normal` → standard container (deletable, free tier eligible)
+- `Legal` → container with **Azure Blob immutable storage policy** + retention lock applied at upload
+- The choice is made by the entity author when creating the file — not a runtime toggle
+
+**AppSettings:** `appsettings.json` exposes both containers under `AzureStorage.Normal` and `AzureStorage.Legal` (with `EnableLegalHold` and `EnableRetentionPolicy` flags). Local dev uses `FileStorage.Normal/Legal` folders.
+
+> Source : `D:/01 - projets/SmartStack.app/features/IA-Workflow/src/SmartStack.Domain/Common/StorageType.cs`
+
+---
+
 ## Entity Patterns
 
 ### Tenant-scoped (most common)
@@ -333,6 +401,49 @@ public class {Name}Controller : ControllerBase
 
 **Sub-resource completeness:** If a parent page has a navigate() to a sub-resource route, the frontend MUST include a page for that route. Otherwise → dead link → white screen. Prefer separate controllers (with Suffix) over sub-endpoints in parent controller.
 
+### Core Controllers Exception (Bootstrap / Navigation / Config)
+
+A small set of **bootstrap controllers** uses `[Route("api/[controller]")]` instead of `[NavRoute]`. These are routed BEFORE the navigation registry is built from the DB, so they cannot use NavRoute.
+
+| Controller | Route | Reason |
+|---|---|---|
+| `BootstrapController` | `api/bootstrap` | Returns initial config (CSRF token, public flags) |
+| `NavigationController` | `api/navigation` | Returns the navigation menu — must run before NavRoute resolves |
+| `ConfigController` (if present) | `api/config` | Public app config (read-only) |
+| `AuthController` | `api/auth` | Login/refresh — runs before authenticated routes resolve |
+
+**Rules for core controllers:**
+- Use the classical `[Route("api/[controller]")]` attribute
+- Still apply `[Authorize]` and `[RequirePermission]` when applicable (most are anonymous-allowed)
+- Do NOT add to navigation seed data
+- POST-CHECK ignores these specific controller names when validating NavRoute usage
+
+**Do not extend this list arbitrarily.** Application/business controllers MUST use `[NavRoute]`. If you think a new controller belongs to the bootstrap set, justify it: the controller must run before navigation is loaded.
+
+---
+
+## Entity Lifecycle Hooks (v3.46+)
+
+6 typed hook interfaces + 1 executor in `SmartStack.Application.Common.Interfaces.Hooks` : `IBeforeCreate<T>`, `IAfterCreate<T>`, `IBeforeUpdate<T>`, `IAfterUpdate<T>`, `IBeforeDelete<T>`, `IAfterDelete<T>`, `IHookExecutor`. `IBefore*` may throw to cancel ; `IAfter*` runs post-commit (no rollback). Each has an `Order` property (default 0).
+
+**See [entity-hooks-pattern.md](entity-hooks-pattern.md)** for full interface signatures, DI registration, usage example, and DO/DON'T list.
+
+---
+
+## Domain Events (lightweight pub-sub)
+
+Minimal pattern in `SmartStack.Domain.Support.Events` : `IDomainEvent { OccurredAt }` + `DomainEvent` abstract base. Use **events** for business facts independent of CRUD ; use **hooks** for cross-cutting reactions tied to the entity lifecycle. Dispatch is explicit (no auto-publication from `SaveChangesAsync` in v3.46).
+
+**See [domain-events-pattern.md](domain-events-pattern.md)** for the full when-to-use table, naming convention, and dispatch example.
+
+---
+
+## Licensing — `[RequiresLicense]` attribute (v3.46+)
+
+Mark a Command or Query class as requiring a valid license, a specific feature (`LicenseFeatures.X`), or write capability (blocked in read-only mode). MediatR pipeline reads the attribute and throws 403 with stable error codes (`LICENSE_FEATURE_DISABLED`, `LICENSE_READ_ONLY`).
+
+**See [licensing-enforcement.md](licensing-enforcement.md)** for the attribute definition (3 constructors), usage on Commands, runtime behavior, feature constants location, and DO/DON'T.
+
 ---
 
 ## Navigation Seed Data (routes must be full paths)
@@ -343,10 +454,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

@@ -256,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

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        ║

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"