@atlashub/smartstack-cli 4.13.0 → 4.16.1

package/package.json

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

package/templates/mcp-scaffolding/frontend/api-client.ts.hbs

@@ -1,3 +1,4 @@
+{{!-- DEPRECATED: Ce template n'est plus utilisé. scaffold_api_client génère le code inline. --}}
 {{!-- SmartStack API Client Template --}}
 {{!-- Generates type-safe API client with NavRoute integration --}}
 

package/templates/skills/apex/references/agent-teams-protocol.md

@@ -43,13 +43,36 @@ Task:
 
 ## Task List Coordination (T10)
 
-Team lead manages the task list:
+### Task Creation (by team lead, BEFORE spawning teammates)
+
+Tasks MUST be created upfront for the full layer scope:
+
+```
+FOR EACH entity in layer:
+  TaskCreate(
+    subject: "Layer {N}: {Entity} {layer_type}",
+    description: "{detailed scope: files, skills, MCP tools}",
+    activeForm: "{Building/Creating} {Entity} {layer_type}"
+  )
+```
+
+### Task Assignment (by team lead, WHEN spawning)
+
+Include task ID and metadata context in teammate prompt:
+
+```
+"Your assigned task ID is {task_id}.
+ Your metadata context: entities={entities}, layer={layer}, tools={tools}.
+ Call TaskUpdate(taskId: '{task_id}', status: 'in_progress') before starting.
+ Call TaskUpdate(taskId: '{task_id}', status: 'completed', metadata: { files_created: [...] }) after ENTITY_COMPLETE message."
+```
+
+### Task Monitoring (by team lead)
 
 ```
-1. TaskCreate: create task for each work item, assign owner
-2. Teammate: TaskUpdate(status: "in_progress") before starting
-3. Teammate: TaskUpdate(status: "completed") after finishing
-4. Lead: TaskList to monitor progress
+1. TaskList() — check progress after each teammate message
+2. All tasks completed → proceed to build gate
+3. Any task stuck → investigate, reassign if needed
 ```
 
 ---

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

@@ -24,6 +24,23 @@ const {EntityName}Page = lazy(() => import('@/pages/{Application}/{Module}/{Enti
 
 ---
 
+## Step 4a.5: Import Generated Route Extensions (if scaffold_routes was used)
+
+If `scaffold_routes` generated `applicationRoutes.generated.tsx`, import and spread:
+
+```tsx
+import { applicationRouteExtensions } from '@/routes/applicationRoutes.generated';
+
+const applicationRoutes: ApplicationRouteExtensions = {
+  ...applicationRouteExtensions,
+  // additional manual routes if needed...
+};
+```
+
+If no generated file exists, add routes directly to the existing `applicationRoutes` object.
+
+---
+
 ## Step 4b: Detect App.tsx Routing Pattern
 
 Read App.tsx and detect which pattern is used:
@@ -81,6 +98,27 @@ Find `<Route path="/t/:slug">` and add the **same route entries** there.
 
 ---
 
+## Step 4b.5: Verify mergeRoutes() Call (BLOCKING)
+
+**BEFORE modifying routes, READ App.tsx and verify the `mergeRoutes()` call has 2 parameters.**
+
+✅ Correct:
+```tsx
+const routes = mergeRoutes(clientRoutes, applicationRoutes);
+```
+
+❌ If you see only 1 parameter:
+```tsx
+const routes = mergeRoutes(clientRoutes);
+```
+
+→ Add the `applicationRoutes` object and pass it as 2nd parameter.
+Without it, ALL application routes are silently ignored → blank page or /login redirect.
+
+**NEVER remove the `applicationRoutes` parameter or the `ApplicationRouteExtensions` import.**
+
+---
+
 ## Step 4c: Application-to-Layout Mapping
 
 | Application prefix | Layout Component | Route path |
@@ -136,6 +174,23 @@ The `to` prop is resolved relative to the **parent route** (`/{application}`), s
 - Adding application routes to `clientRoutes[]` with absolute paths — `clientRoutes` is ONLY for routes outside SmartStack applications (e.g., `/about`, `/pricing`)
 - Adding routes OUTSIDE the Layout wrapper (shell will not render)
 - Using `createBrowserRouter` (SmartStack uses `useRoutes()` + `mergeRoutes()`)
+- Adding custom application routes to `clientRoutes[]` with absolute paths:
+  ```tsx
+  // ❌ WRONG — bypasses RouteGuard + TenantLayout + AppLayout → /login redirect
+  const clientRoutes: RouteConfig[] = [
+    { path: '/human-resources/employees/management', element: <EmployeePage /> },
+  ];
+  ```
+  Custom application routes MUST go in `applicationRoutes` with RELATIVE paths:
+  ```tsx
+  // ✅ CORRECT
+  const applicationRoutes: ApplicationRouteExtensions = {
+    'human-resources': [
+      { path: 'employees/management', element: <EmployeePage /> },
+    ],
+  };
+  ```
+- Removing the `applicationRoutes` 2nd parameter from `mergeRoutes()` — this silently breaks ALL custom routes
 
 ---
 

package/templates/skills/apex/steps/step-02-plan.md

@@ -155,6 +155,138 @@ Write to `{output_dir}/02-plan.md` with the complete plan.
 
 ---
 
+## 8. Create Task List (MANDATORY)
+
+> **Visibility:** TaskCreate generates the grouped progress UI with checkboxes.
+> This makes APEX execution trackable and predictable for the user.
+
+After plan is finalized (auto_mode or user approved):
+
+### Task Creation Rules
+
+1. Create ONE task per layer (Layer 0-4)
+2. For multi-entity layers (2, 3): create ONE sub-task per entity within the layer
+3. Add build/test gate tasks after each layer
+4. Set dependencies via `addBlockedBy` to enforce layer ordering
+
+### Metadata Schema
+
+> **All APEX tasks use this metadata schema for context recovery after compression:**
+
+```typescript
+// Schema for ALL APEX tasks
+{
+  layer?: number,           // 0-4, absent for meta/examine/finding tasks
+  apex_step?: string,       // "02-plan", "03-execute", etc (meta task only)
+  entities?: string[],      // entities concerned
+  tools?: string[],         // MCP tools/skills used
+  build_gate?: "pending" | "pass" | "fail",
+  files_created?: string[], // updated via TaskUpdate after creation
+  module?: string,          // module code (meta task only)
+  app?: string,             // app name (meta task only)
+  flags?: object            // APEX flags (meta task only)
+}
+```
+
+### Task Template
+
+```
+# APEX Progress Tracker (recovery anchor)
+TaskCreate(subject: "APEX Progress",
+  description: "Module: {module_code}, App: {app_name}, Entities: {entities list}. Current: step-02 (Plan)",
+  activeForm: "Planning execution",
+  metadata: {
+    apex_step: "02-plan",
+    module: "{module_code}",
+    app: "{app_name}",
+    entities: ["{entity1}", "{entity2}"],
+    flags: { auto: {auto_mode}, economy: {economy_mode}, examine: {examine_mode} }
+  })
+
+# Layer 0 — Domain + Infrastructure
+TaskCreate(subject: "Layer 0: Domain + Infrastructure",
+  description: "Entities: {entity1} ({tenantMode}), {entity2} ({tenantMode}).
+Files: Domain/Entities/*.cs, Infrastructure/Persistence/Configs/*.cs, Migration.
+Tools: MCP scaffold_extension (type: entity, configuration). MCP suggest_migration.
+Gate: dotnet build --no-restore. ACs: {relevant ACs}.",
+  activeForm: "Creating domain entities",
+  metadata: { layer: 0, entities: [...], tools: ["scaffold_extension", "suggest_migration"], build_gate: "pending", files_created: [] })
+
+# Layer 1 — Seed Data
+TaskCreate(subject: "Layer 1: Seed Data",
+  description: "Navigation, permissions, roles, provider for {module_code}.
+Files: Seeding/Data/{Module}/*.cs, {App}SeedDataProvider.cs.
+Tools: MCP generate_permissions. Ref: core-seed-data.md.
+Gate: dotnet build. ACs: {relevant ACs}.",
+  activeForm: "Generating seed data",
+  metadata: { layer: 1, entities: [...], tools: ["generate_permissions"], build_gate: "pending", files_created: [] })
+TaskUpdate(taskId: layer1_id, addBlockedBy: [layer0_id])
+
+# Layer 2 — Backend (1 task per entity if multi-entity, 1 task if single)
+IF multi-entity:
+  FOR EACH entity:
+    TaskCreate(subject: "Layer 2: {Entity} backend",
+      description: "Service + DTO + Controller + Validator for {Entity}.
+Files: Application/Services/{Entity}Service.cs, Application/DTOs/{Entity}*.cs, Api/Controllers/{Entity}Controller.cs.
+Tools: MCP scaffold_extension, /controller skill. Gate: dotnet build.
+ACs: {relevant ACs for this entity}.",
+      activeForm: "Building {Entity} backend",
+      metadata: { layer: 2, entities: ["{Entity}"], tools: ["scaffold_extension", "controller"], build_gate: "pending", files_created: [] })
+    TaskUpdate(taskId: entity_task_id, addBlockedBy: [layer1_id])
+
+# Layer 2 Tests
+TaskCreate(subject: "Layer 2: Backend tests",
+  description: "Unit + integration tests for all entities.
+Tools: MCP scaffold_tests (unit + integration). Gate: dotnet test.",
+  activeForm: "Running backend tests",
+  metadata: { layer: 2, tools: ["scaffold_tests"], build_gate: "pending" })
+
+# Layer 3 — Frontend (1 task per entity if multi-entity)
+IF multi-entity:
+  FOR EACH entity:
+    TaskCreate(subject: "Layer 3: {Entity} frontend",
+      description: "API client, pages (List/Detail/Create/Edit), i18n (4 langs), routes for {Entity}.
+Files: src/pages/{App}/{Module}/{Entity}*.tsx, src/i18n/locales/*/{module}.json.
+Tools: MCP scaffold_api_client, MCP scaffold_routes, /ui-components skill.
+Gate: npm run typecheck + 5 compliance gates. ACs: {relevant ACs}.",
+      activeForm: "Building {Entity} frontend",
+      metadata: { layer: 3, entities: ["{Entity}"], tools: ["scaffold_api_client", "scaffold_routes", "ui-components"], build_gate: "pending", files_created: [] })
+    TaskUpdate(taskId: entity_task_id, addBlockedBy: [layer2_tests_id])
+
+# Layer 3 Tests + Compliance
+TaskCreate(subject: "Layer 3: Frontend tests + compliance",
+  description: "Form tests (Create/Edit .test.tsx), typecheck, 5 compliance gates.
+Tools: Vitest + React Testing Library. Gate: npm run test + typecheck.",
+  activeForm: "Running frontend tests",
+  metadata: { layer: 3, tools: ["vitest"], build_gate: "pending" })
+
+# Layer 4 (if applicable)
+IF NOT foundation_mode AND devdata needed:
+  TaskCreate(subject: "Layer 4: DevData",
+    description: "Development test data seeder.
+Files: Infrastructure/Persistence/Seeding/DevData/{Module}DevDataSeeder.cs.
+Gate: dotnet build.",
+    activeForm: "Creating dev data",
+    metadata: { layer: 4, tools: [], build_gate: "pending", files_created: [] })
+
+# Post-execution
+TaskCreate(subject: "eXamine: Validation + POST-CHECKs",
+  description: "MCP validate_conventions, build, 50 POST-CHECKs, acceptance criteria.
+Tools: MCP validate_conventions, validate_security, validate_frontend_routes.",
+  activeForm: "Validating conventions",
+  metadata: { tools: ["validate_conventions", "validate_security", "validate_frontend_routes"] })
+```
+
+### Economy Mode
+
+IF economy_mode: Create the SAME tasks (for visibility), but no Agent Teams — agent principal executes sequentially.
+
+### Delegate Mode
+
+IF delegate_mode: Create tasks from PRD task list, mapped to layers.
+
+---
+
 ## NEXT STEP
 
 Load `steps/step-03-execute.md`

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

@@ -47,6 +47,12 @@ Execute ALL layers normally (Layer 0 → Layer 1 → Layer 2 → Layer 3 → Lay
 
 ## Layer 0 — Domain + Infrastructure (sequential, agent principal)
 
+### Task Progress
+TaskUpdate(taskId: layer0_task_id, status: "in_progress")
+TaskUpdate(taskId: progress_tracker_id,
+  description: "Module: {module_code}. Current: step-03 (Execute), Layer 0",
+  activeForm: "Executing Layer 0")
+
 ### Domain Entities
 
 ```
@@ -108,6 +114,9 @@ dotnet build
 
 **MUST PASS before Layer 1. If NuGet error, run `dotnet restore` first. If file lock (MSB3021), use `--output /tmp/{project}_build`.**
 
+TaskUpdate(taskId: layer0_task_id, status: "completed",
+  metadata: { build_gate: "pass" })
+
 ### Layer 0 Commit
 
 ```
@@ -118,6 +127,12 @@ feat({module}): [domain+infra] {short description}
 
 ## Layer 1 — Seed Data (DEDICATED LAYER — sequential, agent principal)
 
+### Task Progress
+TaskUpdate(taskId: layer1_task_id, status: "in_progress")
+TaskUpdate(taskId: progress_tracker_id,
+  description: "Module: {module_code}. Current: step-03 (Execute), Layer 1",
+  activeForm: "Executing Layer 1")
+
 > **This layer is DEDICATED and MANDATORY.** Seed data makes modules visible in the UI.
 > Without seed data, the module exists in code but is invisible to users.
 > Reference: `references/core-seed-data.md` (loaded above) for complete C# templates.
@@ -181,6 +196,9 @@ dotnet build
 
 **MUST PASS before Layer 2.**
 
+TaskUpdate(taskId: layer1_task_id, status: "completed",
+  metadata: { build_gate: "pass" })
+
 ### Layer 1 Commit
 
 ```
@@ -191,6 +209,12 @@ feat({module}): [seed] navigation, permissions, roles
 
 ## Layer 2 — Backend (Services + Controllers)
 
+### Task Progress
+TaskUpdate(taskId: layer2_task_id, status: "in_progress")
+TaskUpdate(taskId: progress_tracker_id,
+  description: "Module: {module_code}. Current: step-03 (Execute), Layer 2",
+  activeForm: "Executing Layer 2")
+
 > **Layer 2 rules** are in `references/smartstack-layers.md` (already in context from step-02):
 > - NavRoute and permission kebab-case (Layer 2 - API section)
 > - Controller route attributes (FORBIDDEN: [Route] alongside [NavRoute])
@@ -238,6 +262,18 @@ Wait for all teammates to report completion.
 shutdown_request → shutdown_response → TeamDelete("apex-layer2")
 ```
 
+### Agent Teams + TaskCreate Integration
+
+When spawning teammates for multi-entity layers:
+- Each teammate receives its task ID and metadata context in the prompt
+- Teammate MUST call TaskUpdate(status: "in_progress") before starting
+- Teammate MUST call TaskUpdate(status: "completed", metadata: { files_created: [...] }) after SendMessage("ENTITY_COMPLETE")
+- Lead monitors via TaskList() between teammate completions
+- Lead updates activeForm after each entity completion:
+  `TaskUpdate(taskId: layer2_task_id, activeForm: "Building {EntityName} backend (2/5 entities)")`
+- Lead updates metadata after each MCP scaffold:
+  `TaskUpdate(taskId: layer_task_id, metadata: { files_created: [...previous, "new_file.cs"] })`
+
 ### Post-Layer 2 Build Gate
 
 ```bash
@@ -246,6 +282,11 @@ dotnet build
 
 **MUST PASS before backend tests.**
 
+TaskUpdate(taskId: layer2_task_id, status: "completed",
+  metadata: { build_gate: "pass" })
+TaskUpdate(taskId: progress_tracker_id,
+  activeForm: "Running build gate (Layer 2)")
+
 ### Backend Tests Inline
 
 > **Tests are scaffolded and run WITHIN Layer 2, not deferred to step-07.**
@@ -282,6 +323,12 @@ test({module}): backend unit and integration tests
 
 ## Layer 3 — Frontend (Pages + I18n + Documentation)
 
+### Task Progress
+TaskUpdate(taskId: layer3_task_id, status: "in_progress")
+TaskUpdate(taskId: progress_tracker_id,
+  description: "Module: {module_code}. Current: step-03 (Execute), Layer 3",
+  activeForm: "Executing Layer 3")
+
 > **Frontend patterns** are in `references/smartstack-frontend.md` (already loaded above):
 > - API client generation (MCP scaffold_api_client)
 > - Route scaffolding (MCP scaffold_routes) — section 1 + 3b
@@ -399,6 +446,18 @@ Wait for all teammates to report completion.
 shutdown_request → shutdown_response → TeamDelete("apex-layer3")
 ```
 
+### Agent Teams + TaskCreate Integration
+
+When spawning teammates for multi-entity layers:
+- Each teammate receives its task ID and metadata context in the prompt
+- Teammate MUST call TaskUpdate(status: "in_progress") before starting
+- Teammate MUST call TaskUpdate(status: "completed", metadata: { files_created: [...] }) after SendMessage("ENTITY_COMPLETE")
+- Lead monitors via TaskList() between teammate completions
+- Lead updates activeForm after each entity completion:
+  `TaskUpdate(taskId: layer3_task_id, activeForm: "Building {EntityName} frontend (2/5 entities)")`
+- Lead updates metadata after each MCP scaffold:
+  `TaskUpdate(taskId: layer_task_id, metadata: { files_created: [...previous, "NewPage.tsx"] })`
+
 ### FRONTEND COMPLIANCE GATE (MANDATORY before commit)
 
 > **Reference:** See `references/smartstack-frontend.md` section 9 "Compliance Gates" for all 5 mandatory checks:
@@ -453,6 +512,9 @@ npm run typecheck
 
 **MUST PASS before commit.**
 
+TaskUpdate(taskId: layer3_task_id, status: "completed",
+  metadata: { build_gate: "pass" })
+
 ### Layer 3 Commits
 
 ```
@@ -464,6 +526,12 @@ test({module}): frontend form tests
 
 ## Layer 4 — DevData (optional)
 
+### Task Progress
+IF layer4 task exists: TaskUpdate(taskId: layer4_task_id, status: "in_progress")
+IF layer4 task exists: TaskUpdate(taskId: progress_tracker_id,
+  description: "Module: {module_code}. Current: step-03 (Execute), Layer 4",
+  activeForm: "Executing Layer 4")
+
 > **Business test data for development/demo environments.**
 > Skip this layer if no meaningful test data is needed.
 
@@ -477,6 +545,9 @@ test({module}): frontend form tests
    dotnet build → MUST PASS
 ```
 
+IF layer4 task exists: TaskUpdate(taskId: layer4_task_id, status: "completed",
+  metadata: { build_gate: "pass" })
+
 ### Layer 4 Commit (if applicable)
 
 ```

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

@@ -14,6 +14,22 @@ next_step: steps/step-05-deep-review.md
 
 ---
 
+## 0. Task Progress
+
+### Progress Tracker Update
+```
+TaskUpdate(taskId: progress_tracker_id,
+  description: "Module: {module_code}. Current: step-04 (eXamine)",
+  activeForm: "Validating conventions")
+```
+
+### eXamine Task Lifecycle
+```
+TaskUpdate(taskId: examine_task_id, status: "in_progress")
+```
+
+---
+
 ## 1. MCP Convention Validation
 
 ```
@@ -284,6 +300,11 @@ ELSE:
 **BLOCKING RULE:** The APEX workflow is NOT complete until steps 07-08 execute.
 The success criteria require: "Tests: 100% pass, >= 80% coverage" — step-07 verifies coverage and adds security tests.
 
+### eXamine Task Lifecycle — Completion
+```
+TaskUpdate(taskId: examine_task_id, status: "completed")
+```
+
 **NEXT ACTION:** Load `steps/step-07-tests.md` now.
 
 ---

package/templates/skills/apex/steps/step-05-deep-review.md

@@ -12,6 +12,17 @@ next_step: steps/step-06-resolve.md
 
 ---
 
+## 0. Task Progress
+
+### Progress Tracker Update
+```
+TaskUpdate(taskId: progress_tracker_id,
+  description: "Module: {module_code}. Current: step-05 (Deep Review)",
+  activeForm: "Reviewing code")
+```
+
+---
+
 ## 1. Gather Changed Files
 
 ```bash

package/templates/skills/apex/steps/step-06-resolve.md

@@ -12,15 +12,34 @@ next_step: steps/step-07-tests.md
 
 ---
 
-## 1. Process BLOCKING Findings
+## 0. Task Progress
+
+### Progress Tracker Update
+```
+TaskUpdate(taskId: progress_tracker_id,
+  description: "Module: {module_code}. Current: step-06 (Resolve)",
+  activeForm: "Fixing findings")
+```
+
+---
+
+## 1. Create Finding Tasks
 
 For each BLOCKING finding from step-05:
 
 ```
-Finding: {F01, F02, ...}
-File: {path}
-Issue: {description}
-Fix approach: {use appropriate skill/MCP tool}
+TaskCreate(subject: "Fix: {F01} — {short description}",
+  description: "File: {path}:{line}\nIssue: {description}\nFix: {approach}",
+  activeForm: "Fixing {F01}",
+  metadata: { finding_id: "F01", severity: "BLOCKING", source_file: "{path}" })
+```
+
+Then process each finding by updating task status:
+
+```
+TaskUpdate(taskId: finding_task_id, status: "in_progress")
+... apply fix ...
+TaskUpdate(taskId: finding_task_id, status: "completed")
 ```
 
 **Fixing rules:**

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

@@ -16,6 +16,17 @@ next_step: steps/step-08-run-tests.md
 
 ---
 
+## Task Progress
+
+### Progress Tracker Update
+```
+TaskUpdate(taskId: progress_tracker_id,
+  description: "Module: {module_code}. Current: step-07 (Final Test Sweep)",
+  activeForm: "Running test sweep")
+```
+
+---
+
 ## 0. Ensure Test Infrastructure Exists
 
 ### 0a. Frontend Test Tooling (if frontend was generated)

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

@@ -24,6 +24,23 @@ const {EntityName}Page = lazy(() => import('@/pages/{Application}/{Module}/{Enti
 
 ---
 
+## Step 4a.5: Import Generated Route Extensions (if scaffold_routes was used)
+
+If `scaffold_routes` generated `applicationRoutes.generated.tsx`, import and spread:
+
+```tsx
+import { applicationRouteExtensions } from '@/routes/applicationRoutes.generated';
+
+const applicationRoutes: ApplicationRouteExtensions = {
+  ...applicationRouteExtensions,
+  // additional manual routes if needed...
+};
+```
+
+If no generated file exists, add routes directly to the existing `applicationRoutes` object.
+
+---
+
 ## Step 4b: Detect App.tsx Routing Pattern
 
 Read App.tsx and detect which pattern is used:
@@ -38,10 +55,14 @@ Read App.tsx and detect which pattern is used:
 const applicationRoutes: ApplicationRouteExtensions = {
   'human-resources': [
     // existing routes...
-    { path: '{module_kebab}', element: <{EntityName}ListPage /> },
-    { path: '{module_kebab}/new', element: <Create{EntityName}Page /> },
-    { path: '{module_kebab}/:id', element: <{EntityName}DetailPage /> },
-    { path: '{module_kebab}/:id/edit', element: <Create{EntityName}Page /> },
+    { path: '{module_kebab}/{section_kebab}', element: <{EntityName}ListPage /> },
+    { path: '{module_kebab}/{section_kebab}/new', element: <Create{EntityName}Page /> },
+    { path: '{module_kebab}/{section_kebab}/:id', element: <{EntityName}DetailPage /> },
+    { path: '{module_kebab}/{section_kebab}/:id/edit', element: <Create{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 /> },
   ],
 };
 ```
@@ -77,6 +98,27 @@ Find `<Route path="/t/:slug">` and add the **same route entries** there.
 
 ---
 
+## Step 4b.5: Verify mergeRoutes() Call (BLOCKING)
+
+**BEFORE modifying routes, READ App.tsx and verify the `mergeRoutes()` call has 2 parameters.**
+
+✅ Correct:
+```tsx
+const routes = mergeRoutes(clientRoutes, applicationRoutes);
+```
+
+❌ If you see only 1 parameter:
+```tsx
+const routes = mergeRoutes(clientRoutes);
+```
+
+→ Add the `applicationRoutes` object and pass it as 2nd parameter.
+Without it, ALL application routes are silently ignored → blank page or /login redirect.
+
+**NEVER remove the `applicationRoutes` parameter or the `ApplicationRouteExtensions` import.**
+
+---
+
 ## Step 4c: Application-to-Layout Mapping
 
 | Application prefix | Layout Component | Route path |
@@ -99,11 +141,56 @@ If `appWiring.issues` is not empty, fix the wiring before proceeding.
 
 ---
 
+## Step 4e: Parent Redirect Routes (MANDATORY)
+
+**CRITICAL:** Without parent redirects, navigating to an application or module URL (e.g., `/human-resources` or `/human-resources/employees`) will cause a redirect to `/login` because no route matches.
+
+For each application, you MUST add:
+
+1. **Application root redirect** — redirects `/{application}` to the first module/section:
+   ```tsx
+   { path: '', element: <Navigate to="{first_module}/{first_section}" replace /> }
+   ```
+
+2. **Module redirect** (if modules have sections) — redirects `/{application}/{module}` to first section:
+   ```tsx
+   { path: '{module}', element: <Navigate to="{module}/{first_section}" replace /> }
+   ```
+
+**Example:** For NavRoutes `human-resources.employees.management` and `human-resources.employees.departments`:
+```tsx
+{ path: 'employees', element: <Navigate to="employees/management" replace /> },
+{ path: '', element: <Navigate to="employees/management" replace /> },
+```
+
+The `to` prop is resolved relative to the **parent route** (`/{application}`), so always use the full path from the application root.
+
+> Note: `scaffold_routes` with `outputFormat: "applicationRoutes"` generates these redirects automatically.
+
+---
+
 ## Forbidden Patterns (BOTH patterns)
 
 - Adding application routes to `clientRoutes[]` with absolute paths — `clientRoutes` is ONLY for routes outside SmartStack applications (e.g., `/about`, `/pricing`)
 - Adding routes OUTSIDE the Layout wrapper (shell will not render)
 - Using `createBrowserRouter` (SmartStack uses `useRoutes()` + `mergeRoutes()`)
+- Adding custom application routes to `clientRoutes[]` with absolute paths:
+  ```tsx
+  // ❌ WRONG — bypasses RouteGuard + TenantLayout + AppLayout → /login redirect
+  const clientRoutes: RouteConfig[] = [
+    { path: '/human-resources/employees/management', element: <EmployeePage /> },
+  ];
+  ```
+  Custom application routes MUST go in `applicationRoutes` with RELATIVE paths:
+  ```tsx
+  // ✅ CORRECT
+  const applicationRoutes: ApplicationRouteExtensions = {
+    'human-resources': [
+      { path: 'employees/management', element: <EmployeePage /> },
+    ],
+  };
+  ```
+- Removing the `applicationRoutes` 2nd parameter from `mergeRoutes()` — this silently breaks ALL custom routes
 
 ---