@atlashub/smartstack-cli 3.46.0 → 3.48.0

package/dist/mcp-entry.mjs

@@ -25919,7 +25919,9 @@ var init_types3 = __esm({
         navRoute: external_exports.string().optional().describe('Navigation route path for controller (e.g., "administration.users"). Required for controllers.'),
         navRouteSuffix: external_exports.string().optional().describe('Optional suffix for NavRoute (e.g., "dashboard" for sub-resources)'),
         withHierarchyFunction: external_exports.boolean().optional().describe("For entity type with self-reference (ParentId): generate TVF SQL script for hierarchy traversal"),
-        hierarchyDirection: external_exports.enum(["ancestors", "descendants", "both"]).optional().describe("Direction for hierarchy traversal function (default: both)")
+        hierarchyDirection: external_exports.enum(["ancestors", "descendants", "both"]).optional().describe("Direction for hierarchy traversal function (default: both)"),
+        isPersonRole: external_exports.boolean().optional().describe("If true, entity is a Person Extension linked to User via UserId FK"),
+        userLinkMode: external_exports.enum(["mandatory", "optional"]).optional().describe("Person Extension mode: mandatory (always a User) or optional (may or may not have a User)")
       }).optional()
     });
     ApiDocsInputSchema = external_exports.object({
@@ -27012,6 +27014,25 @@ async function validateEntities(structure, _config, result) {
         suggestion: `Add factory method: public static ${entityName} Create(...)`
       });
     }
+    const hasUserId = content.includes("UserId") && content.includes("private set");
+    const hasUserNavProp = /public\s+User\?\s+User\s*{/.test(content);
+    if (hasUserId && hasUserNavProp && hasAnyTenantInterface) {
+      const personFields = ["FirstName", "LastName", "Email", "PhoneNumber"];
+      const duplicatedFields = personFields.filter((field) => {
+        const propPattern = new RegExp(`public\\s+string[?]?\\s+${field}\\s*{`);
+        return propPattern.test(content);
+      });
+      const hasDisplayProps = content.includes("DisplayFirstName") || content.includes("DisplayLastName");
+      if (duplicatedFields.length >= 2 && !hasDisplayProps) {
+        result.warnings.push({
+          type: "warning",
+          category: "entities",
+          message: `Entity "${entityName}" has UserId (Person Extension) but also declares person fields (${duplicatedFields.join(", ")}) \u2014 these may duplicate User data`,
+          file: path8.relative(structure.root, file),
+          suggestion: "For mandatory Person Extension: remove person fields and read them from User. For optional: add Display* computed properties (DisplayFirstName => User?.FirstName ?? FirstName)"
+        });
+      }
+    }
   }
 }
 async function validateTenantAwareness(structure, _config, result) {
@@ -34771,6 +34792,10 @@ namespace {{implNamespace}};
 /// Scoped entity: EF global query filter includes shared + current tenant data. Scope controls visibility.
 {{/if}}
 /// IMPORTANT: GetAllAsync MUST support search parameter for frontend EntityLookup component.
+{{#if isPersonRole}}
+/// IMPORTANT: Person Extension \u2014 always include User for person data resolution.
+/// All queries must .Include(x => x.User).
+{{/if}}
 /// </summary>
 public class {{name}}Service : I{{name}}Service
 {
@@ -34833,7 +34858,8 @@ public class {{name}}Service : I{{name}}Service
   const diTemplate = `// Add to DependencyInjection.cs or ServiceCollectionExtensions.cs:
 services.AddScoped<I{{name}}Service, {{name}}Service>();
 `;
-  const context = { interfaceNamespace, implNamespace, name, methods, ...tmFlags };
+  const isPersonRole = options?.isPersonRole || false;
+  const context = { interfaceNamespace, implNamespace, name, methods, ...tmFlags, isPersonRole };
   const interfaceContent = import_handlebars.default.compile(interfaceTemplate)(context);
   const implementationContent = import_handlebars.default.compile(implementationTemplate)(context);
   const diContent = import_handlebars.default.compile(diTemplate)(context);
@@ -34866,6 +34892,8 @@ async function scaffoldEntity(name, options, structure, config2, result, dryRun
   const isSystemEntity = tmFlags.isSystemEntity;
   const tablePrefix = options?.tablePrefix || "ref_";
   const schema = options?.schema || config2.conventions.schemas.platform;
+  const isPersonRole = options?.isPersonRole || false;
+  const userLinkMode = options?.userLinkMode || "mandatory";
   const entityTemplate = `using System;
 using SmartStack.Domain.Common;
 
@@ -34937,6 +34965,38 @@ public class {{name}} : BaseEntity, IAuditableEntity
     /// </summary>
     public {{baseEntity}}? {{baseEntity}} { get; private set; }
 
+{{/if}}
+{{#if isPersonRoleMandatory}}
+    // === USER LINK (Person Extension \u2014 mandatory) ===
+
+    /// <summary>
+    /// Link to the User entity. This person is ALWAYS a system user.
+    /// Person data (FirstName, LastName, Email) comes from User \u2014 never duplicated here.
+    /// </summary>
+    public Guid UserId { get; private set; }
+    public User? User { get; private set; }
+
+{{else if isPersonRoleOptional}}
+    // === USER LINK (Person Extension \u2014 optional) ===
+
+    /// <summary>
+    /// Optional link to a User entity. This person MAY have a system account.
+    /// When linked, person data comes from User (via Display* properties).
+    /// </summary>
+    public Guid? UserId { get; private set; }
+    public User? User { get; private set; }
+
+    // === PERSON FIELDS (standalone when no User linked) ===
+    public string FirstName { get; private set; } = null!;
+    public string LastName { get; private set; } = null!;
+    public string? Email { get; private set; }
+    public string? PhoneNumber { get; private set; }
+
+    // === COMPUTED (read from User if linked, else from own fields) ===
+    public string DisplayFirstName => User?.FirstName ?? FirstName;
+    public string DisplayLastName => User?.LastName ?? LastName;
+    public string? DisplayEmail => User?.Email ?? Email;
+
 {{/if}}
     // === BUSINESS PROPERTIES ===
     // TODO: Add {{name}} specific properties here
@@ -35073,6 +35133,35 @@ public class {{name}}Configuration : IEntityTypeConfiguration<{{name}}>
                .HasDatabaseName("IX_{{tablePrefix}}{{name}}s_{{baseEntity}}Id");
 {{/if}}
 
+{{#if isPersonRoleMandatory}}
+
+        // === PERSON EXTENSION (mandatory) \u2014 User link ===
+        builder.HasOne(e => e.User)
+            .WithMany()
+            .HasForeignKey(e => e.UserId)
+            .OnDelete(DeleteBehavior.Restrict);
+
+        builder.HasIndex(e => new { e.TenantId, e.UserId })
+            .IsUnique();
+{{else if isPersonRoleOptional}}
+
+        // === PERSON EXTENSION (optional) \u2014 User link ===
+        builder.HasOne(e => e.User)
+            .WithMany()
+            .HasForeignKey(e => e.UserId)
+            .OnDelete(DeleteBehavior.Restrict);
+
+        builder.HasIndex(e => new { e.TenantId, e.UserId })
+            .IsUnique()
+            .HasFilter("[UserId] IS NOT NULL");
+
+        // Person fields
+        builder.Property(e => e.FirstName).HasMaxLength(200);
+        builder.Property(e => e.LastName).HasMaxLength(200);
+        builder.Property(e => e.Email).HasMaxLength(256);
+        builder.Property(e => e.PhoneNumber).HasMaxLength(50);
+{{/if}}
+
         // TODO: Add business property configurations (HasMaxLength, IsRequired, indexes)
     }
 }
@@ -35086,7 +35175,10 @@ public class {{name}}Configuration : IEntityTypeConfiguration<{{name}}>
     schema,
     infrastructureNamespace: config2.conventions.namespaces.infrastructure,
     configNamespaceSuffix: hierarchy.infraPath ? hierarchy.infraPath.replace(/[\\/]/g, ".") : "",
-    domainNamespace: config2.conventions.namespaces.domain
+    domainNamespace: config2.conventions.namespaces.domain,
+    isPersonRoleMandatory: isPersonRole && userLinkMode === "mandatory",
+    isPersonRoleOptional: isPersonRole && userLinkMode === "optional",
+    isPersonRole
   };
   const entityContent = import_handlebars.default.compile(entityTemplate)(context);
   const configContent = import_handlebars.default.compile(configTemplate)(context);
@@ -36617,6 +36709,15 @@ var init_scaffold_extension = __esm({
                 enum: ["ancestors", "descendants", "both"],
                 description: "Direction for hierarchy traversal function (default: both)"
               },
+              isPersonRole: {
+                type: "boolean",
+                description: "If true, entity is a Person Extension linked to User via UserId FK. Mandatory mode: no person fields, UserId required. Optional mode: own person fields + Display* computed properties."
+              },
+              userLinkMode: {
+                type: "string",
+                enum: ["mandatory", "optional"],
+                description: "Person Extension mode: mandatory (UserId non-nullable, no person fields) or optional (UserId nullable, own person fields + Display* computed properties)"
+              },
               codePattern: {
                 type: "object",
                 description: 'Code auto-generation pattern for this entity. When strategy != "manual", Code is auto-generated and removed from CreateDto.',
@@ -57630,7 +57731,8 @@ async function scaffoldRoutes(input, config2) {
       await writeText(clientRoutesFile, clientRoutesContent);
     }
     result.files.push({ path: clientRoutesFile, content: clientRoutesContent, type: "created" });
-    result.instructions.push(`Generated ${navRoutes.length} routes in clientRoutes format`);
+    const routeCount = navRoutes.length * 4;
+    result.instructions.push(`Generated ${routeCount} routes (4 CRUD per NavRoute) for ${navRoutes.length} NavRoutes in clientRoutes format`);
     result.instructions.push("");
     result.instructions.push("## App.tsx Wiring Instructions");
     result.instructions.push("");
@@ -57639,7 +57741,8 @@ async function scaffoldRoutes(input, config2) {
     const routeTree = buildRouteTree(navRoutes);
     result.instructions.push("### Pattern A: mergeRoutes (applicationRoutes pattern)");
     result.instructions.push("");
-    result.instructions.push("Add routes to `applicationRoutes.{application}[]` with **RELATIVE** paths (no leading `/`):");
+    result.instructions.push("Routes are FLAT (no nested children) \u2014 compatible with `mergeRoutes()`.");
+    result.instructions.push("Each NavRoute generates 4 routes: list, create, detail (:id), edit (:id/edit).");
     result.instructions.push("");
     result.instructions.push("**IMPORTANT:** Pages are lazy-loaded. Use `<Suspense fallback={<PageLoader />}>` wrapper.");
     result.instructions.push("");
@@ -57651,21 +57754,23 @@ async function scaffoldRoutes(input, config2) {
     for (const [_app, modules] of Object.entries(routeTree)) {
       for (const [, moduleRoutes] of Object.entries(modules)) {
         for (const route of moduleRoutes) {
-          const pageEntry = pageFiles.get(route.navRoute);
-          if (pageEntry) {
-            for (const entry of pageEntry) {
-              if (!importedComponents.has(entry.componentName)) {
-                importedComponents.add(entry.componentName);
-                result.instructions.push(`const ${entry.componentName} = lazy(() =>`);
-                result.instructions.push(`  import('${entry.importPath}').then(m => ({ default: m.${entry.componentName} }))`);
+          const discovery = pageFiles.get(route.navRoute);
+          if (discovery) {
+            for (const page of [discovery.list, discovery.create, discovery.detail, discovery.edit]) {
+              if (page && !importedComponents.has(page.componentName)) {
+                importedComponents.add(page.componentName);
+                result.instructions.push(`const ${page.componentName} = lazy(() =>`);
+                result.instructions.push(`  import('${page.importPath}').then(m => ({ default: m.${page.componentName} }))`);
                 result.instructions.push(");");
               }
             }
           } else {
-            const component = route.navRoute.split(".").map(capitalize).join("") + "Page";
-            if (!importedComponents.has(component)) {
-              importedComponents.add(component);
-              result.instructions.push(`// TODO: const ${component} = lazy(() => import('@/pages/...'));`);
+            const { entityPlural, entitySingular, basePath } = deriveEntityNames(route.navRoute);
+            for (const comp of [`${entityPlural}Page`, `${entitySingular}CreatePage`, `${entitySingular}DetailPage`, `${entitySingular}EditPage`]) {
+              if (!importedComponents.has(comp)) {
+                importedComponents.add(comp);
+                result.instructions.push(`// TODO: const ${comp} = lazy(() => import('${basePath}/${comp}').then(m => ({ default: m.${comp} })));`);
+              }
             }
           }
         }
@@ -57678,9 +57783,17 @@ async function scaffoldRoutes(input, config2) {
       for (const [, moduleRoutes] of Object.entries(modules)) {
         for (const route of moduleRoutes) {
           const modulePath = route.navRoute.split(".").slice(1).map(toKebabCase).join("/");
-          const pageEntry = pageFiles.get(route.navRoute);
-          const component = pageEntry?.[0]?.componentName || `${route.navRoute.split(".").map(capitalize).join("")}Page`;
-          result.instructions.push(`    { path: '${modulePath}', element: <Suspense fallback={<PageLoader />}><${component} /></Suspense> },`);
+          const discovery = pageFiles.get(route.navRoute);
+          const { entityPlural, entitySingular } = deriveEntityNames(route.navRoute);
+          const listComp = discovery?.list?.componentName || `${entityPlural}Page`;
+          const createComp = discovery?.create?.componentName || `${entitySingular}CreatePage`;
+          const detailComp = discovery?.detail?.componentName || `${entitySingular}DetailPage`;
+          const editComp = discovery?.edit?.componentName || `${entitySingular}EditPage`;
+          result.instructions.push(`    // === ${entityPlural.toLowerCase()} (NavRoute: ${route.navRoute}) ===`);
+          result.instructions.push(`    { path: '${modulePath}', element: <Suspense fallback={<PageLoader />}><${listComp} /></Suspense> },`);
+          result.instructions.push(`    { path: '${modulePath}/create', element: <Suspense fallback={<PageLoader />}><${createComp} /></Suspense> },`);
+          result.instructions.push(`    { path: '${modulePath}/:id', element: <Suspense fallback={<PageLoader />}><${detailComp} /></Suspense> },`);
+          result.instructions.push(`    { path: '${modulePath}/:id/edit', element: <Suspense fallback={<PageLoader />}><${editComp} /></Suspense> },`);
         }
       }
       result.instructions.push("  ],");
@@ -57703,9 +57816,16 @@ async function scaffoldRoutes(input, config2) {
       for (const [, moduleRoutes] of Object.entries(modules)) {
         for (const route of moduleRoutes) {
           const modulePath = route.navRoute.split(".").slice(1).map(toKebabCase).join("/");
-          const pageEntry = pageFiles.get(route.navRoute);
-          const component = pageEntry?.[0]?.componentName || `${route.navRoute.split(".").map(capitalize).join("")}Page`;
-          result.instructions.push(`<Route path="${modulePath}" element={<Suspense fallback={<PageLoader />}><${component} /></Suspense>} />`);
+          const discovery = pageFiles.get(route.navRoute);
+          const { entityPlural, entitySingular } = deriveEntityNames(route.navRoute);
+          const listComp = discovery?.list?.componentName || `${entityPlural}Page`;
+          const createComp = discovery?.create?.componentName || `${entitySingular}CreatePage`;
+          const detailComp = discovery?.detail?.componentName || `${entitySingular}DetailPage`;
+          const editComp = discovery?.edit?.componentName || `${entitySingular}EditPage`;
+          result.instructions.push(`<Route path="${modulePath}" element={<Suspense fallback={<PageLoader />}><${listComp} /></Suspense>} />`);
+          result.instructions.push(`<Route path="${modulePath}/create" element={<Suspense fallback={<PageLoader />}><${createComp} /></Suspense>} />`);
+          result.instructions.push(`<Route path="${modulePath}/:id" element={<Suspense fallback={<PageLoader />}><${detailComp} /></Suspense>} />`);
+          result.instructions.push(`<Route path="${modulePath}/:id/edit" element={<Suspense fallback={<PageLoader />}><${editComp} /></Suspense>} />`);
         }
       }
       result.instructions.push("```");
@@ -57937,6 +58057,7 @@ function generateRouterConfig(routes, includeGuards) {
     " * React Router Configuration",
     " *",
     " * Auto-generated by SmartStack MCP - DO NOT EDIT MANUALLY",
+    " * Each NavRoute generates 4 flat CRUD routes (list, create, detail, edit).",
     " */",
     "",
     "import { createBrowserRouter, RouteObject } from 'react-router-dom';",
@@ -57953,10 +58074,15 @@ function generateRouterConfig(routes, includeGuards) {
     lines.push(`const ${name} = lazy(() => import('../layouts/${name}').then(m => ({ default: m.${name} })));`);
   }
   lines.push("");
-  lines.push("// Page imports - lazy loaded (customize paths)");
+  lines.push("// Page imports - lazy loaded");
+  lines.push("// Uncomment and adjust import paths for your page components:");
   for (const route of routes) {
-    const pageName = route.navRoute.split(".").map(capitalize).join("");
-    lines.push(`// const ${pageName}Page = lazy(() => import('../pages/${pageName}Page').then(m => ({ default: m.${pageName}Page })));`);
+    const { entityPlural, entitySingular, basePath } = deriveEntityNames(route.navRoute);
+    const pagesBasePath = basePath.replace("@/pages/", "../pages/");
+    lines.push(`// const ${entityPlural}Page = lazy(() => import('${pagesBasePath}/${entityPlural}Page').then(m => ({ default: m.${entityPlural}Page })));`);
+    lines.push(`// const ${entitySingular}CreatePage = lazy(() => import('${pagesBasePath}/${entitySingular}CreatePage').then(m => ({ default: m.${entitySingular}CreatePage })));`);
+    lines.push(`// const ${entitySingular}DetailPage = lazy(() => import('${pagesBasePath}/${entitySingular}DetailPage').then(m => ({ default: m.${entitySingular}DetailPage })));`);
+    lines.push(`// const ${entitySingular}EditPage = lazy(() => import('${pagesBasePath}/${entitySingular}EditPage').then(m => ({ default: m.${entitySingular}EditPage })));`);
   }
   lines.push("");
   lines.push("const routes: RouteObject[] = [");
@@ -57968,23 +58094,14 @@ function generateRouterConfig(routes, includeGuards) {
     for (const [, moduleRoutes] of Object.entries(modules)) {
       for (const route of moduleRoutes) {
         const modulePath = route.navRoute.split(".").slice(1).map(toKebabCase).join("/");
-        const pageName = route.navRoute.split(".").map(capitalize).join("");
-        if (includeGuards && route.permissions.length > 0) {
-          lines.push("      {");
-          lines.push(`        path: '${modulePath || ""}',`);
-          lines.push(`        element: (`);
-          lines.push(`          <PermissionGuard permissions={ROUTES['${route.navRoute}'].permissions}>`);
-          lines.push(`            {/* <${pageName}Page /> */}`);
-          lines.push(`            <div>TODO: ${pageName}Page</div>`);
-          lines.push(`          </PermissionGuard>`);
-          lines.push(`        ),`);
-          lines.push("      },");
-        } else {
-          lines.push("      {");
-          lines.push(`        path: '${modulePath || ""}',`);
-          lines.push(`        element: <div>TODO: ${pageName}Page</div>,`);
-          lines.push("      },");
-        }
+        const { entityPlural, entitySingular } = deriveEntityNames(route.navRoute);
+        const permGuardOpen = includeGuards && route.permissions.length > 0 ? `<PermissionGuard permissions={ROUTES['${route.navRoute}'].permissions}>` : "";
+        const permGuardClose = permGuardOpen ? "</PermissionGuard>" : "";
+        lines.push(`      // === ${entityPlural.toLowerCase()} (NavRoute: ${route.navRoute}) ===`);
+        lines.push(`      // TODO: { path: '${modulePath}', element: <Suspense fallback={<PageLoader />}>${permGuardOpen}<${entityPlural}Page />${permGuardClose}</Suspense> },`);
+        lines.push(`      // TODO: { path: '${modulePath}/create', element: <Suspense fallback={<PageLoader />}>${permGuardOpen}<${entitySingular}CreatePage />${permGuardClose}</Suspense> },`);
+        lines.push(`      // TODO: { path: '${modulePath}/:id', element: <Suspense fallback={<PageLoader />}>${permGuardOpen}<${entitySingular}DetailPage />${permGuardClose}</Suspense> },`);
+        lines.push(`      // TODO: { path: '${modulePath}/:id/edit', element: <Suspense fallback={<PageLoader />}>${permGuardOpen}<${entitySingular}EditPage />${permGuardClose}</Suspense> },`);
       }
     }
     lines.push("    ],");
@@ -58154,14 +58271,24 @@ async function discoverPageFiles(webPath, routes) {
     const moduleDir = moduleParts.join("/");
     const pagesDir = path19.join(webPath, "src", "pages", app, moduleDir || "");
     try {
-      const pageFiles = await glob("*Page.tsx", { cwd: pagesDir, absolute: false });
-      if (pageFiles.length > 0) {
-        const entries = pageFiles.map((f) => {
+      const files = await glob("*Page.tsx", { cwd: pagesDir, absolute: false });
+      if (files.length > 0) {
+        const discovery = {};
+        for (const f of files) {
           const componentName = f.replace(".tsx", "");
           const importPath = `@/pages/${app}/${moduleDir ? moduleDir + "/" : ""}${componentName}`;
-          return { importPath, componentName };
-        });
-        pageMap.set(route.navRoute, entries);
+          const entry = { importPath, componentName };
+          if (componentName.endsWith("CreatePage")) {
+            discovery.create = entry;
+          } else if (componentName.endsWith("EditPage")) {
+            discovery.edit = entry;
+          } else if (componentName.endsWith("DetailPage")) {
+            discovery.detail = entry;
+          } else {
+            discovery.list = entry;
+          }
+        }
+        pageMap.set(route.navRoute, discovery);
       }
     } catch {
       logger.debug(`No pages found for route ${route.navRoute} at ${pagesDir}`);
@@ -58178,9 +58305,8 @@ function generateClientRoutesConfig(routes, pageFiles, includeGuards) {
     " * Auto-generated by SmartStack MCP - DO NOT EDIT MANUALLY",
     ' * Run `scaffold_routes` with outputFormat: "clientRoutes" to regenerate.',
     " *",
-    " * These routes must be added INSIDE the appropriate Layout wrapper in App.tsx.",
-    " * They are NOT standalone - they are children of the application layout routes.",
-    " * Routes must be added in BOTH the standard block and the tenant-prefixed block.",
+    " * These routes are FLAT (not nested children) \u2014 compatible with mergeRoutes().",
+    " * Each NavRoute generates up to 4 CRUD routes: list, create, detail, edit.",
     " */",
     "",
     "import type { RouteObject } from 'react-router-dom';",
@@ -58196,22 +58322,32 @@ function generateClientRoutesConfig(routes, pageFiles, includeGuards) {
   lines.push("");
   const importedComponents = /* @__PURE__ */ new Set();
   for (const route of routes) {
-    const pageEntries = pageFiles.get(route.navRoute);
-    if (pageEntries) {
-      for (const entry of pageEntries) {
-        if (!importedComponents.has(entry.componentName)) {
-          lines.push(`const ${entry.componentName} = lazy(() =>`);
-          lines.push(`  import('${entry.importPath}').then(m => ({ default: m.${entry.componentName} }))`);
+    const discovery = pageFiles.get(route.navRoute);
+    if (discovery) {
+      for (const page of [discovery.list, discovery.create, discovery.detail, discovery.edit]) {
+        if (page && !importedComponents.has(page.componentName)) {
+          importedComponents.add(page.componentName);
+          lines.push(`const ${page.componentName} = lazy(() =>`);
+          lines.push(`  import('${page.importPath}').then(m => ({ default: m.${page.componentName} }))`);
           lines.push(");");
-          importedComponents.add(entry.componentName);
         }
       }
     }
   }
   for (const route of routes) {
-    if (!pageFiles.has(route.navRoute)) {
-      const pageName = route.navRoute.split(".").map(capitalize).join("") + "Page";
-      lines.push(`// TODO: const ${pageName} = lazy(() => import('@/pages/...').then(m => ({ default: m.${pageName} })));`);
+    const discovery = pageFiles.get(route.navRoute);
+    const { entityPlural, entitySingular, basePath } = deriveEntityNames(route.navRoute);
+    if (!discovery?.list) {
+      lines.push(`// TODO: const ${entityPlural}Page = lazy(() => import('${basePath}/${entityPlural}Page').then(m => ({ default: m.${entityPlural}Page })));`);
+    }
+    if (!discovery?.create) {
+      lines.push(`// TODO: const ${entitySingular}CreatePage = lazy(() => import('${basePath}/${entitySingular}CreatePage').then(m => ({ default: m.${entitySingular}CreatePage })));`);
+    }
+    if (!discovery?.detail) {
+      lines.push(`// TODO: const ${entitySingular}DetailPage = lazy(() => import('${basePath}/${entitySingular}DetailPage').then(m => ({ default: m.${entitySingular}DetailPage })));`);
+    }
+    if (!discovery?.edit) {
+      lines.push(`// TODO: const ${entitySingular}EditPage = lazy(() => import('${basePath}/${entitySingular}EditPage').then(m => ({ default: m.${entitySingular}EditPage })));`);
     }
   }
   lines.push("");
@@ -58220,30 +58356,44 @@ function generateClientRoutesConfig(routes, pageFiles, includeGuards) {
     const layoutName = getLayoutName(app);
     lines.push("/**");
     lines.push(` * Routes for ${appUpper} application`);
-    lines.push(` * Add these as children of <Route path="/${app}" element={<${layoutName} />}>`);
+    lines.push(` * Flat routes for mergeRoutes() \u2014 children of <Route path="/${app}" element={<${layoutName} />}>`);
     lines.push(" */");
     lines.push(`export const ${app}Routes: RouteObject[] = [`);
     for (const [, moduleRoutes] of Object.entries(modules)) {
       for (const route of moduleRoutes) {
         const modulePath = route.navRoute.split(".").slice(1).map(toKebabCase).join("/");
-        const pageName = route.navRoute.split(".").map(capitalize).join("") + "Page";
-        const pageEntry = pageFiles.get(route.navRoute);
-        const component = pageEntry?.[0]?.componentName || pageName;
-        const hasRealPage = pageFiles.has(route.navRoute);
-        if (includeGuards && route.permissions.length > 0) {
-          lines.push(`  {`);
-          lines.push(`    path: '${modulePath}',`);
-          if (hasRealPage) {
-            lines.push(`    element: <Suspense fallback={<PageLoader />}><PermissionGuard permissions={ROUTES['${route.navRoute}'].permissions}><${component} /></PermissionGuard></Suspense>,`);
-          } else {
-            lines.push(`    element: <PermissionGuard permissions={ROUTES['${route.navRoute}'].permissions}><div>TODO: ${component}</div></PermissionGuard>,`);
-          }
-          lines.push(`  },`);
+        const discovery = pageFiles.get(route.navRoute);
+        const { entityPlural, entitySingular } = deriveEntityNames(route.navRoute);
+        const permGuardOpen = includeGuards && route.permissions.length > 0 ? `<PermissionGuard permissions={ROUTES['${route.navRoute}'].permissions}>` : "";
+        const permGuardClose = permGuardOpen ? "</PermissionGuard>" : "";
+        lines.push(`  // === ${entityPlural.toLowerCase()} (NavRoute: ${route.navRoute}) ===`);
+        const listComp = discovery?.list?.componentName || `${entityPlural}Page`;
+        const listElement = discovery?.list ? `<Suspense fallback={<PageLoader />}>${permGuardOpen}<${listComp} />${permGuardClose}</Suspense>` : void 0;
+        if (listElement) {
+          lines.push(`  { path: '${modulePath}', element: ${listElement} },`);
+        } else {
+          lines.push(`  // TODO: { path: '${modulePath}', element: <${listComp} /> },`);
+        }
+        const createComp = discovery?.create?.componentName || `${entitySingular}CreatePage`;
+        const createElement = discovery?.create ? `<Suspense fallback={<PageLoader />}>${permGuardOpen}<${createComp} />${permGuardClose}</Suspense>` : void 0;
+        if (createElement) {
+          lines.push(`  { path: '${modulePath}/create', element: ${createElement} },`);
+        } else {
+          lines.push(`  // TODO: { path: '${modulePath}/create', element: <${createComp} /> },`);
+        }
+        const detailComp = discovery?.detail?.componentName || `${entitySingular}DetailPage`;
+        const detailElement = discovery?.detail ? `<Suspense fallback={<PageLoader />}>${permGuardOpen}<${detailComp} />${permGuardClose}</Suspense>` : void 0;
+        if (detailElement) {
+          lines.push(`  { path: '${modulePath}/:id', element: ${detailElement} },`);
+        } else {
+          lines.push(`  // TODO: { path: '${modulePath}/:id', element: <${detailComp} /> },`);
+        }
+        const editComp = discovery?.edit?.componentName || `${entitySingular}EditPage`;
+        const editElement = discovery?.edit ? `<Suspense fallback={<PageLoader />}>${permGuardOpen}<${editComp} />${permGuardClose}</Suspense>` : void 0;
+        if (editElement) {
+          lines.push(`  { path: '${modulePath}/:id/edit', element: ${editElement} },`);
         } else {
-          lines.push(`  {`);
-          lines.push(`    path: '${modulePath}',`);
-          lines.push(`    element: ${hasRealPage ? `<Suspense fallback={<PageLoader />}><${component} /></Suspense>` : `<div>TODO: ${component}</div>`},`);
-          lines.push(`  },`);
+          lines.push(`  // TODO: { path: '${modulePath}/:id/edit', element: <${editComp} /> },`);
         }
       }
     }
@@ -58290,6 +58440,23 @@ function navRouteToUrlPath(navRoute) {
 function capitalize(str) {
   return str.charAt(0).toUpperCase() + str.slice(1);
 }
+function singularize(word) {
+  if (word.endsWith("ies")) return word.slice(0, -3) + "y";
+  if (word.endsWith("ses") || word.endsWith("xes") || word.endsWith("zes") || word.endsWith("ches") || word.endsWith("shes")) return word.slice(0, -2);
+  if (word.endsWith("s") && !word.endsWith("ss")) return word.slice(0, -1);
+  return word;
+}
+function deriveEntityNames(navRoute) {
+  const parts = navRoute.split(".");
+  const lastSegment = parts[parts.length - 1];
+  const entityPlural = capitalize(lastSegment);
+  const entitySingular = singularize(entityPlural);
+  const app = capitalize(parts[0]);
+  const moduleParts = parts.slice(1).map(capitalize);
+  const moduleDir = moduleParts.join("/");
+  const basePath = `@/pages/${app}/${moduleDir}`;
+  return { entityPlural, entitySingular, basePath };
+}
 function formatResult5(result, input) {
   const lines = [];
   lines.push("# Scaffold Routes");
@@ -58461,6 +58628,7 @@ async function discoverBackendNavRoutes(structure) {
         if (content.includes("[HttpPost]")) methods.push("POST");
         if (content.includes("[HttpPut]")) methods.push("PUT");
         if (content.includes("[HttpDelete]")) methods.push("DELETE");
+        if (content.includes("[HttpPatch]")) methods.push("PATCH");
         const permissions = [];
         const authorizeMatches = content.matchAll(/\[Authorize\s*\(\s*[^)]*Policy\s*=\s*"([^"]+)"/g);
         for (const match2 of authorizeMatches) {
@@ -58468,8 +58636,8 @@ async function discoverBackendNavRoutes(structure) {
         }
         routes.push({
           navRoute: fullNavRoute,
-          apiPath: `/api/${navRoute.replace(/\./g, "/")}${suffix ? `/${suffix}` : ""}`,
-          webPath: `/${navRoute.replace(/\./g, "/")}${suffix ? `/${suffix}` : ""}`,
+          apiPath: `/api/${navRoute.split(".").map(toKebabCase2).join("/")}${suffix ? `/${toKebabCase2(suffix)}` : ""}`,
+          webPath: `/${navRoute.split(".").map(toKebabCase2).join("/")}${suffix ? `/${toKebabCase2(suffix)}` : ""}`,
           permissions,
           controller: controllerName,
           methods
@@ -58560,14 +58728,26 @@ async function validateApiClients(webPath, backendRoutes, result) {
   }
 }
 async function validateRoutes(webPath, backendRoutes, result) {
-  const routesPath = path20.join(webPath, "src", "routes", "index.tsx");
-  if (!await fileExists(routesPath)) {
+  const routeCandidates = ["clientRoutes.generated.tsx", "index.tsx"];
+  let routesContent = "";
+  for (const candidate of routeCandidates) {
+    const candidatePath = path20.join(webPath, "src", "routes", candidate);
+    if (await fileExists(candidatePath)) {
+      try {
+        routesContent = await readText(candidatePath);
+      } catch {
+        logger.debug(`Failed to read ${candidatePath}`);
+      }
+      break;
+    }
+  }
+  if (!routesContent) {
     result.routes.total = 0;
     result.routes.missing = backendRoutes.map((r) => r.navRoute);
     return;
   }
   try {
-    const content = await readText(routesPath);
+    const content = routesContent;
     const pathMatches = content.matchAll(/path:\s*['"`]([^'"`]+)['"`]/g);
     const frontendPaths = /* @__PURE__ */ new Set();
     for (const match2 of pathMatches) {
@@ -58676,7 +58856,7 @@ async function validateAppWiring(webPath, backendRoutes, result) {
     );
   }
   for (const route of backendRoutes) {
-    const modulePath = route.navRoute.split(".").slice(1).join("/");
+    const modulePath = route.navRoute.split(".").slice(1).map(toKebabCase2).join("/");
     const lastSegment = route.navRoute.split(".").pop() || "";
     const pathInApp = appContent.includes(`path="${modulePath}"`) || appContent.includes(`path='${modulePath}'`) || appContent.includes(`path="${lastSegment}"`) || appContent.includes(`path='${lastSegment}'`);
     if (!pathInApp) {
@@ -58720,6 +58900,9 @@ function generateRecommendations2(result) {
     result.recommendations.push("All routes are synchronized between frontend and backend");
   }
 }
+function toKebabCase2(segment) {
+  return segment.replace(/([a-z0-9])([A-Z])/g, "$1-$2").toLowerCase();
+}
 function formatResult6(result, _input) {
   const lines = [];
   const statusIcon = result.valid ? "\u2705" : "\u274C";
@@ -65090,6 +65273,35 @@ builder.HasOne(e => e.User)
        .HasForeignKey<UserExtension>(e => e.UserId);
 \`\`\`
 
+### Person Extension Pattern (Person Roles)
+
+When creating entities that represent person roles (Employee, Customer, Supplier...), use the Person Extension pattern to link to User instead of duplicating person data:
+
+**Mandatory variant** \u2014 entity always corresponds to a User:
+\`\`\`csharp
+public class Employee : BaseEntity, ITenantEntity, IAuditableEntity
+{
+    public Guid UserId { get; private set; }  // FK to auth_Users (non-nullable)
+    public User? User { get; private set; }
+    // Business properties ONLY \u2014 no FirstName, LastName, Email
+}
+// Config: unique index on (TenantId, UserId)
+\`\`\`
+
+**Optional variant** \u2014 entity may or may not have a User:
+\`\`\`csharp
+public class Customer : BaseEntity, ITenantEntity, IAuditableEntity
+{
+    public Guid? UserId { get; private set; }  // FK to auth_Users (nullable)
+    public User? User { get; private set; }
+    public string FirstName { get; private set; } = null!;  // Own fields as fallback
+    public string DisplayFirstName => User?.FirstName ?? FirstName;  // Computed
+}
+// Config: unique filtered index on (TenantId, UserId) WHERE UserId IS NOT NULL
+\`\`\`
+
+Use \`scaffold_extension\` with \`isPersonRole: true\` and \`userLinkMode: "mandatory" | "optional"\`.
+
 ---
 
 ## 2. Migration Conventions