create-m5kdev 0.41.0 → 0.43.0

package/templates/minimal-app/apps/server/drizzle-postgresql/meta/_journal.json.tpl

@@ -0,0 +1,13 @@
+{
+  "version": "7",
+  "dialect": "postgresql",
+  "entries": [
+    {
+      "idx": 0,
+      "version": "7",
+      "when": 1793634297401,
+      "tag": "0000_glorious_warhawk",
+      "breakpoints": true
+    }
+  ]
+}

package/templates/minimal-app/apps/server/drizzle.config.ts.tpl

@@ -1,3 +1,3 @@
 import { defineDrizzleKitConfig } from "@m5kdev/backend/db";
 
-export default defineDrizzleKitConfig({ schema: "./src/schema.ts" });
+export default defineDrizzleKitConfig({ schema: "./src/drizzle.schema.ts" });

package/templates/minimal-app/apps/server/mastra.ts.tpl

@@ -0,0 +1,42 @@
+import type { PgVector } from "@mastra/pg";
+import {
+  conversationEmbeddingDimensions,
+  conversationEmbeddingIndex,
+  conversationEmbeddingMetric,
+  createConversationStorage,
+  createConversationVectorProvisioner,
+} from "./src/modules/conversation/conversation.persistence";
+
+async function initialize(): Promise<void> {
+  const storage = createConversationStorage(true);
+  let vector: PgVector | undefined;
+  try {
+    vector = createConversationVectorProvisioner();
+    const extension = await vector.pool.query<{ schema: string }>(
+      "SELECT n.nspname AS schema FROM pg_extension e JOIN pg_namespace n ON n.oid = e.extnamespace WHERE e.extname = 'vector'"
+    );
+    if (extension.rows[0]?.schema !== "public") {
+      throw new Error(
+        "Provision pgvector in the public schema before Mastra initialization (required for transaction pooling)"
+      );
+    }
+    await storage.init();
+    await vector.createIndex({
+      indexName: conversationEmbeddingIndex,
+      dimension: conversationEmbeddingDimensions,
+      metric: conversationEmbeddingMetric,
+      buildIndex: false,
+    });
+  } finally {
+    try {
+      await vector?.disconnect();
+    } finally {
+      await storage.close();
+    }
+  }
+}
+
+void initialize().catch((error) => {
+  console.error(error);
+  process.exitCode = 1;
+});

package/templates/minimal-app/apps/server/package.json.tpl

@@ -11,19 +11,23 @@
     "lint:fix": "biome check . --write",
     "check-types": "tsc --noEmit",
     "drizzle:generate": "drizzle-kit generate",
-    "drizzle:migrate": "drizzle-kit migrate",
-    "drizzle:studio": "drizzle-kit studio",
-    "drizzle:sync": "tsx --env-file=../shared/.env db.ts sync",
+    "drizzle:migrate": "tsx --env-file=../shared/.env db.ts migrate",
+    "drizzle:studio": "drizzle-kit studio",
+
+    "mastra:init": "tsx --env-file=../shared/.env mastra.ts",
+// m5k:ai:end
     "drizzle:seed": "tsx --env-file=../shared/.env db.ts seed",
     "drizzle:reset": "tsx --env-file=../shared/.env db.ts reset"
   },
   "dependencies": {
     "{{PACKAGE_SCOPE}}/email": "workspace:*",
     "{{PACKAGE_SCOPE}}/shared": "workspace:*",
-    "@libsql/client": "catalog:m5kdev",
     "@m5kdev/backend": "catalog:m5kdev",
     "@m5kdev/commons": "catalog:m5kdev",
     "@mastra/core": "catalog:m5kdev",
+    "@mastra/pg": "catalog:m5kdev",
+    "@mastra/memory": "catalog:m5kdev",
+    "pg": "catalog:m5kdev",
     "@openrouter/ai-sdk-provider": "catalog:m5kdev",
     "@opentelemetry/api": "catalog:m5kdev",
     "@trpc/server": "catalog:m5kdev",
@@ -43,6 +47,7 @@
     "@m5kdev/config": "catalog:m5kdev",
     "@types/express": "catalog:m5kdev",
     "@types/node": "catalog:m5kdev",
+    "@types/pg": "catalog:m5kdev",
     "@types/react": "catalog:m5kdev",
     "@types/react-dom": "catalog:m5kdev",
     "drizzle-kit": "catalog:m5kdev",

package/templates/minimal-app/apps/server/src/app.ts.tpl

@@ -1,6 +1,8 @@
+// biome-ignore-all assist/source/organizeImports: feature-gated module imports stay in marker blocks
 import { createBackendApp } from "@m5kdev/backend/app";
 import { shutdownTelemetry } from "@m5kdev/backend/lib/otel";
 // m5k:ai:start
+import { defineBackendModule } from "@m5kdev/backend/app";
 import { AIModule } from "@m5kdev/backend/modules/ai/ai.module";
 // m5k:ai:end
 import { createBetterAuth } from "@m5kdev/backend/modules/auth/auth.lib";
@@ -30,7 +32,13 @@ import {
 import { NOTIFICATION_KINDS } from "{{PACKAGE_SCOPE}}/shared/modules/notification/notification.constants";
 // m5k:notifications:end
 // m5k:ai:start
-import { mastra, openrouter } from "./modules/conversation/conversation.mastra";
+import {
+  conversationStorage,
+  mastra,
+  openrouter,
+  verifyConversationPersistence,
+} from "./modules/conversation/conversation.mastra";
+import { conversationVectorSchema } from "./modules/conversation/conversation.persistence";
 // m5k:ai:end
 // m5k:workflows:start
 import { DemoWorkflowModule } from "./modules/demo-workflow/demo-workflow.module";
@@ -43,27 +51,15 @@ import * as schema from "./schema";
 
 const appUrl = process.env.VITE_APP_URL ?? "http://localhost:5173";
 const serverUrl = process.env.VITE_SERVER_URL ?? "http://localhost:8080";
-const databaseUrl = process.env.DATABASE_URL ?? "file:./local.db";
-const syncUrl = process.env.TURSO_DATABASE_URL;
-const authToken = process.env.TURSO_AUTH_TOKEN;
+const databaseUrl = process.env.DATABASE_URL;
+if (!databaseUrl) throw new Error("DATABASE_URL must point to the runtime PgBouncer connection");
 // m5k:workflows:start
 const redisUrl = process.env.REDIS_URL ?? "redis://127.0.0.1:6379";
 // m5k:workflows:end
 const resendApiKey = process.env.RESEND_API_KEY;
 const enableWaitlist = process.env.VITE_ENABLE_WAITLIST === "true";
 
-const connection =
-  syncUrl && authToken
-    ? {
-        url: databaseUrl,
-        syncUrl,
-        authToken,
-        syncInterval: 60,
-        readYourWrites: true,
-      }
-    : {
-        url: databaseUrl,
-      };
+const connection = { connectionString: databaseUrl };
 
 export const builtBackendApp = createBackendApp(
   {
@@ -128,6 +124,15 @@ export const builtBackendApp = createBackendApp(
     // m5k:ai:start
     new AIModule({
       libs: { mastra, openrouter },
+      vectorStore: {
+        connectionString: process.env.VECTOR_DATABASE_URL || databaseUrl,
+        schemaName: conversationVectorSchema,
+      },
+    }),
+    defineBackendModule({
+      id: "conversation-persistence",
+      startup: verifyConversationPersistence,
+      shutdown: () => conversationStorage.close(),
     }),
     // m5k:ai:end
     // m5k:files:start

package/templates/minimal-app/apps/server/src/drizzle.schema.ts.tpl

@@ -0,0 +1,2 @@
+export { appDatabaseSchema } from "@m5kdev/backend/base/database.schema";
+export * from "./schema";

package/templates/minimal-app/apps/server/src/modules/conversation/conversation.mastra.ts.tpl

@@ -1,7 +1,53 @@
 import { Mastra } from "@mastra/core";
 import { Agent } from "@mastra/core/agent";
+import { Memory } from "@mastra/memory";
 import { createOpenRouter } from "@openrouter/ai-sdk-provider";
 import { STARTER_ASSISTANT_AGENT_ID } from "{{PACKAGE_SCOPE}}/shared/modules/conversation/conversation.constants";
+import {
+  conversationEmbeddingDimensions,
+  conversationEmbeddingIndex,
+  conversationEmbeddingMetric,
+  conversationStorageSchema,
+  conversationVectorSchema,
+  createConversationStorage,
+} from "./conversation.persistence";
+
+export const conversationStorage = createConversationStorage();
+
+export async function verifyConversationPersistence(): Promise<void> {
+  const tables = await conversationStorage.pool.query<{ ready: boolean }>(
+    "SELECT to_regclass(format('%I.%I', $1::text, 'mastra_threads')) IS NOT NULL AND to_regclass(format('%I.%I', $1::text, 'mastra_messages')) IS NOT NULL AS ready",
+    [conversationStorageSchema]
+  );
+  if (!tables.rows[0]?.ready)
+    throw new Error(
+      "Mastra storage is not ready; run mastra:init using the direct connection before startup"
+    );
+  const { PgVector } = await import("@mastra/pg");
+  const vector = new PgVector({
+    id: "starter-vector-readiness",
+    connectionString: process.env.VECTOR_DATABASE_URL || process.env.DATABASE_URL!,
+    schemaName: conversationVectorSchema,
+    disableInit: true,
+  });
+  try {
+    const extension = await vector.pool.query<{ ready: boolean }>(
+      "SELECT EXISTS(SELECT 1 FROM pg_extension e JOIN pg_namespace n ON n.oid = e.extnamespace WHERE e.extname = 'vector' AND n.nspname = 'public') AS ready"
+    );
+    if (!extension.rows[0]?.ready)
+      throw new Error(
+        "Provision pgvector in public before startup (transaction pooling requires this)"
+      );
+    const index = await vector.describeIndex({ indexName: conversationEmbeddingIndex });
+    if (
+      index.dimension !== conversationEmbeddingDimensions ||
+      index.metric !== conversationEmbeddingMetric
+    )
+      throw new Error("Starter vector configuration differs from the provisioned index");
+  } finally {
+    await vector.disconnect();
+  }
+}
 
 /** Cheap OpenRouter chat model for the starter Conversation example. */
 const STARTER_CHAT_MODEL = "google/gemini-2.5-flash";
@@ -14,12 +60,14 @@ const assistant = new Agent({
   id: STARTER_ASSISTANT_AGENT_ID,
   name: "Assistant",
   instructions: "You are a helpful assistant for this starter app. Keep answers concise.",
+  memory: new Memory({ storage: conversationStorage, options: { semanticRecall: false } }),
   model: openrouter.chat(STARTER_CHAT_MODEL, {
     usage: { include: true },
   }),
 });
 
 export const mastra = new Mastra({
+  storage: conversationStorage,
   agents: {
     [STARTER_ASSISTANT_AGENT_ID]: assistant,
   },

package/templates/minimal-app/apps/server/src/modules/conversation/conversation.persistence.ts.tpl

@@ -0,0 +1,47 @@
+import { PgVector, PostgresStore } from "@mastra/pg";
+
+export const conversationStorageSchema = process.env.MASTRA_DATABASE_SCHEMA ?? "mastra";
+export const conversationVectorSchema = process.env.VECTOR_DATABASE_SCHEMA ?? "vectors";
+export const conversationEmbeddingIndex = "mastra_embeddings";
+export const conversationEmbeddingModel = "openai/text-embedding-3-small";
+export const conversationEmbeddingDimensions = 1536;
+export const conversationEmbeddingMetric = "cosine" as const;
+
+export function createConversationStorage(initialize = false): PostgresStore {
+  const appSchema = process.env.DATABASE_SCHEMA ?? "app";
+  if (
+    conversationStorageSchema === appSchema ||
+    conversationVectorSchema === appSchema ||
+    conversationStorageSchema === conversationVectorSchema
+  ) {
+    throw new Error("App, Mastra storage, and vectors must use separately owned schemas");
+  }
+  const connectionString = initialize
+    ? process.env.MASTRA_DATABASE_DIRECT_URL || process.env.DATABASE_DIRECT_URL
+    : process.env.MASTRA_DATABASE_URL || process.env.DATABASE_URL;
+  if (!connectionString) {
+    throw new Error(
+      initialize
+        ? "DATABASE_DIRECT_URL is required for Mastra initialization"
+        : "DATABASE_URL is required for Mastra runtime storage"
+    );
+  }
+  return new PostgresStore({
+    id: "starter-mastra",
+    connectionString,
+    schemaName: conversationStorageSchema,
+    disableInit: !initialize,
+  });
+}
+
+export function createConversationVectorProvisioner(): PgVector {
+  const connectionString =
+    process.env.VECTOR_DATABASE_DIRECT_URL || process.env.DATABASE_DIRECT_URL;
+  if (!connectionString)
+    throw new Error("DATABASE_DIRECT_URL is required for vector initialization");
+  return new PgVector({
+    id: "starter-vector-init",
+    connectionString,
+    schemaName: conversationVectorSchema,
+  });
+}

package/templates/minimal-app/apps/server/src/modules/posts/posts.db.ts.tpl

@@ -1,8 +1,9 @@
+import { appDatabaseSchema } from "@m5kdev/backend/base/database.schema";
 import { members, organizations, users } from "@m5kdev/backend/modules/auth/auth.db";
-import { integer, sqliteTable as table, text } from "drizzle-orm/sqlite-core";
+import { text, timestamp } from "drizzle-orm/pg-core";
 import { v4 as uuidv4 } from "uuid";
 
-export const posts = table("posts", {
+export const posts = appDatabaseSchema.table("posts", {
   id: text("id").primaryKey().$default(uuidv4),
   authorUserId: text("author_user_id").references(() => users.id, {
     onDelete: "set null",
@@ -19,10 +20,10 @@ export const posts = table("posts", {
   excerpt: text("excerpt"),
   content: text("content").notNull(),
   status: text("status").$type<"draft" | "published">().notNull().default("draft"),
-  publishedAt: integer("published_at", { mode: "timestamp" }),
-  createdAt: integer("created_at", { mode: "timestamp" })
+  publishedAt: timestamp("published_at", { withTimezone: true, mode: "date" }),
+  createdAt: timestamp("created_at", { withTimezone: true, mode: "date" })
     .notNull()
     .$default(() => new Date()),
-  updatedAt: integer("updated_at", { mode: "timestamp" }),
-  deletedAt: integer("deleted_at", { mode: "timestamp" }),
+  updatedAt: timestamp("updated_at", { withTimezone: true, mode: "date" }),
+  deletedAt: timestamp("deleted_at", { withTimezone: true, mode: "date" }),
 });

package/templates/minimal-app/apps/server/src/modules/posts/posts.repository.ts.tpl

@@ -1,7 +1,7 @@
 import { BaseTableRepository } from "@m5kdev/backend/modules/base/base.repository";
 
 import { and, eq, isNull, ne } from "drizzle-orm";
-import type { LibSQLDatabase } from "drizzle-orm/libsql";
+import type { NodePgDatabase } from "drizzle-orm/node-postgres";
 import { err, ok } from "neverthrow";
 import { z } from "zod";
 import { posts } from "./posts.db";
@@ -9,7 +9,7 @@ import { postSchemas } from "./posts.dto";
 
 const schema = { posts };
 type Schema = typeof schema;
-type Orm = LibSQLDatabase<Schema>;
+type Orm = NodePgDatabase<Schema>;
 
 export class PostsRepository extends BaseTableRepository<
   Orm,

package/templates/minimal-app/apps/shared/.env.example.tpl

@@ -8,9 +8,12 @@ VITE_SERVER_URL=http://localhost:8080
 VITE_ENABLE_WAITLIST=false
 
 # Database
-DATABASE_URL=file:./local.db
-TURSO_DATABASE_URL=
-TURSO_AUTH_TOKEN=
+DATABASE_URL=postgresql://m5kdev:m5kdev@127.0.0.1:6432/m5kdev
+DATABASE_DIRECT_URL=postgresql://m5kdev:m5kdev@127.0.0.1:5432/m5kdev
+DATABASE_SCHEMA=app
+DATABASE_DISPOSABLE=false
+MASTRA_DATABASE_SCHEMA=mastra
+VECTOR_DATABASE_SCHEMA=vectors
 
 # Redis (BullMQ / workflow workers)
 REDIS_URL=redis://127.0.0.1:6379

package/templates/minimal-app/apps/shared/.env.production.example.tpl

@@ -2,8 +2,13 @@
 # image (.dockerignore excludes .env*). app:deploy forwards every key as a Fly
 # build secret; app:secrets imports the same file as runtime secrets.
 
-# Database (Fly volume at /app/data)
-DATABASE_URL=file:/app/data/local.db
+# PostgreSQL: runtime transaction pool and direct migration/admin connection
+DATABASE_URL=
+DATABASE_DIRECT_URL=
+DATABASE_SCHEMA=app
+DATABASE_DISPOSABLE=false
+MASTRA_DATABASE_SCHEMA=mastra
+VECTOR_DATABASE_SCHEMA=vectors
 
 # Redis — set as a Fly runtime secret (do not bake into the image)
 REDIS_URL=

package/templates/minimal-app/apps/shared/.env.tpl

@@ -8,9 +8,12 @@ VITE_SERVER_URL=http://localhost:8080
 VITE_ENABLE_WAITLIST=false
 
 # Database
-DATABASE_URL=file:./local.db
-TURSO_DATABASE_URL=
-TURSO_AUTH_TOKEN=
+DATABASE_URL=postgresql://m5kdev:m5kdev@127.0.0.1:6432/m5kdev
+DATABASE_DIRECT_URL=postgresql://m5kdev:m5kdev@127.0.0.1:5432/m5kdev
+DATABASE_SCHEMA=app
+DATABASE_DISPOSABLE=false
+MASTRA_DATABASE_SCHEMA=mastra
+VECTOR_DATABASE_SCHEMA=vectors
 
 # m5k:ai:start
 # Optional OpenRouter (AI Conversation). Required to get an assistant reply.

package/templates/minimal-app/apps/shared/Dockerfile.pgbouncer

@@ -0,0 +1,6 @@
+FROM debian:bookworm-slim
+RUN apt-get update && apt-get install -y --no-install-recommends pgbouncer && rm -rf /var/lib/apt/lists/*
+COPY pgbouncer.ini /etc/pgbouncer/pgbouncer.ini
+COPY pgbouncer.users /etc/pgbouncer/users.txt
+USER nobody
+CMD ["pgbouncer", "/etc/pgbouncer/pgbouncer.ini"]

package/templates/minimal-app/apps/shared/compose.yaml.tpl

@@ -0,0 +1,27 @@
+services:
+  postgres:
+    image: pgvector/pgvector:pg17
+    environment:
+      POSTGRES_DB: m5kdev
+      POSTGRES_USER: m5kdev
+      POSTGRES_PASSWORD: m5kdev
+    ports:
+      - "127.0.0.1:5432:5432"
+    volumes:
+      - postgres_data:/var/lib/postgresql/data
+    healthcheck:
+      test: ["CMD-SHELL", "pg_isready -U m5kdev -d m5kdev"]
+      interval: 2s
+      timeout: 2s
+      retries: 30
+  pgbouncer:
+    build:
+      context: .
+      dockerfile: Dockerfile.pgbouncer
+    depends_on:
+      postgres:
+        condition: service_healthy
+    ports:
+      - "127.0.0.1:6432:6432"
+volumes:
+  postgres_data:

package/templates/minimal-app/apps/shared/fly.toml.tpl

@@ -6,10 +6,6 @@ primary_region = "iad"
 [env]
   PORT = "8080"
 
-[[mounts]]
-  source = "libsql_data"
-  destination = "/app/data"
-
 [http_service]
   internal_port = 8080
   force_https = true

package/templates/minimal-app/apps/shared/package.json.tpl

@@ -1,27 +1,27 @@
-{
-  "name": "{{PACKAGE_SCOPE}}/shared",
-  "version": "0.0.0",
-  "private": true,
-  "scripts": {
-    "build": "tsc --noEmit",
-    "lint": "biome check .",
-    "lint:fix": "biome check . --write",
-    "check-types": "tsc --noEmit"
-  },
-  "dependencies": {
-    "@m5kdev/commons": "catalog:m5kdev",
-    "zod": "catalog:m5kdev"
-  },
-  "devDependencies": {
-    "@m5kdev/config": "catalog:m5kdev",
-    "tslib": "catalog:m5kdev",
-    "typescript": "catalog:m5kdev"
-  },
-  "exports": {
-    "./modules/app/*": "./src/modules/app/*.ts",
-    "./modules/conversation/*": "./src/modules/conversation/*.ts",
-    "./modules/demo-workflow/*": "./src/modules/demo-workflow/*.ts",
-    "./modules/notification/*": "./src/modules/notification/*.ts",
-    "./modules/posts/*": "./src/modules/posts/*.ts"
-  }
-}
+{
+  "name": "{{PACKAGE_SCOPE}}/shared",
+  "version": "0.0.0",
+  "private": true,
+  "scripts": {
+    "build": "tsc --noEmit",
+    "lint": "biome check .",
+    "lint:fix": "biome check . --write",
+    "check-types": "tsc --noEmit"
+  },
+  "dependencies": {
+    "@m5kdev/commons": "catalog:m5kdev",
+    "zod": "catalog:m5kdev"
+  },
+  "devDependencies": {
+    "@m5kdev/config": "catalog:m5kdev",
+    "tslib": "catalog:m5kdev",
+    "typescript": "catalog:m5kdev"
+  },
+  "exports": {
+    "./modules/app/*": "./src/modules/app/*.ts",
+    "./modules/conversation/*": "./src/modules/conversation/*.ts",
+    "./modules/demo-workflow/*": "./src/modules/demo-workflow/*.ts",
+    "./modules/notification/*": "./src/modules/notification/*.ts",
+    "./modules/posts/*": "./src/modules/posts/*.ts"
+  }
+}

package/templates/minimal-app/apps/shared/pgbouncer.ini

@@ -0,0 +1,13 @@
+[databases]
+m5kdev = host=postgres port=5432 dbname=m5kdev
+
+[pgbouncer]
+listen_addr = 0.0.0.0
+listen_port = 6432
+unix_socket_dir = /tmp
+auth_type = plain
+auth_file = /etc/pgbouncer/users.txt
+pool_mode = transaction
+default_pool_size = 10
+max_client_conn = 100
+pidfile = /tmp/pgbouncer.pid

package/templates/minimal-app/apps/shared/pgbouncer.users

@@ -0,0 +1 @@
+"m5kdev" "m5kdev"

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

@@ -1,24 +1,24 @@
-# AGENTS.md
-
-## Frontend Stack
-
-- React 19 + TypeScript
-- React Router v7
-- HeroUI v3
-- Tailwind CSS v4
-- `nuqs` for URL state
-- TanStack Query + tRPC
-- i18next for all user-facing copy
-
-## Conventions
-
-- Keep providers centralized in `src/Providers.tsx`.
-- Keep routing in `src/Router.tsx`.
-- Keep feature code grouped under `src/modules/<feature>/` with `components/` and `hooks/` subfolders.
-- Prefer HeroUI primitives and existing framework utilities before adding custom abstractions.
-- Components stay display-focused: queries, mutations, URL state, and effects live in custom hooks (`hooks/use<Feature>Route.ts` composed from smaller hooks); ephemeral UI state (modal open, selected row) may stay in the component. Reusable tRPC actions (delete, publish) get their own hook.
-- Derive values during render instead of syncing state with `useEffect`.
-- Forms are uncontrolled: HeroUI `Form` + `TextField` with native HTML validation and `FieldError`, values read from `FormData` on submit. No form libraries. Extra checks that HTML validation cannot express happen in the submit handler.
-- Fetch through `useTRPC()` + `queryOptions`/`mutationOptions` only; invalidate with `queryFilter()` after mutations.
-- Use `useTranslation` for local app copy and rely on the bundled `web-ui` translations for auth routes.
-- The `posts` module is the reference implementation; detailed guides live in `.cursor/rules/frontend-*.mdc`.
+# AGENTS.md
+
+## Frontend Stack
+
+- React 19 + TypeScript
+- React Router v7
+- HeroUI v3
+- Tailwind CSS v4
+- `nuqs` for URL state
+- TanStack Query + tRPC
+- i18next for all user-facing copy
+
+## Conventions
+
+- Keep providers centralized in `src/Providers.tsx`.
+- Keep routing in `src/Router.tsx`.
+- Keep feature code grouped under `src/modules/<feature>/` with `components/` and `hooks/` subfolders.
+- Prefer HeroUI primitives and existing framework utilities before adding custom abstractions.
+- Components stay display-focused: queries, mutations, URL state, and effects live in custom hooks (`hooks/use<Feature>Route.ts` composed from smaller hooks); ephemeral UI state (modal open, selected row) may stay in the component. Reusable tRPC actions (delete, publish) get their own hook.
+- Derive values during render instead of syncing state with `useEffect`.
+- Forms are uncontrolled: HeroUI `Form` + `TextField` with native HTML validation and `FieldError`, values read from `FormData` on submit. No form libraries. Extra checks that HTML validation cannot express happen in the submit handler.
+- Fetch through `useTRPC()` + `queryOptions`/`mutationOptions` only; invalidate with `queryFilter()` after mutations.
+- Use `useTranslation` for local app copy and rely on the bundled `web-ui` translations for auth routes.
+- The `posts` module is the reference implementation; detailed guides live in `.cursor/rules/frontend-*.mdc`.

package/templates/minimal-app/apps/webapp/index.html.tpl

@@ -1,22 +1,22 @@
-<!doctype html>
-<html lang="en">
-  <head>
-    <meta charset="UTF-8" />
-    <meta
-      name="viewport"
-      content="width=device-width, initial-scale=1.0"
-    />
-    <meta
-      name="description"
-      content="The m5kdev starter application."
-    />
-    <title>{{APP_NAME}}</title>
-  </head>
-  <body>
-    <div id="root"></div>
-    <script
-      type="module"
-      src="/src/main.tsx"
-    ></script>
-  </body>
-</html>
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="UTF-8" />
+    <meta
+      name="viewport"
+      content="width=device-width, initial-scale=1.0"
+    />
+    <meta
+      name="description"
+      content="The m5kdev starter application."
+    />
+    <title>{{APP_NAME}}</title>
+  </head>
+  <body>
+    <div id="root"></div>
+    <script
+      type="module"
+      src="/src/main.tsx"
+    ></script>
+  </body>
+</html>