docs: add NATS cache sharing documentation

Document the new NATS cache sharing feature added in v0.3.0:
- Add CLI flags for NATS configuration
- Add NixOS module options under flake.nats
- Add dedicated section explaining the feature

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

README.md

@@ -44,6 +44,10 @@ nix build
 | `--collector.flake` | `false` | Enable flake collector |
 | `--flake.url` | | Flake URL for revision comparison (required if flake collector enabled) |
 | `--flake.check-interval` | `1h` | Interval between remote flake checks |
+| `--flake.nats.enable` | `false` | Enable NATS cache sharing |
+| `--flake.nats.url` | `nats://localhost:4222` | NATS server URL |
+| `--flake.nats.subject` | `nixos-exporter.remote-rev` | NATS subject for revision updates |
+| `--flake.nats.credentials-file` | | NATS credentials file (optional) |
 
 ## NixOS Module Options
 
@@ -58,6 +62,13 @@ services.prometheus.exporters.nixos = {
     enable = false;
     url = "";  # Required if flake.enable = true
     checkInterval = "1h";
+
+    nats = {
+      enable = false;
+      url = "nats://localhost:4222";
+      subject = "nixos-exporter.remote-rev";
+      credentialsFile = null;  # Optional path to credentials file
+    };
   };
 };
 ```
@@ -160,6 +171,19 @@ groups:
 
 - The `nixos_flake_revision_behind` metric requires `system.configurationRevision` to be set. Without it, the metric will always be 0 since there's no local revision to compare against.
 
+## NATS Cache Sharing
+
+When running multiple nixos-exporter instances across different hosts, NATS cache sharing allows them to share remote revision data. This reduces the number of `nix flake metadata` calls and ensures all hosts see updates faster.
+
+When enabled:
+- Hosts publish their remote revision when they fetch new data
+- Hosts subscribe to receive updates from other hosts
+- Updates are filtered by flake URL to avoid cross-contamination
+- Auto-reconnect handles NATS server restarts gracefully
+- Falls back to local fetching if NATS is unavailable
+
+Additionally, smart cache refresh is enabled: when the current system revision matches the cached remote revision, the exporter immediately checks for newer revisions instead of waiting for the next scheduled check.
+
 ## License
 
 MIT