@atlashub/smartstack-cli 4.13.0 → 4.14.0

package/package.json

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

@@ -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/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:
@@ -77,6 +94,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 |
@@ -104,6 +142,23 @@ If `appWiring.issues` is not empty, fix the wiring before proceeding.
 - 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/application/steps/step-05-frontend.md

@@ -113,11 +113,13 @@ This generates:
 ### 4. Wire Routes to App.tsx (BLOCKING)
 
 See [references/frontend-route-wiring-app-tsx.md](../references/frontend-route-wiring-app-tsx.md) for:
-- Step 4a: Import page components
+- Step 4a: Import page components (lazy)
+- Step 4a.5: Import generated route extensions (if scaffold_routes was used)
 - Step 4b: Detect App.tsx routing pattern (Pattern A vs Pattern B)
+- Step 4b.5: Verify mergeRoutes() has 2 parameters (BLOCKING)
 - Step 4c: Application-to-Layout mapping table
 - Step 4d: Route wiring verification
-- Forbidden patterns (absolute paths, outside Layout, createBrowserRouter)
+- Forbidden patterns (absolute paths in clientRoutes, outside Layout, missing 2nd param)
 
 ### 5-6. Verify i18n & Present Output