@atlashub/smartstack-cli 4.14.0 → 4.16.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@atlashub/smartstack-cli",
-  "version": "4.14.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/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

@@ -55,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 /> },
   ],
 };
 ```
@@ -137,6 +141,34 @@ 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`)

package/templates/skills/application/references/nav-fallback-procedure.md

@@ -53,13 +53,15 @@ Read the parent SeedData class and find the GUID matching `{parent_path}`.
 Generate a random GUID for the new navigation entity:
 
 ```csharp
-// ALWAYS use Guid.NewGuid() — avoids conflicts between projects/tenants/environments
-var guid = Guid.NewGuid();
+// IMPORTANT: Use a stable GUID. Never change after the first seed.
+// Generate once with Guid.NewGuid(), then hardcode the result as a static field.
+public static readonly Guid MyEntityId = Guid.Parse("xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx");
 ```
 
 **Rules:**
-- ALWAYS use `Guid.NewGuid()` — no deterministic, no sequential, no fixed values
-- Idempotence is handled by Code-based lookups, not by fixed IDs
+- Generate a GUID once with `Guid.NewGuid()`, then **hardcode it as a static readonly field**
+- NEVER call `Guid.NewGuid()` at runtime in seed data — each migration run would generate different IDs, breaking foreign keys
+- Idempotence is handled by EF Core HasData matching on the `Id` primary key
 - Store result as `{navigation_guid}`
 
 ## F4. Write Navigation Entity Seed

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

@@ -20,9 +20,15 @@ Gather all context needed to generate the controller. Find the Entity, check DbC
 
 **Search for entity file:**
 
+1. Read `.smartstack/config.json` → use `paths.domain` if available
+2. Otherwise, use wildcard on project name:
 ```
-Glob: "src/SmartStack.Domain/**/{entity}.cs"
-Glob: "src/SmartStack.Domain/**/{entity}s.cs"
+Glob: "src/*Domain*/**/{entity}.cs"
+Glob: "src/*Domain*/**/{entity}s.cs"
+```
+3. Fallback (if no match):
+```
+Glob: "src/**/{entity}.cs" with ignore "**/obj/**,**/bin/**,**/Tests/**"
 ```
 
 **Extract from Entity:**

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

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