From 44c17eee3d6b6ac6a4e280577f6f2f84b86281cb Mon Sep 17 00:00:00 2001
From: TheGeneralist <180094941+thegeneralist01@users.noreply.github.com>
Date: Sun, 21 Jun 2026 19:22:59 +0200
Subject: [PATCH] docs: document runtime entrypoints

---
 ARCHIVR-MENTAL-MODEL.md | 34 ++++++++++++++++++++++++++++++++
 docs/README.md          | 43 +++++++++++++++++++++++++++++++++++++++++
 2 files changed, 77 insertions(+)

diff --git a/ARCHIVR-MENTAL-MODEL.md b/ARCHIVR-MENTAL-MODEL.md
index 01f4387..3ce03f6 100644
--- a/ARCHIVR-MENTAL-MODEL.md
+++ b/ARCHIVR-MENTAL-MODEL.md
@@ -57,6 +57,40 @@ label = "Personal"
 archive_path = "/path/to/archive/.archivr"
 ```
 
+## How To Run It
+
+There are two user-facing binaries:
+
+| Binary | Purpose |
+|---|---|
+| `archivr` | CLI for initializing archives and capturing material into one archive |
+| `archivr-server` | Web server for browsing one or more existing archives |
+
+The CLI writes archive data:
+
+```sh
+nix run .#archivr -- init ./my-archive --name "My Archive"
+nix run .#archivr -- archive file:///absolute/path/to/file.pdf
+```
+
+The server reads archive data:
+
+```sh
+nix run .#archivr-server -- ./archivr-server.toml
+```
+
+If no config path is passed, the server reads `./archivr-server.toml`.
+The config is a server registry, not archive data:
+
+```toml
+[[archives]]
+id = "personal"
+label = "Personal"
+archive_path = "/absolute/path/to/my-archive/.archivr"
+```
+
+The packaged Nix server wrapper sets `ARCHIVR_STATIC_DIR` so the server can find the installed web UI assets. Source-tree runs do not need that variable because they fall back to `crates/archivr-server/static`.
+
 ## Write Data Flow
 
 When archiving something through the CLI:
diff --git a/docs/README.md b/docs/README.md
index c6d1eba..7c35eea 100644
--- a/docs/README.md
+++ b/docs/README.md
@@ -56,6 +56,49 @@ This project aims to provide a reliable solution for archiving important data fr
 - Direct platform URLs
 - Platform shorthand inputs such as `tweet:...`, `yt:...`, or `instagram:...`
 
+## Running Archivr
+
+Archivr currently ships as two binaries:
+
+- `archivr`
+  - The CLI for creating and writing to one archive.
+  - Use this for `init` and `archive`.
+- `archivr-server`
+  - The web server for reading one or more existing archives through the browser UI.
+  - Use this after archives already exist.
+
+With Nix, run the CLI with:
+
+```sh
+nix run .#archivr -- init ./my-archive --name "My Archive"
+nix run .#archivr -- archive file:///absolute/path/to/file.pdf
+```
+
+Run the web server with:
+
+```sh
+nix run .#archivr-server -- ./archivr-server.toml
+```
+
+The server expects a TOML registry file. If no path is passed, it reads `./archivr-server.toml`.
+
+Example:
+
+```toml
+[[archives]]
+id = "personal"
+label = "Personal"
+archive_path = "/absolute/path/to/my-archive/.archivr"
+```
+
+Then open:
+
+```text
+http://127.0.0.1:8080
+```
+
+When installed through Nix, `archivr-server` is wrapped so it can find the static web UI assets automatically. The wrapper sets `ARCHIVR_STATIC_DIR` to the installed static asset directory. Running from source with `cargo run -p archivr-server` falls back to `crates/archivr-server/static`.
+
 ### Supported Platforms
 
 - Local files: `file:///absolute/path/to/file.ext`