@atlashub/smartstack-cli 4.35.0 → 4.37.0

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

@@ -79,6 +79,274 @@ export function $MODULE_PASCALPage() {
 
 ---
 
+## TEMPLATE: DETAIL PAGE
+
+```tsx
+// pages/$APPLICATION/$MODULE/$MODULE_PASCALDetailPage.tsx
+
+import { useState, useEffect, useCallback } from 'react';
+import { useParams, useNavigate } from 'react-router-dom';
+import { useTranslation } from 'react-i18next';
+import { ArrowLeft, Pencil, Trash2, Loader2 } from 'lucide-react';
+import { Breadcrumb } from '@/components/ui/Breadcrumb';
+import { $moduleApi, type $ENTITY_PASCALDto } from '@/services/api/$moduleApi';
+
+export function $MODULE_PASCALDetailPage() {
+  // ⚠️ CRITICAL: DynamicRouter generates /:id — use destructuring rename
+  const { id: $entityId } = useParams<{ id: string }>();
+  const navigate = useNavigate();
+  const { t } = useTranslation(['$module', 'common']);
+
+  const [$entity, set$ENTITY_PASCAL] = useState<$ENTITY_PASCALDto | null>(null);
+  const [loading, setLoading] = useState(true);
+  const [error, setError] = useState<string | null>(null);
+
+  const loadData = useCallback(async () => {
+    if (!$entityId) return;
+    try {
+      setLoading(true);
+      setError(null);
+      const data = await $moduleApi.getById($entityId);
+      set$ENTITY_PASCAL(data);
+    } catch (err) {
+      setError(t('common:errors.loadFailed'));
+      console.error('Failed to load $entity:', err);
+    } finally {
+      setLoading(false);
+    }
+  }, [$entityId, t]);
+
+  useEffect(() => {
+    loadData();
+  }, [loadData]);
+
+  const handleDelete = async () => {
+    if (!$entityId || !confirm(t('common:confirmDelete'))) return;
+    try {
+      await $moduleApi.delete($entityId);
+      navigate('..');
+    } catch (err) {
+      console.error('Failed to delete:', err);
+    }
+  };
+
+  if (loading) {
+    return (
+      <div className="flex items-center justify-center py-12">
+        <Loader2 className="w-8 h-8 animate-spin text-[var(--color-accent-500)]" />
+      </div>
+    );
+  }
+
+  if (error || !$entity) {
+    return (
+      <div className="p-6">
+        <p className="text-[var(--error-text)]">{error || t('common:errors.notFound')}</p>
+      </div>
+    );
+  }
+
+  return (
+    <div className="space-y-6">
+      <Breadcrumb
+        items={[
+          { label: t('$module:title'), href: '/$APPLICATION_KEBAB/$MODULE_KEBAB' },
+          { label: $entity.name },
+        ]}
+      />
+
+      <div className="flex items-center justify-between">
+        <div className="flex items-center gap-3">
+          <button onClick={() => navigate('..')} className="p-2 hover:bg-[var(--bg-hover)]" style={{ borderRadius: 'var(--radius-button)' }}>
+            <ArrowLeft className="w-5 h-5" />
+          </button>
+          <h1 className="text-2xl font-bold text-[var(--text-primary)]">{$entity.name}</h1>
+        </div>
+        <div className="flex items-center gap-2">
+          <button
+            onClick={() => navigate('edit')}
+            className="flex items-center gap-2 px-4 py-2 bg-[var(--color-accent-500)] hover:bg-[var(--color-accent-600)] text-white font-medium transition-colors"
+            style={{ borderRadius: 'var(--radius-button)' }}
+          >
+            <Pencil className="w-4 h-4" />
+            {t('common:actions.edit')}
+          </button>
+          <button
+            onClick={handleDelete}
+            className="flex items-center gap-2 px-4 py-2 bg-[var(--error-bg)] hover:bg-[var(--error-border)] text-[var(--error-text)] font-medium transition-colors"
+            style={{ borderRadius: 'var(--radius-button)' }}
+          >
+            <Trash2 className="w-4 h-4" />
+            {t('common:actions.delete')}
+          </button>
+        </div>
+      </div>
+
+      {/* Detail content — adapt to your entity */}
+      <div className="bg-[var(--bg-card)] border border-[var(--item-color-border)] p-6" style={{ borderRadius: 'var(--radius-card)' }}>
+        <dl className="grid grid-cols-1 md:grid-cols-2 gap-4">
+          <div>
+            <dt className="text-sm font-medium text-[var(--text-secondary)]">{t('$module:columns.name')}</dt>
+            <dd className="mt-1 text-[var(--text-primary)]">{$entity.name}</dd>
+          </div>
+          <div>
+            <dt className="text-sm font-medium text-[var(--text-secondary)]">{t('$module:columns.description')}</dt>
+            <dd className="mt-1 text-[var(--text-primary)]">{$entity.description || '-'}</dd>
+          </div>
+        </dl>
+      </div>
+    </div>
+  );
+}
+```
+
+---
+
+## TEMPLATE: EDIT PAGE
+
+```tsx
+// pages/$APPLICATION/$MODULE/$MODULE_PASCALEditPage.tsx
+
+import { useState, useEffect, useCallback } from 'react';
+import { useParams, useNavigate } from 'react-router-dom';
+import { useTranslation } from 'react-i18next';
+import { ArrowLeft, Save, Loader2 } from 'lucide-react';
+import { Breadcrumb } from '@/components/ui/Breadcrumb';
+import { $moduleApi, type $ENTITY_PASCALDto, type Update$ENTITY_PASCALRequest } from '@/services/api/$moduleApi';
+
+export function $MODULE_PASCALEditPage() {
+  // ⚠️ CRITICAL: DynamicRouter generates /:id/edit — use destructuring rename
+  const { id: $entityId } = useParams<{ id: string }>();
+  const navigate = useNavigate();
+  const { t } = useTranslation(['$module', 'common']);
+
+  const [data, setData] = useState<$ENTITY_PASCALDto | null>(null);
+  const [form, setForm] = useState<Update$ENTITY_PASCALRequest>({ name: '', description: '' });
+  const [loading, setLoading] = useState(true);
+  const [saving, setSaving] = useState(false);
+  const [error, setError] = useState<string | null>(null);
+
+  const loadData = useCallback(async () => {
+    if (!$entityId) return;
+    try {
+      setLoading(true);
+      const result = await $moduleApi.getById($entityId);
+      setData(result);
+      setForm({ name: result.name, description: result.description || '' });
+    } catch (err) {
+      setError(t('common:errors.loadFailed'));
+      console.error('Failed to load $entity:', err);
+    } finally {
+      setLoading(false);
+    }
+  }, [$entityId, t]);
+
+  useEffect(() => {
+    loadData();
+  }, [loadData]);
+
+  const handleSave = async () => {
+    if (!$entityId) return;
+    try {
+      setSaving(true);
+      setError(null);
+      await $moduleApi.update($entityId, form);
+      navigate('..');
+    } catch (err) {
+      setError(t('common:errors.saveFailed'));
+      console.error('Failed to save:', err);
+    } finally {
+      setSaving(false);
+    }
+  };
+
+  if (loading) {
+    return (
+      <div className="flex items-center justify-center py-12">
+        <Loader2 className="w-8 h-8 animate-spin text-[var(--color-accent-500)]" />
+      </div>
+    );
+  }
+
+  return (
+    <div className="space-y-6">
+      <Breadcrumb
+        items={[
+          { label: t('$module:title'), href: '/$APPLICATION_KEBAB/$MODULE_KEBAB' },
+          { label: data?.name || '...', href: '..' },
+          { label: t('common:actions.edit') },
+        ]}
+      />
+
+      <div className="flex items-center gap-3">
+        <button onClick={() => navigate('..')} className="p-2 hover:bg-[var(--bg-hover)]" style={{ borderRadius: 'var(--radius-button)' }}>
+          <ArrowLeft className="w-5 h-5" />
+        </button>
+        <h1 className="text-2xl font-bold text-[var(--text-primary)]">
+          {t('common:actions.edit')} — {data?.name}
+        </h1>
+      </div>
+
+      {error && (
+        <div className="p-4 bg-[var(--error-bg)] border border-[var(--error-border)]" style={{ borderRadius: 'var(--radius-card)' }}>
+          <span className="text-[var(--error-text)]">{error}</span>
+        </div>
+      )}
+
+      <div className="bg-[var(--bg-card)] border border-[var(--item-color-border)] p-6" style={{ borderRadius: 'var(--radius-card)' }}>
+        <div className="space-y-4 max-w-lg">
+          <div>
+            <label className="block text-sm font-medium text-[var(--text-secondary)] mb-1">
+              {t('$module:columns.name')}
+            </label>
+            <input
+              type="text"
+              value={form.name}
+              onChange={(e) => setForm(prev => ({ ...prev, name: e.target.value }))}
+              className="w-full px-3 py-2 bg-[var(--bg-primary)] border border-[var(--border-color)] text-sm focus:outline-none focus:border-[var(--color-accent-500)]"
+              style={{ borderRadius: 'var(--radius-input)' }}
+            />
+          </div>
+          <div>
+            <label className="block text-sm font-medium text-[var(--text-secondary)] mb-1">
+              {t('$module:columns.description')}
+            </label>
+            <textarea
+              value={form.description || ''}
+              onChange={(e) => setForm(prev => ({ ...prev, description: e.target.value }))}
+              rows={3}
+              className="w-full px-3 py-2 bg-[var(--bg-primary)] border border-[var(--border-color)] text-sm focus:outline-none focus:border-[var(--color-accent-500)]"
+              style={{ borderRadius: 'var(--radius-input)' }}
+            />
+          </div>
+        </div>
+
+        <div className="flex justify-end gap-3 mt-6 pt-4 border-t border-[var(--border-color)]">
+          <button
+            onClick={() => navigate('..')}
+            className="px-4 py-2 bg-[var(--bg-secondary)] hover:bg-[var(--bg-tertiary)] text-[var(--text-primary)] font-medium transition-colors"
+            style={{ borderRadius: 'var(--radius-button)' }}
+          >
+            {t('common:actions.cancel')}
+          </button>
+          <button
+            onClick={handleSave}
+            disabled={saving}
+            className="flex items-center gap-2 px-4 py-2 bg-[var(--color-accent-500)] hover:bg-[var(--color-accent-600)] text-white font-medium transition-colors disabled:opacity-50"
+            style={{ borderRadius: 'var(--radius-button)' }}
+          >
+            {saving ? <Loader2 className="w-4 h-4 animate-spin" /> : <Save className="w-4 h-4" />}
+            {t('common:actions.save')}
+          </button>
+        </div>
+      </div>
+    </div>
+  );
+}
+```
+
+---
+
 ## TEMPLATE: LIST VIEW (Reusable component)
 
 ```tsx
@@ -557,6 +825,28 @@ INSERT INTO core.nav_Sections (...)
 VALUES (..., ComponentKey = '$APPLICATION_KEBAB.$MODULE_KEBAB', ...);
 ```
 
+### ⚠️ IMPLICIT ROUTE PARAM CONVENTION
+
+DynamicRouter generates implicit sub-routes for `.detail`, `.create`, and `.edit` page keys:
+
+| Suffix | URL pattern | Route param |
+|--------|-------------|-------------|
+| `.detail` | `/:id` | `id` |
+| `.create` | `/create` | — |
+| `.edit` | `/:id/edit` | `id` |
+
+**The route param is ALWAYS `id`** — never `ticketId`, `userId`, or any entity-specific name.
+
+In detail/edit pages, use destructuring rename to keep a readable local variable:
+
+```tsx
+// ✅ CORRECT — matches DynamicRouter's /:id pattern
+const { id: $entityId } = useParams<{ id: string }>();
+
+// ❌ WRONG — will be undefined because the route param is :id, not :$entityId
+const { $entityId } = useParams<{ $entityId: string }>();
+```
+
 ### How DynamicRouter resolves routes
 
 1. Fetches menu from `GET /api/navigation/menu`
@@ -618,11 +908,13 @@ These patterns are **strictly prohibited** in generated frontend code:
 | Check | Status |
 |-------|--------|
 | ☐ Main page created (`$MODULE_PASCALPage.tsx`) | |
+| ☐ Detail page created (`$MODULE_PASCALDetailPage.tsx`) with `useParams<{ id: string }>` | |
+| ☐ Edit page created (`$MODULE_PASCALEditPage.tsx`) with `useParams<{ id: string }>` | |
 | ☐ ListView component created (`$MODULE_PASCALListView.tsx`) | |
 | ☐ Preferences hook created (`use$MODULE_PASCALPreferences.ts`) | |
 | ☐ API service created (uses `apiClient`, NOT raw axios) | |
-| ☐ Routes added inside Layout wrapper in App.tsx | |
-| ☐ Route path follows `/{application_kebab}/{module_kebab}` (kebab-case) | |
+| ☐ PageRegistry keys registered (`.detail`, `.create`, `.edit`) in `componentRegistry.generated.ts` | |
+| ☐ Route param uses `{ id: entityId }` destructuring (NOT `{ entityId }`) | |
 
 ### Theme Compliance
 | Check | Status |

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

@@ -805,7 +805,7 @@ public class {AppPascalName}SeedDataProvider : IClientSeedDataProvider
         else
         {
             app = NavigationApplication.Create(
-                "{app_code}", "{app_label_en}",
+                ApplicationZone.Business, "{app_code}", "{app_label_en}",
                 "{app_desc_en}", "{app_icon}", IconType.Lucide,
                 "/{app_code}", {display_order});
             context.NavigationApplications.Add(app);
@@ -822,17 +822,23 @@ public class {AppPascalName}SeedDataProvider : IClientSeedDataProvider
 
         // Module translations — IDEMPOTENT (unique index IX_nav_Translations_EntityType_EntityId_LanguageCode)
         // CRITICAL: Always check before inserting to avoid duplicate key errors on re-runs
+        // CRITICAL: Use modEntity.Id (actual DB ID), NOT seed-time GUID from SeedData class.
         // if (!await context.NavigationTranslations.AnyAsync(
-        //     t => t.EntityId == {Module}NavigationSeedData.{Module}ModuleId && t.EntityType == NavigationEntityType.Module, ct))
-        // { foreach (var t in {Module}NavigationSeedData.GetTranslationEntries()) { ... } }
+        //     t => t.EntityId == mod1Entity.Id && t.EntityType == NavigationEntityType.Module, ct))
+        // { foreach (var t in {Module}NavigationSeedData.GetTranslationEntries())
+        //   { context.NavigationTranslations.Add(
+        //       NavigationTranslation.Create(t.EntityType, mod1Entity.Id, t.LanguageCode, t.Label, t.Description)); } }
 
         // Sections (idempotent per-section — check each before inserting)
         // var secExists = await context.NavigationSections.AnyAsync(s => s.Code == secEntry.Code && s.ModuleId == ..., ct);
         // Use NavigationSection.Create(moduleId, code, label, description, icon, iconType, route, displayOrder)
 
         // Section translations — IDEMPOTENT (same guard pattern as module translations)
+        // CRITICAL: Resolve actual section from DB (secEntry.Id is seed-time GUID ≠ DB ID):
+        // var actualSection = await context.NavigationSections
+        //     .FirstAsync(s => s.Code == secEntry.Code && s.ModuleId == modEntity.Id, ct);
         // if (!await context.NavigationTranslations.AnyAsync(
-        //     t => t.EntityId == secEntry.Id && t.EntityType == NavigationEntityType.Section, ct))
+        //     t => t.EntityId == actualSection.Id && t.EntityType == NavigationEntityType.Section, ct))
 
         // Resources (idempotent per-resource — check each before inserting)
         // var resExists = await context.NavigationResources.AnyAsync(r => r.Code == resEntry.Code && r.SectionId == ..., ct);
@@ -841,20 +847,26 @@ public class {AppPascalName}SeedDataProvider : IClientSeedDataProvider
 
     public async Task SeedRolesAsync(ICoreDbContext context, CancellationToken ct)
     {
-        // Check idempotence
+        // Resolve application from DB by Code — NOT seed-time GUID
+        var app = await context.NavigationApplications
+            .FirstAsync(a => a.Code == "{app_code}", ct);
+
+        // Check idempotence — scoped by actual DB ApplicationId
         var exists = await context.Roles
-            .AnyAsync(r => r.ApplicationId == ApplicationRolesSeedData.ApplicationId, ct);
+            .AnyAsync(r => r.ApplicationId == app.Id, ct);
         if (exists) return;
 
         // Create application-scoped roles (Admin, Manager, Contributor, Viewer)
         foreach (var entry in ApplicationRolesSeedData.GetRoleEntries())
         {
             var role = Role.Create(
-                entry.Code,
-                entry.Name,
-                entry.Description,
-                entry.ApplicationId,
-                entry.IsSystem);
+                name: entry.Name,
+                shortName: entry.Code,
+                category: RoleCategory.Application,
+                description: entry.Description,
+                isSystem: entry.IsSystem,
+                applicationId: app.Id,
+                code: entry.Code);
             context.Roles.Add(role);
         }
         await ((DbContext)context).SaveChangesAsync(ct);

package/templates/skills/audit-route/SKILL.md

@@ -0,0 +1,107 @@
+---
+name: audit-route
+description: |
+  Audit dynamic routing architecture against the DB-driven pattern.
+  Use this skill when:
+  - Verifying routing is fully database-driven (no hardcoded routes)
+  - Checking the 5 mandatory elements (componentRegistry, ProtectedRoute, DynamicRouter, useRouteConfig, API)
+  - Validating route/permission alignment
+  - Detecting anti-patterns (static routes, hardcoded permissions, non-lazy imports)
+argument-hint: "[--strict] [--scope=frontend|backend|all]"
+model: sonnet
+allowed-tools: "Read, Grep, Glob, Bash, Agent, ToolSearch"
+entry_point: steps/step-00-init.md
+---
+
+<objective>
+Audit the dynamic routing implementation against the SmartStack DB-driven routing pattern. The architecture requires that navigation and permissions are **entirely driven by the database** — the React frontend must contain **zero hardcoded routes**.
+
+The audit validates 5 mandatory elements:
+1. **componentRegistry** — static mapping `string -> lazy(component)`, only allowed static file
+2. **ProtectedRoute** — front-end guard that validates permissions from the API (defense in depth)
+3. **DynamicRouter** — rendering engine that generates `<Route>` from API config
+4. **useRouteConfig** — hook that fetches route config + permissions from the API at mount
+5. **Navigation API** — endpoint returning routes **already filtered** by JWT/session
+
+For each element: inventory, conformity check, causal analysis of deviations, and migration plan.
+</objective>
+
+<quick_start>
+
+```bash
+/audit-route                     # Full audit (frontend + backend)
+/audit-route --scope=frontend    # Frontend only (React routing)
+/audit-route --scope=backend     # Backend only (API + navigation)
+/audit-route --strict            # Fail on any partial conformity (treat warnings as errors)
+```
+
+</quick_start>
+
+<parameters>
+
+<flags>
+| Flag | Description |
+|------|-------------|
+| `--scope=all` | Audit both frontend and backend (default) |
+| `--scope=frontend` | Audit React routing only (elements 1-4) |
+| `--scope=backend` | Audit API navigation only (element 5) |
+| `--strict` | Treat partial conformity (warning) as non-conformity (error) |
+</flags>
+
+</parameters>
+
+<workflow>
+1. **Initialize** — Detect project structure, resolve paths, parse flags
+2. **MCP Pre-scan** — Call `validate_frontend_routes` and `validate_conventions` for automated baseline
+3. **Inventory** — Locate each of the 5 mandatory elements in the codebase
+4. **Conformity** — Evaluate each element against the reference pattern, cross-reference with MCP findings
+5. **Anti-patterns** — Scan for hardcoded routes, static permissions, non-lazy imports
+6. **Report** — Generate structured audit report with causal analysis and migration plan
+</workflow>
+
+<state_variables>
+| Variable | Type | Description |
+|----------|------|-------------|
+| `{scope}` | string | frontend, backend, or all |
+| `{strict}` | boolean | Treat warnings as errors |
+| `{web_root}` | string | Path to web/smartstack-web/src/ |
+| `{api_root}` | string | Path to src/SmartStack.Api/ |
+| `{elements}` | object[] | Inventory of the 5 mandatory elements |
+| `{conformity}` | object[] | Conformity status per element |
+| `{anti_patterns}` | object[] | Detected anti-patterns with file:line |
+| `{mcp_results}` | object | Results from MCP validate_frontend_routes + validate_conventions |
+| `{score}` | string | X/5 conformity score |
+</state_variables>
+
+<entry_point>
+
+**FIRST ACTION:** Load `steps/step-00-init.md`
+
+</entry_point>
+
+<step_files>
+| Step | File | Purpose |
+|------|------|---------|
+| 00 | `steps/step-00-init.md` | Parse flags, detect project structure, resolve paths |
+| 01 | `steps/step-01-inventory.md` | Locate all 5 mandatory elements in the codebase |
+| 02 | `steps/step-02-conformity.md` | Evaluate conformity, causal analysis, anti-pattern scan |
+| 03 | `steps/step-03-report.md` | Generate structured audit report with migration plan |
+</step_files>
+
+<execution_rules>
+- **Read-only** — This skill NEVER modifies code
+- **Non-judgmental** — Analyze code, not developers. Distinguish errors from conscious choices
+- **Comprehensive** — Check ALL files, not a sample. Grep entire codebase for anti-patterns
+- **Evidence-based** — Every finding must reference a specific file:line
+- **Causal** — Every deviation must include: what was done instead, why it deviates, probable reason, consequence, and migration path
+- **SmartStack-aware** — Respect SmartStack SDK architecture (PageRegistry, DynamicRouter, menu API)
+</execution_rules>
+
+<success_criteria>
+- All 5 elements inventoried with exact file paths and line numbers
+- Each element rated: Conforme / Partiellement conforme / Non conforme / Absent
+- Anti-patterns detected across entire codebase (not just routing files)
+- Causal analysis for every deviation (5 questions answered)
+- Prioritized migration plan (critical > important > nice-to-have)
+- Executive summary with X/5 score and 3-line architecture status
+</success_criteria>

package/templates/skills/audit-route/references/routing-pattern.md

@@ -0,0 +1,129 @@
+# Dynamic Routing Reference Pattern
+
+## Architecture Principle
+
+Navigation and permissions are **entirely driven by the database**. The React frontend contains **zero hardcoded routes**. The backend API returns routes already filtered by the user's JWT/session.
+
+## 5 Mandatory Elements
+
+### 1. componentRegistry
+
+**Role**: Static mapping `string -> lazy(component)`. The ONLY allowed static file.
+
+**Requirements**:
+- All page imports MUST be lazy (`React.lazy(() => import(...))`)
+- Keys are string identifiers (dot-separated hierarchical recommended)
+- No business logic in the registry — pure mapping only
+- Must be loaded at app startup (imported in main.tsx or App.tsx)
+- New pages are registered here and ONLY here
+
+**SmartStack specifics**:
+- File: `componentRegistry.generated.ts`
+- Registration via `PageRegistry.register()` (v3.7+)
+- `PAGE_KEYS` constant for type-safe key references
+- Generated by MCP `scaffold_routes` tool
+
+### 2. ProtectedRoute
+
+**Role**: Front-end guard that validates permissions received from the API (defense in depth).
+
+**Requirements**:
+- Receives permission requirements from route config (NOT hardcoded)
+- Checks user permissions against route requirements
+- Redirects unauthorized users (to login or forbidden page)
+- Does NOT contain a list of routes or paths
+- Permissions come from the API, not from static constants
+
+**SmartStack specifics**:
+- File: `ProtectedRoute.tsx`
+- Replaced the old `RouteGuard.tsx` (which had hardcoded lists)
+- Uses `permissionPath` from menu API DTOs
+
+### 3. DynamicRouter
+
+**Role**: Rendering engine that generates `<Route>` elements from the API configuration.
+
+**Requirements**:
+- Iterates over API route config to create React Router `<Route>` elements
+- Resolves components from componentRegistry by key
+- Wraps routes with ProtectedRoute for permission checking
+- Handles nested routes (outlets, tabs)
+- Supports loading states (shows loader while config is being fetched)
+- No hardcoded route paths in the router itself
+
+**SmartStack specifics**:
+- File: `DynamicRouter.tsx`
+- Sole routing engine — App.tsx reduced to providers + DynamicRouter
+- Handles: dynamic app routes, feature gating, auto-redirects, outlet tab routes, doc routes
+- `OUTLET_SECTIONS` config for tab-based pages
+- `getStaticAppRoutes()` for per-app legacy redirects (migration period only)
+
+### 4. useRouteConfig
+
+**Role**: Hook that fetches route configuration + permissions from the API at mount.
+
+**Requirements**:
+- Calls navigation API on mount (or auth change)
+- Returns structured route config with components, paths, and permissions
+- Provides loading/error states
+- Caches appropriately (invalidates on auth change)
+- Flattens hierarchical menu into usable route entries
+
+**SmartStack specifics**:
+- File: `useRouteConfig.ts`
+- Flattens menu API response into `RouteConfigEntry[]`
+- Provides `byKey` and `byApplication` maps
+- Used by DynamicRouter to build routes
+
+### 5. Navigation API
+
+**Role**: Endpoint returning routes already filtered by JWT/session.
+
+**Requirements**:
+- Returns routes with: path, componentKey, permissions, children
+- Filters routes based on authenticated user's permissions
+- Hierarchical structure (Application > Module > Section > Resource)
+- Includes permission paths for front-end guard
+- Supports feature gating (license-based)
+
+**SmartStack specifics**:
+- Endpoint: `GET /api/navigation/menu`
+- Returns enriched DTOs at 4 levels (Application, Module, Section, Resource)
+- `ComponentKey` and `PermissionPath` on all 4 DTO levels
+- `RequiredFeature` for license-based feature gating
+- Built by `NavigationService.BuildApplicationMenu/BuildModuleMenu/BuildSectionMenu/BuildResourceMenu`
+
+## Expected API Response Structure
+
+```json
+{
+  "routes": [
+    {
+      "path": "/administration/users",
+      "componentKey": "administration.users.list",
+      "permissionPath": "administration.users",
+      "permissions": ["administration.users.access", "administration.users.read"],
+      "children": [
+        {
+          "path": ":id",
+          "componentKey": "administration.users.detail",
+          "permissions": ["administration.users.read"]
+        }
+      ]
+    }
+  ]
+}
+```
+
+## Common Anti-Patterns
+
+| Anti-Pattern | Description | Risk |
+|-------------|-------------|------|
+| Hardcoded routes in JSX | `<Route path="/admin" ...>` outside DynamicRouter | Routes drift from DB, permissions bypassed |
+| Static permission lists | `const ADMIN_PERMS = [...]` in components | Permissions out of sync with API |
+| Non-lazy imports in registry | `import Page from './Page'` (eager) | Bundle bloat, slow initial load |
+| Missing Suspense boundary | No `<Suspense>` around lazy components | Crashes on slow loads |
+| Route paths in components | `navigate('/admin/users')` with hardcoded paths | Tight coupling, breaks if DB paths change |
+| Permission checks without API | `if (user.role === 'admin')` | Bypasses permission system |
+| Duplicate route definitions | Routes in both DynamicRouter and static config | Conflicts, unpredictable behavior |
+| Missing loading state | No loader while route config is fetching | Flash of "not found" page |