Document homeserver requirements for hookshot's end-to-bridge encryption

Enabling matrix_hookshot_encryption_enabled configures the bridge side
correctly (registration flags, Valkey cache), but hookshot's encryption
also needs the homeserver to support and enable MSC2409 and MSC3202,
which are typically experimental features disabled by default. Nothing
documented that, so the resulting setup silently did not work.

Reference the MSCs in the variable's comment, and show the exact Synapse
settings in the hookshot documentation page. The playbook deliberately
does not auto-enable them: they are experimental homeserver-wide
features, and flipping them from a bridge toggle would be surprising.

Fixes #3861

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

docs/configuring-playbook-bridge-hookshot.md

@@ -40,6 +40,16 @@ matrix_hookshot_enabled: true
 # matrix_hookshot_github_private_key: "GITHUB_PRIVATE_KEY_HERE"
 ```
 
+> [!NOTE]
+> End-to-bridge encryption also requires the homeserver to support (and have enabled) [MSC2409](https://github.com/matrix-org/matrix-spec-proposals/pull/2409) and [MSC3202](https://github.com/matrix-org/matrix-spec-proposals/pull/3202). If you are using Synapse, enable them by also adding this to your `vars.yml` file:
+>
+> ```yaml
+> matrix_synapse_experimental_features_msc2409_to_device_messages_enabled: true
+> matrix_synapse_experimental_features_msc3202_transaction_extensions_enabled: true
+> ```
+>
+> These are experimental homeserver-wide features (as is Hookshot's encryption support itself), so enable them deliberately.
+
 For each of the services (GitHub, GitLab, Jira, Figma, and generic webhooks) fill in the respective variables `matrix_hookshot_service_*` listed in [main.yml](../roles/custom/matrix-bridge-hookshot/defaults/main.yml) as required.
 
 Take special note of the `matrix_hookshot_*_enabled` variables. Services that need no further configuration are enabled by default (GitLab and generic webhooks), while you must first add the required configuration and enable the others (GitHub, Jira, and Figma).

roles/custom/matrix-bridge-hookshot/defaults/main.yml

@@ -70,7 +70,8 @@ matrix_hookshot_cache_redisUri: "{{ ('redis://' + matrix_hookshot_cache_redis_ho
 
 # Controls whether the end-to-bridge encryption support is enabled.
 # This requires that:
-# - support to also be enabled in the homeserver, see the documentation of Hookshot.
+# - the homeserver to support MSC2409 (to-device messages for appservices) and MSC3202 (encryption-related appservice transaction extensions), and to have them enabled.
+#   These are typically experimental homeserver features which are disabled by default, so they usually need to be enabled explicitly via homeserver-specific configuration.
 # - Hookshot to be pointed at a Redis instance via the `matrix_hookshot_cache_redis*` variables. Note that this is configured automatically by the playbook when encryption is enabled.
 # See: https://matrix-org.github.io/matrix-hookshot/latest/advanced/encryption.html
 # NOTE: Encryption is not currently (2025-12-30) supported when using MAS (https://github.com/matrix-org/matrix-hookshot/issues/1084)