@reldens/cms 0.51.0 → 0.53.0

package/CLAUDE.md

@@ -5,6 +5,7 @@ This file provides guidance to Claude Code (claude.ai/code) when working with co
 ## Package Overview
 
 **@reldens/cms** is a comprehensive Content Management System package for Reldens. It provides a complete web application framework with:
+
 - Database-driven content management with entity access control
 - Multi-domain support with domain-specific templates
 - Powerful template engine with Mustache integration
@@ -32,560 +33,126 @@ npx reldens-cms-update-password --email=admin@example.com
 npm run generate-entities
 ```
 
-## Password Management
+## Quick Start
 
-### CLI Password Update Command
+### Password Management
 
-The CMS provides a dedicated CLI command for securely updating user passwords:
+The CMS automatically encrypts passwords using PBKDF2 (100k iterations, SHA-512) when saving user records through the admin panel.
 
+**CLI Password Update:**
 ```bash
-# Interactive mode (recommended - will prompt for password)
+# Interactive mode (recommended)
 npx reldens-cms-update-password --email=admin@example.com
-
-# By username
-npx reldens-cms-update-password --username=admin
-
-# With password in command (less secure)
-npx reldens-cms-update-password --email=admin@example.com --password=newPassword123
 ```
 
-**Options**:
-- `--email=[email]` - User email address
-- `--username=[username]` - User username
-- `--password=[password]` - New password (prompted if not provided)
-- `--help` or `-h` - Show this help message
-
-**Notes**:
-- Works with any storage driver (prisma, objection-js, mikro-orm)
-- Uses `RELDENS_STORAGE_DRIVER` environment variable to detect the driver
-- Automatically loads entities and Prisma client (if using Prisma)
-
-### Automatic Password Encryption
-
-The CMS automatically encrypts passwords when saving user records through the admin panel using the `PasswordEncryptionHandler`:
-
-- Listens to `reldens.adminBeforeEntitySave` event
-- Detects password field changes in users entity
-- Encrypts passwords using PBKDF2 (100k iterations, SHA-512)
-- Stores passwords in `salt:hash` format
-- **Enabled by default** - can be disabled with `enablePasswordEncryption: false` in Manager config
-
-**Password Encryption Algorithm**:
-- **Method**: PBKDF2 (Password-Based Key Derivation Function 2)
-- **Iterations**: 100,000
-- **Key Length**: 64 bytes
-- **Digest**: SHA-512
-- **Salt Length**: 32 bytes (randomly generated)
-- **Storage Format**: `salt:hash` (192 characters total)
-
 See `.claude/password-management-guide.md` for comprehensive password management documentation.
 
-## Architecture Overview
-
-The CMS follows a modular architecture with specialized classes following SOLID principles:
-
-### Core Orchestrators
-
-**lib/manager.js** - Main CMS orchestrator
-- Initializes all services (data server, admin, frontend)
-- Handles configuration and environment variables
-- Manages multi-domain setup and security
-- Coordinates service lifecycle
-- Initializes password encryption handler
-
-**lib/frontend.js** - Frontend orchestrator
-- Coordinates all frontend operations
-- Manages template engine, cache, and rendering
-- Handles search and dynamic forms
-- Routes requests to appropriate handlers
-
-**lib/admin-manager.js** - Admin panel orchestrator
-- Manages admin panel routes and authentication
-- Handles entity CRUD operations
-- Processes file uploads
-- Builds admin UI from entity configurations
-
-**lib/password-encryption-handler.js** - Password encryption handler
-- Automatic password encryption for users entity
-- Event-driven architecture
-- PBKDF2 encryption with 100k iterations
-- Detects and skips already-encrypted passwords
-- Configurable entity and field names
-
-**lib/admin-manager/router-contents.js** - Admin routing and form handling
-- Password field handling (type="password", empty on edit)
-- Password updates optional (skip if empty when editing)
-- Configurable password field names via `passwordFieldNames`
-
-### Installation & Setup
-
-**lib/installer.js** - Installation orchestrator
-- Web-based installer with subprocess management
-- Dependency checking and installation
-- Database schema creation
-- Environment file generation
-- Post-installation callbacks
-
-**lib/mysql-installer.js** - Database-specific installation
-- MySQL schema creation
-- Schema migration support
-- Database validation
-
-**lib/prisma-subprocess-worker.js** - Subprocess worker
-- Handles Prisma client generation
-- Progress tracking for long operations
-
-### Frontend Architecture (lib/frontend/)
-
-**template-resolver.js** - Template discovery
-- Domain-aware template resolution
-- Fallback system (domain → default → base)
-- Layout and partial template lookup
-- Path-to-template mapping
-
-**template-cache.js** - Template caching
-- Loads and caches partials
-- Domain-specific template management
-- Partial inheritance and overrides
-
-**request-processor.js** - Request routing
-- Route database lookup
-- Domain extraction from requests
-- Path normalization
-- Cache key generation
-
-**entity-access-manager.js** - Entity access control
-- Loads entity access rules
-- Public/private entity validation
-- Entity lookup by path
-
-**content-renderer.js** - Content generation
-- Main content rendering logic
-- Route-based content generation
-- Template processing
-- Meta field handling
-
-**response-manager.js** - Response handling
-- HTTP response management
-- Cache integration
-- Error handling (404, 500)
-
-### Template Engine (lib/template-engine.js & lib/template-engine/)
-
-**template-engine.js** - Core template processor
-- Orchestrates all template transformers
-- System variables injection
-- Event-driven rendering pipeline
-- Mustache integration
-
-**Template Transformers:**
-- **entities-transformer.js** - Single entity rendering `<entity name="cmsBlocks" field="name" value="header"/>`
-- **collections-transformer.js** - Collection loops with pagination
-- **collections-single-transformer.js** - Single field collections
-- **partials-transformer.js** - Partial template processing
-- **forms-transformer.js** - Dynamic forms rendering `<cmsForm key="contact"/>`
-- **url-transformer.js** - URL generation `[url(/path)]`
-- **asset-transformer.js** - Asset URLs `[asset(/img/logo.png)]`
-- **cdn-transformer.js** - CDN URL transformation
-- **date-transformer.js** - Date formatting `[date(now, Y-m-d)]`
-- **translate-transformer.js** - Internationalization `[translate(key)]`
-
-**system-variables-provider.js** - System variables
-- Current request context (host, path, protocol)
-- Current route data
-- Current domain information
-- System information (environment, timestamp)
-
-**translation-service.js** - Translation loading
-- JSON translation file management
-- Locale detection
-- Fallback handling
-
-### Dynamic Forms System
-
-**lib/dynamic-form.js** - Form validation and processing
-- Schema-based validation
-- Honeypot protection
-- Rate limiting integration
-- Data sanitization
-- Database storage
-
-**lib/dynamic-form-renderer.js** - Form template rendering
-- Domain-aware form templates
-- Field type templates
-- Error display
-- Form attribute handling
-
-**lib/dynamic-form-request-handler.js** - Form request handling
-- POST request processing
-- Validation orchestration
-- Success/error redirects
-- JSON response support
-
-### Search System
-
-**lib/search.js** - Search functionality
-- Multi-entity search
-- Custom search sets
-- Query parameter parsing
-- Pagination support
-
-**lib/search-renderer.js** - Search result rendering
-- Template-based result display
-- Custom column classes
-- Domain-aware templates
-
-**lib/search-request-handler.js** - Search request handling
-- Query processing
-- Template data support
-- Error handling
-
-### Cache System (lib/cache/)
-
-**cache-manager.js** - Cache orchestrator
-- Domain and path-based caching
-- Cache invalidation
-- Enable/disable functionality
-
-**cache-routes-handler.js** - Cache admin routes
-- Cache clearing endpoints
-- Cache management UI integration
-
-**add-cache-button-subscriber.js** - Cache UI integration
-- Adds cache buttons to admin panel
-- Event-driven cache controls
-
-### Admin System (lib/admin-manager/)
-
-**router.js** - Admin routing
-- Authentication middleware
-- Session management
-- CRUD route setup
-- File upload handling
-
-**router-contents.js** - Admin content generation
-- List view generation
-- Edit form generation
-- Relation handling
-- Save/delete processing
-
-**contents-builder.js** - Admin UI builder
-- Sidebar navigation
-- Entity list/edit views
-- Form field generation
-- Branding and styling
-
-**admin-filters-manager.js** - Entity filtering
-- Filter UI generation
-- Query building
-
-**default-translations.js** - Admin translations
-- Default English labels
-- Extensible translation system
-
-### Utility Classes
-
-**lib/entities-loader.js** - Entity loading from files
-**lib/loaded-entities-processor.js** - Entity configuration processing
-**lib/admin-entities-generator.js** - Admin entity configuration
-**lib/admin-templates-loader.js** - Admin template loading
-**lib/templates-to-path-mapper.js** - Template path mapping
-**lib/templates-list.js** - Template file list
-**lib/json-fields-parser.js** - JSON field parsing
-**lib/pagination-handler.js** - Pagination logic
-**lib/template-reloader.js** - Development template reloading
-**lib/cms-pages-route-manager.js** - CMS page routing
-**lib/admin-manager-validator.js** - Admin config validation
-**lib/admin-dist-helper.js** - Admin asset distribution
-**lib/mime-types.js** - File type definitions
-**lib/allowed-extensions.js** - Upload extension whitelist
-
-## Database Schema
-
-The CMS uses these core tables:
-
-### Content Tables
-- **routes** - URL routing with SEO metadata (title, description, keywords)
-- **cms_pages** - Page content with layout assignments
-- **cms_blocks** - Reusable content blocks (by name identifier)
-- **cms_forms** - Dynamic form configurations with JSON schema
-- **cms_forms_submitted** - Form submission storage with JSON data
-
-### Access Control
-- **entities_access** - Entity visibility and operation rules
-- **entities_meta** - Generic metadata storage
-- **cms_pages_meta** - Page-specific metadata
-
-### User Management (Optional)
-- **users** - User authentication (with encrypted passwords)
-- **roles** - Role definitions
-
-## Template System
-
-### Template Directory Structure
-```
-templates/
-├── domains/                    # Domain-specific templates
-│   └── example.com/
-│       ├── layouts/           # Domain layouts
-│       ├── partials/          # Domain partials
-│       ├── cms_forms/         # Domain form templates
-│       └── page.html          # Domain page wrapper
-├── layouts/                   # Default layouts (body content only)
-│   ├── default.html
-│   └── full-width.html
-├── partials/                  # Default partials
-├── cms_forms/                 # Default form templates
-│   ├── form.html
-│   ├── field_text.html
-│   └── field_email.html
-├── translations/              # i18n files
-│   ├── en.json
-│   └── es.json
-├── page.html                  # Base HTML wrapper
-└── 404.html                   # Error page
-```
+### Architecture
 
-### Template Resolution Order
-1. Domain-specific: `templates/domains/{domain}/template.html`
-2. Default: `templates/template.html`
-3. Base: Package default templates
+The CMS follows a modular architecture with specialized classes:
 
-### Template Functions
+- **Manager** - Main CMS orchestrator
+- **Frontend** - Frontend operations coordinator
+- **Admin Manager** - Admin panel orchestrator
+- **Template Engine** - Template processing and rendering
+- **Dynamic Forms** - Form validation and processing
+- **Search** - Multi-entity search functionality
+- **Cache** - Domain and path-based caching
 
-**Entity Rendering:**
-```html
-<entity name="cmsBlocks" field="name" value="header-main"/>
-<entity name="articles" id="123"/>
-```
+See `.claude/architecture-guide.md` for detailed architecture documentation.
 
-**Collection Loops:**
-```html
-<collection name="articles" filters="{featured: true}" data="{limit: 5, sortBy: 'created_at', sortDirection: 'desc'}">
-    <div class="article">
-        <h3>{{row.title}}</h3>
-        <p>{{row.summary}}</p>
-    </div>
-</collection>
-```
+### SEO: Sitemaps and Robots.txt
 
-**Pagination:**
-```html
-<collection name="articles" filters="{}" data="{limit: 10}" pagination="articles-list" container="pagedCollection" prevPages="2" nextPages="2">
-    <article>{{row.title}}</article>
-</collection>
-```
+The CMS provides built-in support for dynamic robots.txt and sitemap.xml generation:
 
-**Dynamic Forms:**
-```html
-<cmsForm key="contactForm" fields="name,email,message" submitButtonText="Send Message"/>
-```
+- `/robots.txt` - Static template with sitemap reference
+- `/sitemap.xml` - Dynamic sitemap with automatic domain filtering
 
-**Partials (HTML-style):**
-```html
-<partial name="hero"
-    title="Welcome"
-    subtitle="To our site"
-    imageUrl="/img/hero.jpg"/>
-```
+See `.claude/seo-guide.md` for detailed SEO documentation.
 
-**Partials (Mustache-style):**
-```html
-{{>cardView -{row}-}}
-{{>hero -{title: "Welcome", subtitle: "To our site"}-}}
-```
+### Template System
 
-**System Variables:**
-```html
-{{currentRequest.host}}
-{{currentRequest.path}}
-{{currentRoute.title}}
-{{currentDomain.current}}
-{{systemInfo.timestamp}}
-{{currentEntity.title}}  <!-- In child blocks -->
-```
+Templates use a three-layer rendering system:
+
+1. **Content Processing** - Variables, collections, entities, and forms
+2. **Layout Wrapping** - Header, sidebar, footer structure
+3. **Template Wrapping** - Final HTML document structure
 
 **Template Functions:**
 ```html
-[url(/articles)]                    <!-- URL generation (no CDN) -->
-[cdn(/css/styles.css)]              <!-- CDN URL (or public URL if no CDN) -->
-[asset(/web/logo.png)]              <!-- Asset URL with /assets prefix (uses CDN if available) -->
-[date(now, Y-m-d)]                  <!-- Date formatting -->
-[translate(welcome.message)]        <!-- i18n -->
-[t(key, Default, {var: value})]     <!-- i18n with interpolation -->
+<entity name="cmsBlocks" field="name" value="header-main"/>
+<collection name="articles" filters="{featured: true}">
+    <h3>{{row.title}}</h3>
+</collection>
+<cmsForm key="contactForm"/>
+[url(/articles)]
+[cdn(/css/styles.css)]
+[asset(/web/logo.png)]
+[date(now, Y-m-d)]
+[translate(welcome.message)]
 ```
 
-**URL Transformer Selection:**
-- `[url()]` - Application routes (never uses CDN)
-- `[cdn()]` - Static assets outside `/assets` (CSS, JS, fonts)
-- `[asset()]` - Static assets inside `/assets` folder (images, media)
-
-See `.claude/templating-system-guide.md` for detailed URL transformer documentation.
+See `.claude/templating-system-guide.md` for detailed template documentation.
 
-## Configuration
+### Configuration
 
-### Environment Variables (.env)
+**Environment Variables (.env):**
 ```bash
-# Server
 RELDENS_APP_HOST=http://localhost
 RELDENS_APP_PORT=8080
-
-# Admin
 RELDENS_ADMIN_ROUTE_PATH=/admin
 RELDENS_ADMIN_SECRET=your-secret-key
-
-# Database
 RELDENS_DB_CLIENT=mysql
-RELDENS_DB_HOST=localhost
-RELDENS_DB_PORT=3306
-RELDENS_DB_NAME=cms_db
-RELDENS_DB_USER=username
-RELDENS_DB_PASSWORD=password
 RELDENS_STORAGE_DRIVER=prisma
-
-# Multi-domain
-RELDENS_DEFAULT_DOMAIN=example.com
-RELDENS_DOMAIN_MAPPING={"dev.example.com":"development"}
-RELDENS_SITE_KEY_MAPPING={"example.com":"main"}
-RELDENS_DOMAIN_PUBLIC_URL_MAPPING={"example.com":"https://cdn.example.com"}
-RELDENS_DOMAIN_CDN_MAPPING={"example.com":"https://cdn.example.com"}
 ```
 
-### Manager Configuration
+**Manager Configuration:**
 ```javascript
 const { Manager } = require('@reldens/cms');
 
 const cms = new Manager({
     projectRoot: process.cwd(),
-
-    // Entity access control
     entityAccess: {
-        articles: { public: true, operations: ['read'] },
-        cmsPages: { public: true, operations: ['read'] },
-        users: { public: false }
+        articles: { public: true, operations: ['read'] }
     },
-
-    // Authentication
-    authenticationMethod: 'db-users',  // or 'custom'
-    authenticationCallback: async (email, password, roleId) => {
-        // Custom auth logic
-    },
-    adminRoleId: 99,
-
-    // Password encryption (enabled by default)
-    enablePasswordEncryption: true,  // Set to false to disable
-
-    // Performance
+    authenticationMethod: 'db-users',
+    enablePasswordEncryption: true,
     cache: true,
-    reloadTime: -1,  // Development: reload on every request
-    // reloadTime: 0,  // Production: disable reloading
-
-    // Multi-domain
-    defaultDomain: 'example.com',
-    domainMapping: {'dev.example.com': 'development'},
-    siteKeyMapping: {'example.com': 'main'},
-
-    // Custom entities and translations
-    entitiesConfig: {},
-    entitiesTranslations: {},
-    adminTranslations: {}
+    reloadTime: -1,
+    defaultDomain: 'example.com'
 });
 
 await cms.start();
 ```
 
-## Event System
+See `.claude/configuration-guide.md` for detailed configuration documentation.
+
+### Event System
 
 The CMS provides extensive event hooks for customization:
 
-### Manager Events
+**Manager Events:**
 - `reldens.cmsManagerInitializeServices` - Before service initialization
 - `reldens.manager.initializeAdminManager` - Before admin initialization
 
-### Template Events
+**Template Events:**
 - `reldens.afterVariablesCreated` - Modify system variables
 - `reldens.beforeContentProcess` - Before template processing
 - `reldens.afterContentProcess` - After template processing
 
-### Form Events
-- `reldens.formsTransformer.beforeRender` - Before form rendering
-- `reldens.formsTransformer.afterRender` - After form rendering
-- `reldens.dynamicForm.beforeValidation` - Before validation
-- `reldens.dynamicForm.afterValidation` - After validation
-- `reldens.dynamicForm.beforeSave` - Before saving
-- `reldens.dynamicForm.afterSave` - After successful save
-- `reldens.dynamicFormRequestHandler.beforeSave` - Before request save
-
-### Admin Events
-- `reldens.setupAdminRouter` - Setup admin routes
-- `reldens.setupAdminRoutes` - After route setup
-- `reldens.setupAdminManagers` - After manager setup
-- `reldens.adminBeforeEntitySave` - Before entity save (used by password encryption handler)
+**Admin Events:**
+- `reldens.adminBeforeEntitySave` - Before entity save
 - `reldens.adminAfterEntitySave` - After entity save
-- `reldens.adminViewPropertiesPopulation` - Add content to view pages
-- `reldens.adminEditPropertiesPopulation` - Add content to edit pages
-- `reldens.adminListPropertiesPopulation` - Add content to list pages
-
-### Template Reloading Events
-- `reldens.templateReloader.templatesChanged` - Templates changed
-
-See `.claude/advanced-usage-guide.md` for comprehensive event-driven customization patterns and examples.
-
-## Development Workflow
 
-### Template Reloading
-Set `reloadTime: -1` in Manager configuration for development:
-- Admin templates reload automatically when files change
-- Frontend templates reload on next page load
-- No server restart needed
-- Zero performance impact in production (`reloadTime: 0`)
+See `.claude/advanced-usage-guide.md` for comprehensive event-driven customization patterns.
 
-### Entity Generation
-```bash
-# Generate entities from database schema
-npx reldens-cms-generate-entities
-
-# Or programmatically
-await dataServer.generateEntities();
-```
+### Entity Config Overrides
 
-### Custom Entities
-Define custom entity configurations in `entitiesConfig`:
-```javascript
-{
-    articles: {
-        listProperties: ['title', 'status', 'created_at'],
-        showProperties: ['title', 'content', 'author'],
-        editProperties: ['title', 'content', 'author_id'],
-        filterProperties: ['status', 'author_id'],
-        titleProperty: 'title',
-        parentItemLabel: 'Content',
-        properties: {
-            title: { type: 'string', isRequired: true },
-            content: { type: 'text' },
-            author_id: { type: 'reference', reference: 'users' },
-            featured_image: {
-                type: 'string',
-                isUpload: true,
-                allowedTypes: 'image',
-                bucket: 'uploads'
-            }
-        }
-    }
-}
-```
+Override generated entity configurations without editing generated files:
 
-### Entity Config Overrides
-Override generated entity configurations without editing generated files using `entitiesConfigOverride`:
 ```javascript
 class CmsPagesOverride
 {
-
-    /**
-     * @param {Object} baseConfig
-     * @param {Object} props
-     * @returns {Object}
-     */
     static propertiesConfig(baseConfig, props)
     {
         baseConfig.properties.meta_og_image = {
@@ -597,61 +164,19 @@ class CmsPagesOverride
         };
         return baseConfig;
     }
-
 }
 
 const manager = new Manager({
     entitiesConfigOverride: {
-        'cmsPages': CmsPagesOverride  // Use camelCase key from entities-config.js
+        'cmsPages': CmsPagesOverride
     }
 });
 ```
 
-**CRITICAL: Entity keys must match exactly as defined in `generated-entities/entities-config.js`**
-- Use camelCase: `'cmsPages'`, `'cmsBlocks'`, `'cmsForms'`
-- NOT kebab-case: `'cms-pages'`, `'cms-blocks'`, `'cms-forms'`
-
-Supports three override patterns:
-- **Class-based**: Class with static `propertiesConfig(baseConfig, props)` method
-- **Function-based**: Function that receives `(baseConfig, props)` and returns modified config
-- **Object-based**: Plain object that gets deep merged with base config
-
-**Upload Field Configuration:**
-- `allowedTypes`: Must be a STRING ('image', 'audio', 'text'), NOT an array
-- `bucket`: Relative path from projectRoot (e.g., 'public/assets/media')
-- `bucketPath`: URL path for display (e.g., '/assets/media/')
-- Do NOT use spread syntax - replace entire property object
-- Do NOT use FileHandler.joinPaths() - bucket paths are relative to projectRoot
-
-**Upload Field Removal:**
-- Admin edit pages automatically show an "X" button before uploaded filenames
-- Clicking X creates hidden input `clear_fieldname=1` in form
-- Server detects this and sets field to null in database
-- File remains on disk - only database field is cleared
-- Template: `admin/templates/fields/edit/file-claude.html`
-- Client JS: `admin/reldens-admin-client-claude.js` (remove upload functionality)
-- Server handling: `lib/admin-manager/router-contents-claude.js` (clear_ parameter detection)
-
-**Example subscribers**: See `lib/cache/add-cache-button-subscriber.js` and `lib/cache/save-and-clear-cache-subscriber.js` for complete working examples of event-driven UI customizations.
+**CRITICAL:** Entity keys must match exactly as defined in `generated-entities/entities-config.js` (use camelCase: `'cmsPages'`, NOT kebab-case: `'cms-pages'`).
 
 See `.claude/advanced-usage-guide.md` for detailed examples.
 
-## Security Features
-
-- **Authentication** - Role-based admin access
-- **Password Encryption** - PBKDF2 with 100k iterations, SHA-512
-- **Automatic Password Encryption** - Event-driven encryption on save (enabled by default)
-- **CSRF Protection** - Via session tokens
-- **File Upload Validation** - MIME type and extension checking
-- **Entity Access Control** - Public/private entity rules
-- **Honeypot Protection** - Bot detection in forms
-- **Rate Limiting** - Via @reldens/server-utils
-- **XSS Protection** - Input sanitization via @reldens/server-utils
-- **SQL Injection Prevention** - Via Prisma ORM
-- **Path Validation** - File path security
-- **CSP Headers** - Content Security Policy via Helmet
-- **HTTPS Support** - SSL/TLS configuration
-
 ## Important Implementation Notes
 
 1. **Always use specialized tools over bash** for file operations (Read, Edit, Write)
@@ -666,6 +191,10 @@ See `.claude/advanced-usage-guide.md` for detailed examples.
 10. **Multi-domain requires proper configuration** - set up domain mapping correctly
 11. **Password encryption is automatic** - enabled by default for users entity
 12. **Never store plain text passwords** - always use Encryptor.encryptPassword()
+13. **Template extensions are consistent** - Manager, Frontend, TemplateResolver, and TemplateCache all use the same default extensions: `['.html', '.mustache', '.template', '.txt', '.xml', '.json']`
+14. **Template names omit extensions** - Database template/layout fields should never include file extensions; the resolver automatically tries all configured extensions
+15. **Sitemap generation is event-driven** - SitemapLoader listens to `reldens.afterVariablesCreated` and populates `sitemapPages` variable; data is cached on `req.sitemapPages` to avoid duplicate queries during multi-pass template rendering
+16. **buildEnhancedRenderData merges all system variables** - Any custom variables added to `eventData.variables` in event listeners will automatically be available in templates via Mustache
 
 ## Common File Paths
 
@@ -681,27 +210,35 @@ See `.claude/advanced-usage-guide.md` for detailed examples.
 
 ## Troubleshooting
 
-### Installation Issues
+### Installation
+
 - Check database connection in `.env`
 - Ensure Prisma schema is valid
 - Verify Node.js version >= 20.0.0
 
-### Template Issues
-- Check template resolution order
+### Templates
+
+- Check logs for "Template not found" or "Template file not found" messages
+- Verify template files exist in correct locations (domain → default → base)
+- Ensure template names in database do NOT include file extensions
+- Check `templateExtensions` configuration includes required extensions
 - Verify domain mapping configuration
-- Enable template reloading for development
+- Enable template reloading for development (`reloadTime: -1`)
+
+### Forms
 
-### Form Issues
 - Validate JSON schema syntax
 - Check form key matches database
 - Verify field names in schema
 
-### Entity Issues
+### Entities
+
 - Regenerate entities after schema changes
 - Check entity access configuration
 - Verify relationship mappings
 
-### Password Issues
+### Passwords
+
 - Verify password is encrypted (contains `:` and is 192 chars)
 - Check `enablePasswordEncryption` is `true` in Manager config
 - Use CLI command for password updates: `npx reldens-cms-update-password`
@@ -717,6 +254,22 @@ See `.claude/advanced-usage-guide.md` for detailed examples.
 
 ## Additional Resources
 
+**Comprehensive Guides:**
+- `.claude/installation-guide.md` - Installation and setup
+- `.claude/architecture-guide.md` - Detailed architecture documentation
+- `.claude/configuration-guide.md` - Configuration options and examples
+- `.claude/database-schema.md` - Database tables and schema
+- `.claude/templating-system-guide.md` - Template system and functions
+- `.claude/forms-system-guide.md` - Dynamic forms system
+- `.claude/search-guide.md` - Search functionality
+- `.claude/multi-domain-i18n-guide.md` - Multi-domain and internationalization
+- `.claude/password-management-guide.md` - Password management
+- `.claude/seo-guide.md` - SEO, sitemaps, and robots.txt
+- `.claude/security-guide.md` - Security features and best practices
+- `.claude/advanced-usage-guide.md` - Advanced customization and event patterns
+- `.claude/api-reference.md` - API reference documentation
+
+**Other Resources:**
 - Main README.md for user documentation
 - Package.json for dependency versions
 - License: MIT