diff --git a/docs/content-system.md b/docs/content-system.md
new file mode 100644
index 0000000..dcf032a
--- /dev/null
+++ b/docs/content-system.md
@@ -0,0 +1,163 @@
+# Content System Reference
+
+For LLM agents working with site content. Read when adding/modifying content or metadata.
+
+## Folder = URL
+
+Every directory under `content/` becomes a URL path. The folder name is the default slug.
+
+```
+content/nyheter/2025-09-26-banebrytende-studie/ -> /nyheter/banebrytende-studie/
+content/faq/Hva-er-MC/ -> /faq/hva-er-mc/
+content/kontakt/ -> /kontakt/
+```
+
+Date prefixes (`YYYY-MM-DD-`) are stripped from URLs and used as the item date.
+Numeric prefixes (`NN-`) control ordering and are stripped from URLs.
+
+## Content Files
+
+Place these inside a content directory:
+
+| File | Purpose |
+|---|---|
+| `article.md` or `index.md` | Main content (Markdown) |
+| `article.en.md` | English translation |
+| `index.html` | HTML content alternative |
+| `index.php` | PHP content (has access to `$GLOBALS['ctx']`) |
+| `metadata.ini` | Configuration for this directory |
+| `cover.png/jpg/webp` | Cover image for list display |
+| `styles.css` | Page-specific CSS |
+| `script.js` | Page-specific JS |
+| `*.pdf` | Downloadable PDF |
+
+Multiple content files in one directory are rendered in sequence (alphabetical order).
+
+## Page vs List Detection
+
+- Directory with **no subdirectories** (or `hide_list = true`) -> renders as **page** using `page.php`
+- Directory with **subdirectories** -> renders as **list** using `list.php` or `page_template` override
+
+## metadata.ini Reference
+
+### Core Fields
+
+```ini
+title = "Page Title" # Display title
+summary = "Short description" # Shown in lists and meta description
+date = "2026-01-15" # Explicit date (overrides folder date prefix)
+slug = "custom-url" # Custom URL segment (overrides folder name)
+```
+
+### Menu & Ordering
+
+```ini
+menu = true # Show in main navigation
+menu_order = 1 # Navigation sort order (lower = first)
+order = 5 # Sort order within parent list
+```
+
+### Display & Templates
+
+```ini
+page_template = "list-faq" # Override list template (list-card-grid, list-faq, list-grid)
+show_date = false # Hide dates in list display
+hide_list = true # Treat directory-with-subdirs as a page instead of list
+```
+
+### Feeds
+
+```ini
+feed = true # Enable Atom feed at /{section}/feed.xml
+author = "Stopp lidelsen" # Feed author name
+```
+
+When `feed = true` is set:
+1. `/{section}/feed.xml` serves Atom XML with full content of each item
+2. `$feedUrl` is set in template context, enabling `` in ``
+3. Feed includes all list items with rendered HTML content
+
+### Plugins
+
+```ini
+plugins = "petition-form" # Comma-separated page plugins to load
+petition_id = "my-petition" # Plugin-specific config
+thank_you_page = "takk" # Plugin-specific config
+```
+
+### Language Overrides
+
+```ini
+[en]
+title = "English Title"
+summary = "English description"
+slug = "english-url"
+```
+
+Language sections are merged into base metadata when that language is active. Any field can be overridden per language.
+
+### Metadata Priority
+
+Language-specific `[lang]` section > root fields > auto-extracted (date from folder name) > defaults
+
+### Categories & Tags
+
+```ini
+tags = "nyhetsbrev, oppsummering"
+categories = "Nyhetsbrev"
+
+[en]
+tags = "newsletter, summary"
+categories = "Newsletters"
+```
+
+Displayed by `page.php` template if present.
+
+## Current Site Sections
+
+| Section | Folder | Template | Menu | Feed | Notes |
+|---|---|---|---|---|---|
+| Home | `content/` | page | - | - | Has newsletter-signup plugin |
+| News | `content/nyheter/` | list | Yes (1) | Eligible | Date-prefixed articles |
+| Articles | `content/artikler/` | list | Yes (2) | - | Subsections with articles |
+| Brochures | `content/brosjyrer/` | list-card-grid | No | - | PDFs + redirects to articles |
+| FAQ | `content/faq/` | list-faq | Yes | - | Accordion layout |
+| Docs | `content/docs/` | list | No | - | Internal documentation |
+| Petitions | `content/underskriftskampanje/` | list | No | - | Has petition-form plugin |
+| Contact | `content/kontakt/` | page | Yes (10) | - | |
+| About | `content/om-oss/` | page | No | - | `hide_list=true` |
+| Privacy | `content/personvern/` | page | No | - | `hide_list=true` |
+
+## Adding Content
+
+### New Article in Existing Section
+
+```
+content/nyheter/YYYY-MM-DD-slug-name/
+ article.md # Norwegian content
+ article.en.md # English content (optional)
+ metadata.ini # tags, categories, [en] overrides
+ cover.png # Optional cover image
+```
+
+### New Section
+
+```
+content/new-section/
+ metadata.ini # menu=true, menu_order=N, page_template=...
+ article.md # Intro content (shown above list)
+ subsection-1/
+ article.md
+ metadata.ini
+ subsection-2/
+ ...
+```
+
+## Language System
+
+- Default language: Norwegian (`no`)
+- Available: `no`, `en` (configured in `custom/config.ini`)
+- Norwegian URLs: `/nyheter/`, `/faq/`, etc.
+- English URLs: `/en/news/`, `/en/faq/`, etc. (with `slug` from `[en]` section)
+- Content files: `article.md` (Norwegian), `article.en.md` (English)
+- Translation strings: `custom/languages/no.ini`, `custom/languages/en.ini`
diff --git a/docs/newsletter-plugin.md b/docs/newsletter-plugin.md
new file mode 100644
index 0000000..a9fa898
--- /dev/null
+++ b/docs/newsletter-plugin.md
@@ -0,0 +1,94 @@
+# Newsletter Plugin Reference
+
+For LLM agents working on the newsletter signup. Read when modifying newsletter functionality.
+
+## Overview
+
+Modular newsletter signup that can be embedded on any page. Uses Listmonk's public subscription API for double opt-in. Located in `custom/plugins/page/newsletter-signup.php`.
+
+## How It Activates
+
+Add to a page's `metadata.ini`:
+```ini
+plugins = "newsletter-signup"
+```
+
+Then call from PHP content files:
+```php
+
+
+```
+
+## Themes
+
+| Theme | Description | HTML Element |
+|---|---|---|
+| `hero` | Full-width gradient background section (green->blue). Centered form with pill-shaped inputs. | `` |
+| `small` | Compact inline box with green border. Fits between paragraphs. | `