webspresso 0.0.91 → 0.0.93

package/src/file-router.js

@@ -367,9 +367,31 @@ function scanDirectory(dir, baseDir = dir) {
 /**
  * Load i18n JSON file with caching
  * @param {string} filePath - Path to JSON file
+ * @param {boolean} [isDev=false] - Whether in development mode
  * @returns {Object} Parsed JSON or empty object
  */
-function loadI18nFile(filePath) {
+function loadI18nFile(filePath, isDev = (process.env.NODE_ENV !== 'production')) {
+  if (!isDev) {
+    const cached = i18nCache.get(filePath);
+    if (cached) {
+      return cached.data;
+    }
+    if (!fs.existsSync(filePath)) {
+      i18nCache.set(filePath, { mtime: 0, data: EMPTY_OBJECT });
+      return EMPTY_OBJECT;
+    }
+    try {
+      const content = fs.readFileSync(filePath, 'utf-8');
+      const data = JSON.parse(content);
+      i18nCache.set(filePath, { mtime: 0, data });
+      return data;
+    } catch (err) {
+      console.error('Error loading i18n file:', filePath, err.message);
+      i18nCache.set(filePath, { mtime: 0, data: EMPTY_OBJECT });
+      return EMPTY_OBJECT;
+    }
+  }
+
   if (!fs.existsSync(filePath)) {
     return EMPTY_OBJECT;
   }
@@ -398,25 +420,43 @@ function loadI18nFile(filePath) {
  * @param {string} pagesDir - Pages directory path
  * @param {string} routeDir - Route directory path
  * @param {string} locale - Locale code
+ * @param {boolean} [isDev=false] - Whether in development mode
  * @returns {Object} Merged translations
  */
-function loadI18n(pagesDir, routeDir, locale) {
+function loadI18n(pagesDir, routeDir, locale, isDev = (process.env.NODE_ENV !== 'production')) {
+  const cacheKey = `${pagesDir}::${routeDir}::${locale}`;
+
+  if (!isDev) {
+    const mergedCached = mergedI18nCache.get(cacheKey);
+    if (mergedCached) {
+      return mergedCached.data;
+    }
+  }
+
   // Load global translations
   const globalPath = path.join(pagesDir, 'locales', `${locale}.json`);
-  const globalTranslations = loadI18nFile(globalPath);
+  const globalTranslations = loadI18nFile(globalPath, isDev);
   
   // Load route-specific translations
   const routePath = path.join(routeDir, 'locales', `${locale}.json`);
-  const routeTranslations = loadI18nFile(routePath);
+  const routeTranslations = loadI18nFile(routePath, isDev);
   
   const gEmpty = globalTranslations === EMPTY_OBJECT || !globalTranslations || Object.keys(globalTranslations).length === 0;
   const rEmpty = routeTranslations === EMPTY_OBJECT || !routeTranslations || Object.keys(routeTranslations).length === 0;
 
-  if (gEmpty && rEmpty) return EMPTY_OBJECT;
-  if (gEmpty) return routeTranslations;
-  if (rEmpty) return globalTranslations;
+  if (gEmpty && rEmpty) {
+    if (!isDev) mergedI18nCache.set(cacheKey, { gm: 0, rm: 0, data: EMPTY_OBJECT });
+    return EMPTY_OBJECT;
+  }
+  if (gEmpty) {
+    if (!isDev) mergedI18nCache.set(cacheKey, { gm: 0, rm: 0, data: routeTranslations });
+    return routeTranslations;
+  }
+  if (rEmpty) {
+    if (!isDev) mergedI18nCache.set(cacheKey, { gm: 0, rm: 0, data: globalTranslations });
+    return globalTranslations;
+  }
 
-  const cacheKey = `${pagesDir}::${routeDir}::${locale}`;
   const gCached = i18nCache.get(globalPath);
   const rCached = i18nCache.get(routePath);
   const gm = gCached?.mtime ?? 0;
@@ -626,32 +666,41 @@ function createTranslator(translations = {}, options = EMPTY_OBJECT) {
  * @returns {Object|null} Route config or null
  */
 function loadRouteConfig(configPath, isDev) {
+  if (!isDev) {
+    if (configCache.has(configPath)) {
+      return configCache.get(configPath);
+    }
+    if (!fs.existsSync(configPath)) {
+      configCache.set(configPath, null);
+      return null;
+    }
+    try {
+      const config = require(configPath);
+      configCache.set(configPath, config);
+      return config;
+    } catch (err) {
+      console.error('Error loading route config:', configPath, err.message);
+      configCache.set(configPath, null);
+      return null;
+    }
+  }
+
   if (!fs.existsSync(configPath)) {
     routeConfigDevCache.delete(configPath);
     return null;
   }
 
   try {
-    if (isDev) {
-      const stats = fs.statSync(configPath);
-      const devCached = routeConfigDevCache.get(configPath);
-      if (devCached && devCached.mtime >= stats.mtimeMs) {
-        return devCached.config;
-      }
-      if (require.cache[require.resolve(configPath)]) {
-        delete require.cache[require.resolve(configPath)];
-      }
-      const config = require(configPath);
-      routeConfigDevCache.set(configPath, { mtime: stats.mtimeMs, config });
-      return config;
+    const stats = fs.statSync(configPath);
+    const devCached = routeConfigDevCache.get(configPath);
+    if (devCached && devCached.mtime >= stats.mtimeMs) {
+      return devCached.config;
     }
-
-    if (configCache.has(configPath)) {
-      return configCache.get(configPath);
+    if (require.cache[require.resolve(configPath)]) {
+      delete require.cache[require.resolve(configPath)];
     }
-
     const config = require(configPath);
-    configCache.set(configPath, config);
+    routeConfigDevCache.set(configPath, { mtime: stats.mtimeMs, config });
     return config;
   } catch (err) {
     console.error('Error loading route config:', configPath, err.message);
@@ -976,123 +1025,133 @@ function mountPages(app, options) {
   /** Register API routes (shared by static phase and dynamic phase). */
   const registerApiRoutes = (routes) => {
     for (const route of routes) {
-    const handler = require(route.fullPath);
-    const handlerFn = typeof handler === 'function' ? handler : handler.default || handler.handler;
-    const routeMiddleware = handler.middleware;
+      const handler = require(route.fullPath);
+      const handlerFn = typeof handler === 'function' ? handler : handler.default || handler.handler;
+      const routeMiddleware = handler.middleware;
 
-    const preResolvedMw = routeMiddleware
-      ? resolveMiddlewares(routeMiddleware, middlewares)
-      : EMPTY_ARRAY;
-    
-    if (typeof handlerFn !== 'function') {
-      console.warn(`API route ${route.file} does not export a function`);
-      continue;
-    }
+      const preResolvedMw = routeMiddleware
+        ? resolveMiddlewares(routeMiddleware, middlewares)
+        : EMPTY_ARRAY;
     
-    app[route.method](route.routePath, async (req, res, next) => {
-      try {
-        // Same instance as createApp({ db }) / getAppContext().db — available to handler & route middleware
-        if (db != null) {
-          req.db = db;
-        }
-        if (serviceRegistry != null) {
-          req.service = (name, input, opts) =>
-            serviceRegistry.call(name, input, { req, res, db }, opts);
-        }
+      if (typeof handlerFn !== 'function') {
+        console.warn(`API route ${route.file} does not export a function`);
+        continue;
+      }
 
-        // Reload handler in dev mode
-        if (isDev && require.cache[require.resolve(route.fullPath)]) {
-          delete require.cache[require.resolve(route.fullPath)];
-        }
-        const currentHandler = isDev 
-          ? require(route.fullPath) 
-          : handler;
-        const fn = typeof currentHandler === 'function' 
-          ? currentHandler 
-          : currentHandler.default || currentHandler.handler;
-
-        if (isDev) {
-          invalidateSchema(route.fullPath);
-        }
-        let compiledSchema;
+      let preCompiledSchema = null;
+      if (!isDev) {
         try {
-          compiledSchema = compileSchema(route.fullPath, currentHandler);
+          preCompiledSchema = compileSchema(route.fullPath, handler);
         } catch (schemaErr) {
           console.error(`API schema compile error ${route.routePath}:`, schemaErr);
-          res.status(500).json({ error: 'Internal Server Error', message: schemaErr.message });
-          return;
         }
-
+      }
+      
+      app[route.method](route.routePath, async (req, res, next) => {
         try {
-          applySchema(req, compiledSchema);
-        } catch (err) {
-          if (err instanceof ZodError) {
-            return res.status(400).json({
-              error: 'Validation Error',
-              issues: err.issues,
-            });
+          // Same instance as createApp({ db }) / getAppContext().db — available to handler & route middleware
+          if (db != null) {
+            req.db = db;
           }
-          throw err;
-        }
-        
-        // Run middleware if defined (resolved at route registration — required for stateful middleware like express-rate-limit)
-        if (preResolvedMw.length) {
-          for (const mw of preResolvedMw) {
-            await new Promise((resolve, reject) => {
-              mw(req, res, (err) => {
-                if (err) reject(err);
-                else resolve();
+          if (serviceRegistry != null) {
+            req.service = (name, input, opts) =>
+              serviceRegistry.call(name, input, { req, res, db }, opts);
+          }
+
+          let fn = handlerFn;
+          let compiledSchema = preCompiledSchema;
+
+          // Reload handler and schema in dev mode
+          if (isDev) {
+            if (require.cache[require.resolve(route.fullPath)]) {
+              delete require.cache[require.resolve(route.fullPath)];
+            }
+            const currentHandler = require(route.fullPath);
+            fn = typeof currentHandler === 'function' 
+              ? currentHandler 
+              : currentHandler.default || currentHandler.handler;
+
+            invalidateSchema(route.fullPath);
+            try {
+              compiledSchema = compileSchema(route.fullPath, currentHandler);
+            } catch (schemaErr) {
+              console.error(`API schema compile error ${route.routePath}:`, schemaErr);
+              res.status(500).json({ error: 'Internal Server Error', message: schemaErr.message });
+              return;
+            }
+          }
+
+          try {
+            applySchema(req, compiledSchema);
+          } catch (err) {
+            if (err instanceof ZodError) {
+              return res.status(400).json({
+                error: 'Validation Error',
+                issues: err.issues,
               });
-            });
+            }
+            throw err;
           }
+          
+          // Run middleware if defined (resolved at route registration — required for stateful middleware like express-rate-limit)
+          if (preResolvedMw.length) {
+            for (const mw of preResolvedMw) {
+              await new Promise((resolve, reject) => {
+                mw(req, res, (err) => {
+                  if (err) reject(err);
+                  else resolve();
+                });
+              });
+            }
+          }
+          
+          await fn(req, res, next);
+        } catch (err) {
+          console.error(`API error ${route.routePath}:`, err);
+          const hookCtx = { req, res, error: err };
+          try {
+            await executeHook(globalHooks, 'onError', hookCtx, err);
+          } catch (hookErr) {
+            console.error('Error in onError hook:', hookErr);
+          }
+          return next(err);
         }
-        
-        await fn(req, res, next);
-      } catch (err) {
-        console.error(`API error ${route.routePath}:`, err);
-        const hookCtx = { req, res, error: err };
-        try {
-          await executeHook(globalHooks, 'onError', hookCtx, err);
-        } catch (hookErr) {
-          console.error('Error in onError hook:', hookErr);
-        }
-        return next(err);
-      }
-    });
-    
-    log(`  ${route.method.toUpperCase()} ${route.routePath} -> ${route.file}`);
+      });
+      
+      log(`  ${route.method.toUpperCase()} ${route.routePath} -> ${route.file}`);
     }
   };
 
   /** Register SSR GET routes (shared by static phase and dynamic phase). */
   const registerSsrRoutes = (routes) => {
     for (const route of routes) {
-    const mountConfig = loadRouteConfig(route.configPath, isDev);
-    const preResolvedPageMw = mountConfig?.middleware
-      ? resolveMiddlewares(mountConfig.middleware, middlewares)
-      : EMPTY_ARRAY;
-
-    app.get(route.routePath, async (req, res, next) => {
-      try {
-        // Detect locale
-        const locale = detectLocale(req);
-        const defaultLocale = process.env.DEFAULT_LOCALE || 'en';
-        
-        // Load translations (primary + fallback)
-        const translations = loadI18n(absolutePagesDir, route.routeDir, locale);
-        const fallbackTranslations = (locale !== defaultLocale)
-          ? loadI18n(absolutePagesDir, route.routeDir, defaultLocale)
-          : EMPTY_OBJECT;
+      const mountConfig = loadRouteConfig(route.configPath, isDev);
+      const preResolvedPageMw = mountConfig?.middleware
+        ? resolveMiddlewares(mountConfig.middleware, middlewares)
+        : EMPTY_ARRAY;
+      const staticRouteHooks = mountConfig?.hooks || EMPTY_OBJECT;
 
-        const t = createTranslator(translations, {
-          locale,
-          fallbackTranslations,
-          fallbackLocale: defaultLocale,
-        });
-        
-        // Load route config
-        const config = loadRouteConfig(route.configPath, isDev);
-        const routeHooks = config?.hooks || EMPTY_OBJECT;
+      app.get(route.routePath, async (req, res, next) => {
+        try {
+          // Detect locale
+          const locale = detectLocale(req);
+          const defaultLocale = process.env.DEFAULT_LOCALE || 'en';
+          
+          // Load translations (primary + fallback)
+          const translations = loadI18n(absolutePagesDir, route.routeDir, locale, isDev);
+          const fallbackTranslations = (locale !== defaultLocale)
+            ? loadI18n(absolutePagesDir, route.routeDir, defaultLocale, isDev)
+            : EMPTY_OBJECT;
+
+          const t = createTranslator(translations, {
+            locale,
+            fallbackTranslations,
+            fallbackLocale: defaultLocale,
+          });
+          
+          // Load route config
+          const config = isDev ? loadRouteConfig(route.configPath, true) : mountConfig;
+          const routeHooks = isDev ? (config?.hooks || EMPTY_OBJECT) : staticRouteHooks;
         
         // Create context with plugin helpers merged
         const baseHelpers = createHelpers({ req, res, locale, t });
@@ -1134,6 +1193,8 @@ function mountPages(app, options) {
           clientRuntime,
         };
         
+        req.context = ctx;
+        
         // Execute hooks: onRequest
         await executeHook(globalHooks, 'onRequest', ctx);
         await executeHook(routeHooks, 'onRequest', ctx);

package/src/njk-frontmatter.js

@@ -115,6 +115,24 @@ function readAndParse(absPath, isDevLike = false) {
  * @param {boolean} isDev NODE_ENV !== 'production' style
  */
 function loadNjkRouteTemplate(absPath, isDev) {
+  if (!isDev) {
+    const cached = prodRouteCache.get(absPath);
+    if (cached) {
+      return cached;
+    }
+    if (!fs.existsSync(absPath)) {
+      const empty = {
+        useStringRender: false,
+        templateBody: null,
+        metaPatch: {},
+        dataPatch: {},
+      };
+      prodRouteCache.set(absPath, empty);
+      return empty;
+    }
+    return readAndParse(absPath, false);
+  }
+
   if (!fs.existsSync(absPath)) {
     return {
       useStringRender: false,
@@ -125,21 +143,13 @@ function loadNjkRouteTemplate(absPath, isDev) {
   }
 
   const stat = fs.statSync(absPath);
-
-  if (isDev) {
-    const prev = devRouteCache.get(absPath);
-    if (prev && prev.mtimeMs >= stat.mtimeMs) {
-      return prev.cached;
-    }
-    const fresh = readAndParse(absPath, true);
-    devRouteCache.set(absPath, { mtimeMs: stat.mtimeMs, cached: fresh });
-    return fresh;
-  }
-
-  if (prodRouteCache.has(absPath)) {
-    return prodRouteCache.get(absPath);
+  const prev = devRouteCache.get(absPath);
+  if (prev && prev.mtimeMs >= stat.mtimeMs) {
+    return prev.cached;
   }
-  return readAndParse(absPath, false);
+  const fresh = readAndParse(absPath, true);
+  devRouteCache.set(absPath, { mtimeMs: stat.mtimeMs, cached: fresh });
+  return fresh;
 }
 
 function clearNjkFrontmatterCaches() {

package/src/server.js

@@ -47,7 +47,7 @@ function configureSafeNunjucks(templateDirs, options = {}) {
   const origRender = env.render.bind(env);
   const origRenderString = env.renderString.bind(env);
 
-  function wrapTemplateRoot(tmpl, name, store) {
+  function wrapTemplateRoot(tmpl, name) {
     if (!tmpl || tmpl._safeWrapped) return;
     tmpl._safeWrapped = true;
     const origRoot = tmpl.rootRenderFunc;
@@ -55,21 +55,28 @@ function configureSafeNunjucks(templateDirs, options = {}) {
 
     tmpl.rootRenderFunc = function(e, context, frame, runtime, renderCb) {
       const normalizedName = String(name || tmpl.path || 'anonymous');
-      store.stack.push(normalizedName);
+      const store = renderStackStorage.getStore();
+      if (store) {
+        store.stack.push(normalizedName);
+      }
       let finished = false;
       const done = (err, out) => {
         if (!finished) {
           finished = true;
-          const idx = store.stack.lastIndexOf(normalizedName);
-          if (idx !== -1) store.stack.splice(idx, 1);
+          if (store) {
+            const idx = store.stack.lastIndexOf(normalizedName);
+            if (idx !== -1) store.stack.splice(idx, 1);
+          }
         }
         renderCb(err, out);
       };
       try {
         return origRoot.call(this, e, context, frame, runtime, done);
       } catch (ex) {
-        const idx = store.stack.lastIndexOf(normalizedName);
-        if (idx !== -1) store.stack.splice(idx, 1);
+        if (store) {
+          const idx = store.stack.lastIndexOf(normalizedName);
+          if (idx !== -1) store.stack.splice(idx, 1);
+        }
         throw ex;
       }
     };
@@ -97,15 +104,15 @@ function configureSafeNunjucks(templateDirs, options = {}) {
     }
 
     const wrappedCb = typeof cb === 'function' ? function(err, tmpl) {
-      if (tmpl && store) {
-        wrapTemplateRoot(tmpl, name, store);
+      if (tmpl) {
+        wrapTemplateRoot(tmpl, name);
       }
       cb(err, tmpl);
     } : undefined;
 
     const res = origGetTemplate(name, eagerCompile, parentName, ignoreMissing, wrappedCb);
-    if (res && store) {
-      wrapTemplateRoot(res, name, store);
+    if (res) {
+      wrapTemplateRoot(res, name);
     }
     return res;
   };
@@ -467,10 +474,21 @@ function createApp(options = {}) {
   const app = express();
   app.serviceRegistry = serviceRegistry;
 
-  // Services caller middleware
+  // Request context & services caller middleware
   app.use((req, res, next) => {
+    if (options.db) {
+      req.db = options.db;
+    }
+    req.context = {
+      req,
+      res,
+      db: options.db ?? null,
+      app,
+      serviceRegistry,
+      ...(req.context || {}),
+    };
     req.service = (name, input, opts) =>
-      serviceRegistry.call(name, input, { req, res, db: options.db ?? null, ...(req.context || {}) }, opts);
+      serviceRegistry.call(name, input, req.context, opts);
     next();
   });
 

package/src/services/discovery.js

@@ -6,6 +6,7 @@
 
 const fs = require('fs');
 const path = require('path');
+const { trimUrlPathSlashes } = require('../../core/url-path-normalize');
 
 const VALID_EXTENSIONS = new Set(['.js', '.mjs', '.cjs']);
 
@@ -50,7 +51,7 @@ function filePathToServiceName(relativePath) {
   }
 
   // Cross-platform slash normalization (Windows \ to Unix /)
-  const normalized = relativePath.replace(/\\/g, '/').replace(/^\/+|\/+$/g, '');
+  const normalized = trimUrlPathSlashes(relativePath.replace(/\\/g, '/'));
   const ext = path.extname(normalized);
   const withoutExt = ext ? normalized.slice(0, -ext.length) : normalized;
   const segments = withoutExt.split('/').filter(Boolean);

package/src/services/registry.js

@@ -102,6 +102,7 @@ class ServiceRegistry {
         rawHandler: definition.handler,
         memoize: memoizeFn,
         metadata: definition.metadata || {},
+        description: definition.description || definition.metadata?.description || '',
         auth: definition.auth,
         cache: definition.cache,
         timeout: definition.timeout,
@@ -158,6 +159,7 @@ class ServiceRegistry {
       rawHandler: def.handler,
       memoize: memoizeFn,
       metadata: def.metadata || {},
+      description: def.description || def.metadata?.description || '',
       auth: def.auth,
       cache: def.cache,
       timeout: def.timeout,

package/src/services/validator.js

@@ -4,60 +4,9 @@
  * @module src/services/validator
  */
 
-const z = require('zod');
 const { ValidationError } = require('../../core/errors');
-const { extendZ } = require('../../core/orm/utils/nanoid');
-
-/** Zod instance extended with z.nanoid() */
-const zForServices = extendZ(z);
-
-/**
- * Check if object contains dangerous prototype pollution keys
- * @param {*} obj
- * @returns {boolean}
- */
-function hasDangerousKeys(obj) {
-  if (obj === null || typeof obj !== 'object') {
-    return false;
-  }
-  if (Array.isArray(obj)) {
-    return obj.some(item => hasDangerousKeys(item));
-  }
-  for (const key of Object.keys(obj)) {
-    if (key === '__proto__' || key === 'constructor' || key === 'prototype') {
-      return true;
-    }
-    if (typeof obj[key] === 'object' && obj[key] !== null && hasDangerousKeys(obj[key])) {
-      return true;
-    }
-  }
-  return false;
-}
-
-/**
- * Sanitize input against prototype pollution
- * @param {*} input
- * @returns {*} Sanitized input
- */
-function sanitizeInput(input) {
-  if (input === null || typeof input !== 'object') {
-    return input;
-  }
-  if (!hasDangerousKeys(input)) {
-    return input;
-  }
-  if (Array.isArray(input)) {
-    return input.map(item => sanitizeInput(item));
-  }
-  const clean = {};
-  for (const key of Object.keys(input)) {
-    if (key === '__proto__' || key === 'constructor' || key === 'prototype') {
-      continue;
-    }
-    clean[key] = sanitizeInput(input[key]);
-  }
-  return clean;
-}
+const { z: zForServices, sanitizeInput, hasDangerousKeys } = require('../../core/validation');
+const z = zForServices;
 
 /**
  * Compile a concise type string descriptor into a Zod schema

package/templates/skills/webspresso-usage/REFERENCE-framework.md

@@ -4,8 +4,10 @@ Sections follow the source repo layout (`index.js`, `src/`, `core/orm`, `doc/ind
 
 ## 1. What this framework is
 
-- **SSR**: Express + **Nunjucks**; URLs map to files under `pages/`.
-- **API**: File-based handlers under `pages/api/` with method suffixes and optional **Zod** validation (`req.input`).
+- **Architecture**: Modern full-stack Node.js framework with Next.js/Nuxt-style file-based routing.
+- **SSR**: Native server-side rendering with **Nunjucks**; URLs map directly to files under `pages/`.
+- **API**: 100% file-based handlers under `pages/api/` with HTTP method suffixes (`.get.js`, `.post.js`, `[id].delete.js`) and declarative **Zod** validation (`req.input`).
+- ⚠️ **CRITICAL ANTI-PATTERN**: **NEVER** create a `routes/` or `src/routes/` directory. **NEVER** use `app.get()`, `app.post()`, or `express.Router()`. All application routes must live under `pages/` and `pages/api/`.
 - **i18n**: JSON locales; `t('key')` in templates.
 - **ORM**: Knex-backed layer in `core/orm` — `defineModel`, `zdb` schema helpers, repositories, query builder, migrations.
 - **Plugins**: Register in `createApp({ plugins })`; optional `db` passed as `ctx.db`.
@@ -60,7 +62,7 @@ project/
 | `pageAssets` | Opt-in **`true`** or **`{ enabled?, stylesheets?, scripts? }`**. When on, route **`load()`** may return reserved keys **`stylesheets`** (string or list; also `{ href, media? }` objects) and **`scripts`** (string, `{ src, defer?, async?, type? }`, or list). They are removed from the root Nunjucks context and passed as **`pageHead`** with **`pageAssets: true`**. The app layout must print them (see [`views/layout.njk`](../../../views/layout.njk) in the package). Default **off** — `stylesheets` / `scripts` in **`load()`** behave as normal data keys. |
 | `clientRuntime` | Opt-in **`{ alpine?: boolean \| object, swup?: boolean \| object }`**. Serves **`/__webspresso/client-runtime/*`** (Alpine 3, swup 4 + Head + Scripts plugins + bootstrap). Template context **`clientRuntime`**; include [`views/partials/webspresso-client-runtime.njk`](../../../views/partials/webspresso-client-runtime.njk) and set **`<main id="swup">`** when swup is on. Env overrides: **`WEBSPRESSO_ALPINE`**, **`WEBSPRESSO_SWUP`** (`1` or `true`). Admin / dev dashboard HTML is unchanged (Mithril). Use **`data-no-swup`** on links for full page loads. HTMX is not used. |
 | `auth` | `AuthManager` from **`createAuth()`** / **`quickAuth()`** (`webspresso/core/auth`). Mounts cookie parser + **`express-session`** + per-request **`authenticate`**; sets **`req.user`**, **`req.auth`**. Injects named route middleware **`auth`** and **`guest`** (overwrites same keys in `middlewares` if you passed both — avoid reusing those names for custom handlers). |
-| `setupRoutes(app, ctx)` | **Register custom Express routes here** — runs **after** file routes and plugins’ `onRoutesReady`, **before** 404. **`ctx.clientRuntime`** is the resolved flags. **`ctx.authMiddleware`** is set when `auth` was passed (guards: `requireAuth`, `requireGuest`, `requireCan`, `requireVerified`, …). Do not rely on `app.get` *after* `createApp` returns unless routes are appended before the 404 middleware (see [`src/server.js`](../../../src/server.js)). |
+| `setupRoutes(app, ctx)` | Low-level server extension hook (e.g. mounting third-party sub-apps or raw middleware). ⚠️ **NEVER** use `setupRoutes` to define application domain or API routes. All application endpoints **MUST** live under `pages/` and `pages/api/`. |
 
 **Returns:** `{ app, nunjucksEnv, pluginManager, authMiddleware }` — `authMiddleware` is **`null`** when `auth` was not configured.
 
@@ -267,7 +269,7 @@ Pass **`db`** into **`createApp({ db })`** so **`ctx.db`** works in pages and pl
 
 ## 14. Pitfalls (for agents)
 
-1. **Custom Express routes** — use **`setupRoutes`**, not only `app.use` after `createApp` returns.
+1. **NEVER use Express routes (`app.get` / `routes/`)** — Webspresso is 100% file-based. Never create `routes/` or call `app.get()`. All routes must live in `pages/` and `pages/api/`.
 2. **File-router order** — understand precedence vs manual routes.
 3. **`ctx.db`** — only when `createApp({ db })` is set.
 4. **ORM hidden fields** — never expose to clients unintentionally.