@beignet/cli 0.0.1 → 0.0.4

package/src/inspect.ts

@@ -1,5 +1,11 @@
 import { readdir, readFile, stat, writeFile } from "node:fs/promises";
 import path from "node:path";
+import { fileURLToPath } from "node:url";
+import {
+  type ProviderPackageMetadata,
+  parseProviderPackageMetadata,
+} from "@beignet/core/providers";
+import { createPainter } from "./ansi.js";
 import {
   type BeignetConfig,
   directoryPath,
@@ -8,6 +14,11 @@ import {
   type ResolvedBeignetConfig,
   resolveConfig,
 } from "./config.js";
+import {
+  formatGithubAnnotation,
+  type GithubAnnotationSeverity,
+} from "./github-annotations.js";
+import { getCliVersion } from "./version.js";
 
 type InspectAppOptions = {
   cwd?: string;
@@ -24,33 +35,62 @@ type HttpMethod =
   | "HEAD"
   | "OPTIONS";
 
+/**
+ * Contract discovered by app inspection.
+ */
 export type InspectedContract = {
   exportName: string;
   file: string;
   method: HttpMethod;
   path: string;
+  metadata?: InspectedContractMetadata;
+};
+
+type InspectedContractMetadata = {
+  authRequired: boolean;
+  authorizationAbility?: string;
+  auditRequired: boolean;
+  catalogErrors: InspectedCatalogErrorRef[];
 };
 
+type InspectedCatalogErrorRef = {
+  key: string;
+  catalog: string;
+  catalogKey: string;
+};
+
+/**
+ * Route handler mapping discovered by app inspection.
+ */
 export type InspectedRoute = InspectedContract & {
   handlerFile?: string;
   handlerExport?: HttpMethod;
   handlerSource: "next-route" | "route-local" | "missing";
 };
 
+/**
+ * Doctor diagnostic produced by app inspection.
+ */
 export type InspectDiagnostic = {
-  severity: "error" | "warning";
+  severity: "error" | "warning" | "hint";
   code: string;
   message: string;
   file?: string;
   contract?: string;
 };
 
+/**
+ * Automatic doctor fix that was applied.
+ */
 export type InspectFix = {
   code: string;
   message: string;
   file: string;
 };
 
+/**
+ * Detected app convention and missing convention files.
+ */
 export type InspectConvention = {
   kind: "standard" | "next" | "custom";
   nextLayout: boolean;
@@ -60,7 +100,11 @@ export type InspectConvention = {
   missingResourceGenerator: string[];
 };
 
+/**
+ * Full app inspection result.
+ */
 export type InspectAppResult = {
+  schemaVersion: 1;
   targetDir: string;
   config: ResolvedBeignetConfig;
   strict: boolean;
@@ -138,6 +182,7 @@ export async function inspectApp(
   );
 
   return {
+    schemaVersion: 1,
     targetDir,
     config,
     strict: Boolean(options.strict),
@@ -161,21 +206,41 @@ export async function applyDoctorFixes(
     : await loadBeignetConfig(targetDir, files);
   const convention = inspectConvention(files, config);
   const contracts = await readContracts(targetDir, files, config);
+  const routeFiles = files.filter(
+    (file) =>
+      file.startsWith(`${directoryPath(config.paths.routes)}/`) &&
+      file.endsWith("/route.ts"),
+  );
+  const routeExports = await readRouteExports(targetDir, routeFiles, config);
+  const matchedRoutes = matchRoutes(contracts, routeExports);
   const fixes: InspectFix[] = [];
 
   const packageFix = await fixMissingTestScript(targetDir, files, convention);
   if (packageFix) fixes.push(packageFix);
 
+  const routeGroupFix = await fixUnregisteredRouteGroups(
+    targetDir,
+    files,
+    config,
+  );
+  if (routeGroupFix) fixes.push(routeGroupFix);
+
   const openApiFix = await fixDirectOpenApiArrayDrift(
     targetDir,
+    files,
     config,
+    convention,
     contracts,
+    matchedRoutes,
   );
   if (openApiFix) fixes.push(openApiFix);
 
   return fixes;
 }
 
+/**
+ * Format inspected routes as a CLI table.
+ */
 export function formatRoutes(result: InspectAppResult): string {
   if (result.routes.length === 0) {
     return `No Beignet routes found in ${result.targetDir}`;
@@ -197,7 +262,14 @@ export function formatRoutes(result: InspectAppResult): string {
   ]);
 }
 
-export function formatDoctor(result: InspectAppResult): string {
+/**
+ * Format doctor diagnostics and applied fixes for CLI output.
+ */
+export function formatDoctor(
+  result: InspectAppResult,
+  options: { color?: boolean } = {},
+): string {
+  const paint = createPainter(options.color);
   const fixLines =
     result.fixes.length === 0
       ? []
@@ -207,7 +279,7 @@ export function formatDoctor(result: InspectAppResult): string {
           }:`,
           "",
           ...result.fixes.map(
-            (fix) => `FIXED ${fix.code} ${fix.file}
+            (fix) => `${paint("FIXED", "green")} ${fix.code} ${fix.file}
   ${fix.message}`,
           ),
           "",
@@ -219,18 +291,80 @@ export function formatDoctor(result: InspectAppResult): string {
     );
   }
 
-  return [
+  const groups = [
+    {
+      severity: "error",
+      header: "Errors",
+      label: paint("ERROR", "red"),
+    },
+    {
+      severity: "warning",
+      header: "Warnings",
+      label: paint("WARNING", "yellow"),
+    },
+    {
+      severity: "hint",
+      header: "Hints",
+      label: paint("HINT", "cyan"),
+    },
+  ] as const;
+
+  const lines = [
     ...fixLines,
     `Found ${result.diagnostics.length} Beignet issue${
       result.diagnostics.length === 1 ? "" : "s"
     } in ${result.targetDir}:`,
-    "",
-    ...result.diagnostics.map((diagnostic) => {
-      const location = diagnostic.file ? ` ${diagnostic.file}` : "";
-      return `${diagnostic.severity.toUpperCase()} ${diagnostic.code}${location}
+  ];
+
+  for (const group of groups) {
+    const diagnostics = result.diagnostics.filter(
+      (diagnostic) => diagnostic.severity === group.severity,
+    );
+    if (diagnostics.length === 0) continue;
+
+    lines.push("", paint(`${group.header}:`, "bold"), "");
+    lines.push(
+      ...diagnostics.map((diagnostic) => {
+        const location = diagnostic.file ? ` ${diagnostic.file}` : "";
+        return `${group.label} ${diagnostic.code}${location}
   ${diagnostic.message}`;
-    }),
-  ].join("\n");
+      }),
+    );
+  }
+
+  lines.push("", formatDoctorFooter(result));
+  return lines.join("\n");
+}
+
+function formatDoctorFooter(result: InspectAppResult): string {
+  const count = (severity: InspectDiagnostic["severity"]) =>
+    result.diagnostics.filter((diagnostic) => diagnostic.severity === severity)
+      .length;
+  const footer = `${count("error")} error(s), ${count("warning")} warning(s), ${count("hint")} hint(s)`;
+
+  return result.strict ? `${footer} (strict: warnings fail)` : footer;
+}
+
+/**
+ * Format doctor diagnostics as GitHub Actions annotations.
+ */
+export function formatDoctorGithub(result: InspectAppResult): string {
+  return result.diagnostics
+    .map((diagnostic) =>
+      formatGithubAnnotation({
+        severity: githubAnnotationSeverity(diagnostic.severity),
+        file: diagnostic.file,
+        message: `${diagnostic.code}: ${diagnostic.message}`,
+      }),
+    )
+    .join("\n");
+}
+
+function githubAnnotationSeverity(
+  severity: InspectDiagnostic["severity"],
+): GithubAnnotationSeverity {
+  if (severity === "hint") return "notice";
+  return severity;
 }
 
 async function assertDirectory(targetDir: string): Promise<void> {
@@ -344,13 +478,14 @@ function hasRequirement(files: string[], requirement: string): boolean {
 function parseContracts(source: string, file: string): InspectedContract[] {
   const contracts: InspectedContract[] = [];
   const groupPrefixes = parseContractGroupPrefixes(source);
+  const groupErrorRefs = parseContractGroupErrorRefs(source);
   const exportRegex =
     /(?:^|\n)export const\s+([A-Za-z_$][\w$]*)\s*=([\s\S]*?)(?=\nexport const\s+[A-Za-z_$][\w$]*\s*=|$)/g;
 
   for (const exportMatch of source.matchAll(exportRegex)) {
     const block = exportMatch[2];
     const methodMatch =
-      /([A-Za-z_$][\w$]*)\s*\.\s*(get|post|put|patch|delete|head|options)\(\s*["']([^"']+)["']\s*\)/.exec(
+      /([A-Za-z_$][\w$]*)(?:\s*\.\s*[A-Za-z_$][\w$]*\([^)]*\))*\s*\.\s*(get|post|put|patch|delete|head|options)\(\s*["']([^"']+)["']\s*\)/.exec(
         block,
       );
     if (methodMatch) {
@@ -361,6 +496,10 @@ function parseContracts(source: string, file: string): InspectedContract[] {
       contracts.push({
         exportName: exportMatch[1],
         file,
+        metadata: parseContractMetadata(
+          block,
+          groupErrorRefs.get(receiver) ?? [],
+        ),
         method: methodMatch[2].toUpperCase() as HttpMethod,
         path: routePath,
       });
@@ -372,6 +511,7 @@ function parseContracts(source: string, file: string): InspectedContract[] {
       contracts.push({
         exportName: exportMatch[1],
         file,
+        metadata: parseContractMetadata(block),
         method: directContract.method,
         path: normalizeContractPath(directContract.path),
       });
@@ -381,10 +521,44 @@ function parseContracts(source: string, file: string): InspectedContract[] {
   return contracts;
 }
 
+function parseContractMetadata(
+  block: string,
+  inheritedCatalogErrors: InspectedCatalogErrorRef[] = [],
+): InspectedContractMetadata | undefined {
+  const authRequired = /\bauth\s*:\s*["']required["']/.test(block);
+  const authorizationAbility =
+    /\bauthorization\s*:\s*\{[\s\S]*?\bability\s*:\s*["']([^"']+)["']/.exec(
+      block,
+    )?.[1];
+  const auditRequired =
+    /\baudit\s*:\s*["']required["']/.test(block) ||
+    /\bauditRequired\s*:\s*true\b/.test(block);
+  const catalogErrors = dedupeCatalogErrorRefs([
+    ...inheritedCatalogErrors,
+    ...parseCatalogErrorRefs(block),
+  ]);
+
+  if (
+    !authRequired &&
+    !authorizationAbility &&
+    !auditRequired &&
+    catalogErrors.length === 0
+  ) {
+    return undefined;
+  }
+
+  return {
+    authRequired,
+    authorizationAbility,
+    auditRequired,
+    catalogErrors,
+  };
+}
+
 function parseDirectContract(
   block: string,
 ): { method: HttpMethod; path: string } | undefined {
-  const configMatch = /createContract\s*\(\s*\{([\s\S]*?)\}\s*\)/.exec(block);
+  const configMatch = /defineContract\s*\(\s*\{([\s\S]*?)\}\s*\)/.exec(block);
   if (!configMatch) return undefined;
 
   const configSource = configMatch[1];
@@ -436,11 +610,59 @@ function parseContractGroupPrefixes(source: string): Map<string, string> {
   return prefixes;
 }
 
+function parseContractGroupErrorRefs(
+  source: string,
+): Map<string, InspectedCatalogErrorRef[]> {
+  const assignments = [
+    ...source.matchAll(
+      /(?:^|\n)(?:export\s+)?const\s+([A-Za-z_$][\w$]*)\s*=\s*([\s\S]*?);/g,
+    ),
+  ].map((match) => ({
+    name: match[1],
+    expression: match[2],
+  }));
+  const groupErrors = new Map<string, InspectedCatalogErrorRef[]>();
+
+  let changed = true;
+  while (changed) {
+    changed = false;
+    for (const assignment of assignments) {
+      if (groupErrors.has(assignment.name)) continue;
+
+      const baseErrors = baseGroupErrors(assignment.expression, groupErrors);
+      if (baseErrors === undefined) continue;
+
+      groupErrors.set(
+        assignment.name,
+        dedupeCatalogErrorRefs([
+          ...baseErrors,
+          ...parseCatalogErrorRefs(assignment.expression),
+        ]),
+      );
+      changed = true;
+    }
+  }
+
+  return groupErrors;
+}
+
+function baseGroupErrors(
+  expression: string,
+  groupErrors: Map<string, InspectedCatalogErrorRef[]>,
+): InspectedCatalogErrorRef[] | undefined {
+  if (expression.includes("defineContractGroup(")) return [];
+
+  const baseMatch = /^\s*([A-Za-z_$][\w$]*)\b/.exec(expression);
+  if (!baseMatch) return undefined;
+
+  return groupErrors.get(baseMatch[1]);
+}
+
 function baseGroupPrefix(
   expression: string,
   prefixes: Map<string, string>,
 ): string | undefined {
-  if (expression.includes("createContractGroup(")) return "";
+  if (expression.includes("defineContractGroup(")) return "";
 
   const baseMatch = /^\s*([A-Za-z_$][\w$]*)\b/.exec(expression);
   if (!baseMatch) return undefined;
@@ -454,6 +676,184 @@ function prefixCalls(expression: string): string[] {
   );
 }
 
+function parseCatalogErrorRefs(source: string): InspectedCatalogErrorRef[] {
+  return dedupeCatalogErrorRefs(
+    objectArgumentBodies(source, /\.errors\s*\(/g).flatMap((body) =>
+      [...body.matchAll(errorCatalogRefRegex)].map((match) => ({
+        key: match[1],
+        catalog: match[2],
+        catalogKey: match[3],
+      })),
+    ),
+  );
+}
+
+const errorCatalogRefRegex =
+  /(?:^|[,{])\s*([A-Za-z_$][\w$]*)\s*:\s*([A-Za-z_$][\w$]*)\s*\.\s*([A-Za-z_$][\w$]*)/g;
+
+function parseErrorCatalogKeys(source: string): Set<string> {
+  const keys = new Set<string>();
+  const catalogBodies = objectArgumentBodies(source, /\bdefineErrors\s*\(/g);
+
+  for (const body of catalogBodies) {
+    if (/\.\.\.\s*httpErrors\b/.test(body)) {
+      for (const key of httpErrorCatalogKeys) keys.add(key);
+    }
+    for (const key of topLevelObjectKeys(body)) keys.add(key);
+  }
+
+  return keys;
+}
+
+const httpErrorCatalogKeys = [
+  "BadRequest",
+  "Unauthorized",
+  "Forbidden",
+  "NotFound",
+  "Conflict",
+  "IdempotencyConflict",
+  "IdempotencyInProgress",
+  "TooManyRequests",
+  "UnprocessableEntity",
+  "ValidationError",
+  "InternalServerError",
+] as const;
+
+function objectArgumentBodies(source: string, callPattern: RegExp): string[] {
+  const bodies: string[] = [];
+  const pattern = new RegExp(callPattern.source, callPattern.flags);
+
+  for (const match of source.matchAll(pattern)) {
+    const callIndex = match.index ?? 0;
+    const openParen = source.indexOf("(", callIndex);
+    if (openParen === -1) continue;
+
+    const objectStart = source.indexOf("{", openParen);
+    if (objectStart === -1) continue;
+
+    const objectSource = balancedObjectSource(source, objectStart);
+    if (!objectSource) continue;
+
+    bodies.push(objectSource.slice(1, -1));
+  }
+
+  return bodies;
+}
+
+function balancedObjectSource(
+  source: string,
+  startIndex: number,
+): string | undefined {
+  if (source[startIndex] !== "{") return undefined;
+
+  let depth = 0;
+  let quote: '"' | "'" | "`" | undefined;
+  let escaped = false;
+
+  for (let index = startIndex; index < source.length; index += 1) {
+    const char = source[index];
+
+    if (quote) {
+      if (escaped) {
+        escaped = false;
+        continue;
+      }
+      if (char === "\\") {
+        escaped = true;
+        continue;
+      }
+      if (char === quote) quote = undefined;
+      continue;
+    }
+
+    if (char === '"' || char === "'" || char === "`") {
+      quote = char;
+      continue;
+    }
+
+    if (char === "{") {
+      depth += 1;
+      continue;
+    }
+
+    if (char === "}") {
+      depth -= 1;
+      if (depth === 0) return source.slice(startIndex, index + 1);
+    }
+  }
+
+  return undefined;
+}
+
+function topLevelObjectKeys(body: string): string[] {
+  const keys: string[] = [];
+  let depth = 0;
+  let quote: '"' | "'" | "`" | undefined;
+  let escaped = false;
+
+  for (let index = 0; index < body.length; index += 1) {
+    const char = body[index];
+
+    if (quote) {
+      if (escaped) {
+        escaped = false;
+        continue;
+      }
+      if (char === "\\") {
+        escaped = true;
+        continue;
+      }
+      if (char === quote) quote = undefined;
+      continue;
+    }
+
+    if (char === '"' || char === "'" || char === "`") {
+      quote = char;
+      continue;
+    }
+
+    if (char === "{" || char === "[" || char === "(") {
+      depth += 1;
+      continue;
+    }
+
+    if (char === "}" || char === "]" || char === ")") {
+      depth = Math.max(0, depth - 1);
+      continue;
+    }
+
+    if (depth !== 0) continue;
+
+    const identifier = /^[A-Za-z_$][\w$]*/.exec(body.slice(index));
+    if (!identifier) continue;
+
+    const name = identifier[0];
+    const next = body.slice(index + name.length).match(/^\s*:/);
+    if (next) keys.push(name);
+
+    index += name.length - 1;
+  }
+
+  return keys;
+}
+
+function dedupeCatalogErrorRefs(
+  refs: InspectedCatalogErrorRef[],
+): InspectedCatalogErrorRef[] {
+  const seen = new Set<string>();
+  const deduped: InspectedCatalogErrorRef[] = [];
+
+  for (const ref of refs) {
+    const key = `${ref.key}:${ref.catalog}:${ref.catalogKey}`;
+    if (seen.has(key)) continue;
+
+    seen.add(key);
+    deduped.push(ref);
+  }
+
+  return deduped;
+}
+
 function joinContractPaths(prefix: string, routePath: string): string {
   if (!prefix) return normalizeContractPath(routePath);
   const segments = [
@@ -577,6 +977,30 @@ function parseNamedImports(
   return imports;
 }
 
+function parseNamedImportSources(
+  source: string,
+): Map<string, { importedName: string; sourcePath: string }> {
+  const imports = new Map<
+    string,
+    { importedName: string; sourcePath: string }
+  >();
+  const importRegex = /import\s+\{([^}]+)\}\s+from\s+["']([^"']+)["']/g;
+
+  for (const match of source.matchAll(importRegex)) {
+    for (const member of match[1].split(",")) {
+      const parsed = parseImportMember(member);
+      if (!parsed) continue;
+
+      imports.set(parsed.localName, {
+        importedName: parsed.importedName,
+        sourcePath: match[2],
+      });
+    }
+  }
+
+  return imports;
+}
+
 function parseImportMember(
   member: string,
 ): { importedName: string; localName: string } | undefined {
@@ -603,6 +1027,33 @@ function parseImportMember(
   return undefined;
 }
 
+function sourceFileFromImport(
+  sourcePath: string,
+  importerFile = "index.ts",
+  files?: string[],
+): string | undefined {
+  const resolveCandidate = (candidate: string) => {
+    if (path.extname(candidate)) return candidate;
+
+    const candidates = [`${candidate}.ts`, `${candidate}/index.ts`];
+    return files
+      ? candidates.find((file) => files.includes(file))
+      : candidates[0];
+  };
+
+  if (sourcePath.startsWith("@/")) {
+    return resolveCandidate(sourcePath.slice("@/".length));
+  }
+
+  if (sourcePath.startsWith(".")) {
+    return resolveCandidate(
+      normalizePath(path.join(path.dirname(importerFile), sourcePath)),
+    );
+  }
+
+  return undefined;
+}
+
 function contractFileFromImport(
   sourcePath: string,
   config: ResolvedBeignetConfig,
@@ -766,7 +1217,7 @@ async function inspectDiagnostics(
   if (!convention.nextLayout) {
     diagnostics.push({
       severity: "warning",
-      code: "CK_APP_LAYOUT_NOT_FOUND",
+      code: "BEIGNET_APP_LAYOUT_NOT_FOUND",
       message: `This directory does not match the standard Beignet app layout. CLI inspection expects ${directoryPath(config.paths.contracts)}/, ${directoryPath(config.paths.routes)}/, and ${config.paths.server}. Missing: ${convention.missingNextLayout.join(", ")}. Add the missing app files or configure their paths in beignet.config.ts.`,
     });
   }
@@ -775,7 +1226,7 @@ async function inspectDiagnostics(
     if (route.handlerSource !== "missing") continue;
     diagnostics.push({
       severity: "error",
-      code: "CK_ROUTE_MISSING",
+      code: "BEIGNET_ROUTE_MISSING",
       file: route.file,
       contract: route.exportName,
       message: `${route.exportName} (${route.method} ${route.path}) has no matching Next route handler. Add ${methodArticle(route.method)} ${route.method} export to ${directoryPath(config.paths.routes)}/[[...path]]/route.ts or a matching route file, or remove the unused contract.`,
@@ -788,7 +1239,14 @@ async function inspectDiagnostics(
 
   diagnostics.push(
     ...(await inspectPackageScripts(targetDir, files, convention)),
-    ...(await inspectOpenApiDrift(targetDir, files, config, contracts)),
+    ...(await inspectOpenApiDrift(
+      targetDir,
+      files,
+      config,
+      convention,
+      contracts,
+      matchedRoutes,
+    )),
     ...(await inspectFeatureRouteRegistration(
       targetDir,
       files,
@@ -796,127 +1254,2121 @@ async function inspectDiagnostics(
       convention,
       contracts,
     )),
+    ...(await inspectRouteErrorCatalogDrift(
+      targetDir,
+      files,
+      config,
+      convention,
+      contracts,
+      strict,
+    )),
+    ...(await inspectCanonicalConformance(
+      targetDir,
+      files,
+      config,
+      convention,
+      strict,
+    )),
+    ...(await inspectVersionSkew(targetDir, files)),
+    ...(await inspectProviderMetadataDrift(targetDir, files, convention)),
     ...(await inspectPortProviderDrift(targetDir, files, config, convention)),
-    ...(await inspectResourceSlices(
+    ...(await inspectProviderRegistrationDrift(
+      targetDir,
+      files,
+      config,
+      convention,
+    )),
+    ...(await inspectDatabaseLifecycleDrift(
       targetDir,
       files,
       config,
       convention,
       strict,
     )),
-  );
-
-  return dedupeDiagnostics(diagnostics);
-}
-
-async function inspectPortProviderDrift(
-  targetDir: string,
-  files: string[],
-  config: ResolvedBeignetConfig,
-  convention: InspectConvention,
-): Promise<InspectDiagnostic[]> {
-  if (!convention.resourceGenerator) return [];
-
+    ...(await inspectAuthzAuditDrift(
+      targetDir,
+      files,
+      config,
+      convention,
+      contracts,
+    )),
+    ...(await inspectServerlessFootguns(targetDir, files)),
+    ...(await inspectProductionReadiness(targetDir, files, config, convention)),
+    ...(await inspectFeatureArtifactDrift(
+      targetDir,
+      files,
+      config,
+      convention,
+    )),
+    ...(await inspectResourceSlices(
+      targetDir,
+      files,
+      config,
+      convention,
+      strict,
+    )),
+  );
+
+  return dedupeDiagnostics(diagnostics);
+}
+
+async function inspectCanonicalConformance(
+  targetDir: string,
+  files: string[],
+  config: ResolvedBeignetConfig,
+  convention: InspectConvention,
+  strict: boolean,
+): Promise<InspectDiagnostic[]> {
+  if (!strict || !convention.resourceGenerator) return [];
+
+  const diagnostics: InspectDiagnostic[] = [];
+  const serverDir = directoryPath(path.dirname(config.paths.server));
+  const routeRegistryFile = `${serverDir}/routes.ts`;
+  const providerRegistryFile = `${serverDir}/providers.ts`;
+  const packageJson = await readPackageJson(targetDir, files);
+  const installedPackages = installedPackageNames(packageJson);
+  const featuresPath = directoryPath(config.paths.features);
+  const hasClientSurface =
+    files.some(
+      (file) =>
+        file.startsWith(`${featuresPath}/`) && file.includes("/components/"),
+    ) ||
+    files.some((file) => file.startsWith("client/")) ||
+    [
+      "@beignet/react-query",
+      "@beignet/react-hook-form",
+      "@beignet/react-uploads",
+      "@beignet/nuqs",
+    ].some((packageName) => installedPackages.has(packageName));
+
+  const requiredFiles = [
+    {
+      file: config.paths.appContext,
+      reason:
+        "Beignet apps should define the shared AppContext type once in app-context.ts.",
+    },
+    {
+      file: config.paths.server,
+      reason:
+        "server/index.ts should compose ports, providers, hooks, routes, and request context.",
+    },
+    {
+      file: routeRegistryFile,
+      reason:
+        "server/routes.ts should own the central route registry and exported contract list.",
+    },
+    {
+      file: providerRegistryFile,
+      reason:
+        "server/providers.ts should own provider registration, even when the provider list is small.",
+    },
+    {
+      file: config.paths.infrastructurePorts,
+      reason:
+        "infra/app-ports.ts should wire concrete app ports for the selected runtime.",
+    },
+  ];
+
+  if (hasClientSurface) {
+    requiredFiles.push({
+      file: "client/index.ts",
+      reason:
+        "client/index.ts should own the typed client and frontend adapter setup.",
+    });
+  }
+
+  if (
+    installedPackages.has("@beignet/react-hook-form") ||
+    files.includes("client/forms.ts")
+  ) {
+    requiredFiles.push({
+      file: "client/forms.ts",
+      reason:
+        "client/forms.ts should own React Hook Form adapter setup when form helpers are used.",
+    });
+  }
+
+  for (const required of requiredFiles) {
+    if (files.includes(required.file)) continue;
+    diagnostics.push({
+      severity: "warning",
+      code: "BEIGNET_CANONICAL_FILE_MISSING",
+      file: required.file,
+      message: `${required.file} is missing. ${required.reason}`,
+    });
+  }
+
+  const sourceCache = new Map<string, string>();
+  const appContextSource = files.includes(config.paths.appContext)
+    ? await readCachedSource(targetDir, config.paths.appContext, sourceCache)
+    : "";
+  const expectedContextFields = canonicalContextFields(appContextSource);
+
+  if (files.includes(routeRegistryFile)) {
+    const routeRegistrySource = await readCachedSource(
+      targetDir,
+      routeRegistryFile,
+      sourceCache,
+    );
+
+    if (
+      !importsAppContext(routeRegistrySource, routeRegistryFile, config, files)
+    ) {
+      diagnostics.push({
+        severity: "warning",
+        code: "BEIGNET_ROUTE_REGISTRY_APP_CONTEXT",
+        file: routeRegistryFile,
+        message: `${routeRegistryFile} should import type { AppContext } from ${config.paths.appContext} so the central route registry uses the app-wide context type.`,
+      });
+    }
+
+    if (
+      !/\bexport\s+const\s+routes\s*=\s*defineRoutes\s*<\s*AppContext\s*>/.test(
+        routeRegistrySource,
+      )
+    ) {
+      diagnostics.push({
+        severity: "warning",
+        code: "BEIGNET_ROUTE_REGISTRY_ROUTES_EXPORT",
+        file: routeRegistryFile,
+        message: `${routeRegistryFile} should export routes with defineRoutes<AppContext>([...]) so route registration follows the canonical Beignet path.`,
+      });
+    }
+
+    if (
+      !/\bexport\s+const\s+contracts\s*=\s*contractsFromRoutes\s*\(\s*routes\s*\)/.test(
+        routeRegistrySource,
+      )
+    ) {
+      diagnostics.push({
+        severity: "warning",
+        code: "BEIGNET_ROUTE_REGISTRY_CONTRACTS_EXPORT",
+        file: routeRegistryFile,
+        message: `${routeRegistryFile} should export contracts = contractsFromRoutes(routes) so OpenAPI, typed clients, and devtools derive from the central route registry.`,
+      });
+    }
+  }
+
+  if (files.includes(config.paths.server)) {
+    const serverSource = await readCachedSource(
+      targetDir,
+      config.paths.server,
+      sourceCache,
+    );
+    const importedRouteRegistry = routeRegistryFileFromServerSource(
+      serverSource,
+      config.paths.server,
+      files,
+    );
+
+    if (importedRouteRegistry !== routeRegistryFile) {
+      diagnostics.push({
+        severity: "warning",
+        code: "BEIGNET_SERVER_ROUTE_REGISTRY",
+        file: config.paths.server,
+        message: `${config.paths.server} should import routes from ./${path.basename(routeRegistryFile, ".ts")} so server setup uses the central route registry.`,
+      });
+    }
+
+    if (!importsAppContext(serverSource, config.paths.server, config, files)) {
+      diagnostics.push({
+        severity: "warning",
+        code: "BEIGNET_SERVER_APP_CONTEXT",
+        file: config.paths.server,
+        message: `${config.paths.server} should import type { AppContext } from ${config.paths.appContext} and thread that context through createNextServer and hooks.`,
+      });
+    }
+
+    // Apps may keep the context blueprint in a sibling server/context.ts
+    // (defineServerContext) instead of inline in the server file.
+    const serverContextFile = `${serverDir}/context.ts`;
+    const serverContextSource = files.includes(serverContextFile)
+      ? await readCachedSource(targetDir, serverContextFile, sourceCache)
+      : "";
+    const contextBlueprintFile = files.includes(serverContextFile)
+      ? serverContextFile
+      : config.paths.server;
+    const contextBlueprintSource = `${serverSource}\n${serverContextSource}`;
+
+    for (const field of expectedContextFields) {
+      if (
+        new RegExp(`\\b${escapeRegExp(field)}\\s*[:,]`).test(
+          contextBlueprintSource,
+        )
+      ) {
+        continue;
+      }
+      diagnostics.push({
+        severity: "warning",
+        code: "BEIGNET_CONTEXT_FIELD_MISSING",
+        file: contextBlueprintFile,
+        message: `${contextBlueprintFile} context factories do not appear to return ${field}. Keep the canonical AppContext shape aligned with app-context.ts.`,
+      });
+    }
+  }
+
+  const featureRoutesPath = `${featuresPath}/`;
+  for (const file of files) {
+    if (!file.startsWith(featureRoutesPath) || !file.endsWith("/routes.ts")) {
+      continue;
+    }
+
+    const source = await readCachedSource(targetDir, file, sourceCache);
+    if (!source.includes("defineRouteGroup")) continue;
+
+    if (!importsAppContext(source, file, config, files)) {
+      diagnostics.push({
+        severity: "warning",
+        code: "BEIGNET_FEATURE_ROUTE_APP_CONTEXT",
+        file,
+        message: `${file} should import type { AppContext } from ${config.paths.appContext} so feature routes use the app-wide context type.`,
+      });
+    }
+
+    if (!/defineRouteGroup\s*<\s*AppContext\s*>/.test(source)) {
+      diagnostics.push({
+        severity: "warning",
+        code: "BEIGNET_FEATURE_ROUTE_GROUP_CONTEXT",
+        file,
+        message: `${file} should call defineRouteGroup<AppContext>(...) for ordinary feature route groups, or defineRouteGroup<AppContext>()({ ... }) when group-level hooks enrich ctx.`,
+      });
+    }
+  }
+
+  for (const file of files) {
+    if (
+      file === config.paths.appContext ||
+      !file.endsWith(".ts") ||
+      file.endsWith(".d.ts")
+    ) {
+      continue;
+    }
+
+    const source = await readCachedSource(targetDir, file, sourceCache);
+    if (!/\b(?:type|interface)\s+AppContext\b/.test(source)) continue;
+
+    diagnostics.push({
+      severity: "warning",
+      code: "BEIGNET_APP_CONTEXT_REDECLARED",
+      file,
+      message: `${file} declares AppContext locally. Import AppContext from "@/app-context" so routes, hooks, use cases, jobs, schedules, and tests share one context model.`,
+    });
+  }
+
+  return diagnostics;
+}
+
+function canonicalContextFields(appContextSource: string): string[] {
+  const fields = ["requestId", "ports"];
+  for (const field of ["actor", "auth", "gate"]) {
+    if (appContextSource.includes(`${field}:`)) fields.push(field);
+  }
+  return fields;
+}
+
+function importsAppContext(
+  source: string,
+  importerFile: string,
+  config: ResolvedBeignetConfig,
+  files: string[],
+): boolean {
+  const importRegex =
+    /import\s+(?:type\s+)?\{([^}]+)\}\s+from\s+["']([^"']+)["']/g;
+
+  for (const match of source.matchAll(importRegex)) {
+    const sourceFile = sourceFileFromImport(match[2], importerFile, files);
+    if (sourceFile !== config.paths.appContext) continue;
+
+    for (const member of match[1].split(",")) {
+      const parsed = parseImportMember(member);
+      if (
+        parsed?.importedName === "AppContext" &&
+        parsed.localName === "AppContext"
+      ) {
+        return true;
+      }
+    }
+  }
+
+  return false;
+}
+
+async function inspectAuthzAuditDrift(
+  targetDir: string,
+  files: string[],
+  config: ResolvedBeignetConfig,
+  convention: InspectConvention,
+  contracts: InspectedContract[],
+): Promise<InspectDiagnostic[]> {
+  if (!convention.resourceGenerator) return [];
+
+  const diagnostics: InspectDiagnostic[] = [];
+  const featuresPath = directoryPath(config.paths.features);
+  const sourceCache = new Map<string, string>();
+
+  for (const contract of contracts) {
+    const feature = featureNameFromContractFile(contract.file, config);
+    if (!feature) continue;
+
+    const ability = contract.metadata?.authorizationAbility;
+    if (ability) {
+      const policyFile = `${featuresPath}/${feature}/policy.ts`;
+      if (!files.includes(policyFile)) {
+        diagnostics.push({
+          severity: "warning",
+          code: "BEIGNET_AUTHZ_POLICY_MISSING",
+          file: contract.file,
+          contract: contract.exportName,
+          message: `${contract.exportName} declares authorization ability "${ability}", but ${policyFile} is missing. Add a feature policy for the ability or remove stale authorization metadata from the contract.`,
+        });
+      } else {
+        const policySource = await readCachedSource(
+          targetDir,
+          policyFile,
+          sourceCache,
+        );
+        if (!policySource.includes(ability)) {
+          diagnostics.push({
+            severity: "warning",
+            code: "BEIGNET_AUTHZ_POLICY_DRIFT",
+            file: policyFile,
+            contract: contract.exportName,
+            message: `${contract.exportName} declares authorization ability "${ability}", but ${policyFile} does not mention that ability. Keep contract metadata aligned with the feature policy.`,
+          });
+        }
+      }
+
+      const policyTestFiles = featureTestFiles(files, featuresPath, feature, {
+        policyOnly: true,
+      });
+      if (
+        policyTestFiles.length === 0 ||
+        !(await anyFileContains(
+          targetDir,
+          policyTestFiles,
+          ability,
+          sourceCache,
+        ))
+      ) {
+        diagnostics.push({
+          severity: "warning",
+          code: "BEIGNET_AUTHZ_POLICY_TEST_MISSING",
+          file:
+            policyTestFiles[0] ??
+            `${featuresPath}/${feature}/tests/policy.test.ts`,
+          contract: contract.exportName,
+          message: `${contract.exportName} declares authorization ability "${ability}", but no feature policy test appears to cover it. Add policy matrix coverage so authorization metadata, policy behavior, and tests stay aligned.`,
+        });
+      }
+    }
+
+    if (contract.metadata?.auditRequired) {
+      const featureSourceFiles = featureRuntimeFiles(
+        files,
+        featuresPath,
+        feature,
+      );
+      if (
+        featureSourceFiles.length === 0 ||
+        !(await anyFileMatches(
+          targetDir,
+          featureSourceFiles,
+          /\baudit\.record\s*\(/,
+          sourceCache,
+        ))
+      ) {
+        diagnostics.push({
+          severity: "warning",
+          code: "BEIGNET_AUDIT_WRITE_MISSING",
+          file: contract.file,
+          contract: contract.exportName,
+          message: `${contract.exportName} declares audit-required metadata, but no feature runtime file appears to record through ctx.ports.audit or a transaction audit port. Record the audited business action in the use case, listener, job, schedule, or upload completion hook.`,
+        });
+      }
+
+      const testFiles = featureTestFiles(files, featuresPath, feature);
+      if (
+        testFiles.length === 0 ||
+        !(await anyFileMatches(
+          targetDir,
+          testFiles,
+          /\b(assertAuditEntry|assertAuditEntries|audit\.entries)\b/,
+          sourceCache,
+        ))
+      ) {
+        diagnostics.push({
+          severity: "warning",
+          code: "BEIGNET_AUDIT_TEST_MISSING",
+          file: testFiles[0] ?? `${featuresPath}/${feature}/tests/`,
+          contract: contract.exportName,
+          message: `${contract.exportName} declares audit-required metadata, but no feature test appears to assert audit behavior. Add an audit assertion for the sensitive workflow so contract metadata and durable activity logging stay aligned.`,
+        });
+      }
+    }
+  }
+
+  return diagnostics;
+}
+
+async function inspectRouteErrorCatalogDrift(
+  targetDir: string,
+  files: string[],
+  config: ResolvedBeignetConfig,
+  convention: InspectConvention,
+  contracts: InspectedContract[],
+  strict: boolean,
+): Promise<InspectDiagnostic[]> {
+  if (!convention.resourceGenerator) return [];
+
+  const diagnostics: InspectDiagnostic[] = [];
+  const featuresPath = directoryPath(config.paths.features);
+  const sharedErrorsFile = `${featuresPath}/shared/errors.ts`;
+  const sourceCache = new Map<string, string>();
+  const sharedErrorKeys = files.includes(sharedErrorsFile)
+    ? parseErrorCatalogKeys(
+        await readCachedSource(targetDir, sharedErrorsFile, sourceCache),
+      )
+    : undefined;
+  const declaredByFeature = new Map<string, Set<string>>();
+  const contractFiles = new Set(contracts.map((contract) => contract.file));
+  const sharedCatalogBindingsByFile = new Map<string, Set<string>>();
+
+  for (const file of contractFiles) {
+    const source = await readCachedSource(targetDir, file, sourceCache);
+    sharedCatalogBindingsByFile.set(
+      file,
+      sharedErrorCatalogBindings(source, file, files, sharedErrorsFile),
+    );
+  }
+
+  for (const contract of contracts) {
+    const catalogErrors = contract.metadata?.catalogErrors ?? [];
+    if (catalogErrors.length === 0) continue;
+
+    const feature = featureNameFromContractFile(contract.file, config);
+    if (feature) {
+      const declared = declaredByFeature.get(feature) ?? new Set<string>();
+      for (const error of catalogErrors) declared.add(error.key);
+      declaredByFeature.set(feature, declared);
+    }
+
+    const sharedBindings =
+      sharedCatalogBindingsByFile.get(contract.file) ?? new Set<string>();
+    for (const error of catalogErrors) {
+      if (!sharedBindings.has(error.catalog)) continue;
+
+      if (!sharedErrorKeys) {
+        diagnostics.push({
+          severity: "error",
+          code: "BEIGNET_ROUTE_ERROR_CATALOG_MISSING",
+          file: sharedErrorsFile,
+          contract: contract.exportName,
+          message: `${contract.exportName} declares route-owned error ${error.key} from ${sharedErrorsFile}, but the shared error catalog file is missing. Add ${sharedErrorsFile} or remove the stale contract .errors(...) entry.`,
+        });
+        continue;
+      }
+
+      if (!sharedErrorKeys.has(error.catalogKey)) {
+        diagnostics.push({
+          severity: "error",
+          code: "BEIGNET_ROUTE_ERROR_CATALOG_ENTRY_MISSING",
+          file: sharedErrorsFile,
+          contract: contract.exportName,
+          message: `${contract.exportName} declares route-owned error ${error.key}, but ${sharedErrorsFile} does not define ${error.catalogKey}. Add it to defineErrors(...) or remove the stale contract .errors(...) entry.`,
+        });
+      }
+    }
+  }
+
+  for (const feature of featureNamesFromContracts(contracts, config)) {
+    const featureRuntime = featureErrorRuntimeFiles(
+      files,
+      featuresPath,
+      feature,
+    );
+    const declared = declaredByFeature.get(feature) ?? new Set<string>();
+    const used = await featureAppErrorUses(
+      targetDir,
+      featureRuntime,
+      sourceCache,
+    );
+
+    for (const [errorName, file] of used) {
+      if (sharedErrorKeys && !sharedErrorKeys.has(errorName)) {
+        diagnostics.push({
+          severity: "error",
+          code: "BEIGNET_APP_ERROR_CATALOG_ENTRY_MISSING",
+          file: sharedErrorsFile,
+          message: `${file} creates appError("${errorName}"), but ${sharedErrorsFile} does not define ${errorName}. Add it to the shared error catalog or fix the stale appError(...) call.`,
+        });
+      }
+
+      if (!declared.has(errorName)) {
+        diagnostics.push({
+          severity: "warning",
+          code: "BEIGNET_APP_ERROR_CONTRACT_MISSING",
+          file,
+          message: `${file} creates appError("${errorName}"), but no ${feature} contract declares ${errorName} with .errors(...). Declare the route-owned error on the contract that can surface it, or move the non-HTTP error out of route-backed workflows.`,
+        });
+      }
+    }
+
+    if (!strict) continue;
+
+    for (const errorName of declared) {
+      if (!isFeatureOwnedErrorName(errorName, feature)) continue;
+      if (used.has(errorName)) continue;
+
+      diagnostics.push({
+        severity: "warning",
+        code: "BEIGNET_ROUTE_ERROR_UNUSED",
+        file: `${featuresPath}/${feature}/contracts.ts`,
+        message: `${feature} contracts declare ${errorName}, but no ${feature} runtime file appears to create appError("${errorName}"). Remove the stale .errors(...) entry or add runtime coverage for the route-owned error.`,
+      });
+    }
+  }
+
+  return diagnostics;
+}
+
+type ProviderDoctorRule = {
+  packageName: string;
+  displayName: string;
+  tokens: readonly string[];
+  appPorts?: readonly { name: string; type: string }[];
+  requiredEnv?: readonly string[];
+  registrationSeverity?: "warning" | "hint";
+};
+
+type ProviderPackageMetadataSource = {
+  packageName: string;
+  file: string;
+  metadata: unknown;
+};
+
+async function inspectProductionReadiness(
+  targetDir: string,
+  files: string[],
+  config: ResolvedBeignetConfig,
+  convention: InspectConvention,
+): Promise<InspectDiagnostic[]> {
+  if (!convention.resourceGenerator) return [];
+
+  const diagnostics: InspectDiagnostic[] = [];
+  const sourceCache = new Map<string, string>();
+  const packageJson = await readPackageJson(targetDir, files);
+  const installedPackages = installedPackageNames(packageJson);
+  const providerDoctorRules = await providerDoctorRulesForInstalledPackages(
+    targetDir,
+    packageJson,
+  );
+  const configFiles = operationalConfigFiles(files, config);
+
+  for (const file of files) {
+    if (!file.endsWith(".ts") || file.endsWith(".test.ts")) continue;
+
+    const source = await readCachedSource(targetDir, file, sourceCache);
+
+    if (
+      containsCallExpression(source, "createDevtoolsRoute") &&
+      /\benabled\s*:\s*true\b/.test(source) &&
+      !/\bauthorize\s*:/.test(source)
+    ) {
+      diagnostics.push({
+        severity: "warning",
+        code: "BEIGNET_DEVTOOLS_ROUTE_EXPOSED",
+        file,
+        message: `${file} enables devtools with enabled: true and no authorize callback. Keep devtools disabled in production or add app-owned authorization before exposing diagnostic data.`,
+      });
+    }
+
+    if (
+      file.startsWith("app/api/cron/") &&
+      file.endsWith("/route.ts") &&
+      !/\bCRON_SECRET\b/.test(source) &&
+      !/\bcreateOutboxDrainRoute\s*\(/.test(source)
+    ) {
+      diagnostics.push({
+        severity: "warning",
+        code: "BEIGNET_CRON_SECRET_MISSING",
+        file,
+        message: `${file} looks like a cron route that does not reference CRON_SECRET. Protect cron entrypoints with a shared secret or a framework helper such as createOutboxDrainRoute(...).`,
+      });
+    }
+
+    if (
+      isFeatureUploadDefinition(file, config) &&
+      containsCallExpression(source, "defineUpload") &&
+      !/\bmaxSizeBytes\s*:/.test(source)
+    ) {
+      diagnostics.push({
+        severity: "warning",
+        code: "BEIGNET_UPLOAD_SIZE_LIMIT_MISSING",
+        file,
+        message: `${file} defines an upload without maxSizeBytes. Add an explicit size limit so upload behavior is predictable before deployment.`,
+      });
+    }
+
+    if (
+      isRouteServerOrInfraFile(file, config) &&
+      containsCallExpression(source, "createCorsHooks") &&
+      /\bcredentials\s*:\s*true\b/.test(source) &&
+      /(?:\borigin\b|\borigins\b)\s*:\s*(?:["']\*["']|\[\s*["']\*["'])/.test(
+        source,
+      )
+    ) {
+      diagnostics.push({
+        severity: "warning",
+        code: "BEIGNET_CORS_CREDENTIALS_WILDCARD",
+        file,
+        message: `${file} enables credentialed CORS with a wildcard origin. Use an explicit origin allow-list so cookies and authorization headers are not exposed to arbitrary origins.`,
+      });
+    }
+  }
+
+  for (const provider of providerDoctorRules) {
+    if (!installedPackages.has(provider.packageName)) continue;
+    for (const envVar of provider.requiredEnv ?? []) {
+      if (await anyFileContains(targetDir, configFiles, envVar, sourceCache)) {
+        continue;
+      }
+      diagnostics.push({
+        severity: "warning",
+        code: "BEIGNET_PROVIDER_ENV_MISSING",
+        file: "package.json",
+        message: `${provider.packageName} is installed, but ${envVar} is not mentioned in app env/config files. Add the expected environment variable or remove the unused provider package.`,
+      });
+    }
+  }
+
+  if (installedPackages.has("@beignet/provider-auth-better-auth")) {
+    if (!hasBetterAuthRoute(files, config)) {
+      diagnostics.push({
+        severity: "warning",
+        code: "BEIGNET_AUTH_ROUTE_MISSING",
+        file: directoryPath(config.paths.routes),
+        message:
+          "@beignet/provider-auth-better-auth is installed, but no Better Auth route was found. Expose Better Auth through app/api/auth/[...all]/route.ts or remove the unused auth provider.",
+      });
+    }
+
+    if (
+      !(await anyFileContains(
+        targetDir,
+        configFiles,
+        "BETTER_AUTH_TRUSTED_ORIGINS",
+        sourceCache,
+      ))
+    ) {
+      diagnostics.push({
+        severity: "warning",
+        code: "BEIGNET_AUTH_TRUSTED_ORIGINS_MISSING",
+        file: "package.json",
+        message:
+          "@beignet/provider-auth-better-auth is installed, but BETTER_AUTH_TRUSTED_ORIGINS is not mentioned in app env/config files. Add it before deploying across multiple origins or document why the app is single-origin only.",
+      });
+    }
+  }
+
+  return diagnostics;
+}
+
+// Local-dev ranges such as the generated-app conformance vendoring point each
+// @beignet/* package at a different path on purpose, so they are exempt from
+// the declared-range comparison. Their installed versions still participate in
+// the installed-version comparison.
+const localOnlyRangePrefixes = ["file:", "link:", "workspace:"];
+
+async function inspectVersionSkew(
+  targetDir: string,
+  files: string[],
+): Promise<InspectDiagnostic[]> {
+  const packageJson = await readPackageJson(targetDir, files);
+  const declaredRanges = new Map<string, string>();
+  for (const section of [
+    packageJson?.dependencies,
+    packageJson?.devDependencies,
+  ]) {
+    for (const [name, range] of Object.entries(section ?? {})) {
+      if (name.startsWith("@beignet/")) declaredRanges.set(name, range);
+    }
+  }
+  if (declaredRanges.size === 0) return [];
+
+  const diagnostics: InspectDiagnostic[] = [];
+  const comparableRanges = [...declaredRanges].filter(
+    ([, range]) =>
+      !localOnlyRangePrefixes.some((prefix) => range.startsWith(prefix)),
+  );
+  const distinctRanges = new Set(comparableRanges.map(([, range]) => range));
+  if (distinctRanges.size > 1) {
+    const pairs = comparableRanges
+      .map(([name, range]) => `${name}@${range}`)
+      .join(", ");
+    diagnostics.push({
+      severity: "warning",
+      code: "BEIGNET_VERSION_SKEW",
+      file: "package.json",
+      message: `package.json declares mixed @beignet/* version ranges: ${pairs}. Align all @beignet/* packages to one version; they release together.`,
+    });
+  }
+
+  const installedVersions = await readInstalledBeignetVersions(targetDir);
+  const distinctInstalled = new Set(installedVersions.values());
+  if (distinctInstalled.size > 1) {
+    const pairs = [...installedVersions]
+      .map(([name, version]) => `${name}@${version}`)
+      .join(", ");
+    diagnostics.push({
+      severity: "warning",
+      code: "BEIGNET_VERSION_SKEW",
+      file: "package.json",
+      message: `node_modules contains mixed @beignet/* versions: ${pairs}. Align the declared @beignet/* ranges to one version, then reinstall so a single version is installed.`,
+    });
+  }
+
+  const coreVersion = installedVersions.get("@beignet/core");
+  const cliVersion = getCliVersion();
+  if (
+    coreVersion !== undefined &&
+    cliVersion !== "0.0.0" &&
+    coreVersion !== cliVersion
+  ) {
+    diagnostics.push({
+      severity: "hint",
+      code: "BEIGNET_CLI_VERSION_SKEW",
+      file: "package.json",
+      message: `This CLI is ${cliVersion} but the app uses @beignet/core ${coreVersion}. Prefer the app-local CLI via \`bun beignet\` so the CLI and framework versions stay aligned.`,
+    });
+  }
+
+  return diagnostics;
+}
+
+async function readInstalledBeignetVersions(
+  targetDir: string,
+): Promise<Map<string, string>> {
+  const scopeDir = path.join(targetDir, "node_modules", "@beignet");
+  let entries: string[];
+  try {
+    entries = await readdir(scopeDir);
+  } catch {
+    return new Map();
+  }
+
+  const versions = new Map<string, string>();
+  for (const entry of entries.sort()) {
+    if (entry.startsWith(".")) continue;
+    const installedPackageJson = await readJsonIfExists<{ version?: string }>(
+      path.join(scopeDir, entry, "package.json"),
+    );
+    if (installedPackageJson?.version) {
+      versions.set(`@beignet/${entry}`, installedPackageJson.version);
+    }
+  }
+
+  return versions;
+}
+
+async function inspectProviderMetadataDrift(
+  targetDir: string,
+  files: string[],
+  convention: InspectConvention,
+): Promise<InspectDiagnostic[]> {
+  if (!convention.resourceGenerator) return [];
+
+  const packageJson = await readPackageJson(targetDir, files);
+  const packageNames = [...installedPackageNames(packageJson)];
+  const diagnostics: InspectDiagnostic[] = [];
+
+  for (const packageName of packageNames) {
+    const source = await readProviderPackageMetadataSource(
+      targetDir,
+      packageName,
+    );
+    if (!source) continue;
+
+    const result = parseProviderPackageMetadata(source.metadata);
+    if (result.success) continue;
+
+    diagnostics.push({
+      severity: "warning",
+      code: "BEIGNET_PROVIDER_METADATA_INVALID",
+      file: diagnosticPackageJsonFile(targetDir, source.file),
+      message: `${packageName} declares invalid beignet.provider metadata: ${formatProviderMetadataIssues(result.issues)}. Fix the provider package metadata or remove the package until it publishes a valid manifest.`,
+    });
+  }
+
+  return diagnostics;
+}
+
+async function inspectProviderRegistrationDrift(
+  targetDir: string,
+  files: string[],
+  config: ResolvedBeignetConfig,
+  convention: InspectConvention,
+): Promise<InspectDiagnostic[]> {
+  if (!convention.resourceGenerator) return [];
+
+  const diagnostics: InspectDiagnostic[] = [];
+  const packageJson = await readPackageJson(targetDir, files);
+  const installedPackages = installedPackageNames(packageJson);
+  const providerDoctorRules = await providerDoctorRulesForInstalledPackages(
+    targetDir,
+    packageJson,
+  );
+  const providerFiles = serverProviderFiles(files, config);
+  const sourceCache = new Map<string, string>();
+  const providerSource = (
+    await Promise.all(
+      providerFiles.map((file) =>
+        readCachedSource(targetDir, file, sourceCache),
+      ),
+    )
+  ).join("\n");
+  const providerListSource = extractProviderListSource(providerSource);
+  const providerEntries =
+    providerListSource === undefined
+      ? []
+      : providerListEntries(providerListSource);
+
+  for (const provider of providerDoctorRules) {
+    const severity = provider.registrationSeverity;
+    if (severity === undefined) continue;
+    if (!installedPackages.has(provider.packageName)) continue;
+    if (
+      provider.tokens.some((token) =>
+        providerEntries.some((entry) => entry.includes(token)),
+      )
+    ) {
+      continue;
+    }
+
+    diagnostics.push({
+      severity,
+      code: "BEIGNET_PROVIDER_REGISTRATION_MISSING",
+      file: providerFiles[0] ?? config.paths.server,
+      message:
+        severity === "hint"
+          ? `${provider.packageName} is installed, but ${provider.displayName} is not registered in server/providers.ts. Register ${registrationTokenHint(provider.tokens)} in the exported providers array or remove the dependency.`
+          : `${provider.packageName} is installed, but ${provider.displayName} is not registered in server/providers.ts. Add it to the exported providers array or remove the unused package.`,
+    });
+  }
+
+  const drizzleIndex = findProviderEntryIndex(providerEntries, [
+    "drizzleTursoProvider",
+    "createDrizzleTursoProvider",
+  ]);
+  const appDatabaseProviderIndex = findProviderEntryIndex(providerEntries, [
+    "starterDatabaseProvider",
+    "exampleDatabaseProvider",
+    "twitterDatabaseProvider",
+    "databaseProvider",
+  ]);
+  if (
+    appDatabaseProviderIndex >= 0 &&
+    drizzleIndex >= 0 &&
+    appDatabaseProviderIndex < drizzleIndex
+  ) {
+    diagnostics.push({
+      severity: "warning",
+      code: "BEIGNET_PROVIDER_ORDER",
+      file: providerFiles[0] ?? config.paths.server,
+      message:
+        "An app database provider is registered before createDrizzleTursoProvider(...). Register the Drizzle/Turso provider first so app-owned database wiring can read ctx.ports.db during setup.",
+    });
+  }
+
+  return diagnostics;
+}
+
+function isFeatureUploadDefinition(
+  file: string,
+  config: ResolvedBeignetConfig,
+): boolean {
+  const featuresPath = directoryPath(config.paths.features);
+  return new RegExp(
+    `^${escapeRegExp(featuresPath)}/[^/]+/uploads/[^/]+\\.ts$`,
+  ).test(file);
+}
+
+function operationalConfigFiles(
+  files: string[],
+  config: ResolvedBeignetConfig,
+): string[] {
+  return files.filter((file) => {
+    if (file === ".env.example") return true;
+    if (file === "drizzle.config.ts") return true;
+    if (file === "lib/env.ts" || file === "lib/better-auth.ts") return true;
+    if (isInfraOrServerFile(file, config) && file.endsWith(".ts")) return true;
+    return false;
+  });
+}
+
+async function readPackageJson(
+  targetDir: string,
+  files: string[],
+): Promise<
+  | {
+      dependencies?: Record<string, string>;
+      devDependencies?: Record<string, string>;
+      peerDependencies?: Record<string, string>;
+    }
+  | undefined
+> {
+  if (!files.includes("package.json")) return undefined;
+
+  return JSON.parse(
+    await readFile(path.join(targetDir, "package.json"), "utf8"),
+  );
+}
+
+async function providerDoctorRulesForInstalledPackages(
+  targetDir: string,
+  packageJson:
+    | {
+        dependencies?: Record<string, string>;
+        devDependencies?: Record<string, string>;
+        peerDependencies?: Record<string, string>;
+      }
+    | undefined,
+): Promise<ProviderDoctorRule[]> {
+  const packageNames = [...installedPackageNames(packageJson)];
+  const rules = await Promise.all(
+    packageNames.map(async (packageName) => {
+      const source = await readProviderPackageMetadataSource(
+        targetDir,
+        packageName,
+      );
+      if (!source) return undefined;
+      const result = parseProviderPackageMetadata(source.metadata);
+      if (!result.success) return undefined;
+      return providerDoctorRuleFromMetadata(packageName, result.metadata);
+    }),
+  );
+
+  return rules.filter((rule): rule is ProviderDoctorRule => Boolean(rule));
+}
+
+async function readProviderPackageMetadataSource(
+  targetDir: string,
+  packageName: string,
+): Promise<ProviderPackageMetadataSource | undefined> {
+  for (const candidate of providerPackageJsonCandidates(
+    targetDir,
+    packageName,
+  )) {
+    const packageJson = await readJsonIfExists<{
+      beignet?: { provider?: unknown };
+    }>(candidate);
+    const metadata = packageJson?.beignet?.provider;
+    if (metadata !== undefined) {
+      return { packageName, file: candidate, metadata };
+    }
+  }
+
+  return undefined;
+}
+
+function providerPackageJsonCandidates(
+  targetDir: string,
+  packageName: string,
+): string[] {
+  const candidates = [
+    path.join(
+      targetDir,
+      "node_modules",
+      ...packageName.split("/"),
+      "package.json",
+    ),
+  ];
+
+  if (packageName.startsWith("@beignet/")) {
+    candidates.push(
+      path.resolve(
+        // import.meta.dir is Bun-only; the published bin also runs under
+        // plain Node, where only import.meta.url is available.
+        path.dirname(fileURLToPath(import.meta.url)),
+        "../../..",
+        "packages",
+        packageName.slice("@beignet/".length),
+        "package.json",
+      ),
+    );
+  }
+
+  return candidates;
+}
+
+async function readJsonIfExists<T>(file: string): Promise<T | undefined> {
+  try {
+    return JSON.parse(await readFile(file, "utf8")) as T;
+  } catch (error) {
+    if (
+      error instanceof Error &&
+      "code" in error &&
+      (error as { code?: string }).code === "ENOENT"
+    ) {
+      return undefined;
+    }
+    throw error;
+  }
+}
+
+function providerDoctorRuleFromMetadata(
+  packageName: string,
+  metadata: ProviderPackageMetadata,
+): ProviderDoctorRule {
+  const registration = metadata.registration;
+
+  return {
+    packageName,
+    displayName: metadata.displayName ?? packageName,
+    tokens: registration?.tokens ?? [],
+    appPorts: metadata.appPorts ?? [],
+    requiredEnv: metadata.requiredEnv ?? [],
+    registrationSeverity:
+      registration?.severity ??
+      (registration?.required === true ? "warning" : undefined),
+  };
+}
+
+function registrationTokenHint(tokens: readonly string[]): string {
+  const token = tokens[0];
+  if (!token) return "the provider";
+  return token.startsWith("create") ? `${token}()` : token;
+}
+
+function diagnosticPackageJsonFile(targetDir: string, file: string): string {
+  const relative = normalizePath(path.relative(targetDir, file));
+  if (relative.startsWith("../")) return "package.json";
+  return relative;
+}
+
+function formatProviderMetadataIssues(
+  issues: readonly { path: string; message: string }[],
+): string {
+  return issues.map((issue) => `${issue.path} ${issue.message}`).join("; ");
+}
+
+function installedPackageNames(
+  packageJson:
+    | {
+        dependencies?: Record<string, string>;
+        devDependencies?: Record<string, string>;
+        peerDependencies?: Record<string, string>;
+      }
+    | undefined,
+): Set<string> {
+  return new Set([
+    ...Object.keys(packageJson?.dependencies ?? {}),
+    ...Object.keys(packageJson?.devDependencies ?? {}),
+    ...Object.keys(packageJson?.peerDependencies ?? {}),
+  ]);
+}
+
+function serverProviderFiles(
+  files: string[],
+  config: ResolvedBeignetConfig,
+): string[] {
+  const serverDir = directoryPath(path.dirname(config.paths.server));
+  const candidates = [`${serverDir}/providers.ts`, config.paths.server];
+  return candidates.filter((file) => files.includes(file));
+}
+
+function extractProviderListSource(source: string): string | undefined {
+  const listMatches = [
+    ...source.matchAll(/\bproviders\s*=\s*\[([\s\S]*?)\]\s*(?:;|as const)/g),
+    ...source.matchAll(/\bproviders\s*:\s*\[([\s\S]*?)\]/g),
+  ];
+  if (listMatches.length === 0) return undefined;
+  return listMatches.map((match) => match[1]).join("\n");
+}
+
+function providerListEntries(source: string): string[] {
+  const entries: string[] = [];
+  let current = "";
+  let depth = 0;
+  let quote: '"' | "'" | "`" | undefined;
+  let escaped = false;
+  let lineComment = false;
+  let blockComment = false;
+
+  for (let index = 0; index < source.length; index += 1) {
+    const char = source[index];
+    const next = source[index + 1];
+
+    if (lineComment) {
+      if (char === "\n") {
+        lineComment = false;
+        current += char;
+      }
+      continue;
+    }
+
+    if (blockComment) {
+      if (char === "*" && next === "/") {
+        blockComment = false;
+        index += 1;
+      }
+      continue;
+    }
+
+    if (quote) {
+      current += char;
+      if (escaped) {
+        escaped = false;
+        continue;
+      }
+      if (char === "\\") {
+        escaped = true;
+        continue;
+      }
+      if (char === quote) {
+        quote = undefined;
+      }
+      continue;
+    }
+
+    if (char === "/" && next === "/") {
+      lineComment = true;
+      index += 1;
+      continue;
+    }
+
+    if (char === "/" && next === "*") {
+      blockComment = true;
+      index += 1;
+      continue;
+    }
+
+    if (char === '"' || char === "'" || char === "`") {
+      quote = char;
+      current += char;
+      continue;
+    }
+
+    if (char === "(" || char === "[" || char === "{") {
+      depth += 1;
+    } else if (char === ")" || char === "]" || char === "}") {
+      depth = Math.max(0, depth - 1);
+    }
+
+    if (char === "," && depth === 0) {
+      const entry = current.trim();
+      if (entry) entries.push(entry);
+      current = "";
+      continue;
+    }
+
+    current += char;
+  }
+
+  const entry = current.trim();
+  if (entry) entries.push(entry);
+  return entries;
+}
+
+function findProviderEntryIndex(
+  entries: string[],
+  tokens: readonly string[],
+): number {
+  return entries.findIndex((entry) =>
+    tokens.some((token) => entry.includes(token)),
+  );
+}
+
+function hasBetterAuthRoute(
+  files: string[],
+  config: ResolvedBeignetConfig,
+): boolean {
+  const routesPath = directoryPath(config.paths.routes);
+  return files.some(
+    (file) =>
+      file.startsWith(`${routesPath}/auth/`) && file.endsWith("/route.ts"),
+  );
+}
+
+function featureNameFromContractFile(
+  file: string,
+  config: ResolvedBeignetConfig,
+): string | undefined {
+  const featuresPath = directoryPath(config.paths.features);
+  const match = new RegExp(
+    `^${escapeRegExp(featuresPath)}/([^/]+)/contracts\\.ts$`,
+  ).exec(file);
+  return match?.[1];
+}
+
+function featureRuntimeFiles(
+  files: string[],
+  featuresPath: string,
+  feature: string,
+): string[] {
+  const runtimeFolders = [
+    "jobs",
+    "listeners",
+    "schedules",
+    "uploads",
+    "use-cases",
+  ];
+  return files.filter((file) => {
+    if (!file.endsWith(".ts") || file.endsWith(".test.ts")) return false;
+    return runtimeFolders.some((folder) =>
+      file.startsWith(`${featuresPath}/${feature}/${folder}/`),
+    );
+  });
+}
+
+function featureTestFiles(
+  files: string[],
+  featuresPath: string,
+  feature: string,
+  options: { policyOnly?: boolean } = {},
+): string[] {
+  return files.filter((file) => {
+    if (
+      !file.startsWith(`${featuresPath}/${feature}/`) ||
+      !file.endsWith(".test.ts")
+    ) {
+      return false;
+    }
+    return !options.policyOnly || file.endsWith("/policy.test.ts");
+  });
+}
+
+function featureNamesFromContracts(
+  contracts: InspectedContract[],
+  config: ResolvedBeignetConfig,
+): string[] {
+  return [
+    ...new Set(
+      contracts
+        .map((contract) => featureNameFromContractFile(contract.file, config))
+        .filter((feature): feature is string => feature !== undefined),
+    ),
+  ].sort();
+}
+
+function sharedErrorCatalogBindings(
+  source: string,
+  file: string,
+  files: string[],
+  sharedErrorsFile: string,
+): Set<string> {
+  const bindings = new Set<string>();
+  const imports = parseNamedImportSources(source);
+
+  for (const [localName, imported] of imports) {
+    if (imported.importedName !== "errors") continue;
+    if (
+      importResolvesToFile(imported.sourcePath, file, files, sharedErrorsFile)
+    ) {
+      bindings.add(localName);
+    }
+  }
+
+  return bindings;
+}
+
+function importResolvesToFile(
+  sourcePath: string,
+  importerFile: string,
+  files: string[],
+  expectedFile: string,
+): boolean {
+  return (
+    sourceFileFromImport(sourcePath, importerFile, files) === expectedFile ||
+    sourceFileFromImport(sourcePath, importerFile) === expectedFile
+  );
+}
+
+function featureErrorRuntimeFiles(
+  files: string[],
+  featuresPath: string,
+  feature: string,
+): string[] {
+  const runtimeFiles = new Set(
+    featureRuntimeFiles(files, featuresPath, feature),
+  );
+  const policyFile = `${featuresPath}/${feature}/policy.ts`;
+  if (files.includes(policyFile)) runtimeFiles.add(policyFile);
+
+  return [...runtimeFiles].sort();
+}
+
+async function featureAppErrorUses(
+  targetDir: string,
+  files: string[],
+  sourceCache: Map<string, string>,
+): Promise<Map<string, string>> {
+  const uses = new Map<string, string>();
+
+  for (const file of files) {
+    const source = await readCachedSource(targetDir, file, sourceCache);
+    for (const match of source.matchAll(
+      /\bappError\s*\(\s*["']([^"']+)["']/g,
+    )) {
+      if (!uses.has(match[1])) uses.set(match[1], file);
+    }
+  }
+
+  return uses;
+}
+
+function isFeatureOwnedErrorName(errorName: string, feature: string): boolean {
+  const singularPascal = pascalCase(singularize(feature));
+  const pluralPascal = pascalCase(feature);
+
+  return (
+    errorName.startsWith(singularPascal) || errorName.startsWith(pluralPascal)
+  );
+}
+
+async function anyFileContains(
+  targetDir: string,
+  files: string[],
+  needle: string,
+  sourceCache: Map<string, string>,
+): Promise<boolean> {
+  for (const file of files) {
+    const source = await readCachedSource(targetDir, file, sourceCache);
+    if (source.includes(needle)) return true;
+  }
+
+  return false;
+}
+
+async function anyFileMatches(
+  targetDir: string,
+  files: string[],
+  pattern: RegExp,
+  sourceCache: Map<string, string>,
+): Promise<boolean> {
+  for (const file of files) {
+    const source = await readCachedSource(targetDir, file, sourceCache);
+    if (pattern.test(source)) return true;
+  }
+
+  return false;
+}
+
+async function readCachedSource(
+  targetDir: string,
+  file: string,
+  sourceCache: Map<string, string>,
+): Promise<string> {
+  const cached = sourceCache.get(file);
+  if (cached !== undefined) return cached;
+
+  const source = await readFile(path.join(targetDir, file), "utf8");
+  sourceCache.set(file, source);
+  return source;
+}
+
+async function inspectFeatureArtifactDrift(
+  targetDir: string,
+  files: string[],
+  config: ResolvedBeignetConfig,
+  convention: InspectConvention,
+): Promise<InspectDiagnostic[]> {
+  if (!convention.resourceGenerator) return [];
+
+  const diagnostics: InspectDiagnostic[] = [];
+  const featuresPath = directoryPath(config.paths.features);
+  const uploadDefinitions = files.filter((file) =>
+    isFeatureArtifactFile(file, featuresPath, "uploads"),
+  );
+
+  if (
+    uploadDefinitions.length > 0 &&
+    !(await appHasUploadRoute(targetDir, files, config))
+  ) {
+    diagnostics.push({
+      severity: "warning",
+      code: "BEIGNET_UPLOAD_ROUTE_MISSING",
+      file: uploadDefinitions[0],
+      message:
+        "This app defines feature uploads but no known upload route. Register the upload registry with createUploadRouter(...) and expose it through createUploadRoute(...) so browser uploads can reach the workflow.",
+    });
+  }
+
+  for (const file of files) {
+    const match = new RegExp(
+      `^${escapeRegExp(featuresPath)}/([^/]+)/[^/]+\\.test\\.ts$`,
+    ).exec(file);
+    if (!match) continue;
+    diagnostics.push({
+      severity: "warning",
+      code: "BEIGNET_FEATURE_TEST_PLACEMENT",
+      file,
+      message: `${file} places a test directly under ${featuresPath}/${match[1]}/. Move feature behavior tests into ${featuresPath}/${match[1]}/tests/ so feature suites stay in the canonical folder; adjacent *.test.ts files are for infra and server modules.`,
+    });
+  }
+
+  for (const file of files) {
+    if (
+      !file.endsWith(".ts") ||
+      file.endsWith(".test.ts") ||
+      file.endsWith(".d.ts")
+    ) {
+      continue;
+    }
+
+    const misplaced = misplacedFeatureArtifactFolder(file, featuresPath);
+    if (misplaced) {
+      diagnostics.push({
+        severity: "warning",
+        code: "BEIGNET_FEATURE_ARTIFACT_FOLDER",
+        file,
+        message: `${file} uses ${misplaced.actual}, but Beignet expects ${misplaced.expected}. Keep feature-owned workflow artifacts in the canonical feature folders so CLI generators, docs, and architecture lint stay aligned.`,
+      });
+    }
+
+    if (
+      isNotificationDefinitionFile(file, featuresPath) ||
+      isInfraOrServerFile(file, config)
+    ) {
+      continue;
+    }
+    const source = await readFile(path.join(targetDir, file), "utf8");
+    if (containsCallExpression(source, "createInlineNotificationDispatcher")) {
+      diagnostics.push({
+        severity: "warning",
+        code: "BEIGNET_NOTIFICATION_PORT_BYPASS",
+        file,
+        message: `${file} creates a notification dispatcher directly. Application workflows should send notifications through ctx.ports.notifications so delivery can be swapped, tested, instrumented, and run through jobs/outbox consistently.`,
+      });
+    }
+  }
+
+  return diagnostics;
+}
+
+function isFeatureArtifactFile(
+  file: string,
+  featuresPath: string,
+  folder: "uploads" | "notifications",
+): boolean {
+  const match = new RegExp(
+    `^${escapeRegExp(featuresPath)}/[^/]+/${folder}/([^/]+)\\.ts$`,
+  ).exec(file);
+  return Boolean(match && match[1] !== "index");
+}
+
+async function appHasUploadRoute(
+  targetDir: string,
+  files: string[],
+  config: ResolvedBeignetConfig,
+): Promise<boolean> {
+  for (const file of files) {
+    if (!file.endsWith(".ts") || file.endsWith(".test.ts")) continue;
+    if (!isRouteServerOrInfraFile(file, config)) continue;
+
+    const source = await readFile(path.join(targetDir, file), "utf8");
+    if (
+      containsCallExpression(source, "createUploadRoute") ||
+      containsCallExpression(source, "createUploadRouter")
+    ) {
+      return true;
+    }
+  }
+
+  return false;
+}
+
+function misplacedFeatureArtifactFolder(
+  file: string,
+  featuresPath: string,
+): { actual: string; expected: string } | undefined {
+  const match = new RegExp(
+    `^${escapeRegExp(featuresPath)}/([^/]+)/([^/]+)/`,
+  ).exec(file);
+  if (!match) return undefined;
+
+  const folder = match[2];
+  const mappings: Record<string, string> = {
+    command: "tasks/",
+    commands: "tasks/",
+    event: "domain/events/",
+    events: "domain/events/",
+    job: "jobs/",
+    listener: "listeners/",
+    notification: "notifications/",
+    schedule: "schedules/",
+    scheduled: "schedules/",
+    task: "tasks/",
+    upload: "uploads/",
+  };
+
+  const expected = mappings[folder];
+  if (!expected) return undefined;
+
+  return { actual: `${folder}/`, expected };
+}
+
+function isNotificationDefinitionFile(
+  file: string,
+  featuresPath: string,
+): boolean {
+  return isFeatureArtifactFile(file, featuresPath, "notifications");
+}
+
+function isRouteServerOrInfraFile(
+  file: string,
+  config: ResolvedBeignetConfig,
+): boolean {
+  return (
+    file.startsWith(`${directoryPath(config.paths.routes)}/`) ||
+    isInfraOrServerFile(file, config)
+  );
+}
+
+function isInfraOrServerFile(
+  file: string,
+  config: ResolvedBeignetConfig,
+): boolean {
+  const serverDir = directoryPath(path.dirname(config.paths.server));
+  const infrastructureDir = directoryPath(
+    path.dirname(config.paths.infrastructurePorts),
+  );
+
+  return (
+    file === config.paths.server ||
+    file.startsWith(`${serverDir}/`) ||
+    file === config.paths.infrastructurePorts ||
+    file.startsWith(`${infrastructureDir}/`)
+  );
+}
+
+function containsCallExpression(source: string, name: string): boolean {
+  return new RegExp(
+    `\\b${escapeRegExp(name)}\\s*(?:<[^;=(){}]*>\\s*)?\\(`,
+  ).test(source);
+}
+
+async function inspectServerlessFootguns(
+  targetDir: string,
+  files: string[],
+): Promise<InspectDiagnostic[]> {
+  const diagnostics: InspectDiagnostic[] = [];
+
+  for (const file of files) {
+    if (
+      !file.endsWith(".ts") ||
+      file.endsWith(".test.ts") ||
+      file.endsWith(".d.ts")
+    ) {
+      continue;
+    }
+
+    const isInfraOrServerFile =
+      file.startsWith("infra/") || file.startsWith("server/");
+    const isProviderFile =
+      /(^|\/)provider(s)?\.ts$/.test(file) ||
+      /(^|\/)[^/]*provider[^/]*\.ts$/.test(file);
+    const source = await readFile(path.join(targetDir, file), "utf8");
+
+    if (
+      isInfraOrServerFile &&
+      isProviderFile &&
+      /\bset(?:Interval|Timeout)\s*\(/.test(source)
+    ) {
+      diagnostics.push({
+        severity: "warning",
+        code: "BEIGNET_PROVIDER_BACKGROUND_WORK",
+        file,
+        message: `${file} starts timer-based work from provider/server setup. Serverless apps should expose bounded runtime entrypoints such as cron routes, scheduled handlers, job functions, or worker processes instead of provider polling loops.`,
+      });
+    }
+
+    if (
+      isInfraOrServerFile &&
+      isProviderFile &&
+      /\bcreateProvider\s*\(/.test(source) &&
+      /\bdrainOutbox\s*\(/.test(source)
+    ) {
+      diagnostics.push({
+        severity: "warning",
+        code: "BEIGNET_PROVIDER_OUTBOX_DRAIN",
+        file,
+        message: `${file} drains the outbox from provider lifecycle code. Move outbox delivery to createOutboxDrainRoute(...) or another bounded runtime entrypoint so imports and serverless cold starts do not run background work.`,
+      });
+    }
+
+    if (
+      file.startsWith("app/api/cron/") &&
+      file.endsWith("/route.ts") &&
+      !/\bauthorization\b/i.test(source) &&
+      !/\bcreateOutboxDrainRoute\s*\(/.test(source) &&
+      !/\bcreateScheduleRoute\s*\(/.test(source)
+    ) {
+      diagnostics.push({
+        severity: "warning",
+        code: "BEIGNET_CRON_ROUTE_AUTH_MISSING",
+        file,
+        message: `${file} looks like a cron route without an authorization check. Require a shared secret or use a framework route helper such as createOutboxDrainRoute(...) or createScheduleRoute(...).`,
+      });
+    }
+  }
+
+  if (
+    hasOutboxRegistry(files) &&
+    !(await appHasOutboxDrainEntrypoint(targetDir, files))
+  ) {
+    diagnostics.push({
+      severity: "warning",
+      code: "BEIGNET_OUTBOX_DRAIN_MISSING",
+      message:
+        "This app defines an outbox registry but no known drain entrypoint. Add a cron/schedule/job route with createOutboxDrainRoute(...) so durable events and jobs are delivered in serverless deployments.",
+    });
+  }
+
+  return diagnostics;
+}
+
+function hasOutboxRegistry(files: string[]): boolean {
+  return files.some(isOutboxRegistryFile);
+}
+
+function isOutboxRegistryFile(file: string): boolean {
+  return file === "server/outbox.ts";
+}
+
+async function appHasOutboxDrainEntrypoint(
+  targetDir: string,
+  files: string[],
+): Promise<boolean> {
+  for (const file of files) {
+    if (!file.endsWith(".ts") || file.endsWith(".test.ts")) continue;
+    if (
+      !file.startsWith("app/api/") &&
+      !file.startsWith("server/") &&
+      !file.startsWith("infra/")
+    ) {
+      continue;
+    }
+
+    const source = await readFile(path.join(targetDir, file), "utf8");
+    if (
+      /\bcreateOutboxDrainRoute\s*\(/.test(source) ||
+      /\bdrainOutbox\s*\(/.test(source)
+    ) {
+      return true;
+    }
+  }
+
+  return false;
+}
+
+async function inspectPortProviderDrift(
+  targetDir: string,
+  files: string[],
+  config: ResolvedBeignetConfig,
+  convention: InspectConvention,
+): Promise<InspectDiagnostic[]> {
+  if (!convention.resourceGenerator) return [];
+
   const diagnostics: InspectDiagnostic[] = [];
   const portsSource = files.includes(config.paths.ports)
     ? await readFile(path.join(targetDir, config.paths.ports), "utf8")
     : "";
   const packageJson = files.includes("package.json")
-    ? (JSON.parse(
-        await readFile(path.join(targetDir, "package.json"), "utf8"),
-      ) as {
-        dependencies?: Record<string, string>;
-        devDependencies?: Record<string, string>;
-        peerDependencies?: Record<string, string>;
-      })
+    ? await readPackageJson(targetDir, files)
     : undefined;
   const installedPackages = new Set([
     ...Object.keys(packageJson?.dependencies ?? {}),
     ...Object.keys(packageJson?.devDependencies ?? {}),
     ...Object.keys(packageJson?.peerDependencies ?? {}),
   ]);
+  const providerDoctorRules = await providerDoctorRulesForInstalledPackages(
+    targetDir,
+    packageJson,
+  );
+
+  const providerPortRequirements = providerDoctorRules.flatMap((provider) =>
+    (provider.appPorts ?? []).map((port) => ({
+      packageName: provider.packageName,
+      portName: port.name,
+      portType: port.type,
+    })),
+  );
+
+  for (const expected of providerPortRequirements) {
+    if (!installedPackages.has(expected.packageName)) continue;
+    if (portsSource.includes(`${expected.portName}:`)) continue;
+    diagnostics.push({
+      severity: "warning",
+      code: "BEIGNET_PROVIDER_PORT_MISSING",
+      file: config.paths.ports,
+      message: `${expected.packageName} is installed, but AppPorts does not declare ${expected.portName}: ${expected.portType}. Add the canonical port to AppPorts or remove the unused provider package.`,
+    });
+  }
+
+  const portDir = directoryPath(path.dirname(config.paths.ports));
+  for (const file of files) {
+    if (
+      !file.startsWith(`${portDir}/`) ||
+      !file.endsWith(".ts") ||
+      file === config.paths.ports ||
+      file.endsWith("-repository.ts")
+    ) {
+      continue;
+    }
+
+    const source = await readFile(path.join(targetDir, file), "utf8");
+    const generatedPort =
+      /export interface ([A-Z]\w*Port)\s*\{[\s\S]*execute\(/.exec(source);
+    if (!generatedPort) continue;
+    const fakeFactory = `createFake${generatedPort[1].replace(/Port$/, "")}Port`;
+    if (source.includes(fakeFactory)) continue;
+    diagnostics.push({
+      severity: "warning",
+      code: "BEIGNET_PORT_TEST_FAKE_MISSING",
+      file,
+      message: `${file} looks like a generated port, but it does not export ${fakeFactory}(). Re-run make port with --force or add a small fake adapter so use-case tests can stay vendor-free.`,
+    });
+  }
+
+  return diagnostics;
+}
+
+async function inspectDatabaseLifecycleDrift(
+  targetDir: string,
+  files: string[],
+  config: ResolvedBeignetConfig,
+  convention: InspectConvention,
+  strict: boolean,
+): Promise<InspectDiagnostic[]> {
+  if (!convention.resourceGenerator) return [];
+
+  const diagnostics: InspectDiagnostic[] = [];
+  const resources = await collectResourceNames(targetDir, files, config);
+  const infrastructurePath = directoryPath(
+    path.dirname(config.paths.infrastructurePorts),
+  );
+  const featuresPath = directoryPath(config.paths.features);
+  const repositoriesPath = path.join(
+    infrastructurePath,
+    "db",
+    "repositories.ts",
+  );
+  const repositoriesSource = files.includes(repositoriesPath)
+    ? await readFile(path.join(targetDir, repositoriesPath), "utf8")
+    : "";
+  const packageScripts = await readPackageScripts(targetDir, files);
+  const schemaDir = `${infrastructurePath}/db/schema`;
+  const schemaIndexFile = `${schemaDir}/index.ts`;
+  const schemaFiles = files.filter(
+    (file) =>
+      file.startsWith(`${schemaDir}/`) &&
+      file.endsWith(".ts") &&
+      file !== schemaIndexFile,
+  );
+  const hasDrizzleArtifacts =
+    hasDrizzleConfig(files) ||
+    files.includes(repositoriesPath) ||
+    files.includes(schemaIndexFile) ||
+    schemaFiles.length > 0 ||
+    files.some(
+      (file) =>
+        file.startsWith(`${infrastructurePath}/`) &&
+        file.endsWith("-repository.ts") &&
+        file.includes("/drizzle-"),
+    );
+
+  if (
+    hasDrizzleArtifacts &&
+    !hasDrizzleConfig(files) &&
+    hasDrizzleLifecycleScriptNeedingRootConfig(packageScripts)
+  ) {
+    diagnostics.push({
+      severity: "warning",
+      code: "BEIGNET_DRIZZLE_CONFIG_MISSING",
+      file: "drizzle.config.ts",
+      message:
+        "This app has Drizzle database artifacts, but no drizzle.config.ts, drizzle.config.mts, drizzle.config.js, or drizzle.config.mjs exists at the app root. Add a Drizzle config so beignet db generate and beignet db migrate can run.",
+    });
+  }
+
+  if (hasDrizzleArtifacts) {
+    for (const script of ["db:generate", "db:migrate"] as const) {
+      if (packageScripts[script]) continue;
+      diagnostics.push({
+        severity: "warning",
+        code: "BEIGNET_DB_SCRIPT_MISSING",
+        file: "package.json",
+        message: `This app has Drizzle database artifacts, but package.json does not define "${script}". Add an app-owned ${script} script so beignet db ${script.replace("db:", "")} can run the database lifecycle command.`,
+      });
+    }
+  }
+
+  const schemaFilePath = `${infrastructurePath}/db/schema.ts`;
+  if (files.includes(schemaFilePath)) {
+    diagnostics.push({
+      severity: "warning",
+      code: "BEIGNET_DB_SCHEMA_FILE_FORM",
+      file: schemaFilePath,
+      message: `${schemaFilePath} keeps the Drizzle schema in a single file. Move it to ${schemaIndexFile} so feature tables can live in separate modules under ${schemaDir}/.`,
+    });
+  }
+
+  if (schemaFiles.length > 0 && !files.includes(schemaIndexFile)) {
+    diagnostics.push({
+      severity: "warning",
+      code: "BEIGNET_DB_SCHEMA_INDEX_MISSING",
+      file: schemaIndexFile,
+      message: `${schemaDir} contains table schema files, but ${schemaIndexFile} is missing. Add the schema index so Drizzle config and generated repositories can import one schema module.`,
+    });
+  } else if (schemaFiles.length > 0) {
+    const schemaIndexSource = await readFile(
+      path.join(targetDir, schemaIndexFile),
+      "utf8",
+    );
+    for (const schemaFile of schemaFiles) {
+      const moduleName = path.basename(schemaFile, ".ts");
+      if (schemaIndexSource.includes(`"./${moduleName}"`)) continue;
+      diagnostics.push({
+        severity: "warning",
+        code: "BEIGNET_DB_SCHEMA_EXPORT_MISSING",
+        file: schemaIndexFile,
+        message: `${schemaFile} is not exported from ${schemaIndexFile}. Export it so Drizzle config, migrations, and repository factories see the same schema module.`,
+      });
+    }
+  }
 
-  for (const expected of canonicalProviderPorts) {
-    if (!installedPackages.has(expected.packageName)) continue;
-    if (portsSource.includes(`${expected.portName}:`)) continue;
+  const standardEntrypoints = [
+    {
+      script: "db:seed",
+      command: "seed",
+      file: `${infrastructurePath}/db/seed.ts`,
+      code: "BEIGNET_DB_SEED_ENTRYPOINT_MISSING",
+    },
+    {
+      script: "db:reset",
+      command: "reset",
+      file: `${infrastructurePath}/db/reset.ts`,
+      code: "BEIGNET_DB_RESET_ENTRYPOINT_MISSING",
+    },
+  ] as const;
+
+  for (const entrypoint of standardEntrypoints) {
+    const script = packageScripts[entrypoint.script];
+    if (!script?.includes(entrypoint.file) || files.includes(entrypoint.file)) {
+      continue;
+    }
     diagnostics.push({
       severity: "warning",
-      code: "CK_PROVIDER_PORT_MISSING",
-      file: config.paths.ports,
-      message: `${expected.packageName} is installed, but AppPorts does not declare ${expected.portName}: ${expected.portType}. Add the canonical port to AppPorts or remove the unused provider package.`,
+      code: entrypoint.code,
+      file: entrypoint.file,
+      message: `package.json script "${entrypoint.script}" runs ${entrypoint.file}, but that file is missing. Restore ${entrypoint.file} or update the script before running beignet db ${entrypoint.command}.`,
     });
   }
 
-  const portDir = directoryPath(path.dirname(config.paths.ports));
-  for (const file of files) {
+  const resetEntrypoint = `${infrastructurePath}/db/reset.ts`;
+  if (
+    packageScripts["db:reset"]?.includes(resetEntrypoint) &&
+    files.includes(resetEntrypoint)
+  ) {
+    const resetSource = await readFile(
+      path.join(targetDir, resetEntrypoint),
+      "utf8",
+    );
+    if (!resetSource.includes("BEIGNET_ALLOW_DATABASE_RESET")) {
+      diagnostics.push({
+        severity: "warning",
+        code: "BEIGNET_DB_RESET_GUARD_MISSING",
+        file: resetEntrypoint,
+        message:
+          "The standard database reset entrypoint does not mention BEIGNET_ALLOW_DATABASE_RESET. Keep destructive reset behavior guarded so non-local databases are not reset accidentally.",
+      });
+    }
+  }
+
+  for (const resource of resources) {
+    const singular = singularize(resource);
+    const pascal = pascalCase(singular);
+    const pluralCamel = camelCase(resource);
+    const infrastructureDir = `${infrastructurePath}/${resource}/`;
+    const hasRepositoryAdapter = hasRepositoryAdapterFile(
+      files,
+      infrastructureDir,
+    );
+    const drizzleRepositoryAdapter = drizzleRepositoryAdapterFile(
+      files,
+      infrastructureDir,
+      singular,
+    );
+
+    const portFile = resourcePortFile(resource, singular, config);
+
+    if (files.includes(portFile) && !hasRepositoryAdapter) {
+      diagnostics.push({
+        severity: "warning",
+        code: "BEIGNET_REPOSITORY_ADAPTER_MISSING",
+        file: portFile,
+        message: `${portFile} declares a repository port, but ${infrastructureDir} does not contain a repository adapter. Add an infra adapter such as drizzle-${singular}-repository.ts and wire it through app ports.`,
+      });
+    }
+
+    if (drizzleRepositoryAdapter) {
+      const factoryName = `createDrizzle${pascal}Repository`;
+      if (
+        repositoriesSource &&
+        (!repositoriesSource.includes(factoryName) ||
+          !new RegExp(`\\b${pluralCamel}\\s*:`).test(repositoriesSource))
+      ) {
+        diagnostics.push({
+          severity: "warning",
+          code: "BEIGNET_DRIZZLE_REPOSITORY_UNWIRED",
+          file: repositoriesPath,
+          message: `${drizzleRepositoryAdapter} exists, but ${repositoriesPath} does not appear to import and return ${factoryName}(db). Wire the repository through createRepositories(...) so normal and transaction-scoped ports stay aligned.`,
+        });
+      }
+    }
+
     if (
-      !file.startsWith(`${portDir}/`) ||
-      !file.endsWith(".ts") ||
-      file === config.paths.ports ||
-      file.endsWith("-repository.ts")
+      strict &&
+      hasFeatureSeeds(files, featuresPath, resource) &&
+      !hasFeatureFactories(files, featuresPath, resource)
     ) {
-      continue;
+      diagnostics.push({
+        severity: "warning",
+        code: "BEIGNET_FACTORY_MISSING",
+        file: `${featuresPath}/${resource}/seeds/`,
+        message: `${resource} defines feature seeds but no feature factory. Add a factory under ${featuresPath}/${resource}/tests/factories/ so seeds and tests share the same app-owned data setup path.`,
+      });
     }
+  }
 
-    const source = await readFile(path.join(targetDir, file), "utf8");
-    const generatedPort =
-      /export interface ([A-Z]\w*Port)\s*\{[\s\S]*execute\(/.exec(source);
-    if (!generatedPort) continue;
-    const fakeFactory = `createFake${generatedPort[1].replace(/Port$/, "")}Port`;
-    if (source.includes(fakeFactory)) continue;
+  if (
+    hasAnyFeatureSeeds(files, featuresPath) &&
+    !(await packageScriptExists(targetDir, files, "db:seed"))
+  ) {
     diagnostics.push({
       severity: "warning",
-      code: "CK_PORT_TEST_FAKE_MISSING",
-      file,
-      message: `${file} looks like a generated port, but it does not export ${fakeFactory}(). Re-run make port with --force or add a small fake adapter so use-case tests can stay vendor-free.`,
+      code: "BEIGNET_DB_SEED_SCRIPT_MISSING",
+      file: "package.json",
+      message:
+        'This app defines feature seeds, but package.json does not define "db:seed". Add an app-owned db:seed script so beignet db seed can run the seed entrypoint.',
     });
   }
 
   return diagnostics;
 }
 
-const canonicalProviderPorts = [
-  {
-    packageName: "@beignet/provider-auth-better-auth",
-    portName: "auth",
-    portType: "AuthPort",
-  },
-  {
-    packageName: "@beignet/provider-event-bus-memory",
-    portName: "eventBus",
-    portType: "EventBusPort",
-  },
-  {
-    packageName: "@beignet/provider-inngest",
-    portName: "jobs",
-    portType: "JobDispatcherPort",
-  },
-  {
-    packageName: "@beignet/provider-logger-pino",
-    portName: "logger",
-    portType: "LoggerPort",
-  },
-  {
-    packageName: "@beignet/provider-mail-resend",
-    portName: "mailer",
-    portType: "MailerPort",
-  },
-  {
-    packageName: "@beignet/provider-mail-smtp",
-    portName: "mailer",
-    portType: "MailerPort",
-  },
-  {
-    packageName: "@beignet/provider-rate-limit-upstash",
-    portName: "rateLimit",
-    portType: "RateLimitPort",
-  },
-  {
-    packageName: "@beignet/provider-redis",
-    portName: "cache",
-    portType: "CachePort",
-  },
-] as const;
+function hasRepositoryAdapterFile(
+  files: string[],
+  infrastructureDir: string,
+): boolean {
+  return files.some(
+    (file) =>
+      file.startsWith(infrastructureDir) &&
+      file.endsWith("-repository.ts") &&
+      !file.endsWith(".test.ts"),
+  );
+}
+
+function drizzleRepositoryAdapterFile(
+  files: string[],
+  infrastructureDir: string,
+  singular: string,
+): string | undefined {
+  return files.find(
+    (file) =>
+      file.startsWith(infrastructureDir) &&
+      file.endsWith(`/drizzle-${singular}-repository.ts`),
+  );
+}
+
+function hasFeatureSeeds(
+  files: string[],
+  featuresPath: string,
+  resource: string,
+): boolean {
+  return files.some(
+    (file) =>
+      file.startsWith(`${featuresPath}/${resource}/seeds/`) &&
+      file.endsWith(".ts") &&
+      !file.endsWith("/index.ts"),
+  );
+}
+
+function hasAnyFeatureSeeds(files: string[], featuresPath: string): boolean {
+  return files.some(
+    (file) =>
+      new RegExp(`^${escapeRegExp(featuresPath)}/[^/]+/seeds/`).test(file) &&
+      file.endsWith(".ts") &&
+      !file.endsWith("/index.ts"),
+  );
+}
+
+function hasFeatureFactories(
+  files: string[],
+  featuresPath: string,
+  resource: string,
+): boolean {
+  return files.some(
+    (file) =>
+      file === `${featuresPath}/${resource}/tests/factories.ts` ||
+      (file.startsWith(`${featuresPath}/${resource}/tests/factories/`) &&
+        file.endsWith(".ts") &&
+        !file.endsWith("/index.ts")),
+  );
+}
+
+async function packageScriptExists(
+  targetDir: string,
+  files: string[],
+  script: string,
+): Promise<boolean> {
+  const scripts = await readPackageScripts(targetDir, files);
+
+  return Boolean(scripts[script]);
+}
+
+async function readPackageScripts(
+  targetDir: string,
+  files: string[],
+): Promise<Record<string, string>> {
+  if (!files.includes("package.json")) return {};
+
+  const packageJson = JSON.parse(
+    await readFile(path.join(targetDir, "package.json"), "utf8"),
+  ) as {
+    scripts?: Record<string, string>;
+  };
+
+  return packageJson.scripts ?? {};
+}
+
+function hasDrizzleConfig(files: string[]): boolean {
+  return [
+    "drizzle.config.ts",
+    "drizzle.config.mts",
+    "drizzle.config.js",
+    "drizzle.config.mjs",
+  ].some((file) => files.includes(file));
+}
+
+function hasDrizzleLifecycleScriptNeedingRootConfig(
+  scripts: Record<string, string>,
+): boolean {
+  const lifecycleScripts = ["db:generate", "db:migrate"]
+    .map((script) => scripts[script])
+    .filter((script): script is string => Boolean(script));
+
+  if (lifecycleScripts.length === 0) return true;
+
+  return lifecycleScripts.some(
+    (script) =>
+      /\bdrizzle-kit\b/.test(script) && !hasExplicitDrizzleConfigFlag(script),
+  );
+}
+
+function hasExplicitDrizzleConfigFlag(script: string): boolean {
+  return /(?:^|\s)--config(?:=|\s)/.test(script);
+}
 
 async function inspectPackageScripts(
   targetDir: string,
@@ -938,7 +3390,7 @@ async function inspectPackageScripts(
   return [
     {
       severity: "warning",
-      code: "CK_PACKAGE_TEST_SCRIPT_MISSING",
+      code: "BEIGNET_PACKAGE_TEST_SCRIPT_MISSING",
       file: "package.json",
       message:
         'package.json does not define a test script. Add "test": "bun test" or run beignet doctor --fix.',
@@ -969,7 +3421,7 @@ async function fixMissingTestScript(
 
   await writeFile(filePath, next);
   return {
-    code: "CK_PACKAGE_TEST_SCRIPT_MISSING",
+    code: "BEIGNET_PACKAGE_TEST_SCRIPT_MISSING",
     file: "package.json",
     message: 'Added "test": "bun test".',
   };
@@ -981,7 +3433,7 @@ function unmatchedRouteDiagnostic(
   if (routeHandler.source === "next-route") {
     return {
       severity: "error",
-      code: "CK_ROUTE_HANDLER_ORPHANED",
+      code: "BEIGNET_ROUTE_HANDLER_ORPHANED",
       file: routeHandler.handlerFile,
       message: `${routeHandler.handlerFile} exports ${routeHandler.method} = server.api, but no known contract matches ${routeHandler.method} ${routeHandler.contractRef}. Add the matching contract, update the route file path, or remove the handler export.`,
     };
@@ -993,7 +3445,7 @@ function unmatchedRouteDiagnostic(
 
   return {
     severity: "error",
-    code: "CK_ROUTE_HANDLER_UNKNOWN_CONTRACT",
+    code: "BEIGNET_ROUTE_HANDLER_UNKNOWN_CONTRACT",
     file: routeHandler.handlerFile,
     contract: routeHandler.contractRef,
     message: `${routeHandler.handlerFile} references ${contractLabel}, but that contract was not found under the configured contracts path. Fix the import/export or remove the route handler.`,
@@ -1025,7 +3477,9 @@ async function inspectOpenApiDrift(
   targetDir: string,
   files: string[],
   config: ResolvedBeignetConfig,
+  convention: InspectConvention,
   contracts: InspectedContract[],
+  matchedRoutes: MatchedRoutesResult,
 ): Promise<InspectDiagnostic[]> {
   const routePath = path.join(targetDir, config.paths.openapiRoute);
   try {
@@ -1035,6 +3489,14 @@ async function inspectOpenApiDrift(
   }
 
   const source = await readFile(routePath, "utf8");
+  const routeSurface = await routeSurfaceContracts(
+    targetDir,
+    files,
+    config,
+    convention,
+    contracts,
+    matchedRoutes,
+  );
   const listedContracts = await openApiContracts(
     targetDir,
     files,
@@ -1045,15 +3507,76 @@ async function inspectOpenApiDrift(
     return [];
   }
 
-  return contracts
-    .filter((contract) => !listedContracts.has(contract.exportName))
-    .map((contract) => ({
-      severity: "warning" as const,
-      code: "CK_OPENAPI_MISSING",
-      file: config.paths.openapiRoute,
-      contract: contract.exportName,
-      message: `${contract.exportName} (${contract.method} ${contract.path}) is not listed in createOpenAPIHandler. Add it to the OpenAPI contract array/list or remove the contract from the documented API surface.`,
-    }));
+  const contractByName = new Map(
+    contracts.map((contract) => [contract.exportName, contract]),
+  );
+  const routeSurfaceNames = new Set(
+    routeSurface.map((contract) => contract.exportName),
+  );
+
+  return [
+    ...routeSurface
+      .filter((contract) => !listedContracts.has(contract.exportName))
+      .map((contract) => ({
+        severity: "warning" as const,
+        code: "BEIGNET_OPENAPI_MISSING",
+        file: config.paths.openapiRoute,
+        contract: contract.exportName,
+        message: `${contract.exportName} (${contract.method} ${contract.path}) is not listed in createOpenAPIHandler. Add it to the OpenAPI contract array/list or remove the contract from the documented API surface.`,
+      })),
+    ...[...listedContracts]
+      .filter((contractName) => !routeSurfaceNames.has(contractName))
+      .flatMap((contractName) => {
+        const contract = contractByName.get(contractName);
+        if (!contract) return [];
+
+        return [
+          {
+            severity: "warning" as const,
+            code: "BEIGNET_OPENAPI_UNROUTED",
+            file: config.paths.openapiRoute,
+            contract: contract.exportName,
+            message: `${contract.exportName} (${contract.method} ${contract.path}) is listed in createOpenAPIHandler, but it is not part of the registered route surface. Register the feature route group or remove the contract from OpenAPI.`,
+          },
+        ];
+      }),
+  ];
+}
+
+async function routeSurfaceContracts(
+  targetDir: string,
+  files: string[],
+  config: ResolvedBeignetConfig,
+  convention: InspectConvention,
+  contracts: InspectedContract[],
+  matchedRoutes: MatchedRoutesResult,
+): Promise<InspectedContract[]> {
+  if (convention.resourceGenerator && files.includes(config.paths.server)) {
+    const routeGroups = await readFeatureRouteGroups(targetDir, files, config);
+    const serverSource = await readFile(
+      path.join(targetDir, config.paths.server),
+      "utf8",
+    );
+    const registeredGroups = await registeredRouteGroupsForServer(
+      targetDir,
+      files,
+      config,
+      serverSource,
+    );
+    const routeGroupContracts = contractsForRegisteredRouteGroups(
+      contracts,
+      routeGroups,
+      registeredGroups,
+    );
+
+    if (routeGroups.length > 0) {
+      return routeGroupContracts;
+    }
+  }
+
+  return matchedRoutes.routes.filter(
+    (route) => route.handlerSource !== "missing",
+  );
 }
 
 async function inspectFeatureRouteRegistration(
@@ -1080,6 +3603,44 @@ async function inspectFeatureRouteRegistration(
     serverSource,
   );
   const diagnostics: InspectDiagnostic[] = [];
+  const featuresPath = directoryPath(config.paths.features);
+
+  for (const contract of contracts) {
+    const feature = featureNameFromContractFile(contract.file, config);
+    if (!feature) continue;
+
+    const routeFile = `${featuresPath}/${feature}/routes.ts`;
+    const featureRouteGroups = routeGroups.filter(
+      (routeGroup) => routeGroup.file === routeFile,
+    );
+
+    if (featureRouteGroups.length === 0) {
+      diagnostics.push({
+        severity: "error",
+        code: "BEIGNET_FEATURE_ROUTE_GROUP_MISSING",
+        file: contract.file,
+        contract: contract.exportName,
+        message: `${contract.exportName} (${contract.method} ${contract.path}) is declared in ${contract.file}, but ${routeFile} is missing. Add a feature route group that maps the contract to a use case, or remove the unused contract.`,
+      });
+      continue;
+    }
+
+    const routeGroupHasContract = featureRouteGroups.some((routeGroup) =>
+      routeGroup.contracts.some(
+        (routeGroupContract) =>
+          findRouteGroupContract([contract], routeGroupContract) !== undefined,
+      ),
+    );
+    if (routeGroupHasContract) continue;
+
+    diagnostics.push({
+      severity: "error",
+      code: "BEIGNET_ROUTE_GROUP_CONTRACT_MISSING",
+      file: routeFile,
+      contract: contract.exportName,
+      message: `${contract.exportName} (${contract.method} ${contract.path}) is declared in ${contract.file}, but no route in ${routeFile} references it. Add the contract to the feature route group or remove the unused contract.`,
+    });
+  }
 
   for (const routeGroup of routeGroups) {
     if (registeredGroups.has(routeGroup.name)) continue;
@@ -1088,7 +3649,7 @@ async function inspectFeatureRouteRegistration(
       const contract = findRouteGroupContract(contracts, routeGroupContract);
       diagnostics.push({
         severity: "error",
-        code: "CK_ROUTE_GROUP_UNREGISTERED",
+        code: "BEIGNET_ROUTE_GROUP_UNREGISTERED",
         file: config.paths.server,
         contract: routeGroupContract.exportName,
         message: contract
@@ -1101,6 +3662,32 @@ async function inspectFeatureRouteRegistration(
   return diagnostics;
 }
 
+function contractsForRegisteredRouteGroups(
+  contracts: InspectedContract[],
+  routeGroups: FeatureRouteGroup[],
+  registeredGroups: Set<string>,
+): InspectedContract[] {
+  const seen = new Set<string>();
+  const registeredContracts: InspectedContract[] = [];
+
+  for (const routeGroup of routeGroups) {
+    if (!registeredGroups.has(routeGroup.name)) continue;
+
+    for (const routeGroupContract of routeGroup.contracts) {
+      const contract = findRouteGroupContract(contracts, routeGroupContract);
+      if (!contract) continue;
+
+      const key = contractKey(contract);
+      if (seen.has(key)) continue;
+
+      seen.add(key);
+      registeredContracts.push(contract);
+    }
+  }
+
+  return registeredContracts.sort(compareContracts);
+}
+
 async function readFeatureRouteGroups(
   targetDir: string,
   files: string[],
@@ -1128,10 +3715,14 @@ function parseFeatureRouteGroups(
 ): FeatureRouteGroup[] {
   const routeGroups: FeatureRouteGroup[] = [];
   const exportRegex =
-    /(?:^|\n)export const\s+([A-Za-z_$][\w$]*)\s*=\s*defineRouteGroup(?:<[^>]+>)?\(\s*(?:\{[\s\S]*?routes:\s*)?\[([\s\S]*?)\]\s*(?:,?\s*\})?\s*\)\s*;?/g;
+    /(?:^|\n)export const\s+([A-Za-z_$][\w$]*)\s*=\s*defineRouteGroup(?:<[^>]+>)?\(/g;
 
   for (const match of source.matchAll(exportRegex)) {
-    const contracts = [...match[2].matchAll(/contract:\s*([^,\n}]+)/g)]
+    const callStart = (match.index ?? 0) + match[0].length;
+    const routesBody = routeGroupRoutesArrayBody(source, callStart);
+    if (routesBody === undefined) continue;
+
+    const contracts = [...routesBody.matchAll(/contract:\s*([^,\n}]+)/g)]
       .map((contractMatch) =>
         routeGroupContractRef(contractMatch[1].trim(), imports),
       )
@@ -1139,14 +3730,87 @@ function parseFeatureRouteGroups(
         Boolean(contract),
       );
 
-    routeGroups.push({
-      name: match[1],
-      file,
-      contracts,
-    });
+    routeGroups.push({
+      name: match[1],
+      file,
+      contracts,
+    });
+  }
+
+  return routeGroups;
+}
+
+/**
+ * Extract the body of the `routes: [...]` array for a route group call.
+ *
+ * Both binder routes (`{ contract, useCase }`) and full handler routes
+ * (`{ contract, handle }`) can contain nested brackets, strings, and arrow
+ * functions, so the array is scanned with balanced-bracket tracking instead
+ * of a regular expression.
+ */
+function routeGroupRoutesArrayBody(
+  source: string,
+  callStart: number,
+): string | undefined {
+  const objectStart = source.indexOf("{", callStart);
+  if (objectStart === -1) return undefined;
+
+  const groupObject = balancedObjectSource(source, objectStart);
+  if (!groupObject) return undefined;
+
+  const routesIndex = groupObject.indexOf("routes:");
+  if (routesIndex === -1) return undefined;
+
+  const arrayStart = groupObject.indexOf("[", routesIndex);
+  if (arrayStart === -1) return undefined;
+
+  const arraySource = balancedArraySource(groupObject, arrayStart);
+  return arraySource?.slice(1, -1);
+}
+
+function balancedArraySource(
+  source: string,
+  startIndex: number,
+): string | undefined {
+  if (source[startIndex] !== "[") return undefined;
+
+  let depth = 0;
+  let quote: '"' | "'" | "`" | undefined;
+  let escaped = false;
+
+  for (let index = startIndex; index < source.length; index += 1) {
+    const char = source[index];
+
+    if (quote) {
+      if (escaped) {
+        escaped = false;
+        continue;
+      }
+      if (char === "\\") {
+        escaped = true;
+        continue;
+      }
+      if (char === quote) quote = undefined;
+      continue;
+    }
+
+    if (char === '"' || char === "'" || char === "`") {
+      quote = char;
+      continue;
+    }
+
+    if (char === "[") {
+      depth += 1;
+      continue;
+    }
+
+    if (char === "]") {
+      depth -= 1;
+      if (depth === 0) return source.slice(startIndex, index + 1);
+    }
   }
 
-  return routeGroups;
+  return undefined;
 }
 
 function routeGroupContractRef(
@@ -1250,8 +3914,11 @@ function findRouteGroupContract(
 
 async function fixDirectOpenApiArrayDrift(
   targetDir: string,
+  files: string[],
   config: ResolvedBeignetConfig,
+  convention: InspectConvention,
   contracts: InspectedContract[],
+  matchedRoutes: MatchedRoutesResult,
 ): Promise<InspectFix | undefined> {
   const routePath = path.join(targetDir, config.paths.openapiRoute);
   let source: string;
@@ -1264,8 +3931,16 @@ async function fixDirectOpenApiArrayDrift(
   const firstArg = firstCreateOpenAPIHandlerArgInfo(source);
   if (!firstArg?.text.startsWith("[")) return undefined;
 
+  const routeSurface = await routeSurfaceContracts(
+    targetDir,
+    files,
+    config,
+    convention,
+    contracts,
+    matchedRoutes,
+  );
   const listedContracts = contractsFromArrayExpression(firstArg.text);
-  const missingContracts = contracts.filter(
+  const missingContracts = routeSurface.filter(
     (contract) => !listedContracts.has(contract.exportName),
   );
   if (missingContracts.length === 0) return undefined;
@@ -1289,7 +3964,7 @@ async function fixDirectOpenApiArrayDrift(
 
   await writeFile(routePath, next);
   return {
-    code: "CK_OPENAPI_MISSING",
+    code: "BEIGNET_OPENAPI_MISSING",
     file: config.paths.openapiRoute,
     message: `Added ${missingContracts
       .map((contract) => contract.exportName)
@@ -1297,6 +3972,113 @@ async function fixDirectOpenApiArrayDrift(
   };
 }
 
+async function fixUnregisteredRouteGroups(
+  targetDir: string,
+  files: string[],
+  config: ResolvedBeignetConfig,
+): Promise<InspectFix | undefined> {
+  if (!files.includes(config.paths.server)) return undefined;
+
+  const routeGroups = await readFeatureRouteGroups(targetDir, files, config);
+  if (routeGroups.length === 0) return undefined;
+
+  const serverSource = await readFile(
+    path.join(targetDir, config.paths.server),
+    "utf8",
+  );
+  const registeredGroups = await registeredRouteGroupsForServer(
+    targetDir,
+    files,
+    config,
+    serverSource,
+  );
+  const missingGroups = routeGroups
+    .filter((routeGroup) => !registeredGroups.has(routeGroup.name))
+    .sort((left, right) => left.file.localeCompare(right.file));
+  if (missingGroups.length === 0) return undefined;
+
+  const targetFile =
+    routeRegistryFileFromServerSource(
+      serverSource,
+      config.paths.server,
+      files,
+    ) ?? config.paths.server;
+  if (!files.includes(targetFile)) return undefined;
+
+  const targetPath = path.join(targetDir, targetFile);
+  const original = await readFile(targetPath, "utf8");
+  const firstArg = firstDefineRoutesArgInfo(original);
+  if (!firstArg?.text.startsWith("[")) return undefined;
+
+  const registeredInTarget = contractsFromArrayExpression(firstArg.text);
+  const groupsToAppend = missingGroups.filter(
+    (routeGroup) => !registeredInTarget.has(routeGroup.name),
+  );
+  if (groupsToAppend.length === 0) return undefined;
+
+  let next = original;
+  for (const routeGroup of groupsToAppend) {
+    const imported = parseNamedImportSources(next).get(routeGroup.name);
+    if (imported) {
+      const importedFile = sourceFileFromImport(
+        imported.sourcePath,
+        targetFile,
+        files,
+      );
+      if (importedFile !== routeGroup.file) return undefined;
+      continue;
+    }
+
+    next = insertAfterImports(
+      next,
+      `import { ${routeGroup.name} } from "${relativeModule(targetFile, routeGroup.file)}";`,
+    );
+  }
+
+  const nextFirstArg = firstDefineRoutesArgInfo(next);
+  if (!nextFirstArg?.text.startsWith("[")) return undefined;
+
+  const nextArray = appendToArrayExpression(
+    nextFirstArg.text,
+    groupsToAppend.map((routeGroup) => routeGroup.name),
+  );
+  next = `${next.slice(0, nextFirstArg.start)}${nextArray}${next.slice(
+    nextFirstArg.end,
+  )}`;
+  if (next === original) return undefined;
+
+  await writeFile(targetPath, next);
+  return {
+    code: "BEIGNET_ROUTE_GROUP_UNREGISTERED",
+    file: targetFile,
+    message: `Registered ${groupsToAppend
+      .map((routeGroup) => routeGroup.name)
+      .join(", ")} in the central route list.`,
+  };
+}
+
+function routeRegistryFileFromServerSource(
+  source: string,
+  serverFile: string,
+  files: string[],
+): string | undefined {
+  const imports = parseNamedImportSources(source);
+
+  for (const identifier of routeOptionIdentifiers(source)) {
+    const imported = imports.get(identifier);
+    if (!imported) continue;
+
+    const importedFile = sourceFileFromImport(
+      imported.sourcePath,
+      serverFile,
+      files,
+    );
+    if (importedFile && files.includes(importedFile)) return importedFile;
+  }
+
+  return undefined;
+}
+
 async function openApiContracts(
   targetDir: string,
   files: string[],
@@ -1313,6 +4095,16 @@ async function openApiContracts(
   const identifier = /^([A-Za-z_$][\w$]*)$/.exec(firstArg)?.[1];
   if (!identifier) return undefined;
 
+  const routeContracts = await contractsFromRoutesExport(
+    targetDir,
+    files,
+    config,
+    config.paths.openapiRoute,
+    source,
+    identifier,
+  );
+  if (routeContracts) return routeContracts;
+
   const imports = parseNamedImports(source, config);
   const imported = imports.get(identifier);
   const listFile = imported?.contractFile ?? config.paths.openapiRoute;
@@ -1324,20 +4116,143 @@ async function openApiContracts(
   );
 }
 
+async function contractsFromRoutesExport(
+  targetDir: string,
+  files: string[],
+  config: ResolvedBeignetConfig,
+  importerFile: string,
+  source: string,
+  identifier: string,
+): Promise<Set<string> | undefined> {
+  const localRouteContracts = await contractsFromRoutesSource(
+    targetDir,
+    files,
+    config,
+    importerFile,
+    source,
+    identifier,
+  );
+  if (localRouteContracts) return localRouteContracts;
+
+  const imports = parseNamedImportSources(source);
+  const imported = imports.get(identifier);
+  if (!imported) return undefined;
+
+  const importedFile = sourceFileFromImport(
+    imported.sourcePath,
+    importerFile,
+    files,
+  );
+  if (!importedFile || !files.includes(importedFile)) return undefined;
+
+  const importedSource = await readFile(path.join(targetDir, importedFile), {
+    encoding: "utf8",
+  });
+  return contractsFromRoutesSource(
+    targetDir,
+    files,
+    config,
+    importedFile,
+    importedSource,
+    imported.importedName,
+  );
+}
+
+async function contractsFromRoutesSource(
+  targetDir: string,
+  files: string[],
+  config: ResolvedBeignetConfig,
+  file: string,
+  source: string,
+  exportName: string,
+): Promise<Set<string> | undefined> {
+  const routeIdentifier = contractsFromRoutesIdentifier(source, exportName);
+  if (!routeIdentifier) return undefined;
+
+  const routeGroups = await readFeatureRouteGroups(targetDir, files, config);
+  const registeredGroups = await registeredRouteGroupsForSource(
+    targetDir,
+    files,
+    file,
+    source,
+    routeIdentifier,
+  );
+  const registeredContracts = contractsForRegisteredRouteGroups(
+    await readContracts(targetDir, files, config),
+    routeGroups,
+    registeredGroups,
+  );
+
+  return new Set(registeredContracts.map((contract) => contract.exportName));
+}
+
+function contractsFromRoutesIdentifier(
+  source: string,
+  exportName: string,
+): string | undefined {
+  return new RegExp(
+    `(?:export\\s+)?const\\s+${escapeRegExp(exportName)}\\s*=\\s*contractsFromRoutes(?:<[^>]+>)?\\(\\s*([A-Za-z_$][\\w$]*)\\s*\\)`,
+  ).exec(source)?.[1];
+}
+
+async function registeredRouteGroupsForSource(
+  targetDir: string,
+  files: string[],
+  file: string,
+  source: string,
+  routeIdentifier: string,
+): Promise<Set<string>> {
+  if (
+    new RegExp(
+      `(?:export\\s+)?const\\s+${escapeRegExp(routeIdentifier)}\\s*=\\s*defineRoutes`,
+    ).test(source)
+  ) {
+    return registeredRouteGroups(source);
+  }
+
+  const imports = parseNamedImportSources(source);
+  const imported = imports.get(routeIdentifier);
+  if (!imported) return registeredRouteGroups(source);
+
+  const importedFile = sourceFileFromImport(imported.sourcePath, file, files);
+  if (!importedFile || !files.includes(importedFile)) {
+    return registeredRouteGroups(source);
+  }
+
+  return registeredRouteGroups(
+    await readFile(path.join(targetDir, importedFile), "utf8"),
+  );
+}
+
 function firstCreateOpenAPIHandlerArg(source: string): string | undefined {
   return firstCreateOpenAPIHandlerArgInfo(source)?.text;
 }
 
+function firstDefineRoutesArgInfo(
+  source: string,
+): { text: string; start: number; end: number } | undefined {
+  const start = /defineRoutes(?:<[^>]+>)?\(/.exec(source);
+  if (!start) return undefined;
+
+  return firstCallArgInfo(source, start.index + start[0].length);
+}
+
 function firstCreateOpenAPIHandlerArgInfo(
   source: string,
 ): { text: string; start: number; end: number } | undefined {
   const start = source.indexOf("createOpenAPIHandler(");
   if (start === -1) return undefined;
 
+  return firstCallArgInfo(source, start + "createOpenAPIHandler(".length);
+}
+
+function firstCallArgInfo(
+  source: string,
+  argStart: number,
+): { text: string; start: number; end: number } | undefined {
   let depth = 0;
   let inString: string | undefined;
   let escaped = false;
-  const argStart = start + "createOpenAPIHandler(".length;
 
   for (let index = argStart; index < source.length; index++) {
     const char = source[index];
@@ -1441,6 +4356,24 @@ function appendToArrayExpression(expression: string, names: string[]): string {
   return `${trimmedBeforeClosingBracket},\n${itemIndent}${appendedNames}${closingBracketText}`;
 }
 
+function insertAfterImports(source: string, line: string): string {
+  const lines = source.split("\n");
+  let lastImportIndex = -1;
+
+  for (let index = 0; index < lines.length; index++) {
+    if (lines[index].startsWith("import ")) {
+      lastImportIndex = index;
+    }
+  }
+
+  if (lastImportIndex === -1) {
+    return `${line}\n${source}`;
+  }
+
+  lines.splice(lastImportIndex + 1, 0, line);
+  return lines.join("\n");
+}
+
 function hasImportedIdentifier(source: string, identifier: string): boolean {
   const importRegex = /import\s+\{([^}]+)\}\s+from\s+["'][^"']+["']/g;
 
@@ -1454,6 +4387,22 @@ function hasImportedIdentifier(source: string, identifier: string): boolean {
   return false;
 }
 
+function relativeModule(fromFile: string, toFile: string): string {
+  const fromDir = path.posix.dirname(normalizePath(fromFile));
+  const relative = path.posix.relative(fromDir, normalizePath(toFile));
+  const specifier = modulePath(relative);
+
+  if (specifier.startsWith("../")) return specifier;
+  if (specifier === "..") return specifier;
+  return specifier.startsWith(".") ? specifier : `./${specifier}`;
+}
+
+function modulePath(filePath: string): string {
+  return directoryPath(filePath)
+    .replace(/\.(?:[cm]?[jt]sx?)$/, "")
+    .replace(/\/index$/, "");
+}
+
 async function readContractLists(
   targetDir: string,
   files: string[],
@@ -1613,12 +4562,40 @@ async function inspectResourceSlices(
 
   for (const resource of resources) {
     const singular = singularize(resource);
+    const pluralCamel = camelCase(resource);
+    const singularPascal = pascalCase(singular);
     const contractFile = resourceContractFile(resource, config);
     const useCaseDir = resourceUseCaseDir(resource, config);
     const portFile = resourcePortFile(resource, singular, config);
+    const featureRouteFile = path.join(
+      config.paths.features,
+      resource,
+      "routes.ts",
+    );
+    const sharedErrorsFile = path.join(
+      config.paths.features,
+      "shared",
+      "errors.ts",
+    );
     const infrastructureDir = `${directoryPath(
       path.dirname(config.paths.infrastructurePorts),
     )}/${resource}/`;
+    const drizzleSchemaFile = path.join(
+      path.dirname(config.paths.infrastructurePorts),
+      "db",
+      "schema",
+      `${resource}.ts`,
+    );
+    const drizzleRepositoryFile = path.join(
+      path.dirname(config.paths.infrastructurePorts),
+      resource,
+      `drizzle-${singular}-repository.ts`,
+    );
+    const memoryRepositoryFile = path.join(
+      path.dirname(config.paths.infrastructurePorts),
+      resource,
+      `in-memory-${singular}-repository.ts`,
+    );
     const routeFile = path.join(config.paths.routes, resource, "route.ts");
     const catchAllRouteFile = path.join(
       config.paths.routes,
@@ -1630,7 +4607,7 @@ async function inspectResourceSlices(
     if (!hasRequirement(files, contractFile)) {
       diagnostics.push(
         resourceDiagnostic(
-          "CK_RESOURCE_CONTRACT_MISSING",
+          "BEIGNET_RESOURCE_CONTRACT_MISSING",
           resource,
           contractFile,
         ),
@@ -1639,7 +4616,7 @@ async function inspectResourceSlices(
     if (!hasRequirement(files, useCaseDir)) {
       diagnostics.push(
         resourceDiagnostic(
-          "CK_RESOURCE_USE_CASES_MISSING",
+          "BEIGNET_RESOURCE_USE_CASES_MISSING",
           resource,
           useCaseDir,
         ),
@@ -1647,13 +4624,13 @@ async function inspectResourceSlices(
     }
     if (!hasRequirement(files, portFile)) {
       diagnostics.push(
-        resourceDiagnostic("CK_RESOURCE_PORT_MISSING", resource, portFile),
+        resourceDiagnostic("BEIGNET_RESOURCE_PORT_MISSING", resource, portFile),
       );
     }
     if (!hasRequirement(files, infrastructureDir)) {
       diagnostics.push(
         resourceDiagnostic(
-          "CK_RESOURCE_INFRASTRUCTURE_MISSING",
+          "BEIGNET_RESOURCE_INFRASTRUCTURE_MISSING",
           resource,
           infrastructureDir,
         ),
@@ -1664,20 +4641,271 @@ async function inspectResourceSlices(
       !hasRequirement(files, catchAllRouteFile)
     ) {
       diagnostics.push(
-        resourceDiagnostic("CK_RESOURCE_ROUTE_MISSING", resource, routeFile),
+        resourceDiagnostic(
+          "BEIGNET_RESOURCE_ROUTE_MISSING",
+          resource,
+          routeFile,
+        ),
       );
     }
     if (strict && !hasRequirement(files, testFile)) {
       diagnostics.push({
-        ...resourceDiagnostic("CK_RESOURCE_TEST_MISSING", resource, testFile),
+        ...resourceDiagnostic(
+          "BEIGNET_RESOURCE_TEST_MISSING",
+          resource,
+          testFile,
+        ),
+        severity: "warning",
+      });
+    }
+
+    const contractSource = await readSourceIfPresent(
+      targetDir,
+      files,
+      contractFile,
+    );
+    const portSource = await readSourceIfPresent(targetDir, files, portFile);
+    const routeSource = await readSourceIfPresent(
+      targetDir,
+      files,
+      featureRouteFile,
+    );
+    const testSource = await readSourceIfPresent(targetDir, files, testFile);
+    const drizzleSchemaSource = await readSourceIfPresent(
+      targetDir,
+      files,
+      drizzleSchemaFile,
+    );
+    const drizzleRepositorySource = await readSourceIfPresent(
+      targetDir,
+      files,
+      drizzleRepositoryFile,
+    );
+    const memoryRepositorySource = await readSourceIfPresent(
+      targetDir,
+      files,
+      memoryRepositoryFile,
+    );
+    const sharedErrorsSource = await readSourceIfPresent(
+      targetDir,
+      files,
+      sharedErrorsFile,
+    );
+    const crudUseCaseFiles = [
+      path.join(useCaseDir, `get-${singular}.ts`),
+      path.join(useCaseDir, `update-${singular}.ts`),
+      path.join(useCaseDir, `delete-${singular}.ts`),
+    ];
+    const hasCrudSignals =
+      crudUseCaseFiles.slice(1).some((file) => files.includes(file)) ||
+      sourceIncludesAny(contractSource, [
+        `export const update${singularPascal}`,
+        `export const delete${singularPascal}`,
+      ]) ||
+      sourceIncludesAny(portSource, [
+        `update(input: Update${singularPascal}Input)`,
+        `update(input: Update${singularPascal}RepositoryInput)`,
+        "delete(id: string): Promise<boolean>",
+      ]);
+
+    if (!hasCrudSignals) continue;
+
+    for (const exportName of [
+      `get${singularPascal}`,
+      `update${singularPascal}`,
+      `delete${singularPascal}`,
+    ]) {
+      if (contractSource?.includes(`export const ${exportName}`)) continue;
+
+      diagnostics.push({
+        severity: "error",
+        code: "BEIGNET_RESOURCE_CONTRACT_EXPORT_MISSING",
+        file: contractFile,
+        contract: exportName,
+        message: `${resource} appears to be a CRUD resource, but ${contractFile} does not export ${exportName}. Restore the generated ${exportName} contract or remove the partial CRUD wiring.`,
+      });
+    }
+
+    for (const file of crudUseCaseFiles) {
+      if (files.includes(file)) continue;
+
+      diagnostics.push({
+        severity: "error",
+        code: "BEIGNET_RESOURCE_CRUD_USE_CASE_MISSING",
+        file,
+        message: `${resource} appears to be a CRUD resource, but ${file} is missing. Restore the generated CRUD use case or remove the partial CRUD wiring.`,
+      });
+    }
+
+    const expectedRepositoryMethods = [
+      {
+        display: `findById(id: string): Promise<${singularPascal} | null>`,
+        alternatives: [
+          `findById(id: string): Promise<${singularPascal} | null>`,
+          `findById(id: string, filter: ${singularPascal}TenantFilter): Promise<${singularPascal} | null>`,
+        ],
+      },
+      {
+        display: `update(input: Update${singularPascal}Input)`,
+        alternatives: [
+          `update(input: Update${singularPascal}Input)`,
+          `update(input: Update${singularPascal}RepositoryInput)`,
+        ],
+      },
+      {
+        display: "delete(id: string): Promise<boolean>",
+        alternatives: [
+          "delete(id: string): Promise<boolean>",
+          `delete(id: string, filter: ${singularPascal}TenantFilter): Promise<boolean>`,
+        ],
+      },
+    ];
+
+    for (const method of expectedRepositoryMethods) {
+      if (sourceIncludesAny(portSource, method.alternatives)) continue;
+
+      diagnostics.push({
+        severity: "error",
+        code: "BEIGNET_RESOURCE_REPOSITORY_METHOD_MISSING",
+        file: portFile,
+        message: `${resource} appears to be a CRUD resource, but ${portFile} does not declare ${method.display}. Restore the generated repository method or remove the partial CRUD wiring.`,
+      });
+    }
+
+    for (const exportName of [
+      `get${singularPascal}`,
+      `update${singularPascal}`,
+      `delete${singularPascal}`,
+    ]) {
+      if (routeSource?.includes(`contract: ${exportName}`)) continue;
+
+      diagnostics.push({
+        severity: "error",
+        code: "BEIGNET_RESOURCE_ROUTE_CONTRACT_MISSING",
+        file: featureRouteFile,
+        contract: exportName,
+        message: `${resource} appears to be a CRUD resource, but ${featureRouteFile} does not route ${exportName}. Add the contract to the feature route group or remove the partial CRUD wiring.`,
+      });
+    }
+
+    const notFoundError = `${singularPascal}NotFound`;
+    const conflictError = `${singularPascal}Conflict`;
+    if (!sharedErrorsSource?.includes(notFoundError)) {
+      diagnostics.push({
+        severity: "error",
+        code: "BEIGNET_RESOURCE_ERROR_CATALOG_MISSING",
+        file: sharedErrorsFile,
+        message: `${resource} appears to be a CRUD resource, but ${sharedErrorsFile} does not declare ${notFoundError}. Add the generated not-found catalog error or remove the partial CRUD wiring.`,
+      });
+    }
+    if (!sharedErrorsSource?.includes(conflictError)) {
+      diagnostics.push({
+        severity: "error",
+        code: "BEIGNET_RESOURCE_ERROR_CATALOG_MISSING",
+        file: sharedErrorsFile,
+        message: `${resource} appears to be a CRUD resource, but ${sharedErrorsFile} does not declare ${conflictError}. Add the generated conflict catalog error or remove the partial CRUD wiring.`,
+      });
+    }
+
+    if (
+      strict &&
+      testSource &&
+      !sourceIncludesAll(testSource, [
+        `get${singularPascal}`,
+        `update${singularPascal}`,
+        `delete${singularPascal}`,
+        `${notFoundError}`,
+        `${conflictError}`,
+      ])
+    ) {
+      diagnostics.push({
         severity: "warning",
+        code: "BEIGNET_RESOURCE_CRUD_TEST_COVERAGE_MISSING",
+        file: testFile,
+        message: `${resource} appears to be a CRUD resource, but ${testFile} does not exercise get, update, delete, ${notFoundError}, and ${conflictError}. Expand the generated resource test or remove the partial CRUD wiring.`,
       });
     }
+
+    const hasDrizzleSoftDeleteSignals =
+      sourceIncludesAny(drizzleSchemaSource, ["deletedAt", "deleted_at"]) ||
+      sourceIncludesAny(drizzleRepositorySource, ["deletedAt", "isNull"]);
+    const hasSoftDeleteSignals =
+      hasDrizzleSoftDeleteSignals ||
+      sourceIncludesAny(memoryRepositorySource, ["deletedAt"]);
+
+    if (hasSoftDeleteSignals) {
+      if (hasDrizzleSoftDeleteSignals) {
+        if (
+          !sourceIncludesAny(drizzleSchemaSource, ["deletedAt", "deleted_at"])
+        ) {
+          diagnostics.push({
+            severity: "error",
+            code: "BEIGNET_RESOURCE_SOFT_DELETE_SCHEMA_MISSING",
+            file: drizzleSchemaFile,
+            message: `${resource} appears to use soft delete, but ${drizzleSchemaFile} does not declare deletedAt. Restore the generated deletedAt column or remove the partial soft-delete wiring.`,
+          });
+        }
+
+        if (
+          !sourceIncludesAll(drizzleRepositorySource ?? "", [
+            "isNull",
+            "deletedAt",
+            `.update(schema.${pluralCamel})`,
+          ])
+        ) {
+          diagnostics.push({
+            severity: "error",
+            code: "BEIGNET_RESOURCE_SOFT_DELETE_REPOSITORY_DRIFT",
+            file: drizzleRepositoryFile,
+            message: `${resource} appears to use soft delete, but ${drizzleRepositoryFile} does not consistently filter active rows and archive deletes. Restore the generated soft-delete repository behavior or remove the partial soft-delete wiring.`,
+          });
+        }
+      }
+
+      if (
+        strict &&
+        testSource &&
+        !sourceIncludesAll(testSource, [
+          "afterDelete",
+          "listedAfterDeleteViaRoute",
+        ])
+      ) {
+        diagnostics.push({
+          severity: "warning",
+          code: "BEIGNET_RESOURCE_SOFT_DELETE_TEST_COVERAGE_MISSING",
+          file: testFile,
+          message: `${resource} appears to use soft delete, but ${testFile} does not assert that deleted records disappear from reads. Expand the generated resource test or remove the partial soft-delete wiring.`,
+        });
+      }
+    }
   }
 
   return diagnostics;
 }
 
+async function readSourceIfPresent(
+  targetDir: string,
+  files: string[],
+  file: string,
+): Promise<string | undefined> {
+  if (!files.includes(file)) return undefined;
+  return readFile(path.join(targetDir, file), "utf8");
+}
+
+function sourceIncludesAny(
+  source: string | undefined,
+  snippets: readonly string[],
+): boolean {
+  return source ? snippets.some((snippet) => source.includes(snippet)) : false;
+}
+
+function sourceIncludesAll(
+  source: string,
+  snippets: readonly string[],
+): boolean {
+  return snippets.every((snippet) => source.includes(snippet));
+}
+
 async function collectResourceNames(
   targetDir: string,
   files: string[],
@@ -1742,11 +4970,16 @@ async function isGeneratedResourcePort(
   const singular = singularize(resource);
   const singularPascal = pascalCase(singular);
   const pluralPascal = pascalCase(resource);
+  const hasCursorList =
+    source.includes("CursorPage") &&
+    source.includes(`list(query: List${pluralPascal}Query)`);
+  const hasOffsetList =
+    source.includes("OffsetPage") && source.includes("list(page: OffsetPage)");
 
   return (
     source.includes(`Create${singularPascal}Input`) &&
-    source.includes(`List${pluralPascal}Input`) &&
     source.includes(`List${pluralPascal}Result`) &&
+    (hasCursorList || hasOffsetList) &&
     source.includes(`interface ${singularPascal}Repository`) &&
     source.includes(`create(input: Create${singularPascal}Input)`)
   );
@@ -1853,7 +5086,7 @@ function resourceDiagnostic(
     severity: "error",
     code,
     file,
-    message: `${resource} appears to be a generated resource slice, but ${file} is missing. Re-run make resource ${resource}, restore the missing file, or remove the partial resource wiring.`,
+    message: `${resource} appears to be a generated feature slice, but ${file} is missing. Re-run make feature ${resource}, restore the missing file, or remove the partial feature wiring.`,
   };
 }
 
@@ -1893,6 +5126,11 @@ function pascalCase(value: string): string {
     .join("");
 }
 
+function camelCase(value: string): string {
+  const pascal = pascalCase(value);
+  return `${pascal.charAt(0).toLowerCase()}${pascal.slice(1)}`;
+}
+
 function singularize(value: string): string {
   if (value.endsWith("ies") && value.length > 3) {
     return `${value.slice(0, -3)}y`;