create-m5kdev 0.32.8 → 0.34.0

package/dist/src/prompts.d.cts

@@ -1,7 +1,13 @@
 import { CreateCommandOptions } from "./types.cjs";
+import { BackendModuleChoice } from "./template.cjs";
 
 //#region src/prompts.d.ts
+declare function formatBackendModulesPrompt(choices: readonly BackendModuleChoice[]): string;
+declare function parseBackendModulesAnswer(options: {
+  answer: string;
+  choices: readonly BackendModuleChoice[];
+}): string[];
 declare function resolveCreateCommandOptions(options: CreateCommandOptions): Promise<CreateCommandOptions>;
 //#endregion
-export { resolveCreateCommandOptions };
+export { formatBackendModulesPrompt, parseBackendModulesAnswer, resolveCreateCommandOptions };
 //# sourceMappingURL=prompts.d.cts.map

package/dist/src/template.cjs

@@ -26,11 +26,28 @@ function getTemplateFilePolicy(manifest, relativePath) {
 	for (const rule of manifest.sync.rules) if (globToRegExp(rule.pattern).test(relativePath)) return rule.policy;
 	return manifest.sync.defaultPolicy;
 }
-function getEnabledFeatures(platform, testHarness) {
+function getFeatureKind(options) {
+	if (options.config.kind) return options.config.kind;
+	if (options.id === "webapp" || options.id === "expo") return "platform";
+	if (options.id === "test-harness") return "harness";
+	return "module";
+}
+function listBackendModuleChoices(manifest) {
+	return Object.entries(manifest.features).filter(([id, config]) => getFeatureKind({
+		id,
+		config
+	}) === "module").map(([id, config]) => ({
+		id,
+		label: config.label ?? id,
+		experimental: Boolean(config.experimental)
+	}));
+}
+function getEnabledFeatures(options) {
 	const enabled = /* @__PURE__ */ new Set();
-	if (platform !== "expo") enabled.add("webapp");
-	if (platform !== "web") enabled.add("expo");
-	if (testHarness) enabled.add("test-harness");
+	if (options.platform !== "expo") enabled.add("webapp");
+	if (options.platform !== "web") enabled.add("expo");
+	if (options.testHarness) enabled.add("test-harness");
+	for (const id of options.modules ?? []) enabled.add(id);
 	return enabled;
 }
 function getExcludedFeaturePaths(manifest, enabledFeatures) {
@@ -39,7 +56,9 @@ function getExcludedFeaturePaths(manifest, enabledFeatures) {
 //#endregion
 exports.getEnabledFeatures = getEnabledFeatures;
 exports.getExcludedFeaturePaths = getExcludedFeaturePaths;
+exports.getFeatureKind = getFeatureKind;
 exports.getTemplateFilePolicy = getTemplateFilePolicy;
+exports.listBackendModuleChoices = listBackendModuleChoices;
 exports.loadTemplateManifest = loadTemplateManifest;
 
 //# sourceMappingURL=template.cjs.map

package/dist/src/template.cjs.map

@@ -1 +1 @@
-{"version":3,"file":"template.cjs","names":["path","fs"],"sources":["../../src/template.ts"],"sourcesContent":["import fs from \"node:fs\";\r\nimport path from \"node:path\";\r\nimport type { TemplateFeatureManifest, TemplateFilePolicy } from \"./types\";\r\n\r\nexport function loadTemplateManifest(templateDirectory: string): TemplateFeatureManifest {\r\n  const manifestPath = path.join(templateDirectory, \"template.manifest.json\");\r\n  if (!fs.existsSync(manifestPath)) {\r\n    throw new Error(`Template manifest is missing: ${manifestPath}`);\r\n  }\r\n  return JSON.parse(fs.readFileSync(manifestPath, \"utf8\")) as TemplateFeatureManifest;\r\n}\r\n\r\nfunction globToRegExp(pattern: string): RegExp {\r\n  let source = \"^\";\r\n  for (let index = 0; index < pattern.length; index += 1) {\r\n    const character = pattern[index];\r\n    if (character === \"*\" && pattern[index + 1] === \"*\") {\r\n      source += \".*\";\r\n      index += 1;\r\n    } else if (character === \"*\") {\r\n      source += \"[^/]*\";\r\n    } else {\r\n      source += character.replace(/[.*+?^${}()|[\\]\\\\]/g, \"\\\\$&\");\r\n    }\r\n  }\r\n  return new RegExp(`${source}$`);\r\n}\r\n\r\nexport function getTemplateFilePolicy(\r\n  manifest: TemplateFeatureManifest,\r\n  relativePath: string\r\n): TemplateFilePolicy {\r\n  for (const rule of manifest.sync.rules) {\r\n    if (globToRegExp(rule.pattern).test(relativePath)) return rule.policy;\r\n  }\r\n  return manifest.sync.defaultPolicy;\r\n}\r\n\r\nexport function getEnabledFeatures(\r\n  platform: \"web\" | \"expo\" | \"both\",\r\n  testHarness: boolean\r\n): Set<string> {\r\n  const enabled = new Set<string>();\r\n  if (platform !== \"expo\") enabled.add(\"webapp\");\r\n  if (platform !== \"web\") enabled.add(\"expo\");\r\n  if (testHarness) enabled.add(\"test-harness\");\r\n  return enabled;\r\n}\r\n\r\nexport function getExcludedFeaturePaths(\r\n  manifest: TemplateFeatureManifest,\r\n  enabledFeatures: ReadonlySet<string>\r\n): string[] {\r\n  return Object.entries(manifest.features)\r\n    .filter(([feature]) => !enabledFeatures.has(feature))\r\n    .flatMap(([, config]) => [...config.paths]);\r\n}\r\n"],"mappings":";;;;;;;AAIA,SAAgB,qBAAqB,mBAAoD;CACvF,MAAM,eAAeA,UAAAA,QAAK,KAAK,mBAAmB,yBAAyB;AAC3E,KAAI,CAACC,QAAAA,QAAG,WAAW,aAAa,CAC9B,OAAM,IAAI,MAAM,iCAAiC,eAAe;AAElE,QAAO,KAAK,MAAMA,QAAAA,QAAG,aAAa,cAAc,OAAO,CAAC;;AAG1D,SAAS,aAAa,SAAyB;CAC7C,IAAI,SAAS;AACb,MAAK,IAAI,QAAQ,GAAG,QAAQ,QAAQ,QAAQ,SAAS,GAAG;EACtD,MAAM,YAAY,QAAQ;AAC1B,MAAI,cAAc,OAAO,QAAQ,QAAQ,OAAO,KAAK;AACnD,aAAU;AACV,YAAS;aACA,cAAc,IACvB,WAAU;MAEV,WAAU,UAAU,QAAQ,uBAAuB,OAAO;;AAG9D,QAAO,IAAI,OAAO,GAAG,OAAO,GAAG;;AAGjC,SAAgB,sBACd,UACA,cACoB;AACpB,MAAK,MAAM,QAAQ,SAAS,KAAK,MAC/B,KAAI,aAAa,KAAK,QAAQ,CAAC,KAAK,aAAa,CAAE,QAAO,KAAK;AAEjE,QAAO,SAAS,KAAK;;AAGvB,SAAgB,mBACd,UACA,aACa;CACb,MAAM,0BAAU,IAAI,KAAa;AACjC,KAAI,aAAa,OAAQ,SAAQ,IAAI,SAAS;AAC9C,KAAI,aAAa,MAAO,SAAQ,IAAI,OAAO;AAC3C,KAAI,YAAa,SAAQ,IAAI,eAAe;AAC5C,QAAO;;AAGT,SAAgB,wBACd,UACA,iBACU;AACV,QAAO,OAAO,QAAQ,SAAS,SAAS,CACrC,QAAQ,CAAC,aAAa,CAAC,gBAAgB,IAAI,QAAQ,CAAC,CACpD,SAAS,GAAG,YAAY,CAAC,GAAG,OAAO,MAAM,CAAC"}
+{"version":3,"file":"template.cjs","names":["path","fs"],"sources":["../../src/template.ts"],"sourcesContent":["import fs from \"node:fs\";\r\nimport path from \"node:path\";\r\nimport type { TemplateFeatureKind, TemplateFeatureManifest, TemplateFilePolicy } from \"./types\";\r\n\r\nexport function loadTemplateManifest(templateDirectory: string): TemplateFeatureManifest {\r\n  const manifestPath = path.join(templateDirectory, \"template.manifest.json\");\r\n  if (!fs.existsSync(manifestPath)) {\r\n    throw new Error(`Template manifest is missing: ${manifestPath}`);\r\n  }\r\n  return JSON.parse(fs.readFileSync(manifestPath, \"utf8\")) as TemplateFeatureManifest;\r\n}\r\n\r\nfunction globToRegExp(pattern: string): RegExp {\r\n  let source = \"^\";\r\n  for (let index = 0; index < pattern.length; index += 1) {\r\n    const character = pattern[index];\r\n    if (character === \"*\" && pattern[index + 1] === \"*\") {\r\n      source += \".*\";\r\n      index += 1;\r\n    } else if (character === \"*\") {\r\n      source += \"[^/]*\";\r\n    } else {\r\n      source += character.replace(/[.*+?^${}()|[\\]\\\\]/g, \"\\\\$&\");\r\n    }\r\n  }\r\n  return new RegExp(`${source}$`);\r\n}\r\n\r\nexport function getTemplateFilePolicy(\r\n  manifest: TemplateFeatureManifest,\r\n  relativePath: string\r\n): TemplateFilePolicy {\r\n  for (const rule of manifest.sync.rules) {\r\n    if (globToRegExp(rule.pattern).test(relativePath)) return rule.policy;\r\n  }\r\n  return manifest.sync.defaultPolicy;\r\n}\r\n\r\nexport interface BackendModuleChoice {\r\n  id: string;\r\n  label: string;\r\n  experimental: boolean;\r\n}\r\n\r\nexport function getFeatureKind(options: {\r\n  id: string;\r\n  config: TemplateFeatureManifest[\"features\"][string];\r\n}): TemplateFeatureKind {\r\n  if (options.config.kind) return options.config.kind;\r\n  if (options.id === \"webapp\" || options.id === \"expo\") return \"platform\";\r\n  if (options.id === \"test-harness\") return \"harness\";\r\n  return \"module\";\r\n}\r\n\r\nexport function listBackendModuleChoices(manifest: TemplateFeatureManifest): BackendModuleChoice[] {\r\n  return Object.entries(manifest.features)\r\n    .filter(([id, config]) => getFeatureKind({ id, config }) === \"module\")\r\n    .map(([id, config]) => ({\r\n      id,\r\n      label: config.label ?? id,\r\n      experimental: Boolean(config.experimental),\r\n    }));\r\n}\r\n\r\nexport function getEnabledFeatures(options: {\r\n  platform: \"web\" | \"expo\" | \"both\";\r\n  testHarness: boolean;\r\n  modules?: readonly string[];\r\n}): Set<string> {\r\n  const enabled = new Set<string>();\r\n  if (options.platform !== \"expo\") enabled.add(\"webapp\");\r\n  if (options.platform !== \"web\") enabled.add(\"expo\");\r\n  if (options.testHarness) enabled.add(\"test-harness\");\r\n  for (const id of options.modules ?? []) enabled.add(id);\r\n  return enabled;\r\n}\r\n\r\nexport function getExcludedFeaturePaths(\r\n  manifest: TemplateFeatureManifest,\r\n  enabledFeatures: ReadonlySet<string>\r\n): string[] {\r\n  return Object.entries(manifest.features)\r\n    .filter(([feature]) => !enabledFeatures.has(feature))\r\n    .flatMap(([, config]) => [...config.paths]);\r\n}\r\n"],"mappings":";;;;;;;AAIA,SAAgB,qBAAqB,mBAAoD;CACvF,MAAM,eAAeA,UAAAA,QAAK,KAAK,mBAAmB,yBAAyB;AAC3E,KAAI,CAACC,QAAAA,QAAG,WAAW,aAAa,CAC9B,OAAM,IAAI,MAAM,iCAAiC,eAAe;AAElE,QAAO,KAAK,MAAMA,QAAAA,QAAG,aAAa,cAAc,OAAO,CAAC;;AAG1D,SAAS,aAAa,SAAyB;CAC7C,IAAI,SAAS;AACb,MAAK,IAAI,QAAQ,GAAG,QAAQ,QAAQ,QAAQ,SAAS,GAAG;EACtD,MAAM,YAAY,QAAQ;AAC1B,MAAI,cAAc,OAAO,QAAQ,QAAQ,OAAO,KAAK;AACnD,aAAU;AACV,YAAS;aACA,cAAc,IACvB,WAAU;MAEV,WAAU,UAAU,QAAQ,uBAAuB,OAAO;;AAG9D,QAAO,IAAI,OAAO,GAAG,OAAO,GAAG;;AAGjC,SAAgB,sBACd,UACA,cACoB;AACpB,MAAK,MAAM,QAAQ,SAAS,KAAK,MAC/B,KAAI,aAAa,KAAK,QAAQ,CAAC,KAAK,aAAa,CAAE,QAAO,KAAK;AAEjE,QAAO,SAAS,KAAK;;AASvB,SAAgB,eAAe,SAGP;AACtB,KAAI,QAAQ,OAAO,KAAM,QAAO,QAAQ,OAAO;AAC/C,KAAI,QAAQ,OAAO,YAAY,QAAQ,OAAO,OAAQ,QAAO;AAC7D,KAAI,QAAQ,OAAO,eAAgB,QAAO;AAC1C,QAAO;;AAGT,SAAgB,yBAAyB,UAA0D;AACjG,QAAO,OAAO,QAAQ,SAAS,SAAS,CACrC,QAAQ,CAAC,IAAI,YAAY,eAAe;EAAE;EAAI;EAAQ,CAAC,KAAK,SAAS,CACrE,KAAK,CAAC,IAAI,aAAa;EACtB;EACA,OAAO,OAAO,SAAS;EACvB,cAAc,QAAQ,OAAO,aAAa;EAC3C,EAAE;;AAGP,SAAgB,mBAAmB,SAInB;CACd,MAAM,0BAAU,IAAI,KAAa;AACjC,KAAI,QAAQ,aAAa,OAAQ,SAAQ,IAAI,SAAS;AACtD,KAAI,QAAQ,aAAa,MAAO,SAAQ,IAAI,OAAO;AACnD,KAAI,QAAQ,YAAa,SAAQ,IAAI,eAAe;AACpD,MAAK,MAAM,MAAM,QAAQ,WAAW,EAAE,CAAE,SAAQ,IAAI,GAAG;AACvD,QAAO;;AAGT,SAAgB,wBACd,UACA,iBACU;AACV,QAAO,OAAO,QAAQ,SAAS,SAAS,CACrC,QAAQ,CAAC,aAAa,CAAC,gBAAgB,IAAI,QAAQ,CAAC,CACpD,SAAS,GAAG,YAAY,CAAC,GAAG,OAAO,MAAM,CAAC"}

package/dist/src/template.d.cts

@@ -1,10 +1,24 @@
-import { TemplateFeatureManifest, TemplateFilePolicy } from "./types.cjs";
+import { TemplateFeatureKind, TemplateFeatureManifest, TemplateFilePolicy } from "./types.cjs";
 
 //#region src/template.d.ts
 declare function loadTemplateManifest(templateDirectory: string): TemplateFeatureManifest;
 declare function getTemplateFilePolicy(manifest: TemplateFeatureManifest, relativePath: string): TemplateFilePolicy;
-declare function getEnabledFeatures(platform: "web" | "expo" | "both", testHarness: boolean): Set<string>;
+interface BackendModuleChoice {
+  id: string;
+  label: string;
+  experimental: boolean;
+}
+declare function getFeatureKind(options: {
+  id: string;
+  config: TemplateFeatureManifest["features"][string];
+}): TemplateFeatureKind;
+declare function listBackendModuleChoices(manifest: TemplateFeatureManifest): BackendModuleChoice[];
+declare function getEnabledFeatures(options: {
+  platform: "web" | "expo" | "both";
+  testHarness: boolean;
+  modules?: readonly string[];
+}): Set<string>;
 declare function getExcludedFeaturePaths(manifest: TemplateFeatureManifest, enabledFeatures: ReadonlySet<string>): string[];
 //#endregion
-export { getEnabledFeatures, getExcludedFeaturePaths, getTemplateFilePolicy, loadTemplateManifest };
+export { BackendModuleChoice, getEnabledFeatures, getExcludedFeaturePaths, getFeatureKind, getTemplateFilePolicy, listBackendModuleChoices, loadTemplateManifest };
 //# sourceMappingURL=template.d.cts.map

package/dist/src/types.d.cts

@@ -6,6 +6,8 @@ interface PromptValues {
   appDescription?: string;
   platform?: AppPlatform;
   testHarness?: boolean;
+  /** Optional Backend Module feature ids (billing, workflows, …). `--yes` defaults to none. */
+  modules?: string[];
 }
 interface CreateCommandOptions extends PromptValues {
   yes: boolean;
@@ -20,11 +22,16 @@ interface TemplateContext {
   packageScope: string;
   betterAuthSecret: string;
 }
+type TemplateFeatureKind = "platform" | "harness" | "module";
+interface TemplateFeatureConfig {
+  paths: readonly string[];
+  kind?: TemplateFeatureKind;
+  experimental?: boolean;
+  label?: string;
+}
 interface TemplateFeatureManifest {
   schemaVersion: number;
-  features: Record<string, {
-    paths: readonly string[];
-  }>;
+  features: Record<string, TemplateFeatureConfig>;
   requiredPaths: readonly string[];
   sync: {
     defaultPolicy: TemplateFilePolicy;
@@ -45,5 +52,5 @@ interface RenderedTemplateFile {
   relativePath: string;
 }
 //#endregion
-export { AppPlatform, CreateCommandOptions, PromptValues, RenderedTemplateFile, TemplateContext, TemplateFeatureManifest, TemplateFilePolicy };
+export { AppPlatform, CreateCommandOptions, PromptValues, RenderedTemplateFile, TemplateContext, TemplateFeatureConfig, TemplateFeatureKind, TemplateFeatureManifest, TemplateFilePolicy };
 //# sourceMappingURL=types.d.cts.map

package/package.json

@@ -1,7 +1,10 @@
 {
   "name": "create-m5kdev",
-  "version": "0.32.8",
+  "version": "0.34.0",
   "license": "GPL-3.0-only",
+  "engines": {
+    "node": ">=24"
+  },
   "repository": {
     "type": "git",
     "url": "https://github.com/michalkow/m5kdev.git"

package/templates/minimal-app/.cursor/rules/module-dto-guide.mdc

@@ -13,7 +13,7 @@ database schema first. Services, repositories, and tRPC files import the DTO
 ## The pattern
 
 ```ts
-import { createZodSchemas } from "@m5kdev/backend/modules/base/base.dto";
+import { createZodSchemas } from "@m5kdev/backend/base/base.dto";
 import {
   postCreateInputSchema,
   postUpdateInputSchema,

package/templates/minimal-app/.cursor/rules/module-grants-guide.mdc

@@ -22,10 +22,10 @@ apps/<app>/server/src/modules/<module>/<module>.grants.ts
 
 ## Grant Structure
 
-App modules use flat `ResourceGrant[]` arrays imported from `@m5kdev/backend/modules/base/base.grants`:
+App modules use flat `ResourceGrant[]` arrays imported from `@m5kdev/backend/base/base.grants`:
 
 ```typescript
-import type { ResourceGrant } from "@m5kdev/backend/modules/base/base.grants";
+import type { ResourceGrant } from "@m5kdev/backend/base/base.grants";
 ```
 
 Each `ResourceGrant` has four fields:
@@ -47,7 +47,7 @@ Each `ResourceGrant` has four fields:
 ## Example
 
 ```typescript
-import type { ResourceGrant } from "@m5kdev/backend/modules/base/base.grants";
+import type { ResourceGrant } from "@m5kdev/backend/base/base.grants";
 
 export const postsGrants: ResourceGrant[] = [
   {

package/templates/minimal-app/.cursor/rules/module-module-guide.mdc

@@ -15,13 +15,14 @@ apps/<app>/server/src/modules/<module>/<module>.module.ts
 
 ## Conventions
 
-- Extend `BaseModule<Deps, Tables, Repositories, Services, Routers>` from `@m5kdev/backend/modules/base/base.module`.
+- Extend `BaseModule<Deps, Tables, Repositories, Services, Routers>` from `@m5kdev/backend/base/base.module`.
 - Declare local type aliases for each generic slot (`*ModuleDeps`, `*ModuleTables`, `*ModuleRepositories`, `*ModuleServices`, `*ModuleRouters`).
 - Set `readonly id` to match the module directory name (e.g. `readonly id = "posts"`).
 - Declare `dbDependsOn` or `dependsOn` as a `readonly` tuple with `as const`. App modules that reference auth tables typically use `dbDependsOn: ["auth"]`.
 - Override only the hooks the module actually needs; omit the rest.
 - Keep hook bodies as pure wiring — no business logic.
 - Use `createBackendRouterMap(namespace, router)` from `@m5kdev/backend/app` in the `trpc()` hook.
+- Register the module with `createBackendApp(config, [modules])`. Do not use `backendApp.use`.
 - Export a singleton instance at the bottom of the file.
 
 ## Generic Parameters
@@ -60,7 +61,7 @@ import {
   type ModuleRepositoriesContext,
   type ModuleServicesContext,
   type ModuleTRPCContext,
-} from "@m5kdev/backend/modules/base/base.module";
+} from "@m5kdev/backend/base/base.module";
 import type * as postsTables from "./posts.db";
 import { postsGrants } from "./posts.grants";
 import { PostsRepository } from "./posts.repository";

package/templates/minimal-app/.cursor/rules/module-service-guide.mdc

@@ -298,7 +298,7 @@ readonly validateCode = this.procedure("validateCode")
 ## Example Skeleton
 
 ```typescript
-import { BasePermissionService } from "@m5kdev/backend/modules/base/base.service";
+import { BasePermissionService } from "@m5kdev/backend/base/base.service";
 import { postSchemas } from "./posts.dto";
 import type { PostsRepository } from "./posts.repository";
 

package/templates/minimal-app/.dockerignore.tpl

@@ -0,0 +1,31 @@
+# Dependencies
+node_modules
+**/node_modules
+.pnpm-store
+.pnp
+.pnp.js
+
+# Git
+.git
+
+# Local env files — never bake secrets into the image
+.env*
+
+# Testing
+coverage
+
+# Turbo
+.turbo
+
+# Build outputs
+build
+dist
+
+# Debug
+npm-debug.log*
+yarn-debug.log*
+yarn-error.log*
+
+# Misc
+.DS_Store
+*.pem

package/templates/minimal-app/.gitignore.tpl

@@ -7,3 +7,4 @@ coverage
 *.db-*
 apps/server/.emails
 apps/shared/.env
+**/.env.production

package/templates/minimal-app/AGENTS.md.tpl

@@ -8,20 +8,23 @@
 
 ## Repository Structure
 
-- `apps/shared` holds shared Zod schemas and constants.
+- `apps/shared` holds shared Zod schemas, constants, and the product Deploy home.
 - `apps/server` holds the backend composition root, modules, auth wiring, and database scripts.
 - `apps/webapp` holds the React app shell, routes, providers, and the `posts` feature.
+- `apps/landing` holds the public one-page site and its Fly adapter.
 - `apps/email` holds the email templates used by auth flows and local email delivery.
 
-## Backend Conventions
-
-- Keep repository, service, and transport layers separate inside each module.
-- Register modules in `apps/server/src/app.ts` via `createBackendApp(config, [modules])`.
-- Use `BaseModule` subclasses for app modules; the kernel wires repositories, services, and tRPC.
-- Keep tRPC files focused on input/output wiring and delegate logic to services.
-- Do not add service methods that merely call another service. Call the owning service directly unless the method adds a business rule, authorization, validation, orchestration, a transaction boundary, or meaningful domain translation.
-- Renaming a dependency method, repackaging arguments, constructing a prompt, or forwarding actor/context data alone does not justify a service wrapper.
-- Do not create Drizzle migrations by hand. Use the scaffolded config and your project migration workflow later if you need generated migrations.
+## Backend Conventions
+
+- Keep repository, service, and transport layers separate inside each module.
+- Register modules in `apps/server/src/app.ts` via `createBackendApp(config, [modules])`.
+- Import Kernel infrastructure (`BaseModule`, Grants, DTOs) from `@m5kdev/backend/base/*`. The `modules/base` path still re-exports.
+- Clay, Docx, Pdf, Social, and Video are Optional Backend Module packages (`@m5kdev/module-<name>`). They are not scaffolded; add them only when the product needs them.
+- Use `BaseModule` subclasses for app modules; the kernel wires repositories, services, and tRPC.
+- Keep tRPC files focused on input/output wiring and delegate logic to services.
+- Do not add service methods that merely call another service. Call the owning service directly unless the method adds a business rule, authorization, validation, orchestration, a transaction boundary, or meaningful domain translation.
+- Renaming a dependency method, repackaging arguments, constructing a prompt, or forwarding actor/context data alone does not justify a service wrapper.
+- Do not create Drizzle migrations by hand. Use the scaffolded config and your project migration workflow later if you need generated migrations.
 
 ## Frontend Conventions
 

package/templates/minimal-app/CLAUDE.md.tpl

@@ -1,131 +1,132 @@
-# CLAUDE.md
-
-Guidance for Claude Code when working in this repository.
-
-## About This App
-
-**{{APP_NAME}}** — {{APP_DESCRIPTION}}
-
-This is a pnpm + Turborepo monorepo built on the **m5kdev framework**:
-
-- `@m5kdev/backend` — backend kernel: Express, Better Auth, Drizzle (LibSQL), and tRPC. Apps compose it via `createBackendApp(config, [modules])`.
-- `@m5kdev/commons` — shared runtime utilities and contracts.
-- `@m5kdev/config` — configuration loading and validation.
-- `@m5kdev/email` — email rendering and local delivery used by auth flows.
-// m5k:webapp:start
-- `@m5kdev/frontend` — framework-level React providers (`AppConfigProvider`, `AppTrpcQueryProvider`) and hooks.
-- `@m5kdev/web-ui` — web UI components built on HeroUI v3.
-// m5k:webapp:end
-
-The framework owns the plumbing (auth, database wiring, tRPC composition, permissions); app code supplies modules and screens that follow the conventions below.
-
-## Workspace
-
-- `apps/shared` — shared Zod schemas, constants, and the `.env` file every app reads.
-- `apps/server` — backend composition root (`src/app.ts`), app modules (`src/modules/`), hand-registered table list (`src/schema.ts`), and Drizzle scripts.
-// m5k:webapp:start
-- `apps/webapp` — Vite + React 19 frontend: app shell, routes, providers, and feature modules.
-// m5k:webapp:end
-// m5k:expo:start
-- `apps/expo` — Expo (React Native) app sharing the same server and shared contracts.
-// m5k:expo:end
-- `apps/email` — email templates and the local delivery registry.
-// m5k:test-harness:start
-- `apps/e2e` — Playwright end-to-end tests; the server exposes a test-harness module for them.
-// m5k:test-harness:end
-
-## Commands
-
-```sh
-pnpm dev          # run all apps in dev (turbo)
-pnpm build        # build all apps
-pnpm lint         # biome check
-pnpm lint:fix     # biome check --write
-pnpm check-types  # tsc --noEmit everywhere
-```
-
-Database (Drizzle, run from the repo root):
-
-```sh
-pnpm --filter ./apps/server drizzle:generate  # generate migrations from *.db.ts changes
-pnpm --filter ./apps/server drizzle:migrate   # apply migrations
-pnpm --filter ./apps/server drizzle:seed      # seed the local database
-pnpm --filter ./apps/server drizzle:reset     # reset the local database
-pnpm --filter ./apps/server drizzle:studio    # inspect the database
-```
-
-First-time setup: `pnpm install`, then `drizzle:migrate` and `drizzle:seed`, then `pnpm dev`.
-// m5k:test-harness:start
-
-End-to-end tests: `pnpm --filter ./apps/e2e test:e2e` (Playwright).
-// m5k:test-harness:end
-
-The local database is a LibSQL file; local auth emails are written to `apps/server/.emails`. Demo login: `admin@{{APP_SLUG}}.local` / `password1234`.
-
-## Framework Architecture
-
-### Backend: kernel + modules
-
-The backend kernel orchestrates modules. Each app module is a `BaseModule` subclass registered in `apps/server/src/app.ts` via `createBackendApp(config, [modules])` — the kernel wires its repositories, services, and tRPC routers.
-
-A module lives in `apps/server/src/modules/<name>/` and follows a strict file anatomy where **the Drizzle table is the source of truth** and types flow one way:
-
-```
-<name>.db.ts          table definition (source of truth; register it in src/schema.ts)
-  └─ <name>.dto.ts    Zod schemas derived from the table — the module's API surface
-       ├─ <name>.repository.ts   data access, consumes the DTO object
-       ├─ <name>.service.ts      business logic, consumes the DTO object
-       └─ <name>.trpc.ts         thin router: attaches DTO schemas, delegates to the service
-<name>.grants.ts      permission grants for the module
-<name>.module.ts      composition unit wiring the above into one class
-```
-
-Clients infer all row/list types from `AppRouter` (`inferRouterOutputs`) — never hand-mirror server types anywhere. Never write Drizzle migrations by hand; change `*.db.ts`, register new tables in `src/schema.ts`, then run `drizzle:generate` + `drizzle:migrate`.
-
-Roles are defined in `apps/shared/src/modules/app/` and passed through both `createBackendApp` metadata and the frontend config provider; when adding roles, extend the module `*.grants.ts` files to match.
-// m5k:webapp:start
-
-### Frontend: fixed stack, hooks own the logic
-
-The webapp stack is fixed — React 19, HeroUI v3, Tailwind CSS v4, react-router v7, `nuqs` for URL state, TanStack Query over tRPC, i18next. Do not introduce alternatives (no fetch/axios, no form libraries, no other UI kits).
-
-- App shell shape: `NuqsAdapter` + `BrowserRouter` + `Providers`; global providers are composed in one place only.
-- Components stay display-focused; data fetching, mutations, and effect chains live in custom hooks under `modules/<feature>/hooks/`, composed into one screen-level hook (e.g. `usePostsRoute`).
-- All server data goes through `useTRPC()` + `queryOptions`/`mutationOptions`; invalidate with the matching `queryFilter()` after mutations.
-- Forms are uncontrolled HeroUI `Form` components with native HTML validation; read values from `FormData` on submit.
-- All user-facing copy goes through i18next; keys live in `apps/webapp/translations/`.
-// m5k:webapp:end
-
-### Reference implementation
-
-The **posts** feature is the canonical example of every convention. When adding a feature, mirror its structure:
-
-- `apps/shared/src/modules/posts/`
-- `apps/server/src/modules/posts/`
-// m5k:webapp:start
-- `apps/webapp/src/modules/posts/`
-// m5k:webapp:end
-
-## Detailed Style Guides
-
-The framework's detailed conventions live in `.cursor/rules/*.mdc`. Cursor applies them by glob automatically; Claude does not — so **before creating or editing a file that matches a pattern below, read the matching guide first**. They describe how the framework is meant to be used, with correct/incorrect examples.
-
-| Guide | Read before touching |
-| --- | --- |
-| `.cursor/rules/module-db-guide.mdc` | `apps/server/src/modules/**/*.db.ts` |
-| `.cursor/rules/module-dto-guide.mdc` | `apps/server/src/modules/**/*.dto.ts` |
-| `.cursor/rules/module-repository-guide.mdc` | `apps/server/src/modules/**/*.repository.ts` |
-| `.cursor/rules/module-service-guide.mdc` | `apps/server/src/modules/**/*.service.ts` |
-| `.cursor/rules/module-trpc-guide.mdc` | `apps/server/src/modules/**/*.trpc.ts` |
-| `.cursor/rules/module-grants-guide.mdc` | `apps/server/src/modules/**/*.grants.ts` |
-| `.cursor/rules/module-module-guide.mdc` | `apps/server/src/modules/**/*.module.ts` |
-| `.cursor/rules/module-schema-guide.mdc` | `apps/shared/src/modules/**/*.schema.ts` |
-// m5k:webapp:start
-| `.cursor/rules/frontend-component-guide.mdc` | webapp `*.tsx` components |
-| `.cursor/rules/frontend-hook-guide.mdc` | webapp `hooks/**` |
-| `.cursor/rules/frontend-data-guide.mdc` | webapp data fetching / tRPC usage |
-| `.cursor/rules/frontend-form-guide.mdc` | webapp forms |
-| `.cursor/rules/frontend-i18n-guide.mdc` | webapp user-facing copy |
-// m5k:webapp:end
-
-`AGENTS.md` (repo root and per-app) carries a compact summary of the same conventions for other agents; this file plus the guides above are the authoritative version for Claude.
+# CLAUDE.md
+
+Guidance for Claude Code when working in this repository.
+
+## About This App
+
+**{{APP_NAME}}** — {{APP_DESCRIPTION}}
+
+This is a pnpm + Turborepo monorepo built on the **m5kdev framework**:
+
+- `@m5kdev/backend` — backend kernel: Express, Better Auth, Drizzle (LibSQL), and tRPC. Apps compose it via `createBackendApp(config, [modules])`.
+- `@m5kdev/commons` — shared runtime utilities and contracts.
+- `@m5kdev/config` — configuration loading and validation.
+- `@m5kdev/email` — email rendering and local delivery used by auth flows.
+// m5k:webapp:start
+- `@m5kdev/frontend` — framework-level React providers (`AppConfigProvider`, `AppTrpcQueryProvider`) and hooks.
+- `@m5kdev/web-ui` — web UI components built on HeroUI v3.
+// m5k:webapp:end
+
+The framework owns the plumbing (auth, database wiring, tRPC composition, permissions); app code supplies modules and screens that follow the conventions below.
+
+## Workspace
+
+- `apps/shared` — shared Zod schemas, constants, and the `.env` file every app reads.
+- `apps/server` — backend composition root (`src/app.ts`), app modules (`src/modules/`), hand-registered table list (`src/schema.ts`), and Drizzle scripts.
+// m5k:webapp:start
+- `apps/webapp` — Vite + React 19 frontend: app shell, routes, providers, and feature modules.
+// m5k:webapp:end
+// m5k:expo:start
+- `apps/expo` — Expo (React Native) app sharing the same server and shared contracts.
+// m5k:expo:end
+- `apps/landing` — public one-page site (app name, pitch, CTA) with its own Dockerfile and `fly.toml`.
+- `apps/email` — email templates and the local delivery registry.
+// m5k:test-harness:start
+- `apps/e2e` — Playwright end-to-end tests; the server exposes a test-harness module for them.
+// m5k:test-harness:end
+
+## Commands
+
+```sh
+pnpm dev          # run all apps in dev (turbo)
+pnpm build        # build all apps
+pnpm lint         # biome check
+pnpm lint:fix     # biome check --write
+pnpm check-types  # tsc --noEmit everywhere
+```
+
+Database (Drizzle, run from the repo root):
+
+```sh
+pnpm --filter ./apps/server drizzle:generate  # generate migrations from *.db.ts changes
+pnpm --filter ./apps/server drizzle:migrate   # apply migrations
+pnpm --filter ./apps/server drizzle:seed      # seed the local database
+pnpm --filter ./apps/server drizzle:reset     # reset the local database
+pnpm --filter ./apps/server drizzle:studio    # inspect the database
+```
+
+First-time setup: `pnpm install`, then `drizzle:migrate` and `drizzle:seed`, then `pnpm dev`.
+// m5k:test-harness:start
+
+End-to-end tests: `pnpm --filter ./apps/e2e test:e2e` (Playwright).
+// m5k:test-harness:end
+
+The local database is a LibSQL file; local auth emails are written to `apps/server/.emails`. Demo login: `admin@{{APP_SLUG}}.local` / `password1234`.
+
+## Framework Architecture
+
+### Backend: kernel + modules
+
+The backend kernel orchestrates modules. Each app module is a `BaseModule` subclass registered in `apps/server/src/app.ts` via `createBackendApp(config, [modules])` — the kernel wires its repositories, services, and tRPC routers. Import Kernel infrastructure from `@m5kdev/backend/base/*`. Clay, Docx, Pdf, Social, and Video are Optional Backend Module packages (`@m5kdev/module-<name>`); they are not scaffolded.
+
+A module lives in `apps/server/src/modules/<name>/` and follows a strict file anatomy where **the Drizzle table is the source of truth** and types flow one way:
+
+```
+<name>.db.ts          table definition (source of truth; register it in src/schema.ts)
+  └─ <name>.dto.ts    Zod schemas derived from the table — the module's API surface
+       ├─ <name>.repository.ts   data access, consumes the DTO object
+       ├─ <name>.service.ts      business logic, consumes the DTO object
+       └─ <name>.trpc.ts         thin router: attaches DTO schemas, delegates to the service
+<name>.grants.ts      permission grants for the module
+<name>.module.ts      composition unit wiring the above into one class
+```
+
+Clients infer all row/list types from `AppRouter` (`inferRouterOutputs`) — never hand-mirror server types anywhere. Never write Drizzle migrations by hand; change `*.db.ts`, register new tables in `src/schema.ts`, then run `drizzle:generate` + `drizzle:migrate`.
+
+Roles are defined in `apps/shared/src/modules/app/` and passed through both `createBackendApp` metadata and the frontend config provider; when adding roles, extend the module `*.grants.ts` files to match.
+// m5k:webapp:start
+
+### Frontend: fixed stack, hooks own the logic
+
+The webapp stack is fixed — React 19, HeroUI v3, Tailwind CSS v4, react-router v7, `nuqs` for URL state, TanStack Query over tRPC, i18next. Do not introduce alternatives (no fetch/axios, no form libraries, no other UI kits).
+
+- App shell shape: `NuqsAdapter` + `BrowserRouter` + `Providers`; global providers are composed in one place only.
+- Components stay display-focused; data fetching, mutations, and effect chains live in custom hooks under `modules/<feature>/hooks/`, composed into one screen-level hook (e.g. `usePostsRoute`).
+- All server data goes through `useTRPC()` + `queryOptions`/`mutationOptions`; invalidate with the matching `queryFilter()` after mutations.
+- Forms are uncontrolled HeroUI `Form` components with native HTML validation; read values from `FormData` on submit.
+- All user-facing copy goes through i18next; keys live in `apps/webapp/translations/`.
+// m5k:webapp:end
+
+### Reference implementation
+
+The **posts** feature is the canonical example of every convention. When adding a feature, mirror its structure:
+
+- `apps/shared/src/modules/posts/`
+- `apps/server/src/modules/posts/`
+// m5k:webapp:start
+- `apps/webapp/src/modules/posts/`
+// m5k:webapp:end
+
+## Detailed Style Guides
+
+The framework's detailed conventions live in `.cursor/rules/*.mdc`. Cursor applies them by glob automatically; Claude does not — so **before creating or editing a file that matches a pattern below, read the matching guide first**. They describe how the framework is meant to be used, with correct/incorrect examples.
+
+| Guide | Read before touching |
+| --- | --- |
+| `.cursor/rules/module-db-guide.mdc` | `apps/server/src/modules/**/*.db.ts` |
+| `.cursor/rules/module-dto-guide.mdc` | `apps/server/src/modules/**/*.dto.ts` |
+| `.cursor/rules/module-repository-guide.mdc` | `apps/server/src/modules/**/*.repository.ts` |
+| `.cursor/rules/module-service-guide.mdc` | `apps/server/src/modules/**/*.service.ts` |
+| `.cursor/rules/module-trpc-guide.mdc` | `apps/server/src/modules/**/*.trpc.ts` |
+| `.cursor/rules/module-grants-guide.mdc` | `apps/server/src/modules/**/*.grants.ts` |
+| `.cursor/rules/module-module-guide.mdc` | `apps/server/src/modules/**/*.module.ts` |
+| `.cursor/rules/module-schema-guide.mdc` | `apps/shared/src/modules/**/*.schema.ts` |
+// m5k:webapp:start
+| `.cursor/rules/frontend-component-guide.mdc` | webapp `*.tsx` components |
+| `.cursor/rules/frontend-hook-guide.mdc` | webapp `hooks/**` |
+| `.cursor/rules/frontend-data-guide.mdc` | webapp data fetching / tRPC usage |
+| `.cursor/rules/frontend-form-guide.mdc` | webapp forms |
+| `.cursor/rules/frontend-i18n-guide.mdc` | webapp user-facing copy |
+// m5k:webapp:end
+
+`AGENTS.md` (repo root and per-app) carries a compact summary of the same conventions for other agents; this file plus the guides above are the authoritative version for Claude.