create-efc-app 0.3.6 → 0.4.0

package/dist/index.js

@@ -19,7 +19,6 @@ async function scaffold(opts) {
   await writeGitignore(dest);
   await writeEnvFiles(dest, opts);
   await writeExampleRoute(dest, opts);
-  if (opts.rbac) await writeRequireRoleMiddleware(dest, opts);
   if (opts.userPortal) await writeUserModel(dest, opts);
   if (opts.adminPortal) await writeAdminModel(dest, opts);
   await writeAuthRoutes(dest, opts);
@@ -149,6 +148,7 @@ async function writeEnvFiles(dest, opts) {
   const resolvedPort = isGmail ? "465" : opts.smtpPort ?? "587";
   const passComment = isGmail ? " # Gmail App Password (16 chars) \u2014 NOT your regular Gmail password. Generate at: Google Account > Security > 2-Step Verification > App passwords" : "";
   const smtpVars = opts.mailer ? `
+APP_URL=http://localhost:3000
 SMTP_HOST=${resolvedHost}
 SMTP_PORT=${resolvedPort}
 SMTP_USER=${opts.smtpUser ?? ""}
@@ -156,6 +156,7 @@ SMTP_PASS=${opts.smtpPass ?? ""}${passComment}
 SMTP_FROM=${opts.smtpUser ?? "noreply@example.com"}
 ` : "";
   const smtpExample = opts.mailer ? `
+APP_URL=http://localhost:3000
 SMTP_HOST=${resolvedHost}
 SMTP_PORT=${resolvedPort}
 SMTP_USER=your@email.com
@@ -182,14 +183,18 @@ async function writeExampleRoute(dest, opts) {
   const metaTs = opts.routeDocs ? `import type { RouteMeta } from 'express-file-cluster';
 
 export const meta: RouteMeta = {
-  description: 'Health check \u2014 returns server status and current timestamp.',
-  response: { status: 200, body: { status: 'OK', timestamp: '2024-01-01T00:00:00.000Z' } },
+  GET: {
+    description: 'Health check \u2014 returns server status and current timestamp.',
+    response: { status: 200, body: { status: 'OK', timestamp: '2024-01-01T00:00:00.000Z' } },
+  },
 };
 
 ` : "";
   const metaJs = opts.routeDocs ? `export const meta = {
-  description: 'Health check \u2014 returns server status and current timestamp.',
-  response: { status: 200, body: { status: 'OK', timestamp: '2024-01-01T00:00:00.000Z' } },
+  GET: {
+    description: 'Health check \u2014 returns server status and current timestamp.',
+    response: { status: 200, body: { status: 'OK', timestamp: '2024-01-01T00:00:00.000Z' } },
+  },
 };
 
 ` : "";
@@ -291,27 +296,42 @@ export interface UserDocument {
   avatar?: string;
   isVerified: boolean;
   isActive: boolean;
+  verifyToken?: string;
+  resetToken?: string;
+  resetTokenExpiry?: Date;
+  refreshToken?: string;
+  refreshTokenExpiry?: Date;
 }
 
 export const User = defineModel<UserDocument>('User', {
-  name:       { type: 'string',  required: true },
-  email:      { type: 'string',  required: true, unique: true },
-  password:   { type: 'string',  required: true },
-  role:       { type: 'string',  required: true, default: 'user' },
-  avatar:     { type: 'string' },
-  isVerified: { type: 'boolean', default: false },
-  isActive:   { type: 'boolean', default: true },
+  name:               { type: 'string',  required: true },
+  email:              { type: 'string',  required: true, unique: true },
+  password:           { type: 'string',  required: true },
+  role:               { type: 'string',  required: true, default: 'user' },
+  avatar:             { type: 'string' },
+  isVerified:         { type: 'boolean', default: false },
+  isActive:           { type: 'boolean', default: true },
+  verifyToken:        { type: 'string' },
+  resetToken:         { type: 'string' },
+  resetTokenExpiry:   { type: 'date' },
+  refreshToken:       { type: 'string' },
+  refreshTokenExpiry: { type: 'date' },
 });
 ` : `import { defineModel } from 'express-file-cluster';
 
 export const User = defineModel('User', {
-  name:       { type: 'string',  required: true },
-  email:      { type: 'string',  required: true, unique: true },
-  password:   { type: 'string',  required: true },
-  role:       { type: 'string',  required: true, default: 'user' },
-  avatar:     { type: 'string' },
-  isVerified: { type: 'boolean', default: false },
-  isActive:   { type: 'boolean', default: true },
+  name:               { type: 'string',  required: true },
+  email:              { type: 'string',  required: true, unique: true },
+  password:           { type: 'string',  required: true },
+  role:               { type: 'string',  required: true, default: 'user' },
+  avatar:             { type: 'string' },
+  isVerified:         { type: 'boolean', default: false },
+  isActive:           { type: 'boolean', default: true },
+  verifyToken:        { type: 'string' },
+  resetToken:         { type: 'string' },
+  resetTokenExpiry:   { type: 'date' },
+  refreshToken:       { type: 'string' },
+  refreshTokenExpiry: { type: 'date' },
 });
 ` : ts ? `// TODO: define your Drizzle schema for User
 // import { pgTable, serial, text, boolean, timestamp } from 'drizzle-orm/pg-core';
@@ -346,25 +366,37 @@ export interface AdminDocument {
   role: string;
   permissions: string[];
   isActive: boolean;
+  resetToken?: string;
+  resetTokenExpiry?: Date;
+  refreshToken?: string;
+  refreshTokenExpiry?: Date;
 }
 
 export const Admin = defineModel<AdminDocument>('Admin', {
-  name:        { type: 'string',  required: true },
-  email:       { type: 'string',  required: true, unique: true },
-  password:    { type: 'string',  required: true },
-  role:        { type: 'string',  required: true, default: 'admin' },
-  permissions: { type: 'array',   default: [] },
-  isActive:    { type: 'boolean', default: true },
+  name:               { type: 'string',  required: true },
+  email:              { type: 'string',  required: true, unique: true },
+  password:           { type: 'string',  required: true },
+  role:               { type: 'string',  required: true, default: 'admin' },
+  permissions:        { type: 'array',   default: [] },
+  isActive:           { type: 'boolean', default: true },
+  resetToken:         { type: 'string' },
+  resetTokenExpiry:   { type: 'date' },
+  refreshToken:       { type: 'string' },
+  refreshTokenExpiry: { type: 'date' },
 });
 ` : `import { defineModel } from 'express-file-cluster';
 
 export const Admin = defineModel('Admin', {
-  name:        { type: 'string',  required: true },
-  email:       { type: 'string',  required: true, unique: true },
-  password:    { type: 'string',  required: true },
-  role:        { type: 'string',  required: true, default: 'admin' },
-  permissions: { type: 'array',   default: [] },
-  isActive:    { type: 'boolean', default: true },
+  name:               { type: 'string',  required: true },
+  email:              { type: 'string',  required: true, unique: true },
+  password:           { type: 'string',  required: true },
+  role:               { type: 'string',  required: true, default: 'admin' },
+  permissions:        { type: 'array',   default: [] },
+  isActive:           { type: 'boolean', default: true },
+  resetToken:         { type: 'string' },
+  resetTokenExpiry:   { type: 'date' },
+  refreshToken:       { type: 'string' },
+  refreshTokenExpiry: { type: 'date' },
 });
 ` : ts ? `// TODO: define your Drizzle schema for Admin
 // import { pgTable, serial, text, boolean, timestamp } from 'drizzle-orm/pg-core';
@@ -392,28 +424,51 @@ async function writeAuthRoutes(dest, opts) {
   const loginMeta = opts.routeDocs ? ts ? `import type { RouteMeta } from 'express-file-cluster';
 
 export const meta: RouteMeta = {
-  description: 'Authenticate a user and issue a JWT.',
-  request: { body: { email: 'user@example.com', password: 'user' } },
-  response: { status: 200, body: { message: 'Logged in as user' } },
+  POST: {
+    description: 'Authenticate a user or admin and issue a JWT.',
+    request: { body: { email: 'user@example.com', password: 'user' } },
+    response: { status: 200, body: { message: 'Logged in as user' } },
+  },
 };
 
 ` : `export const meta = {
-  description: 'Authenticate a user and issue a JWT.',
-  request: { body: { email: 'user@example.com', password: 'user' } },
-  response: { status: 200, body: { message: 'Logged in as user' } },
+  POST: {
+    description: 'Authenticate a user or admin and issue a JWT.',
+    request: { body: { email: 'user@example.com', password: 'user' } },
+    response: { status: 200, body: { message: 'Logged in as user' } },
+  },
 };
 
 ` : "";
   const loginDbImports = opts.database === "mongodb" ? ts ? `import bcrypt from 'bcrypt';
+import crypto from 'node:crypto';
 import { User } from '../../model/User.js';
 import { Admin } from '../../model/Admin.js';
 ` : `import bcrypt from 'bcrypt';
+import crypto from 'node:crypto';
 import { User } from '../../model/User.js';
 import { Admin } from '../../model/Admin.js';
 ` : "";
   const loginContent = opts.database === "mongodb" ? ts ? `import { issueToken } from 'express-file-cluster/auth';
 import type { Request, Response } from 'express';
-${loginDbImports}${loginMeta}export const POST = async (req: Request, res: Response) => {
+${loginDbImports}${loginMeta}const REFRESH_TOKEN_TTL_MS = 1000 * 60 * 60 * 24 * 30; // 30 days
+
+async function issueRefreshToken(
+  res: Response,
+  model: { update: (id: string, data: Record<string, unknown>) => Promise<unknown> },
+  id: string,
+): Promise<void> {
+  const refreshToken = crypto.randomBytes(40).toString('hex');
+  await model.update(id, { refreshToken, refreshTokenExpiry: new Date(Date.now() + REFRESH_TOKEN_TTL_MS) });
+  res.cookie('efc_refresh_token', refreshToken, {
+    httpOnly: true,
+    secure: process.env.NODE_ENV === 'production',
+    sameSite: 'strict',
+    maxAge: REFRESH_TOKEN_TTL_MS,
+  });
+}
+
+export const POST = async (req: Request, res: Response) => {
   const { email, password } = req.body;
   if (!email || !password) return res.status(400).json({ error: 'email and password are required' });
 
@@ -423,6 +478,7 @@ ${loginDbImports}${loginMeta}export const POST = async (req: Request, res: Respo
     if (!match) return res.status(401).json({ error: 'Invalid credentials' });
     if (!admin.isActive) return res.status(403).json({ error: 'Account suspended' });
     await issueToken(res, { id: admin.id, role: admin.role, email: admin.email });
+    await issueRefreshToken(res, Admin, admin.id);
     return res.json({ message: 'Logged in as admin' });
   }
 
@@ -432,10 +488,24 @@ ${loginDbImports}${loginMeta}export const POST = async (req: Request, res: Respo
   if (!match) return res.status(401).json({ error: 'Invalid credentials' });
   if (!user.isActive) return res.status(403).json({ error: 'Account suspended' });
   await issueToken(res, { id: user.id, role: user.role, email: user.email });
+  await issueRefreshToken(res, User, user.id);
   res.json({ message: 'Logged in' });
 };
 ` : `import { issueToken } from 'express-file-cluster/auth';
-${loginDbImports}${loginMeta}export const POST = async (req, res) => {
+${loginDbImports}${loginMeta}const REFRESH_TOKEN_TTL_MS = 1000 * 60 * 60 * 24 * 30; // 30 days
+
+async function issueRefreshToken(res, model, id) {
+  const refreshToken = crypto.randomBytes(40).toString('hex');
+  await model.update(id, { refreshToken, refreshTokenExpiry: new Date(Date.now() + REFRESH_TOKEN_TTL_MS) });
+  res.cookie('efc_refresh_token', refreshToken, {
+    httpOnly: true,
+    secure: process.env.NODE_ENV === 'production',
+    sameSite: 'strict',
+    maxAge: REFRESH_TOKEN_TTL_MS,
+  });
+}
+
+export const POST = async (req, res) => {
   const { email, password } = req.body;
   if (!email || !password) return res.status(400).json({ error: 'email and password are required' });
 
@@ -445,6 +515,7 @@ ${loginDbImports}${loginMeta}export const POST = async (req, res) => {
     if (!match) return res.status(401).json({ error: 'Invalid credentials' });
     if (!admin.isActive) return res.status(403).json({ error: 'Account suspended' });
     await issueToken(res, { id: admin.id, role: admin.role, email: admin.email });
+    await issueRefreshToken(res, Admin, admin.id);
     return res.json({ message: 'Logged in as admin' });
   }
 
@@ -454,6 +525,7 @@ ${loginDbImports}${loginMeta}export const POST = async (req, res) => {
   if (!match) return res.status(401).json({ error: 'Invalid credentials' });
   if (!user.isActive) return res.status(403).json({ error: 'Account suspended' });
   await issueToken(res, { id: user.id, role: user.role, email: user.email });
+  await issueRefreshToken(res, User, user.id);
   res.json({ message: 'Logged in' });
 };
 ` : ts ? `import { issueToken } from 'express-file-cluster/auth';
@@ -473,13 +545,17 @@ ${loginMeta}export const POST = async (req, res) => {
   const logoutMeta = opts.routeDocs ? ts ? `import type { RouteMeta } from 'express-file-cluster';
 
 export const meta: RouteMeta = {
-  description: 'Clear the auth cookie and log the user out.',
-  response: { status: 200, body: { message: 'Logged out successfully' } },
+  POST: {
+    description: 'Clear the auth cookie and log the user out.',
+    response: { status: 200, body: { message: 'Logged out successfully' } },
+  },
 };
 
 ` : `export const meta = {
-  description: 'Clear the auth cookie and log the user out.',
-  response: { status: 200, body: { message: 'Logged out successfully' } },
+  POST: {
+    description: 'Clear the auth cookie and log the user out.',
+    response: { status: 200, body: { message: 'Logged out successfully' } },
+  },
 };
 
 ` : "";
@@ -487,11 +563,13 @@ export const meta: RouteMeta = {
 import type { Request, Response } from 'express';
 ${logoutMeta}export const POST = async (_req: Request, res: Response) => {
   revokeToken(res);
+  res.clearCookie('efc_refresh_token');
   res.json({ message: 'Logged out successfully' });
 };
 ` : `import { revokeToken } from 'express-file-cluster/auth';
 ${logoutMeta}export const POST = async (_req, res) => {
   revokeToken(res);
+  res.clearCookie('efc_refresh_token');
   res.json({ message: 'Logged out successfully' });
 };
 `;
@@ -501,23 +579,36 @@ ${logoutMeta}export const POST = async (_req, res) => {
   const registerMeta = opts.routeDocs ? ts ? `import type { RouteMeta } from 'express-file-cluster';
 
 export const meta: RouteMeta = {
-  description: 'Register a new user account.',
-  request: { body: { name: 'Jane Doe', email: 'jane@example.com', password: 'secret' } },
-  response: { status: 201, body: { message: 'Account created successfully' } },
+  POST: {
+    description: 'Register a new user account.',
+    request: { body: { name: 'Jane Doe', email: 'jane@example.com', password: 'secret' } },
+    response: { status: 201, body: { message: 'Account created successfully' } },
+  },
 };
 
 ` : `export const meta = {
-  description: 'Register a new user account.',
-  request: { body: { name: 'Jane Doe', email: 'jane@example.com', password: 'secret' } },
-  response: { status: 201, body: { message: 'Account created successfully' } },
+  POST: {
+    description: 'Register a new user account.',
+    request: { body: { name: 'Jane Doe', email: 'jane@example.com', password: 'secret' } },
+    response: { status: 201, body: { message: 'Account created successfully' } },
+  },
 };
 
 ` : "";
-  const registerDbImports = opts.database === "mongodb" ? ts ? `import bcrypt from 'bcrypt';
-import { User } from '../../model/User.js';
-` : `import bcrypt from 'bcrypt';
-import { User } from '../../model/User.js';
+  const registerDbImports = opts.database === "mongodb" ? `import bcrypt from 'bcrypt';
+import crypto from 'node:crypto';
+${opts.mailer ? "import { enqueue } from 'express-file-cluster/tasks';\n" : ""}import { User } from '../../model/User.js';
 ` : "";
+  const sendVerifyEmail = opts.mailer ? `
+  var appUrl = process.env.APP_URL || 'http://localhost:3000';
+  await enqueue('SendEmail', {
+    to: email,
+    subject: 'Verify your email address',
+    body: 'Welcome, ' + name + '! Verify your email: ' + appUrl + '/auth/verify-email?token=' + verifyToken,
+  });
+` : `
+  // TODO: email this token to the user \u2014 enable the Mailer feature to auto-wire SendEmail
+`;
   const registerContent = opts.database === "mongodb" ? ts ? `import type { Request, Response } from 'express';
 ${registerDbImports}${registerMeta}export const POST = async (req: Request, res: Response) => {
   const { name, email, password } = req.body;
@@ -527,8 +618,10 @@ ${registerDbImports}${registerMeta}export const POST = async (req: Request, res:
   const existing = await User.findOne({ email });
   if (existing) return res.status(409).json({ error: 'Email already in use' });
   const hashed = await bcrypt.hash(password, 10);
-  const user = await User.create({ name, email, password: hashed });
-  const { password: _, ...safe } = user;
+  const verifyToken = crypto.randomBytes(32).toString('hex');
+  const user = await User.create({ name, email, password: hashed, verifyToken });
+${sendVerifyEmail}
+  const { password: _, verifyToken: __, ...safe } = user;
   res.status(201).json({ message: 'Account created successfully', user: safe });
 };
 ` : `${registerDbImports}${registerMeta}export const POST = async (req, res) => {
@@ -539,8 +632,10 @@ ${registerDbImports}${registerMeta}export const POST = async (req: Request, res:
   const existing = await User.findOne({ email });
   if (existing) return res.status(409).json({ error: 'Email already in use' });
   const hashed = await bcrypt.hash(password, 10);
-  const user = await User.create({ name, email, password: hashed });
-  const { password: _, ...safe } = user;
+  const verifyToken = crypto.randomBytes(32).toString('hex');
+  const user = await User.create({ name, email, password: hashed, verifyToken });
+${sendVerifyEmail}
+  const { password: _, verifyToken: __, ...safe } = user;
   res.status(201).json({ message: 'Account created successfully', user: safe });
 };
 ` : ts ? `import type { Request, Response } from 'express';
@@ -564,68 +659,42 @@ ${registerMeta}export const POST = async (req: Request, res: Response) => {
   const meMeta = opts.routeDocs ? ts ? `import type { RouteMeta } from 'express-file-cluster';
 
 export const meta: RouteMeta = {
-  description: 'Return the currently authenticated user.',
-  response: { status: 200, body: { user: { id: '1', role: 'user', email: 'user@example.com' } } },
+  GET: {
+    description: 'Return the currently authenticated user.',
+    response: { status: 200, body: { user: { id: '1', role: 'user', email: 'user@example.com' } } },
+  },
 };
 
 ` : `export const meta = {
-  description: 'Return the currently authenticated user.',
-  response: { status: 200, body: { user: { id: '1', role: 'user', email: 'user@example.com' } } },
+  GET: {
+    description: 'Return the currently authenticated user.',
+    response: { status: 200, body: { user: { id: '1', role: 'user', email: 'user@example.com' } } },
+  },
 };
 
 ` : "";
-  const requireRoleImport = opts.rbac ? ts ? `import { requireRole } from '../../middleware/requireRole.js';
-` : `import { requireRole } from '../../middleware/requireRole.js';
-` : "";
-  const meMiddlewares = opts.rbac ? `export const middlewares = [requireAuth, requireRole('user', 'admin')];
+  const meMiddlewares = opts.rbac ? `export const middlewares = [requireAuth('user', 'admin')];
 
 ` : `export const middlewares = [requireAuth];
 
 `;
   const meContent = ts ? `import { requireAuth } from 'express-file-cluster/auth';
-${requireRoleImport}import type { Request, Response } from 'express';
+import type { Request, Response } from 'express';
 ${meMeta}${meMiddlewares}export const GET = async (req: Request, res: Response) => {
   res.json({ user: (req as any).user });
 };
 ` : `import { requireAuth } from 'express-file-cluster/auth';
-${requireRoleImport}${meMeta}${meMiddlewares}export const GET = async (req, res) => {
+${meMeta}${meMiddlewares}export const GET = async (req, res) => {
   res.json({ user: req.user });
 };
 `;
   await fs.outputFile(path.join(dest, "src", "api", "auth", `register.${ext}`), registerContent);
   await fs.outputFile(path.join(dest, "src", "api", "auth", `me.${ext}`), meContent);
 }
-async function writeRequireRoleMiddleware(dest, opts) {
-  const ext = opts.language === "typescript" ? "ts" : "js";
-  const content = opts.language === "typescript" ? `import type { Request, Response, NextFunction } from 'express';
-
-export function requireRole(...roles: string[]) {
-  return (req: Request, res: Response, next: NextFunction) => {
-    const user = (req as any).user;
-    if (!user) return res.status(401).json({ error: 'Unauthorized' });
-    if (!roles.includes(user.role)) return res.status(403).json({ error: 'Forbidden' });
-    next();
-  };
-}
-` : `export function requireRole(...roles) {
-  return (req, res, next) => {
-    const user = req.user;
-    if (!user) return res.status(401).json({ error: 'Unauthorized' });
-    if (!roles.includes(user.role)) return res.status(403).json({ error: 'Forbidden' });
-    next();
-  };
-}
-`;
-  await fs.outputFile(path.join(dest, "src", "middleware", `requireRole.${ext}`), content);
-}
 async function writeAdminRoutes(dest, opts) {
   const ext = opts.language === "typescript" ? "ts" : "js";
   const ts = opts.language === "typescript";
-  const requireRoleImport = opts.rbac ? `import { requireRole } from '../../middleware/requireRole.js';
-` : "";
-  const usersRequireRoleImport = opts.rbac ? `import { requireRole } from '../../../middleware/requireRole.js';
-` : "";
-  const middlewares = opts.rbac ? `export const middlewares = [requireAuth, requireRole('admin')];
+  const middlewares = opts.rbac ? `export const middlewares = [requireAuth('admin')];
 ` : `export const middlewares = [requireAuth];
 `;
   const roleGuard = opts.rbac ? "" : ts ? `  const user = (req as any).user;
@@ -642,20 +711,24 @@ async function writeAdminRoutes(dest, opts) {
   const dashboardMeta = opts.routeDocs ? ts ? `import type { RouteMeta } from 'express-file-cluster';
 
 export const meta: RouteMeta = {
-  description: 'Admin dashboard stats. Requires admin role.',
-  response: { status: 200, body: { stats: { users: 120, revenue: 5000 } } },
+  GET: {
+    description: 'Admin dashboard stats. Requires admin role.',
+    response: { status: 200, body: { stats: { totalUsers: 120, activeUsers: 98, verifiedUsers: 84 } } },
+  },
 };
 
 ` : `export const meta = {
-  description: 'Admin dashboard stats. Requires admin role.',
-  response: { status: 200, body: { stats: { users: 120, revenue: 5000 } } },
+  GET: {
+    description: 'Admin dashboard stats. Requires admin role.',
+    response: { status: 200, body: { stats: { totalUsers: 120, activeUsers: 98, verifiedUsers: 84 } } },
+  },
 };
 
 ` : "";
   const dashboardDbImport = opts.database === "mongodb" ? `import { User } from '../../model/User.js';
 ` : "";
   const dashboardContent = opts.database === "mongodb" ? ts ? `import { requireAuth } from 'express-file-cluster/auth';
-${requireRoleImport}import type { Request, Response } from 'express';
+import type { Request, Response } from 'express';
 ${dashboardDbImport}${dashboardMeta}${middlewares}
 export const GET = async (_req: Request, res: Response) => {
 ${roleGuard}  const [totalUsers, activeUsers, verifiedUsers] = await Promise.all([
@@ -666,7 +739,7 @@ ${roleGuard}  const [totalUsers, activeUsers, verifiedUsers] = await Promise.all
   res.json({ stats: { totalUsers, activeUsers, verifiedUsers } });
 };
 ` : `import { requireAuth } from 'express-file-cluster/auth';
-${requireRoleImport}${dashboardDbImport}${dashboardMeta}${middlewares}
+${dashboardDbImport}${dashboardMeta}${middlewares}
 export const GET = async (_req, res) => {
 ${roleGuard}  const [totalUsers, activeUsers, verifiedUsers] = await Promise.all([
     User.count({}),
@@ -676,14 +749,14 @@ ${roleGuard}  const [totalUsers, activeUsers, verifiedUsers] = await Promise.all
   res.json({ stats: { totalUsers, activeUsers, verifiedUsers } });
 };
 ` : ts ? `import { requireAuth } from 'express-file-cluster/auth';
-${requireRoleImport}import type { Request, Response } from 'express';
+import type { Request, Response } from 'express';
 ${dashboardMeta}${middlewares}
 export const GET = async (_req: Request, res: Response) => {
 ${roleGuard}  // TODO: aggregate stats from DB
   res.json({ stats: { users: 0 } });
 };
 ` : `import { requireAuth } from 'express-file-cluster/auth';
-${requireRoleImport}${dashboardMeta}${middlewares}
+${dashboardMeta}${middlewares}
 export const GET = async (_req, res) => {
 ${roleGuard}  // TODO: aggregate stats from DB
   res.json({ stats: { users: 0 } });
@@ -693,13 +766,29 @@ ${roleGuard}  // TODO: aggregate stats from DB
   const usersListMeta = opts.routeDocs ? ts ? `import type { RouteMeta } from 'express-file-cluster';
 
 export const meta: RouteMeta = {
-  description: 'List all users (admin only).',
-  response: { status: 200, body: { users: [], total: 0 } },
+  GET: {
+    description: 'List all users, paginated (admin only).',
+    request: { query: { page: '1', limit: '20' } },
+    response: { status: 200, body: { users: [], total: 0, page: 1, limit: 20 } },
+  },
+  POST: {
+    description: 'Create a new user account (admin only).',
+    request: { body: { name: 'Jane Doe', email: 'jane@example.com', password: 'secret', role: 'user' } },
+    response: { status: 201, body: { message: 'User created', user: { id: 'new-id', name: 'Jane Doe', email: 'jane@example.com', role: 'user' } } },
+  },
 };
 
 ` : `export const meta = {
-  description: 'List all users (admin only).',
-  response: { status: 200, body: { users: [], total: 0 } },
+  GET: {
+    description: 'List all users, paginated (admin only).',
+    request: { query: { page: '1', limit: '20' } },
+    response: { status: 200, body: { users: [], total: 0, page: 1, limit: 20 } },
+  },
+  POST: {
+    description: 'Create a new user account (admin only).',
+    request: { body: { name: 'Jane Doe', email: 'jane@example.com', password: 'secret', role: 'user' } },
+    response: { status: 201, body: { message: 'User created', user: { id: 'new-id', name: 'Jane Doe', email: 'jane@example.com', role: 'user' } } },
+  },
 };
 
 ` : "";
@@ -709,7 +798,7 @@ import { User } from '../../../model/User.js';
 import { User } from '../../../model/User.js';
 ` : "";
   const usersListContent = opts.database === "mongodb" ? ts ? `import { requireAuth } from 'express-file-cluster/auth';
-${usersRequireRoleImport}import type { Request, Response } from 'express';
+import type { Request, Response } from 'express';
 ${adminUsersDbImport}${usersListMeta}${middlewares}
 export const GET = async (req: Request, res: Response) => {
 ${roleGuard}  const page = Math.max(1, Number(req.query.page) || 1);
@@ -730,7 +819,7 @@ ${roleGuard}  const { name, email, password, role } = req.body;
   res.status(201).json({ message: 'User created', user: safe });
 };
 ` : `import { requireAuth } from 'express-file-cluster/auth';
-${usersRequireRoleImport}${adminUsersDbImport}${usersListMeta}${middlewares}
+${adminUsersDbImport}${usersListMeta}${middlewares}
 export const GET = async (req, res) => {
 ${roleGuard}  const page = Math.max(1, Number(req.query.page) || 1);
   const limit = Math.min(100, Number(req.query.limit) || 20);
@@ -750,7 +839,7 @@ ${roleGuard}  const { name, email, password, role } = req.body;
   res.status(201).json({ message: 'User created', user: safe });
 };
 ` : ts ? `import { requireAuth } from 'express-file-cluster/auth';
-${usersRequireRoleImport}import type { Request, Response } from 'express';
+import type { Request, Response } from 'express';
 ${usersListMeta}${middlewares}
 export const GET = async (_req: Request, res: Response) => {
 ${roleGuard}  // TODO: fetch users from DB with pagination
@@ -764,7 +853,7 @@ ${roleGuard}  const { name, email, role } = req.body;
   res.status(201).json({ message: 'User created', user: { id: 'new-id', name, email, role: role ?? 'user' } });
 };
 ` : `import { requireAuth } from 'express-file-cluster/auth';
-${usersRequireRoleImport}${usersListMeta}${middlewares}
+${usersListMeta}${middlewares}
 export const GET = async (_req, res) => {
 ${roleGuard}  // TODO: fetch users from DB with pagination
   res.json({ users: [], total: 0 });
@@ -781,18 +870,46 @@ ${roleGuard}  const { name, email, role } = req.body;
   const userByIdMeta = opts.routeDocs ? ts ? `import type { RouteMeta } from 'express-file-cluster';
 
 export const meta: RouteMeta = {
-  description: 'Get, update, or delete a single user by ID (admin only).',
+  GET: {
+    description: 'Fetch a single user by ID (admin only).',
+    request: { params: { id: 'usr_01HXZ' } },
+    response: { status: 200, body: { user: { id: 'usr_01HXZ', name: 'Jane Doe', email: 'jane@example.com', role: 'user' } } },
+  },
+  PUT: {
+    description: 'Update a user by ID (admin only).',
+    request: { params: { id: 'usr_01HXZ' }, body: { name: 'Jane Doe', email: 'jane@example.com', role: 'user', isActive: true } },
+    response: { status: 200, body: { message: 'User updated', user: { id: 'usr_01HXZ', name: 'Jane Doe', email: 'jane@example.com', role: 'user' } } },
+  },
+  DELETE: {
+    description: 'Delete a user by ID (admin only).',
+    request: { params: { id: 'usr_01HXZ' } },
+    response: { status: 200, body: { message: 'User usr_01HXZ deleted' } },
+  },
 };
 
 ` : `export const meta = {
-  description: 'Get, update, or delete a single user by ID (admin only).',
+  GET: {
+    description: 'Fetch a single user by ID (admin only).',
+    request: { params: { id: 'usr_01HXZ' } },
+    response: { status: 200, body: { user: { id: 'usr_01HXZ', name: 'Jane Doe', email: 'jane@example.com', role: 'user' } } },
+  },
+  PUT: {
+    description: 'Update a user by ID (admin only).',
+    request: { params: { id: 'usr_01HXZ' }, body: { name: 'Jane Doe', email: 'jane@example.com', role: 'user', isActive: true } },
+    response: { status: 200, body: { message: 'User updated', user: { id: 'usr_01HXZ', name: 'Jane Doe', email: 'jane@example.com', role: 'user' } } },
+  },
+  DELETE: {
+    description: 'Delete a user by ID (admin only).',
+    request: { params: { id: 'usr_01HXZ' } },
+    response: { status: 200, body: { message: 'User usr_01HXZ deleted' } },
+  },
 };
 
 ` : "";
   const adminUserByIdDbImport = opts.database === "mongodb" ? `import { User } from '../../../model/User.js';
 ` : "";
   const userByIdContent = opts.database === "mongodb" ? ts ? `import { requireAuth } from 'express-file-cluster/auth';
-${usersRequireRoleImport}import type { Request, Response } from 'express';
+import type { Request, Response } from 'express';
 ${adminUserByIdDbImport}${userByIdMeta}${middlewares}
 export const GET = async (req: Request, res: Response) => {
 ${roleGuard}  const { id } = req.params;
@@ -819,7 +936,7 @@ ${roleGuard}  const { id } = req.params;
   res.json({ message: \`User \${id} deleted\` });
 };
 ` : `import { requireAuth } from 'express-file-cluster/auth';
-${usersRequireRoleImport}${adminUserByIdDbImport}${userByIdMeta}${middlewares}
+${adminUserByIdDbImport}${userByIdMeta}${middlewares}
 export const GET = async (req, res) => {
 ${roleGuard}  const { id } = req.params;
   const user = await User.findById(id);
@@ -845,7 +962,7 @@ ${roleGuard}  const { id } = req.params;
   res.json({ message: \`User \${id} deleted\` });
 };
 ` : ts ? `import { requireAuth } from 'express-file-cluster/auth';
-${usersRequireRoleImport}import type { Request, Response } from 'express';
+import type { Request, Response } from 'express';
 ${userByIdMeta}${middlewares}
 export const GET = async (req: Request, res: Response) => {
 ${roleGuard}  const { id } = req.params;
@@ -865,7 +982,7 @@ ${roleGuard}  const { id } = req.params;
   res.json({ message: \`User \${id} deleted\` });
 };
 ` : `import { requireAuth } from 'express-file-cluster/auth';
-${usersRequireRoleImport}${userByIdMeta}${middlewares}
+${userByIdMeta}${middlewares}
 export const GET = async (req, res) => {
 ${roleGuard}  const { id } = req.params;
   // TODO: fetch user from DB
@@ -889,28 +1006,40 @@ ${roleGuard}  const { id } = req.params;
 async function writeUserRoutes(dest, opts) {
   const ext = opts.language === "typescript" ? "ts" : "js";
   const ts = opts.language === "typescript";
-  const requireRoleImport = opts.rbac ? `import { requireRole } from '../../middleware/requireRole.js';
-` : "";
-  const middlewares = opts.rbac ? `export const middlewares = [requireAuth, requireRole('user', 'admin')];
+  const middlewares = opts.rbac ? `export const middlewares = [requireAuth('user', 'admin')];
 ` : `export const middlewares = [requireAuth];
 `;
   const profileMeta = opts.routeDocs ? ts ? `import type { RouteMeta } from 'express-file-cluster';
 
 export const meta: RouteMeta = {
-  description: "View or update the authenticated user's profile.",
-  response: { status: 200, body: { user: { id: '1', role: 'user', email: 'user@example.com' } } },
+  GET: {
+    description: "Fetch the authenticated user's profile.",
+    response: { status: 200, body: { user: { id: '1', role: 'user', email: 'user@example.com' } } },
+  },
+  PUT: {
+    description: "Update the authenticated user's profile.",
+    request: { body: { name: 'Jane Doe', email: 'jane@example.com' } },
+    response: { status: 200, body: { message: 'Profile updated', user: { id: '1', role: 'user', email: 'jane@example.com' } } },
+  },
 };
 
 ` : `export const meta = {
-  description: "View or update the authenticated user's profile.",
-  response: { status: 200, body: { user: { id: '1', role: 'user', email: 'user@example.com' } } },
+  GET: {
+    description: "Fetch the authenticated user's profile.",
+    response: { status: 200, body: { user: { id: '1', role: 'user', email: 'user@example.com' } } },
+  },
+  PUT: {
+    description: "Update the authenticated user's profile.",
+    request: { body: { name: 'Jane Doe', email: 'jane@example.com' } },
+    response: { status: 200, body: { message: 'Profile updated', user: { id: '1', role: 'user', email: 'jane@example.com' } } },
+  },
 };
 
 ` : "";
   const profileDbImport = opts.database === "mongodb" ? `import { User } from '../../model/User.js';
 ` : "";
   const profileContent = opts.database === "mongodb" ? ts ? `import { requireAuth } from 'express-file-cluster/auth';
-${requireRoleImport}import type { Request, Response } from 'express';
+import type { Request, Response } from 'express';
 ${profileDbImport}${profileMeta}${middlewares}
 export const GET = async (req: Request, res: Response) => {
   const { id } = (req as any).user;
@@ -929,7 +1058,7 @@ export const PUT = async (req: Request, res: Response) => {
   res.json({ message: 'Profile updated', user: safe });
 };
 ` : `import { requireAuth } from 'express-file-cluster/auth';
-${requireRoleImport}${profileDbImport}${profileMeta}${middlewares}
+${profileDbImport}${profileMeta}${middlewares}
 export const GET = async (req, res) => {
   const { id } = req.user;
   const user = await User.findById(id);
@@ -947,7 +1076,7 @@ export const PUT = async (req, res) => {
   res.json({ message: 'Profile updated', user: safe });
 };
 ` : ts ? `import { requireAuth } from 'express-file-cluster/auth';
-${requireRoleImport}import type { Request, Response } from 'express';
+import type { Request, Response } from 'express';
 ${profileMeta}${middlewares}
 export const GET = async (req: Request, res: Response) => {
   res.json({ user: (req as any).user });
@@ -959,7 +1088,7 @@ export const PUT = async (req: Request, res: Response) => {
   res.json({ message: 'Profile updated', user: { ...(req as any).user, name, email } });
 };
 ` : `import { requireAuth } from 'express-file-cluster/auth';
-${requireRoleImport}${profileMeta}${middlewares}
+${profileMeta}${middlewares}
 export const GET = async (req, res) => {
   res.json({ user: req.user });
 };
@@ -972,20 +1101,32 @@ export const PUT = async (req, res) => {
 `;
   await fs.outputFile(path.join(dest, "src", "api", "user", `profile.${ext}`), profileContent);
 }
-function mkMeta(opts, description, body, req) {
+function mkMeta(opts, methods) {
   if (!opts.routeDocs) return "";
-  const reqLine = req ? `  request: { body: ${req} },
+  const blocks = Object.entries(methods).map(([method, m]) => {
+    const reqParts = [];
+    if (m.params) reqParts.push(`params: ${m.params}`);
+    if (m.query) reqParts.push(`query: ${m.query}`);
+    if (m.request) reqParts.push(`body: ${m.request}`);
+    const reqLine = reqParts.length ? `      request: { ${reqParts.join(", ")} },
 ` : "";
+    const status = m.status ?? 200;
+    const respLine = m.response !== void 0 ? `      response: { status: ${status}, body: ${m.response} },
+` : `      response: { status: ${status} },
+`;
+    const description = m.description.replace(/'/g, "\\'");
+    return `  ${method}: {
+    description: '${description}',
+${reqLine}${respLine}  },`;
+  }).join("\n");
   return opts.language === "typescript" ? `import type { RouteMeta } from 'express-file-cluster';
 
 export const meta: RouteMeta = {
-  description: '${description}',
-${reqLine}  response: { status: 200, body: ${body} },
+${blocks}
 };
 
 ` : `export const meta = {
-  description: '${description}',
-${reqLine}  response: { status: 200, body: ${body} },
+${blocks}
 };
 
 `;
@@ -1700,11 +1841,7 @@ export {};
 async function writeAuthExtendedRoutes(dest, opts) {
   const ext = opts.language === "typescript" ? "ts" : "js";
   const ts = opts.language === "typescript";
-  const rr2 = opts.rbac ? `import { requireRole } from '../../middleware/requireRole.js';
-` : "";
-  const rr3 = opts.rbac ? `import { requireRole } from '../../../middleware/requireRole.js';
-` : "";
-  const mwUser2 = opts.rbac ? `export const middlewares = [requireAuth, requireRole('user', 'admin')];
+  const mwUser2 = opts.rbac ? `export const middlewares = [requireAuth('user', 'admin')];
 ` : `export const middlewares = [requireAuth];
 `;
   const mwUser3 = mwUser2;
@@ -1712,8 +1849,96 @@ async function writeAuthExtendedRoutes(dest, opts) {
 ` : "";
   const RA = `import { requireAuth } from 'express-file-cluster/auth';
 `;
-  const refreshMeta = mkMeta(opts, "Refresh the JWT and issue a new token.", `{ message: 'Token refreshed' }`);
-  const refreshContent = ts ? `${RA}import type { Request, Response } from 'express';
+  const mongo = opts.database === "mongodb";
+  const sendResetEmail = opts.mailer ? `    var appUrl = process.env.APP_URL || 'http://localhost:3000';
+    await enqueue('SendEmail', {
+      to: email,
+      subject: 'Reset your password',
+      body: 'Reset your password: ' + appUrl + '/auth/reset-password?token=' + resetToken,
+    });
+` : `    // TODO: email this token to the user \u2014 enable the Mailer feature to auto-wire SendEmail
+`;
+  const sendVerifyEmailResend = opts.mailer ? `    var appUrl = process.env.APP_URL || 'http://localhost:3000';
+    await enqueue('SendEmail', {
+      to: email,
+      subject: 'Verify your email address',
+      body: 'Verify your email: ' + appUrl + '/auth/verify-email?token=' + verifyToken,
+    });
+` : `    // TODO: email this token to the user \u2014 enable the Mailer feature to auto-wire SendEmail
+`;
+  const mailerTaskImport = opts.mailer ? `import { enqueue } from 'express-file-cluster/tasks';
+` : "";
+  const refreshMeta = mkMeta(opts, {
+    POST: { description: "Refresh the JWT using the refresh-token cookie and issue a new access token.", response: `{ message: 'Token refreshed' }` }
+  });
+  const refreshContent = mongo ? ts ? `import { issueToken } from 'express-file-cluster/auth';
+import type { Request, Response } from 'express';
+import crypto from 'node:crypto';
+import { User } from '../../model/User.js';
+import { Admin } from '../../model/Admin.js';
+${refreshMeta}const REFRESH_TOKEN_TTL_MS = 1000 * 60 * 60 * 24 * 30; // 30 days
+
+export const POST = async (req: Request, res: Response) => {
+  const token = req.cookies?.['efc_refresh_token'] || req.body?.refreshToken;
+  if (!token) return res.status(401).json({ error: 'Refresh token required' });
+
+  const user = await User.findOne({ refreshToken: token });
+  const admin = user ? null : await Admin.findOne({ refreshToken: token });
+  const account = user || admin;
+
+  if (!account || !account.refreshTokenExpiry || new Date(account.refreshTokenExpiry) < new Date()) {
+    return res.status(401).json({ error: 'Invalid or expired refresh token' });
+  }
+
+  const newRefreshToken = crypto.randomBytes(40).toString('hex');
+  const refreshTokenExpiry = new Date(Date.now() + REFRESH_TOKEN_TTL_MS);
+  if (user) await User.update(user.id, { refreshToken: newRefreshToken, refreshTokenExpiry });
+  else if (admin) await Admin.update(admin.id, { refreshToken: newRefreshToken, refreshTokenExpiry });
+
+  res.cookie('efc_refresh_token', newRefreshToken, {
+    httpOnly: true,
+    secure: process.env.NODE_ENV === 'production',
+    sameSite: 'strict',
+    maxAge: REFRESH_TOKEN_TTL_MS,
+  });
+
+  await issueToken(res, { id: account.id, role: account.role, email: account.email });
+  res.json({ message: 'Token refreshed' });
+};
+` : `import { issueToken } from 'express-file-cluster/auth';
+import crypto from 'node:crypto';
+import { User } from '../../model/User.js';
+import { Admin } from '../../model/Admin.js';
+${refreshMeta}const REFRESH_TOKEN_TTL_MS = 1000 * 60 * 60 * 24 * 30; // 30 days
+
+export const POST = async (req, res) => {
+  const token = req.cookies?.efc_refresh_token || req.body?.refreshToken;
+  if (!token) return res.status(401).json({ error: 'Refresh token required' });
+
+  const user = await User.findOne({ refreshToken: token });
+  const admin = user ? null : await Admin.findOne({ refreshToken: token });
+  const account = user || admin;
+
+  if (!account || !account.refreshTokenExpiry || new Date(account.refreshTokenExpiry) < new Date()) {
+    return res.status(401).json({ error: 'Invalid or expired refresh token' });
+  }
+
+  const newRefreshToken = crypto.randomBytes(40).toString('hex');
+  const refreshTokenExpiry = new Date(Date.now() + REFRESH_TOKEN_TTL_MS);
+  if (user) await User.update(user.id, { refreshToken: newRefreshToken, refreshTokenExpiry });
+  else if (admin) await Admin.update(admin.id, { refreshToken: newRefreshToken, refreshTokenExpiry });
+
+  res.cookie('efc_refresh_token', newRefreshToken, {
+    httpOnly: true,
+    secure: process.env.NODE_ENV === 'production',
+    sameSite: 'strict',
+    maxAge: REFRESH_TOKEN_TTL_MS,
+  });
+
+  await issueToken(res, { id: account.id, role: account.role, email: account.email });
+  res.json({ message: 'Token refreshed' });
+};
+` : ts ? `${RA}import type { Request, Response } from 'express';
 ${refreshMeta}export const POST = async (_req: Request, res: Response) => {
   // TODO: validate refresh token, issue new JWT
   res.json({ message: 'Token refreshed' });
@@ -1724,8 +1949,62 @@ ${refreshMeta}export const POST = async (_req: Request, res: Response) => {
 };
 `;
   await fs.outputFile(path.join(dest, "src", "api", "auth", `refresh.${ext}`), refreshContent);
-  const veMeta = mkMeta(opts, "Verify email address via token or resend verification email.", `{ message: 'Email verified' }`);
-  const veContent = ts ? `${RA}import type { Request, Response } from 'express';
+  const veMeta = mkMeta(opts, {
+    GET: { description: "Verify an email address using the token from the verification link.", query: `{ token: 'a1b2c3d4' }`, response: `{ message: 'Email verified' }` },
+    POST: { description: "Resend the verification email to a given address.", request: `{ email: 'user@example.com' }`, response: `{ message: 'Verification email sent' }` }
+  });
+  const veContent = mongo ? ts ? `import type { Request, Response } from 'express';
+import crypto from 'node:crypto';
+${mailerTaskImport}import { User } from '../../model/User.js';
+${veMeta}export const GET = async (req: Request, res: Response) => {
+  const { token } = req.query;
+  if (!token || typeof token !== 'string') return res.status(400).json({ error: 'token is required' });
+
+  const user = await User.findOne({ verifyToken: token });
+  if (!user) return res.status(400).json({ error: 'Invalid or expired verification token' });
+
+  await User.update(user.id, { isVerified: true, verifyToken: '' });
+  res.json({ message: 'Email verified' });
+};
+
+export const POST = async (req: Request, res: Response) => {
+  const { email } = req.body;
+  if (!email) return res.status(400).json({ error: 'email is required' });
+
+  const user = await User.findOne({ email });
+  if (user && !user.isVerified) {
+    const verifyToken = crypto.randomBytes(32).toString('hex');
+    await User.update(user.id, { verifyToken });
+${sendVerifyEmailResend}  }
+
+  res.json({ message: 'Verification email sent' });
+};
+` : `import crypto from 'node:crypto';
+${mailerTaskImport}import { User } from '../../model/User.js';
+${veMeta}export const GET = async (req, res) => {
+  const { token } = req.query;
+  if (!token || typeof token !== 'string') return res.status(400).json({ error: 'token is required' });
+
+  const user = await User.findOne({ verifyToken: token });
+  if (!user) return res.status(400).json({ error: 'Invalid or expired verification token' });
+
+  await User.update(user.id, { isVerified: true, verifyToken: '' });
+  res.json({ message: 'Email verified' });
+};
+
+export const POST = async (req, res) => {
+  const { email } = req.body;
+  if (!email) return res.status(400).json({ error: 'email is required' });
+
+  const user = await User.findOne({ email });
+  if (user && !user.isVerified) {
+    const verifyToken = crypto.randomBytes(32).toString('hex');
+    await User.update(user.id, { verifyToken });
+${sendVerifyEmailResend}  }
+
+  res.json({ message: 'Verification email sent' });
+};
+` : ts ? `${RA}import type { Request, Response } from 'express';
 ${veMeta}export const GET = async (req: Request, res: Response) => {
   const { token } = req.query;
   // TODO: verify token and mark user as verified
@@ -1748,8 +2027,57 @@ export const POST = async (_req, res) => {
 };
 `;
   await fs.outputFile(path.join(dest, "src", "api", "auth", `verify-email.${ext}`), veContent);
-  const fpMeta = mkMeta(opts, "Send a password reset email to the given address.", `{ message: 'Reset email sent' }`, `{ email: 'user@example.com' }`);
-  const fpContent = ts ? `${RA}import type { Request, Response } from 'express';
+  const fpMeta = mkMeta(opts, {
+    POST: { description: "Send a password reset email to the given address.", request: `{ email: 'user@example.com' }`, response: `{ message: 'Reset email sent' }` }
+  });
+  const fpContent = mongo ? ts ? `import type { Request, Response } from 'express';
+import crypto from 'node:crypto';
+${mailerTaskImport}import { User } from '../../model/User.js';
+import { Admin } from '../../model/Admin.js';
+${fpMeta}const RESET_TOKEN_TTL_MS = 1000 * 60 * 60; // 1 hour
+
+export const POST = async (req: Request, res: Response) => {
+  const { email } = req.body;
+  if (!email) return res.status(400).json({ error: 'email is required' });
+
+  const user = await User.findOne({ email });
+  const admin = user ? null : await Admin.findOne({ email });
+
+  // Always respond the same way whether or not the account exists, so this
+  // endpoint can't be used to enumerate registered emails.
+  if (user || admin) {
+    const resetToken = crypto.randomBytes(32).toString('hex');
+    const resetTokenExpiry = new Date(Date.now() + RESET_TOKEN_TTL_MS);
+    if (user) await User.update(user.id, { resetToken, resetTokenExpiry });
+    else if (admin) await Admin.update(admin.id, { resetToken, resetTokenExpiry });
+${sendResetEmail}  }
+
+  res.json({ message: 'Reset email sent' });
+};
+` : `import crypto from 'node:crypto';
+${mailerTaskImport}import { User } from '../../model/User.js';
+import { Admin } from '../../model/Admin.js';
+${fpMeta}const RESET_TOKEN_TTL_MS = 1000 * 60 * 60; // 1 hour
+
+export const POST = async (req, res) => {
+  const { email } = req.body;
+  if (!email) return res.status(400).json({ error: 'email is required' });
+
+  const user = await User.findOne({ email });
+  const admin = user ? null : await Admin.findOne({ email });
+
+  // Always respond the same way whether or not the account exists, so this
+  // endpoint can't be used to enumerate registered emails.
+  if (user || admin) {
+    const resetToken = crypto.randomBytes(32).toString('hex');
+    const resetTokenExpiry = new Date(Date.now() + RESET_TOKEN_TTL_MS);
+    if (user) await User.update(user.id, { resetToken, resetTokenExpiry });
+    else if (admin) await Admin.update(admin.id, { resetToken, resetTokenExpiry });
+${sendResetEmail}  }
+
+  res.json({ message: 'Reset email sent' });
+};
+` : ts ? `${RA}import type { Request, Response } from 'express';
 ${fpMeta}export const POST = async (req: Request, res: Response) => {
   const { email } = req.body;
   if (!email) return res.status(400).json({ error: 'email is required' });
@@ -1764,8 +2092,53 @@ ${fpMeta}export const POST = async (req: Request, res: Response) => {
 };
 `;
   await fs.outputFile(path.join(dest, "src", "api", "auth", `forgot-password.${ext}`), fpContent);
-  const rpMeta = mkMeta(opts, "Reset password using a valid reset token.", `{ message: 'Password reset successfully' }`, `{ token: 'reset-token', password: 'newpassword' }`);
-  const rpContent = ts ? `${RA}import type { Request, Response } from 'express';
+  const rpMeta = mkMeta(opts, {
+    POST: { description: "Reset password using a valid reset token.", request: `{ token: 'reset-token', password: 'newpassword' }`, response: `{ message: 'Password reset successfully' }` }
+  });
+  const rpContent = mongo ? ts ? `import type { Request, Response } from 'express';
+import bcrypt from 'bcrypt';
+import { User } from '../../model/User.js';
+import { Admin } from '../../model/Admin.js';
+${rpMeta}export const POST = async (req: Request, res: Response) => {
+  const { token, password } = req.body;
+  if (!token || !password) return res.status(400).json({ error: 'token and password are required' });
+
+  const user = await User.findOne({ resetToken: token });
+  const admin = user ? null : await Admin.findOne({ resetToken: token });
+  const account = user || admin;
+
+  if (!account || !account.resetTokenExpiry || new Date(account.resetTokenExpiry) < new Date()) {
+    return res.status(400).json({ error: 'Invalid or expired reset token' });
+  }
+
+  const hashed = await bcrypt.hash(password, 10);
+  if (user) await User.update(user.id, { password: hashed, resetToken: '' });
+  else if (admin) await Admin.update(admin.id, { password: hashed, resetToken: '' });
+
+  res.json({ message: 'Password reset successfully' });
+};
+` : `import bcrypt from 'bcrypt';
+import { User } from '../../model/User.js';
+import { Admin } from '../../model/Admin.js';
+${rpMeta}export const POST = async (req, res) => {
+  const { token, password } = req.body;
+  if (!token || !password) return res.status(400).json({ error: 'token and password are required' });
+
+  const user = await User.findOne({ resetToken: token });
+  const admin = user ? null : await Admin.findOne({ resetToken: token });
+  const account = user || admin;
+
+  if (!account || !account.resetTokenExpiry || new Date(account.resetTokenExpiry) < new Date()) {
+    return res.status(400).json({ error: 'Invalid or expired reset token' });
+  }
+
+  const hashed = await bcrypt.hash(password, 10);
+  if (user) await User.update(user.id, { password: hashed, resetToken: '' });
+  else if (admin) await Admin.update(admin.id, { password: hashed, resetToken: '' });
+
+  res.json({ message: 'Password reset successfully' });
+};
+` : ts ? `${RA}import type { Request, Response } from 'express';
 ${rpMeta}export const POST = async (req: Request, res: Response) => {
   const { token, password } = req.body;
   if (!token || !password) return res.status(400).json({ error: 'token and password are required' });
@@ -1780,8 +2153,10 @@ ${rpMeta}export const POST = async (req: Request, res: Response) => {
 };
 `;
   await fs.outputFile(path.join(dest, "src", "api", "auth", `reset-password.${ext}`), rpContent);
-  const cpMeta = mkMeta(opts, "Change password for the authenticated user.", `{ message: 'Password changed successfully' }`, `{ oldPassword: 'current', newPassword: 'newpassword' }`);
-  const cpContent = ts ? `${RA}${rr2}import type { Request, Response } from 'express';
+  const cpMeta = mkMeta(opts, {
+    POST: { description: "Change password for the authenticated user.", request: `{ oldPassword: 'current', newPassword: 'newpassword' }`, response: `{ message: 'Password changed successfully' }` }
+  });
+  const cpContent = ts ? `${RA}import type { Request, Response } from 'express';
 ${cpMeta}${mwUser2}
 export const POST = async (req: Request, res: Response) => {
   const { oldPassword, newPassword } = req.body;
@@ -1789,7 +2164,7 @@ export const POST = async (req: Request, res: Response) => {
   // TODO: verify old password, hash and update new password
   res.json({ message: 'Password changed successfully' });
 };
-` : `${RA}${rr2}${cpMeta}${mwUser2}
+` : `${RA}${cpMeta}${mwUser2}
 export const POST = async (req, res) => {
   const { oldPassword, newPassword } = req.body;
   if (!oldPassword || !newPassword) return res.status(400).json({ error: 'oldPassword and newPassword are required' });
@@ -1798,8 +2173,11 @@ export const POST = async (req, res) => {
 };
 `;
   await fs.outputFile(path.join(dest, "src", "api", "auth", `change-password.${ext}`), cpContent);
-  const tfaSetupMeta = mkMeta(opts, "Get 2FA QR code (GET) or enable 2FA with a verified TOTP code (POST).", `{ message: '2FA enabled' }`);
-  const tfaSetupContent = ts ? `${RA}${rr3}import type { Request, Response } from 'express';
+  const tfaSetupMeta = mkMeta(opts, {
+    GET: { description: "Generate a TOTP secret and QR code to set up 2FA.", response: `{ qrCode: 'otpauth://totp/...', secret: 'BASE32SECRET' }` },
+    POST: { description: "Confirm a TOTP code to enable 2FA for the authenticated user.", request: `{ code: '123456' }`, response: `{ message: '2FA enabled' }` }
+  });
+  const tfaSetupContent = ts ? `${RA}import type { Request, Response } from 'express';
 ${tfaSetupMeta}${mwUser3}
 export const GET = async (req: Request, res: Response) => {
   // TODO: generate TOTP secret and return QR code URL
@@ -1812,7 +2190,7 @@ export const POST = async (req: Request, res: Response) => {
   // TODO: verify TOTP code and enable 2FA
   res.json({ message: '2FA enabled' });
 };
-` : `${RA}${rr3}${tfaSetupMeta}${mwUser3}
+` : `${RA}${tfaSetupMeta}${mwUser3}
 export const GET = async (req, res) => {
   // TODO: generate TOTP secret and return QR code URL
   res.json({ qrCode: 'otpauth://totp/...', secret: 'BASE32SECRET' });
@@ -1826,7 +2204,9 @@ export const POST = async (req, res) => {
 };
 `;
   await fs.outputFile(path.join(dest, "src", "api", "auth", "2fa", `setup.${ext}`), tfaSetupContent);
-  const tfaVerifyMeta = mkMeta(opts, "Verify a TOTP code during login.", `{ message: '2FA verified' }`);
+  const tfaVerifyMeta = mkMeta(opts, {
+    POST: { description: "Verify a TOTP code during login.", request: `{ code: '123456' }`, response: `{ message: '2FA verified' }` }
+  });
   const tfaVerifyContent = ts ? `${RA}import type { Request, Response } from 'express';
 ${tfaVerifyMeta}export const POST = async (req: Request, res: Response) => {
   const { code } = req.body;
@@ -1842,8 +2222,10 @@ ${tfaVerifyMeta}export const POST = async (req: Request, res: Response) => {
 };
 `;
   await fs.outputFile(path.join(dest, "src", "api", "auth", "2fa", `verify.${ext}`), tfaVerifyContent);
-  const tfaDisableMeta = mkMeta(opts, "Disable 2FA for the authenticated user.", `{ message: '2FA disabled' }`);
-  const tfaDisableContent = ts ? `${RA}${rr3}import type { Request, Response } from 'express';
+  const tfaDisableMeta = mkMeta(opts, {
+    POST: { description: "Disable 2FA for the authenticated user.", request: `{ code: '123456' }`, response: `{ message: '2FA disabled' }` }
+  });
+  const tfaDisableContent = ts ? `${RA}import type { Request, Response } from 'express';
 ${tfaDisableMeta}${mwUser3}
 export const POST = async (req: Request, res: Response) => {
   const { code } = req.body;
@@ -1851,7 +2233,7 @@ export const POST = async (req: Request, res: Response) => {
   // TODO: verify code and disable 2FA
   res.json({ message: '2FA disabled' });
 };
-` : `${RA}${rr3}${tfaDisableMeta}${mwUser3}
+` : `${RA}${tfaDisableMeta}${mwUser3}
 export const POST = async (req, res) => {
   const { code } = req.body;
   if (!code) return res.status(400).json({ error: 'code is required' });
@@ -1860,28 +2242,33 @@ export const POST = async (req, res) => {
 };
 `;
   await fs.outputFile(path.join(dest, "src", "api", "auth", "2fa", `disable.${ext}`), tfaDisableContent);
-  const sessListMeta = mkMeta(opts, "List all active sessions for the authenticated user.", `{ sessions: [] }`);
-  const sessListContent = ts ? `${RA}${rr3}import type { Request, Response } from 'express';
+  const sessListMeta = mkMeta(opts, {
+    GET: { description: "List all active sessions for the authenticated user.", response: `{ sessions: [] }` }
+  });
+  const sessListContent = ts ? `${RA}import type { Request, Response } from 'express';
 ${sessListMeta}${mwUser3}
 export const GET = async (req: Request, res: Response) => {
   // TODO: fetch sessions for req.user.id
   res.json({ sessions: [] });
 };
-` : `${RA}${rr3}${sessListMeta}${mwUser3}
+` : `${RA}${sessListMeta}${mwUser3}
 export const GET = async (req, res) => {
   // TODO: fetch sessions for req.user.id
   res.json({ sessions: [] });
 };
 `;
   await fs.outputFile(path.join(dest, "src", "api", "auth", "sessions", `index.${ext}`), sessListContent);
-  const sessRevokeContent = ts ? `${RA}${rr3}import type { Request, Response } from 'express';
-${mwUser3}
+  const sessRevokeMeta = mkMeta(opts, {
+    DELETE: { description: "Revoke a single active session by ID.", params: `{ id: 'sess_01HXZ' }`, response: `{ message: 'Session sess_01HXZ revoked' }` }
+  });
+  const sessRevokeContent = ts ? `${RA}import type { Request, Response } from 'express';
+${sessRevokeMeta}${mwUser3}
 export const DELETE = async (req: Request, res: Response) => {
   const { id } = req.params;
   // TODO: revoke session by id
   res.json({ message: \`Session \${id} revoked\` });
 };
-` : `${RA}${rr3}${mwUser3}
+` : `${RA}${sessRevokeMeta}${mwUser3}
 export const DELETE = async (req, res) => {
   const { id } = req.params;
   // TODO: revoke session by id
@@ -1893,19 +2280,18 @@ export const DELETE = async (req, res) => {
 async function writeUserExtendedRoutes(dest, opts) {
   const ext = opts.language === "typescript" ? "ts" : "js";
   const ts = opts.language === "typescript";
-  const rr2 = opts.rbac ? `import { requireRole } from '../../middleware/requireRole.js';
-` : "";
-  const rr3 = opts.rbac ? `import { requireRole } from '../../../middleware/requireRole.js';
-` : "";
-  const mw2 = opts.rbac ? `export const middlewares = [requireAuth, requireRole('user', 'admin')];
+  const mw2 = opts.rbac ? `export const middlewares = [requireAuth('user', 'admin')];
 ` : `export const middlewares = [requireAuth];
 `;
   const mw3 = mw2;
   const RA = `import { requireAuth } from 'express-file-cluster/auth';
 `;
   const user = ts ? `(req as any).user` : `req.user`;
-  const avatarMeta = mkMeta(opts, "Upload (POST) or remove (DELETE) the authenticated user avatar.", `{ message: 'Avatar updated', url: 'https://...' }`);
-  const avatarContent = ts ? `${RA}${rr2}import type { Request, Response } from 'express';
+  const avatarMeta = mkMeta(opts, {
+    POST: { description: "Upload a new avatar image for the authenticated user.", response: `{ message: 'Avatar updated', url: 'https://example.com/avatar.jpg' }` },
+    DELETE: { description: "Remove the authenticated user's avatar.", response: `{ message: 'Avatar removed' }` }
+  });
+  const avatarContent = ts ? `${RA}import type { Request, Response } from 'express';
 ${avatarMeta}${mw2}
 export const POST = async (req: Request, res: Response) => {
   // TODO: handle multipart upload, store file, update user.avatar
@@ -1916,7 +2302,7 @@ export const DELETE = async (req: Request, res: Response) => {
   // TODO: remove avatar and clear user.avatar
   res.json({ message: 'Avatar removed' });
 };
-` : `${RA}${rr2}${avatarMeta}${mw2}
+` : `${RA}${avatarMeta}${mw2}
 export const POST = async (req, res) => {
   // TODO: handle multipart upload, store file, update user.avatar
   res.json({ message: 'Avatar updated', url: 'https://example.com/avatar.jpg' });
@@ -1928,8 +2314,11 @@ export const DELETE = async (req, res) => {
 };
 `;
   await fs.outputFile(path.join(dest, "src", "api", "user", `avatar.${ext}`), avatarContent);
-  const settingsMeta = mkMeta(opts, "Get or update account settings (notifications, language, theme, privacy).", `{ settings: { notifications: true, language: 'en', theme: 'system' } }`);
-  const settingsContent = ts ? `${RA}${rr2}import type { Request, Response } from 'express';
+  const settingsMeta = mkMeta(opts, {
+    GET: { description: "Get account settings (notifications, language, theme, privacy) for the authenticated user.", response: `{ settings: { notifications: true, language: 'en', theme: 'system', privacy: 'public' } }` },
+    PUT: { description: "Update account settings for the authenticated user.", request: `{ notifications: true, language: 'en', theme: 'system', privacy: 'public' }`, response: `{ message: 'Settings updated', settings: { notifications: true, language: 'en', theme: 'system', privacy: 'public' } }` }
+  });
+  const settingsContent = ts ? `${RA}import type { Request, Response } from 'express';
 ${settingsMeta}${mw2}
 export const GET = async (req: Request, res: Response) => {
   // TODO: fetch user settings from DB
@@ -1941,7 +2330,7 @@ export const PUT = async (req: Request, res: Response) => {
   // TODO: update user settings in DB
   res.json({ message: 'Settings updated', settings: { notifications, language, theme, privacy } });
 };
-` : `${RA}${rr2}${settingsMeta}${mw2}
+` : `${RA}${settingsMeta}${mw2}
 export const GET = async (req, res) => {
   // TODO: fetch user settings from DB
   res.json({ settings: { notifications: true, language: 'en', theme: 'system', privacy: 'public' } });
@@ -1954,8 +2343,11 @@ export const PUT = async (req, res) => {
 };
 `;
   await fs.outputFile(path.join(dest, "src", "api", "user", `settings.${ext}`), settingsContent);
-  const accountMeta = mkMeta(opts, "Delete account (DELETE) or download personal data (GET).", `{ message: 'Account deleted' }`);
-  const accountContent = ts ? `${RA}${rr2}import type { Request, Response } from 'express';
+  const accountMeta = mkMeta(opts, {
+    GET: { description: "Download a personal data export for the authenticated user.", response: `{ data: { user: { id: '1', role: 'user', email: 'user@example.com' }, exportedAt: '2026-01-01T00:00:00.000Z' } }` },
+    DELETE: { description: "Schedule the authenticated account for deletion (requires password confirmation).", request: `{ password: 'current' }`, response: `{ message: 'Account scheduled for deletion' }` }
+  });
+  const accountContent = ts ? `${RA}import type { Request, Response } from 'express';
 ${accountMeta}${mw2}
 export const GET = async (req: Request, res: Response) => {
   // TODO: compile and return personal data export
@@ -1968,7 +2360,7 @@ export const DELETE = async (req: Request, res: Response) => {
   // TODO: verify password, schedule account deletion
   res.json({ message: 'Account scheduled for deletion' });
 };
-` : `${RA}${rr2}${accountMeta}${mw2}
+` : `${RA}${accountMeta}${mw2}
 export const GET = async (req, res) => {
   // TODO: compile and return personal data export
   res.json({ data: { user: ${user}, exportedAt: new Date().toISOString() } });
@@ -1982,29 +2374,33 @@ export const DELETE = async (req, res) => {
 };
 `;
   await fs.outputFile(path.join(dest, "src", "api", "user", `account.${ext}`), accountContent);
-  const dashMeta = mkMeta(opts, "Personal dashboard: stats, recent activity, and quick actions.", `{ stats: {}, recentActivity: [], quickActions: [] }`);
-  const dashContent = ts ? `${RA}${rr2}import type { Request, Response } from 'express';
+  const dashMeta = mkMeta(opts, {
+    GET: { description: "Personal dashboard: stats, recent activity, and quick actions.", response: `{ stats: {}, recentActivity: [], quickActions: [] }` }
+  });
+  const dashContent = ts ? `${RA}import type { Request, Response } from 'express';
 ${dashMeta}${mw2}
 export const GET = async (req: Request, res: Response) => {
   // TODO: aggregate personal stats and activity
   res.json({ stats: {}, recentActivity: [], quickActions: [] });
 };
-` : `${RA}${rr2}${dashMeta}${mw2}
+` : `${RA}${dashMeta}${mw2}
 export const GET = async (req, res) => {
   // TODO: aggregate personal stats and activity
   res.json({ stats: {}, recentActivity: [], quickActions: [] });
 };
 `;
   await fs.outputFile(path.join(dest, "src", "api", "user", `dashboard.${ext}`), dashContent);
-  const actMeta = mkMeta(opts, "Paginated activity history for the authenticated user.", `{ activities: [], total: 0, page: 1, limit: 20 }`);
-  const actContent = ts ? `${RA}${rr2}import type { Request, Response } from 'express';
+  const actMeta = mkMeta(opts, {
+    GET: { description: "Paginated activity history for the authenticated user.", query: `{ page: '1', limit: '20' }`, response: `{ activities: [], total: 0, page: 1, limit: 20 }` }
+  });
+  const actContent = ts ? `${RA}import type { Request, Response } from 'express';
 ${actMeta}${mw2}
 export const GET = async (req: Request, res: Response) => {
   const { page = 1, limit = 20 } = req.query;
   // TODO: fetch paginated activity log
   res.json({ activities: [], total: 0, page: Number(page), limit: Number(limit) });
 };
-` : `${RA}${rr2}${actMeta}${mw2}
+` : `${RA}${actMeta}${mw2}
 export const GET = async (req, res) => {
   const { page = 1, limit = 20 } = req.query;
   // TODO: fetch paginated activity log
@@ -2012,8 +2408,11 @@ export const GET = async (req, res) => {
 };
 `;
   await fs.outputFile(path.join(dest, "src", "api", "user", `activity.${ext}`), actContent);
-  const notifListMeta = mkMeta(opts, "List notifications (GET) or mark all as read (POST).", `{ notifications: [], total: 0, unread: 0 }`);
-  const notifListContent = ts ? `${RA}${rr3}import type { Request, Response } from 'express';
+  const notifListMeta = mkMeta(opts, {
+    GET: { description: "List notifications for the authenticated user.", response: `{ notifications: [], total: 0, unread: 0 }` },
+    POST: { description: "Mark all notifications as read for the authenticated user.", response: `{ message: 'All notifications marked as read' }` }
+  });
+  const notifListContent = ts ? `${RA}import type { Request, Response } from 'express';
 ${notifListMeta}${mw3}
 export const GET = async (req: Request, res: Response) => {
   // TODO: fetch notifications for user
@@ -2024,7 +2423,7 @@ export const POST = async (req: Request, res: Response) => {
   // TODO: mark all notifications as read
   res.json({ message: 'All notifications marked as read' });
 };
-` : `${RA}${rr3}${notifListMeta}${mw3}
+` : `${RA}${notifListMeta}${mw3}
 export const GET = async (req, res) => {
   // TODO: fetch notifications for user
   res.json({ notifications: [], total: 0, unread: 0 });
@@ -2036,8 +2435,13 @@ export const POST = async (req, res) => {
 };
 `;
   await fs.outputFile(path.join(dest, "src", "api", "user", "notifications", `index.${ext}`), notifListContent);
-  const notifByIdContent = ts ? `${RA}${rr3}import type { Request, Response } from 'express';
-${mw3}
+  const notifByIdMeta = mkMeta(opts, {
+    GET: { description: "Fetch a single notification by ID.", params: `{ id: 'notif_01HXZ' }`, response: `{ notification: { id: 'notif_01HXZ' } }` },
+    PATCH: { description: "Mark a single notification as read.", params: `{ id: 'notif_01HXZ' }`, response: `{ message: 'Notification marked as read', id: 'notif_01HXZ' }` },
+    DELETE: { description: "Delete a single notification.", params: `{ id: 'notif_01HXZ' }`, response: `{ message: 'Notification notif_01HXZ deleted' }` }
+  });
+  const notifByIdContent = ts ? `${RA}import type { Request, Response } from 'express';
+${notifByIdMeta}${mw3}
 export const GET = async (req: Request, res: Response) => {
   const { id } = req.params;
   // TODO: fetch notification by id
@@ -2055,7 +2459,7 @@ export const DELETE = async (req: Request, res: Response) => {
   // TODO: delete notification
   res.json({ message: \`Notification \${id} deleted\` });
 };
-` : `${RA}${rr3}${mw3}
+` : `${RA}${notifByIdMeta}${mw3}
 export const GET = async (req, res) => {
   const { id } = req.params;
   // TODO: fetch notification by id
@@ -2075,8 +2479,11 @@ export const DELETE = async (req, res) => {
 };
 `;
   await fs.outputFile(path.join(dest, "src", "api", "user", "notifications", `[id].${ext}`), notifByIdContent);
-  const filesListMeta = mkMeta(opts, "List uploaded files with storage usage (GET) or upload a new file (POST).", `{ files: [], total: 0, storageUsed: 0 }`);
-  const filesListContent = ts ? `${RA}${rr3}import type { Request, Response } from 'express';
+  const filesListMeta = mkMeta(opts, {
+    GET: { description: "List uploaded files with storage usage for the authenticated user.", response: `{ files: [], total: 0, storageUsed: 0 }` },
+    POST: { description: "Upload a new file for the authenticated user.", response: `{ message: 'File uploaded', file: { id: 'new-id' } }`, status: 201 }
+  });
+  const filesListContent = ts ? `${RA}import type { Request, Response } from 'express';
 ${filesListMeta}${mw3}
 export const GET = async (req: Request, res: Response) => {
   // TODO: fetch user files and compute storage usage
@@ -2087,7 +2494,7 @@ export const POST = async (req: Request, res: Response) => {
   // TODO: handle multipart upload, persist file record
   res.status(201).json({ message: 'File uploaded', file: { id: 'new-id' } });
 };
-` : `${RA}${rr3}${filesListMeta}${mw3}
+` : `${RA}${filesListMeta}${mw3}
 export const GET = async (req, res) => {
   // TODO: fetch user files and compute storage usage
   res.json({ files: [], total: 0, storageUsed: 0 });
@@ -2099,8 +2506,12 @@ export const POST = async (req, res) => {
 };
 `;
   await fs.outputFile(path.join(dest, "src", "api", "user", "files", `index.${ext}`), filesListContent);
-  const fileByIdContent = ts ? `${RA}${rr3}import type { Request, Response } from 'express';
-${mw3}
+  const fileByIdMeta = mkMeta(opts, {
+    GET: { description: "Get a download/preview URL for a single file by ID.", params: `{ id: 'file_01HXZ' }`, response: `{ file: { id: 'file_01HXZ', url: 'https://example.com/files/file_01HXZ' } }` },
+    DELETE: { description: "Delete a file from storage.", params: `{ id: 'file_01HXZ' }`, response: `{ message: 'File file_01HXZ deleted' }` }
+  });
+  const fileByIdContent = ts ? `${RA}import type { Request, Response } from 'express';
+${fileByIdMeta}${mw3}
 export const GET = async (req: Request, res: Response) => {
   const { id } = req.params;
   // TODO: stream or redirect to file download/preview URL
@@ -2112,7 +2523,7 @@ export const DELETE = async (req: Request, res: Response) => {
   // TODO: delete file from storage and DB
   res.json({ message: \`File \${id} deleted\` });
 };
-` : `${RA}${rr3}${mw3}
+` : `${RA}${fileByIdMeta}${mw3}
 export const GET = async (req, res) => {
   const { id } = req.params;
   // TODO: stream or redirect to file download/preview URL
@@ -2126,8 +2537,12 @@ export const DELETE = async (req, res) => {
 };
 `;
   await fs.outputFile(path.join(dest, "src", "api", "user", "files", `[id].${ext}`), fileByIdContent);
-  const favListContent = ts ? `${RA}${rr3}import type { Request, Response } from 'express';
-${mw3}
+  const favListMeta = mkMeta(opts, {
+    GET: { description: "List favorites for the authenticated user.", response: `{ favorites: [] }` },
+    POST: { description: "Add an entity to the authenticated user's favorites.", request: `{ entityId: 'post_01HXZ', entityType: 'post' }`, response: `{ message: 'Added to favorites' }`, status: 201 }
+  });
+  const favListContent = ts ? `${RA}import type { Request, Response } from 'express';
+${favListMeta}${mw3}
 export const GET = async (req: Request, res: Response) => {
   // TODO: fetch user favorites
   res.json({ favorites: [] });
@@ -2139,7 +2554,7 @@ export const POST = async (req: Request, res: Response) => {
   // TODO: add to favorites
   res.status(201).json({ message: 'Added to favorites' });
 };
-` : `${RA}${rr3}${mw3}
+` : `${RA}${favListMeta}${mw3}
 export const GET = async (req, res) => {
   // TODO: fetch user favorites
   res.json({ favorites: [] });
@@ -2153,14 +2568,17 @@ export const POST = async (req, res) => {
 };
 `;
   await fs.outputFile(path.join(dest, "src", "api", "user", "favorites", `index.${ext}`), favListContent);
-  const favByIdContent = ts ? `${RA}${rr3}import type { Request, Response } from 'express';
-${mw3}
+  const favByIdMeta = mkMeta(opts, {
+    DELETE: { description: "Remove an entity from the authenticated user favorites.", params: `{ id: 'fav_01HXZ' }`, response: `{ message: 'Removed favorite fav_01HXZ' }` }
+  });
+  const favByIdContent = ts ? `${RA}import type { Request, Response } from 'express';
+${favByIdMeta}${mw3}
 export const DELETE = async (req: Request, res: Response) => {
   const { id } = req.params;
   // TODO: remove from favorites
   res.json({ message: \`Removed favorite \${id}\` });
 };
-` : `${RA}${rr3}${mw3}
+` : `${RA}${favByIdMeta}${mw3}
 export const DELETE = async (req, res) => {
   const { id } = req.params;
   // TODO: remove from favorites
@@ -2168,8 +2586,12 @@ export const DELETE = async (req, res) => {
 };
 `;
   await fs.outputFile(path.join(dest, "src", "api", "user", "favorites", `[id].${ext}`), favByIdContent);
-  const bkListContent = ts ? `${RA}${rr3}import type { Request, Response } from 'express';
-${mw3}
+  const bkListMeta = mkMeta(opts, {
+    GET: { description: "List bookmarks for the authenticated user.", response: `{ bookmarks: [] }` },
+    POST: { description: "Save a new bookmark for the authenticated user.", request: `{ url: 'https://example.com', title: 'Example' }`, response: `{ message: 'Bookmark saved' }`, status: 201 }
+  });
+  const bkListContent = ts ? `${RA}import type { Request, Response } from 'express';
+${bkListMeta}${mw3}
 export const GET = async (req: Request, res: Response) => {
   // TODO: fetch user bookmarks
   res.json({ bookmarks: [] });
@@ -2181,7 +2603,7 @@ export const POST = async (req: Request, res: Response) => {
   // TODO: save bookmark
   res.status(201).json({ message: 'Bookmark saved' });
 };
-` : `${RA}${rr3}${mw3}
+` : `${RA}${bkListMeta}${mw3}
 export const GET = async (req, res) => {
   // TODO: fetch user bookmarks
   res.json({ bookmarks: [] });
@@ -2195,14 +2617,17 @@ export const POST = async (req, res) => {
 };
 `;
   await fs.outputFile(path.join(dest, "src", "api", "user", "bookmarks", `index.${ext}`), bkListContent);
-  const bkByIdContent = ts ? `${RA}${rr3}import type { Request, Response } from 'express';
-${mw3}
+  const bkByIdMeta = mkMeta(opts, {
+    DELETE: { description: "Delete a bookmark by ID.", params: `{ id: 'bm_01HXZ' }`, response: `{ message: 'Bookmark bm_01HXZ removed' }` }
+  });
+  const bkByIdContent = ts ? `${RA}import type { Request, Response } from 'express';
+${bkByIdMeta}${mw3}
 export const DELETE = async (req: Request, res: Response) => {
   const { id } = req.params;
   // TODO: delete bookmark
   res.json({ message: \`Bookmark \${id} removed\` });
 };
-` : `${RA}${rr3}${mw3}
+` : `${RA}${bkByIdMeta}${mw3}
 export const DELETE = async (req, res) => {
   const { id } = req.params;
   // TODO: delete bookmark
@@ -2210,15 +2635,17 @@ export const DELETE = async (req, res) => {
 };
 `;
   await fs.outputFile(path.join(dest, "src", "api", "user", "bookmarks", `[id].${ext}`), bkByIdContent);
-  const searchMeta = mkMeta(opts, "Search with filters, sort, and pagination.", `{ results: [], total: 0, page: 1, limit: 20 }`);
-  const searchContent = ts ? `${RA}${rr2}import type { Request, Response } from 'express';
+  const searchMeta = mkMeta(opts, {
+    GET: { description: "Search with filters, sort, and pagination.", query: `{ q: 'query', filter: 'active', sort: 'newest', page: '1', limit: '20' }`, response: `{ results: [], total: 0, page: 1, limit: 20 }` }
+  });
+  const searchContent = ts ? `${RA}import type { Request, Response } from 'express';
 ${searchMeta}${mw2}
 export const GET = async (req: Request, res: Response) => {
   const { q, filter, sort, page = 1, limit = 20 } = req.query;
   // TODO: implement search
   res.json({ results: [], total: 0, page: Number(page), limit: Number(limit) });
 };
-` : `${RA}${rr2}${searchMeta}${mw2}
+` : `${RA}${searchMeta}${mw2}
 export const GET = async (req, res) => {
   const { q, filter, sort, page = 1, limit = 20 } = req.query;
   // TODO: implement search
@@ -2226,8 +2653,11 @@ export const GET = async (req, res) => {
 };
 `;
   await fs.outputFile(path.join(dest, "src", "api", "user", `search.${ext}`), searchContent);
-  const akListMeta = mkMeta(opts, "List API keys (GET) or create a new one (POST).", `{ apiKeys: [] }`);
-  const akListContent = ts ? `${RA}${rr3}import type { Request, Response } from 'express';
+  const akListMeta = mkMeta(opts, {
+    GET: { description: "List API keys for the authenticated user.", response: `{ apiKeys: [] }` },
+    POST: { description: "Generate a new API key for the authenticated user.", request: `{ name: 'CI key' }`, response: `{ message: 'API key created', key: 'efc_...' }`, status: 201 }
+  });
+  const akListContent = ts ? `${RA}import type { Request, Response } from 'express';
 ${akListMeta}${mw3}
 export const GET = async (req: Request, res: Response) => {
   // TODO: fetch api keys for user
@@ -2240,7 +2670,7 @@ export const POST = async (req: Request, res: Response) => {
   // TODO: generate and store API key
   res.status(201).json({ message: 'API key created', key: 'efc_...' });
 };
-` : `${RA}${rr3}${akListMeta}${mw3}
+` : `${RA}${akListMeta}${mw3}
 export const GET = async (req, res) => {
   // TODO: fetch api keys for user
   res.json({ apiKeys: [] });
@@ -2254,14 +2684,17 @@ export const POST = async (req, res) => {
 };
 `;
   await fs.outputFile(path.join(dest, "src", "api", "user", "api-keys", `index.${ext}`), akListContent);
-  const akByIdContent = ts ? `${RA}${rr3}import type { Request, Response } from 'express';
-${mw3}
+  const akByIdMeta = mkMeta(opts, {
+    DELETE: { description: "Revoke and delete an API key by ID.", params: `{ id: 'key_01HXZ' }`, response: `{ message: 'API key key_01HXZ revoked' }` }
+  });
+  const akByIdContent = ts ? `${RA}import type { Request, Response } from 'express';
+${akByIdMeta}${mw3}
 export const DELETE = async (req: Request, res: Response) => {
   const { id } = req.params;
   // TODO: revoke and delete API key
   res.json({ message: \`API key \${id} revoked\` });
 };
-` : `${RA}${rr3}${mw3}
+` : `${RA}${akByIdMeta}${mw3}
 export const DELETE = async (req, res) => {
   const { id } = req.params;
   // TODO: revoke and delete API key
@@ -2273,32 +2706,34 @@ export const DELETE = async (req, res) => {
 async function writeUserBillingRoutes(dest, opts) {
   const ext = opts.language === "typescript" ? "ts" : "js";
   const ts = opts.language === "typescript";
-  const rr3 = opts.rbac ? `import { requireRole } from '../../../middleware/requireRole.js';
-` : "";
-  const rr4 = opts.rbac ? `import { requireRole } from '../../../../middleware/requireRole.js';
-` : "";
-  const mw3 = opts.rbac ? `export const middlewares = [requireAuth, requireRole('user', 'admin')];
+  const mw3 = opts.rbac ? `export const middlewares = [requireAuth('user', 'admin')];
 ` : `export const middlewares = [requireAuth];
 `;
   const mw4 = mw3;
   const RA = `import { requireAuth } from 'express-file-cluster/auth';
 `;
-  const plansMeta = mkMeta(opts, "List all available subscription plans.", `{ plans: [] }`);
-  const plansContent = ts ? `${RA}${rr3}import type { Request, Response } from 'express';
+  const plansMeta = mkMeta(opts, {
+    GET: { description: "List all available subscription plans.", response: `{ plans: [] }` }
+  });
+  const plansContent = ts ? `${RA}import type { Request, Response } from 'express';
 ${plansMeta}${mw3}
 export const GET = async (_req: Request, res: Response) => {
   // TODO: fetch active plans from DB
   res.json({ plans: [] });
 };
-` : `${RA}${rr3}${plansMeta}${mw3}
+` : `${RA}${plansMeta}${mw3}
 export const GET = async (_req, res) => {
   // TODO: fetch active plans from DB
   res.json({ plans: [] });
 };
 `;
   await fs.outputFile(path.join(dest, "src", "api", "user", "billing", `plans.${ext}`), plansContent);
-  const subMeta = mkMeta(opts, "Get current subscription (GET), subscribe to a plan (POST), or cancel (DELETE).", `{ subscription: null }`);
-  const subContent = ts ? `${RA}${rr3}import type { Request, Response } from 'express';
+  const subMeta = mkMeta(opts, {
+    GET: { description: "Get the current subscription for the authenticated user.", response: `{ subscription: null }` },
+    POST: { description: "Subscribe the authenticated user to a plan.", request: `{ planId: 'plan_01HXZ' }`, response: `{ message: 'Subscribed', subscription: { planId: 'plan_01HXZ' } }`, status: 201 },
+    DELETE: { description: "Cancel the current subscription at period end.", response: `{ message: 'Subscription cancelled' }` }
+  });
+  const subContent = ts ? `${RA}import type { Request, Response } from 'express';
 ${subMeta}${mw3}
 export const GET = async (req: Request, res: Response) => {
   // TODO: fetch current subscription for user
@@ -2316,7 +2751,7 @@ export const DELETE = async (req: Request, res: Response) => {
   // TODO: cancel subscription at period end
   res.json({ message: 'Subscription cancelled' });
 };
-` : `${RA}${rr3}${subMeta}${mw3}
+` : `${RA}${subMeta}${mw3}
 export const GET = async (req, res) => {
   // TODO: fetch current subscription for user
   res.json({ subscription: null });
@@ -2335,8 +2770,12 @@ export const DELETE = async (req, res) => {
 };
 `;
   await fs.outputFile(path.join(dest, "src", "api", "user", "billing", `subscription.${ext}`), subContent);
-  const pmListContent = ts ? `${RA}${rr4}import type { Request, Response } from 'express';
-${mw4}
+  const pmListMeta = mkMeta(opts, {
+    GET: { description: "List payment methods for the authenticated user.", response: `{ paymentMethods: [] }` },
+    POST: { description: "Attach a new payment method via the payment gateway.", request: `{ token: 'tok_...' }`, response: `{ message: 'Payment method added' }`, status: 201 }
+  });
+  const pmListContent = ts ? `${RA}import type { Request, Response } from 'express';
+${pmListMeta}${mw4}
 export const GET = async (req: Request, res: Response) => {
   // TODO: fetch payment methods for user
   res.json({ paymentMethods: [] });
@@ -2348,7 +2787,7 @@ export const POST = async (req: Request, res: Response) => {
   // TODO: attach payment method via payment gateway
   res.status(201).json({ message: 'Payment method added' });
 };
-` : `${RA}${rr4}${mw4}
+` : `${RA}${pmListMeta}${mw4}
 export const GET = async (req, res) => {
   // TODO: fetch payment methods for user
   res.json({ paymentMethods: [] });
@@ -2362,14 +2801,17 @@ export const POST = async (req, res) => {
 };
 `;
   await fs.outputFile(path.join(dest, "src", "api", "user", "billing", "payment-methods", `index.${ext}`), pmListContent);
-  const pmByIdContent = ts ? `${RA}${rr4}import type { Request, Response } from 'express';
-${mw4}
+  const pmByIdMeta = mkMeta(opts, {
+    DELETE: { description: "Detach a payment method from the payment gateway.", params: `{ id: 'pm_01HXZ' }`, response: `{ message: 'Payment method pm_01HXZ removed' }` }
+  });
+  const pmByIdContent = ts ? `${RA}import type { Request, Response } from 'express';
+${pmByIdMeta}${mw4}
 export const DELETE = async (req: Request, res: Response) => {
   const { id } = req.params;
   // TODO: detach payment method from payment gateway
   res.json({ message: \`Payment method \${id} removed\` });
 };
-` : `${RA}${rr4}${mw4}
+` : `${RA}${pmByIdMeta}${mw4}
 export const DELETE = async (req, res) => {
   const { id } = req.params;
   // TODO: detach payment method from payment gateway
@@ -2377,28 +2819,33 @@ export const DELETE = async (req, res) => {
 };
 `;
   await fs.outputFile(path.join(dest, "src", "api", "user", "billing", "payment-methods", `[id].${ext}`), pmByIdContent);
-  const invListMeta = mkMeta(opts, "List all invoices for the authenticated user.", `{ invoices: [], total: 0 }`);
-  const invListContent = ts ? `${RA}${rr4}import type { Request, Response } from 'express';
+  const invListMeta = mkMeta(opts, {
+    GET: { description: "List all invoices for the authenticated user.", response: `{ invoices: [], total: 0 }` }
+  });
+  const invListContent = ts ? `${RA}import type { Request, Response } from 'express';
 ${invListMeta}${mw4}
 export const GET = async (req: Request, res: Response) => {
   // TODO: fetch invoices for user
   res.json({ invoices: [], total: 0 });
 };
-` : `${RA}${rr4}${invListMeta}${mw4}
+` : `${RA}${invListMeta}${mw4}
 export const GET = async (req, res) => {
   // TODO: fetch invoices for user
   res.json({ invoices: [], total: 0 });
 };
 `;
   await fs.outputFile(path.join(dest, "src", "api", "user", "billing", "invoices", `index.${ext}`), invListContent);
-  const invByIdContent = ts ? `${RA}${rr4}import type { Request, Response } from 'express';
-${mw4}
+  const invByIdMeta = mkMeta(opts, {
+    GET: { description: "Get the download URL for a single invoice by ID.", params: `{ id: 'inv_01HXZ' }`, response: `{ invoice: { id: 'inv_01HXZ', downloadUrl: 'https://example.com/invoices/inv_01HXZ.pdf' } }` }
+  });
+  const invByIdContent = ts ? `${RA}import type { Request, Response } from 'express';
+${invByIdMeta}${mw4}
 export const GET = async (req: Request, res: Response) => {
   const { id } = req.params;
   // TODO: return invoice PDF URL or inline data
   res.json({ invoice: { id, downloadUrl: 'https://...' } });
 };
-` : `${RA}${rr4}${mw4}
+` : `${RA}${invByIdMeta}${mw4}
 export const GET = async (req, res) => {
   const { id } = req.params;
   // TODO: return invoice PDF URL or inline data
@@ -2410,15 +2857,16 @@ export const GET = async (req, res) => {
 async function writeSupportRoutes(dest, opts) {
   const ext = opts.language === "typescript" ? "ts" : "js";
   const ts = opts.language === "typescript";
-  const rr3 = opts.rbac ? `import { requireRole } from '../../../middleware/requireRole.js';
-` : "";
-  const mw3 = opts.rbac ? `export const middlewares = [requireAuth, requireRole('user', 'admin')];
+  const mw3 = opts.rbac ? `export const middlewares = [requireAuth('user', 'admin')];
 ` : `export const middlewares = [requireAuth];
 `;
   const RA = `import { requireAuth } from 'express-file-cluster/auth';
 `;
-  const ticketListMeta = mkMeta(opts, "List own support tickets (GET) or create a new one (POST).", `{ tickets: [], total: 0 }`, `{ subject: 'Issue with login', message: 'I cannot log in', priority: 'normal' }`);
-  const ticketListContent = ts ? `${RA}${rr3}import type { Request, Response } from 'express';
+  const ticketListMeta = mkMeta(opts, {
+    GET: { description: "List the authenticated user's own support tickets.", response: `{ tickets: [], total: 0 }` },
+    POST: { description: "Create a new support ticket.", request: `{ subject: 'Issue with login', message: 'I cannot log in', priority: 'normal' }`, response: `{ message: 'Ticket created', ticket: { id: 'new-id', subject: 'Issue with login', status: 'open' } }`, status: 201 }
+  });
+  const ticketListContent = ts ? `${RA}import type { Request, Response } from 'express';
 ${ticketListMeta}${mw3}
 export const GET = async (req: Request, res: Response) => {
   // TODO: fetch tickets for current user
@@ -2431,7 +2879,7 @@ export const POST = async (req: Request, res: Response) => {
   // TODO: create support ticket in DB
   res.status(201).json({ message: 'Ticket created', ticket: { id: 'new-id', subject, status: 'open' } });
 };
-` : `${RA}${rr3}${ticketListMeta}${mw3}
+` : `${RA}${ticketListMeta}${mw3}
 export const GET = async (req, res) => {
   // TODO: fetch tickets for current user
   res.json({ tickets: [], total: 0 });
@@ -2445,8 +2893,11 @@ export const POST = async (req, res) => {
 };
 `;
   await fs.outputFile(path.join(dest, "src", "api", "support", "tickets", `index.${ext}`), ticketListContent);
-  const ticketByIdMeta = mkMeta(opts, "View a support ticket (GET) or add a reply / close it (PUT).", `{ ticket: { id: '1', subject: 'Issue', status: 'open', replies: [] } }`);
-  const ticketByIdContent = ts ? `${RA}${rr3}import type { Request, Response } from 'express';
+  const ticketByIdMeta = mkMeta(opts, {
+    GET: { description: "Fetch a single support ticket by ID.", params: `{ id: 'tk_01HXZ' }`, response: `{ ticket: { id: 'tk_01HXZ', subject: 'Issue', status: 'open', replies: [] } }` },
+    PUT: { description: "Add a reply to a support ticket or update its status.", params: `{ id: 'tk_01HXZ' }`, request: `{ reply: 'Thanks, resolved.', status: 'closed' }`, response: `{ message: 'Ticket updated', ticket: { id: 'tk_01HXZ', status: 'closed' } }` }
+  });
+  const ticketByIdContent = ts ? `${RA}import type { Request, Response } from 'express';
 ${ticketByIdMeta}${mw3}
 export const GET = async (req: Request, res: Response) => {
   const { id } = req.params;
@@ -2460,7 +2911,7 @@ export const PUT = async (req: Request, res: Response) => {
   // TODO: add reply or update status
   res.json({ message: 'Ticket updated', ticket: { id, status: status ?? 'open' } });
 };
-` : `${RA}${rr3}${ticketByIdMeta}${mw3}
+` : `${RA}${ticketByIdMeta}${mw3}
 export const GET = async (req, res) => {
   const { id } = req.params;
   // TODO: fetch ticket by id, verify ownership
@@ -2479,11 +2930,7 @@ export const PUT = async (req, res) => {
 async function writeAdminExtendedRoutes(dest, opts) {
   const ext = opts.language === "typescript" ? "ts" : "js";
   const ts = opts.language === "typescript";
-  const rr3 = opts.rbac ? `import { requireRole } from '../../../middleware/requireRole.js';
-` : "";
-  const rr4 = opts.rbac ? `import { requireRole } from '../../../../middleware/requireRole.js';
-` : "";
-  const mwAdmin3 = opts.rbac ? `export const middlewares = [requireAuth, requireRole('admin')];
+  const mwAdmin3 = opts.rbac ? `export const middlewares = [requireAuth('admin')];
 ` : `export const middlewares = [requireAuth];
 `;
   const mwAdmin4 = mwAdmin3;
@@ -2494,29 +2941,33 @@ async function writeAdminExtendedRoutes(dest, opts) {
 `;
   const RA = `import { requireAuth } from 'express-file-cluster/auth';
 `;
-  const analyticsOverviewMeta = mkMeta(opts, "Analytics overview: users, revenue, traffic.", `{ users: {}, revenue: {}, traffic: {} }`);
-  const analyticsOverviewContent = ts ? `${RA}${rr3}import type { Request, Response } from 'express';
+  const analyticsOverviewMeta = mkMeta(opts, {
+    GET: { description: "Analytics overview: users, revenue, traffic (admin only).", response: `{ users: {}, revenue: {}, traffic: {} }` }
+  });
+  const analyticsOverviewContent = ts ? `${RA}import type { Request, Response } from 'express';
 ${analyticsOverviewMeta}${mwAdmin3}
 export const GET = async (req: Request, res: Response) => {
 ${roleGuard}  // TODO: aggregate analytics overview
   res.json({ users: {}, revenue: {}, traffic: {} });
 };
-` : `${RA}${rr3}${analyticsOverviewMeta}${mwAdmin3}
+` : `${RA}${analyticsOverviewMeta}${mwAdmin3}
 export const GET = async (req, res) => {
 ${roleGuard}  // TODO: aggregate analytics overview
   res.json({ users: {}, revenue: {}, traffic: {} });
 };
 `;
   await fs.outputFile(path.join(dest, "src", "api", "admin", "analytics", `index.${ext}`), analyticsOverviewContent);
-  const analyticsUsersMeta = mkMeta(opts, "User analytics: registrations, active users, churn.", `{ registrations: [], activeUsers: 0, churn: 0 }`);
-  const analyticsUsersContent = ts ? `${RA}${rr3}import type { Request, Response } from 'express';
+  const analyticsUsersMeta = mkMeta(opts, {
+    GET: { description: "User analytics: registrations, active users, churn (admin only).", query: `{ period: '30d' }`, response: `{ registrations: [], activeUsers: 0, churn: 0, period: '30d' }` }
+  });
+  const analyticsUsersContent = ts ? `${RA}import type { Request, Response } from 'express';
 ${analyticsUsersMeta}${mwAdmin3}
 export const GET = async (req: Request, res: Response) => {
 ${roleGuard}  const { period = '30d' } = req.query;
   // TODO: fetch user analytics for period
   res.json({ registrations: [], activeUsers: 0, churn: 0, period });
 };
-` : `${RA}${rr3}${analyticsUsersMeta}${mwAdmin3}
+` : `${RA}${analyticsUsersMeta}${mwAdmin3}
 export const GET = async (req, res) => {
 ${roleGuard}  const { period = '30d' } = req.query;
   // TODO: fetch user analytics for period
@@ -2524,15 +2975,17 @@ ${roleGuard}  const { period = '30d' } = req.query;
 };
 `;
   await fs.outputFile(path.join(dest, "src", "api", "admin", "analytics", `users.${ext}`), analyticsUsersContent);
-  const analyticsRevenueMeta = mkMeta(opts, "Revenue analytics: MRR, ARR, payment history.", `{ mrr: 0, arr: 0, history: [] }`);
-  const analyticsRevenueContent = ts ? `${RA}${rr3}import type { Request, Response } from 'express';
+  const analyticsRevenueMeta = mkMeta(opts, {
+    GET: { description: "Revenue analytics: MRR, ARR, payment history (admin only).", query: `{ period: '30d' }`, response: `{ mrr: 0, arr: 0, history: [], period: '30d' }` }
+  });
+  const analyticsRevenueContent = ts ? `${RA}import type { Request, Response } from 'express';
 ${analyticsRevenueMeta}${mwAdmin3}
 export const GET = async (req: Request, res: Response) => {
 ${roleGuard}  const { period = '30d' } = req.query;
   // TODO: fetch revenue analytics for period
   res.json({ mrr: 0, arr: 0, history: [], period });
 };
-` : `${RA}${rr3}${analyticsRevenueMeta}${mwAdmin3}
+` : `${RA}${analyticsRevenueMeta}${mwAdmin3}
 export const GET = async (req, res) => {
 ${roleGuard}  const { period = '30d' } = req.query;
   // TODO: fetch revenue analytics for period
@@ -2540,15 +2993,17 @@ ${roleGuard}  const { period = '30d' } = req.query;
 };
 `;
   await fs.outputFile(path.join(dest, "src", "api", "admin", "analytics", `revenue.${ext}`), analyticsRevenueContent);
-  const analyticsTrafficMeta = mkMeta(opts, "Traffic analytics: page views, devices, countries.", `{ pageViews: 0, devices: {}, countries: {} }`);
-  const analyticsTrafficContent = ts ? `${RA}${rr3}import type { Request, Response } from 'express';
+  const analyticsTrafficMeta = mkMeta(opts, {
+    GET: { description: "Traffic analytics: page views, devices, countries (admin only).", query: `{ period: '30d' }`, response: `{ pageViews: 0, devices: {}, countries: {}, period: '30d' }` }
+  });
+  const analyticsTrafficContent = ts ? `${RA}import type { Request, Response } from 'express';
 ${analyticsTrafficMeta}${mwAdmin3}
 export const GET = async (req: Request, res: Response) => {
 ${roleGuard}  const { period = '30d' } = req.query;
   // TODO: fetch traffic analytics for period
   res.json({ pageViews: 0, devices: {}, countries: {}, period });
 };
-` : `${RA}${rr3}${analyticsTrafficMeta}${mwAdmin3}
+` : `${RA}${analyticsTrafficMeta}${mwAdmin3}
 export const GET = async (req, res) => {
 ${roleGuard}  const { period = '30d' } = req.query;
   // TODO: fetch traffic analytics for period
@@ -2556,15 +3011,18 @@ ${roleGuard}  const { period = '30d' } = req.query;
 };
 `;
   await fs.outputFile(path.join(dest, "src", "api", "admin", "analytics", `traffic.${ext}`), analyticsTrafficContent);
-  const suspendContent = ts ? `${RA}${rr4}import type { Request, Response } from 'express';
-${mwAdmin4}
+  const suspendMeta = mkMeta(opts, {
+    POST: { description: "Suspend a user account (admin only).", params: `{ id: 'usr_01HXZ' }`, request: `{ reason: 'Terms of service violation' }`, response: `{ message: 'User usr_01HXZ suspended', reason: 'Terms of service violation' }` }
+  });
+  const suspendContent = ts ? `${RA}import type { Request, Response } from 'express';
+${suspendMeta}${mwAdmin4}
 export const POST = async (req: Request, res: Response) => {
 ${roleGuard}  const { id } = req.params;
   const { reason } = req.body;
   // TODO: set user.isActive = false, log audit event
   res.json({ message: \`User \${id} suspended\`, reason });
 };
-` : `${RA}${rr4}${mwAdmin4}
+` : `${RA}${suspendMeta}${mwAdmin4}
 export const POST = async (req, res) => {
 ${roleGuard}  const { id } = req.params;
   const { reason } = req.body;
@@ -2573,14 +3031,17 @@ ${roleGuard}  const { id } = req.params;
 };
 `;
   await fs.outputFile(path.join(dest, "src", "api", "admin", "users", "[id]", `suspend.${ext}`), suspendContent);
-  const activateContent = ts ? `${RA}${rr4}import type { Request, Response } from 'express';
-${mwAdmin4}
+  const activateMeta = mkMeta(opts, {
+    POST: { description: "Reactivate a suspended user account (admin only).", params: `{ id: 'usr_01HXZ' }`, response: `{ message: 'User usr_01HXZ activated' }` }
+  });
+  const activateContent = ts ? `${RA}import type { Request, Response } from 'express';
+${activateMeta}${mwAdmin4}
 export const POST = async (req: Request, res: Response) => {
 ${roleGuard}  const { id } = req.params;
   // TODO: set user.isActive = true, log audit event
   res.json({ message: \`User \${id} activated\` });
 };
-` : `${RA}${rr4}${mwAdmin4}
+` : `${RA}${activateMeta}${mwAdmin4}
 export const POST = async (req, res) => {
 ${roleGuard}  const { id } = req.params;
   // TODO: set user.isActive = true, log audit event
@@ -2588,14 +3049,17 @@ ${roleGuard}  const { id } = req.params;
 };
 `;
   await fs.outputFile(path.join(dest, "src", "api", "admin", "users", "[id]", `activate.${ext}`), activateContent);
-  const verifyUserContent = ts ? `${RA}${rr4}import type { Request, Response } from 'express';
-${mwAdmin4}
+  const verifyUserMeta = mkMeta(opts, {
+    POST: { description: "Mark a user's email as verified (admin only).", params: `{ id: 'usr_01HXZ' }`, response: `{ message: 'User usr_01HXZ verified' }` }
+  });
+  const verifyUserContent = ts ? `${RA}import type { Request, Response } from 'express';
+${verifyUserMeta}${mwAdmin4}
 export const POST = async (req: Request, res: Response) => {
 ${roleGuard}  const { id } = req.params;
   // TODO: set user.isVerified = true
   res.json({ message: \`User \${id} verified\` });
 };
-` : `${RA}${rr4}${mwAdmin4}
+` : `${RA}${verifyUserMeta}${mwAdmin4}
 export const POST = async (req, res) => {
 ${roleGuard}  const { id } = req.params;
   // TODO: set user.isVerified = true
@@ -2603,8 +3067,10 @@ ${roleGuard}  const { id } = req.params;
 };
 `;
   await fs.outputFile(path.join(dest, "src", "api", "admin", "users", "[id]", `verify.${ext}`), verifyUserContent);
-  const exportMeta = mkMeta(opts, "Export all users as CSV.", `{ csv: '...' }`);
-  const exportContent = ts ? `${RA}${rr3}import type { Request, Response } from 'express';
+  const exportMeta = mkMeta(opts, {
+    GET: { description: "Export all users as a CSV download (admin only).", response: `'id,name,email,role,createdAt\\n'` }
+  });
+  const exportContent = ts ? `${RA}import type { Request, Response } from 'express';
 ${exportMeta}${mwAdmin3}
 export const GET = async (_req: Request, res: Response) => {
 ${roleGuard}  // TODO: generate CSV of all users and stream response
@@ -2612,7 +3078,7 @@ ${roleGuard}  // TODO: generate CSV of all users and stream response
   res.setHeader('Content-Disposition', 'attachment; filename="users.csv"');
   res.send('id,name,email,role,createdAt\\n');
 };
-` : `${RA}${rr3}${exportMeta}${mwAdmin3}
+` : `${RA}${exportMeta}${mwAdmin3}
 export const GET = async (_req, res) => {
 ${roleGuard}  // TODO: generate CSV of all users and stream response
   res.setHeader('Content-Type', 'text/csv');
@@ -2621,8 +3087,11 @@ ${roleGuard}  // TODO: generate CSV of all users and stream response
 };
 `;
   await fs.outputFile(path.join(dest, "src", "api", "admin", "users", `export.${ext}`), exportContent);
-  const adminsListMeta = mkMeta(opts, "List all admins (GET) or create a new admin (POST).", `{ admins: [], total: 0 }`);
-  const adminsListContent = ts ? `${RA}${rr3}import type { Request, Response } from 'express';
+  const adminsListMeta = mkMeta(opts, {
+    GET: { description: "List all admin accounts (admin only).", response: `{ admins: [], total: 0 }` },
+    POST: { description: "Create a new admin account (admin only).", request: `{ name: 'Jane Doe', email: 'jane@example.com', role: 'admin' }`, response: `{ message: 'Admin created', admin: { id: 'new-id', name: 'Jane Doe', email: 'jane@example.com', role: 'admin' } }`, status: 201 }
+  });
+  const adminsListContent = ts ? `${RA}import type { Request, Response } from 'express';
 ${adminsListMeta}${mwAdmin3}
 export const GET = async (_req: Request, res: Response) => {
 ${roleGuard}  // TODO: fetch admins from DB
@@ -2635,7 +3104,7 @@ ${roleGuard}  const { name, email, role } = req.body;
   // TODO: create admin account
   res.status(201).json({ message: 'Admin created', admin: { id: 'new-id', name, email, role: role ?? 'admin' } });
 };
-` : `${RA}${rr3}${adminsListMeta}${mwAdmin3}
+` : `${RA}${adminsListMeta}${mwAdmin3}
 export const GET = async (_req, res) => {
 ${roleGuard}  // TODO: fetch admins from DB
   res.json({ admins: [], total: 0 });
@@ -2649,8 +3118,13 @@ ${roleGuard}  const { name, email, role } = req.body;
 };
 `;
   await fs.outputFile(path.join(dest, "src", "api", "admin", "admins", `index.${ext}`), adminsListContent);
-  const adminByIdContent = ts ? `${RA}${rr3}import type { Request, Response } from 'express';
-${mwAdmin3}
+  const adminByIdMeta = mkMeta(opts, {
+    GET: { description: "Fetch a single admin account by ID (admin only).", params: `{ id: 'adm_01HXZ' }`, response: `{ admin: { id: 'adm_01HXZ' } }` },
+    PUT: { description: "Update an admin account by ID (admin only).", params: `{ id: 'adm_01HXZ' }`, request: `{ name: 'Jane Doe', role: 'admin' }`, response: `{ message: 'Admin updated', admin: { id: 'adm_01HXZ', name: 'Jane Doe', role: 'admin' } }` },
+    DELETE: { description: "Delete an admin account by ID (admin only).", params: `{ id: 'adm_01HXZ' }`, response: `{ message: 'Admin adm_01HXZ deleted' }` }
+  });
+  const adminByIdContent = ts ? `${RA}import type { Request, Response } from 'express';
+${adminByIdMeta}${mwAdmin3}
 export const GET = async (req: Request, res: Response) => {
 ${roleGuard}  const { id } = req.params;
   // TODO: fetch admin by id
@@ -2668,7 +3142,7 @@ ${roleGuard}  const { id } = req.params;
   // TODO: delete admin
   res.json({ message: \`Admin \${id} deleted\` });
 };
-` : `${RA}${rr3}${mwAdmin3}
+` : `${RA}${adminByIdMeta}${mwAdmin3}
 export const GET = async (req, res) => {
 ${roleGuard}  const { id } = req.params;
   // TODO: fetch admin by id
@@ -2689,8 +3163,12 @@ ${roleGuard}  const { id } = req.params;
 `;
   await fs.outputFile(path.join(dest, "src", "api", "admin", "admins", `[id].${ext}`), adminByIdContent);
   if (opts.rbac) {
-    const rolesListContent = ts ? `${RA}${rr3}import type { Request, Response } from 'express';
-${mwAdmin3}
+    const rolesListMeta = mkMeta(opts, {
+      GET: { description: "List all roles (admin only).", response: `{ roles: [] }` },
+      POST: { description: "Create a new role (admin only).", request: `{ name: 'editor', description: 'Can edit content', permissions: ['content:write'] }`, response: `{ message: 'Role created', role: { id: 'new-id', name: 'editor', permissions: ['content:write'] } }`, status: 201 }
+    });
+    const rolesListContent = ts ? `${RA}import type { Request, Response } from 'express';
+${rolesListMeta}${mwAdmin3}
 export const GET = async (_req: Request, res: Response) => {
   // TODO: fetch all roles
   res.json({ roles: [] });
@@ -2702,7 +3180,7 @@ export const POST = async (req: Request, res: Response) => {
   // TODO: create role
   res.status(201).json({ message: 'Role created', role: { id: 'new-id', name, permissions: permissions ?? [] } });
 };
-` : `${RA}${rr3}${mwAdmin3}
+` : `${RA}${rolesListMeta}${mwAdmin3}
 export const GET = async (_req, res) => {
   // TODO: fetch all roles
   res.json({ roles: [] });
@@ -2716,8 +3194,13 @@ export const POST = async (req, res) => {
 };
 `;
     await fs.outputFile(path.join(dest, "src", "api", "admin", "roles", `index.${ext}`), rolesListContent);
-    const roleByIdContent = ts ? `${RA}${rr3}import type { Request, Response } from 'express';
-${mwAdmin3}
+    const roleByIdMeta = mkMeta(opts, {
+      GET: { description: "Fetch a single role by ID (admin only).", params: `{ id: 'role_01HXZ' }`, response: `{ role: { id: 'role_01HXZ', name: 'editor', permissions: ['content:write'] } }` },
+      PUT: { description: "Update a role by ID (admin only).", params: `{ id: 'role_01HXZ' }`, request: `{ name: 'editor', permissions: ['content:write'] }`, response: `{ message: 'Role updated', role: { id: 'role_01HXZ', name: 'editor', permissions: ['content:write'] } }` },
+      DELETE: { description: "Delete a role by ID (admin only).", params: `{ id: 'role_01HXZ' }`, response: `{ message: 'Role role_01HXZ deleted' }` }
+    });
+    const roleByIdContent = ts ? `${RA}import type { Request, Response } from 'express';
+${roleByIdMeta}${mwAdmin3}
 export const GET = async (req: Request, res: Response) => {
   const { id } = req.params;
   // TODO: fetch role by id
@@ -2735,7 +3218,7 @@ export const DELETE = async (req: Request, res: Response) => {
   // TODO: delete role
   res.json({ message: \`Role \${id} deleted\` });
 };
-` : `${RA}${rr3}${mwAdmin3}
+` : `${RA}${roleByIdMeta}${mwAdmin3}
 export const GET = async (req, res) => {
   const { id } = req.params;
   // TODO: fetch role by id
@@ -2756,8 +3239,12 @@ export const DELETE = async (req, res) => {
 `;
     await fs.outputFile(path.join(dest, "src", "api", "admin", "roles", `[id].${ext}`), roleByIdContent);
   }
-  const adminNotifContent = ts ? `${RA}${rr3}import type { Request, Response } from 'express';
-${mwAdmin3}
+  const adminNotifMeta = mkMeta(opts, {
+    GET: { description: "List all sent notifications (admin only).", response: `{ notifications: [], total: 0 }` },
+    POST: { description: "Send a notification to a specific user (admin only).", request: `{ userId: 'usr_01HXZ', title: 'Welcome', message: 'Thanks for joining!', type: 'info' }`, response: `{ message: 'Notification sent' }`, status: 201 }
+  });
+  const adminNotifContent = ts ? `${RA}import type { Request, Response } from 'express';
+${adminNotifMeta}${mwAdmin3}
 export const GET = async (_req: Request, res: Response) => {
 ${roleGuard}  // TODO: fetch sent notifications
   res.json({ notifications: [], total: 0 });
@@ -2769,7 +3256,7 @@ ${roleGuard}  const { userId, title, message, type } = req.body;
   // TODO: create and send notification to user
   res.status(201).json({ message: 'Notification sent' });
 };
-` : `${RA}${rr3}${mwAdmin3}
+` : `${RA}${adminNotifMeta}${mwAdmin3}
 export const GET = async (_req, res) => {
 ${roleGuard}  // TODO: fetch sent notifications
   res.json({ notifications: [], total: 0 });
@@ -2783,8 +3270,10 @@ ${roleGuard}  const { userId, title, message, type } = req.body;
 };
 `;
   await fs.outputFile(path.join(dest, "src", "api", "admin", "notifications", `index.${ext}`), adminNotifContent);
-  const broadcastMeta = mkMeta(opts, "Broadcast a notification to all users.", `{ message: 'Broadcast sent', count: 0 }`, `{ title: 'Announcement', message: 'Hello everyone!', type: 'info' }`);
-  const broadcastContent = ts ? `${RA}${rr3}import type { Request, Response } from 'express';
+  const broadcastMeta = mkMeta(opts, {
+    POST: { description: "Broadcast a notification to all users (admin only).", request: `{ title: 'Announcement', message: 'Hello everyone!', type: 'info' }`, response: `{ message: 'Broadcast sent', count: 0 }` }
+  });
+  const broadcastContent = ts ? `${RA}import type { Request, Response } from 'express';
 ${broadcastMeta}${mwAdmin3}
 export const POST = async (req: Request, res: Response) => {
 ${roleGuard}  const { title, message, type } = req.body;
@@ -2792,7 +3281,7 @@ ${roleGuard}  const { title, message, type } = req.body;
   // TODO: send notification to all users
   res.json({ message: 'Broadcast sent', count: 0 });
 };
-` : `${RA}${rr3}${broadcastMeta}${mwAdmin3}
+` : `${RA}${broadcastMeta}${mwAdmin3}
 export const POST = async (req, res) => {
 ${roleGuard}  const { title, message, type } = req.body;
   if (!title || !message) return res.status(400).json({ error: 'title and message are required' });
@@ -2802,15 +3291,17 @@ ${roleGuard}  const { title, message, type } = req.body;
 `;
   await fs.outputFile(path.join(dest, "src", "api", "admin", "notifications", `broadcast.${ext}`), broadcastContent);
   const mkLogContent = (label) => {
-    const meta = mkMeta(opts, `Paginated ${label} log entries.`, `{ logs: [], total: 0, page: 1, limit: 50 }`);
-    return ts ? `${RA}${rr3}import type { Request, Response } from 'express';
+    const meta = mkMeta(opts, {
+      GET: { description: `Paginated ${label} log entries (admin only).`, query: `{ page: '1', limit: '50' }`, response: `{ logs: [], total: 0, page: 1, limit: 50 }` }
+    });
+    return ts ? `${RA}import type { Request, Response } from 'express';
 ${meta}${mwAdmin3}
 export const GET = async (req: Request, res: Response) => {
 ${roleGuard}  const { page = 1, limit = 50 } = req.query;
   // TODO: fetch ${label} logs with pagination
   res.json({ logs: [], total: 0, page: Number(page), limit: Number(limit) });
 };
-` : `${RA}${rr3}${meta}${mwAdmin3}
+` : `${RA}${meta}${mwAdmin3}
 export const GET = async (req, res) => {
 ${roleGuard}  const { page = 1, limit = 50 } = req.query;
   // TODO: fetch ${label} logs with pagination
@@ -2821,8 +3312,11 @@ ${roleGuard}  const { page = 1, limit = 50 } = req.query;
   await fs.outputFile(path.join(dest, "src", "api", "admin", "logs", `audit.${ext}`), mkLogContent("audit"));
   await fs.outputFile(path.join(dest, "src", "api", "admin", "logs", `activity.${ext}`), mkLogContent("activity"));
   await fs.outputFile(path.join(dest, "src", "api", "admin", "logs", `security.${ext}`), mkLogContent("security"));
-  const settingsMeta = mkMeta(opts, "Get or update system-wide settings.", `{ settings: {} }`);
-  const settingsContent = ts ? `${RA}${rr3}import type { Request, Response } from 'express';
+  const settingsMeta = mkMeta(opts, {
+    GET: { description: "Get system-wide settings (admin only).", response: `{ settings: {} }` },
+    PUT: { description: "Update system-wide settings (admin only).", request: `{ maintenanceMode: false }`, response: `{ message: 'Settings updated', settings: { maintenanceMode: false } }` }
+  });
+  const settingsContent = ts ? `${RA}import type { Request, Response } from 'express';
 ${settingsMeta}${mwAdmin3}
 export const GET = async (_req: Request, res: Response) => {
 ${roleGuard}  // TODO: fetch system settings from DB
@@ -2833,7 +3327,7 @@ export const PUT = async (req: Request, res: Response) => {
 ${roleGuard}  // TODO: update system settings
   res.json({ message: 'Settings updated', settings: req.body });
 };
-` : `${RA}${rr3}${settingsMeta}${mwAdmin3}
+` : `${RA}${settingsMeta}${mwAdmin3}
 export const GET = async (_req, res) => {
 ${roleGuard}  // TODO: fetch system settings from DB
   res.json({ settings: {} });
@@ -2845,43 +3339,49 @@ ${roleGuard}  // TODO: update system settings
 };
 `;
   await fs.outputFile(path.join(dest, "src", "api", "admin", "settings", `index.${ext}`), settingsContent);
-  const healthMeta = mkMeta(opts, "System health check: DB, queue, cache status.", `{ status: 'ok', db: 'ok', queue: 'ok' }`);
-  const healthContent = ts ? `${RA}${rr3}import type { Request, Response } from 'express';
+  const healthMeta = mkMeta(opts, {
+    GET: { description: "System health check: DB, queue, cache status (admin only).", response: `{ status: 'ok', db: 'ok', queue: 'ok', uptime: 12345 }` }
+  });
+  const healthContent = ts ? `${RA}import type { Request, Response } from 'express';
 ${healthMeta}${mwAdmin3}
 export const GET = async (_req: Request, res: Response) => {
 ${roleGuard}  // TODO: check DB connection, queue, cache health
   res.json({ status: 'ok', db: 'ok', queue: 'ok', uptime: process.uptime() });
 };
-` : `${RA}${rr3}${healthMeta}${mwAdmin3}
+` : `${RA}${healthMeta}${mwAdmin3}
 export const GET = async (_req, res) => {
 ${roleGuard}  // TODO: check DB connection, queue, cache health
   res.json({ status: 'ok', db: 'ok', queue: 'ok', uptime: process.uptime() });
 };
 `;
   await fs.outputFile(path.join(dest, "src", "api", "admin", "system", `health.${ext}`), healthContent);
-  const cacheMeta = mkMeta(opts, "Flush the application cache.", `{ message: 'Cache cleared' }`);
-  const cacheContent = ts ? `${RA}${rr3}import type { Request, Response } from 'express';
+  const cacheMeta = mkMeta(opts, {
+    DELETE: { description: "Flush the application cache (admin only).", response: `{ message: 'Cache cleared' }` }
+  });
+  const cacheContent = ts ? `${RA}import type { Request, Response } from 'express';
 ${cacheMeta}${mwAdmin3}
 export const DELETE = async (_req: Request, res: Response) => {
 ${roleGuard}  // TODO: flush Redis or in-memory cache
   res.json({ message: 'Cache cleared' });
 };
-` : `${RA}${rr3}${cacheMeta}${mwAdmin3}
+` : `${RA}${cacheMeta}${mwAdmin3}
 export const DELETE = async (_req, res) => {
 ${roleGuard}  // TODO: flush Redis or in-memory cache
   res.json({ message: 'Cache cleared' });
 };
 `;
   await fs.outputFile(path.join(dest, "src", "api", "admin", "system", `cache.${ext}`), cacheContent);
-  const adminTicketsListMeta = mkMeta(opts, "List all support tickets with filters.", `{ tickets: [], total: 0 }`);
-  const adminTicketsListContent = ts ? `${RA}${rr3}import type { Request, Response } from 'express';
+  const adminTicketsListMeta = mkMeta(opts, {
+    GET: { description: "List all support tickets with filters (admin only).", query: `{ status: 'open', priority: 'normal', page: '1', limit: '20' }`, response: `{ tickets: [], total: 0, page: 1, limit: 20 }` }
+  });
+  const adminTicketsListContent = ts ? `${RA}import type { Request, Response } from 'express';
 ${adminTicketsListMeta}${mwAdmin3}
 export const GET = async (req: Request, res: Response) => {
 ${roleGuard}  const { status, priority, page = 1, limit = 20 } = req.query;
   // TODO: fetch all tickets with filters
   res.json({ tickets: [], total: 0, page: Number(page), limit: Number(limit) });
 };
-` : `${RA}${rr3}${adminTicketsListMeta}${mwAdmin3}
+` : `${RA}${adminTicketsListMeta}${mwAdmin3}
 export const GET = async (req, res) => {
 ${roleGuard}  const { status, priority, page = 1, limit = 20 } = req.query;
   // TODO: fetch all tickets with filters
@@ -2889,8 +3389,12 @@ ${roleGuard}  const { status, priority, page = 1, limit = 20 } = req.query;
 };
 `;
   await fs.outputFile(path.join(dest, "src", "api", "admin", "tickets", `index.${ext}`), adminTicketsListContent);
-  const adminTicketByIdContent = ts ? `${RA}${rr3}import type { Request, Response } from 'express';
-${mwAdmin3}
+  const adminTicketByIdMeta = mkMeta(opts, {
+    GET: { description: "Fetch a single support ticket by ID (admin only).", params: `{ id: 'tk_01HXZ' }`, response: `{ ticket: { id: 'tk_01HXZ' } }` },
+    PUT: { description: "Assign, reply to, or change the status of a support ticket (admin only).", params: `{ id: 'tk_01HXZ' }`, request: `{ reply: 'Looking into it.', status: 'in_progress', assignedTo: 'adm_01HXZ' }`, response: `{ message: 'Ticket updated', ticket: { id: 'tk_01HXZ', status: 'in_progress', assignedTo: 'adm_01HXZ' } }` }
+  });
+  const adminTicketByIdContent = ts ? `${RA}import type { Request, Response } from 'express';
+${adminTicketByIdMeta}${mwAdmin3}
 export const GET = async (req: Request, res: Response) => {
 ${roleGuard}  const { id } = req.params;
   // TODO: fetch ticket by id
@@ -2903,7 +3407,7 @@ ${roleGuard}  const { id } = req.params;
   // TODO: update ticket (assign, change status, add reply)
   res.json({ message: 'Ticket updated', ticket: { id, status, assignedTo } });
 };
-` : `${RA}${rr3}${mwAdmin3}
+` : `${RA}${adminTicketByIdMeta}${mwAdmin3}
 export const GET = async (req, res) => {
 ${roleGuard}  const { id } = req.params;
   // TODO: fetch ticket by id
@@ -2919,8 +3423,16 @@ ${roleGuard}  const { id } = req.params;
 `;
   await fs.outputFile(path.join(dest, "src", "api", "admin", "tickets", `[id].${ext}`), adminTicketByIdContent);
   const mkContentCrud = (name, namePlural, dir, createFields) => {
-    const listMeta = mkMeta(opts, `List ${namePlural} (GET) or create a new ${name} (POST).`, `{ ${namePlural}: [], total: 0 }`);
-    const listContent = ts ? `${RA}${rr4}import type { Request, Response } from 'express';
+    const lower = name.toLowerCase();
+    const firstField = createFields.split(", ")[0];
+    const sampleCreateBody = `{ ${createFields.split(", ").map((f) => `${f}: 'sample-${f}'`).join(", ")} }`;
+    const sampleCreatedRecord = `{ id: 'new-id', ${firstField}: 'sample-${firstField}' }`;
+    const sampleFullRecord = `{ id: '${lower}_01HXZ', ${createFields.split(", ").map((f) => `${f}: 'sample-${f}'`).join(", ")} }`;
+    const listMeta = mkMeta(opts, {
+      GET: { description: `List all ${namePlural} (admin only).`, response: `{ ${namePlural}: [], total: 0 }` },
+      POST: { description: `Create a new ${lower} (admin only).`, request: sampleCreateBody, response: `{ message: '${name} created', ${lower}: ${sampleCreatedRecord} }`, status: 201 }
+    });
+    const listContent = ts ? `${RA}import type { Request, Response } from 'express';
 ${listMeta}${mwAdmin4}
 export const GET = async (_req: Request, res: Response) => {
 ${roleGuard}  // TODO: fetch ${namePlural}
@@ -2930,9 +3442,9 @@ ${roleGuard}  // TODO: fetch ${namePlural}
 export const POST = async (req: Request, res: Response) => {
 ${roleGuard}  const { ${createFields} } = req.body;
   // TODO: create ${name}
-  res.status(201).json({ message: '${name} created', ${name.toLowerCase()}: { id: 'new-id', ${createFields.split(", ")[0]} } });
+  res.status(201).json({ message: '${name} created', ${lower}: { id: 'new-id', ${firstField} } });
 };
-` : `${RA}${rr4}${listMeta}${mwAdmin4}
+` : `${RA}${listMeta}${mwAdmin4}
 export const GET = async (_req, res) => {
 ${roleGuard}  // TODO: fetch ${namePlural}
   res.json({ ${namePlural}: [], total: 0 });
@@ -2941,21 +3453,26 @@ ${roleGuard}  // TODO: fetch ${namePlural}
 export const POST = async (req, res) => {
 ${roleGuard}  const { ${createFields} } = req.body;
   // TODO: create ${name}
-  res.status(201).json({ message: '${name} created', ${name.toLowerCase()}: { id: 'new-id' } });
+  res.status(201).json({ message: '${name} created', ${lower}: { id: 'new-id' } });
 };
 `;
-    const byIdContent = ts ? `${RA}${rr4}import type { Request, Response } from 'express';
-${mwAdmin4}
+    const byIdMeta = mkMeta(opts, {
+      GET: { description: `Fetch a single ${lower} by ID (admin only).`, params: `{ id: '${lower}_01HXZ' }`, response: `{ ${lower}: ${sampleFullRecord} }` },
+      PUT: { description: `Update a ${lower} by ID (admin only).`, params: `{ id: '${lower}_01HXZ' }`, request: sampleCreateBody, response: `{ message: '${name} updated', ${lower}: ${sampleFullRecord} }` },
+      DELETE: { description: `Delete a ${lower} by ID (admin only).`, params: `{ id: '${lower}_01HXZ' }`, response: `{ message: '${name} ${lower}_01HXZ deleted' }` }
+    });
+    const byIdContent = ts ? `${RA}import type { Request, Response } from 'express';
+${byIdMeta}${mwAdmin4}
 export const GET = async (req: Request, res: Response) => {
 ${roleGuard}  const { id } = req.params;
   // TODO: fetch ${name} by id
-  res.json({ ${name.toLowerCase()}: { id } });
+  res.json({ ${lower}: { id } });
 };
 
 export const PUT = async (req: Request, res: Response) => {
 ${roleGuard}  const { id } = req.params;
   // TODO: update ${name}
-  res.json({ message: '${name} updated', ${name.toLowerCase()}: { id, ...req.body } });
+  res.json({ message: '${name} updated', ${lower}: { id, ...req.body } });
 };
 
 export const DELETE = async (req: Request, res: Response) => {
@@ -2963,17 +3480,17 @@ ${roleGuard}  const { id } = req.params;
   // TODO: delete ${name}
   res.json({ message: \`${name} \${id} deleted\` });
 };
-` : `${RA}${rr4}${mwAdmin4}
+` : `${RA}${byIdMeta}${mwAdmin4}
 export const GET = async (req, res) => {
 ${roleGuard}  const { id } = req.params;
   // TODO: fetch ${name} by id
-  res.json({ ${name.toLowerCase()}: { id } });
+  res.json({ ${lower}: { id } });
 };
 
 export const PUT = async (req, res) => {
 ${roleGuard}  const { id } = req.params;
   // TODO: update ${name}
-  res.json({ message: '${name} updated', ${name.toLowerCase()}: { id, ...req.body } });
+  res.json({ message: '${name} updated', ${lower}: { id, ...req.body } });
 };
 
 export const DELETE = async (req, res) => {
@@ -2999,15 +3516,17 @@ ${roleGuard}  const { id } = req.params;
   const { listContent: couponList, byIdContent: couponById } = mkContentCrud("Coupon", "coupons", [], "code, type, value");
   await fs.outputFile(path.join(dest, "src", "api", "admin", "billing", "coupons", `index.${ext}`), couponList);
   await fs.outputFile(path.join(dest, "src", "api", "admin", "billing", "coupons", `[id].${ext}`), couponById);
-  const adminSubsMeta = mkMeta(opts, "List all subscriptions with filters.", `{ subscriptions: [], total: 0 }`);
-  const adminSubsContent = ts ? `${RA}${rr4}import type { Request, Response } from 'express';
+  const adminSubsMeta = mkMeta(opts, {
+    GET: { description: "List all subscriptions with filters (admin only).", query: `{ status: 'active', page: '1', limit: '20' }`, response: `{ subscriptions: [], total: 0, page: 1, limit: 20 }` }
+  });
+  const adminSubsContent = ts ? `${RA}import type { Request, Response } from 'express';
 ${adminSubsMeta}${mwAdmin4}
 export const GET = async (req: Request, res: Response) => {
 ${roleGuard}  const { status, page = 1, limit = 20 } = req.query;
   // TODO: fetch all subscriptions with filters
   res.json({ subscriptions: [], total: 0, page: Number(page), limit: Number(limit) });
 };
-` : `${RA}${rr4}${adminSubsMeta}${mwAdmin4}
+` : `${RA}${adminSubsMeta}${mwAdmin4}
 export const GET = async (req, res) => {
 ${roleGuard}  const { status, page = 1, limit = 20 } = req.query;
   // TODO: fetch all subscriptions with filters
@@ -3064,7 +3583,7 @@ async function main() {
       { value: "routeDocs", label: "API route documentation", hint: "meta exports + dashboard" },
       { value: "userPortal", label: "User portal", hint: "auth, profile, billing routes" },
       { value: "adminPortal", label: "Admin portal", hint: "dashboard, user mgmt, analytics" },
-      { value: "rbac", label: "Role-based access control", hint: "requireRole middleware" },
+      { value: "rbac", label: "Role-based access control", hint: "requireAuth('role') middleware" },
       { value: "mailer", label: "Mailer", hint: "nodemailer + SMTP" }
     ],
     initialValues: ["cluster", "tasks", "routeDocs", "userPortal", "adminPortal", "rbac"],
@@ -3177,6 +3696,13 @@ async function main() {
   await npmInstallGlobal().catch(() => {
   });
   spinner2.stop("efc CLI ready");
+  if (opts.mailer) {
+    p.note(
+      `SMTP_USER and SMTP_PASS were written to ${projectName}/.env \u2014 that file is gitignored, never commit it.
+` + (opts.smtpProvider === "gmail" ? "If this Gmail app password ever leaks, revoke it and generate a new one." : "Rotate SMTP_PASS immediately if it is ever exposed."),
+      "Mailer credentials"
+    );
+  }
   p.outro(
     pc.green(`
 Your project is ready!