@atlashub/smartstack-cli 4.76.0 → 4.79.0

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/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)

package/templates/skills/apex-verify/steps/step-01-nav-audit.md

@@ -78,6 +78,10 @@ For each issue found, create a finding:
 | NAV-003 | BLOCKING | Route contains forbidden segment (/detail/, /create/, /edit/) |
 | NAV-004 | WARNING | Reserved section code with IsActive = false (acceptable but unnecessary) |
 | NAV-005 | WARNING | Section code not in kebab-case |
+| NAV-006 | WARNING (v3.46) | `ApplicationZone` enum referenced in seed data — must use `IsPersonal`/`IsOpen` flags (cf. seed-checks.sh check **C66**, will become BLOCKING in v3.47) |
+| NAV-007 | WARNING (v3.46) | Legacy layouts `AdminLayout`/`BusinessLayout`/`UserLayout`/`HRLayout`/`SalesLayout` referenced — must use `AppLayout` (cf. seed-checks.sh check **C67**, will become BLOCKING in v3.47) |
+
+**Note** : NAV-006 and NAV-007 mirror the bash post-checks **C66**/**C67** in `apex/references/checks/seed-checks.sh`. The bash checks emit `WARNING` (no FAIL) during the v3.46 grace period — apex-verify should align with the same severity.
 
 ---
 

package/templates/skills/application/references/contexts-cheatsheet.md

@@ -0,0 +1,86 @@
+# SmartStack Contexts — Cheatsheet
+
+> **Reference for `application` skill** — quick lookup of the 10 system contexts exposed by `<SmartStackProvider>`.
+
+## When This Reference Applies
+
+- You generate a component that needs to read auth/tenant/theme state
+- You audit a page that re-implements existing context state
+- The user asks "how do I read the current tenant", "how do I check a permission", "where is the SignalR connection"
+
+---
+
+## The 10 contexts (state map)
+
+| # | Context | Hook | State exposed | Example use case |
+|---|---|---|---|---|
+| 1 | AuthContext | `useAuth()` | `user`, `roles`, `permissions`, `isAuthenticated`, `login()`, `logout()`, `refresh()`, `hasPermission(path)` | Read current user, check permission gate |
+| 2 | TenantContext | `useTenant()` | `currentTenant`, `userTenants`, `isGlobalView`, `switchTenant(id)` | Display tenant switcher, scope a query |
+| 3 | NavigationContext | `useNavigation()` | `menu` (MenuDto), `reload()`, `currentApp`, `currentModule`, `currentSection`, `isLoading`, `getApplicationsByZone()` (back-compat alias) | Render sidebar, breadcrumb, route resolution |
+| 4 | ThemeContext | `useTheme()` | `mode`, `selectedTheme`, `selectedPreset`, `setMode()`, `setTheme(id)`, `setPreset(id)` | Toggle dark mode, switch theme |
+| 5 | LicenseContext | `useLicense()` | `license`, `isFeatureEnabled(code)`, `hasModule(code)` | Gate a feature behind license |
+| 6 | SignalRContext | `useSignalR()` | `isConnected`, `on(event, handler)`, `off(event, handler)`, `emit(event, payload)` | Real-time notifications |
+| 7 | FavoritesContext | `useFavorites()` | `favorites`, `toggleFavorite(item)`, `isFavorite(id)` | Bookmark a page/entity |
+| 8 | SidebarContext | `useSidebar()` | `isCollapsed`, `toggle()`, `setCollapsed(value)` | Sidebar collapse button |
+| 9 | FeatureConfigContext | `useFeatureConfig()` | `features` (record from `/api/config/public`) | Feature flag, A/B test |
+| 10 | DocPanelContext | `useDocPanel()` | `isOpen`, `toggle()`, `openDoc(slug)` | Contextual help panel |
+
+---
+
+## Common patterns
+
+### Permission check — render guard
+
+```tsx
+const { hasPermission } = useAuth();
+if (!hasPermission('administration.users.create')) return <Forbidden />;
+```
+
+### Tenant-scoped query
+
+```tsx
+const { currentTenant } = useTenant();
+const { data } = useQuery(
+  ['orders', currentTenant?.id],
+  () => orderApi.list({ tenantId: currentTenant?.id })
+);
+```
+
+### Real-time updates
+
+```tsx
+const { on, off } = useSignalR();
+useEffect(() => {
+  const handler = (notif) => toast(notif.message);
+  on('NotificationReceived', handler);
+  return () => off('NotificationReceived', handler);
+}, []);
+```
+
+### Feature flag
+
+```tsx
+const { isFeatureEnabled } = useLicense();
+if (isFeatureEnabled('ai-assistant')) return <AiAssistant />;
+```
+
+---
+
+## DO / DON'T
+
+| ✅ DO | ❌ DON'T |
+|---|---|
+| Consume contexts via the provided hooks | `useContext(SmartStackContext)` directly |
+| Memoize derived values from context | Re-compute on every render |
+| Subscribe/unsubscribe SignalR handlers in `useEffect` cleanup | Forget to `off()` (memory leak) |
+| Treat `permissions` as opaque strings | Parse permissions client-side |
+| Read tenant from `currentTenant`, not URL | Trust the URL slug as a source of truth |
+
+---
+
+## Reference source files (read-only)
+
+- `D:\01 - projets\SmartStack.app\features\IA-Workflow\web\smartstack-web\src\contexts\` (all 10 files)
+- `D:\01 - projets\SmartStack.app\features\IA-Workflow\web\smartstack-web\src\provider\SmartStackProvider.tsx` (wrapping order)
+
+See [smartstack-provider.md](smartstack-provider.md) for the wrapping order.

package/templates/skills/application/references/extensions-system.md

@@ -0,0 +1,158 @@
+# Extension System — Slot/Fill, Page Overrides, Hooks
+
+> **Reference for `application` skill** — how a client project enriches a SmartStack page without forking the SDK.
+
+## When This Reference Applies
+
+- Client wants to inject content into an existing SmartStack page (header action, table column, side panel)
+- Client wants to fully replace a built-in page with a custom one
+- Client needs to react to navigation/auth/tenant lifecycle events
+- The user asks "how do I add a column to UsersList", "how do I override the AdministrationDashboard page", "how do I customize a SmartStack form"
+
+---
+
+## Three extension mechanisms
+
+### 1. Page overrides — `componentRegistry` + `PageRegistry`
+
+Override a built-in page by registering your component under the same key :
+
+```tsx
+// In your client componentRegistry.generated.ts (or a custom registry.ts)
+import { PageRegistry } from '@atlashub/smartstack';
+import { lazy } from 'react';
+
+PageRegistry.register(
+  'administration.users',                       // built-in key — replaces SmartStack page
+  lazy(() => import('@/pages/MyCustomUsers')),  // your component
+);
+
+// Or via SmartStackConfig.extensions.pages (declarative)
+const config: SmartStackConfig = {
+  apiUrl: '...',
+  extensions: {
+    pages: {
+      'administration.users': () => import('@/pages/MyCustomUsers'),
+    },
+  },
+};
+```
+
+The `DynamicRouter` calls `PageRegistry.resolve(componentKey)` and your override wins.
+
+> **Tip** — for net-new pages on client-defined routes, prefer the MCP tool `mcp__smartstack__scaffold_routes` to keep `componentRegistry.generated.ts` consistent.
+
+### 2. Slot / Fill — render-prop injection
+
+Inject content into a named slot exposed by a SmartStack page :
+
+```tsx
+import { Fill } from '@atlashub/smartstack';
+
+// Inject into the slot 'users.header.actions'
+<Fill slot="users.header.actions">
+  <button onClick={...}>My custom action</button>
+</Fill>
+```
+
+Available slot names follow the convention `{section}.{location}.{purpose}` (see `extensions/types.ts` SlotName union for the full list — examples : `users.header.actions`, `users.table.columns.before`, `users.table.row.actions`, `users.form.fields.after`, `users.detail.tabs.after`).
+
+You can declare slots once via `SmartStackConfig.extensions.slots` :
+
+```ts
+extensions: {
+  slots: {
+    'users.header.actions': MyHeaderWidget,
+    'dashboard.kpi.before': MyKpi,
+  }
+}
+```
+
+### 3. Lifecycle hooks
+
+Subscribe to platform events from anywhere :
+
+```ts
+extensions: {
+  hooks: {
+    onAuthSuccess: (user) => analytics.identify(user.id),
+    onTenantSwitch: (tenant) => router.navigate('/dashboard'),
+    onNavigationChanged: (menu) => console.log('menu refreshed'),
+  }
+}
+```
+
+---
+
+## Table columns & form fields extensions
+
+Extend the standard `DataTable` or `EntityForm` of any built-in section :
+
+```ts
+extensions: {
+  tableColumns: {
+    'administration.users.list': [
+      {
+        key: 'department',
+        label: 'Department',
+        render: (row) => row.department?.name,
+        align: 'left',
+        sortable: true,
+      },
+    ],
+  },
+  formFields: {
+    'administration.users.create': [
+      {
+        name: 'department',
+        type: 'select',
+        label: 'Department',
+        options: () => departmentApi.list(),
+        validation: { required: true },
+      },
+    ],
+  },
+}
+```
+
+These extensions are consumed by the corresponding hooks in the SmartStack page :
+
+```tsx
+const extraColumns = useTableColumnExtensions('administration.users.list');
+const extraFields = useFormFieldExtensions('administration.users.create');
+```
+
+---
+
+## DO / DON'T
+
+| ✅ DO | ❌ DON'T |
+|---|---|
+| Use `PageRegistry.register()` once at startup | Register the same key twice (last wins, but ambiguous) |
+| Use lazy imports for page overrides | Import override pages eagerly (kills code splitting) |
+| Match exact componentKey from the navigation menu | Guess the key — read it from `/api/navigation/menu` response |
+| Use slots for additive content | Use slots to remove content (use page override instead) |
+| Type custom column data via `row` typing | Cast `row as any` |
+
+---
+
+## MCP delegation
+
+For complex extension scaffolds (page override + slots + tests), prefer the MCP tool over hand-written code :
+
+| Goal | MCP tool |
+|---|---|
+| Generate a page override + register it | `mcp__smartstack__scaffold_frontend_extension` (type: `page-override`) |
+| Generate a custom Slot component | `mcp__smartstack__scaffold_frontend_extension` (type: `slot`) |
+| Generate a custom column extension | `mcp__smartstack__scaffold_frontend_extension` (type: `table-column`) |
+
+---
+
+## Reference source files (read-only)
+
+- `D:\01 - projets\SmartStack.app\features\IA-Workflow\web\smartstack-web\src\extensions\PageRegistry.tsx`
+- `D:\01 - projets\SmartStack.app\features\IA-Workflow\web\smartstack-web\src\extensions\types.ts` (SlotName, ColumnExtension, FormFieldExtension)
+- `D:\01 - projets\SmartStack.app\features\IA-Workflow\web\smartstack-web\src\extensions\ExtensionContext.tsx` (useExtensions, useTableColumnExtensions, useFormFieldExtensions)
+- `D:\01 - projets\SmartStack.app\features\IA-Workflow\web\smartstack-web\src\extensions\SlotFill.tsx` (Slot, Fill, SlotFillProvider)
+
+See also [smartstack-provider.md](smartstack-provider.md) for the SmartStackConfig shape that hosts `extensions`.

package/templates/skills/application/references/frontend-route-naming.md

@@ -79,19 +79,21 @@ const applicationRoutes: ApplicationRouteExtensions = {
 
 ## Implementation Pattern
 
+> **v3.46+ note** — The domain-specific layouts `AdminLayout`, `BusinessLayout`, `UserLayout`, `HRLayout`, `SalesLayout` are REMOVED. `AppLayout` is now the SOLE shell for authenticated application routes. Routes are resolved dynamically by `DynamicRouter` via `componentRegistry.generated.ts` — the JSX `<Route>` blocks below are illustrative for naming convention only, not for manual declaration. See `references/smartstack-provider.md` for the full provider/router setup.
+
 When generating routes, apply kebab-case to all multi-word segments:
 
 ```tsx
-// CORRECT
-<Route path="/human-resources" element={<HRLayout />}>
+// CORRECT — kebab-case convention (illustrative — actual routes flow through DynamicRouter)
+<Route path="/human-resources" element={<AppLayout />}>
   <Route path="employees" element={<EmployeesPage />} />
   <Route path="time-management" element={<TimeManagementPage />} />
 </Route>
 
 // FORBIDDEN
-<Route path="/humanresources" element={<HRLayout />} />
-<Route path="/HR" element={<HRLayout />} />
-<Route path="/human_resources" element={<HRLayout />} />
+<Route path="/humanresources" element={<AppLayout />} />
+<Route path="/HR" element={<AppLayout />} />
+<Route path="/human_resources" element={<AppLayout />} />
 ```
 
 ---

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

@@ -4,13 +4,15 @@
 
 ## Routing Rules
 
+> ⚠️ **DEPRECATED PATTERN — v3.46+** : Domain-specific layouts (`SalesLayout`, `AdminLayout`, `BusinessLayout`, `UserLayout`, `HRLayout`) are REMOVED. There are now **only 4 layouts** : `AppLayout` (sole shell for authenticated app routes), `AuthLayout` (login/register), `PublicLayout` (public pages), `DocsLayout` (documentation). The "manual `<Route>` declaration" examples below are LEGACY ; on v3.46+ routes are resolved by `DynamicRouter` via `componentRegistry.generated.ts` (see Section 5b below + `references/smartstack-provider.md`). The examples are kept for projects on v3.6 and earlier.
+
 ### 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).
+**CRITICAL (legacy v3.6 only):** All routes MUST be nested inside the appropriate context layout. This is what provides the SmartStack shell (header with AvatarMenu, sidebar, navigation). On v3.46+, `AppLayout` is the SOLE shell.
 
 ```tsx
-// CORRECT - Inside SalesLayout (shell renders: header + AvatarMenu + sidebar)
-<Route path="/sales" element={<SalesLayout />}>
+// CORRECT (v3.46+) - Inside AppLayout (shell renders: header + AvatarMenu + sidebar)
+<Route path="/sales" element={<AppLayout />}>
   <Route path="products" element={<ProductsPage />} />
 </Route>
 
@@ -23,8 +25,8 @@
 **CRITICAL:** SmartStack requires NESTED routes within the layout:
 
 ```tsx
-// CORRECT - Nested routes inside layout
-<Route path="/sales" element={<SalesLayout />}>
+// CORRECT - Nested routes inside layout (v3.46+ uses AppLayout)
+<Route path="/sales" element={<AppLayout />}>
   <Route path="products">
     <Route index element={<Navigate to="products" replace />} />
     <Route path="products" element={<ProductsPage />} />

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

@@ -42,10 +42,12 @@ public class {AppPascalName}SeedDataProvider : IClientSeedDataProvider
         }
         else
         {
+            // v3.46+ signature : Zone removed. New flags isOpen + isPersonal at the END (optional, default false).
             app = NavigationApplication.Create(
-                ApplicationZone.Business, appEntry.Code, appEntry.Label,
+                appEntry.Code, appEntry.Label,
                 appEntry.Description, appEntry.Icon, appEntry.IconType,
-                appEntry.Route, appEntry.DisplayOrder);
+                appEntry.Route, appEntry.DisplayOrder,
+                isOpen: appEntry.IsOpen, isPersonal: appEntry.IsPersonal);
             context.NavigationApplications.Add(app);
             await ((DbContext)context).SaveChangesAsync(ct);
 

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

@@ -0,0 +1,118 @@
+# SmartStackProvider — Wrapping the Client App
+
+> **Reference for `application` skill** — how to bootstrap a SmartStack client project (npm `@atlashub/smartstack`) using the SDK provider.
+
+## When This Reference Applies
+
+- The client project consumes `@atlashub/smartstack` as an npm package (v3.7+)
+- You are generating or auditing `App.tsx` / `main.tsx` / the application bootstrap
+- The user asks "how do I wrap my app", "where do I put providers", "how do I configure SmartStack"
+
+If the project is the SmartStack platform itself (`SmartStack.app`), the platform's internal `App.tsx` already inlines the providers and does NOT use `<SmartStackProvider>` — only client projects use it.
+
+---
+
+## SmartStackConfig shape
+
+```ts
+interface SmartStackConfig {
+  apiUrl: string;                          // REQUIRED — backend root URL (e.g. "https://api.client.com")
+  defaultLanguage?: 'fr' | 'en' | 'it' | 'de';  // default 'fr'
+  debug?: boolean;                          // verbose logging
+  logo?: ReactNode;                         // override branding logo
+  appName?: string;                         // displayed in title/header fallback
+  licenseKey?: string;                      // license string (validated against /api/license)
+  extensions?: ExtensionConfig;             // see references/extensions-system.md
+}
+```
+
+---
+
+## Wrapping order (Outer → Inner)
+
+```tsx
+import { BrowserRouter } from 'react-router-dom';
+import { SmartStackProvider, DynamicRouter } from '@atlashub/smartstack';
+import '@atlashub/smartstack/theme.css';
+
+const config: SmartStackConfig = {
+  apiUrl: import.meta.env.VITE_API_URL,
+  defaultLanguage: 'fr',
+  appName: 'My Client App',
+};
+
+createRoot(document.getElementById('root')!).render(
+  <StrictMode>
+    <BrowserRouter>
+      <SmartStackProvider config={config}>
+        <DynamicRouter />
+      </SmartStackProvider>
+    </BrowserRouter>
+  </StrictMode>,
+);
+```
+
+`<SmartStackProvider>` internally nests, in this order :
+
+```
+SmartStackContext (config)
+└─ GlobalErrorBoundary
+   └─ ExtensionProvider
+      └─ ThemeProvider
+         └─ FeatureConfigProvider
+            └─ AuthProvider
+               └─ TenantProvider
+                  └─ LicenseProvider
+                     └─ FavoritesProvider
+                        └─ SidebarProvider
+                           └─ SessionProvider
+                              └─ ThemeSync
+                                 └─ NavigationProvider
+                                    └─ SignalRProvider
+                                       └─ {children}
+```
+
+**Do NOT re-wrap any of these providers manually.** They are exported only for advanced cases (e.g., Storybook).
+
+---
+
+## Hooks consumable from any descendant
+
+| Hook | Context | Returns |
+|---|---|---|
+| `useSmartStack()` | SmartStackContext | `{ config }` |
+| `useAuth()` | AuthContext | `{ user, login, logout, refresh, hasPermission }` |
+| `useTenant()` | TenantContext | `{ currentTenant, userTenants, switchTenant, isGlobalView }` |
+| `useNavigation()` | NavigationContext | `{ menu, reload, currentApp, currentModule, isLoading }` |
+| `useTheme()` | ThemeContext | `{ mode, selectedTheme, selectedPreset, setTheme, setPreset, toggleMode }` |
+| `useLicense()` | LicenseContext | `{ license, isFeatureEnabled, hasModule }` |
+| `useSignalR()` | SignalRContext | `{ isConnected, on, off, emit }` |
+| `useFavorites()` | FavoritesContext | `{ favorites, toggleFavorite, isFavorite }` |
+| `useSidebar()` | SidebarContext | `{ isCollapsed, toggle, setCollapsed }` |
+| `useFeatureConfig()` | FeatureConfigContext | `{ features }` |
+| `useDocPanel()` | DocPanelContext | `{ isOpen, toggle, openDoc }` |
+
+See [contexts-cheatsheet.md](contexts-cheatsheet.md) for usage examples.
+
+---
+
+## DO / DON'T
+
+| ✅ DO | ❌ DON'T |
+|---|---|
+| Place `<SmartStackProvider>` exactly once at root | Wrap the same provider twice |
+| Put `<BrowserRouter>` ABOVE `<SmartStackProvider>` | Put `<SmartStackProvider>` above the router |
+| Read config via `useSmartStack()` from any descendant | Pass config down via props |
+| Import `componentRegistry.generated` in `main.tsx` BEFORE the render | Forget the import (DynamicRouter will not resolve pages) |
+| Wait for `i18nReady` promise before render | Render before i18n loaded (causes FOUC) |
+| Provide `apiUrl` via `import.meta.env.VITE_API_URL` | Hardcode the backend URL |
+
+---
+
+## Reference source files (read-only — DO NOT copy verbatim)
+
+- `D:\01 - projets\SmartStack.app\features\IA-Workflow\web\smartstack-web\src\provider\SmartStackProvider.tsx`
+- `D:\01 - projets\SmartStack.app\features\IA-Workflow\web\smartstack-web\src\router\types.ts` (SmartStackConfig)
+- `D:\01 - projets\SmartStack.app\features\IA-Workflow\web\smartstack-web\src\main.tsx` (i18nReady + componentRegistry import)
+
+For overrides via `extensions`, see [extensions-system.md](extensions-system.md).