create-momentum-app 0.5.2 → 0.5.3

package/index.cjs

@@ -34,7 +34,10 @@ var import_fs_extra = __toESM(require("fs-extra"));
 var import_picocolors = __toESM(require("picocolors"));
 var TEMPLATE_EXT = ".tmpl";
 function getTemplatesDir() {
-  return import_node_path.default.resolve(__dirname, "templates");
+  const distPath = import_node_path.default.resolve(__dirname, "templates");
+  if (import_fs_extra.default.existsSync(distPath))
+    return distPath;
+  return import_node_path.default.resolve(__dirname, "..", "templates");
 }
 function interpolate(content, vars) {
   let result = content;
@@ -163,7 +166,8 @@ Directory "${projectName}" already exists.`));
     process.exit(1);
   }
   const templatesDir = getTemplatesDir();
-  const pkgJson = import_fs_extra.default.readJsonSync(import_node_path.default.resolve(__dirname, "package.json"));
+  const pkgJsonPath = import_fs_extra.default.existsSync(import_node_path.default.resolve(__dirname, "package.json")) ? import_node_path.default.resolve(__dirname, "package.json") : import_node_path.default.resolve(__dirname, "..", "package.json");
+  const pkgJson = import_fs_extra.default.readJsonSync(pkgJsonPath);
   const packageVersion = pkgJson.version ?? "0.0.1";
   const vars = {
     projectName,
@@ -171,9 +175,9 @@ Directory "${projectName}" already exists.`));
     databaseType: database,
     dbImport: database === "postgres" ? "import { postgresAdapter } from '@momentumcms/db-drizzle';" : "import { sqliteAdapter } from '@momentumcms/db-drizzle';",
     dbAdapter: database === "postgres" ? `postgresAdapter({
-		connectionString: process.env['DATABASE_URL'] ?? 'postgresql://postgres:postgres@localhost:5432/momentum',
+		connectionString: process.env['DATABASE_URL'] ?? 'postgresql://postgres:postgres@localhost:5432/${projectName}',
 	})` : `sqliteAdapter({
-		filename: process.env['DATABASE_PATH'] ?? './data/momentum.db',
+		filename: process.env['DATABASE_PATH'] ?? './data/${projectName}.db',
 	})`,
     dbPoolSetup: database === "postgres" ? `import type { PostgresAdapterWithRaw } from '@momentumcms/db-drizzle';
 
@@ -182,7 +186,7 @@ const pool = (dbAdapter as PostgresAdapterWithRaw).getPool();` : "",
     authDbConfig: database === "postgres" ? "db: { type: 'postgres', pool }," : "db: { type: 'sqlite', database: dbAdapter.getRawDatabase() },",
     dbPackage: database === "postgres" ? '"pg": "^8.18.0"' : '"better-sqlite3": "^12.6.0"',
     dbDevPackage: database === "postgres" ? "" : '"@types/better-sqlite3": "^7.6.13",',
-    envDbVar: database === "postgres" ? "DATABASE_URL=postgresql://postgres:postgres@localhost:5432/momentum" : "DATABASE_PATH=./data/momentum.db",
+    envDbVar: database === "postgres" ? `DATABASE_URL=postgresql://postgres:postgres@localhost:5432/${projectName}` : `DATABASE_PATH=./data/${projectName}.db`,
     defaultPort: "4200",
     externalDependencies: [
       database === "postgres" ? '"pg", "pg-native"' : '"better-sqlite3"',
@@ -204,7 +208,7 @@ This project uses PostgreSQL via Docker. The database is configured in \`docker-
 **Connection Details:**
 - Host: \`localhost\`
 - Port: \`5432\`
-- Database: \`momentum\`
+- Database: \`${projectName}\`
 - Username: \`postgres\`
 - Password: \`postgres\`
 
@@ -226,7 +230,7 @@ docker compose logs -f postgres
 
 You can also use an external PostgreSQL instance by updating \`DATABASE_URL\` in \`.env\`.` : `### SQLite
 
-This project uses SQLite with the database file at \`./data/momentum.db\`.  
+This project uses SQLite with the database file at \`./data/${projectName}.db\`.  
 The database is automatically created on first run - no setup required.`
   };
   console.log();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-momentum-app",
-  "version": "0.5.2",
+  "version": "0.5.3",
   "description": "Create a new Momentum CMS application",
   "license": "MIT",
   "author": "Momentum CMS Contributors",

package/templates/analog/src/momentum.config.ts.tmpl

@@ -11,13 +11,13 @@ const dbAdapter = {{dbAdapter}};
 
 {{dbPoolSetup}}
 
-const authBaseURL =
-	process.env['BETTER_AUTH_URL'] || `http://localhost:${process.env['PORT'] || {{defaultPort}}}`;
+const PORT = Number(process.env['PORT']) || {{defaultPort}};
+const BASE_URL = process.env['BETTER_AUTH_URL'] || `http://localhost:${PORT}`;
 
 export const authPlugin = momentumAuth({
 	{{authDbConfig}}
-	baseURL: authBaseURL,
-	trustedOrigins: [authBaseURL],
+	baseURL: BASE_URL,
+	trustedOrigins: [BASE_URL],
 	email: {
 		appName: '{{projectName}}',
 	},
@@ -28,7 +28,7 @@ export const authPlugin = momentumAuth({
  */
 export const seo = seoPlugin({
 	collections: ['posts'],
-	siteUrl: `http://localhost:${process.env['PORT'] || {{defaultPort}}}`,
+	siteUrl: BASE_URL,
 	analysis: true,
 	sitemap: true,
 	robots: true,
@@ -51,7 +51,7 @@ const config = defineMomentumConfig({
 		},
 	},
 	server: {
-		port: Number(process.env['PORT']) || {{defaultPort}},
+		port: PORT,
 		cors: {
 			origin: process.env['CORS_ORIGIN'] || '*',
 			methods: ['GET', 'POST', 'PATCH', 'PUT', 'DELETE', 'OPTIONS'],

package/templates/angular/src/momentum.config.ts.tmpl

@@ -13,16 +13,16 @@ const dbAdapter = {{dbAdapter}};
 
 {{dbPoolSetup}}
 
-const authBaseURL =
-	process.env['BETTER_AUTH_URL'] || `http://localhost:${process.env['PORT'] || {{defaultPort}}}`;
+const PORT = Number(process.env['PORT']) || {{defaultPort}};
+const BASE_URL = process.env['BETTER_AUTH_URL'] || `http://localhost:${PORT}`;
 
 /**
  * Auth plugin - manages Better Auth integration, user tables, and middleware.
  */
 export const authPlugin = momentumAuth({
 	{{authDbConfig}}
-	baseURL: authBaseURL,
-	trustedOrigins: [authBaseURL],
+	baseURL: BASE_URL,
+	trustedOrigins: [BASE_URL],
 });
 
 /**
@@ -30,7 +30,7 @@ export const authPlugin = momentumAuth({
  */
 export const seo = seoPlugin({
 	collections: ['posts'],
-	siteUrl: `http://localhost:${process.env['PORT'] || {{defaultPort}}}`,
+	siteUrl: BASE_URL,
 	analysis: true,
 	sitemap: true,
 	robots: true,
@@ -56,7 +56,7 @@ const config = defineMomentumConfig({
 		},
 	},
 	server: {
-		port: Number(process.env['PORT']) || {{defaultPort}},
+		port: PORT,
 		cors: {
 			origin: '*',
 			methods: ['GET', 'POST', 'PATCH', 'PUT', 'DELETE', 'OPTIONS'],

package/templates/nestjs/src/momentum.config.ts.tmpl

@@ -13,16 +13,16 @@ const dbAdapter = {{dbAdapter}};
 
 {{dbPoolSetup}}
 
-const authBaseURL =
-	process.env['BETTER_AUTH_URL'] || `http://localhost:${process.env['PORT'] || {{defaultPort}}}`;
+const PORT = Number(process.env['PORT']) || {{defaultPort}};
+const BASE_URL = process.env['BETTER_AUTH_URL'] || `http://localhost:${PORT}`;
 
 /**
  * Auth plugin - manages Better Auth integration, user tables, and middleware.
  */
 export const authPlugin = momentumAuth({
 	{{authDbConfig}}
-	baseURL: authBaseURL,
-	trustedOrigins: [authBaseURL],
+	baseURL: BASE_URL,
+	trustedOrigins: [BASE_URL],
 });
 
 /**
@@ -30,7 +30,7 @@ export const authPlugin = momentumAuth({
  */
 export const seo = seoPlugin({
 	collections: ['posts'],
-	siteUrl: `http://localhost:${process.env['PORT'] || {{defaultPort}}}`,
+	siteUrl: BASE_URL,
 	analysis: true,
 	sitemap: true,
 	robots: true,
@@ -56,7 +56,7 @@ const config = defineMomentumConfig({
 		},
 	},
 	server: {
-		port: Number(process.env['PORT']) || {{defaultPort}},
+		port: PORT,
 		cors: {
 			origin: '*',
 			methods: ['GET', 'POST', 'PATCH', 'PUT', 'DELETE', 'OPTIONS'],

package/templates/shared/.claude/agents.md

@@ -17,11 +17,16 @@ Momentum CMS is a headless CMS built with Angular. You define collections in Typ
 
 ## Available Skills
 
-| Skill                | Usage                      | Description                                                      |
-| -------------------- | -------------------------- | ---------------------------------------------------------------- |
-| `/collection <name>` | `/collection products`     | Generate a new collection with fields, access control, and hooks |
-| `/momentum-api <op>` | `/momentum-api crud posts` | Guide for using `injectMomentumAPI()` in Angular components      |
-| `/add-plugin <name>` | `/add-plugin analytics`    | Add and configure a Momentum CMS plugin                          |
+| Skill                  | Usage                          | Description                                                      |
+| ---------------------- | ------------------------------ | ---------------------------------------------------------------- |
+| `/collection <name>`   | `/collection products`         | Generate a new collection with fields, access control, and hooks |
+| `/momentum-api <op>`   | `/momentum-api crud posts`     | Guide for using `injectMomentumAPI()` in Angular components      |
+| `/add-plugin <name>`   | `/add-plugin analytics`        | Add and configure a Momentum CMS plugin                          |
+| `/admin-config <what>` | `/admin-config field-renderer` | Wire admin routes, plugin imports, and custom field renderers    |
+| `/api-route <name>`    | `/api-route health`            | Generate API route handlers for Express or Analog.js             |
+| `/component <name>`    | `/component post-card`         | Generate an Angular component with signals and OnPush            |
+| `/e2e-test <feature>`  | `/e2e-test posts`              | Write Playwright E2E tests (dashboard-first, no blind tests)     |
+| `/migrations <op>`     | `/migrations generate`         | Run migrations, generate schemas, and manage code generation     |
 
 ## Common Workflows
 

package/templates/shared/.claude/skills/add-plugin/SKILL.md

@@ -10,7 +10,7 @@ Add and configure a plugin in this Momentum CMS project.
 
 ## Arguments
 
-- `$ARGUMENTS` - Plugin name: "analytics", "otel", "event-bus", or an npm package name
+- `$ARGUMENTS` - Plugin name: "seo", "analytics", "otel", "event-bus", or an npm package name
 
 ## Steps
 
@@ -23,6 +23,43 @@ Add and configure a plugin in this Momentum CMS project.
 
 ## Official Plugins
 
+### SEO (`@momentumcms/plugins-seo`)
+
+Adds SEO fields to collections, sitemap.xml, robots.txt, meta tag API, and an admin dashboard. **Included by default** in scaffolded projects.
+
+```bash
+npm install @momentumcms/plugins-seo
+```
+
+```typescript
+// In src/momentum.config.ts
+import { seoPlugin } from '@momentumcms/plugins-seo';
+
+const seo = seoPlugin({
+	collections: ['posts'], // Collection slugs to inject SEO fields into (or '*' for all)
+	siteUrl: BASE_URL, // Base URL for sitemaps and canonical URLs
+	analysis: true, // Enable SEO scoring analysis on save
+	sitemap: true, // Enable /sitemap.xml endpoint
+	robots: true, // Enable /robots.txt endpoint
+	metaApi: true, // Enable /api/seo/meta/:collection/:id endpoint
+	adminDashboard: true, // Enable SEO admin pages (dashboard, sitemap, robots)
+});
+
+const config = defineMomentumConfig({
+	// ...existing config
+	plugins: [authPlugin, seo],
+});
+```
+
+**What it adds:**
+
+- SEO fields (title, description, keywords, Open Graph, Twitter cards) injected into specified collections via a tabbed "SEO" section
+- SEO analysis scoring (title length, description, keyword density) with per-document scores
+- Sitemap.xml generation from published documents
+- Robots.txt generation with configurable rules
+- Meta tag API endpoint for headless frontends
+- Admin dashboard with SEO overview, sitemap settings, and robots.txt editor
+
 ### Analytics (`@momentumcms/plugins-analytics`)
 
 Adds event tracking, content performance dashboard, and block-level analytics.

package/templates/shared/.claude/skills/admin-config/SKILL.md

@@ -0,0 +1,76 @@
+---
+name: admin-config
+description: Wire admin routes, configure browser-safe plugin imports, and create custom field renderers. Use when setting up momentumAdminRoutes, browserImports, or FieldRendererRegistry.
+argument-hint: <routes|field-renderer|plugin-imports>
+---
+
+# Admin Config & Field Renderers
+
+Reference for wiring admin routes, plugin browser imports, and custom field renderers.
+
+## Arguments
+
+- `$ARGUMENTS` - What to configure: `routes`, `field-renderer`, or `plugin-imports`
+
+## Admin Config Generator
+
+The admin config generator reads `momentum.config.ts` (server-side, Node) and outputs a browser-safe TypeScript file with proper imports. This eliminates manual wiring of collections, auth collections, and plugin routes in app routing.
+
+### Usage in app routes
+
+```typescript
+import { momentumAdminRoutes } from '@momentumcms/admin';
+import { adminConfig } from '../generated/momentum.config';
+
+export const appRoutes: Route[] = [
+	...momentumAdminRoutes(adminConfig),
+	// app-specific routes...
+];
+```
+
+### Regenerate after config changes
+
+```bash
+npm run generate    # Regenerates types + admin config
+```
+
+### Plugin browserImports
+
+Plugins declare browser-safe imports via `browserImports` on `MomentumPlugin`:
+
+```typescript
+browserImports: {
+	collections: { path: '@momentumcms/auth/collections', exportName: 'BASE_AUTH_COLLECTIONS' },
+	adminRoutes: { path: '@momentumcms/plugins-seo/admin-routes', exportName: 'seoAdminRoutes' },
+	modifyCollections: { path: '@momentumcms/plugins-analytics/block-fields', exportName: 'injectBlockAnalyticsFields' },
+}
+```
+
+## Custom Field Renderers
+
+Field renderers are lazily loaded via `FieldRendererRegistry`. Built-in renderers are registered with `provideMomentumFieldRenderers()`.
+
+### App setup (required)
+
+```typescript
+import { provideMomentumFieldRenderers } from '@momentumcms/admin';
+
+export const appConfig: ApplicationConfig = {
+	providers: [provideMomentumFieldRenderers()],
+};
+```
+
+### Adding a custom field type
+
+```typescript
+import { provideFieldRenderer } from '@momentumcms/admin';
+
+export const appConfig: ApplicationConfig = {
+	providers: [
+		provideMomentumFieldRenderers(),
+		provideFieldRenderer('color', () =>
+			import('./renderers/color-field.component').then((m) => m.ColorFieldRenderer),
+		),
+	],
+};
+```

package/templates/shared/.claude/skills/api-route/SKILL.md

@@ -0,0 +1,98 @@
+---
+name: api-route
+description: Generate API route handlers for Express, NestJS, or Analog.js
+argument-hint: <route-name>
+---
+
+# Generate API Route
+
+Create API route handlers for your Momentum CMS project.
+
+## Arguments
+
+- `$ARGUMENTS` - Route name (e.g., "health", "custom-endpoint")
+
+## For Express / NestJS (Angular SSR)
+
+Both the Express and NestJS server adapters expose an Express instance. Custom routes use the same Express Router pattern.
+
+Create handler in `src/api/<route-name>.ts`:
+
+```typescript
+import { Router, Request, Response } from 'express';
+import type { CollectionConfig } from '@momentumcms/core';
+
+export function create<PascalName>Routes(collections: CollectionConfig[]): Router {
+  const router = Router();
+
+  router.get('/<route-name>', async (req: Request, res: Response) => {
+    try {
+      // Implementation
+      res.json({ success: true });
+    } catch (error) {
+      res.status(500).json({ error: 'Internal server error' });
+    }
+  });
+
+  return router;
+}
+```
+
+Register in `src/server.ts`:
+
+```typescript
+import { create<PascalName>Routes } from './api/<route-name>';
+
+// Express: register on the Express app directly
+app.use('/api', create<PascalName>Routes(collections));
+
+// NestJS: register via afterApiMiddleware in createMomentumNestServer()
+afterApiMiddleware: (app) => {
+  app.use('/api', create<PascalName>Routes(collections));
+  // ...existing static files and Angular SSR handlers
+},
+```
+
+## For Analog.js
+
+Create file-based route in `src/server/routes/api/<route-name>.get.ts`:
+
+```typescript
+import { defineEventHandler, getQuery } from 'h3';
+
+export default defineEventHandler(async (event) => {
+	const query = getQuery(event);
+
+	try {
+		// Implementation
+		return { success: true };
+	} catch (error) {
+		throw createError({
+			statusCode: 500,
+			statusMessage: 'Internal server error',
+		});
+	}
+});
+```
+
+## HTTP Method Suffixes (Analog.js)
+
+- `index.get.ts` - GET request
+- `index.post.ts` - POST request
+- `[id].get.ts` - GET with dynamic param
+- `[id].patch.ts` - PATCH with dynamic param
+- `[id].delete.ts` - DELETE with dynamic param
+- `[...].ts` - Catch-all route
+
+## h3 Utilities
+
+```typescript
+import {
+	defineEventHandler,
+	getQuery,
+	readBody,
+	getRouterParam,
+	createError,
+	setResponseStatus,
+} from 'h3';
+```

package/templates/shared/.claude/skills/collection/SKILL.md

@@ -70,8 +70,8 @@ collections: [Posts, <PascalName>],
 4. Remind user to run schema generation:
 
 ```bash
-npx drizzle-kit generate
-npx drizzle-kit push
+npm run migrate:generate
+npm run migrate:run
 ```
 
 ## Field Types Available

package/templates/shared/.claude/skills/component/SKILL.md

@@ -0,0 +1,136 @@
+---
+name: component
+description: Generate an Angular component with signals, OnPush, and host-based styling following Momentum CMS conventions.
+argument-hint: <component-name>
+---
+
+# Generate Angular Component
+
+Create an Angular component following Momentum CMS conventions.
+
+## Arguments
+
+- `$ARGUMENTS` - Component name in kebab-case (e.g., "data-table", "post-card")
+
+## Steps
+
+1. Create component file at `src/app/components/<component>.ts` (or `src/app/<feature>/<component>.ts`)
+
+2. Use this template:
+
+```typescript
+import { ChangeDetectionStrategy, Component, computed, input, output, signal, inject } from '@angular/core';
+
+@Component({
+  selector: 'app-<component-name>',
+  host: { class: 'block' },
+  template: `
+    <!-- Template here -->
+  `,
+  changeDetection: ChangeDetectionStrategy.OnPush,
+})
+export class <PascalName>Component {
+  // Signal inputs (use proper types, never `any`)
+  readonly data = input.required<DataType>();
+
+  // Optional inputs with defaults
+  readonly disabled = input(false);
+
+  // Signal outputs
+  readonly valueChange = output<ValueType>();
+
+  // Internal state
+  private readonly _loading = signal(false);
+
+  // Computed values
+  readonly loading = this._loading.asReadonly();
+  readonly hasData = computed(() => !!this.data());
+}
+```
+
+## Key Conventions
+
+- **NO `standalone: true`** — default in Angular 21, redundant
+- **NO `any` types** — use proper interfaces
+- **NO `CommonModule` import** — unnecessary in Angular 21
+- Always use `ChangeDetectionStrategy.OnPush`
+- Use `input()` and `input.required()` for inputs
+- Use `output()` for outputs
+- Use `signal()` for internal state, `computed()` for derived values
+- Use `inject()` for dependency injection
+- Use `@for`/`@if`/`@switch` control flow
+
+## UI Component Patterns
+
+### No Wrapping Divs
+
+Angular components create a host element. Style the host directly — do NOT add wrapper divs:
+
+```typescript
+@Component({
+  selector: 'app-button',
+  host: { class: 'inline-flex items-center gap-2' },
+  template: `<ng-content />`,
+})
+```
+
+NOT:
+
+```typescript
+// BAD: unnecessary wrapper div
+template: `<div class="inline-flex items-center gap-2"><ng-content /></div>`,
+```
+
+### Theme Service
+
+Use `McmsThemeService` for dark mode support:
+
+```typescript
+import { McmsThemeService } from '@momentumcms/admin';
+
+@Component({...})
+export class MyComponent {
+  private readonly theme = inject(McmsThemeService);
+
+  toggleDarkMode(): void {
+    this.theme.toggleTheme();
+  }
+
+  readonly isDark = this.theme.isDark;           // computed signal
+  readonly currentTheme = this.theme.theme;      // 'light' | 'dark' | 'system'
+}
+```
+
+## Tailwind Setup
+
+The project uses the `@momentumcms/admin` Tailwind preset and CSS variables for theming.
+
+### tailwind.config.js
+
+```javascript
+const adminPreset = require('@momentumcms/admin/tailwind.preset');
+
+module.exports = {
+	presets: [adminPreset],
+	content: [
+		'./src/**/*.{html,ts}',
+		'./node_modules/@momentumcms/admin/**/*.{html,ts,mjs}',
+		'./node_modules/@momentumcms/ui/**/*.{html,ts,mjs}',
+	],
+};
+```
+
+### styles.css
+
+CSS variables are defined in `src/styles.css` with `:root` (light) and `.dark` variants. All use HSL values referenced via `hsl(var(--mcms-<name>))`. Key tokens:
+
+- `--mcms-background/foreground` — page background and text
+- `--mcms-primary/primary-foreground` — primary actions (blue)
+- `--mcms-card/card-foreground` — card surfaces
+- `--mcms-muted/muted-foreground` — subtle backgrounds
+- `--mcms-destructive` — danger/delete actions
+- `--mcms-sidebar` — sidebar-specific colors
+- `--mcms-border`, `--mcms-input`, `--mcms-ring` — form elements
+- `--mcms-radius` — border radius base
+
+Use Tailwind utility classes that reference these tokens (e.g., `bg-background`, `text-foreground`, `border-border`).

package/templates/shared/.claude/skills/e2e-test/SKILL.md

@@ -0,0 +1,164 @@
+---
+name: e2e-test
+description: Write and validate Playwright E2E tests for Momentum CMS features. UI tests start from /admin dashboard and navigate via sidebar — never go directly to deep URLs.
+argument-hint: <feature-or-collection-name>
+---
+
+# E2E Test Writing Skill
+
+Write Playwright E2E tests for Momentum CMS features. UI tests simulate real user journeys — they **always start from the admin dashboard** and navigate through the actual UI.
+
+## RULE 1: DASHBOARD IS THE STARTING POINT
+
+**Every admin UI test starts at `/admin` (the dashboard) and navigates to the feature via the sidebar or dashboard cards.** This validates that the feature is actually visible and reachable.
+
+### The Navigation Chain
+
+```
+/admin (dashboard) → sidebar click → list view → create/view/edit
+```
+
+**NEVER do this:**
+
+```typescript
+// BAD: Skipping to a deep URL
+await page.goto('/admin/collections/posts/new');
+```
+
+**ALWAYS do this:**
+
+```typescript
+// GOOD: Start from dashboard
+await page.goto('/admin');
+await page.waitForLoadState('domcontentloaded');
+
+const sidebar = page.getByLabel('Main navigation');
+await sidebar.getByRole('link', { name: 'Posts' }).click();
+await expect(page).toHaveURL(/\/admin\/collections\/posts$/);
+
+await page.getByRole('button', { name: /Create Post/i }).click();
+```
+
+## RULE 2: NEVER WRITE BLIND TESTS
+
+**You MUST see the actual UI before writing any assertions.** Write a probe test that intentionally fails to see the page structure:
+
+```typescript
+test('probe: inspect dashboard', async ({ page }) => {
+	await page.goto('/admin');
+	await page.waitForLoadState('domcontentloaded');
+	await expect(page.getByText('XYZZY_WILL_NOT_MATCH')).toBeVisible();
+});
+```
+
+## Arguments
+
+- `$ARGUMENTS` - Feature/collection to test (e.g., "posts", "settings", "seo dashboard")
+
+## Test File Location
+
+Create test files at:
+
+```
+tests/<feature>.spec.ts
+```
+
+## Test Setup
+
+```typescript
+import { test, expect } from '@playwright/test';
+
+const ADMIN_EMAIL = 'admin@test.com';
+const ADMIN_PASSWORD = 'password123';
+
+test.beforeEach(async ({ page, request }) => {
+	// Sign in
+	await request.post('/api/auth/sign-in/email', {
+		headers: { 'Content-Type': 'application/json' },
+		data: { email: ADMIN_EMAIL, password: ADMIN_PASSWORD },
+	});
+});
+```
+
+## Admin UI Test Patterns
+
+### Full Navigation Flow
+
+```typescript
+test.describe('Feature Admin UI', () => {
+	test('navigate from dashboard to list via sidebar', async ({ page }) => {
+		await page.goto('/admin');
+		await page.waitForLoadState('domcontentloaded');
+
+		// Navigate via sidebar
+		const sidebar = page.getByLabel('Main navigation');
+		await sidebar.getByRole('link', { name: 'Posts' }).click();
+		await expect(page).toHaveURL(/\/admin\/collections\/posts$/);
+		await expect(page.getByRole('heading', { name: 'Posts' })).toBeVisible();
+	});
+
+	test('create via UI from dashboard', async ({ page }) => {
+		await page.goto('/admin');
+		await page.waitForLoadState('domcontentloaded');
+
+		const sidebar = page.getByLabel('Main navigation');
+		await sidebar.getByRole('link', { name: 'Posts' }).click();
+
+		await page.getByRole('button', { name: /Create Post/i }).click();
+		await expect(page.getByRole('button', { name: 'Create', exact: true })).toBeVisible();
+
+		await page.locator('input#field-title').fill('Test Post');
+		await page.getByRole('button', { name: 'Create', exact: true }).click();
+
+		await expect(page).toHaveURL(/\/admin\/collections\/posts\/[^/]+$/);
+	});
+});
+```
+
+### Key UI Selectors
+
+| Element         | Selector                                                     |
+| --------------- | ------------------------------------------------------------ |
+| Sidebar nav     | `getByLabel('Main navigation')`                              |
+| Dashboard group | `getByRole('region', { name: 'GroupName' })`                 |
+| Text inputs     | `locator('input#field-{fieldName}')`                         |
+| Create button   | `getByRole('button', { name: 'Create', exact: true })`       |
+| Save button     | `getByRole('button', { name: 'Save Changes' })` (NOT "Save") |
+| Edit URL        | `/{id}/edit` (view page is `/{id}`)                          |
+
+## API Test Patterns
+
+```typescript
+test.describe('Feature - API', () => {
+	test('CRUD operations', async ({ request }) => {
+		const create = await request.post('/api/posts', {
+			headers: { 'Content-Type': 'application/json' },
+			data: { title: 'API Test Post' },
+		});
+		expect(create.status()).toBe(201);
+
+		const { doc } = (await create.json()) as { doc: { id: string } };
+
+		const get = await request.get(`/api/posts/${doc.id}`);
+		expect(get.ok()).toBe(true);
+
+		// Clean up
+		await request.delete(`/api/posts/${doc.id}`);
+	});
+});
+```
+
+## Banned Patterns
+
+1. **NO `.catch(() => false/null/{})` on Playwright calls**
+2. **NO `waitForTimeout(N)`** — use `expect(locator).toBeVisible({ timeout: N })`
+3. **NO ambiguous assertions** — use exact status codes and values
+4. **NO direct URL navigation for UI tests** — always start from `/admin`
+
+## Running Tests
+
+```bash
+npx playwright test                          # Run all tests
+npx playwright test tests/<feature>.spec.ts  # Run specific spec
+npx playwright test --grep "test name"       # Run by name
+```

package/templates/shared/.claude/skills/migrations/SKILL.md

@@ -0,0 +1,55 @@
+---
+name: migrations
+description: Run migrations, generate schemas, and manage code generation for Momentum CMS.
+argument-hint: <generate|run|status|rollback|codegen>
+---
+
+# Migrations & Code Generation
+
+Reference for database migrations and type/config generation.
+
+## Arguments
+
+- `$ARGUMENTS` - Operation: `generate`, `run`, `status`, `rollback`, or `codegen`
+
+## Migration CLI
+
+```bash
+npm run migrate:generate   # Diff schema, create migration file
+npm run migrate:run        # Apply pending migrations
+npm run migrate:status     # Show applied vs pending
+npm run migrate:rollback   # Rollback latest batch
+```
+
+## Drizzle Kit
+
+```bash
+npx drizzle-kit generate   # Create SQL migrations from schema diff
+npx drizzle-kit migrate    # Apply migrations
+npx drizzle-kit push       # Direct push (dev only, skips migration files)
+```
+
+## Code Generation
+
+The generator reads `momentum.config.ts` (server-side, Node) and outputs:
+
+1. **TypeScript types** — interfaces for all collections, blocks, where clauses
+2. **Browser-safe admin config** — inlined collections with server-only props stripped
+
+```bash
+npm run generate           # One-shot generation (types + admin config)
+```
+
+Output files (do not edit manually):
+
+- `src/generated/momentum.types.ts` — TypeScript interfaces
+- `src/generated/momentum.config.ts` — Browser-safe admin config
+
+## Workflow
+
+1. Make collection changes in `src/collections/`
+2. Run `npm run generate` to regenerate types + admin config
+3. Run `npm run migrate:generate` to create a migration file
+4. Review the generated migration SQL
+5. Run `npm run migrate:run` to apply
+6. Restart the dev server

package/templates/shared/.claude/skills/momentum-api/SKILL.md

@@ -62,6 +62,18 @@ const updated = await this.api.collection<Post>('posts').update('123', { title:
 const result = await this.api.collection<Post>('posts').delete('123');
 ```
 
+### With Generated Types
+
+1. Generate types: `npm run generate`
+2. Import and use:
+
+```typescript
+import type { Post, User } from '../generated/momentum.types';
+
+const posts = await this.api.collection<Post>('posts').find();
+const users = await this.api.collection<User>('users').find();
+```
+
 ## Find Options
 
 ```typescript
@@ -78,6 +90,7 @@ interface FindOptions {
 ```typescript
 import { Component, signal, ChangeDetectionStrategy } from '@angular/core';
 import { injectMomentumAPI } from '@momentumcms/admin';
+import type { Post } from '../generated/momentum.types';
 
 @Component({
 	selector: 'app-posts',
@@ -88,17 +101,23 @@ import { injectMomentumAPI } from '@momentumcms/admin';
 			@for (post of posts(); track post.id) {
 				<article>
 					<h2>{{ post.title }}</h2>
+					<p>{{ post.content }}</p>
 					<button (click)="deletePost(post.id)">Delete</button>
 				</article>
 			}
 		}
+
+		<form (submit)="createPost($event)">
+			<input #titleInput placeholder="Title" />
+			<button type="submit">Create Post</button>
+		</form>
 	`,
 	changeDetection: ChangeDetectionStrategy.OnPush,
 })
 export class PostsComponent {
 	private readonly api = injectMomentumAPI();
 
-	readonly posts = signal<any[]>([]);
+	readonly posts = signal<Post[]>([]);
 	readonly loading = signal(true);
 
 	constructor() {
@@ -108,7 +127,7 @@ export class PostsComponent {
 	async loadPosts(): Promise<void> {
 		this.loading.set(true);
 		try {
-			const result = await this.api.collection('posts').find({
+			const result = await this.api.collection<Post>('posts').find({
 				limit: 20,
 				sort: '-createdAt',
 			});
@@ -118,8 +137,21 @@ export class PostsComponent {
 		}
 	}
 
+	async createPost(event: Event): Promise<void> {
+		event.preventDefault();
+		const form = event.target as HTMLFormElement;
+		const input = form.querySelector('input') as HTMLInputElement;
+
+		const post = await this.api.collection<Post>('posts').create({
+			title: input.value,
+		});
+
+		this.posts.update((posts) => [post, ...posts]);
+		input.value = '';
+	}
+
 	async deletePost(id: string): Promise<void> {
-		await this.api.collection('posts').delete(id);
+		await this.api.collection<Post>('posts').delete(id);
 		this.posts.update((posts) => posts.filter((p) => p.id !== id));
 	}
 }
@@ -131,28 +163,76 @@ export class PostsComponent {
 - **Browser**: HTTP calls to `/api/*`
 - **Same interface** - code works identically on both platforms
 
+## Error Handling
+
+```typescript
+import {
+	CollectionNotFoundError,
+	DocumentNotFoundError,
+	AccessDeniedError,
+	ValidationError,
+} from '@momentumcms/server-core';
+
+try {
+	await this.api.collection('posts').create({ title: '' });
+} catch (error) {
+	if (error instanceof ValidationError) {
+		console.error('Validation failed:', error.errors);
+	}
+}
+```
+
+## Type Generation
+
+Generate types from your collections:
+
+```bash
+npm run generate
+```
+
+Output files (do not edit manually):
+
+- `src/generated/momentum.types.ts` — TypeScript interfaces
+- `src/generated/momentum.config.ts` — Browser-safe admin config
+
 ## TransferState (SSR Hydration)
 
-TransferState is **enabled by default** for read operations. Data fetched during SSR is cached and reused on browser hydration.
+TransferState is **enabled by default** for all read operations (`find`, `findById`, `findSignal`, `findByIdSignal`). Data fetched during SSR is automatically cached and reused on browser hydration, eliminating duplicate HTTP calls.
+
+### Default Behavior (TransferState enabled)
 
 ```typescript
-// Default: TransferState enabled (no duplicate fetch on hydration)
+// SSR: Fetches and caches | Browser: Reads from cache (no HTTP)
 const posts = await this.api.collection<Post>('posts').find({ limit: 10 });
+const post = await this.api.collection<Post>('posts').findById(id);
+```
+
+### Opt-out
 
-// Opt-out: always fetch fresh data
-const posts = await this.api.collection<Post>('posts').find({ limit: 10, transfer: false });
+Use `transfer: false` to disable TransferState for a specific call:
+
+```typescript
+const posts = await this.api.collection<Post>('posts').find({
+	limit: 10,
+	transfer: false,
+});
 ```
 
-Requires `provideClientHydration()` in app config.
+### Signal Methods
 
-## Error Handling
+```typescript
+// Signals also use TransferState by default
+readonly posts = this.api.collection<Post>('posts').findSignal({ limit: 10 });
+readonly post = this.api.collection<Post>('posts').findByIdSignal(id);
+```
+
+### Requirements
+
+Ensure `provideClientHydration()` is in your app config:
 
 ```typescript
-try {
-	await this.api.collection('posts').create({ title: '' });
-} catch (error) {
-	if (error instanceof ValidationError) {
-		console.error('Validation failed:', error.errors);
-	}
-}
+// app.config.ts
+export const appConfig: ApplicationConfig = {
+	providers: [provideClientHydration()],
+};
 ```

package/templates/shared/docker-compose.yml.tmpl

@@ -12,7 +12,7 @@ services:
     environment:
       POSTGRES_USER: postgres
       POSTGRES_PASSWORD: postgres
-      POSTGRES_DB: momentum
+      POSTGRES_DB: {{projectName}}
     volumes:
       - {{projectName}}_postgres_data:/var/lib/postgresql/data
     healthcheck: