@atlashub/smartstack-cli 4.28.0 → 4.30.0

package/.documentation/business-analyse.html

@@ -122,6 +122,11 @@
                             <a href="#step-03" class="sidebar-toc-link">03. Specify (Per-Module)</a>
                             <a href="#step-04" class="sidebar-toc-link">04. Consolidation</a>
                             <a href="#step-05" class="sidebar-toc-link">05. Handoff</a>
+                            <a href="#step-06" class="sidebar-toc-link">06. Extract</a>
+                            <a href="#companion-skills" class="sidebar-toc-link">
+                                <span data-lang="fr">Skills complementaires</span>
+                                <span data-lang="en">Companion Skills</span>
+                            </a>
                             <a href="#schemas" class="sidebar-toc-link">Schemas</a>
                             <a href="#agents" class="sidebar-toc-link">Agents</a>
                             <a href="#ids-refs" class="sidebar-toc-link">
@@ -904,6 +909,31 @@ Exemple:
                             At the handoff step, an interactive HTML document (<code>ba-interactive.html</code>) is deployed to the project directory. This document allows the client to review, edit and enrich the business analysis directly in their browser, without a server. Modifications can be re-imported via <code>/business-analyse -x &lt;json-path&gt;</code>.
                         </p>
 
+                        <div class="warning-block" style="background:rgba(255,170,0,0.1);border-left:4px solid #ffaa00;padding:1rem 1.2rem;border-radius:6px;margin:1rem 0;">
+                            <strong style="color:#ffaa00;">&#9888;
+                                <span data-lang="fr">Important : Source de verite</span>
+                                <span data-lang="en">Important: Source of Truth</span>
+                            </strong>
+                            <p data-lang="fr" style="margin:0.5rem 0 0;">
+                                Le HTML interactif est un <strong>livrable genere</strong>, pas une source de donnees. La source de verite est constituee par les fichiers JSON (<code>index.json</code>, <code>cadrage.json</code>, <code>entities.json</code>, etc.). Toute modification faite directement dans le HTML sera <strong>ecrasee</strong> a la prochaine regeneration via <code>/ba-generate-html</code>.
+                            </p>
+                            <p data-lang="en" style="margin:0.5rem 0 0;">
+                                The interactive HTML is a <strong>generated deliverable</strong>, not a data source. The source of truth is the JSON files (<code>index.json</code>, <code>cadrage.json</code>, <code>entities.json</code>, etc.). Any modification made directly in the HTML will be <strong>overwritten</strong> on the next regeneration via <code>/ba-generate-html</code>.
+                            </p>
+                            <p data-lang="fr" style="margin:0.5rem 0 0;">
+                                <strong>Pour conserver vos modifications :</strong><br>
+                                1. Exporter le JSON depuis le HTML (bouton d'export)<br>
+                                2. Re-importer avec <code>/business-analyse -x &lt;json-path&gt;</code> (met a jour les fichiers JSON sources)<br>
+                                3. Regenerer le HTML avec <code>/ba-generate-html</code>
+                            </p>
+                            <p data-lang="en" style="margin:0.5rem 0 0;">
+                                <strong>To preserve your modifications:</strong><br>
+                                1. Export JSON from the HTML (export button)<br>
+                                2. Re-import with <code>/business-analyse -x &lt;json-path&gt;</code> (updates source JSON files)<br>
+                                3. Regenerate the HTML with <code>/ba-generate-html</code>
+                            </p>
+                        </div>
+
                         <h4 data-lang="fr">Verification post-handoff</h4>
                         <h4 data-lang="en">Post-Handoff Verification</h4>
 
@@ -952,6 +982,193 @@ Exemple:
                         </div>
                     </section>
 
+                    <!-- ============================================ -->
+                    <!-- COMPANION SKILLS                              -->
+                    <!-- ============================================ -->
+                    <section id="companion-skills">
+                        <h2>
+                            <span data-lang="fr">Skills complementaires</span>
+                            <span data-lang="en">Companion Skills</span>
+                        </h2>
+
+                        <p data-lang="fr">
+                            Deux skills independants completent le workflow de business analyse pour la gestion du document HTML interactif.
+                        </p>
+                        <p data-lang="en">
+                            Two independent skills complement the business analysis workflow for managing the interactive HTML document.
+                        </p>
+
+                        <!-- /ba-generate-html -->
+                        <h3><code>/ba-generate-html</code></h3>
+
+                        <p data-lang="fr">
+                            Genere (ou regenere) le document HTML interactif a partir des fichiers JSON d'analyse. Ce skill lit les sources JSON (<code>index.json</code>, <code>cadrage.json</code>, fichiers modules) et produit un fichier <code>ba-interactive.html</code> autonome.
+                        </p>
+                        <p data-lang="en">
+                            Generates (or regenerates) the interactive HTML document from the analysis JSON files. This skill reads the JSON sources (<code>index.json</code>, <code>cadrage.json</code>, module files) and produces a standalone <code>ba-interactive.html</code> file.
+                        </p>
+
+                        <div class="code-block">
+                            <button class="copy-btn">Copy</button>
+<pre><code>/ba-generate-html FEAT-001
+/ba-generate-html FEAT-001 --force</code></pre>
+                        </div>
+
+                        <div class="table-container">
+                            <table class="reference-table">
+                                <thead>
+                                    <tr>
+                                        <th>Flag</th>
+                                        <th><span data-lang="fr">Effet</span><span data-lang="en">Effect</span></th>
+                                    </tr>
+                                </thead>
+                                <tbody>
+                                    <tr>
+                                        <td><code>--force</code></td>
+                                        <td><span data-lang="fr">Regenerer meme si le HTML existe deja</span><span data-lang="en">Regenerate even if HTML already exists</span></td>
+                                    </tr>
+                                </tbody>
+                            </table>
+                        </div>
+
+                        <h4><span data-lang="fr">Etapes internes</span><span data-lang="en">Internal Steps</span></h4>
+                        <div class="table-container">
+                            <table class="reference-table">
+                                <thead>
+                                    <tr>
+                                        <th>Step</th>
+                                        <th><span data-lang="fr">Role</span><span data-lang="en">Role</span></th>
+                                    </tr>
+                                </thead>
+                                <tbody>
+                                    <tr>
+                                        <td>01</td>
+                                        <td><span data-lang="fr">Lire les sources JSON (index, cadrage, modules, consolidation)</span><span data-lang="en">Read JSON sources (index, cadrage, modules, consolidation)</span></td>
+                                    </tr>
+                                    <tr>
+                                        <td>02</td>
+                                        <td><span data-lang="fr">Construire FEATURE_DATA + EMBEDDED_ARTIFACTS</span><span data-lang="en">Build FEATURE_DATA + EMBEDDED_ARTIFACTS</span></td>
+                                    </tr>
+                                    <tr>
+                                        <td>03</td>
+                                        <td><span data-lang="fr">Injecter dans le template ba-interactive.html</span><span data-lang="en">Inject into ba-interactive.html template</span></td>
+                                    </tr>
+                                    <tr>
+                                        <td>04</td>
+                                        <td><span data-lang="fr">Verification (taille &gt; 100KB, sections, coherence)</span><span data-lang="en">Verification (size &gt; 100KB, sections, coherence)</span></td>
+                                    </tr>
+                                </tbody>
+                            </table>
+                        </div>
+
+                        <div class="warning-block" style="background:rgba(255,170,0,0.1);border-left:4px solid #ffaa00;padding:1rem 1.2rem;border-radius:6px;margin:1rem 0;">
+                            <strong style="color:#ffaa00;">&#9888;
+                                <span data-lang="fr">Regeneration = ecrasement</span>
+                                <span data-lang="en">Regeneration = overwrite</span>
+                            </strong>
+                            <p data-lang="fr" style="margin:0.5rem 0 0;">
+                                <code>/ba-generate-html</code> ecrase le HTML existant. Si vous avez fait des modifications dans le HTML interactif, exportez d'abord le JSON puis re-importez avec <code>/business-analyse -x</code> avant de regenerer.
+                            </p>
+                            <p data-lang="en" style="margin:0.5rem 0 0;">
+                                <code>/ba-generate-html</code> overwrites the existing HTML. If you made modifications in the interactive HTML, first export the JSON then re-import with <code>/business-analyse -x</code> before regenerating.
+                            </p>
+                        </div>
+
+                        <!-- /ba-review -->
+                        <h3><code>/ba-review</code></h3>
+
+                        <p data-lang="fr">
+                            Applique les corrections client exportees depuis le HTML interactif et regenere le document. Ce skill attend un fichier <code>ba-review.json</code> contenant les modifications structurees.
+                        </p>
+                        <p data-lang="en">
+                            Applies client corrections exported from the interactive HTML and regenerates the document. This skill expects a <code>ba-review.json</code> file containing structured modifications.
+                        </p>
+
+                        <div class="code-block">
+                            <button class="copy-btn">Copy</button>
+<pre><code>/ba-review</code></pre>
+                        </div>
+
+                        <h4><span data-lang="fr">Workflow</span><span data-lang="en">Workflow</span></h4>
+                        <ol>
+                            <li data-lang="fr">Lire <code>ba-review.json</code> (exporte depuis le HTML interactif)</li>
+                            <li data-lang="en">Read <code>ba-review.json</code> (exported from interactive HTML)</li>
+                            <li data-lang="fr">Lire le master <code>index.json</code> existant</li>
+                            <li data-lang="en">Read the existing master <code>index.json</code></li>
+                            <li data-lang="fr">Creer une nouvelle version</li>
+                            <li data-lang="en">Create a new version</li>
+                            <li data-lang="fr">Appliquer les corrections (cadrage, modules, consolidation)</li>
+                            <li data-lang="en">Apply corrections (cadrage, modules, consolidation)</li>
+                            <li data-lang="fr">Regenerer le HTML via <code>/ba-generate-html</code></li>
+                            <li data-lang="en">Regenerate HTML via <code>/ba-generate-html</code></li>
+                        </ol>
+
+                        <h4><span data-lang="fr">Routage des corrections</span><span data-lang="en">Correction Routing</span></h4>
+                        <div class="table-container">
+                            <table class="reference-table">
+                                <thead>
+                                    <tr>
+                                        <th><span data-lang="fr">Type de modification</span><span data-lang="en">Modification Type</span></th>
+                                        <th><span data-lang="fr">Action declenchee</span><span data-lang="en">Triggered Action</span></th>
+                                    </tr>
+                                </thead>
+                                <tbody>
+                                    <tr>
+                                        <td><span data-lang="fr">Entites / regles / UC / permissions</span><span data-lang="en">Entities / rules / UC / permissions</span></td>
+                                        <td><span data-lang="fr">Re-execution <code>/business-analyse</code> step-03</span><span data-lang="en">Re-run <code>/business-analyse</code> step-03</span></td>
+                                    </tr>
+                                    <tr>
+                                        <td><span data-lang="fr">Ecrans / wireframes / navigation</span><span data-lang="en">Screens / wireframes / navigation</span></td>
+                                        <td><span data-lang="fr">Re-execution <code>/ba-design-ui</code></span><span data-lang="en">Re-run <code>/ba-design-ui</code></span></td>
+                                    </tr>
+                                    <tr>
+                                        <td><span data-lang="fr">Les deux</span><span data-lang="en">Both</span></td>
+                                        <td><span data-lang="fr">Re-specification complete</span><span data-lang="en">Full re-specification</span></td>
+                                    </tr>
+                                    <tr>
+                                        <td><span data-lang="fr">Cadrage uniquement</span><span data-lang="en">Cadrage only</span></td>
+                                        <td><span data-lang="fr">Regeneration HTML uniquement</span><span data-lang="en">HTML regeneration only</span></td>
+                                    </tr>
+                                    <tr>
+                                        <td><span data-lang="fr">Client approuve</span><span data-lang="en">Client approves</span></td>
+                                        <td><code>/derive-prd</code></td>
+                                    </tr>
+                                </tbody>
+                            </table>
+                        </div>
+
+                        <!-- Workflow recap -->
+                        <h3><span data-lang="fr">Cycle de vie complet</span><span data-lang="en">Complete Lifecycle</span></h3>
+
+                        <div class="code-block">
+<pre><code><span data-lang="fr"># 1. Analyse initiale (genere les JSON + HTML)
+/business-analyse My Application Description
+
+# 2. Client consulte le HTML, fait des modifications, exporte le JSON
+
+# 3a. Re-import des modifications client dans les JSON sources
+/business-analyse -x ./docs/business/MyApp/ba-export.json
+
+# 3b. OU appliquer des corrections structurees
+/ba-review
+
+# 4. Regenerer le HTML apres modifications des JSON
+/ba-generate-html FEAT-001</span><span data-lang="en"># 1. Initial analysis (generates JSON + HTML)
+/business-analyse My Application Description
+
+# 2. Client reviews the HTML, makes modifications, exports JSON
+
+# 3a. Re-import client modifications into source JSONs
+/business-analyse -x ./docs/business/MyApp/ba-export.json
+
+# 3b. OR apply structured corrections
+/ba-review
+
+# 4. Regenerate HTML after JSON modifications
+/ba-generate-html FEAT-001</span></code></pre>
+                        </div>
+                    </section>
+
                     <!-- ============================================ -->
                     <!-- SCHEMAS                                      -->
                     <!-- ============================================ -->

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@atlashub/smartstack-cli",
-  "version": "4.28.0",
+  "version": "4.30.0",
   "description": "SmartStack Claude Code automation toolkit - GitFlow, EF Core migrations, prompts and more",
   "author": {
     "name": "SmartStack",

package/templates/skills/apex/references/frontend-route-wiring-app-tsx.md

@@ -56,20 +56,42 @@ Read App.tsx and detect which pattern is used:
 
 → Add routes to `applicationRoutes.{application}[]` with **RELATIVE** paths (no leading `/`)
 
+> **CRITICAL — Include Module Segment:** Paths are relative to `/{application}/`.
+> For a 3-level hierarchy (app → module → sections), paths MUST be `{module_kebab}/{section_kebab}`.
+> Using just `{section_kebab}` omits the module segment → route resolves to `/{app}/{section}` instead
+> of `/{app}/{module}/{section}` → mismatch with backend navigation seed data → 404.
+
 ```tsx
 const applicationRoutes: ApplicationRouteExtensions = {
   'human-resources': [
     // existing routes...
+    // Paths include module segment: employee-management/employees (NOT just employees)
     { path: '{module_kebab}/{section_kebab}', element: <{EntityName}ListPage /> },
     { path: '{module_kebab}/{section_kebab}/create', element: <Create{EntityName}Page /> },
     { path: '{module_kebab}/{section_kebab}/:id', element: <{EntityName}DetailPage /> },
-    { path: '{module_kebab}/{section_kebab}/:id/edit', element: <Create{EntityName}Page /> },
+    { path: '{module_kebab}/{section_kebab}/:id/edit', element: <Edit{EntityName}Page /> },
 
     // Parent redirect routes (MANDATORY — prevents /login redirect on parent navigation)
     { path: '{module_kebab}', element: <Navigate to="{module_kebab}/{first_section_kebab}" replace /> },
     { path: '', element: <Navigate to="{first_module_kebab}/{first_section_kebab}" replace /> },
   ],
 };
+
+// Concrete example: app=human-resources, module=employee-management, sections=employees,absences
+const applicationRoutes: ApplicationRouteExtensions = {
+  'human-resources': [
+    { path: 'employee-management/employees', element: <EmployeesPage /> },           // ✅
+    { path: 'employee-management/employees/create', element: <CreateEmployeePage /> }, // ✅
+    { path: 'employee-management/employees/:id', element: <EmployeeDetailPage /> },   // ✅
+    // ...absences...
+    { path: 'employee-management', element: <Navigate to="employee-management/employees" replace /> },
+    { path: '', element: <Navigate to="employee-management/employees" replace /> },
+  ],
+};
+
+// ❌ WRONG — missing module segment:
+// { path: 'employees', ... }  → resolves to /human-resources/employees (backend expects /human-resources/employee-management/employees)
+```
 ```
 
 Routes are automatically injected into BOTH standard (`/{application}/...`) and tenant-prefixed (`/t/:slug/{application}/...`) route trees by `mergeRoutes()`. No manual duplication needed.
@@ -162,10 +184,10 @@ For each application, add:
    { path: '{module}', element: <Navigate to="{module}/{first_section}" replace /> }
    ```
 
-**Example:** For NavRoutes `human-resources.employees.management` and `human-resources.employees.departments`:
+**Example:** For NavRoutes `human-resources.employee-management.employees` and `human-resources.employee-management.absences`:
 ```tsx
-{ path: 'employees', element: <Navigate to="employees/management" replace /> },
-{ path: '', element: <Navigate to="employees/management" replace /> },
+{ path: 'employee-management', element: <Navigate to="employee-management/employees" replace /> },
+{ path: '', element: <Navigate to="employee-management/employees" replace /> },
 ```
 
 The `to` prop is resolved relative to the **parent route** (`/{application}`), so always use the full path from the application root.
@@ -186,12 +208,12 @@ The `to` prop is resolved relative to the **parent route** (`/{application}`), s
     { path: '/human-resources/employees/management', element: <EmployeePage /> },
   ];
   ```
-  Custom application routes go in `applicationRoutes` with RELATIVE paths:
+  Custom application routes go in `applicationRoutes` with RELATIVE paths (including module segment):
   ```tsx
-  // ✅ CORRECT
+  // ✅ CORRECT — module segment included
   const applicationRoutes: ApplicationRouteExtensions = {
     'human-resources': [
-      { path: 'employees/management', element: <EmployeePage /> },
+      { path: 'employee-management/employees', element: <EmployeesPage /> },
     ],
   };
   ```

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

@@ -1884,6 +1884,48 @@ if [ -n "$CTRL_FILES" ]; then
 fi
 ```
 
+### POST-CHECK C52: Frontend route paths must include module segment (BLOCKING)
+
+> **Source:** APEX regression — frontend routes used `employees` instead of `employee-management/employees`,
+> causing mismatch with backend navigation seed data routes (`/human-resources/employee-management/employees`).
+> Nav links produced 404 because React Router had no matching route for the full path.
+
+```bash
+# Compare frontend route paths in App.tsx against backend navigation seed data routes
+APP_TSX=$(find . -path "*/src/App.tsx" -not -path "*/node_modules/*" 2>/dev/null | head -1)
+if [ -n "$APP_TSX" ]; then
+  # Extract all route paths from applicationRoutes
+  ROUTE_PATHS=$(grep -oP "path:\s*'[^']+'" "$APP_TSX" | grep -v "^path: ''" | grep -v ":id" | grep -v "create" | grep -v "edit" | sed "s/path: '//;s/'//")
+
+  # Find navigation seed data files to get backend routes
+  NAV_SEED_FILES=$(find src/ -name "*NavigationSeedData.cs" -o -name "*NavigationModuleSeedData.cs" 2>/dev/null)
+  if [ -n "$NAV_SEED_FILES" ]; then
+    # Extract module codes from seed data
+    MODULE_CODES=$(grep -oP 'Code\s*=\s*"\K[^"]+' $NAV_SEED_FILES 2>/dev/null | sort -u)
+
+    for route in $ROUTE_PATHS; do
+      # Skip redirect paths (empty or just module)
+      if [ -z "$route" ]; then continue; fi
+
+      # Check if route contains a slash (module/section pattern)
+      if ! echo "$route" | grep -q "/"; then
+        # Single segment route — check if it matches a section code (not a module code)
+        IS_MODULE=false
+        for mod in $MODULE_CODES; do
+          if [ "$route" = "$mod" ]; then IS_MODULE=true; break; fi
+        done
+        if [ "$IS_MODULE" = false ]; then
+          echo "BLOCKING: Frontend route '$route' is missing module segment"
+          echo "  Expected: '{module}/{route}' (e.g., 'employee-management/$route')"
+          echo "  Backend navigation seed data defines routes with full hierarchy: /app/module/section"
+          echo "  Frontend routes must match: module/section (relative to app root)"
+        fi
+      fi
+    done
+  fi
+fi
+```
+
 ---
 
 ## Architecture — Clean Architecture Layer Isolation

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

@@ -14,8 +14,9 @@
 
 ```tsx
 // Named exports — use .then() to wrap
+// Path: @/pages/{App}/{Module}/{Section}/{Page}
 const EmployeesPage = lazy(() =>
-  import('@/pages/HumanResources/Employees/EmployeesPage')
+  import('@/pages/HumanResources/EmployeeManagement/Employees/EmployeesPage')
     .then(m => ({ default: m.EmployeesPage }))
 );
 
@@ -49,7 +50,7 @@ element: (
 **Incorrect patterns:**
 ```tsx
 // WRONG: static import in route file
-import { EmployeesPage } from '@/pages/HumanResources/Employees/EmployeesPage';
+import { EmployeesPage } from '@/pages/HumanResources/EmployeeManagement/Employees/EmployeesPage';
 
 // WRONG: no Suspense wrapper
 element: <EmployeesPage />
@@ -64,8 +65,9 @@ In the client `App.tsx` (where application routes are defined), all page imports
 
 **Correct — Lazy imports in client App.tsx:**
 ```tsx
+// Path includes module level: {App}/{Module}/{Section}/{Page}
 const ClientsListPage = lazy(() =>
-  import('@/pages/HumanResources/Clients/ClientsListPage')
+  import('@/pages/HumanResources/ClientManagement/Clients/ClientsListPage')
     .then(m => ({ default: m.ClientsListPage }))
 );
 ```
@@ -73,7 +75,7 @@ const ClientsListPage = lazy(() =>
 **Do not use — Static imports in client App.tsx:**
 ```tsx
 // WRONG: Static import kills code splitting
-import { ClientsListPage } from '@/pages/HumanResources/Clients/ClientsListPage';
+import { ClientsListPage } from '@/pages/HumanResources/ClientManagement/Clients/ClientsListPage';
 ```
 
 > **Note:** The `smartstackRoutes.tsx` from the npm package may use static imports internally — this is acceptable for the package. But client `App.tsx` code MUST always use lazy imports for business pages.
@@ -698,18 +700,19 @@ export function EntityEditPage() {
 
 ```tsx
 // In route files — form pages are also lazy-loaded
+// Path: @/pages/{App}/{Module}/{Section}/{Page}
 const EntityCreatePage = lazy(() =>
-  import('@/pages/HumanResources/Employees/EntityCreatePage')
+  import('@/pages/HumanResources/EmployeeManagement/Employees/EntityCreatePage')
     .then(m => ({ default: m.EntityCreatePage }))
 );
 const EntityEditPage = lazy(() =>
-  import('@/pages/HumanResources/Employees/EntityEditPage')
+  import('@/pages/HumanResources/EmployeeManagement/Employees/EntityEditPage')
     .then(m => ({ default: m.EntityEditPage }))
 );
 
-// Route registration — form pages have their own routes
+// Route registration — Pattern B (JSX nested children):
 {
-  path: 'employees',
+  path: 'employee-management/employees',
   children: [
     { index: true, element: <Suspense fallback={<PageLoader />}><EmployeesPage /></Suspense> },
     { path: 'create', element: <Suspense fallback={<PageLoader />}><EntityCreatePage /></Suspense> },
@@ -718,6 +721,18 @@ const EntityEditPage = lazy(() =>
   ]
 }
 
+// Route registration — Pattern A (applicationRoutes flat paths):
+// CRITICAL: paths are RELATIVE to /{app}/ and MUST include the module segment
+const applicationRoutes: ApplicationRouteExtensions = {
+  'human-resources': [
+    { path: 'employee-management/employees', element: <EmployeesPage /> },           // ✅ includes module
+    { path: 'employee-management/employees/create', element: <CreateEmployeePage /> }, // ✅
+    { path: 'employee-management/employees/:id', element: <EmployeeDetailPage /> },   // ✅
+    { path: 'employee-management/employees/:id/edit', element: <EditEmployeePage /> }, // ✅
+    // ❌ WRONG: { path: 'employees', ... } — missing module segment → 404 on nav click
+  ],
+};
+
 // Section-level routes — children of the module route (when module has sections)
 //
 // > **IMPORTANT:** The `list` and `detail` sections do NOT generate additional route entries.

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

@@ -315,39 +315,55 @@ const [loading, setLoading] = useState(true);
 
 **Order (MANDATORY):**
 
-1. Index/list route (path: `''` or `'{section}'`)
-2. Create route (`'{section}/create'`)
-3. Static sections (`'{section}/dashboard'`, `'{section}/departments'`, etc.)
-4. Dynamic routes (`'{section}/:id'`, `'{section}/:id/edit'`)
-5. Redirect routes (`Navigate`) — ALWAYS LAST
+1. Index/list route (path: `'{module}/{section}'`)
+2. Create route (`'{module}/{section}/create'`)
+3. Static sections (`'{module}/{section}/dashboard'`, etc.)
+4. Dynamic routes (`'{module}/{section}/:id'`, `'{module}/{section}/:id/edit'`)
+5. Module redirect (`'{module}'` → `'{module}/{first_section}'`)
+6. Application redirect (`''` → `'{first_module}/{first_section}'`) — ALWAYS LAST
 
 ```tsx
-// ✅ CORRECT — static before dynamic
+// ✅ CORRECT — module segment included, static before dynamic
+// (inside applicationRoutes['human-resources'], paths are relative to /human-resources/)
+{ path: 'employee-management/employees', element: <EmployeesPage /> },
+{ path: 'employee-management/employees/create', element: <CreateEmployeePage /> },
+{ path: 'employee-management/employees/dashboard', element: <EmployeeDashboardPage /> },
+{ path: 'employee-management/employees/:id', element: <EmployeeDetailPage /> },
+{ path: 'employee-management/employees/:id/edit', element: <EditEmployeePage /> },
+{ path: 'employee-management', element: <Navigate to="employee-management/employees" replace /> },
+{ path: '', element: <Navigate to="employee-management/employees" replace /> },
+
+// ❌ WRONG — missing module segment (resolves to /human-resources/employees instead of /human-resources/employee-management/employees)
 { path: 'employees', element: <EmployeesPage /> },
-{ path: 'employees/create', element: <CreateEmployeePage /> },
-{ path: 'employees/dashboard', element: <EmployeeDashboardPage /> },
-{ path: 'employees/:id', element: <EmployeeDetailPage /> },
-{ path: 'employees/:id/edit', element: <EditEmployeePage /> },
-{ path: '', element: <Navigate to="employees" replace /> },
 
 // ❌ WRONG — :id before dashboard → dashboard is unreachable (matched as id="dashboard")
-{ path: 'employees/:id', element: <EmployeeDetailPage /> },
-{ path: 'employees/dashboard', element: <EmployeeDashboardPage /> },  // NEVER REACHED
+{ path: 'employee-management/employees/:id', element: <EmployeeDetailPage /> },
+{ path: 'employee-management/employees/dashboard', element: <EmployeeDashboardPage /> },  // NEVER REACHED
 ```
 
 POST-CHECK C49 detects this anti-pattern and BLOCKS.
 
 ### Section Routes (when module has sections)
 
-If the module defines `{sections}`, generate frontend routes for EACH section as children of the module route:
+If the module defines `{sections}`, generate frontend routes for EACH section as children of the application route.
+
+> **CRITICAL — Module Segment Required:** Route paths in `applicationRoutes['{app}']` are RELATIVE to the application root.
+> They MUST include the module segment: `{module-kebab}/{section-kebab}`, NOT just `{section-kebab}`.
+> Without the module segment, the route resolves to `/{app}/{section}` instead of `/{app}/{module}/{section}`,
+> causing a mismatch with backend navigation seed data routes → nav links produce 404s.
 
 ```tsx
-// Section routes are nested inside the module's children array
+// Routes in applicationRoutes['human-resources'] — RELATIVE paths include module segment
 // IMPORTANT: static routes BEFORE dynamic routes (see Route Ordering rule above)
-{ path: '{section-kebab}', element: <Suspense fallback={<PageLoader />}><{Section}Page /></Suspense> },
-{ path: '{section-kebab}/create', element: <Suspense fallback={<PageLoader />}><Create{Section}Page /></Suspense> },
-{ path: '{section-kebab}/:id', element: <Suspense fallback={<PageLoader />}><{Section}DetailPage /></Suspense> },
-{ path: '{section-kebab}/:id/edit', element: <Suspense fallback={<PageLoader />}><Edit{Section}Page /></Suspense> },
+// Example: app=human-resources, module=employee-management, section=employees
+{ path: '{module-kebab}/{section-kebab}', element: <Suspense fallback={<PageLoader />}><{Section}Page /></Suspense> },
+{ path: '{module-kebab}/{section-kebab}/create', element: <Suspense fallback={<PageLoader />}><Create{Section}Page /></Suspense> },
+{ path: '{module-kebab}/{section-kebab}/:id', element: <Suspense fallback={<PageLoader />}><{Section}DetailPage /></Suspense> },
+{ path: '{module-kebab}/{section-kebab}/:id/edit', element: <Suspense fallback={<PageLoader />}><Edit{Section}Page /></Suspense> },
+
+// Concrete example:
+// { path: 'employee-management/employees', element: ... },         → /human-resources/employee-management/employees ✅
+// { path: 'employees', element: ... },                             → /human-resources/employees ❌ WRONG (missing module)
 ```
 
 Section pages live in `src/pages/{AppPascal}/{Module}/{Section}/`.

package/templates/skills/apex/steps/step-03-execute.md

@@ -427,6 +427,11 @@ For each module:
   → Read App.tsx and detect the routing pattern
   → Pattern A (`applicationRoutes: ApplicationRouteExtensions`): add routes to `applicationRoutes['{application_kebab}'][]` with RELATIVE paths
   → Pattern B (JSX `<Route>`): nest routes inside `<Route path="/{application}" element={<AppLayout />}>` + duplicate in tenant block
+  → **CRITICAL — Module Segment Required:** Route paths MUST include the module segment.
+    For a 3-level hierarchy (app → module → sections), paths are `{module_kebab}/{section_kebab}`.
+    Example: `employee-management/employees` NOT just `employees`.
+    Without the module segment, routes resolve to `/{app}/{section}` instead of `/{app}/{module}/{section}`,
+    causing mismatch with backend navigation seed data → nav links produce 404s.
   → **BEFORE wiring:** Verify route ordering — static routes (`create`, `dashboard`, `departments`) MUST come BEFORE dynamic routes (`:id`, `:id/edit`). Redirect routes (`Navigate`) MUST be LAST. See `references/smartstack-layers.md` "RULE — Frontend Route Ordering".
   → Do not add business routes to `clientRoutes[]` — it is only for non-app routes (`/about`, `/pricing`)
   → All business applications use `<AppLayout />` as layout wrapper
@@ -482,7 +487,9 @@ For each module:
     5. Verify: `grep -q "{module_namespace}" src/**/i18n/config.ts` → must match
 - Permissions: Call MCP generate_permissions for the module permission root (2 segments: {app}.{module}),
   then also call MCP generate_permissions for each section (3 segments: {app}.{module}.{section}).
-- Section routes: Add section child routes to the module's children array.
+- Section routes: Add section child routes to `applicationRoutes['{app_kebab}']`.
+  Route paths MUST include the module segment: `{module_kebab}/{section_kebab}` (e.g., `employee-management/employees`).
+  Do NOT use just `{section_kebab}` (e.g., `employees`) — this omits the module level and causes 404s.
   Wire PermissionGuard for section routes with section-level permissions.
 - MUST use src/pages/{App}/{Module}/ hierarchy (NOT flat)
 
@@ -519,6 +526,7 @@ IF NOT economy_mode AND entities.length > 1:
         - API client: MCP scaffold_api_client
         - Routes: MCP scaffold_routes (outputFormat: "applicationRoutes", dryRun: false) → MUST generate navRoutes.generated.ts
         - Wire Routes to App.tsx (BLOCKING): detect Pattern A/B, wire accordingly
+          → CRITICAL: Route paths MUST include module segment: {module_kebab}/{section_kebab} (e.g., employee-management/employees, NOT just employees)
           → See references/frontend-route-wiring-app-tsx.md for full patterns
           → Verify: mcp__smartstack__validate_frontend_routes (scope: "routes")
         - Pages: /ui-components skill (ALL 4 types: List, Detail, Create, Edit)
@@ -539,6 +547,7 @@ ELSE:
     1. MCP scaffold_api_client
     2. MCP scaffold_routes (outputFormat: 'applicationRoutes')
     3. Wire routes to App.tsx (Pattern A/B — see references/frontend-route-wiring-app-tsx.md)
+       CRITICAL: paths MUST include module segment: {module_kebab}/{section_kebab} (e.g., employee-management/employees)
     4. **INVOKE Skill("ui-components")** — pass entity context:
        - Entity: {EntityName}, Module: {ModuleName}, App: {AppName}
        - Page types: List, Detail, Create, Edit (+ Dashboard if applicable)

package/templates/skills/apex/steps/step-04-examine.md

@@ -65,6 +65,9 @@ Verify:
 - Routes nested inside correct Layout wrapper
 - Route paths match controller patterns
 - No orphan routes
+- Route paths include module segment (e.g., 'employee-management/employees', NOT just 'employees')
+  → Compare frontend route paths in App.tsx against backend NavigationSeedData routes
+  → If backend defines route /app/module/section, frontend must use module/section (relative)
 ```
 
 ### 3b. Frontend Page Completeness
@@ -196,6 +199,7 @@ AC2: {criterion} → PASS / FAIL (evidence: {file:line or test})
 | I18n registration | Namespaces registered in i18n config (POST-CHECK C39) | PASS / N/A |
 | Validators DI | FluentValidation registered in DI (POST-CHECK C40) | PASS / N/A |
 | Route/NavRoute conflict | No [Route] alongside [NavRoute] on controllers (POST-CHECK C43) | PASS / N/A |
+| Route module segment | Frontend routes include module segment matching seed data (POST-CHECK C52) | PASS / N/A |
 | Role-permission matrix | Admin=wildcard, Manager=CRU, Contributor=CR, Viewer=R (POST-CHECK C44) | PASS / N/A |
 | PermissionAction enum | No Enum.Parse, only typed enum values 0-10 (POST-CHECK C45) | PASS / N/A |
 | Navigation translations | 4 langs per level, section/resource translations present (POST-CHECK C46) | PASS / N/A |