@atlashub/smartstack-cli 4.33.0 → 4.35.0

package/templates/project/claude-md/web.CLAUDE.md.template

@@ -0,0 +1,339 @@
+# {{ProjectName}} Web - React Frontend Memory
+
+## Purpose
+
+React SPA frontend. Communicates with {{ProjectName}}.Api via REST + SignalR.
+
+## Tech Stack
+
+| Technology | Version | Purpose |
+|------------|---------|---------|
+| React | ^18 / ^19 | UI library |
+| TypeScript | ~5.9.3 | Type safety (strict mode) |
+| Vite | ^7.2 | Build tool + dev server |
+| React Router | ^6 / ^7 | Routing (lazy-loaded) |
+| Context API | - | Client + server state |
+| Axios | ^1.13 | HTTP client |
+| Tailwind CSS | ^4.1 | Styling |
+| i18next | ^25.7 | Internationalization |
+| SignalR | ^10.0 | Real-time updates |
+| Lucide React | ^0.562 | Icons |
+
+---
+
+## CRITICAL: Internationalization (i18n) - 4 Languages Required
+
+### Rules
+
+- **CRITICAL**: Every page MUST use translations via `useTranslation()` hook
+- **CRITICAL**: All user-visible text MUST be in translation files (fr, en, it, de)
+- **NEVER** hardcode text strings in components
+- **ALWAYS** add translations to ALL 4 locales: `fr/`, `en/`, `it/`, `de/`
+
+### Supported Languages
+
+| Language | Code | Folder |
+|----------|------|--------|
+| French | `fr` | `locales/fr/` |
+| English | `en` | `locales/en/` |
+| Italian | `it` | `locales/it/` |
+| German | `de` | `locales/de/` |
+
+### Structure
+
+```
+src/i18n/
+├── config.ts                    → i18next configuration
+└── locales/
+    ├── en/
+    │   ├── common.json          → Common UI (buttons, labels, errors)
+    │   ├── navigation.json      → Menu and navigation
+    │   └── {feature}.json       → Feature-specific translations
+    ├── fr/
+    │   └── ...                  → Same structure as en/
+    ├── it/
+    │   └── ...                  → Same structure as en/
+    └── de/
+        └── ...                  → Same structure as en/
+```
+
+### Usage in Pages
+
+```tsx
+import { useTranslation } from 'react-i18next';
+
+export function ExamplePage() {
+  const { t } = useTranslation('feature');  // Specify namespace
+
+  return (
+    <div>
+      <h1>{t('pageTitle')}</h1>
+      <p>{t('description')}</p>
+      <button>{t('common:save')}</button>  {/* Cross-namespace */}
+    </div>
+  );
+}
+```
+
+### Adding New Translations
+
+**ALWAYS add to ALL 4 languages** (en, fr, it, de) with the same structure.
+
+### Translation Keys Convention
+
+- Use **dot notation** for nested keys: `orders.pageTitle`
+- Use **camelCase** for key names
+- Group by feature/section: `orders.table.headerName`
+- Common actions in `common` namespace: `common:save`, `common:cancel`
+
+---
+
+## Structure
+
+```
+{{ProjectNameLower}}-web/
+├── src/
+│   ├── main.tsx                 → Entry point
+│   ├── App.tsx                  → Root component + providers + DynamicRouter
+│   ├── i18n/                    → Internationalization
+│   │   ├── config.ts            → i18next setup
+│   │   └── locales/             → Translation files (fr/en/it/de)
+│   ├── services/                → API client layer
+│   │   └── api/
+│   │       ├── apiClient.ts     → Axios instance + interceptors
+│   │       └── {feature}Api.ts  → Feature-specific API modules
+│   ├── components/              → Shared & domain components
+│   │   ├── ui/                  → Base UI components (DataTable, Modal, etc.)
+│   │   ├── layout/              → Layout components
+│   │   ├── routing/             → Route guards + dynamic routing
+│   │   └── {feature}/           → Feature-specific components
+│   ├── pages/                   → Page components
+│   │   └── {application}/{module}/ → Organized by navigation hierarchy
+│   ├── contexts/                → React Context providers
+│   ├── hooks/                   → Custom hooks
+│   ├── layouts/                 → Layout wrappers
+│   ├── utils/                   → Utility functions
+│   ├── types/                   → Global types
+│   ├── routes/                  → Route definitions
+│   └── extensions/              → Extension system (PageRegistry)
+├── tests/                       → Vitest tests (NOT in src/)
+│   ├── utils/                   → Pure utility tests
+│   ├── components/              → Component tests
+│   ├── hooks/                   → Hook tests
+│   └── services/                → Service tests
+├── vite.config.ts
+├── vitest.config.ts
+├── tsconfig.json
+└── eslint.config.js
+```
+
+## Patterns
+
+### Page Template with i18n
+
+```tsx
+// src/pages/{module}/{PageName}Page.tsx
+import { useTranslation } from 'react-i18next';
+
+export function ExamplePage() {
+  const { t } = useTranslation('feature');
+
+  return (
+    <div className="container mx-auto p-4">
+      <h1 className="text-2xl font-bold">{t('example.pageTitle')}</h1>
+      <p className="text-muted-foreground">{t('example.description')}</p>
+
+      <div className="mt-4 flex gap-2">
+        <button className="btn-primary">{t('common:save')}</button>
+        <button className="btn-secondary">{t('common:cancel')}</button>
+      </div>
+    </div>
+  );
+}
+```
+
+### API Client
+
+```typescript
+// src/services/api/apiClient.ts — uses Axios instance
+import { api } from '@/services/api/apiClient';
+
+// Request interceptors automatically add:
+// - Authorization: Bearer {token}
+// - X-Tenant-Slug: {currentTenantSlug}
+// - Accept-Language: {i18nextLng}
+// - X-Correlation-ID: {UUID}
+
+// Usage in service files:
+const orders = await api.get<Order[]>('/orders');
+const order = await api.post<Order>('/orders', { name, amount });
+```
+
+### API Service File Pattern
+
+```typescript
+// src/services/api/{feature}Api.ts
+import { api } from './apiClient';
+
+export interface OrderDto {
+  id: string;
+  name: string;
+  amount: number;
+  isActive: boolean;
+}
+
+export const orderApi = {
+  getAll: (search?: string) =>
+    api.get<OrderDto[]>('/orders', { params: { search } }),
+
+  getById: (id: string) =>
+    api.get<OrderDto>(`/orders/${id}`),
+
+  create: (data: Partial<OrderDto>) =>
+    api.post<OrderDto>('/orders', data),
+
+  update: (id: string, data: Partial<OrderDto>) =>
+    api.put<OrderDto>(`/orders/${id}`, data),
+
+  delete: (id: string) =>
+    api.delete(`/orders/${id}`),
+};
+```
+
+### Custom Hook Pattern
+
+```typescript
+// src/hooks/useOrderDetail.ts
+import { useState, useCallback } from 'react';
+import { orderApi, OrderDto } from '@/services/api/orderApi';
+
+export function useOrderDetail(id: string) {
+  const [data, setData] = useState<OrderDto | null>(null);
+  const [loading, setLoading] = useState(false);
+  const [error, setError] = useState<string | null>(null);
+
+  const load = useCallback(async () => {
+    setLoading(true);
+    setError(null);
+    try {
+      const result = await orderApi.getById(id);
+      setData(result);
+    } catch (err: unknown) {
+      setError(err instanceof Error ? err.message : 'Unknown error');
+    } finally {
+      setLoading(false);
+    }
+  }, [id]);
+
+  return { data, loading, error, load };
+}
+```
+
+### Context Provider Pattern
+
+```typescript
+// src/contexts/ExampleContext.tsx
+import { createContext, useContext, useState, type ReactNode } from 'react';
+
+interface ExampleContextType {
+  value: string;
+  setValue: (v: string) => void;
+}
+
+const ExampleContext = createContext<ExampleContextType | null>(null);
+
+export function ExampleProvider({ children }: { children: ReactNode }) {
+  const [value, setValue] = useState('');
+  return (
+    <ExampleContext.Provider value={{ value, setValue }}>
+      {children}
+    </ExampleContext.Provider>
+  );
+}
+
+export function useExample() {
+  const ctx = useContext(ExampleContext);
+  if (!ctx) throw new Error('useExample must be used within ExampleProvider');
+  return ctx;
+}
+```
+
+## UI Styling Patterns
+
+### Semantic Color Usage
+
+| Color | CSS Variables | Usage |
+|-------|---------------|-------|
+| `blue` | `--info-*` | Totals, informational, in progress |
+| `green` | `--success-*` | Completed, resolved, active |
+| `yellow` | `--warning-*` | Pending, on hold, warnings |
+| `red` | `--error-*` | Errors, critical, failed |
+| `neutral` | `--bg-secondary`, `--text-primary` | Inactive, closed, disabled |
+
+---
+
+## Commands
+
+```bash
+# Development
+npm run dev              # Start dev server (port 6173)
+
+# Build
+npm run build            # Production build
+
+# Tests (MANDATORY before commit)
+npm test                 # Run all tests
+npm run test:watch       # Watch mode
+npm run test:coverage    # Coverage report
+
+# Lint
+npm run lint             # ESLint check
+npm run typecheck        # TypeScript type check
+```
+
+## Routing
+
+### Lazy Loading
+
+All non-critical pages use `React.lazy()` for code splitting:
+
+```tsx
+const OrdersPage = lazy(() =>
+  import('@/pages/{module}/OrdersPage').then(m => ({ default: m.OrdersPage }))
+);
+```
+
+### Route Guards (Layered)
+
+```
+Auth check → Tenant transition → Permission check → Render
+```
+
+---
+
+## Rules
+
+1. **CRITICAL: i18n Required** - ALL pages must use `useTranslation()` with all 4 language files (fr/en/it/de)
+2. **Pages in `pages/`**, components in `components/`** - organized by application/module
+3. **Custom hooks for logic** - extract API calls and state management from components into `hooks/`
+4. **Context API for global state** - use `contexts/` for auth, tenant, navigation, theme, etc.
+5. **Axios API client** - all HTTP calls via `services/api/apiClient.ts`, never raw `fetch()`
+6. **TypeScript strict mode** - no `any` types
+7. **Tailwind for styling** - no CSS files, no inline styles (`style={{}}`)
+8. **Functional components only** - no class components
+9. **Composition over inheritance** - use props and children
+10. **Tests in `tests/`** - NOT in `src/`, use Vitest + Testing Library
+
+## CRITICAL: Tabs Must Persist in URL
+
+When creating a page with tabs, **ALWAYS** persist the active tab in the URL query params (`?tab=xxx`).
+Use the `useTabNavigation` hook.
+
+## When Adding New Feature
+
+1. Create page in `pages/{application}/{module}/`
+2. Create components in `components/{feature}/`
+3. Create API service in `services/api/{feature}Api.ts`
+4. Create custom hooks in `hooks/use{Feature}.ts`
+5. Register page via `PageRegistry.register()`
+6. **CRITICAL**: Add translations to ALL 4 locales: `i18n/locales/{fr,en,it,de}/`

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

@@ -2,8 +2,8 @@
 
 > These templates generate React/TypeScript code for new applications/modules.
 
-> **DEPRECATED (v3.7+):** Pattern A (mergeRoutes) and Pattern B (JSX Routes) below
-> are replaced by PageRegistry.register() + DynamicRouter.
+> **v3.7+:** Pattern A (mergeRoutes) and Pattern B (JSX Routes) were removed.
+> The only supported routing pattern is PageRegistry.register() + DynamicRouter.
 > See references/frontend-route-wiring-app-tsx.md for the current pattern.
 
 ---
@@ -507,117 +507,86 @@ export const $moduleApi = {
 
 ---
 
-## TEMPLATE: ROUTES (App.tsx)
+## TEMPLATE: ROUTES (PageRegistry + DynamicRouter)
 
-### Detect App.tsx Routing Pattern FIRST
+### Default Pattern (v3.7+): PageRegistry + DynamicRouter
 
-Before adding routes, **read App.tsx** and detect which pattern is used:
+> **This is the ONLY supported pattern** since v3.7.
+> Pages are registered in `componentRegistry.generated.ts` via `PageRegistry.register()`.
+> DynamicRouter resolves routes automatically from the navigation API + PageRegistry.
+> **No App.tsx wiring needed.** No manual route duplication for tenant prefixes.
 
-| Pattern | How to detect | Action |
-|---------|---------------|--------|
-| **Pattern A** (mergeRoutes) | `applicationRoutes: ApplicationRouteExtensions` present | Add to `applicationRoutes.{application}[]` array |
-| **Pattern B** (JSX Routes) | `<Route path="/{application}" element={<{Layout} />}>` present | Insert `<Route>` children inside Layout wrapper |
+**Steps:**
 
-### Pattern A: mergeRoutes (applicationRoutes array)
-
-> **This is the DEFAULT pattern** generated by `smartstack init`.
-> Routes added to `applicationRoutes` are automatically injected into BOTH standard and tenant-prefixed route trees by `mergeRoutes()`. No manual duplication needed.
+1. Create your page component(s)
+2. Register in `componentRegistry.generated.ts` (or run `scaffold_routes outputFormat="componentRegistry"`)
+3. Ensure navigation seed data has matching `ComponentKey` values
+4. DynamicRouter does the rest
 
 ```tsx
-// Add to App.tsx — imports at top
-import { $MODULE_PASCALPage } from '@/pages/$APPLICATION/$MODULE/$MODULE_PASCALPage';
-import { $MODULE_PASCALDetailPage } from '@/pages/$APPLICATION/$MODULE/$MODULE_PASCALDetailPage';
-import { Create$MODULE_PASCALPage } from '@/pages/$APPLICATION/$MODULE/Create$MODULE_PASCALPage';
-
-// Add routes to applicationRoutes.{application}[] with RELATIVE paths (no leading /)
-const applicationRoutes: ApplicationRouteExtensions = {
-  '$APPLICATION_KEBAB': [
-    // ... existing routes ...
-    { path: '$MODULE_KEBAB', element: <$MODULE_PASCALPage /> },
-    { path: '$MODULE_KEBAB/create', element: <Create$MODULE_PASCALPage /> },
-    { path: '$MODULE_KEBAB/:id', element: <$MODULE_PASCALDetailPage /> },
-    { path: '$MODULE_KEBAB/:id/edit', element: <Create$MODULE_PASCALPage /> },
-  ],
-};
+// 1. Create page component
+// pages/$APPLICATION/$MODULE/$MODULE_PASCALPage.tsx
+export function $MODULE_PASCALPage() { /* ... */ }
+
+// 2. Register in componentRegistry.generated.ts
+import { PageRegistry } from '@/extensions/PageRegistry';
+
+PageRegistry.register(
+  '$APPLICATION_KEBAB.$MODULE_KEBAB',
+  lazy(() => import('@/pages/$APPLICATION/$MODULE/$MODULE_PASCALPage')
+    .then(m => ({ default: m.$MODULE_PASCALPage })))
+);
+
+// For CRUD sub-pages (detail, create):
+PageRegistry.register(
+  '$APPLICATION_KEBAB.$MODULE_KEBAB.detail',
+  lazy(() => import('@/pages/$APPLICATION/$MODULE/$MODULE_PASCALDetailPage')
+    .then(m => ({ default: m.$MODULE_PASCALDetailPage })))
+);
+
+PageRegistry.register(
+  '$APPLICATION_KEBAB.$MODULE_KEBAB.create',
+  lazy(() => import('@/pages/$APPLICATION/$MODULE/Create$MODULE_PASCALPage')
+    .then(m => ({ default: m.Create$MODULE_PASCALPage })))
+);
 ```
 
-**mergeRoutes auto-generates redirects** for intermediate paths (e.g., `$APPLICATION` → `$APPLICATION/$DEFAULT_MODULE_KEBAB`) so you don't need to add index redirects manually.
-
-**Application-to-Layout mapping (automatic via mergeRoutes):**
-
-| Application key | Injected into Layout | Standard path | Tenant path |
-|-----------------|---------------------|---------------|-------------|
-| `administration` | `AppLayout` | `/administration/...` | `/t/:slug/administration/...` |
-| `{application}` | `AppLayout` | `/{application}/...` | `/t/:slug/{application}/...` |
-| `myspace` | `AppLayout` | `/myspace/...` | `/t/:slug/myspace/...` |
-
-### Pattern B: JSX Routes (inside Layout wrapper)
-
-> **Legacy pattern** — only used if App.tsx was manually restructured with JSX `<Route>` elements.
-
-The unified `AppLayout` provides the application shell: **header with AvatarMenu**, sidebar, navigation. It renders child pages via React Router's `<Outlet />`.
+```sql
+-- 3. Navigation seed data (ComponentKey must match PageRegistry key)
+INSERT INTO core.nav_Sections (...)
+VALUES (..., ComponentKey = '$APPLICATION_KEBAB.$MODULE_KEBAB', ...);
+```
 
-**If routes are placed OUTSIDE the layout wrapper, the shell (header, sidebar, AvatarMenu) will NOT render. The page appears "naked" without any navigation.**
+### How DynamicRouter resolves routes
 
-**Step-by-step insertion:**
+1. Fetches menu from `GET /api/navigation/menu`
+2. For each Application → Module → Section → Resource, builds `<Route>` elements
+3. Looks up each item's `ComponentKey` in `PageRegistry` to get the React component
+4. Wraps routes in `<ProtectedRoute>` (API-driven permission check via `isOpen` flag)
+5. Generates both standard (`/$APPLICATION/$MODULE`) and tenant-prefixed (`/t/:slug/$APPLICATION/$MODULE`) routes automatically
 
-1. Open `App.tsx`
-2. Find the existing layout route for the target application:
-   - `administration` → `<Route path="/administration" element={<AppLayout />}>`
-   - `{application}` → `<Route path="/{application}" element={<AppLayout />}>`
-   - `myspace` → `<Route path="/myspace" element={<AppLayout />}>`
-3. Add the new routes **INSIDE** that `<Route>` block
-4. If a tenant-prefixed block exists (`/t/:slug/...`), add the routes there too
+### ⚠️ CRITICAL RULES
 
+**FORBIDDEN — Flat routes outside DynamicRouter:**
 ```tsx
-// Add to App.tsx
-
-import { $MODULE_PASCALPage } from '@/pages/$APPLICATION/$MODULE/$MODULE_PASCALPage';
-import { $MODULE_PASCALDetailPage } from '@/pages/$APPLICATION/$MODULE/$MODULE_PASCALDetailPage';
-import { Create$MODULE_PASCALPage } from '@/pages/$APPLICATION/$MODULE/Create$MODULE_PASCALPage';
-
-// Find the EXISTING layout route and add routes INSIDE it:
-<Route path="/$APPLICATION" element={<$APPLICATION_Layout />}>
-  {/* ... existing routes stay here ... */}
-
-  {/* NEW: $MODULE routes - added as children of the layout */}
-  <Route path="$MODULE_KEBAB">
-    <Route index element={<Navigate to="." replace />} />
-    <Route index element={<$MODULE_PASCALPage />} />
-    <Route path="create" element={<Create$MODULE_PASCALPage />} />
-    <Route path=":id" element={<$MODULE_PASCALDetailPage />} />
-    <Route path=":id/edit" element={<Create$MODULE_PASCALPage />} />
-  </Route>
-</Route>
+// ❌ WRONG — bypasses layout, permission checks, and tenant handling
+<Route path="/$APPLICATION_KEBAB/$MODULE_KEBAB" element={<$MODULE_PASCALPage />} />
 ```
 
-### ⚠️ CRITICAL RULES (both patterns)
-
-**FORBIDDEN — Adding to clientRoutes[] with absolute paths:**
+**FORBIDDEN — Registering pages without navigation seed data:**
 ```tsx
-// ❌ WRONG — bypasses layout entirely, shell will NOT render
-const clientRoutes: RouteConfig[] = [
-  { path: '/$APPLICATION_KEBAB/$MODULE_KEBAB', element: <$MODULE_PASCALPage /> },
-];
+// ❌ WRONG — PageRegistry.register() alone does nothing without a matching ComponentKey in the DB
+PageRegistry.register('my-app.my-module', MyPage);
+// Must also have INSERT INTO core.nav_Sections with ComponentKey = 'my-app.my-module'
 ```
 
-`clientRoutes` is ONLY for routes **outside** SmartStack locked applications (e.g., `/about`, `/pricing`).
-
-**FORBIDDEN — Flat routes outside layout:**
-```tsx
-// ❌ WRONG (Pattern B only) — flat route bypasses layout
-<Route path="/$APPLICATION_KEBAB/$MODULE_KEBAB" element={<$MODULE_PASCALPage />} />
-```
+---
 
-### Why nested/context routes?
+### Legacy Patterns (DEPRECATED — removed in v3.7)
 
-| Aspect | clientRoutes (wrong) | applicationRoutes / nested (correct) |
-|--------|---------------------|--------------------------------------|
-| Shell rendered | No (bypasses layout) | Yes (Outlet pattern) |
-| AvatarMenu visible | No | Yes |
-| Tenant prefix | Manual duplication | Automatic (mergeRoutes) |
-| Auto-redirects | None | Generated for intermediate paths |
-| Permission check | Bypassed (no RouteGuard) | Enforced by RouteGuard |
+> **Pattern A (mergeRoutes)** and **Pattern B (JSX Routes)** were removed in v3.7.
+> `smartstackRoutes.tsx`, `RouteGuard.tsx`, and `mergeRoutes()` no longer exist.
+> If you encounter a pre-v3.7 project, upgrade to PageRegistry + DynamicRouter.
 
 ---
 

package/templates/skills/cli-app-sync/SKILL.md

@@ -113,7 +113,7 @@ COMPARISON POINTS: {total}
   [OK]    index.css — @custom-variant dark present
   [OK]    DependencyInjection.Application — MediatR warning present
   [OK]    DependencyInjection.Infrastructure — SQL Server pattern matches
-  [SKIP]  App.tsx — Intentionally different (client uses mergeRoutes legacy or PageRegistry+DynamicRouter)
+  [SKIP]  App.tsx — Intentionally different (client uses PageRegistry+DynamicRouter v3.7+)
   [SKIP]  ExtensionsDbContext — Intentionally simplified
 
 --------------------------------------------------------------------------------
@@ -161,7 +161,7 @@ These differences are **by design** and should always be marked `[SKIP]`:
 
 | File/Pattern | Reason |
 |---|---|
-| `App.tsx` — routing pattern (`mergeRoutes` legacy or `PageRegistry`+`DynamicRouter` v3.7+) | Client projects use their own routing entry point, not platform routing |
+| `App.tsx` — routing pattern (`PageRegistry`+`DynamicRouter` v3.7+) | Client projects use their own routing entry point, not platform routing |
 | `ExtensionsDbContext` | Intentionally simplified vs `CoreDbContext` — different architectural role |
 | `api.ts` | Re-exports SmartStack client — wrapper pattern is correct |
 | `DependencyInjection.Infrastructure.cs` | SQL Server connection pattern identical by design |

package/templates/skills/cli-app-sync/references/comparison-map.md

@@ -208,7 +208,7 @@ These comparisons should **always** return `[SKIP]` — differences are by desig
 
 | Item | Reason |
 |---|---|
-| `App.tsx` | Client uses `mergeRoutes` (legacy) or `PageRegistry`+`DynamicRouter` (v3.7+); app uses direct routing |
+| `App.tsx` | Client uses `PageRegistry`+`DynamicRouter` (v3.7+); app uses DynamicRouter exclusively (mergeRoutes removed in v3.7) |
 | `api.ts` | Client re-exports SmartStack client — wrapper pattern is correct |
 | `ExtensionsDbContext` | Intentionally simplified vs `CoreDbContext` |
 | `GlobalUsings.cs` | App has platform-wide usings; client has minimal set |

package/templates/skills/documentation/steps/step-03-validate.md

@@ -25,8 +25,7 @@ Validate that generated documentation is complete and accurate, then integrate i
 - [ ] Mock UI faithfully reproduces the real page interface (not generic KPI/table)
 - [ ] Every Mock UI section has `Annotation` components explaining each visual element
 - [ ] i18n JSON is FLAT (no root key) — `t('title')` resolves directly
-- [ ] Route added as **child** of `/docs/business` group (not standalone) in App.tsx
-- [ ] Route added in `smartstackRoutes.tsx` (locked routes)
+- [ ] Route added as **child** of `/docs/business` group (not standalone) in DynamicRouter.tsx
 - [ ] DocsLayout sidebar updated (if applicable)
 - [ ] Module appears in UserIndexPage.tsx (if applicable)
 - [ ] DocPanelContext.tsx mapping updated for all module routes
@@ -38,8 +37,7 @@ Validate that generated documentation is complete and accurate, then integrate i
 - [ ] i18n JSON uses root key matching namespace
 - [ ] DocRenderer wrapper (index.tsx) passes correct `i18nNamespace` prop
 - [ ] doc-data.ts contains structured data (~50 lines)
-- [ ] Route added as **child** of `/system/docs` group (not standalone) in App.tsx
-- [ ] Route added in `smartstackRoutes.tsx` (locked routes)
+- [ ] Route added as **child** of `/system/docs` group (not standalone) in DynamicRouter.tsx
 - [ ] DocsLayout sidebar updated (if applicable)
 
 #### For `update` Type
@@ -113,7 +111,7 @@ detects tenant-prefixed routes (`/t/:slug/...`), and builds lookup keys as `{app
 - `/support/tickets/123` → tries `support/tickets/123`, then `support/tickets`
 - `/t/my-company/administration/users` → strips tenant prefix, then tries `administration/users`
 
-#### App.tsx Routing
+#### DynamicRouter.tsx Routing
 
 Documentation pages use a **separate routing system** from business pages. They render inside `DocsLayout` (sidebar navigation), NOT `AppLayout`. There are two route groups:
 
@@ -122,10 +120,10 @@ Documentation pages use a **separate routing system** from business pages. They
 
 > **Note:** The `<Suspense fallback={<PageLoader />}>` is already in place at the global level (wrapping the entire Routes tree). Do NOT add per-route `<Suspense>` wrappers.
 
-**For `user` type:** Add lazy import and **child route** inside the existing `/docs/business` group:
+**For `user` type:** Add lazy import and **child route** inside the existing `/docs/business` group in `DynamicRouter.tsx`:
 
 ```tsx
-// 1. Add lazy import at top of App.tsx
+// 1. Add lazy import at top of DynamicRouter.tsx
 const {Module}DocPage = lazy(() =>
   import('@/pages/docs/business/{application}/{module}')
 );
@@ -138,10 +136,10 @@ const {Module}DocPage = lazy(() =>
 </Route>
 ```
 
-**For `developer|database|testing` types:** Add **child route** inside the existing `/system/docs` group:
+**For `developer|database|testing` types:** Add **child route** inside the existing `/system/docs` group in `DynamicRouter.tsx`:
 
 ```tsx
-// 1. Add lazy import at top of App.tsx
+// 1. Add lazy import at top of DynamicRouter.tsx
 const {Tool}DocPage = lazy(() =>
   import('@/pages/docs/{category}/{tool}')
 );
@@ -154,9 +152,9 @@ const {Tool}DocPage = lazy(() =>
 </Route>
 ```
 
-#### smartstackRoutes.tsx Registration
+#### DynamicRouter Documentation Routes
 
-**MANDATORY** for all doc types: Add the route in `smartstackRoutes.tsx` under the corresponding group (`/docs/business` or `/system/docs`). Documentation routes are part of `LOCKED_PREFIXES` and cannot be overridden by client extensions.
+Documentation routes are statically defined in `DynamicRouter.tsx` (not dynamically generated from the navigation API). When adding new documentation pages, add the lazy import and `<Route>` entry in the documentation section of `DynamicRouter.tsx`.
 
 #### DocsLayout Sidebar Update
 
@@ -164,7 +162,7 @@ If the new documentation page should appear in the sidebar navigation, update th
 
 #### Important Notes
 
-- Documentation routes do **NOT** use `AppLayout`, `RouteGuard`, or `LicenseGuard`
+- Documentation routes do **NOT** use `AppLayout`, `ProtectedRoute`, or `LicenseGuard`
 - Documentation routes have **no tenant prefix** (`/t/:slug/...`) — they are globally accessible
 - Documentation routes require **no specific permission** to access
 
@@ -259,8 +257,8 @@ Add or update entry with metadata:
 - [x] Mock UI faithfully reproduces the real page interface (user type)
 - [x] Every Mock UI section has `Annotation` components (user type)
 - [x] i18n files created in ALL 4 languages (FR, EN, DE, IT) with correct format
-- [x] Route added as child of correct DocsLayout group in App.tsx
-- [x] Route registered in smartstackRoutes.tsx (locked routes)
+- [x] Route added as child of correct DocsLayout group in DynamicRouter.tsx
+- [x] Route added in DynamicRouter.tsx documentation section
 - [x] DocsLayout sidebar updated (if applicable)
 - [x] docs-manifest.json updated
 - [x] i18n/config.ts updated with new namespace