From 1a35bb42bdc89b1d7ce2516195a37ae913661d47 Mon Sep 17 00:00:00 2001
From: thePR0M3TH3AN <53631862+PR0M3TH3AN@users.noreply.github.com>
Date: Wed, 6 Aug 2025 10:09:05 -0400
Subject: [PATCH] docs: add Nostr setup guide and architecture overview

---
 README.md                 | 31 +++++++++++++++----------------
 docs/nostr_setup.md       | 33 +++++++++++++++++++++++++++++++++
 src/seedpass/cli/nostr.py |  4 +++-
 3 files changed, 51 insertions(+), 17 deletions(-)
 create mode 100644 docs/nostr_setup.md

diff --git a/README.md b/README.md
index 30cd899..fca742f 100644
--- a/README.md
+++ b/README.md
@@ -49,7 +49,7 @@ SeedPass now uses the `portalocker` library for cross-platform file locking. No
 
 - **Deterministic Password Generation:** Utilize BIP-85 for generating deterministic and secure passwords.
 - **Encrypted Storage:** All seeds, login passwords, and sensitive index data are encrypted locally.
-- **Nostr Integration:** Post and retrieve your encrypted password index to/from the Nostr network.
+- **Nostr Integration:** Post and retrieve your encrypted password index to/from the Nostr network. See [Nostr Setup](docs/nostr_setup.md) for relay configuration and event details.
 - **Chunked Snapshots:** Encrypted vaults are compressed and split into 50 KB chunks published as `kind 30071` events with a `kind 30070` manifest and `kind 30072` deltas. The manifest's `delta_since` field stores the UNIX timestamp of the latest delta event.
 - **Automatic Checksum Generation:** The script generates and verifies a SHA-256 checksum to detect tampering.
 - **Multiple Seed Profiles:** Manage separate seed profiles and switch between them seamlessly.
@@ -82,32 +82,31 @@ before fading.
 
 SeedPass follows a layered design. The **`seedpass.core`** package exposes the
 `PasswordManager` along with service classes (e.g. `VaultService` and
-`EntryService`) that implement the main API used across interfaces.
-The command line tool in **`seedpass.cli`** is a thin adapter built with Typer
-that delegates operations to this API layer.
+`EntryService`) that implement the main API used across interfaces. Both the
+command line tool in **`seedpass.cli`** and the FastAPI server in
+**`seedpass.api`** delegate operations to this core. The BeeWare desktop
+interface (`seedpass_gui.app`) and an optional browser extension reuse these
+services, with the extension communicating through the API layer.
 
-The BeeWare desktop interface lives in **`seedpass_gui.app`** and can be
-started with either `seedpass-gui` or `python -m seedpass_gui`. It reuses the
-same service objects to unlock the vault, list entries and search through them.
-
-An optional browser extension can communicate with the FastAPI server exposed by
-`seedpass.api` to manage entries from within the browser.
+Nostr synchronisation lives in the **`nostr`** modules. The core services call
+into these modules to publish or retrieve encrypted snapshots and deltas from
+configured relays.
 
 ```mermaid
 graph TD
-    core["seedpass.core"]
     cli["CLI"]
     api["FastAPI server"]
-    gui["BeeWare GUI"]
-    ext["Browser Extension"]
+    core["seedpass.core"]
+    nostr["Nostr client"]
+    relays["Nostr relays"]
 
     cli --> core
-    gui --> core
     api --> core
-    ext --> api
+    core --> nostr
+    nostr --> relays
 ```
 
-See `docs/ARCHITECTURE.md` for details.
+See `docs/ARCHITECTURE.md` and [Nostr Setup](docs/nostr_setup.md) for details.
 
 ## Prerequisites
 
diff --git a/docs/nostr_setup.md b/docs/nostr_setup.md
new file mode 100644
index 0000000..f446e16
--- /dev/null
+++ b/docs/nostr_setup.md
@@ -0,0 +1,33 @@
+# Nostr Setup
+
+This guide explains how SeedPass uses the Nostr protocol for encrypted vault backups and how to configure relays.
+
+## Relay Configuration
+
+SeedPass communicates with the Nostr network through a list of relays. You can manage these relays from the CLI:
+
+```bash
+seedpass nostr list-relays      # show configured relays
+seedpass nostr add-relay <url>  # add a relay URL
+seedpass nostr remove-relay <n> # remove relay by index
+```
+
+At least one relay is required for publishing and retrieving backups. Choose relays you trust to remain online and avoid those that charge high fees or aggressively rate‑limit connections.
+
+## Manifest and Delta Events
+
+Backups are published as parameterised replaceable events:
+
+- **Kind 30070 – Manifest:** describes the snapshot and lists chunk IDs. The optional `delta_since` field stores the UNIX timestamp of the latest delta event.
+- **Kind 30071 – Snapshot Chunk:** each 50 KB fragment of the compressed, encrypted vault.
+- **Kind 30072 – Delta:** captures changes since the last snapshot.
+
+When restoring, SeedPass downloads the most recent manifest and applies any newer delta events.
+
+## Troubleshooting
+
+- **No events found:** ensure the relays are reachable and that the correct fingerprint is selected.
+- **Connection failures:** some relays only support WebSocket over TLS; verify you are using `wss://` URLs where required.
+- **Stale data:** if deltas accumulate without a fresh snapshot, run `seedpass nostr sync` to publish an updated snapshot.
+
+Increasing log verbosity with `--verbose` can also help diagnose relay or network issues.
diff --git a/src/seedpass/cli/nostr.py b/src/seedpass/cli/nostr.py
index 612bdf8..ba26e49 100644
--- a/src/seedpass/cli/nostr.py
+++ b/src/seedpass/cli/nostr.py
@@ -5,7 +5,9 @@ import typer
 from .common import _get_services, _get_nostr_service
 
 
-app = typer.Typer(help="Interact with Nostr relays")
+app = typer.Typer(
+    help="Interact with Nostr relays. See docs/nostr_setup.md for configuration and troubleshooting."
+)
 
 
 @app.command("sync")