From 229162640ee7df207a8a67e5b250d5b8cc7127dd Mon Sep 17 00:00:00 2001
From: Slavi Pantaleev <slavi@devture.com>
Date: Thu, 7 May 2026 16:57:03 +0300
Subject: [PATCH] Polish Draupnir 3.1.0 ZTD docs and fix variable name typo

- Fix `matrxi_appservice_draupnir_for_all_zero_touch_deployment` typo in
  the appservice doc example so the variable actually matches the role
  default (`matrix_appservice_draupnir_for_all_zero_touch_deploy`).
- Drop a garbled sentence in the appservice usage section.
- Restructure the bot-mode "Adjusting the playbook configuration"
  section into clearly labeled ZTD vs. native-login subsections so the
  access-token vs. native-login choice is unambiguous.
- Restore an example block under the (now uncommented) `pollReports`
  paragraph in the bot-mode doc.
- Reorder the orphaned "automatically done if Ketesa is enabled"
  sentence so it precedes the code block it qualifies.
- Fix `SPDX-FileCopyRightText` casing and normalize `2024,2026` /
  `2024, 2026` to the project's `YYYY - YYYY` convention.
- Fix variable name references in role default comments
  (`matrix_*_initialManager` -> `matrix_*_config_initialManager`).
- Misc grammar/spelling fixes ("the the", "a admin", "mittigated",
  "recommendationare", "News memory", "re creation", "an Synapse").
- Drop a stray double blank line in the appservice template.
---
 ...ng-playbook-appservice-draupnir-for-all.md | 44 +++++++++----------
 docs/configuring-playbook-bot-draupnir.md     | 43 ++++++++++--------
 .../defaults/main.yml                         | 17 +++----
 .../tasks/setup_install.yml                   |  2 +-
 .../tasks/validate_config.yml                 |  2 +-
 .../templates/production-appservice.yaml.j2   |  1 -
 .../matrix-bot-draupnir/defaults/main.yml     |  2 +-
 7 files changed, 57 insertions(+), 54 deletions(-)

diff --git a/docs/configuring-playbook-appservice-draupnir-for-all.md b/docs/configuring-playbook-appservice-draupnir-for-all.md
index 2574b1c3e..fce711584 100644
--- a/docs/configuring-playbook-appservice-draupnir-for-all.md
+++ b/docs/configuring-playbook-appservice-draupnir-for-all.md
@@ -1,5 +1,5 @@
 <!--
-SPDX-FileCopyRightText: 2024,2026 Catalan Lover <catalanlover@protonmail.com>
+SPDX-FileCopyrightText: 2024 - 2026 Catalan Lover <catalanlover@protonmail.com>
 SPDX-FileCopyrightText: 2024 - 2025 Suguru Hirahara
 SPDX-FileCopyrightText: 2024 MDAD project contributors
 
@@ -26,44 +26,42 @@ Draupnir for all only has limited support for external tooling like [MRU](https:
 
 ## Prerequisites
 
-### Prerequisites for Zero Touch Deployment (Recommended)
+### Prerequisites for Zero Touch Deployment (recommended)
 
-Zero Touch Deployment of Draupnir Appservice Mode (Draupnir for all) requires as of Draupnir 3.1.0 that you supply Draupnir the following:
+As of Draupnir 3.1.0, Zero Touch Deployment of Draupnir Appservice Mode (Draupnir for all) requires you to supply the following:
 
-- MXID of the the first person who gets invited to the admin room the bot creates for you.
+- MXID of the first person who gets invited to the admin room that the bot creates for you.
 
-That is all. The appservice manages everything on its own after you provide it a MXID to invite.
+That is all. The appservice manages everything on its own after you provide it with an MXID to invite.
 
-If proceeding with Zero Touch Deployment proceed to [Adjusting the playbook configuration](#adjusting-the-playbook-configuration)
+If proceeding with Zero Touch Deployment, skip ahead to [Adjusting the playbook configuration](#adjusting-the-playbook-configuration).
 
-### Create a admin room (Optional)
+### Create an admin room (optional)
 
-The playbook does not create a admin room for your Admin Draupnir but the appservice it self can do this. You **can create room manually** before setting up the bot.
+The playbook does not create an admin room for your Draupnir, but the appservice itself can do this for you. Alternatively, you **can create the room manually** before setting up the bot.
 
 Note that the room must be unencrypted.
 
 The admin room has to be given an alias, and your bot has to be invited to the room.
 
-This admin room is used to control who has access to your D4A deployment. The room stores this data inside of the control room state so your bot must have sufficient powerlevel to send custom state events. This is default 50 or moderator as Element clients call this powerlevel.
+This admin room is used to control who has access to your D4A deployment. The room stores this data in the control room state, so your bot must have sufficient power level to send custom state events. This is `50` by default (moderator, as Element clients call this power level).
 
 > [!WARNING]
 > Anyone in this room can control the bot so it is important that you only invite trusted users to this room.
 
 ## Adjusting the playbook configuration
 
-Add the following configuration to your `inventory/host_vars/matrix.example.com/vars.yml` file. Make sure to replace `INITIAL_MANAGER_MXID_HERE`.
+When using Zero Touch Deployment, add the following configuration to your `inventory/host_vars/matrix.example.com/vars.yml` file. Make sure to replace `INITIAL_MANAGER_MXID_HERE` with the MXID of the user who should be invited to the admin room first.
 
 ```yaml
 matrix_appservice_draupnir_for_all_enabled: true
 
-matrxi_appservice_draupnir_for_all_zero_touch_deployment: true
+matrix_appservice_draupnir_for_all_zero_touch_deploy: true
 
 matrix_appservice_draupnir_for_all_config_initialManager: "INITIAL_MANAGER_MXID_HERE"
 ```
 
-If opting out of Zero Touch deployment use the following configuration block instead.
-
-Add the following configuration to your `inventory/host_vars/matrix.example.com/vars.yml` file. Make sure to replace `MANAGEMENT_ROOM_ALIAS_HERE`.
+If opting out of Zero Touch Deployment, use the following configuration block instead. Make sure to replace `MANAGEMENT_ROOM_ALIAS_HERE` with the alias of the admin room you have created earlier.
 
 ```yaml
 matrix_appservice_draupnir_for_all_enabled: true
@@ -126,11 +124,9 @@ ansible-playbook -i inventory/hosts setup.yml --tags=setup-all,start
 
 ## Usage
 
-If you made it through all the steps above and your main control room was joined by a user called `@draupnir-main:example.com` you have successfully installed Draupnir for All and can now start using it.
-
-If using Zero Touch Deployment the flow will be reversed and the success signal is the initial manager account being invited to the admin room.
+If you made it through all the steps above and your main control room was joined by a user called `@draupnir-main:example.com`, you have successfully installed Draupnir for All and can now start using it.
 
-The installation of Draupnir for all in Usage-wise, Draupnir for all is almost identical to Draupnir bot mode.
+If using Zero Touch Deployment, the flow is reversed and the success signal is the initial manager account being invited to the admin room.
 
 Draupnir for all installation via this playbook is very much Alpha quality. Usage-wise, Draupnir for all is almost identical to Draupnir bot mode, except that protections requiring homeserver admin access are not available, and the config file is shared between all bots so legacy protections like wordlist share a single global config.
 
@@ -138,16 +134,16 @@ Draupnir for all installation via this playbook is very much Alpha quality. Usag
 
 Draupnir for all includes several security measures like that it only allows users that are on its allow list to ask for a bot. To add a user to this list we have 2 primary options. Using the chat to tell Draupnir to do this for us or if you want to automatically do it by sending `m.policy.rule.user` events that target the subject you want to allow provisioning for with the `org.matrix.mjolnir.allow` recommendation. Using the chat is recommended.
 
-The bot requires a powerlevel of 50 in the management room to control who is allowed to use the bot. The bot does currently not say anything if this is true or false. (This is considered a bug and is documented in issue [#297](https://github.com/the-draupnir-project/Draupnir/issues/297)) This issue is mittigated in large part by Zero Touch Deployment workflows that got introduced in Draupnir 3.1.0
+The bot requires a power level of 50 in the management room to control who is allowed to use the bot. The bot does currently not say anything if this is true or false. (This is considered a bug and is documented in issue [#297](https://github.com/the-draupnir-project/Draupnir/issues/297).) This issue is largely mitigated by the Zero Touch Deployment workflows introduced in Draupnir 3.1.0.
 
 To allow users or whole homeservers you type /plain !admin allow `target` and target can be either a MXID or a wildcard like `@*:example.com` to allow all users on example.com to provision a bot. We use /plain to force the client to not attempt to mess with this command as it can break Wildcard commands especially.
 
 ### How to provision a D4A once you are allowed to
 
-Once someone is allowed to provision a bot. Simply provision them one with `!admin provision MXID`.
-Self Service Provisioning is disabled as a security feature due to it being bugged. Force Provisioning bypasses this disabled status.
+Once someone is allowed to provision a bot, simply provision them one with `!admin provision MXID`.
+
+Self-service provisioning is disabled as a security measure because it is currently bugged. Force-provisioning (with `!admin provision`) bypasses this disabled status.
 
-Please note that the reason you should always make sure there is an allow entry matching whoever is provisioned is that when
-self service gets fixed the bot of anyone who is not allowed to provision a bot will refuse to start.
+Note that you should always make sure there is an allow entry matching whoever is provisioned, because once self-service is fixed, the bot of anyone who is not allowed to provision a bot will refuse to start.
 
-Congratulations if you made it all the way here because you now have a fully working Draupnir for all deployment.
+Congratulations if you made it all the way here, because you now have a fully working Draupnir for all deployment.
diff --git a/docs/configuring-playbook-bot-draupnir.md b/docs/configuring-playbook-bot-draupnir.md
index da728d4d7..55f8710bf 100644
--- a/docs/configuring-playbook-bot-draupnir.md
+++ b/docs/configuring-playbook-bot-draupnir.md
@@ -1,5 +1,5 @@
 <!--
-SPDX-FileCopyRightText: 2023 - 2026 Catalan Lover <catalanlover@protonmail.com>
+SPDX-FileCopyrightText: 2023 - 2026 Catalan Lover <catalanlover@protonmail.com>
 SPDX-FileCopyrightText: 2023 - 2025 MDAD project contributors
 SPDX-FileCopyrightText: 2023 Kim Brose
 SPDX-FileCopyrightText: 2024 - 2025 Slavi Pantaleev
@@ -20,15 +20,15 @@ If your migrating from [Mjolnir](configuring-playbook-bot-mjolnir.md), skip to [
 
 ## Prerequisites
 
-### Prerequisites for Zero Touch Deployment (Recommended)
+### Prerequisites for Zero Touch Deployment (recommended)
 
-Zero Touch Deployment of Draupnir bot mode requires as of Draupnir 3.1.0 that you supply Draupnir the following:
+As of Draupnir 3.1.0, Zero Touch Deployment of Draupnir bot mode requires you to supply the following:
 
-- MXID of the the first person who gets invited to the management room the bot creates for you.
-- Permanent access token for authentication. Instructions for obtaining one can be found at [obtain an access token via curl](obtaining-access-tokens.md#obtain-an-access-token-via-curl)
-- User account for Draupnir
+- MXID of the first person who gets invited to the management room that the bot creates for you.
+- A permanent access token for authentication. Instructions for obtaining one can be found at [obtain an access token via curl](obtaining-access-tokens.md#obtain-an-access-token-via-curl).
+- A user account for Draupnir.
 
-Zero Touch Deployment is the officially preferred installation method for new deployments of Draupnir as of 3.1.0
+Zero Touch Deployment is the officially preferred installation method for new deployments of Draupnir as of 3.1.0.
 
 ### Create a management room (optional)
 
@@ -39,7 +39,7 @@ Using your own account, create a new invite only room that you will use to manag
 
 It is possible to make the management room encrypted (E2EE). If doing so, then you need to enable the native E2EE support (see [below](#native-e2ee-support)).
 
-E2EE Support for the management room is mutually exclusive with Zero Touch Deployment of Draupnir.
+E2EE support for the management room is mutually exclusive with Zero Touch Deployment of Draupnir.
 
 Once you have created the room you need to copy the room ID so you can specify it on your `inventory/host_vars/matrix.example.com/vars.yml` file. In Element Web you can check the ID by going to the room's settings and clicking "Advanced". The room ID will look something like `!qporfwt:example.com`.
 
@@ -76,7 +76,9 @@ matrix_bot_draupnir_config_accessToken: "CLEAN_ACCESS_TOKEN_HERE"
 
 ## Adjusting the playbook configuration
 
-To enable the bot, add the following configuration to your `vars.yml` file. Make sure to replace `INITIAL_MANAGER_MXID_HERE` with the MXID for whoever is to be invited to the management room first.
+### Configuration for Zero Touch Deployment (recommended)
+
+To enable the bot using Zero Touch Deployment, add the following configuration to your `vars.yml` file. Make sure to replace `INITIAL_MANAGER_MXID_HERE` with the MXID of the user who should be invited to the management room first, and `CLEAN_ACCESS_TOKEN_HERE` with the access token you obtained.
 
 ```yaml
 # Enable Draupnir
@@ -87,11 +89,12 @@ matrix_bot_draupnir_zero_touch_deploy: true
 matrix_bot_draupnir_config_initialManager: "INITIAL_MANAGER_MXID_HERE"
 
 # Access token which the bot will use for logging in.
-# Comment out `matrix_bot_draupnir_login_native` when using this option.
 matrix_bot_draupnir_config_accessToken: "CLEAN_ACCESS_TOKEN_HERE"
 ```
 
-If wanting to have the bot manage its own login at the cost of having to create a management room you can use login native and the config block below.
+### Configuration without Zero Touch Deployment
+
+If you'd prefer to have the bot manage its own login at the cost of having to create the management room manually, you can use native login with the configuration block below. Make sure to replace `MANAGEMENT_ROOM_ID_HERE` with the ID of the management room you have created earlier.
 
 ```yaml
 # Enable Draupnir
@@ -118,7 +121,7 @@ This is due to the conditional restart logic not being able to reliably tell whe
 
 Conditional restarts work correctly for all tags when running only one of these two operating modes.
 
-### Create and invite the bot to the management room (if using login native and not using Zero Touch Deployment)
+### Create and invite the bot to the management room (only when using native login without Zero Touch Deployment)
 
 Before proceeding to the next step, run the playbook with the following command to create the bot user.
 
@@ -130,9 +133,9 @@ ansible-playbook -i inventory/hosts setup.yml --tags=setup-all,ensure-matrix-use
 
 Then, invite the bot (`@bot.draupnir:example.com`) to its management room which you have created earlier.
 
-### Creating user account for the bot
+### Creating a user account for the bot (when using Zero Touch Deployment)
 
-Since Zero Touch Deployment is not validated with login native we will create the user account manually.
+Since Zero Touch Deployment is not validated with native login, you will need to create the user account manually.
 
 Refer to [registering users](registering-users.md) for documentation on how to configure the user account.
 
@@ -148,8 +151,7 @@ The APIs can also be accessed via [Ketesa](https://github.com/etkecc/ketesa), a
 
 #### Add the configuration
 
-To expose the APIs publicly, add the following configuration to your `vars.yml` file:
-This is automatically done if Ketesa is enabled.
+This is automatically done if Ketesa is enabled. Otherwise, to expose the APIs publicly, add the following configuration to your `vars.yml` file:
 
 ```yaml
 matrix_synapse_container_labels_public_client_synapse_admin_api_enabled: true
@@ -201,9 +203,14 @@ matrix_bot_draupnir_config_web_synapseHTTPAntispam_enabled: true
 matrix_bot_draupnir_admin_api_enabled: true
 ```
 
-These protections need to be manually activated and consulting the [enabling protections](#enabling-built-in-protections) guide can be helpful or consulting upstream documentation.
+These protections need to be manually activated. Consulting the [enabling protections](#enabling-built-in-protections) guide and/or upstream documentation can be helpful.
+
+The other method polls a Synapse Admin API endpoint, hence it is available only if using Synapse and if the Draupnir user is an admin. To enable it, set `pollReports: true` in your `vars.yml` file as below:
 
-The other method polls an Synapse Admin API endpoint, hence it is available only if using Synapse and if the Draupnir user is an admin (see [above](#register-the-bot-account)). To enable it, set `pollReports: true` on `vars.yml` file as below.
+```yaml
+matrix_bot_draupnir_configuration_extension_yaml: |
+  pollReports: true
+```
 
 ### Extending the configuration
 
diff --git a/roles/custom/matrix-appservice-draupnir-for-all/defaults/main.yml b/roles/custom/matrix-appservice-draupnir-for-all/defaults/main.yml
index f0408c2b5..2c8893f87 100644
--- a/roles/custom/matrix-appservice-draupnir-for-all/defaults/main.yml
+++ b/roles/custom/matrix-appservice-draupnir-for-all/defaults/main.yml
@@ -63,25 +63,26 @@ matrix_appservice_draupnir_for_all_force_restart: "{{
 # the configuration values Draupnir expects for this mode.
 # This prevents invalid manual combinations from being passed through, since
 # Draupnir requires `matrix_appservice_draupnir_for_all_config_adminRoom` to be
-# unset and `matrix_appservice_draupnir_for_all_initialManager` to be a valid
-# user ID.
+# unset and `matrix_appservice_draupnir_for_all_config_initialManager` to be a
+# valid user ID.
 # Zero Touch Deployment is recommended for all new deployments.
-# New deployments that are exempt from this recommendationare assumed to be advanced users.
-# Who know what they are doing and have specific needs that require the flexibility of non-zero-touch-deployment mode.
+# Deployments that are exempt from this recommendation are assumed to be
+# advanced setups with specific needs that require the flexibility of
+# non-zero-touch-deployment mode.
 # Note that enabling this on an existing deployment will cause the bot to recreate the admin room.
-# Manual policy migration has to be done in that case as to not break when access controls return to working order.
+# Manual policy migration has to be done in that case so as not to break when access controls return to working order.
 matrix_appservice_draupnir_for_all_zero_touch_deploy: false
 
 # The room ID where people can use the bot. The bot has no access controls, so
 # anyone in this room can use the bot - secure your room!
 # This should be a room alias - not a matrix.to URL.
-# Appservice mode unlike bot mode is not verbose in the admin room.
+# Appservice mode, unlike bot mode, is not verbose in the admin room.
 # This room is different for Appservice Mode compared to normal mode.
 # In Appservice mode it provides functions like user management.
 matrix_appservice_draupnir_for_all_config_adminRoom: ""  # noqa var-naming
 
-# This controls the mxid of who is invited to the admin room on its creation when using Zero Touch Deployment.
-# The this value is mutually exclusive with matrix_appservice_draupnir_for_all_config_adminRoom
+# This controls the MXID of who is invited to the admin room on its creation when using Zero Touch Deployment.
+# This value is mutually exclusive with matrix_appservice_draupnir_for_all_config_adminRoom
 # and the bot will crash if you attempt to set both at the same time.
 matrix_appservice_draupnir_for_all_config_initialManager: ""  # noqa var-naming
 
diff --git a/roles/custom/matrix-appservice-draupnir-for-all/tasks/setup_install.yml b/roles/custom/matrix-appservice-draupnir-for-all/tasks/setup_install.yml
index d411b7299..7c9d582e7 100644
--- a/roles/custom/matrix-appservice-draupnir-for-all/tasks/setup_install.yml
+++ b/roles/custom/matrix-appservice-draupnir-for-all/tasks/setup_install.yml
@@ -1,6 +1,6 @@
 # SPDX-FileCopyrightText: 2024 David Mehren
 # SPDX-FileCopyrightText: 2024 MDAD project contributors
-# SPDX-FileCopyrightText: 2024, 2026 Catalan Lover <catalanlover@protonmail.com>
+# SPDX-FileCopyrightText: 2024 - 2026 Catalan Lover <catalanlover@protonmail.com>
 # SPDX-FileCopyrightText: 2024 Slavi Pantaleev
 # SPDX-FileCopyrightText: 2024 Suguru Hirahara
 #
diff --git a/roles/custom/matrix-appservice-draupnir-for-all/tasks/validate_config.yml b/roles/custom/matrix-appservice-draupnir-for-all/tasks/validate_config.yml
index 4d9b46c99..6383b6487 100644
--- a/roles/custom/matrix-appservice-draupnir-for-all/tasks/validate_config.yml
+++ b/roles/custom/matrix-appservice-draupnir-for-all/tasks/validate_config.yml
@@ -1,5 +1,5 @@
 # SPDX-FileCopyrightText: 2024 MDAD project contributors
-# SPDX-FileCopyrightText: 2024, 2026 Catalan Lover <catalanlover@protonmail.com>
+# SPDX-FileCopyrightText: 2024 - 2026 Catalan Lover <catalanlover@protonmail.com>
 # SPDX-FileCopyrightText: 2024 Slavi Pantaleev
 # SPDX-FileCopyrightText: 2025 Suguru Hirahara
 #
diff --git a/roles/custom/matrix-appservice-draupnir-for-all/templates/production-appservice.yaml.j2 b/roles/custom/matrix-appservice-draupnir-for-all/templates/production-appservice.yaml.j2
index 355f816d6..38bce59b9 100644
--- a/roles/custom/matrix-appservice-draupnir-for-all/templates/production-appservice.yaml.j2
+++ b/roles/custom/matrix-appservice-draupnir-for-all/templates/production-appservice.yaml.j2
@@ -28,7 +28,6 @@ adminRoom: {{ matrix_appservice_draupnir_for_all_config_adminRoom | to_json }}
 initialManager: {{ matrix_appservice_draupnir_for_all_config_initialManager | to_json }}
 {% endif %}
 
-
 # This is a web api that the widget connects to in order to interact with the appservice.
 webAPI:
   port: 9000
diff --git a/roles/custom/matrix-bot-draupnir/defaults/main.yml b/roles/custom/matrix-bot-draupnir/defaults/main.yml
index 05a4fc4d3..7e8184c56 100644
--- a/roles/custom/matrix-bot-draupnir/defaults/main.yml
+++ b/roles/custom/matrix-bot-draupnir/defaults/main.yml
@@ -127,7 +127,7 @@ matrix_bot_draupnir_login_native: false
 # Note that enabling this on an existing deployment will cause the bot to
 # recreate the management room.
 # Recreating the management room will cause all protections to reset their settings to defaults
-# and cause the re creation of secondary rooms like notification rooms. News memory will also be wiped.
+# and cause the recreation of secondary rooms like notification rooms. All bot memory will also be wiped.
 matrix_bot_draupnir_zero_touch_deploy: false
 
 # The management room used for administration when Zero Touch