@tailor-platform/erp-kit 0.2.2 → 0.4.0

package/dist/cli.mjs

@@ -362,22 +362,85 @@ const ALL_SCHEMAS = {
 	...APP_COMPOSE_SCHEMAS
 };
 //#endregion
-//#region src/commands/check.ts
+//#region src/commands/lib/paths.ts
+const MODULE_PATHS = {
+	commands: "command",
+	db: "db",
+	queries: "query",
+	docs: {
+		commands: "docs/commands",
+		models: "docs/models",
+		queries: "docs/queries",
+		features: "docs/features"
+	}
+};
+const APP_PATHS = {
+	storySegment: "story",
+	docs: {
+		resolver: "docs/resolver",
+		actors: "docs/actors",
+		businessFlow: "docs/business-flow",
+		screen: "docs/screen"
+	}
+};
+//#endregion
+//#region src/commands/lib/discovery.ts
+function moduleCategories(root) {
+	return [
+		{
+			name: "command",
+			sourcePattern: `${root}/*/${MODULE_PATHS.commands}/*.ts`,
+			docPattern: `${root}/*/${MODULE_PATHS.docs.commands}/*.md`,
+			exclusions: [/\.test\.ts$/, /\.generated\.ts$/]
+		},
+		{
+			name: "model",
+			sourcePattern: `${root}/*/${MODULE_PATHS.db}/*.ts`,
+			docPattern: `${root}/*/${MODULE_PATHS.docs.models}/*.md`,
+			exclusions: [/\.test\.ts$/, /^index\.ts$/]
+		},
+		{
+			name: "query",
+			sourcePattern: `${root}/*/${MODULE_PATHS.queries}/*.ts`,
+			docPattern: `${root}/*/${MODULE_PATHS.docs.queries}/*.md`,
+			exclusions: [/\.test\.ts$/]
+		}
+	];
+}
+function appComposeCategories(root) {
+	return [{
+		name: "resolver",
+		sourcePattern: `${root}/*/backend/src/resolvers/*.ts`,
+		docPattern: `${root}/*/${APP_PATHS.docs.resolver}/*.md`,
+		exclusions: [/\.test\.ts$/, /^index\.ts$/]
+	}];
+}
+function testCaseCategories(root) {
+	return [{
+		name: "command-test-case",
+		docPattern: `${root}/*/${MODULE_PATHS.docs.commands}/*.md`,
+		testDir: MODULE_PATHS.commands
+	}, {
+		name: "query-test-case",
+		docPattern: `${root}/*/${MODULE_PATHS.docs.queries}/*.md`,
+		testDir: MODULE_PATHS.queries
+	}];
+}
 function buildCheckTargets(config) {
 	const targets = [];
 	if (config.modulesRoot) {
 		const m = config.modulesRoot;
 		targets.push({
-			glob: `${m}/[a-zA-Z]*/docs/features/*.md`,
+			glob: `${m}/[a-zA-Z]*/${MODULE_PATHS.docs.features}/*.md`,
 			schemaKey: "feature"
 		}, {
-			glob: `${m}/[a-zA-Z]*/docs/commands/*.md`,
+			glob: `${m}/[a-zA-Z]*/${MODULE_PATHS.docs.commands}/*.md`,
 			schemaKey: "command"
 		}, {
-			glob: `${m}/[a-zA-Z]*/docs/models/*.md`,
+			glob: `${m}/[a-zA-Z]*/${MODULE_PATHS.docs.models}/*.md`,
 			schemaKey: "model"
 		}, {
-			glob: `${m}/[a-zA-Z]*/docs/queries/*.md`,
+			glob: `${m}/[a-zA-Z]*/${MODULE_PATHS.docs.queries}/*.md`,
 			schemaKey: "query"
 		}, {
 			glob: `${m}/[a-zA-Z]*/README.md`,
@@ -390,24 +453,26 @@ function buildCheckTargets(config) {
 			glob: `${a}/[a-zA-Z]*/README.md`,
 			schemaKey: "app"
 		}, {
-			glob: `${a}/[a-zA-Z]*/docs/actors/*.md`,
+			glob: `${a}/[a-zA-Z]*/${APP_PATHS.docs.actors}/*.md`,
 			schemaKey: "actors"
 		}, {
-			glob: `${a}/[a-zA-Z]*/docs/business-flow/*/README.md`,
+			glob: `${a}/[a-zA-Z]*/${APP_PATHS.docs.businessFlow}/*/README.md`,
 			schemaKey: "business-flow"
 		}, {
-			glob: `${a}/[a-zA-Z]*/docs/business-flow/*/story/*.md`,
+			glob: `${a}/[a-zA-Z]*/${APP_PATHS.docs.businessFlow}/*/${APP_PATHS.storySegment}/*.md`,
 			schemaKey: "story"
 		}, {
-			glob: `${a}/[a-zA-Z]*/docs/screen/*.md`,
+			glob: `${a}/[a-zA-Z]*/${APP_PATHS.docs.screen}/*.md`,
 			schemaKey: "screen"
 		}, {
-			glob: `${a}/[a-zA-Z]*/docs/resolver/*.md`,
+			glob: `${a}/[a-zA-Z]*/${APP_PATHS.docs.resolver}/*.md`,
 			schemaKey: "resolver"
 		});
 	}
 	return targets;
 }
+//#endregion
+//#region src/commands/check.ts
 async function runCheck(config, cwd) {
 	const targets = buildCheckTargets(config);
 	const results = await Promise.all(targets.map(async (target) => {
@@ -430,83 +495,85 @@ async function runCheck(config, cwd) {
 	return results.some((code) => code !== 0) ? 1 : 0;
 }
 //#endregion
-//#region src/commands/parse-doc-test-cases.ts
-function isHeading$1(node) {
-	return node.type === "heading";
+//#region src/commands/init-module.ts
+function runInitModule(name, dir) {
+	const moduleDir = path.resolve(dir, name);
+	if (fs.existsSync(moduleDir)) {
+		console.error(`Directory already exists: ${moduleDir}`);
+		return 1;
+	}
+	fs.mkdirSync(moduleDir, { recursive: true });
+	return 0;
 }
-function isList$1(node) {
-	return node.type === "list";
+async function runInitModuleWithReadme(name, dir, cwd) {
+	const initResult = runInitModule(name, dir);
+	if (initResult !== 0) return initResult;
+	const moduleDir = path.resolve(cwd, dir, name);
+	const readmePath = path.join(moduleDir, "README.md");
+	const schemaPath = MODULE_SCHEMAS.module;
+	const { exitCode, stdout, stderr } = await runMdschema([
+		"generate",
+		"--schema",
+		schemaPath,
+		"--output",
+		readmePath
+	], cwd);
+	if (stdout.trim()) console.log(stdout);
+	if (stderr.trim()) console.error(stderr);
+	return exitCode;
 }
-/**
-* Parse test case descriptions from the `## Test Cases` section of a Markdown doc.
-* Uses mdast to traverse the AST instead of string matching.
-*/
-function parseTestCasesFromDoc(markdown) {
-	const tree = fromMarkdown(markdown);
-	const cases = [];
-	let collecting = false;
-	for (const node of tree.children) {
-		if (isHeading$1(node)) {
-			if (collecting) break;
-			if (node.depth === 2 && toString(node) === "Test Cases") {
-				collecting = true;
-				continue;
-			}
-		}
-		if (collecting && isList$1(node)) for (const item of node.children) {
-			const text = toString(item).trim();
-			if (text) cases.push(text);
-		}
+function runInitApp(name, dir) {
+	const appDir = path.resolve(dir, name);
+	if (fs.existsSync(appDir)) {
+		console.error(`Directory already exists: ${appDir}`);
+		return 1;
 	}
-	return cases;
+	fs.mkdirSync(appDir, { recursive: true });
+	return 0;
 }
-/**
-* Parse `it("...")` descriptions from a test file using regex.
-* Test files are not Markdown, so regex is appropriate here.
-*/
-function parseItDescriptionsFromTest(content) {
-	const descriptions = [];
-	const regex = /\bit\(\s*["'`]([^"'`]+)["'`]/g;
-	let match;
-	while ((match = regex.exec(content)) !== null) descriptions.push(match[1]);
-	return descriptions;
+async function runInitAppWithReadme(name, dir, cwd) {
+	const initResult = runInitApp(name, dir);
+	if (initResult !== 0) return initResult;
+	const appDir = path.resolve(cwd, dir, name);
+	const readmePath = path.join(appDir, "README.md");
+	const schemaPath = APP_COMPOSE_SCHEMAS.app;
+	const { exitCode, stdout, stderr } = await runMdschema([
+		"generate",
+		"--schema",
+		schemaPath,
+		"--output",
+		readmePath
+	], cwd);
+	if (stdout.trim()) console.log(stdout);
+	if (stderr.trim()) console.error(stderr);
+	return exitCode;
 }
 //#endregion
-//#region src/commands/sync-check.ts
-function moduleCategories(root) {
-	return [
-		{
-			name: "command",
-			sourcePattern: `${root}/*/command/*.ts`,
-			docPattern: `${root}/*/docs/commands/*.md`,
-			exclusions: [/\.test\.ts$/, /\.generated\.ts$/]
-		},
-		{
-			name: "model",
-			sourcePattern: `${root}/*/db/*.ts`,
-			docPattern: `${root}/*/docs/models/*.md`,
-			exclusions: [/\.test\.ts$/, /^index\.ts$/]
-		},
-		{
-			name: "query",
-			sourcePattern: `${root}/*/query/*.ts`,
-			docPattern: `${root}/*/docs/queries/*.md`,
-			exclusions: [/\.test\.ts$/]
-		}
-	];
+//#region src/commands/lib/command-result.ts
+function success() {
+	return { exitCode: 0 };
 }
-function appComposeCategories(root) {
-	return [{
-		name: "resolver",
-		sourcePattern: `${root}/*/backend/src/modules/**/resolvers/*.ts`,
-		docPattern: `${root}/*/docs/resolver/*.md`,
-		exclusions: [/\.test\.ts$/, /^index\.ts$/]
-	}];
+function silentFailure(exitCode = 1) {
+	return {
+		exitCode,
+		message: ""
+	};
+}
+async function runCommand(fn) {
+	const result = await fn();
+	if (result.exitCode !== 0 && "message" in result && result.message) console.error(result.message);
+	return result;
 }
+async function executeCommand(fn) {
+	const result = await runCommand(fn);
+	process.exit(result.exitCode);
+}
+//#endregion
+//#region src/commands/lib/sync-check-source.ts
 function shouldExclude(fileName, exclusions) {
 	return exclusions.some((pattern) => pattern.test(fileName));
 }
-async function runSyncCheck(config, cwd) {
+async function runSourceSyncCheck(config, cwd) {
 	const errors = [];
 	let totalSources = 0;
 	let totalDocs = 0;
@@ -543,10 +610,6 @@ async function runSyncCheck(config, cwd) {
 		totalSources += sourceBasenames.size;
 		totalDocs += docBasenames.size;
 	}
-	if (config.modulesRoot) {
-		const testCaseErrors = await runTestCaseSyncCheck(config.modulesRoot, cwd);
-		errors.push(...testCaseErrors);
-	}
 	return {
 		exitCode: errors.length > 0 ? 1 : 0,
 		errors,
@@ -557,17 +620,56 @@ async function runSyncCheck(config, cwd) {
 		}
 	};
 }
-function testCaseCategories(root) {
-	return [{
-		name: "command-test-case",
-		docPattern: `${root}/*/docs/commands/*.md`,
-		testDir: "command"
-	}, {
-		name: "query-test-case",
-		docPattern: `${root}/*/docs/queries/*.md`,
-		testDir: "query"
-	}];
+//#endregion
+//#region src/commands/parse-doc-test-cases.ts
+function isHeading$2(node) {
+	return node.type === "heading";
+}
+function isList$1(node) {
+	return node.type === "list";
+}
+/**
+* Parse test case descriptions from the `## Test Cases` section of a Markdown doc.
+* Uses mdast to traverse the AST instead of string matching.
+*/
+function parseTestCasesFromDoc(markdown) {
+	const tree = fromMarkdown(markdown);
+	const cases = [];
+	let collecting = false;
+	for (const node of tree.children) {
+		if (isHeading$2(node)) {
+			if (collecting) break;
+			if (node.depth === 2 && toString(node) === "Test Cases") {
+				collecting = true;
+				continue;
+			}
+		}
+		if (collecting && isList$1(node)) for (const item of node.children) {
+			const text = toString(item).trim();
+			if (text) cases.push(text);
+		}
+	}
+	return cases;
+}
+/**
+* Parse `it("...")` descriptions from a test file using regex.
+* Test files are not Markdown, so regex is appropriate here.
+* Uses separate patterns per quote type so that e.g. an apostrophe
+* inside a double-quoted string does not end the match early.
+*/
+function parseItDescriptionsFromTest(content) {
+	const descriptions = [];
+	const regex = /\bit\(\s*"([^"]+)"/gs;
+	let match;
+	while ((match = regex.exec(content)) !== null) descriptions.push(match[1].replace(/\s+/g, " ").trim());
+	const singleQuoteRegex = /\bit\(\s*'([^']+)'/gs;
+	while ((match = singleQuoteRegex.exec(content)) !== null) descriptions.push(match[1].replace(/\s+/g, " ").trim());
+	const backtickRegex = /\bit\(\s*`([^`]+)`/gs;
+	while ((match = backtickRegex.exec(content)) !== null) descriptions.push(match[1].replace(/\s+/g, " ").trim());
+	return descriptions;
 }
+//#endregion
+//#region src/commands/lib/sync-check-tests.ts
 function toCamelCase(pascalCase) {
 	return pascalCase.charAt(0).toLowerCase() + pascalCase.slice(1);
 }
@@ -609,6 +711,17 @@ async function runTestCaseSyncCheck(root, cwd) {
 	}
 	return errors;
 }
+//#endregion
+//#region src/commands/sync-check.ts
+async function runSyncCheck(config, cwd) {
+	const sourceResult = await runSourceSyncCheck(config, cwd);
+	if (config.modulesRoot) {
+		const testCaseErrors = await runTestCaseSyncCheck(config.modulesRoot, cwd);
+		sourceResult.errors.push(...testCaseErrors);
+		sourceResult.exitCode = sourceResult.errors.length > 0 ? 1 : 0;
+	}
+	return sourceResult;
+}
 function formatSyncCheckReport(result) {
 	const lines = [];
 	lines.push(chalk.bold("docs-sync-check: Checking source-documentation correspondence...\n"));
@@ -655,158 +768,6 @@ function formatSyncCheckReport(result) {
 	return lines.join("\n");
 }
 //#endregion
-//#region src/commands/scaffold.ts
-const MODULE_TYPES = [
-	"module",
-	"feature",
-	"command",
-	"model",
-	"query"
-];
-const APP_TYPES = [
-	"app",
-	"actors",
-	"business-flow",
-	"story",
-	"screen",
-	"resolver"
-];
-[...MODULE_TYPES, ...APP_TYPES];
-const MODULE_DIR_MAP = {
-	feature: "docs/features",
-	command: "docs/commands",
-	model: "docs/models",
-	query: "docs/queries"
-};
-const APP_DIR_MAP = {
-	actors: "docs/actors",
-	"business-flow": "docs/business-flow",
-	screen: "docs/screen",
-	resolver: "docs/resolver"
-};
-function resolveScaffoldPath(type, parentName, name, root) {
-	if (type === "module" || type === "app") return path.join(root, parentName, "README.md");
-	if (!name) throw new Error(`Name is required for scaffold type "${type}"`);
-	if (type === "business-flow") return path.join(root, parentName, "docs/business-flow", name, "README.md");
-	if (type === "story") {
-		const parts = name.split("/");
-		if (parts.length !== 2) throw new Error(`Story name must be "<flow>/<story>" (e.g., "onboarding/admin--create-user")`);
-		return path.join(root, parentName, "docs/business-flow", parts[0], "story", `${parts[1]}.md`);
-	}
-	if (MODULE_DIR_MAP[type]) return path.join(root, parentName, MODULE_DIR_MAP[type], `${name}.md`);
-	if (APP_DIR_MAP[type]) return path.join(root, parentName, APP_DIR_MAP[type], `${name}.md`);
-	throw new Error(`Unknown scaffold type: ${type}`);
-}
-async function runScaffold(type, parentName, name, root, cwd) {
-	const outputPath = resolveScaffoldPath(type, parentName, name, root);
-	const absoluteOutput = path.resolve(cwd, outputPath);
-	if (fs.existsSync(absoluteOutput)) {
-		console.error(`File already exists: ${outputPath}`);
-		return 1;
-	}
-	const schemaPath = ALL_SCHEMAS[type];
-	if (!schemaPath) {
-		console.error(`No schema found for type: ${type}`);
-		return 2;
-	}
-	try {
-		fs.mkdirSync(path.dirname(absoluteOutput), { recursive: true });
-	} catch (err) {
-		console.error(`Failed to create directory: ${err instanceof Error ? err.message : String(err)}`);
-		return 1;
-	}
-	const { exitCode, stdout, stderr } = await runMdschema([
-		"generate",
-		"--schema",
-		schemaPath,
-		"--output",
-		absoluteOutput
-	], cwd);
-	if (stdout.trim()) console.log(stdout);
-	if (stderr.trim()) console.error(stderr);
-	if (exitCode !== 0) return exitCode;
-	if (type === "module") scaffoldModuleSrc(path.dirname(absoluteOutput), parentName);
-	if (type === "app") scaffoldAppSrc(path.dirname(absoluteOutput), parentName);
-	return exitCode;
-}
-function copyTemplateDir(srcDir, destDir, replacements, placeholderFiles) {
-	for (const entry of fs.readdirSync(srcDir, { withFileTypes: true })) {
-		const srcPath = path.join(srcDir, entry.name);
-		const destName = entry.name === "__dot__gitignore" ? ".gitignore" : entry.name;
-		const destPath = path.join(destDir, destName);
-		if (entry.isDirectory()) {
-			fs.mkdirSync(destPath, { recursive: true });
-			copyTemplateDir(srcPath, destPath, replacements, placeholderFiles);
-		} else {
-			fs.mkdirSync(path.dirname(destPath), { recursive: true });
-			if (placeholderFiles.has(entry.name)) {
-				let content = fs.readFileSync(srcPath, "utf-8");
-				for (const [from, to] of Object.entries(replacements)) content = content.replaceAll(from, to);
-				fs.writeFileSync(destPath, content);
-			} else fs.copyFileSync(srcPath, destPath);
-		}
-	}
-}
-function scaffoldModuleSrc(moduleDir, moduleName) {
-	copyTemplateDir(path.join(PACKAGE_ROOT, "templates", "scaffold", "module"), moduleDir, { "template-module": moduleName }, new Set(["permissions.ts", "tailor.config.ts"]));
-}
-function scaffoldAppSrc(appDir, appName) {
-	const templateDir = path.join(PACKAGE_ROOT, "templates", "scaffold", "app");
-	const erpKitVersion = readErpKitVersion();
-	copyTemplateDir(templateDir, appDir, {
-		"template-app-frontend": `${appName}-frontend`,
-		"template-app-backend": appName,
-		"template-app": appName,
-		"\"workspace:*\"": `"${erpKitVersion}"`
-	}, new Set([
-		"package.json",
-		"tailor.config.ts",
-		"index.html"
-	]));
-}
-//#endregion
-//#region src/commands/module/list.ts
-const MODULES_DIR = join(PACKAGE_ROOT, "src", "modules");
-const EXCLUDED_DIRS = new Set(["shared", "testing"]);
-function countFiles(dir, pattern, exclusions) {
-	if (!existsSync(dir)) return 0;
-	return readdirSync(dir).filter((f) => pattern.test(f) && !exclusions.some((p) => p.test(f))).length;
-}
-function listModules() {
-	if (!existsSync(MODULES_DIR)) return [];
-	return readdirSync(MODULES_DIR, { withFileTypes: true }).filter((d) => d.isDirectory() && !EXCLUDED_DIRS.has(d.name)).map((d) => {
-		const modDir = join(MODULES_DIR, d.name);
-		return {
-			name: d.name,
-			commands: countFiles(join(modDir, "command"), /\.ts$/, [/\.test\.ts$/]),
-			models: countFiles(join(modDir, "db"), /\.ts$/, [/\.test\.ts$/, /^index\.ts$/]),
-			features: countFiles(join(modDir, "docs", "features"), /\.md$/, [])
-		};
-	}).sort((a, b) => a.name.localeCompare(b.name));
-}
-function formatModuleList(modules) {
-	if (modules.length === 0) return "No modules found.";
-	const lines = [];
-	lines.push(chalk.bold("Modules:\n"));
-	const nameWidth = Math.max(...modules.map((m) => m.name.length), 4);
-	for (const mod of modules) {
-		const counts = [
-			`${mod.commands} commands`,
-			`${mod.models} models`,
-			`${mod.features} features`
-		].join(", ");
-		lines.push(`  ${mod.name.padEnd(nameWidth)}  ${counts}`);
-	}
-	lines.push("");
-	lines.push(`${modules.length} modules`);
-	return lines.join("\n");
-}
-function runModuleList() {
-	const modules = listModules();
-	console.log(formatModuleList(modules));
-	return 0;
-}
-//#endregion
 //#region src/generator/parse-command-doc.ts
 function parseCommandDoc(fileName, markdown) {
 	const commandName = fileName.charAt(0).toLowerCase() + fileName.slice(1);
@@ -820,17 +781,17 @@ function parseCommandDoc(fileName, markdown) {
 function errorCodeToClassName(code) {
 	return code.toLowerCase().split("_").map((word) => word.charAt(0).toUpperCase() + word.slice(1)).join("") + "Error";
 }
-function isHeading(node) {
+function isHeading$1(node) {
 	return node.type === "heading";
 }
 function isList(node) {
 	return node.type === "list";
 }
-function getNodesUnderHeading(tree, headingText) {
+function getNodesUnderHeading$1(tree, headingText) {
 	const nodes = [];
 	let collecting = false;
 	for (const node of tree.children) {
-		if (isHeading(node)) {
+		if (isHeading$1(node)) {
 			if (collecting) break;
 			if (node.depth === 2 && toString(node) === headingText) {
 				collecting = true;
@@ -843,7 +804,7 @@ function getNodesUnderHeading(tree, headingText) {
 }
 const ERROR_PATTERN = /^([A-Z_]+):\s*(.+)$/;
 function parseErrorScenarios(tree) {
-	const nodes = getNodesUnderHeading(tree, "Error Scenarios");
+	const nodes = getNodesUnderHeading$1(tree, "Error Scenarios");
 	const errors = [];
 	for (const node of nodes) {
 		if (!isList(node)) continue;
@@ -860,7 +821,7 @@ function parseErrorScenarios(tree) {
 }
 const DEPENDENCY_PATTERN = /^([^:]+)::(.+)$/;
 function parseExternalDependencies(tree) {
-	const nodes = getNodesUnderHeading(tree, "External Dependencies");
+	const nodes = getNodesUnderHeading$1(tree, "External Dependencies");
 	const deps = [];
 	for (const node of nodes) {
 		if (!isList(node)) continue;
@@ -880,7 +841,7 @@ function parseExternalDependencies(tree) {
 	return deps;
 }
 //#endregion
-//#region src/generator/generate-code.ts
+//#region src/generator/generate-errors.ts
 function moduleNameToPrefix(moduleName) {
 	return moduleName.toUpperCase().replace(/-/g, "_");
 }
@@ -906,9 +867,49 @@ import { createDomainError } from "../../../shared";
 
 ${lines.join("\n")}`;
 }
-function generateCommandStub(doc) {
-	const inputType = `${doc.commandName.charAt(0).toUpperCase() + doc.commandName.slice(1)}Input`;
-	return `import { ok, type CommandContext } from "../../../shared";
+//#endregion
+//#region src/generator/generate-permissions.ts
+function generatePermissions(moduleName, commandNames) {
+	return `// @generated — do not edit
+import { definePermissions } from "../../../shared";
+
+export const { permissions, own, all } = definePermissions("${moduleName}", [
+${[...commandNames].sort().map((name) => `  "${name}",`).join("\n")}
+] as const);
+`;
+}
+//#endregion
+//#region src/generator/generate-shells.ts
+function generateCommandShell(doc) {
+	return [
+		`// @generated — do not edit`,
+		`import { defineCommand } from "../../../shared";`,
+		`import { permissions } from "../lib/permissions.generated";`,
+		`import { run } from "./${doc.commandName}";`,
+		``,
+		`export const ${doc.commandName} = defineCommand(permissions.${doc.commandName}, run);`,
+		``
+	].join("\n");
+}
+function generateQueryShell(doc) {
+	return [
+		`// @generated — do not edit`,
+		`import { defineQuery } from "../../../shared";`,
+		`import { run } from "./${doc.commandName}";`,
+		``,
+		`export const ${doc.commandName} = defineQuery(run);`,
+		``
+	].join("\n");
+}
+//#endregion
+//#region src/generator/stub-templates.ts
+function toPascal(name) {
+	return name.charAt(0).toUpperCase() + name.slice(1);
+}
+const templates = {
+	command: { render: (name) => {
+		const inputType = `${toPascal(name)}Input`;
+		return `import { ok, type CommandContext } from "../../../shared";
 import type { Transaction } from "../generated/kysely-tailordb";
 
 export interface ${inputType} {
@@ -920,19 +921,19 @@ export async function run(db: Transaction, input: ${inputType}, ctx: CommandCont
   return ok({});
 }
 `;
-}
-function generateTestStub(doc) {
-	const pascal = doc.commandName.charAt(0).toUpperCase() + doc.commandName.slice(1);
-	return `import { describe, expect, it } from "vitest";
+	} },
+	commandTest: { render: (name) => {
+		const pascal = toPascal(name);
+		return `import { describe, expect, it } from "vitest";
 import { createMockDb } from "../../../testing/index";
 import type { CommandContext } from "../../../shared";
 import type { Transaction } from "../generated/kysely-tailordb";
-import { run, ${pascal}Input } from "./${doc.commandName}";
+import { run, ${pascal}Input } from "./${name}";
 
-describe("${doc.commandName} - test scenario", () => {
+describe("${name} - test scenario", () => {
   const ctx: CommandContext = {
     actorId: "test-actor",
-    permissions: ["TODO:${doc.commandName}"],
+    permissions: ["TODO:${name}"],
   };
 
   it("should be implemented", async () => {
@@ -942,31 +943,10 @@ describe("${doc.commandName} - test scenario", () => {
   });
 });
 `;
-}
-function generateCommandShell(doc) {
-	return [
-		`// @generated — do not edit`,
-		`import { defineCommand } from "../../../shared";`,
-		`import { permissions } from "../lib/permissions.generated";`,
-		`import { run } from "./${doc.commandName}";`,
-		``,
-		`export const ${doc.commandName} = defineCommand(permissions.${doc.commandName}, run);`,
-		``
-	].join("\n");
-}
-function generateQueryShell(doc) {
-	return [
-		`// @generated — do not edit`,
-		`import { defineQuery } from "../../../shared";`,
-		`import { run } from "./${doc.commandName}";`,
-		``,
-		`export const ${doc.commandName} = defineQuery(run);`,
-		``
-	].join("\n");
-}
-function generateQueryStub(doc) {
-	const inputType = `${doc.commandName.charAt(0).toUpperCase() + doc.commandName.slice(1)}Input`;
-	return `import type { ReadonlyDB } from "../../../shared";
+	} },
+	query: { render: (name) => {
+		const inputType = `${toPascal(name)}Input`;
+		return `import type { ReadonlyDB } from "../../../shared";
 import type { DB } from "../generated/kysely-tailordb";
 
 export interface ${inputType} {
@@ -978,15 +958,15 @@ export async function run(db: ReadonlyDB<DB>, input: ${inputType}) {
   return {};
 }
 `;
-}
-function generateQueryTestStub(doc) {
-	const inputType = `${doc.commandName.charAt(0).toUpperCase() + doc.commandName.slice(1)}Input`;
-	return `import { describe, expect, it } from "vitest";
+	} },
+	queryTest: { render: (name) => {
+		const inputType = `${toPascal(name)}Input`;
+		return `import { describe, expect, it } from "vitest";
 import { createMockDb } from "../../../testing/index";
 import type { DB } from "../generated/kysely-tailordb";
-import { run, type ${inputType} } from "./${doc.commandName}";
+import { run, type ${inputType} } from "./${name}";
 
-describe("${doc.commandName}", () => {
+describe("${name}", () => {
   it("should be implemented", async () => {
     const { db } = createMockDb<DB>();
     const result = await run(db, {} as ${inputType});
@@ -994,28 +974,140 @@ describe("${doc.commandName}", () => {
   });
 });
 `;
-}
-function generatePermissions(moduleName, commandNames) {
-	return `// @generated — do not edit
-import { definePermissions } from "../../../shared";
+	} },
+	db: { render: (name) => {
+		return `import { db, unsafeAllowAllGqlPermission, unsafeAllowAllTypePermission } from "@tailor-platform/sdk";
 
-export const { permissions, own, all } = definePermissions("${moduleName}", [
-${[...commandNames].sort().map((name) => `  "${name}",`).join("\n")}
-] as const);
+export const ${name} = db
+  .type("${toPascal(name)}", {
+    // TODO: define fields
+    ...db.fields.timestamps(),
+  })
+  .permission(unsafeAllowAllTypePermission)
+  .gqlPermission(unsafeAllowAllGqlPermission);
+`;
+	} },
+	resolver: { render: (name) => {
+		return `import { createResolver, t } from "@tailor-platform/sdk";
+import { createContext } from "@tailor-platform/erp-kit/app";
+import { getDB } from "@/generated/kysely-tailordb";
+
+export default createResolver({
+  name: "${name}",
+  operation: "mutation",
+  input: {
+    // TODO: define input fields
+  },
+  body: async (context) => {
+    const db = getDB("main-db");
+    return db.transaction().execute(async (trx) => {
+      // TODO: implement
+      return {};
+    });
+  },
+  output: t
+    .object({
+      // TODO: define output fields
+    })
+    .description("${toPascal(name)} response"),
+});
+`;
+	} },
+	resolverTest: { render: (name) => {
+		return `import { describe, expect, it } from "vitest";
+
+describe("${name}", () => {
+  it("should be implemented", async () => {
+    const resolver = await import("./${name}");
+    expect(resolver.default).toBeDefined();
+    expect(resolver.default.name).toBe("${name}");
+  });
+});
 `;
+	} }
+};
+function renderStub(type, name) {
+	return templates[type].render(name);
+}
+//#endregion
+//#region src/generator/generate-stubs.ts
+function generateCommandStub(doc) {
+	return renderStub("command", doc.commandName);
+}
+function generateTestStub(doc) {
+	return renderStub("commandTest", doc.commandName);
+}
+function generateQueryStub(doc) {
+	return renderStub("query", doc.commandName);
+}
+function generateQueryTestStub(doc) {
+	return renderStub("queryTest", doc.commandName);
+}
+function generateDbStub(modelName) {
+	return renderStub("db", modelName);
 }
+function generateResolverStub(resolverName) {
+	return renderStub("resolver", resolverName);
+}
+function generateResolverTestStub(resolverName) {
+	return renderStub("resolverTest", resolverName);
+}
+//#endregion
+//#region src/generator/scaffold.ts
+function copyTemplateDir(srcDir, destDir, replacements, placeholderFiles) {
+	for (const entry of fs.readdirSync(srcDir, { withFileTypes: true })) {
+		const srcPath = path.join(srcDir, entry.name);
+		const destName = entry.name === "__dot__gitignore" ? ".gitignore" : entry.name;
+		const destPath = path.join(destDir, destName);
+		if (entry.name === "node_modules") continue;
+		if (entry.isDirectory()) {
+			fs.mkdirSync(destPath, { recursive: true });
+			copyTemplateDir(srcPath, destPath, replacements, placeholderFiles);
+		} else {
+			if (fs.existsSync(destPath)) continue;
+			fs.mkdirSync(path.dirname(destPath), { recursive: true });
+			if (placeholderFiles.has(entry.name)) {
+				let content = fs.readFileSync(srcPath, "utf-8");
+				for (const [from, to] of Object.entries(replacements)) content = content.replaceAll(from, to);
+				fs.writeFileSync(destPath, content);
+			} else fs.copyFileSync(srcPath, destPath);
+		}
+	}
+}
+function scaffoldModuleBoilerplate(moduleDir, moduleName) {
+	copyTemplateDir(path.join(PACKAGE_ROOT, "templates", "scaffold", "module"), moduleDir, { "template-module": moduleName }, new Set(["permissions.ts", "tailor.config.ts"]));
+}
+function scaffoldAppBoilerplate(appDir, appName) {
+	const templateDir = path.join(PACKAGE_ROOT, "templates", "scaffold", "app");
+	const erpKitVersion = readErpKitVersion();
+	copyTemplateDir(templateDir, appDir, {
+		"template-app-frontend": `${appName}-frontend`,
+		"template-app-backend": appName,
+		"template-app": appName,
+		"\"workspace:*\"": `"${erpKitVersion}"`
+	}, new Set([
+		"package.json",
+		"tailor.config.ts",
+		"index.html"
+	]));
+}
+//#endregion
+//#region src/generator/generate-code.ts
 function runGenerateCode(modulePath, moduleName) {
+	scaffoldModuleBoilerplate(modulePath, moduleName);
 	const docsDir = path.join(modulePath, "docs", "commands");
 	const libDir = path.join(modulePath, "lib");
 	const commandDir = path.join(modulePath, "command");
 	if (!fs.existsSync(docsDir)) {
-		console.error(`No docs/commands/ directory found at ${docsDir}`);
-		return 1;
+		console.log(`No docs/commands/ directory found — skipping code generation`);
+		console.log(`Generated boilerplate for ${moduleName}`);
+		return 0;
 	}
 	const mdFiles = fs.readdirSync(docsDir).filter((f) => f.endsWith(".md"));
 	if (mdFiles.length === 0) {
-		console.error(`No command docs found in ${docsDir}`);
-		return 1;
+		console.log(`No command docs found — skipping code generation`);
+		console.log(`Generated boilerplate for ${moduleName}`);
+		return 0;
 	}
 	const parsedDocs = [];
 	for (const file of mdFiles) {
@@ -1090,149 +1182,404 @@ function runGenerateCode(modulePath, moduleName) {
 			}
 		}
 	}
+	const modelDocsDir = path.join(modulePath, "docs", "models");
+	if (fs.existsSync(modelDocsDir)) {
+		const modelFiles = fs.readdirSync(modelDocsDir).filter((f) => f.endsWith(".md"));
+		if (modelFiles.length > 0) {
+			const dbDir = path.join(modulePath, "db");
+			fs.mkdirSync(dbDir, { recursive: true });
+			for (const file of modelFiles) {
+				const modelName = path.basename(file, ".md");
+				const camelName = modelName.charAt(0).toLowerCase() + modelName.slice(1);
+				const dbFile = path.join(dbDir, `${camelName}.ts`);
+				if (!fs.existsSync(dbFile)) {
+					fs.writeFileSync(dbFile, generateDbStub(camelName));
+					console.log(`  scaffolded ${path.relative(modulePath, dbFile)}`);
+				}
+			}
+		}
+	}
 	console.log(`Generated ${generated} file(s) for ${moduleName}`);
 	return 0;
 }
 //#endregion
+//#region src/commands/generate-doc.ts
+const MODULE_DOC_TYPES = [
+	"feature",
+	"command",
+	"model",
+	"query"
+];
+const APP_DOC_TYPES = [
+	"actors",
+	"business-flow",
+	"story",
+	"screen",
+	"resolver"
+];
+[...MODULE_DOC_TYPES, ...APP_DOC_TYPES];
+const MODULE_DIR_MAP = {
+	feature: MODULE_PATHS.docs.features,
+	command: MODULE_PATHS.docs.commands,
+	model: MODULE_PATHS.docs.models,
+	query: MODULE_PATHS.docs.queries
+};
+const APP_DIR_MAP = {
+	actors: APP_PATHS.docs.actors,
+	"business-flow": APP_PATHS.docs.businessFlow,
+	screen: APP_PATHS.docs.screen,
+	resolver: APP_PATHS.docs.resolver
+};
+function resolveDocPath(type, name, modulePath) {
+	if (!name) throw new Error(`Name is required for doc type "${type}"`);
+	if (type === "business-flow") return path.join(modulePath, APP_PATHS.docs.businessFlow, name, "README.md");
+	if (type === "story") {
+		const parts = name.split("/");
+		if (parts.length !== 2) throw new Error(`Story name must be "<flow>/<story>" (e.g., "onboarding/admin--create-user")`);
+		return path.join(modulePath, APP_PATHS.docs.businessFlow, parts[0], APP_PATHS.storySegment, `${parts[1]}.md`);
+	}
+	if (MODULE_DIR_MAP[type]) return path.join(modulePath, MODULE_DIR_MAP[type], `${name}.md`);
+	if (APP_DIR_MAP[type]) return path.join(modulePath, APP_DIR_MAP[type], `${name}.md`);
+	throw new Error(`Unknown doc type: ${type}`);
+}
+async function runGenerateDoc(type, name, modulePath, cwd) {
+	const outputPath = resolveDocPath(type, name, modulePath);
+	const absoluteOutput = path.resolve(cwd, outputPath);
+	if (fs.existsSync(absoluteOutput)) {
+		console.error(`File already exists: ${outputPath}`);
+		return 1;
+	}
+	const schemaPath = ALL_SCHEMAS[type];
+	if (!schemaPath) {
+		console.error(`No schema found for type: ${type}`);
+		return 2;
+	}
+	try {
+		fs.mkdirSync(path.dirname(absoluteOutput), { recursive: true });
+	} catch (err) {
+		console.error(`Failed to create directory: ${err instanceof Error ? err.message : String(err)}`);
+		return 1;
+	}
+	const { exitCode, stdout, stderr } = await runMdschema([
+		"generate",
+		"--schema",
+		schemaPath,
+		"--output",
+		absoluteOutput
+	], cwd);
+	if (stdout.trim()) console.log(stdout);
+	if (stderr.trim()) console.error(stderr);
+	return exitCode;
+}
+//#endregion
 //#region src/commands/module/generate.ts
 const cwd$3 = process.cwd();
-const generateCommand = defineCommand({
+const pathArgs$2 = z.object({ path: arg(z.string(), {
+	alias: "p",
+	description: "Path to the module directory"
+}) });
+const generateCommand$1 = defineCommand({
 	name: "generate",
-	description: "Generate code from model definitions and docs",
-	subCommands: { code: defineCommand({
-		name: "code",
-		description: "Generate errors, permissions, command shells, and query shells from docs",
-		args: z.object({
-			root: arg(z.string(), {
-				alias: "r",
-				description: "Path to modules directory"
+	description: "Generate docs and code for a module",
+	subCommands: {
+		doc: defineCommand({
+			name: "doc",
+			description: "Create a documentation file from a schema template",
+			args: pathArgs$2.extend({
+				type: arg(z.enum(MODULE_DOC_TYPES), {
+					positional: true,
+					description: `Doc type (${MODULE_DOC_TYPES.join(", ")})`
+				}),
+				name: arg(z.string().optional(), {
+					positional: true,
+					description: "Item name (required for all types)"
+				})
 			}),
-			module: arg(z.string(), {
-				positional: true,
-				description: "Module name (e.g., primitives, item-management)"
-			})
+			run: (args) => {
+				return executeCommand(async () => {
+					const exitCode = await runGenerateDoc(args.type, args.name, args.path, cwd$3);
+					return exitCode === 0 ? success() : silentFailure(exitCode);
+				});
+			}
 		}),
-		run: (args) => {
-			const modulePath = path.resolve(cwd$3, args.root, args.module);
-			console.log(`Generating code for ${args.module}...`);
-			const exitCode = runGenerateCode(modulePath, args.module);
-			process.exit(exitCode);
-		}
-	}) }
+		code: defineCommand({
+			name: "code",
+			description: "Generate boilerplate, implementation stubs, and generated code from docs",
+			args: pathArgs$2,
+			run: (args) => {
+				return executeCommand(() => {
+					const modulePath = path.resolve(cwd$3, args.path);
+					const moduleName = path.basename(modulePath);
+					console.log(`Generating code for ${moduleName}...`);
+					const exitCode = runGenerateCode(modulePath, moduleName);
+					return exitCode === 0 ? success() : silentFailure(exitCode);
+				});
+			}
+		})
+	}
 });
 //#endregion
 //#region src/commands/module/index.ts
 const cwd$2 = process.cwd();
-const rootArgs$1 = z.object({ root: arg(z.string(), {
-	alias: "r",
+const pathArgs$1 = z.object({ path: arg(z.string(), {
+	alias: "p",
 	description: "Path to modules directory"
 }) });
-const listCommand = defineCommand({
-	name: "list",
-	description: "List available modules",
-	run: () => {
-		const exitCode = runModuleList();
-		process.exit(exitCode);
-	}
-});
 const checkCommand$1 = defineCommand({
 	name: "check",
 	description: "Validate module docs against schemas",
-	args: rootArgs$1,
-	run: async (args) => {
-		const exitCode = await runCheck({ modulesRoot: args.root }, cwd$2);
-		process.exit(exitCode);
+	args: pathArgs$1,
+	run: (args) => {
+		return executeCommand(async () => {
+			const exitCode = await runCheck({ modulesRoot: args.path }, cwd$2);
+			return exitCode === 0 ? success() : silentFailure(exitCode);
+		});
 	}
 });
 const syncCheckCommand$1 = defineCommand({
 	name: "sync-check",
 	description: "Validate source <-> doc correspondence",
-	args: rootArgs$1,
-	run: async (args) => {
-		const result = await runSyncCheck({ modulesRoot: args.root }, cwd$2);
-		console.log(formatSyncCheckReport(result));
-		process.exit(result.exitCode);
+	args: pathArgs$1,
+	run: (args) => {
+		return executeCommand(async () => {
+			const result = await runSyncCheck({ modulesRoot: args.path }, cwd$2);
+			console.log(formatSyncCheckReport(result));
+			return result.exitCode === 0 ? success() : silentFailure(result.exitCode);
+		});
 	}
 });
-const scaffoldCommand$1 = defineCommand({
-	name: "scaffold",
-	description: "Generate module doc from schema template",
-	args: rootArgs$1.extend({
-		type: arg(z.enum(MODULE_TYPES), {
-			positional: true,
-			description: `Scaffold type (${MODULE_TYPES.join(", ")})`
-		}),
-		parent: arg(z.string(), {
+const initCommand$2 = defineCommand({
+	name: "init",
+	description: "Bootstrap a new module with directory structure and README",
+	args: z.object({
+		name: arg(z.string(), {
 			positional: true,
 			description: "Module name"
 		}),
-		name: arg(z.string().optional(), {
+		dir: arg(z.string(), {
 			positional: true,
-			description: "Item name (required for feature, command, model)"
+			description: "Parent directory where the module will be created"
 		})
 	}),
-	run: async (args) => {
-		const exitCode = await runScaffold(args.type, args.parent, args.name, args.root, cwd$2);
-		process.exit(exitCode);
+	run: (args) => {
+		return executeCommand(async () => {
+			const exitCode = await runInitModuleWithReadme(args.name, args.dir, cwd$2);
+			return exitCode === 0 ? success() : silentFailure(exitCode);
+		});
 	}
 });
-const moduleCommand = defineCommand({
+const moduleCommand$1 = defineCommand({
 	name: "module",
 	description: "Module management",
 	subCommands: {
-		list: listCommand,
 		check: checkCommand$1,
 		"sync-check": syncCheckCommand$1,
-		scaffold: scaffoldCommand$1,
-		generate: generateCommand
+		init: initCommand$2,
+		generate: generateCommand$1
 	}
 });
 //#endregion
+//#region src/generator/parse-resolver-doc.ts
+const MODULE_COMMAND_PATTERN = /([a-z][\w-]*)\.(\w+)/;
+const TABLE_ROW_PATTERN = /^\|(.+)\|(.+)\|$/;
+function parseResolverDoc(fileName, markdown) {
+	return {
+		resolverName: fileName.charAt(0).toLowerCase() + fileName.slice(1),
+		moduleCommands: parseModuleCommands(fromMarkdown(markdown)),
+		errors: parseExceptionHandlingFromRaw(markdown)
+	};
+}
+function isHeading(node) {
+	return node.type === "heading";
+}
+function getNodesUnderHeading(tree, headingText) {
+	const nodes = [];
+	let collecting = false;
+	for (const node of tree.children) {
+		if (isHeading(node)) {
+			if (collecting) break;
+			if (node.depth === 2 && toString(node) === headingText) {
+				collecting = true;
+				continue;
+			}
+		}
+		if (collecting) nodes.push(node);
+	}
+	return nodes;
+}
+function parseModuleCommands(tree) {
+	const nodes = getNodesUnderHeading(tree, "Modules Commands Used");
+	const commands = [];
+	for (const node of nodes) {
+		if (node.type !== "list") continue;
+		for (const item of node.children) {
+			const text = toString(item);
+			const match = MODULE_COMMAND_PATTERN.exec(text);
+			if (match) commands.push({
+				module: match[1],
+				command: match[2]
+			});
+		}
+	}
+	return commands;
+}
+function parseExceptionHandlingFromRaw(markdown) {
+	const lines = markdown.split("\n");
+	const errors = [];
+	let inSection = false;
+	let headerSkipped = false;
+	let separatorSkipped = false;
+	for (const line of lines) {
+		const trimmed = line.trim();
+		if (trimmed.startsWith("## Exception Handling")) {
+			inSection = true;
+			continue;
+		}
+		if (!inSection) continue;
+		if (trimmed.startsWith("#")) break;
+		if (!trimmed) continue;
+		const match = TABLE_ROW_PATTERN.exec(trimmed);
+		if (!match) continue;
+		if (!headerSkipped) {
+			headerSkipped = true;
+			continue;
+		}
+		if (!separatorSkipped) {
+			separatorSkipped = true;
+			continue;
+		}
+		const code = match[1].trim();
+		const description = match[2].trim();
+		if (code) errors.push({
+			code,
+			description
+		});
+	}
+	return errors;
+}
+//#endregion
+//#region src/generator/generate-app-code.ts
+function runGenerateAppCode(appPath) {
+	const appName = path.basename(appPath);
+	scaffoldAppBoilerplate(appPath, appName);
+	const docsDir = path.join(appPath, "docs", "resolver");
+	const resolverDir = path.join(appPath, "backend", "src", "resolvers");
+	if (!fs.existsSync(docsDir)) {
+		console.log(`No docs/resolver/ directory found — skipping resolver generation`);
+		console.log(`Generated boilerplate for ${appName}`);
+		return 0;
+	}
+	const mdFiles = fs.readdirSync(docsDir).filter((f) => f.endsWith(".md"));
+	if (mdFiles.length === 0) {
+		console.log(`No resolver docs found — skipping resolver generation`);
+		console.log(`Generated boilerplate for ${appName}`);
+		return 0;
+	}
+	fs.mkdirSync(resolverDir, { recursive: true });
+	let generated = 0;
+	for (const file of mdFiles) {
+		const content = fs.readFileSync(path.join(docsDir, file), "utf-8");
+		const doc = parseResolverDoc(path.basename(file, ".md"), content);
+		const implFile = path.join(resolverDir, `${doc.resolverName}.ts`);
+		if (!fs.existsSync(implFile)) {
+			fs.writeFileSync(implFile, generateResolverStub(doc.resolverName));
+			console.log(`  scaffolded ${path.relative(appPath, implFile)}`);
+			generated++;
+		}
+		const testFile = path.join(resolverDir, `${doc.resolverName}.test.ts`);
+		if (!fs.existsSync(testFile)) {
+			fs.writeFileSync(testFile, generateResolverTestStub(doc.resolverName));
+			console.log(`  scaffolded ${path.relative(appPath, testFile)}`);
+		}
+	}
+	console.log(`Scaffolded ${generated} resolver(s) for ${appName}`);
+	return 0;
+}
+//#endregion
 //#region src/commands/app/index.ts
 const cwd$1 = process.cwd();
-const rootArgs = z.object({ root: arg(z.string(), {
-	alias: "r",
+const pathArgs = z.object({ path: arg(z.string(), {
+	alias: "p",
 	description: "Path to app-compose directory"
 }) });
 const checkCommand = defineCommand({
 	name: "check",
 	description: "Validate app docs against schemas",
-	args: rootArgs,
-	run: async (args) => {
-		const exitCode = await runCheck({ appRoot: args.root }, cwd$1);
-		process.exit(exitCode);
+	args: pathArgs,
+	run: (args) => {
+		return executeCommand(async () => {
+			const exitCode = await runCheck({ appRoot: args.path }, cwd$1);
+			return exitCode === 0 ? success() : silentFailure(exitCode);
+		});
 	}
 });
 const syncCheckCommand = defineCommand({
 	name: "sync-check",
 	description: "Validate source <-> doc correspondence",
-	args: rootArgs,
-	run: async (args) => {
-		const result = await runSyncCheck({ appRoot: args.root }, cwd$1);
-		console.log(formatSyncCheckReport(result));
-		process.exit(result.exitCode);
+	args: pathArgs,
+	run: (args) => {
+		return executeCommand(async () => {
+			const result = await runSyncCheck({ appRoot: args.path }, cwd$1);
+			console.log(formatSyncCheckReport(result));
+			return result.exitCode === 0 ? success() : silentFailure(result.exitCode);
+		});
 	}
 });
-const scaffoldCommand = defineCommand({
-	name: "scaffold",
-	description: "Generate app doc from schema template",
-	args: rootArgs.extend({
-		type: arg(z.enum(APP_TYPES), {
-			positional: true,
-			description: `Scaffold type (${APP_TYPES.join(", ")})`
-		}),
-		parent: arg(z.string(), {
+const initCommand$1 = defineCommand({
+	name: "init",
+	description: "Bootstrap a new app with directory structure and README",
+	args: z.object({
+		name: arg(z.string(), {
 			positional: true,
 			description: "App name"
 		}),
-		name: arg(z.string().optional(), {
+		dir: arg(z.string(), {
 			positional: true,
-			description: "Item name (required for most types)"
+			description: "Parent directory where the app will be created"
 		})
 	}),
-	run: async (args) => {
-		const exitCode = await runScaffold(args.type, args.parent, args.name, args.root, cwd$1);
-		process.exit(exitCode);
+	run: (args) => {
+		return executeCommand(async () => {
+			const exitCode = await runInitAppWithReadme(args.name, args.dir, cwd$1);
+			return exitCode === 0 ? success() : silentFailure(exitCode);
+		});
+	}
+});
+const generateCommand = defineCommand({
+	name: "generate",
+	description: "Generate docs and code for an app",
+	subCommands: {
+		doc: defineCommand({
+			name: "doc",
+			description: "Create a documentation file from a schema template",
+			args: pathArgs.extend({
+				type: arg(z.enum(APP_DOC_TYPES), {
+					positional: true,
+					description: `Doc type (${APP_DOC_TYPES.join(", ")})`
+				}),
+				name: arg(z.string().optional(), {
+					positional: true,
+					description: "Item name (required for most types)"
+				})
+			}),
+			run: (args) => {
+				return executeCommand(async () => {
+					const exitCode = await runGenerateDoc(args.type, args.name, args.path, cwd$1);
+					return exitCode === 0 ? success() : silentFailure(exitCode);
+				});
+			}
+		}),
+		code: defineCommand({
+			name: "code",
+			description: "Generate boilerplate source files from docs",
+			args: pathArgs,
+			run: (args) => {
+				return executeCommand(() => {
+					const exitCode = runGenerateAppCode(path.resolve(cwd$1, args.path));
+					return exitCode === 0 ? success() : silentFailure(exitCode);
+				});
+			}
+		})
 	}
 });
 const appCommand = defineCommand({
@@ -1241,7 +1588,8 @@ const appCommand = defineCommand({
 	subCommands: {
 		check: checkCommand,
 		"sync-check": syncCheckCommand,
-		scaffold: scaffoldCommand
+		init: initCommand$1,
+		generate: generateCommand
 	}
 });
 //#endregion
@@ -1527,9 +1875,11 @@ const mockCommand = defineCommand({
 					description: "Filter by provider or provider/scenario"
 				})
 			}),
-			run: async (args) => {
-				const exitCode = await runMockStart(args.mocksRoot, args.filter, args.port);
-				process.exit(exitCode);
+			run: (args) => {
+				return executeCommand(async () => {
+					const exitCode = await runMockStart(args.mocksRoot, args.filter, args.port);
+					return exitCode === 0 ? success() : silentFailure(exitCode);
+				});
 			}
 		}),
 		validate: defineCommand({
@@ -1542,9 +1892,290 @@ const mockCommand = defineCommand({
 					description: "Specific scenario paths to validate"
 				})
 			}),
-			run: async (args) => {
-				const exitCode = await runMockValidate(args.mocksRoot, args.paths);
-				process.exit(exitCode);
+			run: (args) => {
+				return executeCommand(async () => {
+					const exitCode = await runMockValidate(args.mocksRoot, args.paths);
+					return exitCode === 0 ? success() : silentFailure(exitCode);
+				});
+			}
+		})
+	}
+});
+//#endregion
+//#region src/commands/doc/modules.ts
+const MODULES_DIR$2 = join(PACKAGE_ROOT, "src", "modules");
+const EXCLUDED_DIRS$2 = new Set(["shared", "testing"]);
+function countDocs(dir) {
+	if (!existsSync(dir)) return 0;
+	return readdirSync(dir).filter((f) => f.endsWith(".md")).length;
+}
+function extractOverview(readmePath) {
+	if (!existsSync(readmePath)) return "";
+	const content = readFileSync(readmePath, "utf-8");
+	const overviewMatch = /## Overview\n\n([\s\S]*?)(?=\n##\s|\n$)/.exec(content);
+	if (!overviewMatch) return "";
+	return overviewMatch[1].trim().split("\n\n")[0];
+}
+function extractDependencies(readmePath) {
+	if (!existsSync(readmePath)) return [];
+	const content = readFileSync(readmePath, "utf-8");
+	const depsMatch = /## Module Dependencies\n\n([\s\S]*?)(?=\n##\s|$)/.exec(content);
+	if (!depsMatch) return [];
+	const deps = [];
+	const linePattern = /^- \[([^\]]+)\]/;
+	for (const line of depsMatch[1].trim().split("\n")) {
+		const match = linePattern.exec(line);
+		if (match) deps.push(match[1]);
+	}
+	return deps;
+}
+function getModuleOverviews() {
+	if (!existsSync(MODULES_DIR$2)) return [];
+	return readdirSync(MODULES_DIR$2, { withFileTypes: true }).filter((d) => d.isDirectory() && !EXCLUDED_DIRS$2.has(d.name)).map((d) => {
+		const modDir = join(MODULES_DIR$2, d.name);
+		const readmePath = join(modDir, "README.md");
+		return {
+			name: d.name,
+			commandCount: countDocs(join(modDir, MODULE_PATHS.docs.commands)),
+			queryCount: countDocs(join(modDir, MODULE_PATHS.docs.queries)),
+			modelCount: countDocs(join(modDir, MODULE_PATHS.docs.models)),
+			overview: extractOverview(readmePath),
+			dependencies: extractDependencies(readmePath)
+		};
+	}).sort((a, b) => a.name.localeCompare(b.name));
+}
+function formatModuleOverviews(modules) {
+	if (modules.length === 0) return "No modules found.";
+	const lines = [];
+	for (const mod of modules) {
+		const counts = [
+			`${mod.commandCount} commands`,
+			`${mod.queryCount} queries`,
+			`${mod.modelCount} models`
+		].join(", ");
+		lines.push(`# ${mod.name} (${counts})`);
+		if (mod.overview) lines.push(mod.overview);
+		if (mod.dependencies.length > 0) lines.push(`Dependencies: ${mod.dependencies.join(", ")}`);
+		else lines.push("Dependencies: none");
+		lines.push("");
+	}
+	lines.push(`${modules.length} modules`);
+	return lines.join("\n");
+}
+function runDocModules(format = "text") {
+	const modules = getModuleOverviews();
+	if (format === "json") console.log(JSON.stringify(modules, null, 2));
+	else console.log(formatModuleOverviews(modules));
+	return 0;
+}
+//#endregion
+//#region src/commands/doc/module.ts
+const MODULES_DIR$1 = join(PACKAGE_ROOT, "src", "modules");
+const EXCLUDED_DIRS$1 = new Set(["shared", "testing"]);
+const DOC_TYPE_MAP$1 = {
+	command: MODULE_PATHS.docs.commands,
+	query: MODULE_PATHS.docs.queries,
+	model: MODULE_PATHS.docs.models,
+	feature: MODULE_PATHS.docs.features
+};
+function listDocNames(dir) {
+	if (!existsSync(dir)) return [];
+	return readdirSync(dir).filter((f) => f.endsWith(".md")).map((f) => f.replace(/\.md$/, "")).sort();
+}
+function formatDocList(type, names) {
+	if (names.length === 0) return "";
+	return `${type}: ${names.join(", ")}`;
+}
+function runDocModule(moduleName, docType, docName, format = "text") {
+	if (!existsSync(MODULES_DIR$1) || EXCLUDED_DIRS$1.has(moduleName)) {
+		console.error(`Module not found: ${moduleName}`);
+		return 1;
+	}
+	const modDir = join(MODULES_DIR$1, moduleName);
+	if (!existsSync(modDir)) {
+		console.error(`Module not found: ${moduleName}`);
+		const available = readdirSync(MODULES_DIR$1, { withFileTypes: true }).filter((d) => d.isDirectory() && !EXCLUDED_DIRS$1.has(d.name)).map((d) => d.name).sort();
+		console.error(`Available modules: ${available.join(", ")}`);
+		return 1;
+	}
+	if (docType && docName) {
+		const docSubdir = DOC_TYPE_MAP$1[docType];
+		if (!docSubdir) {
+			console.error(`Unknown doc type: ${docType}`);
+			console.error(`Available types: ${Object.keys(DOC_TYPE_MAP$1).join(", ")}`);
+			return 1;
+		}
+		const docPath = join(modDir, docSubdir, `${docName}.md`);
+		if (!existsSync(docPath)) {
+			console.error(`Doc not found: ${moduleName}/${docType}/${docName}`);
+			const available = listDocNames(join(modDir, docSubdir));
+			if (available.length > 0) console.error(`Available ${docType}s: ${available.join(", ")}`);
+			else console.error(`No ${docType} docs found for ${moduleName}`);
+			return 1;
+		}
+		const content = readFileSync(docPath, "utf-8");
+		if (format === "json") console.log(JSON.stringify({
+			module: moduleName,
+			type: docType,
+			name: docName,
+			content
+		}, null, 2));
+		else console.log(content);
+		return 0;
+	}
+	const readmePath = join(modDir, "README.md");
+	const readme = existsSync(readmePath) ? readFileSync(readmePath, "utf-8") : "";
+	const docs = {};
+	for (const [type, subdir] of Object.entries(DOC_TYPE_MAP$1)) {
+		const names = listDocNames(join(modDir, subdir));
+		if (names.length > 0) docs[type] = names;
+	}
+	if (format === "json") console.log(JSON.stringify({
+		module: moduleName,
+		readme,
+		docs
+	}, null, 2));
+	else {
+		if (readme) console.log(readme);
+		else console.log(`# ${moduleName}\n\nNo README found.\n`);
+		const sections = [];
+		for (const [type, names] of Object.entries(docs)) sections.push(formatDocList(type, names));
+		if (sections.length > 0) {
+			console.log("\n## Available Documentation\n");
+			console.log(sections.join("\n"));
+		}
+	}
+	return 0;
+}
+//#endregion
+//#region src/commands/doc/search.ts
+const MODULES_DIR = join(PACKAGE_ROOT, "src", "modules");
+const EXCLUDED_DIRS = new Set(["shared", "testing"]);
+const DOC_TYPE_MAP = {
+	command: MODULE_PATHS.docs.commands,
+	query: MODULE_PATHS.docs.queries,
+	model: MODULE_PATHS.docs.models,
+	feature: MODULE_PATHS.docs.features
+};
+function searchFile(filePath, query, module, type, name) {
+	if (!existsSync(filePath)) return [];
+	const content = readFileSync(filePath, "utf-8");
+	const lowerQuery = query.toLowerCase();
+	const results = [];
+	const lines = content.split("\n");
+	for (let i = 0; i < lines.length; i++) if (lines[i].toLowerCase().includes(lowerQuery)) results.push({
+		module,
+		type,
+		name,
+		line: i + 1,
+		excerpt: lines[i].trim()
+	});
+	return results;
+}
+function searchModuleDocs(query, typeFilter) {
+	if (!existsSync(MODULES_DIR)) return [];
+	const results = [];
+	const modules = readdirSync(MODULES_DIR, { withFileTypes: true }).filter((d) => d.isDirectory() && !EXCLUDED_DIRS.has(d.name)).sort((a, b) => a.name.localeCompare(b.name));
+	for (const mod of modules) {
+		const modDir = join(MODULES_DIR, mod.name);
+		if (!typeFilter || typeFilter === "readme") results.push(...searchFile(join(modDir, "README.md"), query, mod.name, "readme", "README"));
+		for (const [type, subdir] of Object.entries(DOC_TYPE_MAP)) {
+			if (typeFilter && typeFilter !== type) continue;
+			const docsDir = join(modDir, subdir);
+			if (!existsSync(docsDir)) continue;
+			const files = readdirSync(docsDir).filter((f) => f.endsWith(".md"));
+			for (const file of files) {
+				const name = file.replace(/\.md$/, "");
+				results.push(...searchFile(join(docsDir, file), query, mod.name, type, name));
+			}
+		}
+	}
+	return results;
+}
+function formatSearchResults(results) {
+	if (results.length === 0) return "No results found.";
+	const lines = [];
+	for (const r of results) lines.push(`${r.module}/${r.type}/${r.name}:${r.line}: ${r.excerpt}`);
+	lines.push("");
+	lines.push(`${results.length} matches`);
+	return lines.join("\n");
+}
+function runDocSearch(query, type, format = "text") {
+	if (type && type !== "readme" && !(type in DOC_TYPE_MAP)) {
+		console.error(`Unknown doc type: ${type}`);
+		console.error(`Available types: readme, ${Object.keys(DOC_TYPE_MAP).join(", ")}`);
+		return 1;
+	}
+	const results = searchModuleDocs(query, type);
+	if (format === "json") console.log(JSON.stringify(results, null, 2));
+	else console.log(formatSearchResults(results));
+	return 0;
+}
+//#endregion
+//#region src/commands/doc/index.ts
+const formatArg = arg(z.enum(["text", "json"]).default("text"), {
+	alias: "f",
+	description: "Output format (text or json)"
+});
+const docCommand = defineCommand({
+	name: "doc",
+	description: "Browse module documentation",
+	subCommands: {
+		modules: defineCommand({
+			name: "modules",
+			description: "List all modules with capabilities overview",
+			args: z.object({ format: formatArg }),
+			run: (args) => {
+				return executeCommand(() => {
+					const exitCode = runDocModules(args.format);
+					return exitCode === 0 ? success() : silentFailure(exitCode);
+				});
+			}
+		}),
+		module: defineCommand({
+			name: "module",
+			description: "Show documentation for a specific module",
+			args: z.object({
+				name: arg(z.string(), {
+					positional: true,
+					description: "Module name"
+				}),
+				type: arg(z.string().optional(), {
+					positional: true,
+					description: "Doc type (command, query, model, feature)"
+				}),
+				docName: arg(z.string().optional(), {
+					positional: true,
+					description: "Doc name"
+				}),
+				format: formatArg
+			}),
+			run: (args) => {
+				return executeCommand(() => {
+					const exitCode = runDocModule(args.name, args.type, args.docName, args.format);
+					return exitCode === 0 ? success() : silentFailure(exitCode);
+				});
+			}
+		}),
+		search: defineCommand({
+			name: "search",
+			description: "Search across all module documentation",
+			args: z.object({
+				query: arg(z.string(), {
+					positional: true,
+					description: "Search query"
+				}),
+				type: arg(z.string().optional(), {
+					alias: "t",
+					description: "Filter by doc type (command, query, model, feature, readme)"
+				}),
+				format: formatArg
+			}),
+			run: (args) => {
+				return executeCommand(() => {
+					const exitCode = runDocSearch(args.query, args.type, args.format);
+					return exitCode === 0 ? success() : silentFailure(exitCode);
+				});
 			}
 		})
 	}
@@ -1558,15 +2189,18 @@ runMain(defineCommand({
 	name: "erp-kit",
 	description: "ERP module framework CLI",
 	subCommands: {
-		module: moduleCommand,
+		module: moduleCommand$1,
 		app: appCommand,
 		mock: mockCommand,
+		doc: docCommand,
 		init: defineCommand({
 			name: "init",
 			description: "First-time setup for a consumer repo",
 			run: () => {
-				const exitCode = runInit(cwd);
-				process.exit(exitCode);
+				return executeCommand(() => {
+					const exitCode = runInit(cwd);
+					return exitCode === 0 ? success() : silentFailure(exitCode);
+				});
 			}
 		}),
 		update: defineCommand({
@@ -1577,8 +2211,10 @@ runMain(defineCommand({
 				description: "Resources to update (skills, workflows). Defaults to all."
 			}) }),
 			run: (args) => {
-				const exitCode = runUpdate(cwd, args.resources);
-				process.exit(exitCode);
+				return executeCommand(() => {
+					const exitCode = runUpdate(cwd, args.resources);
+					return exitCode === 0 ? success() : silentFailure(exitCode);
+				});
 			}
 		}),
 		license: defineCommand({
@@ -1593,16 +2229,20 @@ runMain(defineCommand({
 						description: "Path to license config JSON file"
 					}) }),
 					run: (args) => {
-						const exitCode = runLicenseCheck(args.config);
-						process.exit(exitCode);
+						return executeCommand(() => {
+							const exitCode = runLicenseCheck(args.config);
+							return exitCode === 0 ? success() : silentFailure(exitCode);
+						});
 					}
 				}),
 				list: defineCommand({
 					name: "list",
 					description: "List available license groups",
 					run: () => {
-						const exitCode = runLicenseList();
-						process.exit(exitCode);
+						return executeCommand(() => {
+							const exitCode = runLicenseList();
+							return exitCode === 0 ? success() : silentFailure(exitCode);
+						});
 					}
 				})
 			}