@atlashub/smartstack-mcp 1.3.0 → 1.4.1

package/dist/index.js

@@ -81,6 +81,26 @@ import path2 from "path";
 import fs from "fs-extra";
 import path from "path";
 import { glob } from "glob";
+var FileSystemError = class extends Error {
+  constructor(message, operation, path14, cause) {
+    super(message);
+    this.operation = operation;
+    this.path = path14;
+    this.cause = cause;
+    this.name = "FileSystemError";
+  }
+};
+function validatePathSecurity(targetPath, baseDir) {
+  const normalizedTarget = path.resolve(targetPath);
+  const normalizedBase = path.resolve(baseDir);
+  if (!normalizedTarget.startsWith(normalizedBase + path.sep) && normalizedTarget !== normalizedBase) {
+    throw new FileSystemError(
+      `Path traversal detected: "${targetPath}" is outside allowed directory "${baseDir}"`,
+      "validatePathSecurity",
+      targetPath
+    );
+  }
+}
 async function fileExists(filePath) {
   try {
     const stat = await fs.stat(filePath);
@@ -101,15 +121,57 @@ async function ensureDirectory(dirPath) {
   await fs.ensureDir(dirPath);
 }
 async function readJson(filePath) {
-  const content = await fs.readFile(filePath, "utf-8");
-  return JSON.parse(content);
+  try {
+    const content = await fs.readFile(filePath, "utf-8");
+    try {
+      return JSON.parse(content);
+    } catch (parseError) {
+      throw new FileSystemError(
+        `Invalid JSON in file: ${filePath}`,
+        "readJson",
+        filePath,
+        parseError instanceof Error ? parseError : void 0
+      );
+    }
+  } catch (error) {
+    if (error instanceof FileSystemError) {
+      throw error;
+    }
+    const err = error instanceof Error ? error : new Error(String(error));
+    throw new FileSystemError(
+      `Failed to read JSON file: ${filePath} - ${err.message}`,
+      "readJson",
+      filePath,
+      err
+    );
+  }
 }
 async function readText(filePath) {
-  return fs.readFile(filePath, "utf-8");
+  try {
+    return await fs.readFile(filePath, "utf-8");
+  } catch (error) {
+    const err = error instanceof Error ? error : new Error(String(error));
+    throw new FileSystemError(
+      `Failed to read file: ${filePath} - ${err.message}`,
+      "readText",
+      filePath,
+      err
+    );
+  }
 }
 async function writeText(filePath, content) {
-  await fs.ensureDir(path.dirname(filePath));
-  await fs.writeFile(filePath, content, "utf-8");
+  try {
+    await fs.ensureDir(path.dirname(filePath));
+    await fs.writeFile(filePath, content, "utf-8");
+  } catch (error) {
+    const err = error instanceof Error ? error : new Error(String(error));
+    throw new FileSystemError(
+      `Failed to write file: ${filePath} - ${err.message}`,
+      "writeText",
+      filePath,
+      err
+    );
+  }
 }
 async function findFiles(pattern, options = {}) {
   const { cwd = process.cwd(), ignore = [] } = options;
@@ -126,7 +188,8 @@ async function findFiles(pattern, options = {}) {
 var defaultConfig = {
   version: "1.0.0",
   smartstack: {
-    projectPath: process.env.SMARTSTACK_PROJECT_PATH || "D:/SmartStack.app/02-Develop",
+    // Will be resolved in getConfig() - never use a hard-coded path
+    projectPath: "",
     apiUrl: process.env.SMARTSTACK_API_URL || "https://localhost:5001",
     apiEnabled: process.env.SMARTSTACK_API_ENABLED !== "false"
   },
@@ -146,7 +209,8 @@ var defaultConfig = {
       "entra_",
       "ref_",
       "loc_",
-      "lic_"
+      "lic_",
+      "tenant_"
     ],
     codePrefixes: {
       core: "core_",
@@ -189,6 +253,17 @@ var defaultConfig = {
   }
 };
 var cachedConfig = null;
+function resolveProjectPath(configPath) {
+  if (process.env.SMARTSTACK_PROJECT_PATH) {
+    return process.env.SMARTSTACK_PROJECT_PATH;
+  }
+  if (configPath && configPath.trim()) {
+    return configPath;
+  }
+  const cwd = process.cwd();
+  logger.warn("No SMARTSTACK_PROJECT_PATH configured, using current directory", { cwd });
+  return cwd;
+}
 async function getConfig() {
   if (cachedConfig) {
     return cachedConfig;
@@ -201,18 +276,23 @@ async function getConfig() {
       logger.info("Configuration loaded from file", { path: configPath });
     } catch (error) {
       logger.warn("Failed to load config file, using defaults", { error });
-      cachedConfig = defaultConfig;
+      cachedConfig = { ...defaultConfig };
     }
   } else {
     logger.debug("No config file found, using defaults");
-    cachedConfig = defaultConfig;
-  }
-  if (process.env.SMARTSTACK_PROJECT_PATH) {
-    cachedConfig.smartstack.projectPath = process.env.SMARTSTACK_PROJECT_PATH;
+    cachedConfig = { ...defaultConfig };
   }
+  cachedConfig.smartstack.projectPath = resolveProjectPath(
+    cachedConfig.smartstack.projectPath
+  );
   if (process.env.SMARTSTACK_API_URL) {
     cachedConfig.smartstack.apiUrl = process.env.SMARTSTACK_API_URL;
   }
+  if (!cachedConfig.smartstack.projectPath) {
+    throw new Error(
+      "SmartStack project path not configured. Set SMARTSTACK_PROJECT_PATH environment variable or configure in config file."
+    );
+  }
   return cachedConfig;
 }
 function mergeConfig(base, override) {
@@ -335,15 +415,21 @@ var ConfigSchema = z.object({
 });
 var ValidateConventionsInputSchema = z.object({
   path: z.string().optional().describe("Project path to validate (default: SmartStack.app path)"),
-  checks: z.array(z.enum(["tables", "migrations", "services", "namespaces", "entities", "all"])).default(["all"]).describe("Types of checks to perform")
+  checks: z.array(z.enum(["tables", "migrations", "services", "namespaces", "entities", "tenants", "controllers", "all"])).default(["all"]).describe("Types of checks to perform")
 });
 var CheckMigrationsInputSchema = z.object({
   projectPath: z.string().optional().describe("EF Core project path"),
   branch: z.string().optional().describe("Git branch to check (default: current)"),
   compareBranch: z.string().optional().describe("Branch to compare against")
 });
+var EntityPropertySchema = z.object({
+  name: z.string().describe("Property name (PascalCase)"),
+  type: z.string().describe("C# type (string, int, Guid, DateTime, etc.)"),
+  required: z.boolean().optional().describe("If true, property is required"),
+  maxLength: z.number().optional().describe("Max length for string properties")
+});
 var ScaffoldExtensionInputSchema = z.object({
-  type: z.enum(["service", "entity", "controller", "component"]).describe("Type of extension to scaffold"),
+  type: z.enum(["feature", "service", "entity", "controller", "component", "test", "dto", "validator", "repository"]).describe('Type of extension to scaffold. Use "feature" for full-stack generation.'),
   name: z.string().describe('Name of the extension (e.g., "UserProfile", "Order")'),
   options: z.object({
     namespace: z.string().optional().describe("Custom namespace"),
@@ -352,7 +438,17 @@ var ScaffoldExtensionInputSchema = z.object({
     outputPath: z.string().optional().describe("Custom output path"),
     isSystemEntity: z.boolean().optional().describe("If true, creates a system entity without TenantId"),
     tablePrefix: z.string().optional().describe('Domain prefix for table name (e.g., "auth_", "nav_", "cfg_")'),
-    schema: z.enum(["core", "extensions"]).optional().describe("Database schema (default: core)")
+    schema: z.enum(["core", "extensions"]).optional().describe("Database schema (default: core)"),
+    dryRun: z.boolean().optional().describe("If true, preview generated code without writing files"),
+    skipService: z.boolean().optional().describe("For feature type: skip service generation"),
+    skipController: z.boolean().optional().describe("For feature type: skip controller generation"),
+    skipComponent: z.boolean().optional().describe("For feature type: skip React component generation"),
+    clientExtension: z.boolean().optional().describe("If true, use extensions schema for client-specific code"),
+    withTests: z.boolean().optional().describe("For feature type: also generate unit tests"),
+    withDtos: z.boolean().optional().describe("For feature type: generate DTOs (Create, Update, Response)"),
+    withValidation: z.boolean().optional().describe("For feature type: generate FluentValidation validators"),
+    withRepository: z.boolean().optional().describe("For feature type: generate repository pattern"),
+    entityProperties: z.array(EntityPropertySchema).optional().describe("Entity properties for DTO/Validator generation")
   }).optional()
 });
 var ApiDocsInputSchema = z.object({
@@ -369,10 +465,30 @@ import { exec } from "child_process";
 import { promisify } from "util";
 import path3 from "path";
 var execAsync = promisify(exec);
+var GitError = class extends Error {
+  constructor(message, command, cwd, cause) {
+    super(message);
+    this.command = command;
+    this.cwd = cwd;
+    this.cause = cause;
+    this.name = "GitError";
+  }
+};
 async function git(command, cwd) {
-  const options = cwd ? { cwd } : {};
-  const { stdout } = await execAsync(`git ${command}`, options);
-  return stdout.trim();
+  const options = cwd ? { cwd, maxBuffer: 10 * 1024 * 1024 } : { maxBuffer: 10 * 1024 * 1024 };
+  try {
+    const { stdout } = await execAsync(`git ${command}`, options);
+    return stdout.trim();
+  } catch (error) {
+    const err = error instanceof Error ? error : new Error(String(error));
+    const stderr = error?.stderr || "";
+    throw new GitError(
+      `Git command failed: git ${command}${stderr ? ` - ${stderr.trim()}` : ""}`,
+      command,
+      cwd,
+      err
+    );
+  }
 }
 async function isGitRepo(cwd) {
   const gitDir = path3.join(cwd || process.cwd(), ".git");
@@ -547,7 +663,7 @@ async function findControllerFiles(apiPath) {
 import path5 from "path";
 var validateConventionsTool = {
   name: "validate_conventions",
-  description: "Validate AtlasHub/SmartStack conventions: SQL schemas (core/extensions), domain table prefixes (auth_, nav_, ai_, etc.), migration naming ({context}_v{version}_{sequence}_*), service interfaces (I*Service), namespace structure",
+  description: "Validate AtlasHub/SmartStack conventions: SQL schemas (core/extensions), domain table prefixes (auth_, nav_, ai_, etc.), migration naming ({context}_v{version}_{sequence}_*), service interfaces (I*Service), namespace structure, controller routes (NavRoute)",
   inputSchema: {
     type: "object",
     properties: {
@@ -559,7 +675,7 @@ var validateConventionsTool = {
         type: "array",
         items: {
           type: "string",
-          enum: ["tables", "migrations", "services", "namespaces", "all"]
+          enum: ["tables", "migrations", "services", "namespaces", "entities", "tenants", "controllers", "all"]
         },
         description: "Types of checks to perform",
         default: ["all"]
@@ -570,7 +686,7 @@ var validateConventionsTool = {
 async function handleValidateConventions(args, config) {
   const input = ValidateConventionsInputSchema.parse(args);
   const projectPath = input.path || config.smartstack.projectPath;
-  const checks = input.checks.includes("all") ? ["tables", "migrations", "services", "namespaces"] : input.checks;
+  const checks = input.checks.includes("all") ? ["tables", "migrations", "services", "namespaces", "entities", "tenants", "controllers"] : input.checks;
   logger.info("Validating conventions", { projectPath, checks });
   const result = {
     valid: true,
@@ -591,6 +707,15 @@ async function handleValidateConventions(args, config) {
   if (checks.includes("namespaces")) {
     await validateNamespaces(structure, config, result);
   }
+  if (checks.includes("entities")) {
+    await validateEntities(structure, config, result);
+  }
+  if (checks.includes("tenants")) {
+    await validateTenantAwareness(structure, config, result);
+  }
+  if (checks.includes("controllers")) {
+    await validateControllerRoutes(structure, config, result);
+  }
   result.valid = result.errors.length === 0;
   result.summary = generateSummary(result, checks);
   return formatResult(result);
@@ -785,6 +910,242 @@ async function validateNamespaces(structure, config, result) {
     }
   }
 }
+async function validateEntities(structure, _config, result) {
+  if (!structure.domain) {
+    result.warnings.push({
+      type: "warning",
+      category: "entities",
+      message: "Domain project not found, skipping entity validation"
+    });
+    return;
+  }
+  const entityFiles = await findFiles("**/*.cs", { cwd: structure.domain });
+  for (const file of entityFiles) {
+    const content = await readText(file);
+    const fileName = path5.basename(file, ".cs");
+    if (fileName.endsWith("Dto") || fileName.endsWith("Command") || fileName.endsWith("Query") || fileName.endsWith("Handler") || fileName.endsWith("Validator") || fileName.endsWith("Exception") || fileName.startsWith("I")) {
+      continue;
+    }
+    const classMatch = content.match(/public\s+(?:class|record)\s+(\w+)(?:\s*:\s*([^{]+))?/);
+    if (!classMatch) continue;
+    const entityName = classMatch[1];
+    const inheritance = classMatch[2]?.trim() || "";
+    const hasBaseEntity = inheritance.includes("BaseEntity");
+    const hasSystemEntity = inheritance.includes("SystemEntity");
+    const hasITenantEntity = inheritance.includes("ITenantEntity");
+    if (!hasBaseEntity && !hasSystemEntity) {
+      continue;
+    }
+    if (hasBaseEntity && !hasSystemEntity && !hasITenantEntity) {
+      result.warnings.push({
+        type: "warning",
+        category: "entities",
+        message: `Entity "${entityName}" inherits BaseEntity but doesn't implement ITenantEntity`,
+        file: path5.relative(structure.root, file),
+        suggestion: "Add ITenantEntity interface for multi-tenant support, or use SystemEntity for platform-level entities"
+      });
+    }
+    if (!content.includes(`private ${entityName}()`)) {
+      result.warnings.push({
+        type: "warning",
+        category: "entities",
+        message: `Entity "${entityName}" is missing private constructor for EF Core`,
+        file: path5.relative(structure.root, file),
+        suggestion: `Add: private ${entityName}() { }`
+      });
+    }
+    if (!content.includes(`public static ${entityName} Create(`)) {
+      result.warnings.push({
+        type: "warning",
+        category: "entities",
+        message: `Entity "${entityName}" is missing factory method`,
+        file: path5.relative(structure.root, file),
+        suggestion: `Add factory method: public static ${entityName} Create(...)`
+      });
+    }
+  }
+}
+async function validateTenantAwareness(structure, _config, result) {
+  if (!structure.domain) {
+    result.warnings.push({
+      type: "warning",
+      category: "tenants",
+      message: "Domain project not found, skipping tenant validation"
+    });
+    return;
+  }
+  const entityFiles = await findFiles("**/*.cs", { cwd: structure.domain });
+  let tenantAwareCount = 0;
+  let systemEntityCount = 0;
+  let ambiguousCount = 0;
+  for (const file of entityFiles) {
+    const content = await readText(file);
+    const classMatch = content.match(/public\s+(?:class|record)\s+(\w+)(?:\s*:\s*([^{]+))?/);
+    if (!classMatch) continue;
+    const entityName = classMatch[1];
+    const inheritance = classMatch[2]?.trim() || "";
+    if (!inheritance.includes("Entity") && !inheritance.includes("ITenant")) {
+      continue;
+    }
+    const hasITenantEntity = inheritance.includes("ITenantEntity");
+    const hasSystemEntity = inheritance.includes("SystemEntity");
+    const hasTenantId = content.includes("TenantId");
+    const hasTenantIdProperty = content.includes("public Guid TenantId") || content.includes("public required Guid TenantId");
+    if (hasITenantEntity) {
+      tenantAwareCount++;
+      if (!hasTenantIdProperty) {
+        result.errors.push({
+          type: "error",
+          category: "tenants",
+          message: `Entity "${entityName}" implements ITenantEntity but is missing TenantId property`,
+          file: path5.relative(structure.root, file),
+          suggestion: "Add: public Guid TenantId { get; private set; }"
+        });
+      }
+      const createMethod = content.match(/public static \w+ Create\s*\(([^)]*)\)/);
+      if (createMethod && !createMethod[1].includes("tenantId") && !createMethod[1].includes("TenantId")) {
+        result.errors.push({
+          type: "error",
+          category: "tenants",
+          message: `Entity "${entityName}" implements ITenantEntity but Create() doesn't require tenantId`,
+          file: path5.relative(structure.root, file),
+          suggestion: "Add tenantId as first parameter: Create(Guid tenantId, ...)"
+        });
+      }
+    }
+    if (hasSystemEntity) {
+      systemEntityCount++;
+      if (hasTenantId) {
+        result.errors.push({
+          type: "error",
+          category: "tenants",
+          message: `System entity "${entityName}" should not have TenantId`,
+          file: path5.relative(structure.root, file),
+          suggestion: "Remove TenantId from system entities"
+        });
+      }
+    }
+    if (!hasITenantEntity && !hasSystemEntity && hasTenantId) {
+      ambiguousCount++;
+      result.warnings.push({
+        type: "warning",
+        category: "tenants",
+        message: `Entity "${entityName}" has TenantId but doesn't implement ITenantEntity`,
+        file: path5.relative(structure.root, file),
+        suggestion: "Add ITenantEntity interface for explicit tenant-awareness"
+      });
+    }
+  }
+  if (tenantAwareCount + systemEntityCount > 0) {
+    result.warnings.push({
+      type: "warning",
+      category: "tenants",
+      message: `Tenant summary: ${tenantAwareCount} tenant-aware, ${systemEntityCount} system, ${ambiguousCount} ambiguous`
+    });
+  }
+}
+async function validateControllerRoutes(structure, _config, result) {
+  if (!structure.api) {
+    result.warnings.push({
+      type: "warning",
+      category: "controllers",
+      message: "API project not found, skipping controller route validation"
+    });
+    return;
+  }
+  const controllerFiles = await findFiles("**/Controllers/**/*Controller.cs", {
+    cwd: structure.api
+  });
+  const systemControllers = [
+    // Auth controllers
+    "AuthController",
+    "RegistrationController",
+    "OnboardingController",
+    "NavigationController",
+    "LogsController",
+    "EntraController",
+    // User-level controllers (not in navigation hierarchy)
+    "PreferencesController",
+    "ApplicationTrackingController",
+    // Support module controllers (using api/support/* routes)
+    "NotificationsController",
+    "SlaController",
+    "TemplatesController",
+    "TicketsController",
+    // DashboardController exists in both User and Support - both use hardcoded routes
+    "DashboardController",
+    // Structure controllers (using api/structure/* routes - navigation paths don't exist yet)
+    "CostCentersController",
+    "OrganisationsController",
+    "OrganizationalDomainsController",
+    // Business controllers (using api/business/* routes - navigation paths don't exist yet)
+    "MyTicketsController"
+  ];
+  let navRouteCount = 0;
+  let hardcodedRouteCount = 0;
+  let systemControllerCount = 0;
+  for (const file of controllerFiles) {
+    const content = await readText(file);
+    const fileName = path5.basename(file, ".cs");
+    if (systemControllers.includes(fileName)) {
+      systemControllerCount++;
+      continue;
+    }
+    const hasNavRoute = content.includes("[NavRoute(");
+    const hasHardcodedRoute = content.includes('[Route("api/[controller]")]') || content.includes('[Route("api/') || /\[Route\s*\(\s*"[^"]+"\s*\)\]/.test(content);
+    if (hasNavRoute) {
+      navRouteCount++;
+      const navRouteMatch = content.match(/\[NavRoute\s*\(\s*"([^"]+)"(?:\s*,\s*Suffix\s*=\s*"([^"]+)")?\s*\)\]/);
+      if (navRouteMatch) {
+        const routePath = navRouteMatch[1];
+        const parts = routePath.split(".");
+        if (parts.length < 2) {
+          result.warnings.push({
+            type: "warning",
+            category: "controllers",
+            message: `Controller "${fileName}" has NavRoute with insufficient depth: "${routePath}"`,
+            file: path5.relative(structure.root, file),
+            suggestion: 'NavRoute should have at least 2 levels: "context.application" (e.g., "platform.administration")'
+          });
+        }
+        const hasUppercase = parts.some((part) => part !== part.toLowerCase());
+        if (hasUppercase) {
+          result.errors.push({
+            type: "error",
+            category: "controllers",
+            message: `Controller "${fileName}" has NavRoute with uppercase characters: "${routePath}"`,
+            file: path5.relative(structure.root, file),
+            suggestion: 'NavRoute paths must be lowercase (e.g., "platform.administration.users")'
+          });
+        }
+      }
+    } else if (hasHardcodedRoute) {
+      hardcodedRouteCount++;
+      result.warnings.push({
+        type: "warning",
+        category: "controllers",
+        message: `Controller "${fileName}" uses hardcoded Route instead of NavRoute`,
+        file: path5.relative(structure.root, file),
+        suggestion: 'Use [NavRoute("context.application.module")] for navigation-based routing'
+      });
+    }
+  }
+  const totalControllers = controllerFiles.length;
+  const businessControllers = totalControllers - systemControllerCount;
+  const navRoutePercentage = businessControllers > 0 ? Math.round(navRouteCount / businessControllers * 100) : 0;
+  result.warnings.push({
+    type: "warning",
+    category: "controllers",
+    message: `Route summary: ${navRouteCount}/${businessControllers} business controllers use NavRoute (${navRoutePercentage}%), ${systemControllerCount} system controllers excluded`
+  });
+  if (navRoutePercentage < 80 && businessControllers > 0) {
+    result.warnings.push({
+      type: "warning",
+      category: "controllers",
+      message: `NavRoute adoption is below 80% (${navRoutePercentage}%). Consider migrating remaining controllers.`
+    });
+  }
+}
 function generateSummary(result, checks) {
   const parts = [];
   parts.push(`Checks performed: ${checks.join(", ")}`);
@@ -928,9 +1289,23 @@ async function parseMigrations(migrationsPath, rootPath) {
     return a.sequence.localeCompare(b.sequence);
   });
 }
+function parseSemver(version) {
+  const match = version.match(/^(\d+)\.(\d+)\.(\d+)$/);
+  if (!match) {
+    return null;
+  }
+  return [
+    parseInt(match[1], 10),
+    parseInt(match[2], 10),
+    parseInt(match[3], 10)
+  ];
+}
 function compareVersions(a, b) {
-  const partsA = a.split(".").map(Number);
-  const partsB = b.split(".").map(Number);
+  const partsA = parseSemver(a);
+  const partsB = parseSemver(b);
+  if (!partsA && !partsB) return 0;
+  if (!partsA) return 1;
+  if (!partsB) return -1;
   for (let i = 0; i < 3; i++) {
     if (partsA[i] > partsB[i]) return 1;
     if (partsA[i] < partsB[i]) return -1;
@@ -955,6 +1330,14 @@ function checkNamingConventions(result, _config) {
         resolution: `Use format: {context}_v{version}_{sequence}_{Description} where version is semver (1.0.0, 1.2.0, etc.)`
       });
     }
+    if (migration.version !== "0.0.0" && !parseSemver(migration.version)) {
+      result.conflicts.push({
+        type: "naming",
+        description: `Migration "${migration.name}" has invalid version format: "${migration.version}"`,
+        files: [migration.file],
+        resolution: `Use semver format (major.minor.patch): 1.0.0, 1.2.0, 2.0.0, etc.`
+      });
+    }
   }
 }
 function checkChronologicalOrder(result) {
@@ -1118,14 +1501,14 @@ import Handlebars from "handlebars";
 import path7 from "path";
 var scaffoldExtensionTool = {
   name: "scaffold_extension",
-  description: "Generate code to extend SmartStack: service (interface + implementation), entity (class + EF config), controller (REST endpoints), or React component",
+  description: "Generate code to extend SmartStack: feature (full-stack), entity, service, controller, component, dto, validator, repository, or test",
   inputSchema: {
     type: "object",
     properties: {
       type: {
         type: "string",
-        enum: ["service", "entity", "controller", "component"],
-        description: "Type of extension to scaffold"
+        enum: ["feature", "service", "entity", "controller", "component", "test", "dto", "validator", "repository"],
+        description: 'Type of extension to scaffold. Use "feature" for full-stack generation.'
       },
       name: {
         type: "string",
@@ -1163,6 +1546,63 @@ var scaffoldExtensionTool = {
             type: "string",
             enum: ["core", "extensions"],
             description: "Database schema (default: core)"
+          },
+          dryRun: {
+            type: "boolean",
+            description: "If true, preview generated code without writing files"
+          },
+          skipService: {
+            type: "boolean",
+            description: "For feature type: skip service generation"
+          },
+          skipController: {
+            type: "boolean",
+            description: "For feature type: skip controller generation"
+          },
+          skipComponent: {
+            type: "boolean",
+            description: "For feature type: skip React component generation"
+          },
+          clientExtension: {
+            type: "boolean",
+            description: "If true, use extensions schema for client-specific code"
+          },
+          withTests: {
+            type: "boolean",
+            description: "For feature type: also generate unit tests"
+          },
+          withDtos: {
+            type: "boolean",
+            description: "For feature type: generate DTOs (Create, Update, Response)"
+          },
+          withValidation: {
+            type: "boolean",
+            description: "For feature type: generate FluentValidation validators"
+          },
+          withRepository: {
+            type: "boolean",
+            description: "For feature type: generate repository pattern"
+          },
+          entityProperties: {
+            type: "array",
+            items: {
+              type: "object",
+              properties: {
+                name: { type: "string" },
+                type: { type: "string" },
+                required: { type: "boolean" },
+                maxLength: { type: "number" }
+              }
+            },
+            description: "Entity properties for DTO/Validator generation"
+          },
+          navRoute: {
+            type: "string",
+            description: 'Navigation route path for controller (e.g., "platform.administration.users"). Required for controllers.'
+          },
+          navRouteSuffix: {
+            type: "string",
+            description: 'Optional suffix for NavRoute (e.g., "dashboard" for sub-resources)'
           }
         }
       }
@@ -1181,35 +1621,149 @@ Handlebars.registerHelper("kebabCase", (str) => {
 });
 async function handleScaffoldExtension(args, config) {
   const input = ScaffoldExtensionInputSchema.parse(args);
-  logger.info("Scaffolding extension", { type: input.type, name: input.name });
+  const dryRun = input.options?.dryRun || false;
+  logger.info("Scaffolding extension", { type: input.type, name: input.name, dryRun });
   const structure = await findSmartStackStructure(config.smartstack.projectPath);
   const result = {
     success: true,
     files: [],
     instructions: []
   };
+  if (input.options?.clientExtension) {
+    input.options.schema = "extensions";
+    input.options.tablePrefix = input.options.tablePrefix || "ext_";
+  }
   try {
     switch (input.type) {
+      case "feature":
+        await scaffoldFeature(input.name, input.options, structure, config, result, dryRun);
+        break;
       case "service":
-        await scaffoldService(input.name, input.options, structure, config, result);
+        await scaffoldService(input.name, input.options, structure, config, result, dryRun);
         break;
       case "entity":
-        await scaffoldEntity(input.name, input.options, structure, config, result);
+        await scaffoldEntity(input.name, input.options, structure, config, result, dryRun);
         break;
       case "controller":
-        await scaffoldController(input.name, input.options, structure, config, result);
+        await scaffoldController(input.name, input.options, structure, config, result, dryRun);
         break;
       case "component":
-        await scaffoldComponent(input.name, input.options, structure, config, result);
+        await scaffoldComponent(input.name, input.options, structure, config, result, dryRun);
+        break;
+      case "test":
+        await scaffoldTest(input.name, input.options, structure, config, result, dryRun);
+        break;
+      case "dto":
+        await scaffoldDtos(input.name, input.options, structure, config, result, dryRun);
+        break;
+      case "validator":
+        await scaffoldValidator(input.name, input.options, structure, config, result, dryRun);
+        break;
+      case "repository":
+        await scaffoldRepository(input.name, input.options, structure, config, result, dryRun);
         break;
     }
   } catch (error) {
     result.success = false;
     result.instructions.push(`Error: ${error instanceof Error ? error.message : "Unknown error"}`);
   }
-  return formatResult3(result, input.type, input.name);
+  return formatResult3(result, input.type, input.name, dryRun);
+}
+async function scaffoldFeature(name, options, structure, config, result, dryRun = false) {
+  const skipService = options?.skipService || false;
+  const skipController = options?.skipController || false;
+  const skipComponent = options?.skipComponent || false;
+  const isClientExtension = options?.clientExtension || false;
+  const withTests = options?.withTests || false;
+  const withDtos = options?.withDtos || false;
+  const withValidation = options?.withValidation || false;
+  const withRepository = options?.withRepository || false;
+  let stepNumber = 1;
+  result.instructions.push(`# Full-Stack Feature: ${name}`);
+  result.instructions.push("");
+  if (isClientExtension) {
+    result.instructions.push("> **Client Extension**: Using `extensions` schema and `ext_` prefix");
+    result.instructions.push("");
+  }
+  result.instructions.push(`## ${stepNumber}. Domain Entity`);
+  await scaffoldEntity(name, options, structure, config, result, dryRun);
+  result.instructions.push("");
+  stepNumber++;
+  if (withDtos) {
+    result.instructions.push(`## ${stepNumber}. DTOs (Data Transfer Objects)`);
+    await scaffoldDtos(name, options, structure, config, result, dryRun);
+    result.instructions.push("");
+    stepNumber++;
+  }
+  if (withValidation) {
+    result.instructions.push(`## ${stepNumber}. FluentValidation Validators`);
+    await scaffoldValidator(name, options, structure, config, result, dryRun);
+    result.instructions.push("");
+    stepNumber++;
+  }
+  if (withRepository) {
+    result.instructions.push(`## ${stepNumber}. Repository Pattern`);
+    await scaffoldRepository(name, options, structure, config, result, dryRun);
+    result.instructions.push("");
+    stepNumber++;
+  }
+  if (!skipService) {
+    result.instructions.push(`## ${stepNumber}. Application Service`);
+    const serviceMethods = [
+      `GetByIdAsync`,
+      `GetAllAsync`,
+      `CreateAsync`,
+      `UpdateAsync`,
+      `DeleteAsync`
+    ];
+    await scaffoldService(name, { ...options, methods: serviceMethods }, structure, config, result, dryRun);
+    result.instructions.push("");
+    stepNumber++;
+  }
+  if (!skipController) {
+    result.instructions.push(`## ${stepNumber}. API Controller`);
+    await scaffoldController(name, options, structure, config, result, dryRun);
+    result.instructions.push("");
+    stepNumber++;
+  }
+  if (!skipComponent) {
+    result.instructions.push(`## ${stepNumber}. React Component`);
+    await scaffoldComponent(name, options, structure, config, result, dryRun);
+    result.instructions.push("");
+    stepNumber++;
+  }
+  if (withTests && !skipService) {
+    result.instructions.push(`## ${stepNumber}. Unit Tests`);
+    await scaffoldTest(name, options, structure, config, result, dryRun);
+    result.instructions.push("");
+  }
+  const generated = ["Entity"];
+  if (withDtos) generated.push("DTOs");
+  if (withValidation) generated.push("Validators");
+  if (withRepository) generated.push("Repository");
+  if (!skipService) generated.push("Service");
+  if (!skipController) generated.push("Controller");
+  if (!skipComponent) generated.push("Component");
+  if (withTests && !skipService) generated.push("Tests");
+  result.instructions.push("---");
+  result.instructions.push(`## Summary: Generated ${generated.join(" + ")}`);
+  result.instructions.push("");
+  result.instructions.push("### Next Steps:");
+  result.instructions.push(`1. Add DbSet to ApplicationDbContext: \`public DbSet<${name}> ${name}s => Set<${name}>();\``);
+  if (withRepository) {
+    result.instructions.push(`2. Register repository: \`services.AddScoped<I${name}Repository, ${name}Repository>();\``);
+  }
+  result.instructions.push(`${withRepository ? "3" : "2"}. Register service: \`services.AddScoped<I${name}Service, ${name}Service>();\``);
+  if (withValidation) {
+    result.instructions.push(`${withRepository ? "4" : "3"}. Register validators: \`services.AddValidatorsFromAssemblyContaining<Create${name}DtoValidator>();\``);
+  }
+  result.instructions.push(`${withRepository ? withValidation ? "5" : "4" : withValidation ? "4" : "3"}. Create migration: \`dotnet ef migrations add ${options?.tablePrefix || "ref_"}vX.X.X_XXX_Add${name}\``);
+  result.instructions.push(`${withRepository ? withValidation ? "6" : "5" : withValidation ? "5" : "4"}. Run migration: \`dotnet ef database update\``);
+  if (!skipComponent) {
+    result.instructions.push(`Import component: \`import { ${name} } from './components/${name}';\``);
+  }
 }
-async function scaffoldService(name, options, structure, config, result) {
+async function scaffoldService(name, options, structure, config, result, dryRun = false) {
   const namespace = options?.namespace || `${config.conventions.namespaces.application}.Services`;
   const methods = options?.methods || ["GetByIdAsync", "GetAllAsync", "CreateAsync", "UpdateAsync", "DeleteAsync"];
   const interfaceTemplate = `using System.Threading;
@@ -1271,19 +1825,24 @@ services.AddScoped<I{{name}}Service, {{name}}Service>();
   const interfaceContent = Handlebars.compile(interfaceTemplate)(context);
   const implementationContent = Handlebars.compile(implementationTemplate)(context);
   const diContent = Handlebars.compile(diTemplate)(context);
-  const basePath = structure.application || config.smartstack.projectPath;
+  const projectRoot = config.smartstack.projectPath;
+  const basePath = structure.application || projectRoot;
   const servicesPath = path7.join(basePath, "Services");
-  await ensureDirectory(servicesPath);
   const interfacePath = path7.join(servicesPath, `I${name}Service.cs`);
   const implementationPath = path7.join(servicesPath, `${name}Service.cs`);
-  await writeText(interfacePath, interfaceContent);
+  validatePathSecurity(interfacePath, projectRoot);
+  validatePathSecurity(implementationPath, projectRoot);
+  if (!dryRun) {
+    await ensureDirectory(servicesPath);
+    await writeText(interfacePath, interfaceContent);
+    await writeText(implementationPath, implementationContent);
+  }
   result.files.push({ path: interfacePath, content: interfaceContent, type: "created" });
-  await writeText(implementationPath, implementationContent);
   result.files.push({ path: implementationPath, content: implementationContent, type: "created" });
   result.instructions.push("Register service in DI container:");
   result.instructions.push(diContent);
 }
-async function scaffoldEntity(name, options, structure, config, result) {
+async function scaffoldEntity(name, options, structure, config, result, dryRun = false) {
   const namespace = options?.namespace || config.conventions.namespaces.domain;
   const baseEntity = options?.baseEntity;
   const isSystemEntity = options?.isSystemEntity || false;
@@ -1297,14 +1856,30 @@ namespace {{namespace}};
 
 /// <summary>
 /// {{name}} entity{{#if baseEntity}} extending {{baseEntity}}{{/if}}
+{{#unless isSystemEntity}}
+/// Tenant-scoped: data is isolated per tenant
+{{else}}
+/// System entity: platform-level, no tenant isolation
+{{/unless}}
 /// </summary>
 {{#if isSystemEntity}}
 public class {{name}} : SystemEntity
 {{else}}
-public class {{name}} : BaseEntity
+public class {{name}} : BaseEntity, ITenantEntity
 {{/if}}
 {
+{{#unless isSystemEntity}}
+    // === MULTI-TENANT ===
+
+    /// <summary>
+    /// Tenant identifier for multi-tenant isolation (required)
+    /// </summary>
+    public Guid TenantId { get; private set; }
+
+{{/unless}}
 {{#if baseEntity}}
+    // === RELATIONSHIPS ===
+
     /// <summary>
     /// Foreign key to {{baseEntity}}
     /// </summary>
@@ -1341,11 +1916,17 @@ public class {{name}} : BaseEntity
         };
     }
 {{else}}
+    /// <param name="tenantId">Required tenant identifier</param>
+    /// <param name="code">Unique code within tenant (will be lowercased)</param>
+    /// <param name="createdBy">User who created this entity</param>
     public static {{name}} Create(
         Guid tenantId,
         string code,
         string? createdBy = null)
     {
+        if (tenantId == Guid.Empty)
+            throw new ArgumentException("TenantId is required", nameof(tenantId));
+
         return new {{name}}
         {
             Id = Guid.NewGuid(),
@@ -1395,6 +1976,14 @@ using {{domainNamespace}};
 
 namespace {{infrastructureNamespace}}.Persistence.Configurations;
 
+/// <summary>
+/// EF Core configuration for {{name}}
+{{#unless isSystemEntity}}
+/// Tenant-aware: includes tenant isolation query filter
+{{else}}
+/// System entity: no tenant isolation
+{{/unless}}
+/// </summary>
 public class {{name}}Configuration : IEntityTypeConfiguration<{{name}}>
 {
     public void Configure(EntityTypeBuilder<{{name}}> builder)
@@ -1406,9 +1995,17 @@ public class {{name}}Configuration : IEntityTypeConfiguration<{{name}}>
         builder.HasKey(e => e.Id);
 
 {{#unless isSystemEntity}}
-        // Multi-tenant
+        // ============================================
+        // MULTI-TENANT CONFIGURATION
+        // ============================================
+
+        // TenantId is required for tenant isolation
         builder.Property(e => e.TenantId).IsRequired();
-        builder.HasIndex(e => e.TenantId);
+        builder.HasIndex(e => e.TenantId)
+            .HasDatabaseName("IX_{{tablePrefix}}{{name}}s_TenantId");
+
+        // Tenant relationship (configured in Tenant configuration)
+        // builder.HasOne<Tenant>().WithMany().HasForeignKey(e => e.TenantId);
 
         // Code: lowercase, unique per tenant (filtered for soft delete)
         builder.Property(e => e.Code).HasMaxLength(100).IsRequired();
@@ -1417,7 +2014,7 @@ public class {{name}}Configuration : IEntityTypeConfiguration<{{name}}>
             .HasFilter("[IsDeleted] = 0")
             .HasDatabaseName("IX_{{tablePrefix}}{{name}}s_Tenant_Code_Unique");
 {{else}}
-        // Code: lowercase, unique (filtered for soft delete)
+        // Code: lowercase, unique globally (filtered for soft delete)
         builder.Property(e => e.Code).HasMaxLength(100).IsRequired();
         builder.HasIndex(e => e.Code)
             .IsUnique()
@@ -1434,6 +2031,10 @@ public class {{name}}Configuration : IEntityTypeConfiguration<{{name}}>
         builder.Property(e => e.DeletedBy).HasMaxLength(256);
 
 {{#if baseEntity}}
+        // ============================================
+        // RELATIONSHIPS
+        // ============================================
+
         // Relationship to {{baseEntity}} (1:1)
         builder.HasOne(e => e.{{baseEntity}})
                .WithOne()
@@ -1445,7 +2046,17 @@ public class {{name}}Configuration : IEntityTypeConfiguration<{{name}}>
                .IsUnique();
 {{/if}}
 
-        // TODO: Add additional configuration
+        // ============================================
+        // QUERY FILTERS
+        // ============================================
+        // Note: Global query filters are applied in DbContext.OnModelCreating
+        // - Soft delete: .HasQueryFilter(e => !e.IsDeleted)
+{{#unless isSystemEntity}}
+        // - Tenant isolation: .HasQueryFilter(e => e.TenantId == _tenantId)
+        // Combined filter applied via ITenantEntity interface check
+{{/unless}}
+
+        // TODO: Add additional business-specific configuration
     }
 }
 `;
@@ -1461,15 +2072,20 @@ public class {{name}}Configuration : IEntityTypeConfiguration<{{name}}>
   };
   const entityContent = Handlebars.compile(entityTemplate)(context);
   const configContent = Handlebars.compile(configTemplate)(context);
-  const domainPath = structure.domain || path7.join(config.smartstack.projectPath, "Domain");
-  const infraPath = structure.infrastructure || path7.join(config.smartstack.projectPath, "Infrastructure");
-  await ensureDirectory(domainPath);
-  await ensureDirectory(path7.join(infraPath, "Persistence", "Configurations"));
+  const projectRoot = config.smartstack.projectPath;
+  const domainPath = structure.domain || path7.join(projectRoot, "Domain");
+  const infraPath = structure.infrastructure || path7.join(projectRoot, "Infrastructure");
   const entityFilePath = path7.join(domainPath, `${name}.cs`);
   const configFilePath = path7.join(infraPath, "Persistence", "Configurations", `${name}Configuration.cs`);
-  await writeText(entityFilePath, entityContent);
+  validatePathSecurity(entityFilePath, projectRoot);
+  validatePathSecurity(configFilePath, projectRoot);
+  if (!dryRun) {
+    await ensureDirectory(domainPath);
+    await ensureDirectory(path7.join(infraPath, "Persistence", "Configurations"));
+    await writeText(entityFilePath, entityContent);
+    await writeText(configFilePath, configContent);
+  }
   result.files.push({ path: entityFilePath, content: entityContent, type: "created" });
-  await writeText(configFilePath, configContent);
   result.files.push({ path: configFilePath, content: configContent, type: "created" });
   result.instructions.push(`Add DbSet to ApplicationDbContext:`);
   result.instructions.push(`public DbSet<${name}> ${name}s => Set<${name}>();`);
@@ -1483,19 +2099,23 @@ public class {{name}}Configuration : IEntityTypeConfiguration<{{name}}>
   result.instructions.push("- IsDeleted, DeletedAt, DeletedBy (soft delete)");
   result.instructions.push("- RowVersion (concurrency)");
 }
-async function scaffoldController(name, options, structure, config, result) {
+async function scaffoldController(name, options, structure, config, result, dryRun = false) {
   const namespace = options?.namespace || `${config.conventions.namespaces.api}.Controllers`;
+  const navRoute = options?.navRoute;
+  const navRouteSuffix = options?.navRouteSuffix;
+  const routeAttribute = navRoute ? navRouteSuffix ? `[NavRoute("${navRoute}", Suffix = "${navRouteSuffix}")]` : `[NavRoute("${navRoute}")]` : `[Route("api/[controller]")]`;
+  const navRouteUsing = navRoute ? "using SmartStack.Api.Core.Routing;\n" : "";
   const controllerTemplate = `using Microsoft.AspNetCore.Authorization;
 using Microsoft.AspNetCore.Mvc;
 using Microsoft.Extensions.Logging;
-
+${navRouteUsing}
 namespace {{namespace}};
 
 /// <summary>
 /// API controller for {{name}} operations
 /// </summary>
 [ApiController]
-[Route("api/[controller]")]
+{{routeAttribute}}
 [Authorize]
 public class {{name}}Controller : ControllerBase
 {
@@ -1570,23 +2190,42 @@ public record Update{{name}}Request();
   const context = {
     namespace,
     name,
-    nameLower: name.charAt(0).toLowerCase() + name.slice(1)
+    nameLower: name.charAt(0).toLowerCase() + name.slice(1),
+    routeAttribute
   };
   const controllerContent = Handlebars.compile(controllerTemplate)(context);
-  const apiPath = structure.api || path7.join(config.smartstack.projectPath, "Api");
+  const projectRoot = config.smartstack.projectPath;
+  const apiPath = structure.api || path7.join(projectRoot, "Api");
   const controllersPath = path7.join(apiPath, "Controllers");
-  await ensureDirectory(controllersPath);
   const controllerFilePath = path7.join(controllersPath, `${name}Controller.cs`);
-  await writeText(controllerFilePath, controllerContent);
+  validatePathSecurity(controllerFilePath, projectRoot);
+  if (!dryRun) {
+    await ensureDirectory(controllersPath);
+    await writeText(controllerFilePath, controllerContent);
+  }
   result.files.push({ path: controllerFilePath, content: controllerContent, type: "created" });
-  result.instructions.push("Controller created. API endpoints:");
-  result.instructions.push(`  GET    /api/${name.toLowerCase()}`);
-  result.instructions.push(`  GET    /api/${name.toLowerCase()}/{id}`);
-  result.instructions.push(`  POST   /api/${name.toLowerCase()}`);
-  result.instructions.push(`  PUT    /api/${name.toLowerCase()}/{id}`);
-  result.instructions.push(`  DELETE /api/${name.toLowerCase()}/{id}`);
-}
-async function scaffoldComponent(name, options, structure, config, result) {
+  if (navRoute) {
+    result.instructions.push("Controller created with NavRoute (Navigation-based routing).");
+    result.instructions.push(`NavRoute: ${navRoute}${navRouteSuffix ? ` (Suffix: ${navRouteSuffix})` : ""}`);
+    result.instructions.push("");
+    result.instructions.push("The actual API route will be resolved from Navigation entities at startup.");
+    result.instructions.push("Ensure the navigation path exists in the database:");
+    result.instructions.push(`  Context > Application > Module > Section matching "${navRoute}"`);
+  } else {
+    result.instructions.push("Controller created with traditional routing.");
+    result.instructions.push("");
+    result.instructions.push("\u26A0\uFE0F  Consider using NavRoute for navigation-based routing:");
+    result.instructions.push(`  [NavRoute("context.application.module")]`);
+    result.instructions.push("");
+    result.instructions.push("API endpoints (with traditional routing):");
+    result.instructions.push(`  GET    /api/${name.toLowerCase()}`);
+    result.instructions.push(`  GET    /api/${name.toLowerCase()}/{id}`);
+    result.instructions.push(`  POST   /api/${name.toLowerCase()}`);
+    result.instructions.push(`  PUT    /api/${name.toLowerCase()}/{id}`);
+    result.instructions.push(`  DELETE /api/${name.toLowerCase()}/{id}`);
+  }
+}
+async function scaffoldComponent(name, options, structure, config, result, dryRun = false) {
   const componentTemplate = `import React, { useState, useEffect } from 'react';
 
 interface {{name}}Props {
@@ -1737,51 +2376,553 @@ export function use{{name}}(options: Use{{name}}Options = {}) {
   };
   const componentContent = Handlebars.compile(componentTemplate)(context);
   const hookContent = Handlebars.compile(hookTemplate)(context);
-  const webPath = structure.web || path7.join(config.smartstack.projectPath, "web", "smartstack-web");
+  const projectRoot = config.smartstack.projectPath;
+  const webPath = structure.web || path7.join(projectRoot, "web", "smartstack-web");
   const componentsPath = options?.outputPath || path7.join(webPath, "src", "components");
   const hooksPath = path7.join(webPath, "src", "hooks");
-  await ensureDirectory(componentsPath);
-  await ensureDirectory(hooksPath);
   const componentFilePath = path7.join(componentsPath, `${name}.tsx`);
   const hookFilePath = path7.join(hooksPath, `use${name}.ts`);
-  await writeText(componentFilePath, componentContent);
+  validatePathSecurity(componentFilePath, projectRoot);
+  validatePathSecurity(hookFilePath, projectRoot);
+  if (!dryRun) {
+    await ensureDirectory(componentsPath);
+    await ensureDirectory(hooksPath);
+    await writeText(componentFilePath, componentContent);
+    await writeText(hookFilePath, hookContent);
+  }
   result.files.push({ path: componentFilePath, content: componentContent, type: "created" });
-  await writeText(hookFilePath, hookContent);
   result.files.push({ path: hookFilePath, content: hookContent, type: "created" });
   result.instructions.push("Import and use the component:");
   result.instructions.push(`import { ${name} } from './components/${name}';`);
   result.instructions.push(`import { use${name} } from './hooks/use${name}';`);
 }
-function formatResult3(result, type, name) {
-  const lines = [];
-  lines.push(`# Scaffold ${type}: ${name}`);
-  lines.push("");
-  if (result.success) {
-    lines.push("## \u2705 Files Generated");
-    lines.push("");
-    for (const file of result.files) {
-      lines.push(`### ${file.type === "created" ? "\u{1F4C4}" : "\u270F\uFE0F"} ${path7.basename(file.path)}`);
-      lines.push(`**Path**: \`${file.path}\``);
-      lines.push("");
-      lines.push("```" + (file.path.endsWith(".cs") ? "csharp" : "typescript"));
-      const contentLines = file.content.split("\n").slice(0, 50);
-      lines.push(contentLines.join("\n"));
-      if (file.content.split("\n").length > 50) {
-        lines.push("// ... (truncated)");
-      }
-      lines.push("```");
-      lines.push("");
+async function scaffoldTest(name, options, structure, config, result, dryRun = false) {
+  const isSystemEntity = options?.isSystemEntity || false;
+  const serviceTestTemplate = `using System;
+using System.Threading;
+using System.Threading.Tasks;
+using Microsoft.Extensions.Logging;
+using Moq;
+using Xunit;
+using FluentAssertions;
+using ${config.conventions.namespaces.application}.Services;
+
+namespace ${config.conventions.namespaces.application}.Tests.Services;
+
+/// <summary>
+/// Unit tests for {{name}}Service
+/// </summary>
+public class {{name}}ServiceTests
+{
+    private readonly Mock<ILogger<{{name}}Service>> _loggerMock;
+    private readonly {{name}}Service _sut;
+
+    public {{name}}ServiceTests()
+    {
+        _loggerMock = new Mock<ILogger<{{name}}Service>>();
+        _sut = new {{name}}Service(_loggerMock.Object);
     }
-    if (result.instructions.length > 0) {
-      lines.push("## \u{1F4CB} Next Steps");
-      lines.push("");
-      for (const instruction of result.instructions) {
-        if (instruction.startsWith("services.") || instruction.startsWith("public DbSet")) {
-          lines.push("```csharp");
-          lines.push(instruction);
-          lines.push("```");
-        } else if (instruction.startsWith("dotnet ")) {
-          lines.push("```bash");
+
+    [Fact]
+    public async Task GetByIdAsync_ShouldReturnEntity_WhenExists()
+    {
+        // Arrange
+        var id = Guid.NewGuid();
+{{#unless isSystemEntity}}
+        var tenantId = Guid.NewGuid();
+{{/unless}}
+
+        // Act
+        var result = await _sut.GetByIdAsync(CancellationToken.None);
+
+        // Assert
+        // TODO: Implement actual assertion
+        result.Should().NotBeNull();
+    }
+
+    [Fact]
+    public async Task GetAllAsync_ShouldReturnList()
+    {
+        // Arrange
+{{#unless isSystemEntity}}
+        var tenantId = Guid.NewGuid();
+{{/unless}}
+
+        // Act
+        var result = await _sut.GetAllAsync(CancellationToken.None);
+
+        // Assert
+        // TODO: Implement actual assertion
+        result.Should().NotBeNull();
+    }
+
+    [Fact]
+    public async Task CreateAsync_ShouldCreateEntity()
+    {
+        // Arrange
+{{#unless isSystemEntity}}
+        var tenantId = Guid.NewGuid();
+{{/unless}}
+
+        // Act
+        var result = await _sut.CreateAsync(CancellationToken.None);
+
+        // Assert
+        // TODO: Implement actual assertion
+        result.Should().NotBeNull();
+    }
+
+    [Fact]
+    public async Task UpdateAsync_ShouldUpdateEntity_WhenExists()
+    {
+        // Arrange
+        var id = Guid.NewGuid();
+
+        // Act
+        var result = await _sut.UpdateAsync(CancellationToken.None);
+
+        // Assert
+        // TODO: Implement actual assertion
+        result.Should().NotBeNull();
+    }
+
+    [Fact]
+    public async Task DeleteAsync_ShouldSoftDelete_WhenExists()
+    {
+        // Arrange
+        var id = Guid.NewGuid();
+
+        // Act
+        var result = await _sut.DeleteAsync(CancellationToken.None);
+
+        // Assert
+        // TODO: Implement actual assertion
+        result.Should().NotBeNull();
+    }
+}
+`;
+  const context = {
+    name,
+    isSystemEntity
+  };
+  const testContent = Handlebars.compile(serviceTestTemplate)(context);
+  const testsPath = structure.application ? path7.join(path7.dirname(structure.application), `${path7.basename(structure.application)}.Tests`, "Services") : path7.join(config.smartstack.projectPath, "Application.Tests", "Services");
+  const testFilePath = path7.join(testsPath, `${name}ServiceTests.cs`);
+  if (!dryRun) {
+    await ensureDirectory(testsPath);
+    await writeText(testFilePath, testContent);
+  }
+  result.files.push({ path: testFilePath, content: testContent, type: "created" });
+  result.instructions.push("Run tests:");
+  result.instructions.push(`dotnet test --filter "FullyQualifiedName~${name}ServiceTests"`);
+  result.instructions.push("");
+  result.instructions.push("Required packages:");
+  result.instructions.push("- xunit");
+  result.instructions.push("- Moq");
+  result.instructions.push("- FluentAssertions");
+}
+async function scaffoldDtos(name, options, structure, config, result, dryRun = false) {
+  const namespace = options?.namespace || `${config.conventions.namespaces.application}.DTOs`;
+  const isSystemEntity = options?.isSystemEntity || false;
+  const properties = options?.entityProperties || [
+    { name: "Name", type: "string", required: true, maxLength: 200 },
+    { name: "Description", type: "string?", required: false, maxLength: 500 }
+  ];
+  const responseDtoTemplate = `using System;
+
+namespace {{namespace}};
+
+/// <summary>
+/// Response DTO for {{name}}
+/// </summary>
+public record {{name}}ResponseDto
+{
+    /// <summary>Unique identifier</summary>
+    public Guid Id { get; init; }
+
+{{#unless isSystemEntity}}
+    /// <summary>Tenant identifier</summary>
+    public Guid TenantId { get; init; }
+
+{{/unless}}
+    /// <summary>Unique code</summary>
+    public string Code { get; init; } = string.Empty;
+
+{{#each properties}}
+    /// <summary>{{name}}</summary>
+    public {{type}} {{name}} { get; init; }{{#if (eq type "string")}} = string.Empty;{{/if}}
+
+{{/each}}
+    /// <summary>Creation timestamp</summary>
+    public DateTime CreatedAt { get; init; }
+
+    /// <summary>Last update timestamp</summary>
+    public DateTime? UpdatedAt { get; init; }
+
+    /// <summary>Created by user</summary>
+    public string? CreatedBy { get; init; }
+}
+`;
+  const createDtoTemplate = `using System;
+using System.ComponentModel.DataAnnotations;
+
+namespace {{namespace}};
+
+/// <summary>
+/// DTO for creating a new {{name}}
+/// </summary>
+public record Create{{name}}Dto
+{
+    /// <summary>Unique code (will be lowercased)</summary>
+    [Required]
+    [MaxLength(100)]
+    public string Code { get; init; } = string.Empty;
+
+{{#each properties}}
+{{#if required}}
+    /// <summary>{{name}} (required)</summary>
+    [Required]
+{{#if maxLength}}
+    [MaxLength({{maxLength}})]
+{{/if}}
+    public {{type}} {{name}} { get; init; }{{#if (eq type "string")}} = string.Empty;{{/if}}
+
+{{else}}
+    /// <summary>{{name}} (optional)</summary>
+{{#if maxLength}}
+    [MaxLength({{maxLength}})]
+{{/if}}
+    public {{type}} {{name}} { get; init; }
+
+{{/if}}
+{{/each}}
+}
+`;
+  const updateDtoTemplate = `using System;
+using System.ComponentModel.DataAnnotations;
+
+namespace {{namespace}};
+
+/// <summary>
+/// DTO for updating an existing {{name}}
+/// </summary>
+public record Update{{name}}Dto
+{
+{{#each properties}}
+{{#if required}}
+    /// <summary>{{name}} (required)</summary>
+    [Required]
+{{#if maxLength}}
+    [MaxLength({{maxLength}})]
+{{/if}}
+    public {{type}} {{name}} { get; init; }{{#if (eq type "string")}} = string.Empty;{{/if}}
+
+{{else}}
+    /// <summary>{{name}} (optional)</summary>
+{{#if maxLength}}
+    [MaxLength({{maxLength}})]
+{{/if}}
+    public {{type}} {{name}} { get; init; }
+
+{{/if}}
+{{/each}}
+}
+`;
+  Handlebars.registerHelper("eq", (a, b) => a === b);
+  const context = {
+    namespace,
+    name,
+    isSystemEntity,
+    properties
+  };
+  const responseContent = Handlebars.compile(responseDtoTemplate)(context);
+  const createContent = Handlebars.compile(createDtoTemplate)(context);
+  const updateContent = Handlebars.compile(updateDtoTemplate)(context);
+  const basePath = structure.application || config.smartstack.projectPath;
+  const dtosPath = path7.join(basePath, "DTOs", name);
+  const responseFilePath = path7.join(dtosPath, `${name}ResponseDto.cs`);
+  const createFilePath = path7.join(dtosPath, `Create${name}Dto.cs`);
+  const updateFilePath = path7.join(dtosPath, `Update${name}Dto.cs`);
+  if (!dryRun) {
+    await ensureDirectory(dtosPath);
+    await writeText(responseFilePath, responseContent);
+    await writeText(createFilePath, createContent);
+    await writeText(updateFilePath, updateContent);
+  }
+  result.files.push({ path: responseFilePath, content: responseContent, type: "created" });
+  result.files.push({ path: createFilePath, content: createContent, type: "created" });
+  result.files.push({ path: updateFilePath, content: updateContent, type: "created" });
+  result.instructions.push("DTOs generated:");
+  result.instructions.push(`- ${name}ResponseDto: For API responses`);
+  result.instructions.push(`- Create${name}Dto: For POST requests`);
+  result.instructions.push(`- Update${name}Dto: For PUT requests`);
+}
+async function scaffoldValidator(name, options, structure, config, result, dryRun = false) {
+  const namespace = options?.namespace || `${config.conventions.namespaces.application}.Validators`;
+  const properties = options?.entityProperties || [
+    { name: "Name", type: "string", required: true, maxLength: 200 },
+    { name: "Description", type: "string?", required: false, maxLength: 500 }
+  ];
+  const createValidatorTemplate = `using FluentValidation;
+using ${config.conventions.namespaces.application}.DTOs;
+
+namespace {{namespace}};
+
+/// <summary>
+/// Validator for Create{{name}}Dto
+/// </summary>
+public class Create{{name}}DtoValidator : AbstractValidator<Create{{name}}Dto>
+{
+    public Create{{name}}DtoValidator()
+    {
+        RuleFor(x => x.Code)
+            .NotEmpty().WithMessage("Code is required")
+            .MaximumLength(100).WithMessage("Code must not exceed 100 characters")
+            .Matches("^[a-z0-9_]+$").WithMessage("Code must be lowercase alphanumeric with underscores");
+
+{{#each properties}}
+{{#if required}}
+        RuleFor(x => x.{{name}})
+            .NotEmpty().WithMessage("{{name}} is required"){{#if maxLength}}
+            .MaximumLength({{maxLength}}).WithMessage("{{name}} must not exceed {{maxLength}} characters"){{/if}};
+
+{{else}}
+{{#if maxLength}}
+        RuleFor(x => x.{{name}})
+            .MaximumLength({{maxLength}}).WithMessage("{{name}} must not exceed {{maxLength}} characters")
+            .When(x => !string.IsNullOrEmpty(x.{{name}}));
+
+{{/if}}
+{{/if}}
+{{/each}}
+    }
+}
+`;
+  const updateValidatorTemplate = `using FluentValidation;
+using ${config.conventions.namespaces.application}.DTOs;
+
+namespace {{namespace}};
+
+/// <summary>
+/// Validator for Update{{name}}Dto
+/// </summary>
+public class Update{{name}}DtoValidator : AbstractValidator<Update{{name}}Dto>
+{
+    public Update{{name}}DtoValidator()
+    {
+{{#each properties}}
+{{#if required}}
+        RuleFor(x => x.{{name}})
+            .NotEmpty().WithMessage("{{name}} is required"){{#if maxLength}}
+            .MaximumLength({{maxLength}}).WithMessage("{{name}} must not exceed {{maxLength}} characters"){{/if}};
+
+{{else}}
+{{#if maxLength}}
+        RuleFor(x => x.{{name}})
+            .MaximumLength({{maxLength}}).WithMessage("{{name}} must not exceed {{maxLength}} characters")
+            .When(x => !string.IsNullOrEmpty(x.{{name}}));
+
+{{/if}}
+{{/if}}
+{{/each}}
+    }
+}
+`;
+  const context = {
+    namespace,
+    name,
+    properties
+  };
+  const createValidatorContent = Handlebars.compile(createValidatorTemplate)(context);
+  const updateValidatorContent = Handlebars.compile(updateValidatorTemplate)(context);
+  const basePath = structure.application || config.smartstack.projectPath;
+  const validatorsPath = path7.join(basePath, "Validators");
+  const createValidatorFilePath = path7.join(validatorsPath, `Create${name}DtoValidator.cs`);
+  const updateValidatorFilePath = path7.join(validatorsPath, `Update${name}DtoValidator.cs`);
+  if (!dryRun) {
+    await ensureDirectory(validatorsPath);
+    await writeText(createValidatorFilePath, createValidatorContent);
+    await writeText(updateValidatorFilePath, updateValidatorContent);
+  }
+  result.files.push({ path: createValidatorFilePath, content: createValidatorContent, type: "created" });
+  result.files.push({ path: updateValidatorFilePath, content: updateValidatorContent, type: "created" });
+  result.instructions.push("Register validators in DI:");
+  result.instructions.push(`services.AddValidatorsFromAssemblyContaining<Create${name}DtoValidator>();`);
+  result.instructions.push("");
+  result.instructions.push("Required package: FluentValidation.DependencyInjectionExtensions");
+}
+async function scaffoldRepository(name, options, structure, config, result, dryRun = false) {
+  const isSystemEntity = options?.isSystemEntity || false;
+  const interfaceTemplate = `using System;
+using System.Collections.Generic;
+using System.Threading;
+using System.Threading.Tasks;
+using ${config.conventions.namespaces.domain};
+
+namespace ${config.conventions.namespaces.application}.Repositories;
+
+/// <summary>
+/// Repository interface for {{name}} entity
+/// </summary>
+public interface I{{name}}Repository
+{
+    /// <summary>Get entity by ID</summary>
+    Task<{{name}}?> GetByIdAsync(Guid id, CancellationToken ct = default);
+
+    /// <summary>Get entity by code</summary>
+    Task<{{name}}?> GetByCodeAsync({{#unless isSystemEntity}}Guid tenantId, {{/unless}}string code, CancellationToken ct = default);
+
+    /// <summary>Get all entities{{#unless isSystemEntity}} for tenant{{/unless}}</summary>
+    Task<IReadOnlyList<{{name}}>> GetAllAsync({{#unless isSystemEntity}}Guid tenantId, {{/unless}}CancellationToken ct = default);
+
+    /// <summary>Check if code exists{{#unless isSystemEntity}} in tenant{{/unless}}</summary>
+    Task<bool> ExistsAsync({{#unless isSystemEntity}}Guid tenantId, {{/unless}}string code, CancellationToken ct = default);
+
+    /// <summary>Add new entity</summary>
+    Task<{{name}}> AddAsync({{name}} entity, CancellationToken ct = default);
+
+    /// <summary>Update entity</summary>
+    Task UpdateAsync({{name}} entity, CancellationToken ct = default);
+
+    /// <summary>Soft delete entity</summary>
+    Task DeleteAsync({{name}} entity, CancellationToken ct = default);
+}
+`;
+  const implementationTemplate = `using System;
+using System.Collections.Generic;
+using System.Linq;
+using System.Threading;
+using System.Threading.Tasks;
+using Microsoft.EntityFrameworkCore;
+using ${config.conventions.namespaces.domain};
+using ${config.conventions.namespaces.infrastructure}.Persistence;
+
+namespace ${config.conventions.namespaces.infrastructure}.Repositories;
+
+/// <summary>
+/// Repository implementation for {{name}} entity
+/// </summary>
+public class {{name}}Repository : I{{name}}Repository
+{
+    private readonly ApplicationDbContext _context;
+
+    public {{name}}Repository(ApplicationDbContext context)
+    {
+        _context = context;
+    }
+
+    /// <inheritdoc />
+    public async Task<{{name}}?> GetByIdAsync(Guid id, CancellationToken ct = default)
+    {
+        return await _context.{{name}}s
+            .FirstOrDefaultAsync(e => e.Id == id, ct);
+    }
+
+    /// <inheritdoc />
+    public async Task<{{name}}?> GetByCodeAsync({{#unless isSystemEntity}}Guid tenantId, {{/unless}}string code, CancellationToken ct = default)
+    {
+        return await _context.{{name}}s
+            .FirstOrDefaultAsync(e => {{#unless isSystemEntity}}e.TenantId == tenantId && {{/unless}}e.Code == code.ToLowerInvariant(), ct);
+    }
+
+    /// <inheritdoc />
+    public async Task<IReadOnlyList<{{name}}>> GetAllAsync({{#unless isSystemEntity}}Guid tenantId, {{/unless}}CancellationToken ct = default)
+    {
+        return await _context.{{name}}s
+            {{#unless isSystemEntity}}.Where(e => e.TenantId == tenantId){{/unless}}
+            .OrderBy(e => e.Code)
+            .ToListAsync(ct);
+    }
+
+    /// <inheritdoc />
+    public async Task<bool> ExistsAsync({{#unless isSystemEntity}}Guid tenantId, {{/unless}}string code, CancellationToken ct = default)
+    {
+        return await _context.{{name}}s
+            .AnyAsync(e => {{#unless isSystemEntity}}e.TenantId == tenantId && {{/unless}}e.Code == code.ToLowerInvariant(), ct);
+    }
+
+    /// <inheritdoc />
+    public async Task<{{name}}> AddAsync({{name}} entity, CancellationToken ct = default)
+    {
+        await _context.{{name}}s.AddAsync(entity, ct);
+        await _context.SaveChangesAsync(ct);
+        return entity;
+    }
+
+    /// <inheritdoc />
+    public async Task UpdateAsync({{name}} entity, CancellationToken ct = default)
+    {
+        _context.{{name}}s.Update(entity);
+        await _context.SaveChangesAsync(ct);
+    }
+
+    /// <inheritdoc />
+    public async Task DeleteAsync({{name}} entity, CancellationToken ct = default)
+    {
+        entity.SoftDelete();
+        await UpdateAsync(entity, ct);
+    }
+}
+`;
+  const context = {
+    name,
+    isSystemEntity
+  };
+  const interfaceContent = Handlebars.compile(interfaceTemplate)(context);
+  const implementationContent = Handlebars.compile(implementationTemplate)(context);
+  const appPath = structure.application || config.smartstack.projectPath;
+  const infraPath = structure.infrastructure || path7.join(config.smartstack.projectPath, "Infrastructure");
+  const interfaceFilePath = path7.join(appPath, "Repositories", `I${name}Repository.cs`);
+  const implementationFilePath = path7.join(infraPath, "Repositories", `${name}Repository.cs`);
+  if (!dryRun) {
+    await ensureDirectory(path7.join(appPath, "Repositories"));
+    await ensureDirectory(path7.join(infraPath, "Repositories"));
+    await writeText(interfaceFilePath, interfaceContent);
+    await writeText(implementationFilePath, implementationContent);
+  }
+  result.files.push({ path: interfaceFilePath, content: interfaceContent, type: "created" });
+  result.files.push({ path: implementationFilePath, content: implementationContent, type: "created" });
+  result.instructions.push("Register repository in DI:");
+  result.instructions.push(`services.AddScoped<I${name}Repository, ${name}Repository>();`);
+}
+function formatResult3(result, type, name, dryRun = false) {
+  const lines = [];
+  if (dryRun) {
+    lines.push(`# \u{1F50D} DRY-RUN: Scaffold ${type}: ${name}`);
+    lines.push("");
+    lines.push("> **Preview mode**: No files were written. Review the generated code below.");
+    lines.push("> To create files, run without `dryRun: true`");
+    lines.push("");
+  } else {
+    lines.push(`# Scaffold ${type}: ${name}`);
+    lines.push("");
+  }
+  if (result.success) {
+    lines.push(dryRun ? "## \u{1F4C4} Files to Generate" : "## \u2705 Files Generated");
+    lines.push("");
+    for (const file of result.files) {
+      lines.push(`### ${file.type === "created" ? "\u{1F4C4}" : "\u270F\uFE0F"} ${path7.basename(file.path)}`);
+      lines.push(`**Path**: \`${file.path}\``);
+      lines.push("");
+      lines.push("```" + (file.path.endsWith(".cs") ? "csharp" : "typescript"));
+      const contentLines = file.content.split("\n").slice(0, 50);
+      lines.push(contentLines.join("\n"));
+      if (file.content.split("\n").length > 50) {
+        lines.push("// ... (truncated)");
+      }
+      lines.push("```");
+      lines.push("");
+    }
+    if (result.instructions.length > 0) {
+      lines.push("## \u{1F4CB} Next Steps");
+      lines.push("");
+      for (const instruction of result.instructions) {
+        if (instruction.startsWith("services.") || instruction.startsWith("public DbSet")) {
+          lines.push("```csharp");
+          lines.push(instruction);
+          lines.push("```");
+        } else if (instruction.startsWith("dotnet ")) {
+          lines.push("```bash");
           lines.push(instruction);
           lines.push("```");
         } else if (instruction.startsWith("import ")) {
@@ -1891,7 +3032,7 @@ async function fetchFromSwagger(apiUrl) {
           required: p.required || false,
           description: p.description
         })),
-        requestBody: operation.requestBody ? "See schema" : void 0,
+        requestBody: operation.requestBody ? { type: "object", required: true } : void 0,
         responses: Object.entries(operation.responses || {}).map(([status, resp]) => ({
           status: parseInt(status, 10),
           description: resp.description
@@ -1942,9 +3083,14 @@ async function parseControllers(structure) {
             });
           }
         }
+        let requestBody;
         if (afterAttribute.includes("[FromBody]")) {
           const bodyMatch = afterAttribute.match(/\[FromBody\]\s*(\w+)\s+(\w+)/);
           if (bodyMatch) {
+            requestBody = {
+              type: bodyMatch[1],
+              required: true
+            };
             parameters.push({
               name: bodyMatch[2],
               in: "body",
@@ -1953,6 +3099,14 @@ async function parseControllers(structure) {
             });
           }
         }
+        let summary;
+        const methodStartIndex = content.lastIndexOf("/// <summary>", match.index);
+        if (methodStartIndex !== -1 && match.index - methodStartIndex < 500) {
+          const summaryMatch = content.substring(methodStartIndex, match.index).match(/\/\/\/\s*<summary>\s*\n?\s*\/\/\/\s*(.+?)\s*\n?\s*\/\/\/\s*<\/summary>/s);
+          if (summaryMatch) {
+            summary = summaryMatch[1].replace(/\/\/\/\s*/g, "").trim();
+          }
+        }
         const queryMatches = afterAttribute.matchAll(/\[FromQuery\]\s*(\w+)\s+(\w+)/g);
         for (const qm of queryMatches) {
           parameters.push({
@@ -1962,20 +3116,88 @@ async function parseControllers(structure) {
             required: false
           });
         }
+        const example = {};
+        if (requestBody) {
+          example.request = generateExampleRequest(requestBody.type);
+        }
+        if (method === "GET" || method === "POST") {
+          example.response = generateExampleResponse(controllerName, method);
+        }
         endpoints.push({
           method,
           path: fullPath.replace(/\/+/g, "/"),
           controller: controllerName,
           action: methodMatch ? methodMatch[2] : "Unknown",
+          summary,
           parameters,
-          responses: [{ status: 200, description: "Success" }],
-          authorize: hasAuthorize
+          requestBody,
+          responses: generateResponses(method),
+          authorize: hasAuthorize,
+          example
         });
       }
     }
   }
   return endpoints;
 }
+function generateResponses(method) {
+  switch (method) {
+    case "GET":
+      return [
+        { status: 200, description: "Success" },
+        { status: 404, description: "Not Found" }
+      ];
+    case "POST":
+      return [
+        { status: 201, description: "Created" },
+        { status: 400, description: "Bad Request" },
+        { status: 422, description: "Validation Error" }
+      ];
+    case "PUT":
+    case "PATCH":
+      return [
+        { status: 204, description: "No Content" },
+        { status: 400, description: "Bad Request" },
+        { status: 404, description: "Not Found" }
+      ];
+    case "DELETE":
+      return [
+        { status: 204, description: "No Content" },
+        { status: 404, description: "Not Found" }
+      ];
+    default:
+      return [{ status: 200, description: "Success" }];
+  }
+}
+function generateExampleRequest(typeName) {
+  const name = typeName.replace("Request", "").replace("Dto", "").replace("Create", "").replace("Update", "");
+  const example = {
+    code: `${name.toLowerCase()}_001`
+  };
+  if (typeName.includes("Create")) {
+    example.name = `New ${name}`;
+    example.description = `Description for ${name}`;
+  } else if (typeName.includes("Update")) {
+    example.name = `Updated ${name}`;
+    example.description = `Updated description for ${name}`;
+  }
+  return JSON.stringify(example, null, 2);
+}
+function generateExampleResponse(controllerName, method) {
+  const example = {
+    id: "3fa85f64-5717-4562-b3fc-2c963f66afa6",
+    tenantId: "6fa85f64-5717-4562-b3fc-2c963f66afa6",
+    code: `${controllerName.toLowerCase()}_001`,
+    name: `Example ${controllerName}`,
+    createdAt: (/* @__PURE__ */ new Date()).toISOString(),
+    updatedAt: null,
+    createdBy: "user@example.com"
+  };
+  if (method === "GET") {
+    return JSON.stringify(example, null, 2);
+  }
+  return JSON.stringify(example, null, 2);
+}
 function formatAsMarkdown(endpoints) {
   const lines = [];
   lines.push("# SmartStack API Documentation");
@@ -2009,6 +3231,18 @@ function formatAsMarkdown(endpoints) {
         }
         lines.push("");
       }
+      if (endpoint.requestBody) {
+        lines.push("**Request Body:**");
+        lines.push("");
+        lines.push(`Type: \`${endpoint.requestBody.type}\``);
+        lines.push("");
+        if (endpoint.example?.request) {
+          lines.push("```json");
+          lines.push(endpoint.example.request);
+          lines.push("```");
+          lines.push("");
+        }
+      }
       if (endpoint.responses.length > 0) {
         lines.push("**Responses:**");
         lines.push("");
@@ -2017,11 +3251,27 @@ function formatAsMarkdown(endpoints) {
         }
         lines.push("");
       }
+      if (endpoint.example?.response && (endpoint.method === "GET" || endpoint.method === "POST")) {
+        lines.push("**Example Response:**");
+        lines.push("");
+        lines.push("```json");
+        lines.push(endpoint.example.response);
+        lines.push("```");
+        lines.push("");
+      }
     }
   }
   if (endpoints.length === 0) {
     lines.push("No endpoints found matching the filter criteria.");
   }
+  lines.push("---");
+  lines.push("");
+  lines.push("## Summary");
+  lines.push("");
+  lines.push(`- **Total Endpoints**: ${endpoints.length}`);
+  lines.push(`- **Controllers**: ${new Set(endpoints.map((e) => e.controller)).size}`);
+  lines.push(`- **Authenticated**: ${endpoints.filter((e) => e.authorize).length}`);
+  lines.push(`- **Public**: ${endpoints.filter((e) => !e.authorize).length}`);
   return lines.join("\n");
 }
 function formatAsOpenApi(endpoints) {
@@ -2056,7 +3306,144 @@ function formatAsOpenApi(endpoints) {
       security: endpoint.authorize ? [{ bearerAuth: [] }] : void 0
     };
   }
-  return JSON.stringify(spec, null, 2);
+  return JSON.stringify(spec, null, 2);
+}
+
+// src/tools/suggest-migration.ts
+import { z as z2 } from "zod";
+import path9 from "path";
+var suggestMigrationTool = {
+  name: "suggest_migration",
+  description: "Suggest a migration name following SmartStack conventions ({context}_v{version}_{sequence}_{Description})",
+  inputSchema: {
+    type: "object",
+    properties: {
+      description: {
+        type: "string",
+        description: 'Description of what the migration does (e.g., "Add User Profiles", "Create Orders Table")'
+      },
+      context: {
+        type: "string",
+        enum: ["core", "extensions"],
+        description: "DbContext name (default: core)"
+      },
+      version: {
+        type: "string",
+        description: 'Semver version (e.g., "1.0.0", "1.2.0"). If not provided, uses latest from existing migrations.'
+      }
+    },
+    required: ["description"]
+  }
+};
+var SuggestMigrationInputSchema = z2.object({
+  description: z2.string().describe("Description of what the migration does"),
+  context: z2.enum(["core", "extensions"]).optional().describe("DbContext name (default: core)"),
+  version: z2.string().optional().describe('Semver version (e.g., "1.0.0")')
+});
+async function handleSuggestMigration(args, config) {
+  const input = SuggestMigrationInputSchema.parse(args);
+  const context = input.context || "core";
+  logger.info("Suggesting migration name", { description: input.description, context });
+  const structure = await findSmartStackStructure(config.smartstack.projectPath);
+  const existingMigrations = await findExistingMigrations(structure, config, context);
+  let version = input.version;
+  let sequence = 1;
+  if (existingMigrations.length > 0) {
+    const latestMigration = existingMigrations[existingMigrations.length - 1];
+    if (!version) {
+      version = latestMigration.version;
+    }
+    const migrationsInVersion = existingMigrations.filter((m) => m.version === version);
+    if (migrationsInVersion.length > 0) {
+      const maxSequence = Math.max(...migrationsInVersion.map((m) => m.sequence));
+      sequence = maxSequence + 1;
+    }
+  } else {
+    version = version || "1.0.0";
+  }
+  const pascalDescription = toPascalCase(input.description);
+  const sequenceStr = sequence.toString().padStart(3, "0");
+  const migrationName = `${context}_v${version}_${sequenceStr}_${pascalDescription}`;
+  const command = `dotnet ef migrations add ${migrationName} --context ApplicationDbContext`;
+  const lines = [];
+  lines.push("# Migration Name Suggestion");
+  lines.push("");
+  lines.push("## Suggested Name");
+  lines.push("```");
+  lines.push(migrationName);
+  lines.push("```");
+  lines.push("");
+  lines.push("## Command");
+  lines.push("```bash");
+  lines.push(command);
+  lines.push("```");
+  lines.push("");
+  lines.push("## Convention Details");
+  lines.push("");
+  lines.push(`| Part | Value | Description |`);
+  lines.push(`|------|-------|-------------|`);
+  lines.push(`| Context | \`${context}\` | DbContext name |`);
+  lines.push(`| Version | \`v${version}\` | Semver version |`);
+  lines.push(`| Sequence | \`${sequenceStr}\` | Order in version |`);
+  lines.push(`| Description | \`${pascalDescription}\` | Migration description |`);
+  lines.push("");
+  if (existingMigrations.length > 0) {
+    lines.push("## Existing Migrations (last 5)");
+    lines.push("");
+    const recent = existingMigrations.slice(-5);
+    for (const m of recent) {
+      lines.push(`- \`${m.name}\``);
+    }
+  }
+  return lines.join("\n");
+}
+async function findExistingMigrations(structure, config, context) {
+  const migrations = [];
+  const infraPath = structure.infrastructure || path9.join(config.smartstack.projectPath, "Infrastructure");
+  const migrationsPath = path9.join(infraPath, "Migrations");
+  try {
+    const migrationFiles = await findFiles("*.cs", { cwd: migrationsPath });
+    const migrationPattern = /^(\w+)_v(\d+\.\d+\.\d+)_(\d+)_(\w+)\.cs$/;
+    for (const file of migrationFiles) {
+      const fileName = path9.basename(file);
+      if (fileName.includes(".Designer.") || fileName.includes("ModelSnapshot")) {
+        continue;
+      }
+      const match = fileName.match(migrationPattern);
+      if (match) {
+        const [, ctx, ver, seq, desc] = match;
+        if (ctx === context || !context) {
+          migrations.push({
+            name: fileName.replace(".cs", ""),
+            context: ctx,
+            version: ver,
+            sequence: parseInt(seq, 10),
+            description: desc
+          });
+        }
+      }
+    }
+    migrations.sort((a, b) => {
+      const verCompare = compareVersions2(a.version, b.version);
+      if (verCompare !== 0) return verCompare;
+      return a.sequence - b.sequence;
+    });
+  } catch {
+    logger.debug("No migrations folder found");
+  }
+  return migrations;
+}
+function toPascalCase(str) {
+  return str.replace(/[^a-zA-Z0-9\s]/g, "").split(/\s+/).map((word) => word.charAt(0).toUpperCase() + word.slice(1).toLowerCase()).join("");
+}
+function compareVersions2(a, b) {
+  const aParts = a.split(".").map(Number);
+  const bParts = b.split(".").map(Number);
+  for (let i = 0; i < 3; i++) {
+    if (aParts[i] > bParts[i]) return 1;
+    if (aParts[i] < bParts[i]) return -1;
+  }
+  return 0;
 }
 
 // src/resources/conventions.ts
@@ -2105,6 +3492,7 @@ Tables are organized by domain using prefixes:
 | \`ref_\` | References | ref_Companies, ref_Departments |
 | \`loc_\` | Localization | loc_Languages, loc_Translations |
 | \`lic_\` | Licensing | lic_Licenses |
+| \`tenant_\` | Multi-Tenancy | tenant_Tenants, tenant_TenantUsers, tenant_TenantUserRoles |
 
 ### Navigation Code Prefixes
 
@@ -2571,6 +3959,286 @@ public class MyEntityConfiguration : IEntityTypeConfiguration<MyEntity>
 
 ---
 
+## 8. Multi-Tenant Architecture
+
+### Overview
+
+SmartStack implements a comprehensive multi-tenant architecture where:
+- **Platform scope**: Users with roles via \`UserRole\` (no tenant) see ALL tenants
+- **Tenant scope**: Users with roles via \`TenantUserRole\` see ONLY their tenant
+
+### Tenant Model
+
+\`\`\`
+License (1) \u2500\u2500\u2500\u2500\u2500\u2500\u25BA (N) Tenant
+                         \u2502
+                         \u251C\u2500\u2500\u25BA (1:1) Organisation (if B2B)
+                         \u2502
+                         \u2514\u2500\u2500\u25BA (N) TenantUser \u2500\u2500\u25BA (N) TenantUserRole
+                                    \u2502
+                                    \u2514\u2500\u2500\u25BA User (global)
+\`\`\`
+
+### Core Entities
+
+#### Tenant
+
+| Field | Type | Description |
+|-------|------|-------------|
+| \`Id\` | Guid | Primary key |
+| \`LicenseId\` | Guid (FK) | Link to License (features & limits) |
+| \`Slug\` | string? | Optional vanity URL (unique, lowercase, alphanum + hyphen) |
+| \`Name\` | string | Display name |
+| \`Type\` | enum | B2B (with Organisation) or B2C |
+| \`Status\` | enum | Active, Suspended, Deleted |
+| \`CreatedBy\` | Guid (FK) | User who created the tenant |
+| \`CreatedAt\` | DateTime | Creation timestamp |
+
+\`\`\`csharp
+public class Tenant : SystemEntity
+{
+    public Guid LicenseId { get; private set; }
+    public License License { get; private set; }
+
+    public string? Slug { get; private set; }  // Vanity URL (optional)
+    public string Name { get; private set; }
+    public TenantType Type { get; private set; }
+    public TenantStatus Status { get; private set; }
+
+    public Guid CreatedBy { get; private set; }
+    public User Creator { get; private set; }
+
+    // Navigation
+    public ICollection<TenantUser> TenantUsers { get; private set; }
+    public Organisation? Organisation { get; private set; }  // If B2B
+}
+
+public enum TenantType { B2B = 1, B2C = 2 }
+public enum TenantStatus { Active = 1, Suspended = 2, Deleted = 3 }
+\`\`\`
+
+#### TenantUser
+
+Links a User to a Tenant with membership metadata.
+
+| Field | Type | Description |
+|-------|------|-------------|
+| \`Id\` | Guid | Primary key |
+| \`TenantId\` | Guid (FK) | **NOT NULL** - Tenant reference |
+| \`UserId\` | Guid (FK) | User reference |
+| \`IsDefault\` | bool | Default tenant for this user (unique per user) |
+| \`Status\` | enum | Pending, Active, Revoked |
+| \`JoinedAt\` | DateTime | When user joined tenant |
+
+\`\`\`csharp
+public class TenantUser
+{
+    public Guid Id { get; private set; }
+    public Guid TenantId { get; private set; }  // NOT NULL
+    public Tenant Tenant { get; private set; }
+
+    public Guid UserId { get; private set; }
+    public User User { get; private set; }
+
+    public bool IsDefault { get; private set; }
+    public TenantUserStatus Status { get; private set; }
+    public DateTime JoinedAt { get; private set; }
+
+    // Roles within this tenant
+    public ICollection<TenantUserRole> Roles { get; private set; }
+}
+
+public enum TenantUserStatus { Pending = 1, Active = 2, Revoked = 3 }
+\`\`\`
+
+#### TenantUserRole
+
+Assigns roles to a user within a specific tenant.
+
+| Field | Type | Description |
+|-------|------|-------------|
+| \`TenantUserId\` | Guid (FK) | TenantUser reference |
+| \`RoleId\` | Guid (FK) | Role reference |
+| \`AssignedAt\` | DateTime | When role was assigned |
+| \`AssignedBy\` | string? | Who assigned the role |
+
+\`\`\`csharp
+public class TenantUserRole
+{
+    public Guid TenantUserId { get; private set; }
+    public TenantUser TenantUser { get; private set; }
+
+    public Guid RoleId { get; private set; }
+    public Role Role { get; private set; }
+
+    public DateTime AssignedAt { get; private set; }
+    public string? AssignedBy { get; private set; }
+}
+\`\`\`
+
+#### TenantInvitation
+
+Manages user invitations to a tenant.
+
+| Field | Type | Description |
+|-------|------|-------------|
+| \`Id\` | Guid | Primary key |
+| \`TenantId\` | Guid (FK) | Target tenant |
+| \`Email\` | string | Invited email address |
+| \`RoleId\` | Guid (FK) | Role to assign on acceptance |
+| \`Token\` | string | Unique invitation token |
+| \`ExpiresAt\` | DateTime | Token expiration |
+| \`Status\` | enum | Pending, Accepted, Expired, Revoked |
+| \`InvitedBy\` | Guid (FK) | User who sent invitation |
+| \`InvitedAt\` | DateTime | Invitation timestamp |
+
+\`\`\`csharp
+public class TenantInvitation
+{
+    public Guid Id { get; private set; }
+    public Guid TenantId { get; private set; }
+    public Tenant Tenant { get; private set; }
+
+    public string Email { get; private set; }
+    public Guid RoleId { get; private set; }
+    public Role Role { get; private set; }
+
+    public string Token { get; private set; }
+    public DateTime ExpiresAt { get; private set; }
+    public TenantInvitationStatus Status { get; private set; }
+
+    public Guid InvitedBy { get; private set; }
+    public User Inviter { get; private set; }
+    public DateTime InvitedAt { get; private set; }
+}
+
+public enum TenantInvitationStatus { Pending = 1, Accepted = 2, Expired = 3, Revoked = 4 }
+\`\`\`
+
+### Access Control Matrix
+
+| Role Source | Scope | Description |
+|-------------|-------|-------------|
+| \`UserRole\` (existing) | Platform | Roles WITHOUT tenant \u2192 sees ALL tenants |
+| \`TenantUserRole\` (new) | Tenant | Roles WITH tenant \u2192 sees ONLY that tenant |
+
+**Examples:**
+
+\`\`\`
+UserRole: UserId=1, RoleId=PlatformAdmin    \u2192 User 1 sees ALL tenants
+UserRole: UserId=2, RoleId=PlatformReader   \u2192 User 2 reads ALL tenants
+
+TenantUserRole: TenantUserId=3, RoleId=Admin   \u2192 User 3 is Admin of Tenant A only
+TenantUserRole: TenantUserId=4, RoleId=User    \u2192 User 4 is User of Tenant A only
+\`\`\`
+
+### Organisation (B2B Extension)
+
+Organisation is a 1:1 extension of Tenant for B2B scenarios:
+
+\`\`\`csharp
+public class Organisation : BaseEntity
+{
+    public Guid TenantId { get; private set; }  // FK to Tenant
+    public Tenant Tenant { get; private set; }
+
+    // Organisation-specific fields
+    public string LegalName { get; private set; }
+    public string? VatNumber { get; private set; }
+    public string? Address { get; private set; }
+    // ... other B2B fields
+}
+\`\`\`
+
+### License Integration
+
+Features and limits are managed via License:
+
+\`\`\`csharp
+// License.LimitsJson example
+{
+    "max_users": 100,
+    "max_tenants": 5,
+    "max_storage_gb": 50
+}
+
+// Check in service
+public async Task<bool> CanCreateTenantAsync(Guid licenseId)
+{
+    var license = await _licenseService.GetAsync(licenseId);
+    var limits = JsonSerializer.Deserialize<LicenseLimits>(license.LimitsJson);
+    var currentTenants = await _tenantRepo.CountByLicenseAsync(licenseId);
+    return currentTenants < limits.MaxTenants;
+}
+\`\`\`
+
+### URL Routing
+
+Tenant identification in URLs:
+
+| Pattern | Example | Use Case |
+|---------|---------|----------|
+| GUID (default) | \`/{tenant-guid}/api/...\` | Always works, secure |
+| Slug (optional) | \`/{slug}/api/...\` | Vanity URL for premium clients |
+
+\`\`\`csharp
+// Middleware resolution priority
+1. Extract from URL path (/{tenant-identifier}/...)
+2. Check if GUID \u2192 resolve directly
+3. Check if Slug \u2192 resolve by slug
+4. Fallback to user's default tenant (IsDefault=true)
+\`\`\`
+
+### Audit Trail
+
+Critical tables have history tracking:
+
+- \`TenantUserHistory\` - tracks membership changes
+- \`TenantUserRoleHistory\` - tracks role assignment changes
+
+\`\`\`csharp
+public class TenantUserHistory : IHistoryEntity<Guid>
+{
+    public Guid Id { get; set; }
+    public Guid SourceId { get; set; }  // TenantUser.Id
+    public ChangeType ChangeType { get; set; }
+    public string? OldValues { get; set; }  // JSON
+    public string? NewValues { get; set; }  // JSON
+    public DateTime ChangedAt { get; set; }
+    public string? ChangedBy { get; set; }
+}
+\`\`\`
+
+### Database Constraints
+
+\`\`\`sql
+-- Tenant slug unique (if set)
+CREATE UNIQUE INDEX IX_Tenant_Slug ON tenant_Tenants(Slug) WHERE Slug IS NOT NULL;
+
+-- Only one default tenant per user
+CREATE UNIQUE INDEX IX_TenantUser_IsDefault
+ON tenant_TenantUsers(UserId) WHERE IsDefault = 1;
+
+-- Composite key for TenantUserRole
+ALTER TABLE tenant_TenantUserRoles
+ADD CONSTRAINT PK_TenantUserRole PRIMARY KEY (TenantUserId, RoleId);
+\`\`\`
+
+### Table Prefix
+
+All tenant-related tables use the \`tenant_\` prefix:
+
+| Table | Prefix |
+|-------|--------|
+| Tenants | \`tenant_Tenants\` |
+| TenantUsers | \`tenant_TenantUsers\` |
+| TenantUserRoles | \`tenant_TenantUserRoles\` |
+| TenantInvitations | \`tenant_TenantInvitations\` |
+| TenantUserHistory | \`tenant_TenantUserHistory\` |
+| TenantUserRoleHistory | \`tenant_TenantUserRoleHistory\` |
+
+---
+
 ## Quick Reference
 
 | Category | Convention | Example |
@@ -2586,11 +4254,185 @@ public class MyEntityConfiguration : IEntityTypeConfiguration<MyEntity>
 | Domain namespace | \`${namespaces.domain}\` | - |
 | API namespace | \`${namespaces.api}\` | - |
 | Required entity fields | Id, TenantId, Code, Audit, SoftDelete, RowVersion | See Entity Conventions |
+| Tenant prefix | \`tenant_\` | \`tenant_Tenants\`, \`tenant_TenantUsers\` |
+| Platform roles | \`UserRole\` | No TenantId \u2192 sees ALL tenants |
+| Tenant roles | \`TenantUserRole\` | With TenantId \u2192 sees ONLY that tenant |
+| License:Tenant | 1:N | One License can have multiple Tenants |
+| Dry-run scaffold | \`dryRun: true\` | Preview generated code without writing |
+| Tenant-aware entity | \`ITenantEntity\` | Default for scaffold_extension |
+| System entity | \`isSystemEntity: true\` | No TenantId, platform-level |
+| Full-stack scaffold | \`type: "feature"\` | Entity + DTOs + Validators + Repository + Service + Controller + Component |
+| Client extension | \`clientExtension: true\` | Auto-sets schema=extensions + prefix=ext_ |
+| Unit tests | \`type: "test"\` | xUnit tests with Moq & FluentAssertions |
+| DTOs generation | \`withDtos: true\` | Create, Update, Response DTOs |
+| Validation | \`withValidation: true\` | FluentValidation validators |
+| Repository | \`withRepository: true\` | Interface + Implementation |
+| Migration naming | \`suggest_migration\` | {context}_v{version}_{seq}_{Desc} |
+
+---
+
+## 9. MCP Tools & Resources
+
+### Available Tools
+
+| Tool | Description |
+|------|-------------|
+| \`scaffold_extension\` | Generate code: feature (full-stack), entity, service, controller, component, dto, validator, repository, or test |
+| \`validate_conventions\` | Validate SmartStack conventions compliance |
+| \`check_migrations\` | Analyze EF Core migrations for conflicts |
+| \`api_docs\` | Get API documentation from Swagger/Controllers with examples |
+| \`suggest_migration\` | Suggest migration name following conventions |
+
+### Available Resources
+
+| URI | Description |
+|-----|-------------|
+| \`smartstack://conventions\` | This documentation |
+| \`smartstack://project\` | Project structure information |
+| \`smartstack://entities\` | Quick reference of all domain entities |
+| \`smartstack://entities/{filter}\` | Filtered entity list by name/prefix |
+| \`smartstack://schema\` | Database schema information |
+| \`smartstack://api\` | API endpoints documentation |
+
+### Scaffold Extension
+
+Generate tenant-aware code by default:
+
+**Type Options:**
+
+| Type | Description | Generated Files |
+|------|-------------|-----------------|
+| \`feature\` | **Full-stack generation** | Entity + DTOs + Validators + Repository + Service + Controller + Component |
+| \`entity\` | Domain entity only | Entity class + EF Configuration |
+| \`dto\` | DTOs only | Create, Update, Response DTOs |
+| \`validator\` | Validators only | FluentValidation validators |
+| \`repository\` | Repository only | Interface + Implementation |
+| \`service\` | Service layer only | Interface + Implementation |
+| \`controller\` | API controller only | REST Controller |
+| \`component\` | React component only | Component + Hook + Types |
+| \`test\` | Unit tests only | xUnit tests with Moq |
+
+#### Full-Stack Feature (Recommended)
+
+Generate all layers in one command:
+
+\`\`\`json
+// Complete feature: Entity \u2192 Service \u2192 Controller \u2192 Component
+{
+  "type": "feature",
+  "name": "Product",
+  "options": {
+    "tablePrefix": "ref_",
+    "dryRun": true,       // Preview first
+    "withTests": true     // Include unit tests
+  }
+}
+
+// Client extension (uses 'extensions' schema + 'ext_' prefix)
+{
+  "type": "feature",
+  "name": "CustomReport",
+  "options": {
+    "clientExtension": true,  // Auto-sets schema + prefix
+    "skipController": true    // Skip API, React-only
+  }
+}
+\`\`\`
+
+#### Individual Types
+
+\`\`\`json
+// Entity (default: tenant-aware with ITenantEntity)
+{
+  "type": "entity",
+  "name": "Product",
+  "options": {
+    "tablePrefix": "ref_",
+    "dryRun": true  // Preview without writing files
+  }
+}
+
+// System entity (no TenantId)
+{
+  "type": "entity",
+  "name": "GlobalConfig",
+  "options": {
+    "isSystemEntity": true,
+    "tablePrefix": "cfg_"
+  }
+}
+
+// Unit tests for a service
+{
+  "type": "test",
+  "name": "Product"
+}
+\`\`\`
+
+**Common Options:**
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| \`dryRun\` | boolean | false | Preview generated code without writing files |
+| \`isSystemEntity\` | boolean | false | Create system entity (no TenantId) |
+| \`tablePrefix\` | string | "ref_" | Domain prefix for table name |
+| \`schema\` | string | "core" | Database schema ("core" or "extensions") |
+| \`namespace\` | string | auto | Custom namespace |
+| \`baseEntity\` | string | - | Base entity to extend |
+
+**Feature-Specific Options:**
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| \`clientExtension\` | boolean | false | Use 'extensions' schema + 'ext_' prefix |
+| \`skipService\` | boolean | false | Skip service layer generation |
+| \`skipController\` | boolean | false | Skip API controller generation |
+| \`skipComponent\` | boolean | false | Skip React component generation |
+| \`withTests\` | boolean | false | Generate unit tests (xUnit + Moq) |
+| \`withDtos\` | boolean | false | Generate DTOs (Create, Update, Response) |
+| \`withValidation\` | boolean | false | Generate FluentValidation validators |
+| \`withRepository\` | boolean | false | Generate repository pattern |
+| \`entityProperties\` | array | - | Define entity properties for DTOs |
+
+### Suggest Migration
+
+Generate migration names following conventions:
+
+\`\`\`json
+{
+  "description": "Add User Profiles",
+  "context": "core",       // optional: core or extensions
+  "version": "1.2.0"       // optional: auto-detected from existing
+}
+\`\`\`
+
+Output: \`core_v1.2.0_001_AddUserProfiles\`
+
+### Validate Conventions
+
+Run specific or all checks:
+
+\`\`\`json
+{
+  "checks": ["tables", "migrations", "services", "namespaces", "entities", "tenants"]
+}
+\`\`\`
+
+**Check Types:**
+
+| Check | Validates |
+|-------|-----------|
+| \`tables\` | Schema specification, domain prefixes |
+| \`migrations\` | Naming convention, version ordering |
+| \`services\` | Interface implementation pattern |
+| \`namespaces\` | Layer namespace structure |
+| \`entities\` | BaseEntity/SystemEntity inheritance, factory methods |
+| \`tenants\` | ITenantEntity implementation, TenantId consistency |
 `;
 }
 
 // src/resources/project-info.ts
-import path9 from "path";
+import path10 from "path";
 var projectInfoResourceTemplate = {
   uri: "smartstack://project",
   name: "SmartStack Project Info",
@@ -2627,16 +4469,16 @@ async function getProjectInfoResource(config) {
   lines.push("```");
   lines.push(`${projectInfo.name}/`);
   if (structure.domain) {
-    lines.push(`\u251C\u2500\u2500 ${path9.basename(structure.domain)}/          # Domain layer (entities)`);
+    lines.push(`\u251C\u2500\u2500 ${path10.basename(structure.domain)}/          # Domain layer (entities)`);
   }
   if (structure.application) {
-    lines.push(`\u251C\u2500\u2500 ${path9.basename(structure.application)}/     # Application layer (services)`);
+    lines.push(`\u251C\u2500\u2500 ${path10.basename(structure.application)}/     # Application layer (services)`);
   }
   if (structure.infrastructure) {
-    lines.push(`\u251C\u2500\u2500 ${path9.basename(structure.infrastructure)}/  # Infrastructure (EF Core)`);
+    lines.push(`\u251C\u2500\u2500 ${path10.basename(structure.infrastructure)}/  # Infrastructure (EF Core)`);
   }
   if (structure.api) {
-    lines.push(`\u251C\u2500\u2500 ${path9.basename(structure.api)}/             # API layer (controllers)`);
+    lines.push(`\u251C\u2500\u2500 ${path10.basename(structure.api)}/             # API layer (controllers)`);
   }
   if (structure.web) {
     lines.push(`\u2514\u2500\u2500 web/smartstack-web/      # React frontend`);
@@ -2649,8 +4491,8 @@ async function getProjectInfoResource(config) {
     lines.push("| Project | Path |");
     lines.push("|---------|------|");
     for (const csproj of projectInfo.csprojFiles) {
-      const name = path9.basename(csproj, ".csproj");
-      const relativePath = path9.relative(projectPath, csproj);
+      const name = path10.basename(csproj, ".csproj");
+      const relativePath = path10.relative(projectPath, csproj);
       lines.push(`| ${name} | \`${relativePath}\` |`);
     }
     lines.push("");
@@ -2660,10 +4502,10 @@ async function getProjectInfoResource(config) {
       cwd: structure.migrations,
       ignore: ["*.Designer.cs"]
     });
-    const migrations = migrationFiles.map((f) => path9.basename(f)).filter((f) => !f.includes("ModelSnapshot") && !f.includes(".Designer.")).sort();
+    const migrations = migrationFiles.map((f) => path10.basename(f)).filter((f) => !f.includes("ModelSnapshot") && !f.includes(".Designer.")).sort();
     lines.push("## EF Core Migrations");
     lines.push("");
-    lines.push(`**Location**: \`${path9.relative(projectPath, structure.migrations)}\``);
+    lines.push(`**Location**: \`${path10.relative(projectPath, structure.migrations)}\``);
     lines.push(`**Total Migrations**: ${migrations.length}`);
     lines.push("");
     if (migrations.length > 0) {
@@ -2698,11 +4540,11 @@ async function getProjectInfoResource(config) {
   lines.push("dotnet build");
   lines.push("");
   lines.push("# Run API");
-  lines.push(`cd ${structure.api ? path9.relative(projectPath, structure.api) : "SmartStack.Api"}`);
+  lines.push(`cd ${structure.api ? path10.relative(projectPath, structure.api) : "SmartStack.Api"}`);
   lines.push("dotnet run");
   lines.push("");
   lines.push("# Run frontend");
-  lines.push(`cd ${structure.web ? path9.relative(projectPath, structure.web) : "web/smartstack-web"}`);
+  lines.push(`cd ${structure.web ? path10.relative(projectPath, structure.web) : "web/smartstack-web"}`);
   lines.push("npm run dev");
   lines.push("");
   lines.push("# Create migration");
@@ -2725,7 +4567,7 @@ async function getProjectInfoResource(config) {
 }
 
 // src/resources/api-endpoints.ts
-import path10 from "path";
+import path11 from "path";
 var apiEndpointsResourceTemplate = {
   uri: "smartstack://api/",
   name: "SmartStack API Endpoints",
@@ -2750,7 +4592,7 @@ async function getApiEndpointsResource(config, endpointFilter) {
 }
 async function parseController(filePath, _rootPath) {
   const content = await readText(filePath);
-  const fileName = path10.basename(filePath, ".cs");
+  const fileName = path11.basename(filePath, ".cs");
   const controllerName = fileName.replace("Controller", "");
   const endpoints = [];
   const routeMatch = content.match(/\[Route\s*\(\s*"([^"]+)"\s*\)\]/);
@@ -2897,7 +4739,7 @@ function getMethodEmoji(method) {
 }
 
 // src/resources/db-schema.ts
-import path11 from "path";
+import path12 from "path";
 var dbSchemaResourceTemplate = {
   uri: "smartstack://schema/",
   name: "SmartStack Database Schema",
@@ -2987,7 +4829,7 @@ async function parseEntity(filePath, rootPath, _config) {
     tableName,
     properties,
     relationships,
-    file: path11.relative(rootPath, filePath)
+    file: path12.relative(rootPath, filePath)
   };
 }
 async function enrichFromConfigurations(entities, infrastructurePath, _config) {
@@ -3132,6 +4974,231 @@ function formatSchema(entities, filter, _config) {
   return lines.join("\n");
 }
 
+// src/resources/entities.ts
+import path13 from "path";
+var entitiesResourceTemplate = {
+  uri: "smartstack://entities/",
+  name: "SmartStack Entities",
+  description: "Quick reference list of all domain entities with tenant-awareness and table prefixes. Use smartstack://entities/{name} for details.",
+  mimeType: "text/markdown"
+};
+async function getEntitiesResource(config, entityFilter) {
+  const structure = await findSmartStackStructure(config.smartstack.projectPath);
+  if (!structure.domain) {
+    return "# SmartStack Entities\n\nNo domain project found.";
+  }
+  const entities = [];
+  const entityFiles = await findEntityFiles(structure.domain);
+  for (const file of entityFiles) {
+    const entity = await parseEntitySummary(file, structure.root, config);
+    if (entity) {
+      entities.push(entity);
+    }
+  }
+  entities.sort((a, b) => {
+    if (a.tablePrefix !== b.tablePrefix) {
+      return a.tablePrefix.localeCompare(b.tablePrefix);
+    }
+    return a.name.localeCompare(b.name);
+  });
+  const filteredEntities = entityFilter ? entities.filter(
+    (e) => e.name.toLowerCase().includes(entityFilter.toLowerCase()) || e.tableName.toLowerCase().includes(entityFilter.toLowerCase()) || e.tablePrefix.toLowerCase().includes(entityFilter.toLowerCase())
+  ) : entities;
+  return formatEntities(filteredEntities, entityFilter, config);
+}
+async function parseEntitySummary(filePath, rootPath, config) {
+  const content = await readText(filePath);
+  const classMatch = content.match(/public\s+(?:class|record)\s+(\w+)(?:\s*:\s*([^{]+))?/);
+  if (!classMatch) return null;
+  const entityName = classMatch[1];
+  const inheritance = classMatch[2]?.trim() || "";
+  if (entityName.endsWith("Dto") || entityName.endsWith("Command") || entityName.endsWith("Query") || entityName.endsWith("Handler") || entityName.endsWith("Configuration") || entityName.endsWith("Service") || entityName.endsWith("Validator") || entityName.endsWith("Exception")) {
+    return null;
+  }
+  const baseClassMatch = inheritance.match(/^(\w+)/);
+  const baseClass = baseClassMatch ? baseClassMatch[1] : "Unknown";
+  const isSystemEntity = baseClass === "SystemEntity" || inheritance.includes("ISystemEntity") || content.includes("// System entity") || !content.includes("TenantId");
+  const isTenantAware = content.includes("TenantId") && (content.includes("public Guid TenantId") || content.includes("public required Guid TenantId"));
+  const hasCode = content.includes("public string Code") || content.includes("public required string Code") || content.includes("public string? Code");
+  const hasSoftDelete = content.includes("IsDeleted") || inheritance.includes("ISoftDeletable") || baseClass === "BaseEntity";
+  const hasRowVersion = content.includes("RowVersion") || inheritance.includes("IHasRowVersion") || baseClass === "BaseEntity";
+  const { tableName, tablePrefix, schema } = inferTableInfo(entityName, config);
+  return {
+    name: entityName,
+    tableName,
+    tablePrefix,
+    schema,
+    isTenantAware,
+    isSystemEntity,
+    baseClass,
+    hasCode,
+    hasSoftDelete,
+    hasRowVersion,
+    file: filePath,
+    relativePath: path13.relative(rootPath, filePath)
+  };
+}
+function inferTableInfo(entityName, config) {
+  const prefixMapping = {
+    // Authentication & Authorization
+    "User": "auth_",
+    "Role": "auth_",
+    "Permission": "auth_",
+    "UserRole": "auth_",
+    "RolePermission": "auth_",
+    "RefreshToken": "auth_",
+    // Navigation
+    "NavigationItem": "nav_",
+    "NavigationMenu": "nav_",
+    "Page": "nav_",
+    // AI
+    "Prompt": "ai_",
+    "Completion": "ai_",
+    "Model": "ai_",
+    "Conversation": "ai_",
+    // Configuration
+    "Setting": "cfg_",
+    "Configuration": "cfg_",
+    // Workflow
+    "Workflow": "wkf_",
+    "WorkflowStep": "wkf_",
+    "WorkflowInstance": "wkf_",
+    // Support
+    "Ticket": "support_",
+    "TicketComment": "support_",
+    // Entra (Azure AD)
+    "EntraUser": "entra_",
+    "EntraGroup": "entra_",
+    // Licensing
+    "License": "lic_",
+    "Subscription": "lic_",
+    // Tenant
+    "Tenant": "tenant_",
+    "TenantUser": "tenant_",
+    "TenantUserRole": "tenant_",
+    "TenantInvitation": "tenant_",
+    "Organisation": "tenant_",
+    // Localization
+    "Translation": "loc_",
+    "Language": "loc_"
+  };
+  let tablePrefix = "ref_";
+  for (const [pattern, prefix] of Object.entries(prefixMapping)) {
+    if (entityName === pattern || entityName.startsWith(pattern)) {
+      tablePrefix = prefix;
+      break;
+    }
+  }
+  const validPrefixes = config.conventions.tablePrefixes;
+  if (!validPrefixes.includes(tablePrefix)) {
+    tablePrefix = "ref_";
+  }
+  const tableName = `${tablePrefix}${pluralize(entityName)}`;
+  const schema = config.conventions.schemas.platform;
+  return { tableName, tablePrefix, schema };
+}
+function pluralize(name) {
+  if (name.endsWith("y") && !/[aeiou]y$/i.test(name)) {
+    return name.slice(0, -1) + "ies";
+  }
+  if (name.endsWith("s") || name.endsWith("x") || name.endsWith("ch") || name.endsWith("sh")) {
+    return name + "es";
+  }
+  return name + "s";
+}
+function formatEntities(entities, filter, config) {
+  const lines = [];
+  lines.push("# SmartStack Entities");
+  lines.push("");
+  if (filter) {
+    lines.push(`> Filtered by: \`${filter}\``);
+    lines.push("");
+  }
+  if (entities.length === 0) {
+    lines.push("No entities found matching the criteria.");
+    return lines.join("\n");
+  }
+  const tenantAwareCount = entities.filter((e) => e.isTenantAware).length;
+  const systemCount = entities.filter((e) => e.isSystemEntity).length;
+  const prefixes = [...new Set(entities.map((e) => e.tablePrefix))];
+  lines.push("## Summary");
+  lines.push("");
+  lines.push(`- **Total Entities**: ${entities.length}`);
+  lines.push(`- **Tenant-Aware**: ${tenantAwareCount}`);
+  lines.push(`- **System Entities**: ${systemCount}`);
+  lines.push(`- **Table Prefixes Used**: ${prefixes.join(", ")}`);
+  lines.push("");
+  lines.push("## Quick Reference");
+  lines.push("");
+  lines.push("| Entity | Table | Tenant | Code | SoftDel | Base |");
+  lines.push("|--------|-------|--------|------|---------|------|");
+  for (const entity of entities) {
+    const tenantIcon = entity.isTenantAware ? "\u2705" : entity.isSystemEntity ? "\u{1F512}" : "\u274C";
+    const codeIcon = entity.hasCode ? "\u2705" : "\u274C";
+    const softDelIcon = entity.hasSoftDelete ? "\u2705" : "\u274C";
+    lines.push(
+      `| ${entity.name} | \`${entity.tableName}\` | ${tenantIcon} | ${codeIcon} | ${softDelIcon} | ${entity.baseClass} |`
+    );
+  }
+  lines.push("");
+  lines.push("## By Domain");
+  lines.push("");
+  const byPrefix = /* @__PURE__ */ new Map();
+  for (const entity of entities) {
+    const list = byPrefix.get(entity.tablePrefix) || [];
+    list.push(entity);
+    byPrefix.set(entity.tablePrefix, list);
+  }
+  const prefixNames = {
+    "auth_": "Authentication & Authorization",
+    "nav_": "Navigation",
+    "ai_": "AI & Prompts",
+    "cfg_": "Configuration",
+    "wkf_": "Workflows",
+    "support_": "Support",
+    "entra_": "Microsoft Entra",
+    "lic_": "Licensing",
+    "tenant_": "Multi-Tenant",
+    "loc_": "Localization",
+    "ref_": "Reference Data",
+    "usr_": "User Data"
+  };
+  for (const [prefix, prefixEntities] of byPrefix) {
+    const domainName = prefixNames[prefix] || prefix;
+    lines.push(`### ${domainName} (\`${prefix}\`)`);
+    lines.push("");
+    for (const entity of prefixEntities) {
+      const badges = [];
+      if (entity.isTenantAware) badges.push("tenant-aware");
+      if (entity.isSystemEntity) badges.push("system");
+      if (entity.hasCode) badges.push("has-code");
+      lines.push(`- **${entity.name}** \u2192 \`${entity.tableName}\``);
+      if (badges.length > 0) {
+        lines.push(`  - ${badges.map((b) => `\`${b}\``).join(" ")}`);
+      }
+      lines.push(`  - File: \`${entity.relativePath}\``);
+    }
+    lines.push("");
+  }
+  lines.push("## Conventions");
+  lines.push("");
+  lines.push("| Property | Convention |");
+  lines.push("|----------|------------|");
+  lines.push(`| Schema | \`${config.conventions.schemas.platform}\` |`);
+  lines.push(`| Valid Prefixes | ${config.conventions.tablePrefixes.map((p) => `\`${p}\``).join(", ")} |`);
+  lines.push("| Tenant-aware | Must have `TenantId` (GUID, NOT NULL) |");
+  lines.push("| System entity | No `TenantId`, used for platform-level data |");
+  lines.push("| Code field | Lowercase, unique per tenant (or globally for system) |");
+  lines.push("");
+  lines.push("## Legend");
+  lines.push("");
+  lines.push("- \u2705 = Feature present");
+  lines.push("- \u274C = Feature absent");
+  lines.push("- \u{1F512} = System entity (no tenant scope)");
+  lines.push("");
+  return lines.join("\n");
+}
+
 // src/server.ts
 async function createServer() {
   const config = await getConfig();
@@ -3154,7 +5221,8 @@ async function createServer() {
         validateConventionsTool,
         checkMigrationsTool,
         scaffoldExtensionTool,
-        apiDocsTool
+        apiDocsTool,
+        suggestMigrationTool
       ]
     };
   });
@@ -3177,6 +5245,9 @@ async function createServer() {
         case "api_docs":
           result = await handleApiDocs(args, config);
           break;
+        case "suggest_migration":
+          result = await handleSuggestMigration(args, config);
+          break;
         default:
           throw new Error(`Unknown tool: ${name}`);
       }
@@ -3210,7 +5281,8 @@ async function createServer() {
         conventionsResourceTemplate,
         projectInfoResourceTemplate,
         apiEndpointsResourceTemplate,
-        dbSchemaResourceTemplate
+        dbSchemaResourceTemplate,
+        entitiesResourceTemplate
       ]
     };
   });
@@ -3230,6 +5302,11 @@ async function createServer() {
       } else if (uri.startsWith("smartstack://schema/")) {
         const table = uri.replace("smartstack://schema/", "");
         content = await getDbSchemaResource(config, table);
+      } else if (uri.startsWith("smartstack://entities/")) {
+        const entityFilter = uri.replace("smartstack://entities/", "");
+        content = await getEntitiesResource(config, entityFilter || void 0);
+      } else if (uri === "smartstack://entities") {
+        content = await getEntitiesResource(config);
       } else {
         throw new Error(`Unknown resource: ${uri}`);
       }