--- a/mod_pubsub_serverinfo/README.md	Thu Jan 15 16:07:19 2026 +0100
+++ b/mod_pubsub_serverinfo/README.md	Thu Jan 15 17:35:43 2026 +0000
@@ -13,48 +13,90 @@
 
 - [Issue #1841](https://issues.prosody.im/1841): In Prosody 0.12, this module conflicts with mod_server_contact_info (both will run, but it may affect the ability of some implementations to read the server/contact information provided). To work around this issue, the [mod_server_contact_info](https://modules.prosody.im/mod_server_contact_info) community module can be used.
 
-Installation
-============
-
-Enable this module in the global or a virtual host.
-
-The default configuration requires the existence of a Pub/Sub component that uses the 'pubsub' subdomain of the host in which the module is enabled:
-
-    Component "pubsub.example.org" "pubsub"
-
-The module will create a node and publish data, using a JID that matches the XMPP domain name of the host. Ensure that this actor is an admin of the
-Pub/Sub service:
-
-    admins = { "example.org" }
-
 Configuration
 =============
 
-The Pub/Sub service on which data is published, by default, is a component addressed as the `pubsub` subdomain of the domain of the virtual host that
-the module is loaded under. To change this, apply this configuration setting:
+### Loading the module
+
+Simply enable this module on the hosts/components that you want to publish information for. Note that, as with most other modules, adding it to the
+global `modules_enabled` will automatically load it on all VirtualHosts on your server:
+
+```
+modules_enabled = {
+    ...
+    "pubsub_serverinfo";
+    ...
+}
+```
+
+Note that adding it to the global modules_enabled won't load it on any Component hosts on your server. If you want to publish info about those, you
+also need to add it to a `modules_enabled` setting under that Component, for example:
+
+```
+Component "rooms.example.com" "muc"
+    modules_enabled = {
+    	"pubsub_serverinfo";
+    }
+```
+
+### Specifying the publish destination
+
+This module publishes information to any XMPP pubsub service, which could be local (i.e. served by the same Prosody instance) or remote (via
+server-to-server connections).
 
-    pubsub_serverinfo_service = "anotherpubsub.example.org"
+The destination to publish to is controlled by two settings:
+
+- `pubsub_serverinfo_service`
+- `pubsub_serverinfo_node`
+
+As usual, these options can be set in the global section (inherited by all hosts/component) or underneath each VirtualHost/Component to apply
+to that VirtualHost/Component only.
+
+If unset, `pubsub_serverinfo_service` will default to `pubsub.<domain>` - that is, it will try to publish to a pubsub service that is on the
+`pubsub` subdomain of the host it is publishing about. For example, if you load the module on `example.com` it will default to publishing to
+`pubsub.example.com`. If this is incorrect, you should set `pubsub_serverinfo_service` to a valid pubsub service address.
+
+The `pubsub_serverinfo_node` option defaults to `"serverinfo"`. Note that if you have multiple hosts publishing to the same pubsub service, you
+*must* set this to something unique for each one, otherwise they will overwrite each other.
 
-The Pub/Sub node on which data is published is, by default, a leaf-node named `serverinfo`. To change this, apply this configuration setting:
+### Pubsub service configuration
+
+As mentioned, you can publish to a local or remote pubsub service. The publish commands will come from the reporting domain(s) where the module
+is loaded (e.g. `example.com`), so those domains must be permitted to publish to the destination pubsub service you have chosen.
+
+If you want to run a local pubsub service in the same Prosody instance, you can use this configuration:
 
-    pubsub_serverinfo_node = "foobar"
+```
+Component "pubsub.example.com" "pubsub"
+    -- Grant permission for example.com to publish here, by simply making it
+    -- an admin:
+    admins = { "example.org" }
+```
+
+### Other settings
 
 To prevent a surplus of event notifications, this module will only publish new data after a certain period of time has expired. The default duration
 is 300 seconds (5 minutes). To change this simply put in the config:
 
+```
     pubsub_serverinfo_publication_interval = 180 -- or any other number of seconds
+```
 
 To detect if remote domains allow their domain name to be included in the data that this module publishes, this module will perform a service
 discovery request to each remote domain. To prevent a continuous flood of disco/info requests, the response to these requests is cached. By default,
 a cached value will remain in cache for one hour. This duration can be modified by adding this configuration option:
 
+```
     pubsub_serverinfo_cache_ttl = 1800 -- or any other number of seconds
+```
 
 To include the count of active (within the past 30 days) users:
 
+```
     pubsub_serverinfo_publish_user_count = true
+```
 
-Enabling this option will automatically load mod_measure_active_users.
+Enabling this option will automatically load mod_measure_active_users, which must be installed.
 
 Compatibility
 =============
@@ -66,25 +108,27 @@
 
 The reported data does not contain the optional 'connection' child elements. These can be used to describe the direction of a connection.
 
-More generic server information (eg: user counts, software version) should be included in the data that is published.
-
 Common Configuration Issues
 ===========================
 
-**Domain must be an admin of the PubSub service** 
+### Incorrect permissions on pubsub service
 
-The XMPP domain itself (for example, `example.org`) must be an admin of the PubSub service. Many users mistakenly assume a user JID (e.g., `admin@example.org`) should be an admin. Configure the PubSub module to accept the global domain as an admin:
+The XMPP domain itself (for example, `example.org`) must be allowed to publish to the chosen pubsub service, e.g. by making it an admin of that service.
+Sometimes people mistakenly assume a user JID (e.g., `admin@example.org`) should be an admin. See the example above for correct configuration.
 
-    admins = { "example.org" }
+### Enabling the module on the wrong host
 
-**Module installation location** 
+`mod_pubsub_serverinfo` must be enabled globally or within a virtual host, **not inside the PubSub component** (unless you want to publish info about that
+component). Generally you are instructing other hosts to publish data to the pubsub service, not extending the pubsub service itself.
 
-`mod_pubsub_serverinfo` must be enabled globally or within a virtual host, **not inside the PubSub component**. You are instructing the global domain to publish data to the PubSub service, not extending the PubSub service itself.
+Additionally, be aware that adding mod_pubsub_serverinfo to the global modules_enabled will not load it on any Components by default, you must still specify
+that explicitly (see the earlier configuration example).
 
-**Conditional dependency on `mod_measure_active_users`**
+### Conditional dependency on `mod_measure_active_users`
 
 Publishing user counts requires `mod_measure_active_users`. This module will be loaded automatically if user count publication is enabled, but it must be installed on the system for this to succeed.
 
-**DNS records for the PubSub service**
+### DNS records for the PubSub service
 
 External servers must be able to connect to the PubSub service. Ensure the hostname of the PubSub service has appropriate A/AAAA and SRV records so remote servers can discover and reach the service.
+You can use the 'prosodyctl check' command to help with this.