docs: Revise accounts overview section

Revised the account section and added additional clarity for common confusion with relation to sender address and multi-domain support.

Top of the page now clarifies it's a technical reference and directs users to the related pages for configuration / caveats.

Technical Overview links to Dovecot docs were missing.

docs/content/config/account-management/overview.md

@@ -1,37 +1,67 @@
 # Account Management - Overview
 
-## Mail Accounts - Domains, Addresses, Aliases
+This page provides a technical reference for account management in DMS.
 
-**TODO:** `ACCOUNT_PROVISIONER` and supplementary pages referenced here.
+!!! note "Account provisioners and alternative authentication support"
 
-!!! info
+    Each [`ACCOUNT_PROVISIONER`][docs::env::account-provisioner] has a separate page for configuration guidance and caveats:
 
-    In the DMS docs, there may be references to the sub-components of an address (`local-part@domain-part`).
+    - [`FILE` provisioner docs][docs::account-provisioner::file]
+    - [`LDAP` provisioner docs][docs::account-provisioner::ldap]
 
-### Accounts
+    Authentication from the provisioner can be supplemented with additional methods:
 
-To receive or send mail, you'll need to provision users into DMS with accounts. A DMS account will provide information such as their email address, login username, and any aliases.
+    - [OAuth2 / OIDC][docs::account-auth::oauth2] (_allow login from an external authentication service_)
+    - [Master Accounts][docs::account-auth::master-accounts] (_access the mailbox of any DMS account_)
 
-The email address assigned to an account is relevant for:
+    ---
 
-- Receiving delivery to an inbox, when DMS receives mail for that address as the recipient (_or an alias that resolves to it_).
+    For custom authentication requirements, you could [implement this with Lua][docs::examples::auth-lua].
-- Mail submission with:
-    - `SPOOF_PROTECTION=1` restricts the sender address to the DMS account email address, unless additional sender addresses have been permitted via supported config.
-    - `SPOOF_PROTECTION=0` allows DMS accounts to use any sender address, only a single DMS account is necessary to send mail with different sender addresses.
 
-??? warning "Email address considerations"
+## Accounts
 
-    An email address should conform to the standard [permitted charset and format](https://stackoverflow.com/questions/2049502/what-characters-are-allowed-in-an-email-address/2049510#2049510).
+To receive or send mail, you'll need to provision user accounts into DMS (_as each provisioner page demonstrates_).
 
-    DMS has features that need to reserve special characters to work correctly. Ensure those characters are not present in email addresses you configure for DMS, or disable / opt-out of the feature.
+A DMS account represents a user with their login username + password, along with related features like aliases and quotas.
 
-    - [Sub-addressing](#sub-addressing) is enabled by default with the _tag delimiter_ `+`. This can be configured, or be unset to opt-out.
+- Sending mail from different addresses **does not require** aliases or separate accounts.
+- Each account is configured with a _primary email address_ that a mailbox is associated to. Aliases allow for sharing delivery to a common mailbox.
+
+??? info "Primary email address"
+
+    The email address associated to an account creates a mailbox. This address is relevant:
+
+    - When DMS **receives mail** for that address as the recipient (_or an alias that resolves to it_), to identify which mailbox to deliver into.
+    - With **mail submission**:
+        - `SPOOF_PROTECTION=1` **restricts the sender address** to the DMS account email address (_unless additional sender addresses have been permitted via supported config_).
+        - `SPOOF_PROTECTION=0` allows DMS accounts to **use any sender address** (_only a single DMS account is necessary to send mail with different sender addresses_).
+
+    ---
+
+    For more details, see the [Technical Overview](#technical-overview) section.
+
+??? note "Support for multiple mail domains"
+
+    No extra configuration in DMS is required after provisioning an account with an email address.
+
+    - The DNS records for a domain should direct mail to DMS and allow DMS to send mail on behalf of that domain.
+    - DMS does not need TLS certificates for your mail domains, only for the DMS FQDN (_the `hostname` setting_).
+
+??? warning "Choosing a compatible email address"
+
+    An email address should conform to the standard [permitted charset and format](https://stackoverflow.com/questions/2049502/what-characters-are-allowed-in-an-email-address/2049510#2049510) (`local-part@domain-part`).
+
+    ---
+
+    DMS has features that need to reserve special characters to work correctly. Ensure those characters are not present in email addresses you configure for DMS, otherwise disable / opt-out of the feature.
+
+    - [Sub-addressing](#sub-addressing) is enabled by default with `+` as the _tag delimiter_. The tag can be changed, feature opt-out when the tag is explicitly unset.
 
 ### Aliases
 
 An alias is typically a full email address that will either be:
 
-- Delivered to an existing local DMS account address.
+- Delivered to the mailbox of a DMS account.
 - Redirected to one or more other email addresses (_these may also be forwarded to external addresses not managed by DMS_).
 
 ??? abstract "Technical Details (_Local vs Virtual aliases_)"
@@ -49,7 +79,7 @@ An alias is typically a full email address that will either be:
 
     !!! tip "Verify alias resolves correctly"
 
-        You can run `postmap -q <alias> <table>` in the container to verify an alias resolves to the expected target. If the target is also an alias, the command will not expand that to resolve the actual recipient(s).
+        You can run `postmap -q <alias> <table>` in the container to verify an alias resolves to the expected target. If the target is also an alias, the command will not expand that alias to resolve the actual recipient(s).
 
         For the `FILE` provisioner, an example would be: `postmap -q alias1@example.com /etc/postfix/virtual`. For the `LDAP` provisioner you'd need to adjust the table path.
 
@@ -68,7 +98,7 @@ An alias is typically a full email address that will either be:
     - Tags are dynamic. Anything between the `+` and `@` is understood as the tag, no additional configuration required.
     - Only the first occurence of the tag delimiter is recognized. Any additional occurences become part of the tag value itself.
 
-!!! tip "When is subaddressing useful?"
+??? tip "When is subaddressing useful?"
 
     A common use-case is to use a unique tag for each service you register your email address with.
 
@@ -115,7 +145,7 @@ An alias is typically a full email address that will either be:
     - This feature is enabled by default, opt-out via [`ENABLE_QUOTAS=0`][docs::env::enable-quotas]
     - **Not implemented** for the LDAP provisioner (_PR welcome! View the [feature request for implementation advice][gh-issue::dms-feature-request::dovecot-quotas-ldap]_)
 
-!!! tip "How are quotas useful?"
+??? tip "How are quotas useful?"
 
     Without quota limits for disk storage, a mailbox could fill up the available storage which would cause delivery failures to all mailboxes.
 
@@ -148,8 +178,10 @@ An alias is typically a full email address that will either be:
 
 ## Technical Overview
 
+This section provides insight for understanding how Postfix and Dovecot services are involved. It is intended as a reference for maintainers and contributors.
+
 - Postfix handles when mail is delivered (inbound) to DMS, or sent (outbound) from DMS.
-- Dovecot manages mailbox storage for mail delivered to your DMS user accounts.
+- Dovecot manages mailbox storage for mail delivered to the DMS accounts of your users.
 
 ??? abstract "Technical Details - Postfix"
 
@@ -177,8 +209,15 @@ An alias is typically a full email address that will either be:
     - A [PassDB][dovecot::docs::passdb] lookup most importantly authenticates the user. It may also provide any other necessary pre-login information.
     - A [UserDB][dovecot::docs::userdb] lookup retrieves post-login information specific to a user.
 
+[docs::env::account-provisioner]: ../environment.md#account_provisioner
+[docs::account-provisioner::file]: ./provisioner/file.md
+[docs::account-provisioner::ldap]: ./provisioner/ldap.md
+[docs::account-auth::oauth2]: ./supplementary/oauth2.md
+[docs::account-auth::master-accounts]: ./supplementary/master-accounts.md
+[docs::examples::auth-lua]: ../../../examples/use-cases/auth-lua.md
+
 [docs::sieve::subaddressing]: ../advanced/mail-sieve.md#subaddress-mailbox-routing
-[web::subaddress-use-cases]: https://www.codetwo.com/admins-blog/plus-addressing/
+[web::subaddress-use-cases]: https://www.codetwo.com/admins-blog/plus-addressing
 [wikipedia::subaddressing]: https://en.wikipedia.org/wiki/Email_address#Sub-addressing
 [ms-exchange-docs::limitations]: https://learn.microsoft.com/en-us/exchange/recipients-in-exchange-online/plus-addressing-in-exchange-online#using-plus-addresses
 
@@ -200,3 +239,6 @@ An alias is typically a full email address that will either be:
 [postfix::delivery-agent::virtual]: https://www.postfix.org/virtual.8.html
 [postfix::config-table::local-alias]: https://www.postfix.org/aliases.5.html
 [postfix::config-table::virtual-alias]: https://www.postfix.org/virtual.5.html
+
+[dovecot::docs::passdb]: https://doc.dovecot.org/configuration_manual/authentication/password_databases_passdb
+[dovecot::docs::userdb]: https://doc.dovecot.org/configuration_manual/authentication/user_databases_userdb

docs/content/config/account-management/provisioner/file.md

@@ -18,7 +18,7 @@ The best way to manage DMS accounts and related config files is through our `set
 
     ```bash
     # Starts a basic DMS instance and then shells into the container to use the `setup` CLI:
-    docker run --rm -itd --name dms --hostname mail.example.com ghcr.io/docker-mailserver/docker-mailserver:latest
+    docker run --rm -itd --name dms --hostname mail.example.com mailserver/docker-mailserver
     docker exec -it dms bash
 
     # Create some accounts:
@@ -49,11 +49,11 @@ Each line in the config file is a value pair (**alias** --> **target address**),
 
 !!! example "`postfix-virtual.cf` config file"
 
-    With DMS configured to manage mail for `example.com`:
+    In this example DMS manages mail for the domain `example.com`:
 
     ```cf-extra title="postfix-virtual.cf"
     # Alias delivers to an existing account:
-    alias1@example.com user1@example.com
+    alias1@example.com hello@example.com
 
     # Alias forwards to an external email address:
     alias2@example.com external-account@gmail.com
@@ -63,9 +63,9 @@ Each line in the config file is a value pair (**alias** --> **target address**),
 
     **`setup` CLI prevents an alias and account sharing an address:**
 
-    You cannot presently add a new account (`setup email add`) or alias `setup alias add` with an address when that already exists as an alias or account.
+    You cannot presently add a new account (`setup email add`) or alias (`setup alias add`) with an address which already exists as an alias or account in DMS.
 
-    This [restriction was enforced][gh-issue::bugs::account-alias-overlap] due to problems it could cause, although there are [use-cases where you may legitimately require this functionality][gh-issue::feature-request::allow-account-alias-overlap].
+    This [restriction was enforced][gh-issue::bugs::account-alias-overlap] due to [problems it could cause][gh-issue::bugs::account-alias-overlap-problem], although there are [use-cases where you may legitimately require this functionality][gh-issue::feature-request::allow-account-alias-overlap].
 
     For now you must manually edit the `postfix-virtual.cf` file as a workaround. There are no run-time checks outside of the `setup` CLI related to this restriction.
 
@@ -111,6 +111,7 @@ This config file is similar to the above `postfix-virtual.cf`, but the alias val
     These files are both copied internally to `/etc/postfix/` and configured in `main.cf` for the `virtual_alias_maps` setting. As `postfix-virtual.cf` is declared first for that setting, it will be processed before using `postfix-regexp.cf` as a fallback.
 
 [gh-issue::feature-request::allow-account-alias-overlap]: https://github.com/docker-mailserver/docker-mailserver/issues/3528
+[gh-issue::bugs::account-alias-overlap-problem]: https://github.com/docker-mailserver/docker-mailserver/issues/3350#issuecomment-1550528898
 [gh-issue::bugs::account-alias-overlap]: https://github.com/docker-mailserver/docker-mailserver/issues/3022#issuecomment-1807816689
 [gh-issue::bugs::wildcard-catchall]: https://github.com/docker-mailserver/docker-mailserver/issues/3022#issuecomment-1610452561
 [gh-issue::bugs::alias-nested]: https://github.com/docker-mailserver/docker-mailserver/issues/3622#issuecomment-1794504849

docs/content/config/account-management/supplementary/oauth2.md

@@ -6,12 +6,12 @@ title: 'Account Management | OAuth2 Support'
 
 !!! warning "This is only a supplement to the existing account provisioners"
 
-    Accounts must still be managed via the configured [`ACCOUNT_PROVISIONER`][env::account-provisioner] (`FILE` or `LDAP`).
+    Accounts must still be managed via the configured [`ACCOUNT_PROVISIONER`][docs::env::account-provisioner] (`FILE` or `LDAP`).
 
     Reasoning for this can be found in [#3480][gh-pr::oauth2]. Future iterations on this feature may allow it to become a full account provisioner.
 
 [gh-pr::oauth2]: https://github.com/docker-mailserver/docker-mailserver/pull/3480
-[env::account-provisioner]: ../../environment.md#account_provisioner
+[docs::env::account-provisioner]: ../../environment.md#account_provisioner
 
 The present OAuth2 support provides the capability for 3rd-party applications such as Roundcube to authenticate with DMS (dovecot) by using a token obtained from an OAuth2 provider, instead of passing passwords around.