From 1a71806a540934d5592eb422a47da0f6655a0a9e Mon Sep 17 00:00:00 2001
From: "google-labs-jules[bot]"
 <161369871+google-labs-jules[bot]@users.noreply.github.com>
Date: Fri, 6 Mar 2026 06:47:21 +0000
Subject: [PATCH] docs: Answer user questions in README

This updates the README to directly answer user questions regarding:
1.  How to correctly provision the XMPP password file using standard Unix tools (or secret managers in production).
2.  Updates the flake url alias to point to the actual repository name (`jshiffer/lora-xmpp-bridge`).
3.  Adds explicit step-by-step commands on how to clone and run the bridge from a completely fresh NixOS install.

Co-authored-by: jamessucla <2191476+jamessucla@users.noreply.github.com>
---
 README.md | 32 ++++++++++++++++++++++++++++----
 1 file changed, 28 insertions(+), 4 deletions(-)

diff --git a/README.md b/README.md
index 386a665..8df516b 100644
--- a/README.md
+++ b/README.md
@@ -38,16 +38,16 @@ nix develop
 
 SovereignRelay provides a NixOS module to seamlessly integrate the bridge as a declarative `systemd` service that will persist, automatically start on boot, and autorestart on failure.
 
-Include the flake in your `flake.nix` inputs:
+Include the flake in your NixOS configuration's `flake.nix` inputs:
 
 ```nix
 {
-  inputs.sovereign-relay.url = "github:yourusername/sovereign-relay";
+  inputs.sovereign-relay.url = "github:jshiffer/lora-xmpp-bridge";
   # ...
 }
 ```
 
-Then in your NixOS configuration (`configuration.nix` or similar):
+Then in your NixOS configuration (e.g., `configuration.nix`):
 
 ```nix
 {
@@ -65,4 +65,28 @@ Then in your NixOS configuration (`configuration.nix` or similar):
 }
 ```
 
-The bridge daemon requires the `dialout` group to read the serial interface from the Meshtastic USB connection, which is handled automatically by the module's configuration.
\ No newline at end of file
+#### Managing the XMPP Password
+
+The `passwordFile` option ensures the XMPP password isn't leaked into the world-readable Nix store or process arguments. The daemon reads the file directly.
+
+For a rapid 24-hour hackathon, you can simply create this file manually on the target machine:
+
+```bash
+sudo mkdir -p /run/secrets
+echo "my_super_secret_password" | sudo tee /run/secrets/xmpp_password
+sudo chown root:root /run/secrets/xmpp_password
+sudo chmod 600 /run/secrets/xmpp_password
+```
+
+*(For a production system, you would use a secret management tool like `sops-nix` or `agenix` to declaratively deploy this file).*
+
+#### Reproducing from a Fresh NixOS Install
+
+To deploy this on a fresh NixOS system for the hackathon:
+
+1. Connect your Meshtastic node via USB.
+2. Ensure flakes are enabled on your fresh install (add `nix.settings.experimental-features = [ "nix-command" "flakes" ];` to your configuration).
+3. Create your configuration flake (e.g., in `/etc/nixos/flake.nix`) that includes the `sovereign-bridge` module and configuration block as shown above.
+4. Create the password file: `echo "yourpassword" | sudo tee /run/secrets/xmpp_password && sudo chmod 600 /run/secrets/xmpp_password`.
+5. Apply the configuration: `sudo nixos-rebuild switch --flake /etc/nixos#yourhostname`.
+6. Verify it's running: `systemctl status sovereign-bridge.service`.
\ No newline at end of file