diff --git a/README.md b/README.md
index a80a23f..5d84e75 100644
--- a/README.md
+++ b/README.md
@@ -14,7 +14,7 @@ Either one installs the dependencies and opens a live preview at
Manually:
```bash
-pip install mkdocs-material mkdocs-macros-plugin pyyaml
+pip install mkdocs-material mkdocs-macros-plugin mkdocs-glightbox pyyaml
python3 tools/make_placeholders.py # fill missing screenshots with placeholders
mkdocs serve # preview at http://127.0.0.1:8000
mkdocs build --strict # static site into site/
diff --git a/docs/getting-started/installation.md b/docs/getting-started/installation.md
index c7ae157..5db0938 100644
--- a/docs/getting-started/installation.md
+++ b/docs/getting-started/installation.md
@@ -23,12 +23,35 @@ Get the latest release from the [plugin releases page](https://bitcoin-after.lif
{ .screenshot }
*Electrum → Tools → Plugins.*
+BAL is an **external plugin**, so it is added from a `.zip` file:
+
1. Open Electrum and go to **Tools → Plugins**.
-2. Choose **install from file** and select the BAL zip.
+2. **Internal plugins** are listed in the dialog — you toggle their checkbox to enable or disable them.
+3. **External plugins** such as BAL are imported from `.zip` files with the **Add** button in the plugins dialog.
+4. Some plugins (hardware wallets) are enabled automatically when you create or restore a hardware wallet.
{ .screenshot }
*Selecting the plugin archive.*
+### First-time setup: the plugin authorization password
+
+The first time you load **any** external plugin, Electrum asks you to set a **plugin
+authorization password**. Two things to know about it:
+
+- It is **independent of your wallet password**, and it can be reset if you forget it.
+- Setting it requires **administrator (root) permissions**, because Electrum writes a
+ password-derived public key into the system. On later startups that key lets Electrum
+ verify the plugin's authenticity without asking you for the password again.
+
+!!! info "Why administrator permissions are needed"
+ This is an Electrum security measure, not something specific to BAL. The elevated
+ permissions are what stop **malware from silently installing or modifying plugins**,
+ or from tampering with the stored key. External plugins can only be enabled by
+ someone who can enter that password — so a piece of malware running as your normal
+ user cannot enable one behind your back.
+
+ Full details: [plugins.electrum.org](https://plugins.electrum.org/)
+
## 3. Enable and restart
Tick **Bitcoin After Life** in the plugin list, then restart Electrum.
@@ -51,3 +74,9 @@ Step-by-step installation notes for specific platforms are kept in their own rep
- [Windows installation](https://bitcoin-after.life/gitea/bitcoinafterlife/bal_plugin_windows_installation)
- [Linux installation](https://bitcoin-after.life/gitea/bitcoinafterlife/bal_plugin_linux_installation)
+
+## More on Electrum plugins
+
+For how Electrum's plugin system works in general — internal vs external plugins, the
+authorization password, and the plugin directory — see the official reference:
+[plugins.electrum.org](https://plugins.electrum.org/)
diff --git a/docs/img/architecture.svg b/docs/img/architecture.svg
new file mode 100644
index 0000000..bbd0281
--- /dev/null
+++ b/docs/img/architecture.svg
@@ -0,0 +1,214 @@
+
diff --git a/docs/index.md b/docs/index.md
index fb0b8af..81e64fc 100644
--- a/docs/index.md
+++ b/docs/index.md
@@ -1,6 +1,6 @@
diff --git a/docs/protocol/how-it-works.md b/docs/protocol/how-it-works.md
index ae02700..eeeafd6 100644
--- a/docs/protocol/how-it-works.md
+++ b/docs/protocol/how-it-works.md
@@ -2,6 +2,11 @@
A summary of the mechanism, for readers who want to understand what happens underneath the interface.
+## Architecture at a glance
+
+{ .diagram }
+*How a will travels from the Electrum plugin to the Bitcoin network. Click to enlarge.*
+
## The building block: absolute time-locks
Bitcoin lets a transaction declare an **absolute `nLockTime`**: a point in time before which the transaction is not valid. Nodes reject such a transaction from the mempool until that moment arrives — this is a consensus rule, not a policy choice.
diff --git a/docs/stylesheets/extra.css b/docs/stylesheets/extra.css
index c476c19..934098d 100644
--- a/docs/stylesheets/extra.css
+++ b/docs/stylesheets/extra.css
@@ -226,3 +226,24 @@ p > img.screenshot + em {
.bal-hero .logo-dark { display: none; }
[data-md-color-scheme="slate"] .bal-hero .logo-light { display: none; }
[data-md-color-scheme="slate"] .bal-hero .logo-dark { display: inline; }
+
+/* -------- Diagrams -------------------------------------------------------- */
+/* Wide technical diagrams: full content width, light frame, no drop shadow
+ (they already have their own internal panels). */
+img.diagram {
+ display: block;
+ width: 100%;
+ height: auto;
+ border: 1px solid var(--md-default-fg-color--lightest);
+ border-radius: 8px;
+ background: var(--bal-panel);
+ padding: 4px;
+}
+[data-md-color-scheme="slate"] img.diagram { background: #f6f8fa; }
+img.diagram + em {
+ display: block;
+ margin-top: .4rem;
+ font-size: .72rem;
+ font-style: normal;
+ color: var(--md-default-fg-color--light);
+}
diff --git a/docs/will-executors/running-a-server.md b/docs/will-executors/running-a-server.md
index fcb3354..1534b7e 100644
--- a/docs/will-executors/running-a-server.md
+++ b/docs/will-executors/running-a-server.md
@@ -20,6 +20,14 @@ This page covers setting up your own Will-Executor node. If you are wondering *w
Two things to keep in mind: for a user's redundancy, a consortium still counts as **one** Will-Executor; and the internal split is an agreement outside the protocol, which BAL neither arbitrates nor guarantees.
+See the [architecture diagram](../protocol/how-it-works.md#architecture-at-a-glance) for how
+`bal-server` and `bal-pusher` fit into the full flow from plugin to Bitcoin node.
+
+## Architecture at a glance
+
+{ .diagram }
+*How a will travels from the Electrum plugin to the Bitcoin network. Click to enlarge.*
+
## The two components
| Component | Role |
diff --git a/docs/will-executors/what-they-are.md b/docs/will-executors/what-they-are.md
index e9500f4..9ba5ac0 100644
--- a/docs/will-executors/what-they-are.md
+++ b/docs/will-executors/what-they-are.md
@@ -11,6 +11,10 @@ A Will-Executor is a server with one narrow job: **it stores pre-signed inherita
What it *does* require is longevity: being still there, still working, years from now.
+!!! info "See the whole flow"
+ The [architecture diagram](../protocol/how-it-works.md#architecture-at-a-glance) shows how a
+ will travels from the Electrum plugin, through a Will-Executor, to the Bitcoin network.
+
## Why competition makes it work
When you create your will, the plugin generates **a separate transaction for every Will-Executor you selected**. Each of those transactions carries an extra output paying that specific server its fee.
diff --git a/internal/source-notes.md b/internal/source-notes.md
index 9bf4315..6563311 100644
--- a/internal/source-notes.md
+++ b/internal/source-notes.md
@@ -26,8 +26,20 @@ Compiled July 2026. Keep this updated whenever the manual is revised.
| Will-Executor lists come from BitcoinTalk | **WeList** directory, downloaded by default |
| "prepare / sign / broadcast" run automatically on close | Still true, but the plugin **asks** — it never signs on your behalf |
+## Version bumps log
+
+| Date | plugin_version | electrum_latest | Note |
+|---|---|---|---|
+| 2026-07 (initial) | 0.2.6 | 4.7.2 | Last version explicitly documented in a release ("tested with electrum 4.7.1") |
+| 2026-07-26 | 0.6.1 | 4.8.0 | Jump from 0.2.6 → 0.6.1: releases v0.5.18/v0.6.0/v0.6.1 mostly cover Tor/onion will-executor support. **`electrum_tested` left at 4.7.1 — unconfirmed for 0.6.1**, neither release's notes state an Electrum version. Verify with svatantrya before the next public update. |
+
## To verify with the developers before the next revision
+0. **Electrum version actually tested for plugin v0.6.1** (see table above) — highest priority, since it's a user-facing compatibility claim.
+0b. ~~Architecture diagram version label mismatch~~ — fixed 2026-07-26: `docs/img/architecture.svg`
+ now reads "Python · v0.6.1", matching `plugin_version`. Still worth asking the diagram's source
+ (likely a design tool, not this repo) to drop the hardcoded version label so it doesn't need a
+ manual edit at every future release.
1. **Exact execution tolerance.** The manual states "~1 hour after the set time, due to the
11-block median". Confirm this still holds.
2. **Relative (Raw) date syntax.** The PDF documents `d` and `y` suffixes. Confirm which
diff --git a/mkdocs.yml b/mkdocs.yml
index e27b5e5..82458c6 100644
--- a/mkdocs.yml
+++ b/mkdocs.yml
@@ -65,6 +65,13 @@ nav:
plugins:
- search
+ - glightbox: # click-to-enlarge on every image (screenshots + diagrams)
+ touchNavigation: true
+ loop: false
+ zoomable: true
+ draggable: true
+ skip_classes:
+ - no-lightbox
- macros:
on_error_fail: true # a typo in a variable breaks the build, not the page
@@ -102,9 +109,9 @@ markdown_extensions:
# =============================================================================
extra:
bal:
- plugin_version: "0.2.6" # latest plugin release
- electrum_tested: "4.7.1" # Electrum version that release was tested against
- electrum_latest: "4.7.2" # latest stable Electrum the manual assumes
+ plugin_version: "0.6.1" # latest plugin release
+ electrum_tested: "4.7.1" # UNCONFIRMED for v0.6.1 — see internal/source-notes.md
+ electrum_latest: "4.8.0" # latest stable Electrum the manual assumes
welist_fee_sats: "50,000" # WeList yearly listing fee
welist_period_days: "365"
last_reviewed: "2026-07" # bump when you do a full pass over the manual
- 
+