diff --git a/TEMPLATE_DOCUMENTATION.md b/TEMPLATE_DOCUMENTATION.md
new file mode 100644
index 00000000..646c0bdf
--- /dev/null
+++ b/TEMPLATE_DOCUMENTATION.md
@@ -0,0 +1,282 @@
+# Template Documentation - Dynamic Lists Widget
+
+## Overview
+The Dynamic Lists widget uses Handlebars templating system to render both the configuration interface and the runtime display. Templates are organized by purpose and layout type.
+
+## Template Categories
+
+### 1. Interface Templates (`templates/interface/`)
+Used for the widget configuration interface in Fliplet Studio.
+
+#### `layouts.interface.hbs`
+Renders the layout selection grid showing available layout options.
+
+**Context Variables:**
+- `id`: Layout identifier
+- `name`: Display name
+- `description`: Layout description
+- `warning`: Optional warning message
+- `gif`: Animated preview image URL
+- `image`: Static preview image URL
+
+#### `filter-panels.interface.hbs`
+Creates filter configuration panels in the interface.
+
+#### `sort-panels.interface.hbs`
+Creates sort configuration panels in the interface.
+
+#### `summary-view-panels.interface.hbs`
+Configures which data fields appear in the summary/list view.
+
+#### `detail-view-panels.interface.hbs`
+Configures which data fields appear in the detail view.
+
+#### `field-token.interface.hbs`
+Renders individual field tokens for drag-and-drop configuration.
+
+### 2. Build Templates (`templates/build/`)
+Used for runtime rendering of the widget content.
+
+#### Base Templates (`[layout]-base.build.hbs`)
+Main structure template for each layout containing:
+- Container wrapper
+- Search interface
+- Filter controls
+- Sort controls
+- Loading states
+- Error states
+- Detail view overlay
+- Social interaction panels
+
+**Example Structure (simple-list-base.build.hbs):**
+```handlebars
+
+
+ {{#if searchEnabled}}
+
+ {{/if}}
+
+
+
+
+
+
+
+
+
+
+
+```
+
+#### Loop Templates (`[layout]-loop.build.hbs`)
+Defines how individual data items are rendered in the list.
+
+**Example Structure (simple-list-loop.build.hbs):**
+```handlebars
+{{#each this}}
+
+ {{#if [Image]}}
+
+ {{/if}}
+
+
+ {{#if [Title]}}
+
{{[Title]}}
+ {{/if}}
+
+ {{#if [Description]}}
+
{{plaintext [Description]}}
+ {{/if}}
+
+
+
+ {{#if likesEnabled}}
+
+
+
+ {{/if}}
+
+
+
+{{/each}}
+```
+
+#### Detail Templates (`[layout]-detail.build.hbs`)
+Renders the expanded detail view for individual items.
+
+#### Filter Templates (`[layout]-filters.build.hbs`)
+Renders filter controls specific to each layout.
+
+#### Additional Templates
+- `[layout]-comment.build.hbs`: Comment display template
+- `[layout]-single-comment.build.hbs`: Individual comment template
+- `[layout]-temp-comment.build.hbs`: Temporary comment template during submission
+
+### 3. Specialized Templates
+
+#### Agenda Layout Templates
+- `agenda-cards-*.build.hbs`: Card-based agenda items
+- `agenda-dates-loop.build.hbs`: Date grouping for agenda
+- `agenda-filters.build.hbs`: Date-based filtering
+
+#### News Feed Templates
+- `news-feed-*.build.hbs`: Social media style feed layout
+- Supports comments, likes, and social interactions
+
+#### Directory Templates
+- `small-card-*.build.hbs`: Directory-style people listings
+- `small-card-profile-icon.build.hbs`: Profile icon display
+- `small-card-user-profile.build.hbs`: User profile card
+
+## Template Variables
+
+### Common Context Variables
+All templates receive these standard variables:
+
+#### Widget Configuration
+- `id`: Widget instance ID
+- `layout`: Selected layout type
+- `searchEnabled`: Boolean for search functionality
+- `filtersEnabled`: Boolean for filtering
+- `sortEnabled`: Boolean for sorting
+- `likesEnabled`: Boolean for likes feature
+- `bookmarksEnabled`: Boolean for bookmarks
+- `commentsEnabled`: Boolean for comments
+
+#### Data Entry Variables
+- `[Title]`: Entry title field
+- `[Description]`: Entry description field
+- `[Image]`: Entry image field
+- `[Category]`: Entry category field
+- `[Date]`: Entry date field
+- `[flClasses]`: CSS classes for filtering/sorting
+- `id`: Entry unique identifier
+
+#### UI State Variables
+- `filtersInOverlay`: Boolean for filter overlay display
+- `searchIconsEnabled`: Boolean for search icon display
+- `showAddEntry`: Boolean for add entry button
+- `previousScreen`: Boolean for navigation state
+- `enabledLimitEntries`: Boolean for entry limiting
+- `limitEntries`: Number of entries to limit
+
+### Template Helpers
+
+#### Built-in Helpers
+- `{{#if condition}}`: Conditional rendering
+- `{{#unless condition}}`: Negative conditional
+- `{{#each array}}`: Loop over arrays
+- `{{#ifCond a '==' b}}`: Conditional comparison
+
+#### Custom Helpers
+- `{{auth url}}`: Authentication-aware URL handling
+- `{{plaintext text}}`: Strip HTML from text
+- `{{T "key"}}`: Translation/internationalization
+- `{{[fieldName]}}`: Dynamic field access
+
+## Template Compilation
+
+Templates are pre-compiled into JavaScript files:
+- `js/build.templates.js`: Runtime templates
+- `js/interface.templates.js`: Interface templates
+
+Access compiled templates via:
+```javascript
+Fliplet.Widget.Templates['templates.build.template-name']
+Fliplet.Widget.Templates['templates.interface.template-name']
+```
+
+## Customization Guidelines
+
+### Adding New Templates
+1. Create `.hbs` file in appropriate directory
+2. Follow naming convention: `[layout]-[purpose].build.hbs`
+3. Recompile templates after changes
+4. Update template references in JavaScript
+
+### Template Best Practices
+1. **Accessibility**: Include proper ARIA labels and roles
+2. **Responsive Design**: Use appropriate CSS classes
+3. **Performance**: Minimize template complexity
+4. **Localization**: Use `{{T "key"}}` for all user-facing text
+5. **Data Binding**: Use `{{[fieldName]}}` for dynamic fields
+
+### Common Patterns
+
+#### Conditional Rendering
+```handlebars
+{{#if fieldName}}
+