@screenbook/cli 1.7.1 → 1.8.0

package/dist/index.mjs

@@ -51,7 +51,7 @@ const ERRORS = {
 	ROUTES_PATTERN_MISSING: {
 		title: "Routes configuration not found",
 		suggestion: "Add routesPattern (for file-based routing) or routesFile (for config-based routing) to your screenbook.config.ts.",
-		example: `import { defineConfig } from "@screenbook/core"
+		example: `import { defineConfig } from "screenbook"
 
 // Option 1: File-based routing (Next.js, Nuxt, etc.)
 export default defineConfig({
@@ -66,7 +66,7 @@ export default defineConfig({
 	ROUTES_FILE_NOT_FOUND: (filePath) => ({
 		title: `Routes file not found: ${filePath}`,
 		suggestion: "Check the routesFile path in your screenbook.config.ts. The file should export a routes array.",
-		example: `import { defineConfig } from "@screenbook/core"
+		example: `import { defineConfig } from "screenbook"
 
 export default defineConfig({
   routesFile: "src/router/routes.ts",  // Make sure this file exists
@@ -80,7 +80,7 @@ export default defineConfig({
 	CONFIG_NOT_FOUND: {
 		title: "Configuration file not found",
 		suggestion: "Run 'screenbook init' to create a screenbook.config.ts file, or create one manually.",
-		example: `import { defineConfig } from "@screenbook/core"
+		example: `import { defineConfig } from "screenbook"
 
 export default defineConfig({
   metaPattern: "src/**/screen.meta.ts",
@@ -107,7 +107,7 @@ export default defineConfig({
 	META_FILE_LOAD_ERROR: (filePath) => ({
 		title: `Failed to load ${filePath}`,
 		suggestion: "Check the file for syntax errors or missing exports. The file should export a 'screen' object.",
-		example: `import { defineScreen } from "@screenbook/core"
+		example: `import { defineScreen } from "screenbook"
 
 export const screen = defineScreen({
   id: "example.screen",
@@ -194,6 +194,12 @@ function setVerbose(verbose) {
 	verboseMode = verbose;
 }
 /**
+* Check if verbose mode is enabled
+*/
+function isVerbose() {
+	return verboseMode;
+}
+/**
 * Logger utility for consistent, color-coded CLI output
 */
 const logger = {
@@ -239,6 +245,25 @@ const logger = {
 		}
 		console.error();
 	},
+	warnWithHelp: (options) => {
+		const { title, message, details, suggestions } = options;
+		console.log();
+		console.log(`${pc.yellow("⚠")} ${pc.yellow(`Warning: ${title}`)}`);
+		if (message) {
+			console.log();
+			console.log(`  ${message}`);
+		}
+		if (details && details.length > 0) {
+			console.log("  This means:");
+			for (const detail of details) console.log(`  ${pc.dim("•")} ${detail}`);
+		}
+		if (suggestions && suggestions.length > 0) {
+			console.log();
+			console.log(`  ${pc.cyan("To fix this, either:")}`);
+			for (let i = 0; i < suggestions.length; i++) console.log(`  ${i + 1}. ${suggestions[i]}`);
+		}
+		console.log();
+	},
 	step: (msg) => {
 		console.log(`${pc.dim("→")} ${msg}`);
 	},
@@ -1283,6 +1308,22 @@ function displayResults(results, verbose) {
 //#endregion
 //#region src/utils/routeParserUtils.ts
 /**
+* Create a spread warning from an AST element.
+* Extracts line number and variable name for better error messages.
+* @param element - AST element (SpreadElement)
+* @returns SpreadWarning object
+*/
+function createSpreadWarning(element) {
+	const line = element.loc?.start.line;
+	const variableName = element.argument?.type === "Identifier" ? element.argument.name : void 0;
+	return {
+		type: "spread",
+		message: `Spread operator detected${line ? ` at line ${line}` : ""}`,
+		line,
+		variableName
+	};
+}
+/**
 * Resolve relative import path to absolute path
 */
 function resolveImportPath(importPath, baseDir) {
@@ -1292,7 +1333,7 @@ function resolveImportPath(importPath, baseDir) {
 /**
 * Flatten nested routes into a flat list with computed properties
 */
-function flattenRoutes(routes, parentPath = "", depth = 0) {
+function flattenRoutes(routes, parentPath = "", depth = 0, options = {}) {
 	const result = [];
 	for (const route of routes) {
 		if (route.redirect && !route.component) continue;
@@ -1303,32 +1344,104 @@ function flattenRoutes(routes, parentPath = "", depth = 0) {
 		fullPath = fullPath.replace(/\/+/g, "/");
 		if (fullPath !== "/" && fullPath.endsWith("/")) fullPath = fullPath.slice(0, -1);
 		if (fullPath === "") fullPath = parentPath || "/";
-		if (route.component || !route.children) result.push({
-			fullPath,
-			name: route.name,
-			componentPath: route.component,
-			screenId: pathToScreenId(fullPath),
-			screenTitle: pathToScreenTitle(fullPath),
-			depth
-		});
-		if (route.children) result.push(...flattenRoutes(route.children, fullPath, depth + 1));
+		if (route.component || !route.children) {
+			const { screenId, suggestions } = pathToScreenId(fullPath, options);
+			result.push({
+				fullPath,
+				name: route.name,
+				componentPath: route.component,
+				screenId,
+				screenTitle: pathToScreenTitle(fullPath),
+				depth,
+				suggestions
+			});
+		}
+		if (route.children) result.push(...flattenRoutes(route.children, fullPath, depth + 1, options));
 	}
 	return result;
 }
 /**
-* Convert route path to screen ID
-* /user/:id/profile -> user.id.profile
+* Action segments that provide semantic context.
+* When a parameter is followed by one of these, the parameter is preserved.
+*/
+const ACTION_SEGMENTS = new Set([
+	"edit",
+	"new",
+	"create",
+	"delete",
+	"settings",
+	"view",
+	"update"
+]);
+/**
+* Check if a segment is an action segment
+*/
+function isActionSegment(segment) {
+	return segment !== void 0 && ACTION_SEGMENTS.has(segment.toLowerCase());
+}
+/**
+* Infer semantic alternatives for a parameter
 */
-function pathToScreenId(path) {
-	if (path === "/" || path === "") return "home";
-	return path.replace(/^\//, "").replace(/\/$/, "").split("/").map((segment) => {
-		if (segment.startsWith(":")) return segment.slice(1);
-		if (segment.startsWith("*")) {
-			if (segment === "**") return "catchall";
-			return segment.slice(1) || "catchall";
+function inferSemanticAlternatives(param, isLast) {
+	const alternatives = [];
+	if (isLast) alternatives.push("detail", "view");
+	const entityMatch = param.match(/^:(\w+)Id$/i);
+	if (entityMatch?.[1]) alternatives.push(entityMatch[1].toLowerCase());
+	return alternatives;
+}
+/**
+* Resolve a parameter segment to a screen ID segment
+*/
+function resolveParameter(segment, isLastSegment, nextSegment, options) {
+	const mappingKey = segment;
+	if (options.parameterMapping?.[mappingKey]) return { resolved: options.parameterMapping[mappingKey] };
+	if (options.smartParameterNaming) {
+		if (segment === ":id" && isLastSegment) return { resolved: "detail" };
+		const entityMatch = segment.match(/^:(\w+)Id$/i);
+		if (entityMatch?.[1] && isLastSegment) return { resolved: entityMatch[1].toLowerCase() };
+		if (!isLastSegment && isActionSegment(nextSegment)) return { resolved: segment.slice(1) };
+		if (segment === ":id" && !isActionSegment(nextSegment)) return { resolved: "detail" };
+	}
+	const cleanParam = segment.slice(1);
+	switch (options.unmappedParameterStrategy) {
+		case "detail": return { resolved: "detail" };
+		case "warn": {
+			const alternatives = inferSemanticAlternatives(segment, isLastSegment);
+			return {
+				resolved: cleanParam,
+				suggestion: alternatives.length > 0 ? `Consider renaming to: ${alternatives.join(", ")}` : void 0
+			};
 		}
-		return segment;
-	}).join(".");
+		default: return { resolved: cleanParam };
+	}
+}
+/**
+* Convert route path to screen ID with options
+* /user/:id/profile -> user.id.profile (default)
+* /user/:id/profile -> user.detail.profile (with smartParameterNaming)
+*/
+function pathToScreenId(path, options = {}) {
+	if (path === "/" || path === "") return { screenId: "home" };
+	const segments = path.replace(/^\//, "").replace(/\/$/, "").split("/");
+	const resolvedSegments = [];
+	const allSuggestions = [];
+	for (let i = 0; i < segments.length; i++) {
+		const segment = segments[i];
+		if (!segment) continue;
+		const isLast = i === segments.length - 1;
+		const nextSegment = segments[i + 1];
+		if (segment.startsWith(":")) {
+			const { resolved, suggestion } = resolveParameter(segment, isLast, nextSegment, options);
+			resolvedSegments.push(resolved);
+			if (suggestion) allSuggestions.push(suggestion);
+		} else if (segment.startsWith("*")) if (segment === "**") resolvedSegments.push("catchall");
+		else resolvedSegments.push(segment.slice(1) || "catchall");
+		else resolvedSegments.push(segment);
+	}
+	return {
+		screenId: resolvedSegments.join("."),
+		suggestions: allSuggestions.length > 0 ? allSuggestions : void 0
+	};
 }
 /**
 * Convert route path to screen title
@@ -1426,7 +1539,10 @@ function parseAngularRouterConfig(filePath, preloadedContent) {
 			routes.push(...routesFromExpr);
 		}
 	}
-	if (routes.length === 0) warnings.push("No routes found. Supported patterns: 'export const routes: Routes = [...]', 'RouterModule.forRoot([...])', or 'RouterModule.forChild([...])'");
+	if (routes.length === 0) warnings.push({
+		type: "general",
+		message: "No routes found. Supported patterns: 'export const routes: Routes = [...]', 'RouterModule.forRoot([...])', or 'RouterModule.forChild([...])'"
+	});
 	return {
 		routes,
 		warnings
@@ -1475,16 +1591,19 @@ function parseRoutesArray$3(arrayNode, baseDir, warnings) {
 	for (const element of arrayNode.elements) {
 		if (!element) continue;
 		if (element.type === "SpreadElement") {
-			const loc = element.loc ? ` at line ${element.loc.start.line}` : "";
-			warnings.push(`Spread operator detected${loc}. Routes from spread cannot be statically analyzed.`);
+			warnings.push(createSpreadWarning(element));
 			continue;
 		}
 		if (element.type === "ObjectExpression") {
 			const parsedRoute = parseRouteObject$3(element, baseDir, warnings);
 			if (parsedRoute) routes.push(parsedRoute);
 		} else {
-			const loc = element.loc ? ` at line ${element.loc.start.line}` : "";
-			warnings.push(`Non-object route element (${element.type})${loc}. Only object literals can be statically analyzed.`);
+			const line = element.loc?.start.line;
+			warnings.push({
+				type: "general",
+				message: `Non-object route element (${element.type})${line ? ` at line ${line}` : ""}. Only object literals can be statically analyzed.`,
+				line
+			});
 		}
 	}
 	return routes;
@@ -1507,8 +1626,12 @@ function parseRouteObject$3(objectNode, baseDir, warnings) {
 					path = prop.value.value;
 					hasPath = true;
 				} else {
-					const loc = prop.loc ? ` at line ${prop.loc.start.line}` : "";
-					warnings.push(`Dynamic path value (${prop.value.type})${loc}. Only string literal paths can be statically analyzed.`);
+					const line = prop.loc?.start.line;
+					warnings.push({
+						type: "general",
+						message: `Dynamic path value (${prop.value.type})${line ? ` at line ${line}` : ""}. Only string literal paths can be statically analyzed.`,
+						line
+					});
 				}
 				break;
 			case "component":
@@ -1571,20 +1694,32 @@ function extractLazyComponent(node, baseDir, warnings) {
 					if (thenArg?.type === "ArrowFunctionExpression" && thenArg.body?.type === "MemberExpression" && thenArg.body.property?.type === "Identifier") return `${importPath}#${thenArg.body.property.name}`;
 					return importPath;
 				}
-				const loc$1 = node.loc ? ` at line ${node.loc.start.line}` : "";
-				warnings.push(`Lazy loadComponent with dynamic path${loc$1}. Only string literal imports can be analyzed.`);
+				const line$1 = node.loc?.start.line;
+				warnings.push({
+					type: "general",
+					message: `Lazy loadComponent with dynamic path${line$1 ? ` at line ${line$1}` : ""}. Only string literal imports can be analyzed.`,
+					line: line$1
+				});
 				return;
 			}
 		}
 		if (body.type === "CallExpression" && body.callee?.type === "Import") {
 			if (body.arguments[0]?.type === "StringLiteral") return resolveImportPath(body.arguments[0].value, baseDir);
-			const loc$1 = node.loc ? ` at line ${node.loc.start.line}` : "";
-			warnings.push(`Lazy loadComponent with dynamic path${loc$1}. Only string literal imports can be analyzed.`);
+			const line$1 = node.loc?.start.line;
+			warnings.push({
+				type: "general",
+				message: `Lazy loadComponent with dynamic path${line$1 ? ` at line ${line$1}` : ""}. Only string literal imports can be analyzed.`,
+				line: line$1
+			});
 			return;
 		}
 	}
-	const loc = node.loc ? ` at line ${node.loc.start.line}` : "";
-	warnings.push(`Unrecognized loadComponent pattern (${node.type})${loc}. Expected arrow function with import().then().`);
+	const line = node.loc?.start.line;
+	warnings.push({
+		type: "general",
+		message: `Unrecognized loadComponent pattern (${node.type})${line ? ` at line ${line}` : ""}. Expected arrow function with import().then().`,
+		line
+	});
 }
 /**
 * Extract path from lazy loadChildren pattern
@@ -1601,8 +1736,12 @@ function extractLazyPath(node, baseDir, warnings) {
 			if (body.arguments[0]?.type === "StringLiteral") return resolveImportPath(body.arguments[0].value, baseDir);
 		}
 	}
-	const loc = node.loc ? ` at line ${node.loc.start.line}` : "";
-	warnings.push(`Unrecognized loadChildren pattern (${node.type})${loc}. Expected arrow function with import().`);
+	const line = node.loc?.start.line;
+	warnings.push({
+		type: "general",
+		message: `Unrecognized loadChildren pattern (${node.type})${line ? ` at line ${line}` : ""}. Expected arrow function with import().`,
+		line
+	});
 }
 /**
 * Detect if content is Angular Router based on patterns.
@@ -1625,7 +1764,7 @@ function createDetectedNavigation(path, type, line) {
 	const pathWithoutQuery = path.split("?")[0] ?? path;
 	return {
 		path,
-		screenId: pathToScreenId(pathWithoutQuery.split("#")[0] ?? pathWithoutQuery),
+		screenId: pathToScreenId(pathWithoutQuery.split("#")[0] ?? pathWithoutQuery).screenId,
 		type,
 		line
 	};
@@ -2220,6 +2359,133 @@ function isMatchingPackage(source, clientPackages) {
 	return false;
 }
 
+//#endregion
+//#region src/utils/constants.ts
+/**
+* Default patterns to exclude from route file scanning.
+* These directories typically contain reusable components, not navigable screens.
+* @see https://github.com/wadakatu/screenbook/issues/170
+* @see https://github.com/wadakatu/screenbook/issues/190
+*/
+const DEFAULT_EXCLUDE_PATTERNS = [
+	"**/components/**",
+	"**/shared/**",
+	"**/utils/**",
+	"**/hooks/**",
+	"**/composables/**",
+	"**/stores/**",
+	"**/services/**",
+	"**/helpers/**",
+	"**/lib/**",
+	"**/common/**"
+];
+/**
+* Check if a path matches any of the exclude patterns.
+* Used by both generate and lint commands for consistent behavior.
+*/
+function matchesExcludePattern(filePath, excludePatterns) {
+	for (const pattern of excludePatterns) {
+		const cleanPattern = pattern.replace(/\*\*/g, "").replace(/\*/g, "").replace(/^\//, "").replace(/\/$/, "");
+		if (cleanPattern && filePath.includes(`/${cleanPattern}/`)) return true;
+		if (cleanPattern && filePath.startsWith(`${cleanPattern}/`)) return true;
+	}
+	return false;
+}
+
+//#endregion
+//#region src/utils/displayWarnings.ts
+/**
+* Display structured warnings with appropriate formatting
+* @param warnings - Array of parsed warnings
+* @param options - Display options
+* @returns Result containing warning counts and whether any were displayed
+*/
+function displayWarnings(warnings, options = {}) {
+	const { spreadOperatorSetting = "warn" } = options;
+	let spreadCount = 0;
+	let generalCount = 0;
+	for (const warning of warnings) if (warning.type === "spread") {
+		if (spreadOperatorSetting === "off") continue;
+		spreadCount++;
+		const varPart = warning.variableName ? `'${warning.variableName}'` : "spread variable";
+		if (spreadOperatorSetting === "error") {
+			logger.error(warning.message);
+			logger.blank();
+			logger.log("  Routes from spread operators cannot be statically analyzed by screenbook.");
+			logger.log("  This means:");
+			logger.log(`  ${logger.dim("•")} screenbook won't detect missing screen.meta.ts for routes in ${varPart}`);
+			logger.log(`  ${logger.dim("•")} These routes may appear to pass lint even without screen.meta.ts files`);
+			logger.blank();
+		} else logger.warnWithHelp({
+			title: warning.message,
+			message: "Routes from spread operators cannot be statically analyzed by screenbook.",
+			details: [`screenbook won't detect missing screen.meta.ts for routes in ${varPart}`, "These routes may appear to pass lint even without screen.meta.ts files"],
+			suggestions: [
+				"Inline the routes directly in the main routes array",
+				"Manually ensure screen.meta.ts files exist for the spread routes",
+				"Ignore this warning if you're OK with manual coverage tracking"
+			]
+		});
+	} else {
+		generalCount++;
+		logger.warn(warning.message);
+	}
+	return {
+		hasWarnings: spreadCount > 0 || generalCount > 0,
+		spreadCount,
+		generalCount,
+		shouldFailLint: spreadOperatorSetting === "error" && spreadCount > 0
+	};
+}
+/**
+* Display warnings for generate command (slightly different messaging)
+* @param warnings - Array of parsed warnings
+* @param options - Display options
+* @returns Result containing warning counts and whether any were displayed
+*/
+function displayGenerateWarnings(warnings, options = {}) {
+	const { spreadOperatorSetting = "warn" } = options;
+	let spreadCount = 0;
+	let generalCount = 0;
+	let suppressedCount = 0;
+	for (const warning of warnings) if (warning.type === "spread") {
+		if (spreadOperatorSetting === "off") {
+			suppressedCount++;
+			continue;
+		}
+		spreadCount++;
+		const varPart = warning.variableName ? `'${warning.variableName}'` : "spread variable";
+		if (spreadOperatorSetting === "error") {
+			logger.error(warning.message);
+			logger.blank();
+			logger.log("  Routes from spread operators cannot be statically analyzed by screenbook.");
+			logger.log("  This means:");
+			logger.log(`  ${logger.dim("•")} screenbook won't auto-generate screen.meta.ts for routes in ${varPart}`);
+			logger.log(`  ${logger.dim("•")} You'll need to manually create screen.meta.ts files for these routes`);
+			logger.blank();
+		} else logger.warnWithHelp({
+			title: warning.message,
+			message: "Routes from spread operators cannot be statically analyzed by screenbook.",
+			details: [`screenbook won't auto-generate screen.meta.ts for routes in ${varPart}`, "You'll need to manually create screen.meta.ts files for these routes"],
+			suggestions: [
+				"Inline the routes directly in the main routes array",
+				"Manually create screen.meta.ts files for the spread routes",
+				"Ignore this warning if you're OK with manual screen metadata"
+			]
+		});
+	} else {
+		generalCount++;
+		logger.warn(warning.message);
+	}
+	if (suppressedCount > 0) logger.log(logger.dim(`  (${suppressedCount} spread operator warning(s) suppressed by configuration)`));
+	return {
+		hasWarnings: spreadCount > 0 || generalCount > 0,
+		spreadCount,
+		generalCount,
+		shouldFailLint: spreadOperatorSetting === "error" && spreadCount > 0
+	};
+}
+
 //#endregion
 //#region src/utils/solidRouterParser.ts
 /**
@@ -2278,7 +2544,10 @@ function parseSolidRouterConfig(filePath, preloadedContent) {
 			routes.push(...parsed);
 		}
 	}
-	if (routes.length === 0) warnings.push("No routes found. Supported patterns: 'export const routes = [...]' or 'export default [...]'");
+	if (routes.length === 0) warnings.push({
+		type: "general",
+		message: "No routes found. Supported patterns: 'export const routes = [...]' or 'export default [...]'"
+	});
 	return {
 		routes,
 		warnings
@@ -2292,16 +2561,19 @@ function parseRoutesArray$2(arrayNode, baseDir, warnings) {
 	for (const element of arrayNode.elements) {
 		if (!element) continue;
 		if (element.type === "SpreadElement") {
-			const loc = element.loc ? ` at line ${element.loc.start.line}` : "";
-			warnings.push(`Spread operator detected${loc}. Routes from spread cannot be statically analyzed.`);
+			warnings.push(createSpreadWarning(element));
 			continue;
 		}
 		if (element.type === "ObjectExpression") {
 			const parsedRoutes = parseRouteObject$2(element, baseDir, warnings);
 			routes.push(...parsedRoutes);
 		} else {
-			const loc = element.loc ? ` at line ${element.loc.start.line}` : "";
-			warnings.push(`Non-object route element (${element.type})${loc}. Only object literals can be statically analyzed.`);
+			const line = element.loc?.start.line;
+			warnings.push({
+				type: "general",
+				message: `Non-object route element (${element.type})${line ? ` at line ${line}` : ""}. Only object literals can be statically analyzed.`,
+				line
+			});
 		}
 	}
 	return routes;
@@ -2328,12 +2600,20 @@ function parseRouteObject$2(objectNode, baseDir, warnings) {
 					paths = extractPathArray(prop.value, warnings);
 					hasPath = paths.length > 0;
 					if (arrayElementCount > 0 && paths.length === 0) {
-						const loc = prop.loc ? ` at line ${prop.loc.start.line}` : "";
-						warnings.push(`Path array contains only dynamic values${loc}. No static paths could be extracted.`);
+						const line = prop.loc?.start.line;
+						warnings.push({
+							type: "general",
+							message: `Path array contains only dynamic values${line ? ` at line ${line}` : ""}. No static paths could be extracted.`,
+							line
+						});
 					}
 				} else {
-					const loc = prop.loc ? ` at line ${prop.loc.start.line}` : "";
-					warnings.push(`Dynamic path value (${prop.value.type})${loc}. Only string literal paths can be statically analyzed.`);
+					const line = prop.loc?.start.line;
+					warnings.push({
+						type: "general",
+						message: `Dynamic path value (${prop.value.type})${line ? ` at line ${line}` : ""}. Only string literal paths can be statically analyzed.`,
+						line
+					});
 				}
 				break;
 			case "component":
@@ -2368,8 +2648,12 @@ function extractPathArray(arrayNode, warnings) {
 		if (!element) continue;
 		if (element.type === "StringLiteral") paths.push(element.value);
 		else {
-			const loc = element.loc ? ` at line ${element.loc.start.line}` : "";
-			warnings.push(`Non-string path in array (${element.type})${loc}. Only string literal paths can be analyzed.`);
+			const line = element.loc?.start.line;
+			warnings.push({
+				type: "general",
+				message: `Non-string path in array (${element.type})${line ? ` at line ${line}` : ""}. Only string literal paths can be analyzed.`,
+				line
+			});
 		}
 	}
 	return paths;
@@ -2386,13 +2670,21 @@ function extractComponent(node, baseDir, warnings) {
 		if (callee.type === "Identifier" && callee.name === "lazy") {
 			const lazyArg = node.arguments[0];
 			if (lazyArg) return extractLazyImportPath$2(lazyArg, baseDir, warnings);
-			const loc$1 = node.loc ? ` at line ${node.loc.start.line}` : "";
-			warnings.push(`lazy() called without arguments${loc$1}. Expected arrow function with import().`);
+			const line$1 = node.loc?.start.line;
+			warnings.push({
+				type: "general",
+				message: `lazy() called without arguments${line$1 ? ` at line ${line$1}` : ""}. Expected arrow function with import().`,
+				line: line$1
+			});
 			return;
 		}
-		const loc = node.loc ? ` at line ${node.loc.start.line}` : "";
+		const line = node.loc?.start.line;
 		const calleeName = callee.type === "Identifier" ? callee.name : "unknown";
-		warnings.push(`Unrecognized component pattern: ${calleeName}(...)${loc}. Only 'lazy(() => import(...))' is supported.`);
+		warnings.push({
+			type: "general",
+			message: `Unrecognized component pattern: ${calleeName}(...)${line ? ` at line ${line}` : ""}. Only 'lazy(() => import(...))' is supported.`,
+			line
+		});
 		return;
 	}
 	if (node.type === "ArrowFunctionExpression") {
@@ -2400,37 +2692,61 @@ function extractComponent(node, baseDir, warnings) {
 			const openingElement = node.body.openingElement;
 			if (openingElement?.name?.type === "JSXIdentifier") return openingElement.name.name;
 			if (openingElement?.name?.type === "JSXMemberExpression") {
-				const loc = node.loc ? ` at line ${node.loc.start.line}` : "";
-				warnings.push(`Namespaced JSX component (e.g., <UI.Button />)${loc}. Component extraction not supported for member expressions. Consider using a direct component reference or create a wrapper component.`);
+				const line$1 = node.loc?.start.line;
+				warnings.push({
+					type: "general",
+					message: `Namespaced JSX component (e.g., <UI.Button />)${line$1 ? ` at line ${line$1}` : ""}. Component extraction not supported for member expressions. Consider using a direct component reference or create a wrapper component.`,
+					line: line$1
+				});
 				return;
 			}
 		}
 		if (node.body.type === "BlockStatement") {
-			const loc = node.loc ? ` at line ${node.loc.start.line}` : "";
-			warnings.push(`Arrow function with block body${loc}. Only concise arrow functions returning JSX directly can be analyzed.`);
+			const line$1 = node.loc?.start.line;
+			warnings.push({
+				type: "general",
+				message: `Arrow function with block body${line$1 ? ` at line ${line$1}` : ""}. Only concise arrow functions returning JSX directly can be analyzed.`,
+				line: line$1
+			});
 			return;
 		}
 		if (node.body.type === "JSXFragment") {
-			const loc = node.loc ? ` at line ${node.loc.start.line}` : "";
-			warnings.push(`JSX Fragment detected${loc}. Cannot extract component name from fragments.`);
+			const line$1 = node.loc?.start.line;
+			warnings.push({
+				type: "general",
+				message: `JSX Fragment detected${line$1 ? ` at line ${line$1}` : ""}. Cannot extract component name from fragments.`,
+				line: line$1
+			});
 			return;
 		}
 		if (node.body.type === "ConditionalExpression") {
-			const loc = node.loc ? ` at line ${node.loc.start.line}` : "";
+			const line$1 = node.loc?.start.line;
 			let componentInfo = "";
 			const consequent = node.body.consequent;
 			const alternate = node.body.alternate;
 			if (consequent?.type === "JSXElement" && alternate?.type === "JSXElement") componentInfo = ` (${consequent.openingElement?.name?.name || "unknown"} or ${alternate.openingElement?.name?.name || "unknown"})`;
-			warnings.push(`Conditional component${componentInfo}${loc}. Only static JSX elements can be analyzed. Consider extracting to a separate component.`);
+			warnings.push({
+				type: "general",
+				message: `Conditional component${componentInfo}${line$1 ? ` at line ${line$1}` : ""}. Only static JSX elements can be analyzed. Consider extracting to a separate component.`,
+				line: line$1
+			});
 			return;
 		}
-		const arrowLoc = node.loc ? ` at line ${node.loc.start.line}` : "";
-		warnings.push(`Unrecognized arrow function body (${node.body.type})${arrowLoc}. Component will not be extracted.`);
+		const line = node.loc?.start.line;
+		warnings.push({
+			type: "general",
+			message: `Unrecognized arrow function body (${node.body.type})${line ? ` at line ${line}` : ""}. Component will not be extracted.`,
+			line
+		});
 		return;
 	}
 	if (node) {
-		const loc = node.loc ? ` at line ${node.loc.start.line}` : "";
-		warnings.push(`Unrecognized component pattern (${node.type})${loc}. Component will not be extracted.`);
+		const line = node.loc?.start.line;
+		warnings.push({
+			type: "general",
+			message: `Unrecognized component pattern (${node.type})${line ? ` at line ${line}` : ""}. Component will not be extracted.`,
+			line
+		});
 	}
 }
 /**
@@ -2442,13 +2758,21 @@ function extractLazyImportPath$2(node, baseDir, warnings) {
 		const body = node.body;
 		if (body.type === "CallExpression" && body.callee.type === "Import") {
 			if (body.arguments[0]?.type === "StringLiteral") return resolveImportPath(body.arguments[0].value, baseDir);
-			const loc$1 = node.loc ? ` at line ${node.loc.start.line}` : "";
-			warnings.push(`Lazy import with dynamic path${loc$1}. Only string literal imports can be analyzed.`);
+			const line$1 = node.loc?.start.line;
+			warnings.push({
+				type: "general",
+				message: `Lazy import with dynamic path${line$1 ? ` at line ${line$1}` : ""}. Only string literal imports can be analyzed.`,
+				line: line$1
+			});
 			return;
 		}
 	}
-	const loc = node.loc ? ` at line ${node.loc.start.line}` : "";
-	warnings.push(`Unrecognized lazy pattern (${node.type})${loc}. Expected arrow function with import().`);
+	const line = node.loc?.start.line;
+	warnings.push({
+		type: "general",
+		message: `Unrecognized lazy pattern (${node.type})${line ? ` at line ${line}` : ""}. Expected arrow function with import().`,
+		line
+	});
 }
 /**
 * Detect if content is Solid Router based on patterns.
@@ -2495,7 +2819,10 @@ function parseTanStackRouterConfig(filePath, preloadedContent) {
 	for (const node of ast.program.body) collectRouteDefinitions(node, routeMap, routesFileDir, warnings);
 	for (const node of ast.program.body) processAddChildrenCalls(node, routeMap, warnings);
 	const routes = buildRouteTree(routeMap, warnings);
-	if (routes.length === 0) warnings.push("No routes found. Supported patterns: 'createRootRoute()', 'createRoute()', and '.addChildren([...])'");
+	if (routes.length === 0) warnings.push({
+		type: "general",
+		message: "No routes found. Supported patterns: 'createRootRoute()', 'createRoute()', and '.addChildren([...])'"
+	});
 	return {
 		routes,
 		warnings
@@ -2565,8 +2892,12 @@ function extractRouteFromCallExpression(callNode, variableName, baseDir, warning
 			case "path":
 				if (prop.value.type === "StringLiteral") routeDef.path = normalizeTanStackPath(prop.value.value);
 				else {
-					const loc = prop.loc ? ` at line ${prop.loc.start.line}` : "";
-					warnings.push(`Dynamic path value (${prop.value.type})${loc}. Only string literal paths can be statically analyzed.`);
+					const line = prop.loc?.start.line;
+					warnings.push({
+						type: "general",
+						message: `Dynamic path value (${prop.value.type})${line ? ` at line ${line}` : ""}. Only string literal paths can be statically analyzed.`,
+						line
+					});
 				}
 				break;
 			case "component":
@@ -2577,8 +2908,12 @@ function extractRouteFromCallExpression(callNode, variableName, baseDir, warning
 					const body = prop.value.body;
 					if (body.type === "Identifier") routeDef.parentVariableName = body.name;
 					else {
-						const loc = prop.loc ? ` at line ${prop.loc.start.line}` : "";
-						warnings.push(`Dynamic getParentRoute${loc}. Only static route references can be analyzed.`);
+						const line = prop.loc?.start.line;
+						warnings.push({
+							type: "general",
+							message: `Dynamic getParentRoute${line ? ` at line ${line}` : ""}. Only static route references can be analyzed.`,
+							line
+						});
 					}
 				}
 				break;
@@ -2597,8 +2932,12 @@ function extractComponentValue(node, baseDir, warnings) {
 		if (callee.type === "Identifier" && callee.name === "lazyRouteComponent") {
 			const importArg = node.arguments[0];
 			if (importArg) return extractLazyImportPath$1(importArg, baseDir, warnings);
-			const loc = node.loc ? ` at line ${node.loc.start.line}` : "";
-			warnings.push(`lazyRouteComponent called without arguments${loc}. Expected arrow function with import().`);
+			const line = node.loc?.start.line;
+			warnings.push({
+				type: "general",
+				message: `lazyRouteComponent called without arguments${line ? ` at line ${line}` : ""}. Expected arrow function with import().`,
+				line
+			});
 			return;
 		}
 		return;
@@ -2608,19 +2947,31 @@ function extractComponentValue(node, baseDir, warnings) {
 			const openingElement = node.body.openingElement;
 			if (openingElement?.name?.type === "JSXIdentifier") return openingElement.name.name;
 			if (openingElement?.name?.type === "JSXMemberExpression") {
-				const loc = node.loc ? ` at line ${node.loc.start.line}` : "";
-				warnings.push(`Namespaced JSX component${loc}. Component extraction not fully supported for member expressions.`);
+				const line = node.loc?.start.line;
+				warnings.push({
+					type: "general",
+					message: `Namespaced JSX component${line ? ` at line ${line}` : ""}. Component extraction not fully supported for member expressions.`,
+					line
+				});
 				return;
 			}
 		}
 		if (node.body.type === "BlockStatement") {
-			const loc = node.loc ? ` at line ${node.loc.start.line}` : "";
-			warnings.push(`Arrow function with block body${loc}. Only concise arrow functions returning JSX directly can be analyzed.`);
+			const line = node.loc?.start.line;
+			warnings.push({
+				type: "general",
+				message: `Arrow function with block body${line ? ` at line ${line}` : ""}. Only concise arrow functions returning JSX directly can be analyzed.`,
+				line
+			});
 			return;
 		}
 		if (node.body.type === "JSXFragment") {
-			const loc = node.loc ? ` at line ${node.loc.start.line}` : "";
-			warnings.push(`JSX Fragment detected${loc}. Cannot extract component name from fragments.`);
+			const line = node.loc?.start.line;
+			warnings.push({
+				type: "general",
+				message: `JSX Fragment detected${line ? ` at line ${line}` : ""}. Cannot extract component name from fragments.`,
+				line
+			});
 			return;
 		}
 	}
@@ -2639,8 +2990,12 @@ function extractLazyImportPath$1(node, baseDir, warnings) {
 			if (importCall.arguments[0]?.type === "StringLiteral") return resolveImportPath(importCall.arguments[0].value, baseDir);
 		}
 	}
-	const loc = node.loc ? ` at line ${node.loc.start.line}` : "";
-	warnings.push(`Unrecognized lazy pattern (${node.type})${loc}. Expected arrow function with import().`);
+	const line = node.loc?.start.line;
+	warnings.push({
+		type: "general",
+		message: `Unrecognized lazy pattern (${node.type})${line ? ` at line ${line}` : ""}. Expected arrow function with import().`,
+		line
+	});
 }
 /**
 * Process addChildren calls to establish parent-child relationships
@@ -2661,8 +3016,12 @@ function processAddChildrenExpression(expr, routeMap, warnings) {
 		if (!parentVarName) return void 0;
 		const parentDef = routeMap.get(parentVarName);
 		if (!parentDef) {
-			const loc = expr.loc ? ` at line ${expr.loc.start.line}` : "";
-			warnings.push(`Parent route "${parentVarName}" not found${loc}. Ensure it's defined with createRoute/createRootRoute.`);
+			const line = expr.loc?.start.line;
+			warnings.push({
+				type: "general",
+				message: `Parent route "${parentVarName}" not found${line ? ` at line ${line}` : ""}. Ensure it's defined with createRoute/createRootRoute.`,
+				line
+			});
 			return;
 		}
 		const childrenArg = expr.arguments[0];
@@ -2674,10 +3033,7 @@ function processAddChildrenExpression(expr, routeMap, warnings) {
 				else if (element.type === "CallExpression") {
 					const nestedParent = processAddChildrenExpression(element, routeMap, warnings);
 					if (nestedParent) childNames.push(nestedParent);
-				} else if (element.type === "SpreadElement") {
-					const loc = element.loc ? ` at line ${element.loc.start.line}` : "";
-					warnings.push(`Spread operator detected${loc}. Routes from spread cannot be statically analyzed.`);
-				}
+				} else if (element.type === "SpreadElement") warnings.push(createSpreadWarning(element));
 			}
 			parentDef.children = childNames;
 		}
@@ -2719,7 +3075,10 @@ function buildTreeFromParentRelations(routeMap, warnings) {
 */
 function buildRouteFromDefinition(def, routeMap, warnings, visited) {
 	if (visited.has(def.variableName)) {
-		warnings.push(`Circular reference detected: route "${def.variableName}" references itself in the route tree.`);
+		warnings.push({
+			type: "general",
+			message: `Circular reference detected: route "${def.variableName}" references itself in the route tree.`
+		});
 		return null;
 	}
 	visited.add(def.variableName);
@@ -2734,7 +3093,10 @@ function buildRouteFromDefinition(def, routeMap, warnings, visited) {
 			if (childDef) {
 				const childRoute = buildRouteFromDefinition(childDef, routeMap, warnings, visited);
 				if (childRoute) children.push(childRoute);
-			} else warnings.push(`Child route "${childName}" not found. Ensure it's defined with createRoute.`);
+			} else warnings.push({
+				type: "general",
+				message: `Child route "${childName}" not found. Ensure it's defined with createRoute.`
+			});
 		}
 		if (children.length > 0) route.children = children;
 	}
@@ -2842,7 +3204,10 @@ function parseReactRouterConfig(filePath, preloadedContent) {
 			routes.push(...parsed);
 		}
 	}
-	if (routes.length === 0) warnings.push("No routes found. Supported patterns: 'createBrowserRouter([...])', 'export const routes = [...]', or 'export default [...]'");
+	if (routes.length === 0) warnings.push({
+		type: "general",
+		message: "No routes found. Supported patterns: 'createBrowserRouter([...])', 'export const routes = [...]', or 'export default [...]'"
+	});
 	return {
 		routes,
 		warnings
@@ -2856,16 +3221,19 @@ function parseRoutesArray$1(arrayNode, baseDir, warnings) {
 	for (const element of arrayNode.elements) {
 		if (!element) continue;
 		if (element.type === "SpreadElement") {
-			const loc = element.loc ? ` at line ${element.loc.start.line}` : "";
-			warnings.push(`Spread operator detected${loc}. Routes from spread cannot be statically analyzed.`);
+			warnings.push(createSpreadWarning(element));
 			continue;
 		}
 		if (element.type === "ObjectExpression") {
 			const route = parseRouteObject$1(element, baseDir, warnings);
 			if (route) routes.push(route);
 		} else {
-			const loc = element.loc ? ` at line ${element.loc.start.line}` : "";
-			warnings.push(`Non-object route element (${element.type})${loc}. Only object literals can be statically analyzed.`);
+			const line = element.loc?.start.line;
+			warnings.push({
+				type: "general",
+				message: `Non-object route element (${element.type})${line ? ` at line ${line}` : ""}. Only object literals can be statically analyzed.`,
+				line
+			});
 		}
 	}
 	return routes;
@@ -2886,8 +3254,12 @@ function parseRouteObject$1(objectNode, baseDir, warnings) {
 					route.path = prop.value.value;
 					hasPath = true;
 				} else {
-					const loc = prop.loc ? ` at line ${prop.loc.start.line}` : "";
-					warnings.push(`Dynamic path value (${prop.value.type})${loc}. Only string literal paths can be statically analyzed.`);
+					const line = prop.loc?.start.line;
+					warnings.push({
+						type: "general",
+						message: `Dynamic path value (${prop.value.type})${line ? ` at line ${line}` : ""}. Only string literal paths can be statically analyzed.`,
+						line
+					});
 				}
 				break;
 			case "index":
@@ -2949,20 +3321,31 @@ function extractComponentFromJSX(node, warnings) {
 			const wrapperName = openingElement.name.name;
 			for (const child of node.children) if (child.type === "JSXElement") {
 				if (extractComponentFromJSX(child, warnings)) {
-					warnings.push(`Wrapper component detected: <${wrapperName}>. Using wrapper name for screen.`);
+					warnings.push({
+						type: "general",
+						message: `Wrapper component detected: <${wrapperName}>. Using wrapper name for screen.`
+					});
 					return wrapperName;
 				}
 			}
 		}
 	}
 	if (node.type === "JSXFragment") {
-		const loc = node.loc ? ` at line ${node.loc.start.line}` : "";
-		warnings.push(`JSX Fragment detected${loc}. Cannot extract component name from fragments. Consider wrapping in a named component.`);
+		const line = node.loc?.start.line;
+		warnings.push({
+			type: "general",
+			message: `JSX Fragment detected${line ? ` at line ${line}` : ""}. Cannot extract component name from fragments. Consider wrapping in a named component.`,
+			line
+		});
 		return;
 	}
 	if (node) {
-		const loc = node.loc ? ` at line ${node.loc.start.line}` : "";
-		warnings.push(`Unrecognized element pattern (${node.type})${loc}. Component will not be extracted.`);
+		const line = node.loc?.start.line;
+		warnings.push({
+			type: "general",
+			message: `Unrecognized element pattern (${node.type})${line ? ` at line ${line}` : ""}. Component will not be extracted.`,
+			line
+		});
 	}
 }
 /**
@@ -2974,13 +3357,21 @@ function extractLazyImportPath(node, baseDir, warnings) {
 		const body = node.body;
 		if (body.type === "CallExpression" && body.callee.type === "Import") {
 			if (body.arguments[0]?.type === "StringLiteral") return resolveImportPath(body.arguments[0].value, baseDir);
-			const loc$1 = node.loc ? ` at line ${node.loc.start.line}` : "";
-			warnings.push(`Lazy import with dynamic path${loc$1}. Only string literal imports can be statically analyzed.`);
+			const line$1 = node.loc?.start.line;
+			warnings.push({
+				type: "general",
+				message: `Lazy import with dynamic path${line$1 ? ` at line ${line$1}` : ""}. Only string literal imports can be statically analyzed.`,
+				line: line$1
+			});
 			return;
 		}
 	}
-	const loc = node.loc ? ` at line ${node.loc.start.line}` : "";
-	warnings.push(`Unrecognized lazy pattern (${node.type})${loc}. Expected arrow function with import().`);
+	const line = node.loc?.start.line;
+	warnings.push({
+		type: "general",
+		message: `Unrecognized lazy pattern (${node.type})${line ? ` at line ${line}` : ""}. Expected arrow function with import().`,
+		line
+	});
 }
 /**
 * Detect if content is React Router based on patterns
@@ -3064,7 +3455,10 @@ function parseVueRouterConfig(filePath, preloadedContent) {
 			routes.push(...parsed);
 		}
 	}
-	if (routes.length === 0) warnings.push("No routes array found. Supported patterns: 'export const routes = [...]', 'export default [...]', or 'export default [...] satisfies RouteRecordRaw[]'");
+	if (routes.length === 0) warnings.push({
+		type: "general",
+		message: "No routes array found. Supported patterns: 'export const routes = [...]', 'export default [...]', or 'export default [...] satisfies RouteRecordRaw[]'"
+	});
 	return {
 		routes,
 		warnings
@@ -3094,8 +3488,7 @@ function parseRoutesArray(arrayNode, baseDir, warnings, importMap) {
 	for (const element of arrayNode.elements) {
 		if (!element) continue;
 		if (element.type === "SpreadElement") {
-			const loc = element.loc ? ` at line ${element.loc.start.line}` : "";
-			warnings.push(`Spread operator detected${loc}. Routes from spread cannot be statically analyzed.`);
+			warnings.push(createSpreadWarning(element));
 			continue;
 		}
 		if (element.type === "ObjectExpression") {
@@ -3337,34 +3730,6 @@ const VUE_ROUTER_CONFIG_PATHS = [
 	"router/index.ts"
 ];
 /**
-* Default patterns to exclude from screen.meta.ts generation.
-* These directories typically contain reusable components, not navigable screens.
-* @see https://github.com/wadakatu/screenbook/issues/170
-*/
-const DEFAULT_EXCLUDE_PATTERNS = [
-	"**/components/**",
-	"**/shared/**",
-	"**/utils/**",
-	"**/hooks/**",
-	"**/composables/**",
-	"**/stores/**",
-	"**/services/**",
-	"**/helpers/**",
-	"**/lib/**",
-	"**/common/**"
-];
-/**
-* Check if a path matches any of the exclude patterns
-*/
-function matchesExcludePattern(filePath, excludePatterns) {
-	for (const pattern of excludePatterns) {
-		const cleanPattern = pattern.replace(/\*\*/g, "").replace(/\*/g, "").replace(/^\//, "").replace(/\/$/, "");
-		if (cleanPattern && filePath.includes(`/${cleanPattern}/`)) return true;
-		if (cleanPattern && filePath.startsWith(`${cleanPattern}/`)) return true;
-	}
-	return false;
-}
-/**
 * Detect Vue Router configuration file in the project
 */
 function detectVueRouterConfigFile(cwd) {
@@ -3480,7 +3845,9 @@ const generateCommand = define({
 				interactive,
 				detectApi,
 				detectNavigation,
-				apiIntegration: config.apiIntegration
+				apiIntegration: config.apiIntegration,
+				spreadOperator: config.lint?.spreadOperator,
+				generate: config.generate
 			});
 			return;
 		}
@@ -3491,7 +3858,9 @@ const generateCommand = define({
 			ignore: config.ignore,
 			detectApi,
 			detectNavigation,
-			apiIntegration: config.apiIntegration
+			apiIntegration: config.apiIntegration,
+			spreadOperator: config.lint?.spreadOperator,
+			generate: config.generate
 		});
 	}
 });
@@ -3499,7 +3868,12 @@ const generateCommand = define({
 * Generate screen.meta.ts files from a router config file (Vue Router or React Router)
 */
 async function generateFromRoutesFile(routesFile, cwd, options) {
-	const { dryRun, force, interactive, detectApi, detectNavigation, apiIntegration } = options;
+	const { dryRun, force, interactive, detectApi, detectNavigation, apiIntegration, spreadOperator, generate } = options;
+	const screenIdOptions = {
+		smartParameterNaming: generate?.smartParameterNaming,
+		parameterMapping: generate?.parameterMapping,
+		unmappedParameterStrategy: generate?.unmappedParameterStrategy
+	};
 	const absoluteRoutesFile = resolve(cwd, routesFile);
 	if (!existsSync(absoluteRoutesFile)) {
 		logger.errorWithHelp(ERRORS.ROUTES_FILE_NOT_FOUND(routesFile));
@@ -3526,8 +3900,8 @@ async function generateFromRoutesFile(routesFile, cwd, options) {
 		logger.errorWithHelp(ERRORS.ROUTES_FILE_PARSE_ERROR(routesFile, message));
 		process.exit(1);
 	}
-	for (const warning of parseResult.warnings) logger.warn(warning);
-	const flatRoutes = flattenRoutes(parseResult.routes);
+	displayGenerateWarnings(parseResult.warnings, { spreadOperatorSetting: spreadOperator });
+	const flatRoutes = flattenRoutes(parseResult.routes, "", 0, screenIdOptions);
 	if (flatRoutes.length === 0) {
 		logger.warn("No routes found in the config file");
 		return;
@@ -3609,7 +3983,8 @@ async function generateFromRoutesFile(routesFile, cwd, options) {
 				owner: result.owner,
 				tags: result.tags,
 				dependsOn: detectedApis,
-				next: detectedNext
+				next: detectedNext,
+				suggestions: route.suggestions
 			});
 			if (dryRun) {
 				logDryRunOutput(metaPath, result.meta, result.owner, result.tags, detectedApis, detectedNext);
@@ -3618,7 +3993,8 @@ async function generateFromRoutesFile(routesFile, cwd, options) {
 		} else {
 			const content = generateScreenMetaContent(screenMeta, {
 				dependsOn: detectedApis,
-				next: detectedNext
+				next: detectedNext,
+				suggestions: route.suggestions
 			});
 			if (dryRun) {
 				logDryRunOutput(metaPath, screenMeta, void 0, void 0, detectedApis, detectedNext);
@@ -3632,7 +4008,12 @@ async function generateFromRoutesFile(routesFile, cwd, options) {
 * Generate screen.meta.ts files from route files matching a glob pattern
 */
 async function generateFromRoutesPattern(routesPattern, cwd, options) {
-	const { dryRun, force, interactive, ignore, detectApi, detectNavigation, apiIntegration } = options;
+	const { dryRun, force, interactive, ignore, detectApi, detectNavigation, apiIntegration, spreadOperator, generate } = options;
+	const screenIdOptions = {
+		smartParameterNaming: generate?.smartParameterNaming,
+		parameterMapping: generate?.parameterMapping,
+		unmappedParameterStrategy: generate?.unmappedParameterStrategy
+	};
 	logger.info("Scanning for route files...");
 	logger.blank();
 	const routeFiles = await glob(routesPattern, {
@@ -3649,12 +4030,12 @@ async function generateFromRoutesPattern(routesPattern, cwd, options) {
 		const vueRouterConfig = detectVueRouterConfigFile(cwd);
 		if (vueRouterConfig) try {
 			const parseResult = parseVueRouterConfig(vueRouterConfig);
-			const flatRoutes = flattenRoutes(parseResult.routes);
+			const flatRoutes = flattenRoutes(parseResult.routes, "", 0, screenIdOptions);
 			if (flatRoutes.length > 0) {
 				routeComponentMap = buildRouteComponentMap(flatRoutes, cwd);
 				logger.log(`  ${logger.dim(`(using routes from ${relative(cwd, vueRouterConfig)})`)}`);
 			}
-			for (const warning of parseResult.warnings) logger.warn(warning);
+			displayGenerateWarnings(parseResult.warnings, { spreadOperatorSetting: spreadOperator });
 		} catch (error) {
 			const message = error instanceof Error ? error.message : String(error);
 			logger.warn(`Could not parse Vue Router config: ${message}`);
@@ -3728,7 +4109,8 @@ async function generateFromRoutesPattern(routesPattern, cwd, options) {
 				owner: result.owner,
 				tags: result.tags,
 				dependsOn: detectedApis,
-				next: detectedNext
+				next: detectedNext,
+				suggestions: matchedRoute?.suggestions
 			});
 			if (dryRun) {
 				logDryRunOutput(metaPath, result.meta, result.owner, result.tags, detectedApis, detectedNext);
@@ -3737,7 +4119,8 @@ async function generateFromRoutesPattern(routesPattern, cwd, options) {
 		} else {
 			const content = generateScreenMetaContent(screenMeta, {
 				dependsOn: detectedApis,
-				next: detectedNext
+				next: detectedNext,
+				suggestions: matchedRoute?.suggestions
 			});
 			if (dryRun) {
 				logDryRunOutput(metaPath, screenMeta, void 0, void 0, detectedApis, detectedNext);
@@ -3914,6 +4297,7 @@ function generateScreenMetaContent(meta, options) {
 	const tags = options?.tags && options.tags.length > 0 ? options.tags : [meta.id.split(".")[0] || "general"];
 	const dependsOn = options?.dependsOn ?? [];
 	const next = options?.next ?? [];
+	const suggestions = options?.suggestions ?? [];
 	const ownerStr = owner.length > 0 ? `[${owner.map((o) => `"${o}"`).join(", ")}]` : "[]";
 	const tagsStr = `[${tags.map((t) => `"${t}"`).join(", ")}]`;
 	const dependsOnStr = dependsOn.length > 0 ? `[${dependsOn.map((d) => `"${d}"`).join(", ")}]` : "[]";
@@ -3921,10 +4305,10 @@ function generateScreenMetaContent(meta, options) {
 	const dependsOnComment = dependsOn.length > 0 ? "// Auto-detected API dependencies (add more as needed)" : `// APIs/services this screen depends on (for impact analysis)
 	// Example: ["UserAPI.getProfile", "PaymentService.checkout"]`;
 	const nextComment = next.length > 0 ? "// Auto-detected navigation targets (add more as needed)" : "// Screen IDs this screen can navigate to";
-	return `import { defineScreen } from "@screenbook/core"
+	return `import { defineScreen } from "screenbook"
 
 export const screen = defineScreen({
-	id: "${meta.id}",
+	${suggestions.length > 0 ? `// TODO: ${suggestions.join("; ")}\n\t` : ""}id: "${meta.id}",
 	title: "${meta.title}",
 	route: "${meta.route}",
 
@@ -4371,7 +4755,7 @@ function isInteractive() {
 //#endregion
 //#region src/commands/init.ts
 function generateConfigTemplate(framework) {
-	if (framework) return `import { defineConfig } from "@screenbook/core"
+	if (framework) return `import { defineConfig } from "screenbook"
 
 export default defineConfig({
 	// Auto-detected: ${framework.name}
@@ -4380,7 +4764,7 @@ export default defineConfig({
 	outDir: ".screenbook",
 })
 `;
-	return `import { defineConfig } from "@screenbook/core"
+	return `import { defineConfig } from "screenbook"
 
 export default defineConfig({
 	// Glob pattern for screen metadata files
@@ -4940,6 +5324,7 @@ const lintCommand = define({
 		const cwd = process.cwd();
 		const adoption = config.adoption ?? { mode: "full" };
 		let hasWarnings = false;
+		let shouldFailLint = false;
 		if (!config.routesPattern && !config.routesFile) {
 			logger.errorWithHelp(ERRORS.ROUTES_PATTERN_MISSING);
 			process.exit(1);
@@ -4959,6 +5344,20 @@ const lintCommand = define({
 			cwd,
 			ignore: config.ignore
 		});
+		const excludePatterns = config.excludePatterns ?? DEFAULT_EXCLUDE_PATTERNS;
+		const excludedFiles = [];
+		routeFiles = routeFiles.filter((file) => {
+			if (matchesExcludePattern(file, excludePatterns)) {
+				excludedFiles.push(file);
+				return false;
+			}
+			return true;
+		});
+		if (isVerbose() && excludedFiles.length > 0) {
+			logger.log(`Excluded by patterns (${excludedFiles.length} files):`);
+			for (const file of excludedFiles) logger.log(`  ${logger.dim(file)}`);
+			logger.blank();
+		}
 		if (adoption.mode === "progressive" && adoption.includePatterns?.length) routeFiles = routeFiles.filter((file) => adoption.includePatterns?.some((pattern) => minimatch(file, pattern)));
 		if (routeFiles.length === 0) {
 			logger.warn(`No route files found matching: ${config.routesPattern}`);
@@ -5008,18 +5407,18 @@ const lintCommand = define({
 		if (existsSync(screensPath)) try {
 			const content = readFileSync(screensPath, "utf-8");
 			const screens = JSON.parse(content);
-			const orphans = findOrphanScreens(screens);
-			if (orphans.length > 0) {
-				hasWarnings = true;
-				logger.blank();
-				logger.warn(`Orphan screens detected (${orphans.length}):`);
+			if (!Array.isArray(screens)) {
 				logger.blank();
-				logger.log("  These screens have no entryPoints and are not");
-				logger.log("  referenced in any other screen's 'next' array.");
-				logger.blank();
-				for (const orphan of orphans) logger.itemWarn(`${orphan.id}  ${logger.dim(orphan.route)}`);
+				logger.error("screens.json does not contain a valid array of screens");
+				logger.log(`  ${logger.dim("Run 'screenbook build' to regenerate.")}`);
+				process.exit(1);
+			}
+			const orphanResult = checkAndReportOrphanScreens(screens, config.lint?.orphans ?? "warn");
+			if (orphanResult.hasWarnings) hasWarnings = true;
+			if (orphanResult.shouldFail) {
 				logger.blank();
-				logger.log(`  ${logger.dim("Consider adding entryPoints or removing these screens.")}`);
+				logger.error("Lint failed: Orphan screens detected in strict mode");
+				shouldFailLint = true;
 			}
 			if (!ctx.values.allowCycles) {
 				const cycleResult = detectCycles(screens);
@@ -5056,17 +5455,26 @@ const lintCommand = define({
 			}
 		} catch (error) {
 			if (error instanceof SyntaxError) {
-				logger.warn("Failed to parse screens.json - file may be corrupted");
-				logger.log(`  ${logger.dim("Run 'screenbook build' to regenerate.")}`);
-				hasWarnings = true;
-			} else if (error instanceof Error) {
-				logger.warn(`Failed to analyze screens.json: ${error.message}`);
-				hasWarnings = true;
-			} else {
-				logger.warn(`Failed to analyze screens.json: ${String(error)}`);
-				hasWarnings = true;
+				logger.blank();
+				logger.error("Failed to parse screens.json");
+				logger.log(`  ${logger.dim("The file contains invalid JSON syntax.")}`);
+				logger.log(`  ${logger.dim("Run 'screenbook build' to regenerate the file.")}`);
+				process.exit(1);
 			}
+			if (error instanceof Error && (error.message.includes("EACCES") || error.message.includes("EPERM"))) {
+				logger.blank();
+				logger.error("Permission denied reading screens.json");
+				logger.log(`  ${logger.dim(error.message)}`);
+				logger.log(`  ${logger.dim("Check file permissions on the .screenbook directory.")}`);
+				process.exit(1);
+			}
+			logger.blank();
+			logger.error("Unexpected error reading screens.json");
+			if (error instanceof Error) logger.log(`  ${logger.dim(error.message)}`);
+			else logger.log(`  ${logger.dim(String(error))}`);
+			process.exit(1);
 		}
+		if (shouldFailLint) process.exit(1);
 		if (hasWarnings) {
 			logger.blank();
 			logger.warn("Lint completed with warnings.");
@@ -5078,6 +5486,7 @@ const lintCommand = define({
 */
 async function lintRoutesFile(routesFile, cwd, config, adoption, allowCycles, strict) {
 	let hasWarnings = false;
+	let shouldFailLint = false;
 	const absoluteRoutesFile = resolve(cwd, routesFile);
 	if (!existsSync(absoluteRoutesFile)) {
 		logger.errorWithHelp(ERRORS.ROUTES_FILE_NOT_FOUND(routesFile));
@@ -5090,25 +5499,43 @@ async function lintRoutesFile(routesFile, cwd, config, adoption, allowCycles, st
 		const content = readFileSync(absoluteRoutesFile, "utf-8");
 		const routerType = detectRouterType(content);
 		let parseResult;
-		if (routerType === "tanstack-router") parseResult = parseTanStackRouterConfig(absoluteRoutesFile, content);
-		else if (routerType === "solid-router") parseResult = parseSolidRouterConfig(absoluteRoutesFile, content);
-		else if (routerType === "angular-router") parseResult = parseAngularRouterConfig(absoluteRoutesFile, content);
-		else if (routerType === "react-router") parseResult = parseReactRouterConfig(absoluteRoutesFile, content);
-		else if (routerType === "vue-router") parseResult = parseVueRouterConfig(absoluteRoutesFile, content);
-		else {
-			logger.warn(`Could not auto-detect router type for ${logger.path(routesFile)}. Attempting to parse as Vue Router.`);
-			logger.log(`  ${logger.dim("If parsing fails, check that your router imports are explicit.")}`);
-			hasWarnings = true;
-			parseResult = parseVueRouterConfig(absoluteRoutesFile, content);
-		}
-		for (const warning of parseResult.warnings) {
-			logger.warn(warning);
-			hasWarnings = true;
+		try {
+			if (routerType === "tanstack-router") parseResult = parseTanStackRouterConfig(absoluteRoutesFile, content);
+			else if (routerType === "solid-router") parseResult = parseSolidRouterConfig(absoluteRoutesFile, content);
+			else if (routerType === "angular-router") parseResult = parseAngularRouterConfig(absoluteRoutesFile, content);
+			else if (routerType === "react-router") parseResult = parseReactRouterConfig(absoluteRoutesFile, content);
+			else if (routerType === "vue-router") parseResult = parseVueRouterConfig(absoluteRoutesFile, content);
+			else {
+				logger.warn(`Could not auto-detect router type for ${logger.path(routesFile)}. Attempting to parse as Vue Router.`);
+				logger.log(`  ${logger.dim("If parsing fails, check that your router imports are explicit.")}`);
+				hasWarnings = true;
+				parseResult = parseVueRouterConfig(absoluteRoutesFile, content);
+			}
+		} catch (parseError) {
+			const message = parseError instanceof Error ? parseError.message : String(parseError);
+			logger.errorWithHelp(ERRORS.ROUTES_FILE_PARSE_ERROR(routesFile, message));
+			process.exit(1);
 		}
+		const warningsResult = displayWarnings(parseResult.warnings, { spreadOperatorSetting: config.lint?.spreadOperator });
+		if (warningsResult.hasWarnings) hasWarnings = true;
+		if (warningsResult.shouldFailLint) shouldFailLint = true;
 		flatRoutes = flattenRoutes(parseResult.routes);
 	} catch (error) {
-		const message = error instanceof Error ? error.message : String(error);
-		logger.errorWithHelp(ERRORS.ROUTES_FILE_PARSE_ERROR(routesFile, message));
+		if (error instanceof Error) if (error.message.includes("ENOENT")) logger.errorWithHelp(ERRORS.ROUTES_FILE_NOT_FOUND(routesFile));
+		else if (error.message.includes("EACCES") || error.message.includes("EPERM")) {
+			logger.blank();
+			logger.error(`Permission denied reading ${routesFile}`);
+			logger.log(`  ${logger.dim(error.message)}`);
+			logger.log(`  ${logger.dim("Check file permissions.")}`);
+		} else {
+			logger.blank();
+			logger.error(`Failed to read ${routesFile}`);
+			logger.log(`  ${logger.dim(error.message)}`);
+		}
+		else {
+			logger.blank();
+			logger.error(`Unexpected error: ${String(error)}`);
+		}
 		process.exit(1);
 	}
 	if (flatRoutes.length === 0) {
@@ -5129,11 +5556,20 @@ async function lintRoutesFile(routesFile, cwd, config, adoption, allowCycles, st
 	}
 	const missingMeta = [];
 	const covered = [];
+	const excludedRoutes = [];
+	const excludePatterns = config.excludePatterns ?? DEFAULT_EXCLUDE_PATTERNS;
 	for (const route of flatRoutes) {
 		if (route.componentPath?.endsWith("Layout")) continue;
+		const metaDir = determineMetaDir(route, cwd);
+		if (matchesExcludePattern(metaDir, excludePatterns)) {
+			excludedRoutes.push({
+				route,
+				metaDir
+			});
+			continue;
+		}
 		let matched = false;
-		const metaPath = determineMetaDir(route, cwd);
-		if (metaDirs.has(metaPath)) matched = true;
+		if (metaDirs.has(metaDir)) matched = true;
 		if (!matched && route.componentPath) {
 			const componentName = route.componentPath.toLowerCase();
 			if (metaDirsByName.has(componentName)) matched = true;
@@ -5155,6 +5591,11 @@ async function lintRoutesFile(routesFile, cwd, config, adoption, allowCycles, st
 		if (matched) covered.push(route);
 		else missingMeta.push(route);
 	}
+	if (isVerbose() && excludedRoutes.length > 0) {
+		logger.log(`Excluded by patterns (${excludedRoutes.length} routes):`);
+		for (const { route, metaDir } of excludedRoutes) logger.log(`  ${logger.dim(`${route.fullPath} → ${metaDir}`)}`);
+		logger.blank();
+	}
 	const total = covered.length + missingMeta.length;
 	const coveredCount = covered.length;
 	const missingCount = missingMeta.length;
@@ -5185,18 +5626,18 @@ async function lintRoutesFile(routesFile, cwd, config, adoption, allowCycles, st
 	if (existsSync(screensPath)) try {
 		const content = readFileSync(screensPath, "utf-8");
 		const screens = JSON.parse(content);
-		const orphans = findOrphanScreens(screens);
-		if (orphans.length > 0) {
-			hasWarnings = true;
-			logger.blank();
-			logger.warn(`Orphan screens detected (${orphans.length}):`);
-			logger.blank();
-			logger.log("  These screens have no entryPoints and are not");
-			logger.log("  referenced in any other screen's 'next' array.");
+		if (!Array.isArray(screens)) {
 			logger.blank();
-			for (const orphan of orphans) logger.itemWarn(`${orphan.id}  ${logger.dim(orphan.route)}`);
+			logger.error("screens.json does not contain a valid array of screens");
+			logger.log(`  ${logger.dim("Run 'screenbook build' to regenerate.")}`);
+			process.exit(1);
+		}
+		const orphanResult = checkAndReportOrphanScreens(screens, config.lint?.orphans ?? "warn");
+		if (orphanResult.hasWarnings) hasWarnings = true;
+		if (orphanResult.shouldFail) {
 			logger.blank();
-			logger.log(`  ${logger.dim("Consider adding entryPoints or removing these screens.")}`);
+			logger.error("Lint failed: Orphan screens detected in strict mode");
+			shouldFailLint = true;
 		}
 		if (!allowCycles) {
 			const cycleResult = detectCycles(screens);
@@ -5233,17 +5674,26 @@ async function lintRoutesFile(routesFile, cwd, config, adoption, allowCycles, st
 		}
 	} catch (error) {
 		if (error instanceof SyntaxError) {
-			logger.warn("Failed to parse screens.json - file may be corrupted");
-			logger.log(`  ${logger.dim("Run 'screenbook build' to regenerate.")}`);
-			hasWarnings = true;
-		} else if (error instanceof Error) {
-			logger.warn(`Failed to analyze screens.json: ${error.message}`);
-			hasWarnings = true;
-		} else {
-			logger.warn(`Failed to analyze screens.json: ${String(error)}`);
-			hasWarnings = true;
+			logger.blank();
+			logger.error("Failed to parse screens.json");
+			logger.log(`  ${logger.dim("The file contains invalid JSON syntax.")}`);
+			logger.log(`  ${logger.dim("Run 'screenbook build' to regenerate the file.")}`);
+			process.exit(1);
+		}
+		if (error instanceof Error && (error.message.includes("EACCES") || error.message.includes("EPERM"))) {
+			logger.blank();
+			logger.error("Permission denied reading screens.json");
+			logger.log(`  ${logger.dim(error.message)}`);
+			logger.log(`  ${logger.dim("Check file permissions on the .screenbook directory.")}`);
+			process.exit(1);
 		}
+		logger.blank();
+		logger.error("Unexpected error reading screens.json");
+		if (error instanceof Error) logger.log(`  ${logger.dim(error.message)}`);
+		else logger.log(`  ${logger.dim(String(error))}`);
+		process.exit(1);
 	}
+	if (shouldFailLint) process.exit(1);
 	if (hasWarnings) {
 		logger.blank();
 		logger.warn("Lint completed with warnings.");
@@ -5309,6 +5759,56 @@ function findOrphanScreens(screens) {
 	return orphans;
 }
 /**
+* Check for orphan screens and report based on configuration.
+* When all screens are orphans (common after initial generation),
+* show a tip instead of warnings to avoid confusing new users.
+*/
+function checkAndReportOrphanScreens(screens, orphanSetting) {
+	if (orphanSetting === "off") return {
+		hasWarnings: false,
+		shouldFail: false
+	};
+	const orphans = findOrphanScreens(screens);
+	if (orphans.length === 0) return {
+		hasWarnings: false,
+		shouldFail: false
+	};
+	if (orphans.length === screens.length) {
+		logger.blank();
+		logger.info("Tip: All screens are currently disconnected.");
+		logger.blank();
+		logger.log("  This is normal after initial setup. To connect screens:");
+		logger.log("  1. Add 'entryPoints' to define how users reach each screen");
+		logger.log("  2. Add 'next' to define navigation targets from each screen");
+		logger.blank();
+		if (orphanSetting === "error") return {
+			hasWarnings: true,
+			shouldFail: true
+		};
+		return {
+			hasWarnings: false,
+			shouldFail: false
+		};
+	}
+	logger.blank();
+	logger.warn(`Orphan screens detected (${orphans.length}):`);
+	logger.blank();
+	logger.log("  These screens have no entryPoints and are not");
+	logger.log("  referenced in any other screen's 'next' array.");
+	logger.blank();
+	for (const orphan of orphans) logger.itemWarn(`${orphan.id}  ${logger.dim(orphan.route)}`);
+	logger.blank();
+	logger.log(`  ${logger.dim("Consider adding entryPoints or removing these screens.")}`);
+	if (orphanSetting === "error") return {
+		hasWarnings: true,
+		shouldFail: true
+	};
+	return {
+		hasWarnings: true,
+		shouldFail: false
+	};
+}
+/**
 * Validate dependsOn references against OpenAPI specifications
 */
 async function validateDependsOnAgainstOpenApi(screens, sources, cwd, strict) {