@atlashub/smartstack-cli 3.21.0 → 3.23.0

package/templates/skills/apex/steps/step-00-init.md

@@ -7,6 +7,14 @@ next_step: steps/step-01-analyze.md
 
 # Step 0: Initialize
 
+**Before anything else**, display the version banner:
+
+```
+═══════════════════════════════════════════════════════════════
+  SmartStack APEX — v{{SMARTSTACK_VERSION}}
+═══════════════════════════════════════════════════════════════
+```
+
 ## LOAD SHARED
 
 Read `_shared.md` for SmartStack detection patterns and MCP tools reference.
@@ -133,20 +141,25 @@ IF save_mode:
 ## 7. Display Context Summary
 
 ```
-**APEX SmartStack - Initialization Complete**
-
-**Task:** {task_description}
-**Context:** {context_code} / {app_name} / {module_code}
-**Sections:** {sections}
-
-**Sources:**
-- PRD: {prd_path || "none"}
-- Feature: {feature_path || "none"}
-
-**Flags:** {active_flags}
-**MCP:** {available|degraded}
-**Needs migration:** {yes|no}
-**Needs seed data:** {yes|no}
+═══════════════════════════════════════════════════════════════
+  APEX INITIALIZATION COMPLETE
+  SmartStack CLI v{{SMARTSTACK_VERSION}}
+═══════════════════════════════════════════════════════════════
+
+| Field              | Value                                        |
+|--------------------|----------------------------------------------|
+| Task               | {task_description}                            |
+| Context            | {context_code} / {app_name} / {module_code}  |
+| Sections           | {sections}                                   |
+| PRD                | {prd_path || "none"}                          |
+| Feature            | {feature_path || "none"}                     |
+| Flags              | {active_flags}                               |
+| MCP                | {available|degraded}                         |
+| Needs migration    | {yes|no}                                     |
+| Needs seed data    | {yes|no}                                     |
+
+NEXT STEP: step-01-analyze
+═══════════════════════════════════════════════════════════════
 ```
 
 ---

package/templates/skills/apex/steps/step-01-analyze.md

@@ -12,10 +12,28 @@ next_step: steps/step-02-plan.md
 
 ## LOAD CONDITIONALLY
 
+- **ALWAYS** read `references/smartstack-api.md` — BaseEntity API, entity/config/controller patterns
 - If NOT `{economy_mode}`: read `references/agent-teams-protocol.md`
 
 ---
 
+## 0. Fresh Project Detection (Early Exit)
+
+```
+IF .smartstack/init-state.json exists:
+  Read it → check if project was recently initialized
+  Glob("src/**/Entities/**/*.cs") → count entity files
+
+  IF entity count == 0 AND no PRD AND no feature.json:
+    → SKIP full code exploration (sections 2-3)
+    → Declare: "Fresh project — all elements need to be CREATED"
+    → Jump directly to section 4 (Gap Analysis) with all items marked "create"
+```
+
+This saves ~2 minutes of Glob searches on an empty project.
+
+---
+
 ## 1. Context Sources
 
 Read available context (in order of priority):

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

@@ -13,6 +13,7 @@ All code goes through skills (/controller, /application, /ui-components, /efcore
 
 ## LOAD CONDITIONALLY
 
+- **ALWAYS** read `references/smartstack-api.md` — BaseEntity API, entity/config/controller patterns
 - Read `references/smartstack-layers.md` for execution rules per layer
 - If NOT `{economy_mode}` AND Layer 1 has parallel work: read `references/agent-teams-protocol.md`
 
@@ -25,7 +26,8 @@ All code goes through skills (/controller, /application, /ui-components, /efcore
 ```
 For each entity to create/modify:
   → MCP scaffold_extension (type: "entity", target: entity_name)
-  → Verify: inherits AuditableEntity, has IHasData if multi-tenant
+  → Verify: inherits BaseEntity, implements ITenantEntity + IAuditableEntity
+  → Verify entity matches patterns in references/smartstack-api.md
 ```
 
 ### EF Core Configurations
@@ -43,7 +45,7 @@ For each entity:
 1. MCP suggest_migration → get standardized name
 2. dotnet ef migrations add {Name} --project src/{Infra}.csproj --startup-project src/{Api}.csproj -o Persistence/Migrations
 3. dotnet ef database update (if local DB)
-4. dotnet build --no-restore → MUST PASS
+4. dotnet build → MUST PASS
 ```
 
 **BLOCKING:** If build fails after migration, fix EF configs before proceeding.
@@ -51,10 +53,10 @@ For each entity:
 ### Post-Layer 0 Build Gate
 
 ```bash
-dotnet build --no-restore
+dotnet build
 ```
 
-**MUST PASS before Layer 1. If failure, fix and retry.**
+**MUST PASS before Layer 1. If NuGet error, run `dotnet restore` first. If file lock (MSB3021), use `--output /tmp/{project}_build`.**
 
 ---
 
@@ -102,7 +104,7 @@ Spawn 2 teammates (Opus, full tools):
 Wait for both teammates to report completion.
 
 Build verification:
-  dotnet build --no-restore  (backend)
+  dotnet build  (backend)
   npm run typecheck           (frontend, if applicable)
 
 shutdown_request → shutdown_response → TeamDelete("apex-exec")
@@ -136,7 +138,7 @@ After Layer 1 completes:
    - DI registration added
 
 2. Build gate:
-   dotnet build --no-restore → MUST PASS
+   dotnet build → MUST PASS
    npm run typecheck → MUST PASS (if frontend)
 ```
 

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

@@ -126,6 +126,7 @@ sqlcmd -S "(localdb)\MSSQLLocalDB" -Q "IF DB_ID('$DB_NAME') IS NOT NULL BEGIN AL
 
 | File | Checks |
 |------|--------|
+| NavigationApplicationSeedData | MUST be first, deterministic GUID, 4 lang translations |
 | NavigationModuleSeedData | Deterministic GUIDs (SHA256), 4 languages, GetModuleEntry + GetTranslationEntries |
 | PermissionsSeedData | MCP generate_permissions used, paths match Permissions.cs, wildcard + CRUD |
 | RolesSeedData | Admin=wildcard, Manager=CRU, Contributor=CR, Viewer=R |
@@ -134,6 +135,97 @@ sqlcmd -S "(localdb)\MSSQLLocalDB" -Q "IF DB_ID('$DB_NAME') IS NOT NULL BEGIN AL
 
 ---
 
+## 6b. BLOCKING POST-CHECKs (bash verification on real files)
+
+> These checks run on the actual generated files. Model-interpreted checks are unreliable.
+
+### POST-CHECK 1: Navigation routes must be full paths starting with /
+
+```bash
+# Find all seed data files and check route values
+SEED_FILES=$(find src/ -path "*/Seeding/Data/*" -name "*.cs" 2>/dev/null)
+if [ -n "$SEED_FILES" ]; then
+  # Check for short routes (no leading /) in Create() calls for navigation entities
+  BAD_ROUTES=$(grep -Pn 'NavigationApplication\.Create\(|NavigationModule\.Create\(|NavigationSection\.Create\(|NavigationResource\.Create\(' $SEED_FILES | grep -v '"/[a-z]')
+  if [ -n "$BAD_ROUTES" ]; then
+    echo "BLOCKING: Navigation routes must be full paths starting with /"
+    echo "$BAD_ROUTES"
+    echo "Expected: \"/business/human-resources\" NOT \"humanresources\""
+    exit 1
+  fi
+fi
+```
+
+### POST-CHECK 2: All services must filter by TenantId (OWASP A01)
+
+```bash
+# Find all service implementation files
+SERVICE_FILES=$(find src/ -path "*/Services/*" -name "*Service.cs" ! -name "I*Service.cs" 2>/dev/null)
+if [ -n "$SERVICE_FILES" ]; then
+  # Check each service file has TenantId reference (either _currentUser.TenantId or TenantId filter)
+  for f in $SERVICE_FILES; do
+    if ! grep -q "TenantId" "$f"; then
+      echo "BLOCKING (OWASP A01): Service missing TenantId filter: $f"
+      echo "Every service query MUST filter by _currentUser.TenantId"
+      exit 1
+    fi
+    if grep -q "Guid.Empty" "$f"; then
+      echo "BLOCKING (OWASP A01): Service uses Guid.Empty instead of _currentUser.TenantId: $f"
+      exit 1
+    fi
+  done
+fi
+```
+
+### POST-CHECK 3: Controllers must use [RequirePermission], not just [Authorize]
+
+```bash
+# Find all controller files
+CTRL_FILES=$(find src/ -path "*/Controllers/*" -name "*Controller.cs" 2>/dev/null)
+if [ -n "$CTRL_FILES" ]; then
+  for f in $CTRL_FILES; do
+    # Check controller has at least one RequirePermission attribute
+    if grep -q "\[Authorize\]" "$f" && ! grep -q "\[RequirePermission" "$f"; then
+      echo "WARNING: Controller uses [Authorize] without [RequirePermission]: $f"
+      echo "Use [RequirePermission(Permissions.{Module}.{Action})] on each endpoint"
+    fi
+  done
+fi
+```
+
+### POST-CHECK 4: Seed data must not use Guid.NewGuid()
+
+```bash
+SEED_FILES=$(find src/ -path "*/Seeding/Data/*" -name "*.cs" 2>/dev/null)
+if [ -n "$SEED_FILES" ]; then
+  BAD_GUIDS=$(grep -n "Guid.NewGuid()" $SEED_FILES 2>/dev/null)
+  if [ -n "$BAD_GUIDS" ]; then
+    echo "BLOCKING: Seed data must use deterministic GUIDs (SHA256), not Guid.NewGuid()"
+    echo "$BAD_GUIDS"
+    exit 1
+  fi
+fi
+```
+
+### POST-CHECK 5: Services must inject ICurrentUser
+
+```bash
+SERVICE_FILES=$(find src/ -path "*/Services/*" -name "*Service.cs" ! -name "I*Service.cs" 2>/dev/null)
+if [ -n "$SERVICE_FILES" ]; then
+  for f in $SERVICE_FILES; do
+    if ! grep -q "ICurrentUser" "$f"; then
+      echo "BLOCKING: Service missing ICurrentUser injection: $f"
+      echo "All services MUST inject ICurrentUser for tenant isolation"
+      exit 1
+    fi
+  done
+fi
+```
+
+**If ANY POST-CHECK fails → fix in step-03, re-validate.**
+
+---
+
 ## 7. Acceptance Criteria POST-CHECK
 
 For each AC inferred in step-01:

package/templates/skills/apex/steps/step-07-tests.md

@@ -12,14 +12,15 @@ next_step: steps/step-08-run-tests.md
 
 ---
 
-## 1. Ensure Test Project Exists
+## 1. Ensure Test Projects Exist
+
+### 1a. Unit Test Project
 
 ```bash
-# Check for existing test project
-TEST_PROJECT=$(find tests/ -name "*.Tests.Unit.csproj" 2>/dev/null | head -1)
+# Check for existing unit test project
+UNIT_PROJECT=$(find tests/ -name "*.Tests.Unit.csproj" 2>/dev/null | head -1)
 
-if [ -z "$TEST_PROJECT" ]; then
-  # Create test project
+if [ -z "$UNIT_PROJECT" ]; then
   PROJECT_NAME=$(basename *.sln .sln)
   dotnet new xunit -n "${PROJECT_NAME}.Tests.Unit" -o "tests/${PROJECT_NAME}.Tests.Unit"
   dotnet add "tests/${PROJECT_NAME}.Tests.Unit" package Moq
@@ -31,6 +32,29 @@ if [ -z "$TEST_PROJECT" ]; then
 fi
 ```
 
+### 1b. Integration Test Project (for step-04 DB validation)
+
+```bash
+# Check for existing integration test project
+INT_PROJECT=$(find tests/ -name "*.Tests.Integration.csproj" 2>/dev/null | head -1)
+
+if [ -z "$INT_PROJECT" ]; then
+  PROJECT_NAME=$(basename *.sln .sln)
+  dotnet new xunit -n "${PROJECT_NAME}.Tests.Integration" -o "tests/${PROJECT_NAME}.Tests.Integration"
+  dotnet add "tests/${PROJECT_NAME}.Tests.Integration" package Moq
+  dotnet add "tests/${PROJECT_NAME}.Tests.Integration" package FluentAssertions
+  dotnet add "tests/${PROJECT_NAME}.Tests.Integration" package Respawn
+  dotnet add "tests/${PROJECT_NAME}.Tests.Integration" package Microsoft.EntityFrameworkCore.SqlServer
+  for proj in src/*/*.csproj; do
+    dotnet add "tests/${PROJECT_NAME}.Tests.Integration" reference "$proj"
+  done
+  dotnet sln add "tests/${PROJECT_NAME}.Tests.Integration/${PROJECT_NAME}.Tests.Integration.csproj"
+fi
+```
+
+> **Note:** Integration tests use `DatabaseFixture` + `Respawn` with SQL Server LocalDB.
+> See step-04 section 5c for details.
+
 ---
 
 ## 2. Scaffold Tests via MCP

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

@@ -50,7 +50,7 @@ public static class ApplicationRolesSeedData
 {
     // Deterministic GUIDs for application roles
     // Generated from: "role-{applicationId}-{roleType}"
-    private static readonly Guid ApplicationId = {ApplicationGuid}; // From NavigationApplicationSeedData
+    public static readonly Guid ApplicationId = NavigationApplicationSeedData.ApplicationId;
 
     public static readonly Guid AdminRoleId = GenerateRoleGuid("admin");
     public static readonly Guid ManagerRoleId = GenerateRoleGuid("manager");
@@ -141,7 +141,7 @@ public class ApplicationRoleSeedEntry
 |-------------|-------------|---------|
 | `{BaseNamespace}` | Root namespace of the client project | `SmartStack.Modules.RessourcesHumaines` |
 | `{AppLabel}` | Human-readable application label (EN) | `Human Resources` |
-| `{ApplicationGuid}` | GUID of the application (from NavigationApplicationSeedData) | `30f1fbba-e8c3-4879-9a49-d18deaa70a83` |
+| `ApplicationId` | Deterministic GUID from `NavigationApplicationSeedData.ApplicationId` — NO placeholder needed | Auto-resolved |
 
 ---
 

package/templates/skills/application/steps/step-05-frontend.md

@@ -102,7 +102,7 @@ This generates:
 
 > **CRITICAL:** This step is MANDATORY. Without it, routes exist as files but are invisible to the React Router. The page will be BLANK.
 
-After `scaffold_routes` generates the route files, you MUST manually insert the routes into `App.tsx`:
+After `scaffold_routes` generates the route files, you MUST manually insert the routes into `App.tsx`.
 
 **Step 4a:** Import the page components at the top of App.tsx:
 
@@ -112,33 +112,49 @@ import { {EntityName}Page } from '@/pages/{Context}/{Application}/{Module}/{Enti
 const {EntityName}Page = lazy(() => import('@/pages/{Context}/{Application}/{Module}/{EntityName}Page'));
 ```
 
-**Step 4b:** Find the correct Layout wrapper block in App.tsx:
+**Step 4b:** Detect the App.tsx routing pattern:
 
-| Context | Layout block to find |
-|---------|---------------------|
-| `platform.*` | `<Route path="/platform" element={<AdminLayout />}>` |
-| `business.*` | `<Route path="/business" element={<BusinessLayout />}>` |
-| `personal.*` | `<Route path="/personal/myspace" element={<UserLayout />}>` |
+Read App.tsx and detect which pattern is used:
 
-**Step 4c:** Insert route entries INSIDE the Layout block (as children, using relative paths):
+**Pattern A** — If App.tsx contains `contextRoutes: ContextRouteExtensions`:
+  → Add routes to `contextRoutes.{context}[]` with **RELATIVE** paths (no leading `/`)
 
-```tsx
-// ✅ CORRECT - Route added INSIDE the layout wrapper
-<Route path="/business" element={<BusinessLayout />}>
-  {/* ... existing routes ... */}
-  <Route path="{application}/{module}" element={<{EntityName}Page />} />
-</Route>
+  ```tsx
+  const contextRoutes: ContextRouteExtensions = {
+    business: [
+      // existing routes...
+      { path: '{application}/{module}/list', element: <{EntityName}ListPage /> },
+      { path: '{application}/{module}/new', element: <Create{EntityName}Page /> },
+      { path: '{application}/{module}/:id', element: <{EntityName}DetailPage /> },
+      { path: '{application}/{module}/:id/edit', element: <Create{EntityName}Page /> },
+    ],
+  };
+  ```
 
-// ❌ FORBIDDEN - Route added OUTSIDE layout (shell will NOT render!)
-<Route path="/business/{application}/{module}" element={<{EntityName}Page />} />
-```
+  Routes are automatically injected into BOTH standard (`/business/...`) and tenant-prefixed (`/t/:slug/business/...`) route trees by `mergeRoutes()`. No manual duplication needed.
+
+**Pattern B** — If App.tsx contains `<Route path="/{context}" element={<{Layout} />}>` (JSX Routes):
+  → Insert `<Route>` children inside the Layout wrapper (see below)
 
-**Step 4d:** ALSO add the same routes inside the tenant-prefixed block:
+  ```tsx
+  <Route path="/business" element={<BusinessLayout />}>
+    {/* ... existing routes ... */}
+    <Route path="{application}/{module}" element={<{EntityName}Page />} />
+  </Route>
+  ```
 
-Find `<Route path="/t/:slug">` and locate the matching `<Route path="{context}" element={<{Layout} />}>` inside it.
-Add the **same route entries** there.
+  ALSO add the same routes inside the tenant-prefixed block:
+  Find `<Route path="/t/:slug">` and add the **same route entries** there.
 
-**Step 4e:** Verify wiring:
+**Step 4c:** Context-to-Layout mapping:
+
+| Context | Layout Component | Route path |
+|---------|------------------|------------|
+| `platform.*` | `AdminLayout` | `/platform` |
+| `business.*` | `BusinessLayout` | `/business` |
+| `personal.*` | `UserLayout` | `/personal/myspace` |
+
+**Step 4d:** Verify wiring:
 
 ```
 Tool: mcp__smartstack__validate_frontend_routes
@@ -148,21 +164,10 @@ Args:
 
 If `appWiring.issues` is not empty, fix the wiring before proceeding.
 
-**For new applications (no existing layout route for the context):**
-
-If the context doesn't have a layout route yet, create one wrapping all child routes:
-
-```tsx
-<Route path="/{context}/{application}" element={<{Context}Layout />}>
-  <Route index element={<Navigate to="{default_module}" replace />} />
-  <Route path="{module}" element={<{EntityName}Page />} />
-</Route>
-```
-
-**FORBIDDEN:**
+**FORBIDDEN (both patterns):**
+- Adding business/platform/personal routes to `clientRoutes[]` with absolute paths — `clientRoutes` is ONLY for routes outside SmartStack contexts (e.g., `/about`, `/pricing`)
 - Adding routes OUTSIDE the Layout wrapper (shell will not render)
-- Adding routes only in the standard block but not in the tenant block
-- Using `createBrowserRouter` (SmartStack uses `BrowserRouter` with JSX `<Routes>`)
+- Using `createBrowserRouter` (SmartStack uses `useRoutes()` + `mergeRoutes()`)
 
 ### 5. Verify i18n Files
 

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

@@ -488,7 +488,51 @@ export const $moduleApi = {
 
 ## TEMPLATE: ROUTES (App.tsx)
 
-### ⚠️ CRITICAL RULE 1: ROUTES MUST BE INSIDE LAYOUT WRAPPER
+### Detect App.tsx Routing Pattern FIRST
+
+Before adding routes, **read App.tsx** and detect which pattern is used:
+
+| Pattern | How to detect | Action |
+|---------|---------------|--------|
+| **Pattern A** (mergeRoutes) | `contextRoutes: ContextRouteExtensions` present | Add to `contextRoutes.{context}[]` array |
+| **Pattern B** (JSX Routes) | `<Route path="/{context}" element={<{Layout} />}>` present | Insert `<Route>` children inside Layout wrapper |
+
+### Pattern A: mergeRoutes (contextRoutes array)
+
+> **This is the DEFAULT pattern** generated by `smartstack init`.
+> Routes added to `contextRoutes` are automatically injected into BOTH standard and tenant-prefixed route trees by `mergeRoutes()`. No manual duplication needed.
+
+```tsx
+// Add to App.tsx — imports at top
+import { $MODULE_PASCALPage } from '@/pages/$CONTEXT/$APPLICATION/$MODULE/$MODULE_PASCALPage';
+import { $MODULE_PASCALDetailPage } from '@/pages/$CONTEXT/$APPLICATION/$MODULE/$MODULE_PASCALDetailPage';
+import { Create$MODULE_PASCALPage } from '@/pages/$CONTEXT/$APPLICATION/$MODULE/Create$MODULE_PASCALPage';
+
+// Add routes to contextRoutes.{context}[] with RELATIVE paths (no leading /)
+const contextRoutes: ContextRouteExtensions = {
+  $CONTEXT: [
+    // ... existing routes ...
+    { path: '$APPLICATION/$MODULE', element: <$MODULE_PASCALPage /> },
+    { path: '$APPLICATION/$MODULE/new', element: <Create$MODULE_PASCALPage /> },
+    { path: '$APPLICATION/$MODULE/:id', element: <$MODULE_PASCALDetailPage /> },
+    { path: '$APPLICATION/$MODULE/:id/edit', element: <Create$MODULE_PASCALPage /> },
+  ],
+};
+```
+
+**mergeRoutes auto-generates redirects** for intermediate paths (e.g., `$APPLICATION` → `$APPLICATION/$DEFAULT_MODULE`) so you don't need to add index redirects manually.
+
+**Context-to-Layout mapping (automatic via mergeRoutes):**
+
+| Context key | Injected into Layout | Standard path | Tenant path |
+|-------------|---------------------|---------------|-------------|
+| `platform` | `AdminLayout` | `/platform/...` | `/t/:slug/platform/...` |
+| `business` | `BusinessLayout` | `/business/...` | `/t/:slug/business/...` |
+| `personal` | `UserLayout` | `/personal/myspace/...` | `/t/:slug/personal/myspace/...` |
+
+### Pattern B: JSX Routes (inside Layout wrapper)
+
+> **Legacy pattern** — only used if App.tsx was manually restructured with JSX `<Route>` elements.
 
 SmartStack layouts (`AdminLayout`, `BusinessLayout`, `UserLayout`) provide the application shell: **header with AvatarMenu**, sidebar, navigation. They render child pages via React Router's `<Outlet />`.
 
@@ -504,13 +548,6 @@ SmartStack layouts (`AdminLayout`, `BusinessLayout`, `UserLayout`) provide the a
 3. Add the new routes **INSIDE** that `<Route>` block
 4. If a tenant-prefixed block exists (`/t/:slug/...`), add the routes there too
 
-**❌ FORBIDDEN - Flat routes OUTSIDE layout (AvatarMenu disappears!)**
-```tsx
-// These routes bypass the layout system entirely = NO header, NO sidebar, NO AvatarMenu
-<Route path="/$CONTEXT/$APPLICATION/$MODULE" element={<$MODULE_PASCALPage />} />
-```
-
-**✅ MANDATORY - Routes INSIDE the existing layout wrapper**
 ```tsx
 // Add to App.tsx
 
@@ -533,42 +570,33 @@ import { Create$MODULE_PASCALPage } from '@/pages/$CONTEXT/$APPLICATION/$MODULE/
 </Route>
 ```
 
-### Context-to-Layout mapping
+### ⚠️ CRITICAL RULES (both patterns)
 
-| Context | Layout Component | Layout Route Path |
-|---------|------------------|-------------------|
-| `platform` | `AdminLayout` | `/platform` |
-| `business` | `BusinessLayout` | `/business` |
-| `personal` | `UserLayout` | `/personal/myspace` |
-
-### ⚠️ CRITICAL RULE 2: NESTED ROUTES MANDATORY
-
-React Router v7 **requires** nested routes for multi-module applications.
-
-**❌ FORBIDDEN - Flat routes (cause redirects to Home)**
+**FORBIDDEN — Adding to clientRoutes[] with absolute paths:**
 ```tsx
-<Route path="$APPLICATION" element={<Navigate to="/$CONTEXT/$APPLICATION/$DEFAULT_MODULE" replace />} />
-<Route path="$APPLICATION/$MODULE" element={<$MODULE_PASCALPage />} />
+// ❌ WRONG — bypasses layout entirely, shell will NOT render
+const clientRoutes: RouteConfig[] = [
+  { path: '/business/$APPLICATION/$MODULE', element: <$MODULE_PASCALPage /> },
+];
 ```
 
-**✅ MANDATORY - Nested routes with index**
+`clientRoutes` is ONLY for routes **outside** SmartStack locked contexts (e.g., `/about`, `/pricing`).
+
+**FORBIDDEN — Flat routes outside layout:**
 ```tsx
-<Route path="$APPLICATION">
-  <Route index element={<Navigate to="$DEFAULT_MODULE" replace />} />
-  <Route path="$MODULE" element={<$MODULE_PASCALPage />} />
-</Route>
+// ❌ WRONG (Pattern B only) — flat route bypasses layout
+<Route path="/$CONTEXT/$APPLICATION/$MODULE" element={<$MODULE_PASCALPage />} />
 ```
 
-### Why this structure?
+### Why nested/context routes?
 
-| Aspect | Flat routes | Nested routes |
-|--------|------------|----------------|
-| Shell rendered | ❌ No (bypasses layout) | ✅ Yes (Outlet pattern) |
-| AvatarMenu visible | ❌ No | ✅ Yes |
-| Matching | Ambiguous between siblings | Hierarchical clear |
-| Navigate | Must be absolute | Can be relative |
-| Outlet | Not supported | Supported |
-| Redirect | Can fail | Always works |
+| Aspect | clientRoutes (wrong) | contextRoutes / 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 |
 
 ---