jeboehm · jeboehm · Feb 8, 2026 · Feb 3, 2026
diff --git a/.cursor/rules/learned-memories.mdc b/.cursor/rules/learned-memories.mdc
diff --git a/.env.dist b/.env.dist
@@ -34,15 +34,16 @@ DOVEADM_API_KEY=changeme2
 WAITSTART_TIMEOUT=2m
 
 # Configure local address extension
-# @see docs/configuration/local-address-extension.md
+# Check the documentation for more information.
 RECIPIENT_DELIMITER=-
 
 # Interval in seconds for fetchmail to check for new mails
 FETCHMAIL_INTERVAL=300
 
-## @see docs/REVERSE_PROXY.md
 # Expects the PROXY protocol on imap(s) and pop3(s) ports
+# Check the documentation for more information.
 MDA_UPSTREAM_PROXY=false
 
 # Expects the PROXY protocol on smtp and submission ports
+# Check the documentation for more information.
 MTA_UPSTREAM_PROXY=false
diff --git a/.mkdocs.yaml b/.mkdocs.yaml
@@ -15,40 +15,49 @@ exclude_docs: |
   requirements.txt
 nav:
   - Welcome: README.md
-  - Quick Start:
-      - installation.md
-      - upgrade.md
-  - Configuration:
-      - configuration/environment-variables.md
-      - "mailserver-admin": configuration/mailserver-admin.md
-      - configuration/dns-configuration.md
-      - configuration/external-mysql.md
-      - configuration/relayhost.md
-      - configuration/local-address-extension.md
-      - configuration/php-sessions.md
-      - configuration/reverse-proxy.md
-      - configuration/roundcube.md
-      - configuration/tls.md
-  - Administration:
-      - administration/login.md
-      - administration/dashboard.md
-      - administration/manage-domains.md
-      - administration/manage-users.md
-      - administration/manage-aliases.md
-      - administration/manage-fetchmail.md
-      - administration/dkim-signing.md
-      - administration/dns-validation-wizard.md
-      - administration/user-roles.md
-      - administration/ios-macos-profile.md
-  - Observability:
-      - observability/intro.md
+  - Tutorial:
+      - Getting Started: tutorials/getting-started.md
+  - How-to guides:
+      - Install with Docker: how-to/install-docker.md
+      - Install on Kubernetes: how-to/install-kubernetes.md
+      - Upgrade: how-to/upgrade.md
+      - Configure DNS: how-to/configure-dns.md
+      - Configure DKIM: how-to/configure-dkim.md
+      - Validate DNS (wizard): how-to/validate-dns.md
+      - Configure relay host: how-to/configure-relayhost.md
+      - Configure reverse proxy: how-to/configure-reverse-proxy.md
+      - Configure TLS certificates: how-to/configure-tls.md
+      - Configure OAuth2: how-to/configure-oauth2.md
+      - Configure external MySQL: how-to/configure-external-mysql.md
+      - Configure Roundcube plugins: how-to/configure-roundcube-plugins.md
+      - Configure PHP sessions: how-to/configure-php-sessions.md
+      - Manage domains: how-to/manage-domains.md
+      - Manage users: how-to/manage-users.md
+      - Manage aliases: how-to/manage-aliases.md
+      - Manage fetchmail: how-to/manage-fetchmail.md
+      - iOS / macOS profile: how-to/ios-macos-profile.md
+  - Reference:
+      - Environment variables: reference/environment-variables.md
+      - Ports: reference/ports.md
+      - DNS records: reference/dns-records.md
+      - Service architecture: reference/service-architecture.md
+      - User roles: reference/user-roles.md
+      - mailserver-admin config: reference/mailserver-admin-config.md
+      - Local address extension: reference/local-address-extension.md
+      - Upgrade changelog: reference/upgrade-changelog.md
+  - Administration (web UI):
+      - Login: administration/login.md
+      - Dashboard: administration/dashboard.md
+  - Explanation:
+      - Service architecture: explanation/architecture.md
+      - DNS and email delivery: explanation/dns-and-email.md
+      - Observability: explanation/observability.md
   - Recipes:
       - Docker:
           - Traefik Reverse Proxy: https://github.com/jeboehm/docker-mailserver/tree/main/docs/example-configs/compose/traefik-reverse-proxy
       - Kubernetes:
           - External Database and HTTPS Ingress: https://github.com/jeboehm/docker-mailserver/tree/main/docs/example-configs/kustomize/external-db-and-https-ingress
   - Development:
-      - development/architecture.md
-      - development/development.md
-      - "mailserver-admin": development/mailserver-admin.md
+      - Development guide: development/development.md
+      - mailserver-admin development: development/mailserver-admin.md
   - Issues: https://github.com/jeboehm/docker-mailserver/issues
diff --git a/AGENTS.md b/AGENTS.md
@@ -0,0 +1,61 @@
+# Agent instructions for docker-mailserver
+
+This file gives AI agents and contributors the project conventions, documentation framework, and structure they need to work consistently on the codebase and docs.
+
+## Documentation framework: Diátaxis
+
+Documentation follows **[Diátaxis](https://diataxis.fr)** (“A systematic approach to technical documentation authoring”). Diátaxis defines four kinds of documentation, each with a different purpose and style:
+
+| Kind             | Purpose                      | Serves                       | Style                                                                                                                      |
+| ---------------- | ---------------------------- | ---------------------------- | -------------------------------------------------------------------------------------------------------------------------- |
+| **Tutorial**     | Learning by doing            | Acquisition of skill (study) | Lesson: take the learner through a concrete path; minimal explanation; visible results early; one main path, no branching. |
+| **How-to guide** | Accomplish a specific task   | Application of skill (work)  | Task-oriented: clear steps to reach a goal; for users who already know what they want; no teaching, no long explanations.  |
+| **Reference**    | Look up facts                | Application of skill (work)  | Technical description: accurate, complete, neutral; structure mirrors the product; consulted, not read.                    |
+| **Explanation**  | Understand context and “why” | Acquisition of skill (study) | Background and discussion: design, trade-offs, connections; can include opinion and perspective.                           |
+
+**Guidelines:**
+
+- **Tutorials:** One or few. One main path; show the result early; avoid options and long explanations; link to reference/explanation for depth.
+- **How-to guides:** One goal per guide; title = “How to …”; steps only; link to reference for options and formats.
+- **Reference:** Describe the machinery (env vars, ports, record formats, APIs); austere; structured like the product; no instruction or opinion.
+- **Explanation:** Answer “why?” and “how does it fit together?”; can compare alternatives and give context; do not mix in procedures or reference tables.
+
+Do not mix the four types in a single doc. When in doubt, use the [Diátaxis compass](https://diataxis.fr/compass/): “Does it inform action or cognition? Does it serve study or work?”
+
+## Documentation structure (docs/)
+
+The docs are organised by Diátaxis type:
+
+- **`tutorials/`** — Learning path (e.g. `getting-started.md`).
+- **`how-to/`** — Task guides: install (Docker/Kubernetes), upgrade, configure (DNS, DKIM, TLS, relay, reverse proxy, OAuth2, MySQL, Roundcube, PHP sessions), manage (domains, users, aliases, fetchmail), iOS/macOS profile.
+- **`reference/`** — Technical reference: `environment-variables.md`, `ports.md`, `dns-records.md`, `service-architecture.md`, `user-roles.md`, `mailserver-admin-config.md`, `local-address-extension.md`, `upgrade-changelog.md`.
+- **`explanation/`** — Context: `architecture.md`, `dns-and-email.md`, `observability.md`.
+- **`administration/`** — Short reference for the web UI: `login.md`, `dashboard.md`; other admin topics live as how-to or reference and are linked from here.
+- **`configuration/`** — Legacy entry points; these files redirect to the appropriate how-to or reference.
+- **`development/`** — Developer how-to: `development.md` (Make, test, lint), `mailserver-admin.md` (mailserver-admin repository setup); `architecture.md` redirects to reference + explanation.
+- **`observability/`** — `intro.md` redirects to `explanation/observability.md`.
+
+MkDocs config is **`.mkdocs.yaml`**; the `nav` there reflects this structure (Tutorial, How-to guides, Reference, Administration, Explanation, Recipes, Development).
+
+## Documentation writing style
+
+- Use **technical documentation language**, not marketing. Avoid subjective terms (“powerful”, “particularly useful”, “sophisticated”).
+- Use **direct, factual** statements about what the software does. Include **technical references** (e.g. RFCs) and **concrete examples** where useful.
+- Focus on **implementation and configuration**; keep prose concise and suitable for technical readers.
+- Prefer **functional descriptions** over promotional copy.
+
+## Project structure
+
+- **Architecture:** The mailserver is made of multiple containers/pods (MTA, MDA, Web, Filter, SSL, Database, Redis, Unbound, Fetchmail) that together provide mail and management.
+- **Container images:** Built under **`target/`**. Each subdirectory is one service (e.g. `target/mta/`, `target/mda/`, `target/filter/`, `target/web/`, `target/db/`, `target/unbound/`, `target/ssl/`).
+- **Deployment manifests:**
+  - **Docker Compose:** `deploy/compose/` (e.g. `mta.yaml`, `mda.yaml`, `web.yaml`, `db.yaml`).
+  - **Kubernetes (Kustomize):** `deploy/kustomize/` (e.g. `mta/`, `mda/`, `web/`, `ingress/`).
+- **Deployment consistency:** The same capabilities should be reflected in both Compose and Kustomize. When you change one (e.g. env vars, volumes, services), update the other so Docker and Kubernetes deployments stay in parity.
+
+## Quick reference for agents
+
+- **Adding a new feature that needs docs:** Add or update the right Diátaxis type (tutorial step, how-to, reference section, or explanation). Keep one purpose per doc; link between them.
+- **Adding env vars or ports:** Document in **`reference/environment-variables.md`** or **`reference/ports.md`**; mention in the relevant how-to if it affects a procedure.
+- **Adding a new how-to:** Create under **`how-to/`** with a “How to …” title; add the page to **`.mkdocs.yaml`** under “How-to guides”.
+- **Changing deployment (Compose or Kustomize):** Apply the same logical change in **`deploy/compose/`** and **`deploy/kustomize/`** where applicable.
diff --git a/docs/README.md b/docs/README.md
@@ -8,58 +8,69 @@
 
 This project enables you to operate your own email services, providing independence from large email providers. The solution is built on Alpine Linux and vendor base images, keeping container images lightweight while maintaining comprehensive functionality.
 
-## Key Features
-
-- **Email Protocols**: POP3, IMAP, and SMTP with user authentication
-- **Web Management**: Web-based interface for account, domain, and alias administration
-- **Webmail**: Integrated webmail interface
-- **External Mail Retrieval**: Fetchmail integration for retrieving emails from external providers
-- **Email Authentication**: DKIM message signing for email authenticity
-- **Spam Filtering**: Server-side mail filtering with configurable rules via web frontend
-- **Spam Training**: Train spam filters by moving emails to or from the junk folder
-- **Real-time Protection**: RBL (Real-Time Blackhole List) integration for spam prevention
-- **Greylisting**: Selective greylisting for likely spam
-- **Address Management**: Support for catch-all addresses and send-only accounts
-- **Security**: Sender address restrictions and configurable address extensions
-- **Quota Management**: Email quota management with notifications
-- **TLS**: Enforced TLS for secure communication
-- **Full-Text Search**: FTS support for efficient message searching
-- **Health Monitoring**: Continuous self-monitoring via Docker healthcheck
-
-## Quick Start
-
-1. **[Installation Guide](installation.md)** - Get started with Docker or Kubernetes deployment
-2. **[Upgrade Guide](upgrade.md)** - Upgrade procedures and version migration notes
-
-## Service Architecture
+## Documentation structure
+
+The documentation is organised by purpose:
+
+- **[Tutorial: Getting Started](tutorials/getting-started.md)** — A step-by-step lesson to install docker-mailserver with Docker Compose and create your first mailbox.
+- **How-to guides** — Task-oriented guides for specific goals (install on Kubernetes, configure DNS, manage users, configure TLS, and more). See the [How-to](how-to/install-docker.md) section in the navigation.
+- **Reference** — Technical descriptions: [environment variables](reference/environment-variables.md), [DNS records](reference/dns-records.md), [ports](reference/ports.md), [service architecture](reference/service-architecture.md), [user roles](reference/user-roles.md), and related topics.
+- **Explanation** — Background and context: [architecture](explanation/architecture.md), [DNS and email delivery](explanation/dns-and-email.md), [observability](explanation/observability.md).
+
+## Key features
+
+- **Email protocols:** POP3, IMAP, and SMTP with user authentication
+- **Web management:** Web-based interface for account, domain, and alias administration
+- **Webmail:** Integrated webmail interface
+- **External mail retrieval:** Fetchmail integration for retrieving emails from external providers
+- **Email authentication:** DKIM message signing for email authenticity
+- **Spam filtering:** Server-side mail filtering with configurable rules via web frontend
+- **Spam training:** Train spam filters by moving emails to or from the junk folder
+- **Real-time protection:** RBL integration for spam prevention
+- **Greylisting:** Selective greylisting for likely spam
+- **Address management:** Catch-all addresses, send-only accounts, local address extension (RFC 5233)
+- **Security:** Sender address restrictions and configurable address extensions
+- **Quota management:** Email quota management with notifications
+- **TLS:** Enforced TLS for secure communication
+- **Full-text search:** FTS support for efficient message searching
+- **Health monitoring:** Continuous self-monitoring via Docker healthcheck
+
+## Quick start
+
+1. **[Tutorial: Getting Started](tutorials/getting-started.md)** — Install with Docker Compose and create your first account
+2. **[How to install with Docker](how-to/install-docker.md)** — Docker Compose installation steps
+3. **[How to install on Kubernetes](how-to/install-kubernetes.md)** — Kubernetes deployment steps
+4. **[How to upgrade](how-to/upgrade.md)** — Upgrade procedures and [upgrade changelog](reference/upgrade-changelog.md)
+
+## Service architecture
 
 The mailserver consists of multiple microservices:
 
-- **MTA (Mail Transfer Agent)** - Postfix for SMTP
-- **MDA (Mail Delivery Agent)** - Dovecot for IMAP/POP3
-- **Web** - Admin interface and Roundcube webmail
-- **Filter** - RSpamd for spam filtering
-- **SSL** - Certificate generation and management
-- **Database** - MySQL for user and configuration data
-- **Redis** - Caching and session storage
-- **Unbound** - DNS resolver for the filter service
-- **Fetchmail** - External mail retrieval (optional)
+- **MTA (Mail Transfer Agent)** — Postfix for SMTP
+- **MDA (Mail Delivery Agent)** — Dovecot for IMAP/POP3
+- **Web** — Admin interface and Roundcube webmail
+- **Filter** — RSpamd for spam filtering
+- **SSL** — Certificate generation and management
+- **Database** — MySQL for user and configuration data
+- **Redis** — Caching and session storage
+- **Unbound** — DNS resolver for the filter service
+- **Fetchmail** — External mail retrieval (optional)
 
-See [Architecture Documentation](development/architecture.md) for detailed information.
+See [Service architecture reference](reference/service-architecture.md) for a concise list and [About the service architecture](explanation/architecture.md) for context.
 
-## Getting Help
+## Getting help
 
-- **[GitHub Issues](https://github.com/jeboehm/docker-mailserver/issues)** - Report bugs and request features
-- **[Releases](https://github.com/jeboehm/docker-mailserver/releases)** - View release notes and changelog
+- **[GitHub Issues](https://github.com/jeboehm/docker-mailserver/issues)** — Report bugs and request features
+- **[Releases](https://github.com/jeboehm/docker-mailserver/releases)** — View release notes and changelog
 
-## Container Images
+## Container images
 
 Container images are available at:
 
 - [GitHub Container Registry](https://github.com/jeboehm?tab=packages&repo_name=docker-mailserver)
 - [Docker Hub](https://hub.docker.com/u/jeboehm?page=1&search=mailserver)
 
-## Component References
+## Component references
 
 - [Dovecot Documentation](https://doc.dovecot.org/2.4.1/)
 - [Postfix Documentation](https://www.postfix.org/documentation.html)
@@ -68,6 +79,6 @@ Container images are available at:
 - [Redis Documentation](https://redis.io/docs/latest/)
 - [Unbound Documentation](https://unbound.docs.nlnetlabs.nl/en/latest/)
 
-## Star History
+## Star history
 
 [![Star History Chart](https://api.star-history.com/svg?repos=jeboehm/docker-mailserver&type=date&legend=top-left)](https://www.star-history.com/#jeboehm/docker-mailserver&type=date&legend=top-left)
diff --git a/docs/administration/dashboard.md b/docs/administration/dashboard.md
@@ -1,5 +1,7 @@
 # Dashboard
 
-The dashboard is the main page of the administration tool. It provides a quick overview of the mailserver and the most important information.
+The dashboard is the main page after login. It shows an overview of the mailserver: domains, users, and quick links to common tasks.
 
 ![Dashboard](../images/admin/dashboard.png)
+
+From the dashboard you can navigate to domain, user, alias, fetchmail, and DKIM management, and to the DNS Validation Wizard and observability dashboards when available.