diff --git a/CHANGELOG_REFACTOR.md b/CHANGELOG_REFACTOR.md
index 87fbe19..4d7484d 100644
--- a/CHANGELOG_REFACTOR.md
+++ b/CHANGELOG_REFACTOR.md
@@ -668,3 +668,24 @@ render before/after mock-ups for visual approval.
star-import re-exports, one F841, one F541) — no new issues.
- Version bumped to **0.3.3** (`bal/VERSION`, `bal/__init__.py`,
`bal/manifest.json`).
+
+## 18. Documentation site (docs/) — no behaviour change
+
+Added a `docs/` tree that renders directly on GitHub and GitHub Pages (no PDF):
+
+- `docs/inheritance-options.md` + `.html`: a code‑accurate **Inheritance Options
+ Guide** covering every change a user can make (date earlier/later, add/remove
+ heir, change percentages, fees, will‑executors), each transaction status flag
+ and its colour, and what happens on the will‑executor servers. Includes a
+ decision **flow chart** (GitHub‑native Mermaid block in the `.md`, plus a
+ static SVG fallback `docs/images/inheritance-flow.svg`, plus a live Mermaid
+ render in the `.html`). Behaviour is derived directly from
+ `core/will.py::is_will_valid` / `check_willexecutors_and_heirs` and
+ `gui/qt/window.py::build_inheritance_transaction`.
+- `docs/manual/README.md` + `manual.html` + `images/`: the official **BAL User
+ Manual (revB)** converted from the upstream Gitea PDF into GitHub‑friendly
+ Markdown/HTML with the original screenshots re‑rendered at high resolution
+ (`docs/manual/images/fig*.png`, `logo.png`).
+- `docs/README.md`: documentation index linking both documents.
+
+No plugin code changed; 186 tests still pass.
diff --git a/docs/README.md b/docs/README.md
new file mode 100644
index 0000000..9d1f272
--- /dev/null
+++ b/docs/README.md
@@ -0,0 +1,36 @@
+
+ 
+
+
+BAL — Bitcoin After Life · Documentation
+
+Documentation for the **BAL** open‑source Electrum plugin for Bitcoin digital
+inheritance. Everything here is plain Markdown + images (and optional styled
+HTML), so it renders directly on GitHub and via GitHub Pages — **no PDF needed**.
+
+## Contents
+
+| Document | Markdown (GitHub) | Styled HTML |
+|---|---|---|
+| **User Manual (revB)** — full plugin manual with screenshots | [`manual/README.md`](./manual/README.md) | [`manual/manual.html`](./manual/manual.html) |
+| **Inheritance Options Guide** — every change (date earlier/later, add/remove heir, change %, fees, executors) + decision flow chart + transaction states & server effects | [`inheritance-options.md`](./inheritance-options.md) | [`inheritance-options.html`](./inheritance-options.html) |
+
+## Quick links
+
+- 📖 **New to BAL?** Start with the [User Manual](./manual/README.md).
+- 🔁 **Changing a will?** See the [Inheritance Options Guide](./inheritance-options.md)
+ to know exactly what happens (and whether it costs an on‑chain fee).
+
+## Viewing the HTML versions
+
+- On GitHub Pages: enable Pages for this repository (Settings → Pages → deploy
+ from branch, folder `/docs`), then open
+ `https://.github.io//manual/manual.html`.
+- Offline: download the `docs/` folder and open the `.html` files in any browser
+ (the styled manual works fully offline; the inheritance‑options page loads
+ Mermaid from a CDN for the live diagram, and also ships a static SVG fallback).
+
+---
+
+*The manual is the GitHub‑friendly edition of the official BAL PDF
+([bal_plugin_manual](https://bitcoin-after.life/gitea/bitcoinafterlife/bal_plugin_manual)).*
diff --git a/docs/inheritance-options.md b/docs/inheritance-options.md
new file mode 100644
index 0000000..c75b3b9
--- /dev/null
+++ b/docs/inheritance-options.md
@@ -0,0 +1,278 @@
+# BAL — Inheritance Options Guide
+
+> How the **Bitcoin After Life** Electrum plugin reacts to every change you can
+> make to your will: changing the date (earlier / later), adding or removing an
+> heir, changing percentages, fees or will‑executors — and what happens to the
+> transactions held by the will‑executor servers.
+
+This guide describes the **actual behaviour of the code** (`core/will.py` →
+`is_will_valid` / `check_willexecutors_and_heirs` and
+`gui/qt/window.py` → `build_inheritance_transaction`). It is meant for end
+users *and* for anyone who wants to understand the on‑chain consequences of
+each action.
+
+---
+
+## 1. The mental model in one paragraph
+
+Your will is a **tree of pre‑signed Bitcoin transactions**. Each leaf
+transaction sends your coins to your heirs and is **time‑locked** (`nLockTime`)
+so it can only be broadcast **after** a future date/block. A copy of each signed
+transaction is handed to one or more **will‑executor servers**. While you are
+alive you periodically prove you are alive (the *Check‑Alive threshold*). When
+you change anything in your will, BAL must decide between three outcomes:
+
+1. **Do nothing** — the will is still coherent.
+2. **Rebuild** (re‑prepare + re‑sign, *no on‑chain cost*) — the will changed but
+ nothing dangerous is already committed.
+3. **Invalidate on‑chain first** (costs a real Bitcoin fee) — a previously
+ **signed/sent** transaction must be neutralised by spending its inputs,
+ *before* a new will can safely replace it.
+
+The whole point of rule 3 is safety: **a will‑executor must never be able to
+broadcast an old transaction that would execute your inheritance too early.**
+
+---
+
+## 2. Transaction states (status flags)
+
+Every will item (`WillItem`) carries a set of boolean status flags. The most
+important ones:
+
+| Status | Meaning | Set when |
+|---|---|---|
+| `VALID` | The item is the current, usable plan | default `True`; cleared by INVALIDATED/REPLACED/CONFIRMED/PENDING |
+| `COMPLETE` (*Signed*) | The transaction has been **signed** | after you press **Sign** |
+| `PUSHED` | The signed tx was **sent to the will‑executor(s)** | after **Broadcast** to executors |
+| `CHECKED` | The will‑executor **confirmed** it holds the tx | after a successful server **Check** (implies `PUSHED`) |
+| `CHECK_FAIL` | The server **check failed** | a queried executor did not return the tx |
+| `PUSH_FAIL` | Sending to the executor failed | cleared when PUSHED becomes true |
+| `CONFIRMED` | The tx is **mined on‑chain** | seen on‑chain with height > 0 |
+| `PENDING` | The tx is **in the mempool** (height 0) | seen on‑chain, not yet mined |
+| `INVALIDATED` | Its inputs were spent → it can never confirm | invalidation tx created / inputs gone |
+| `REPLACED` | Superseded by a child tx with earlier locktime | a replacing child was found |
+| `EXPIRED` | Its locktime is already in the past relative to the check date | `check_will_expired` |
+
+Flag transitions enforced by `set_status` (the safety rules baked in the code):
+
+- Setting `INVALIDATED` / `REPLACED` / `CONFIRMED` / `PENDING` → clears `VALID`.
+- Setting `CONFIRMED` / `PENDING` → clears `INVALIDATED`.
+- Setting `PUSHED` → clears `PUSH_FAIL` **and** `CHECK_FAIL`.
+- Setting `CHECKED` → implies `PUSHED` (and clears `PUSH_FAIL`).
+
+### How states map to row colour in the list
+
+| State (first match wins) | Colour | Hex |
+|---|---|---|
+| `CHECK_FAIL` | red | `#e83845` |
+| `INVALIDATED` / `REPLACED` | grey | (muted) |
+| `CONFIRMED` | green | (confirmed on server / chain) |
+| `COMPLETE` (signed, **not** yet pushed) | blue | `#2bc8ed` |
+| `VALID` (prepared, not signed) | default | — |
+
+> **Note (v0.3.3 fix):** a will that is *signed but not yet broadcast*
+> (`COMPLETE` and **not** `PUSHED`) is **not** queried on the server, so it stays
+> **blue** instead of turning red. Only `PUSHED` wills are server‑checked.
+
+---
+
+## 3. The decision flow
+
+When you press **Prepare** (or on the periodic **Check**, or when Electrum
+closes), BAL runs `is_will_valid`. Depending on what it finds it raises a
+specific exception, and each exception maps to one action.
+
+> 📊 A styled version of this guide (with a live diagram) is in
+> [`inheritance-options.html`](./inheritance-options.html) — open it via GitHub
+> Pages or download and open it in any browser.
+
+The static diagram below renders everywhere; the Mermaid block after it renders
+live on GitHub.
+
+
+
+```mermaid
+flowchart TD
+ A([You change something & press Prepare / Check]) --> B{Heirs defined?}
+ B -- No --> Z1[/Show: "Heirs are not defined" — stop/]
+ B -- Yes --> C{Check-Alive threshold
in the future?}
+ C -- No, it's in the past --> INV1[[Invalidate on-chain
CheckAliveError]]
+ C -- Yes --> D{Any VALID tx with
locktime earlier than
the new date?}
+
+ D -- "Yes (you moved the date EARLIER / anticipate)" --> E{Was that tx already
signed or sent?}
+ E -- "Not signed yet" --> R1[[Rebuild only
no on-chain cost]]
+ E -- "Signed / sent" --> INV2[[Invalidate on-chain FIRST
WillExpired]]
+
+ D -- "No" --> F{Will-executor / fee /
heirs unchanged?}
+ F -- "Fee changed" --> R2[[Rebuild
TxFeesChanged]]
+ F -- "Will-executor changed/absent" --> R3[[Rebuild
WillExecutorNotPresent / Change]]
+ F -- "Heir added or removed,
% or address changed" --> G{Is it a POSTPONE of an
already signed/sent tx?}
+
+ G -- "Yes (date later + signed/sent)" --> INV3[[Invalidate on-chain FIRST,
then rebuild — WillPostponed]]
+ G -- "No (never signed, or pure heir/% change)" --> R4[[Rebuild only
HeirNotFound / HeirChange]]
+
+ F -- "Nothing changed" --> OK([Will still coherent — do nothing])
+
+ R1 --> SIGN
+ R2 --> SIGN
+ R3 --> SIGN
+ R4 --> SIGN
+ SIGN([Re-sign the new transactions]) --> PUSH([Broadcast to will-executors])
+
+ INV1 --> SB
+ INV2 --> SB
+ INV3 --> SB
+ SB([Sign & broadcast the INVALIDATION tx on-chain]) --> WAIT{Invalidation
confirmed?}
+ WAIT -- "Yes" --> REBUILD([Press Prepare again → build the new will])
+ REBUILD --> SIGN
+```
+
+---
+
+## 4. Every option, explained
+
+### 4.1 Changing the Check‑Alive date / heir locktime
+
+The locktime is the future moment from which a transaction becomes spendable by
+the heir. BAL compares the **requested** locktime against the locktime
+**frozen inside the already‑signed transaction** (`w.tx.locktime`), which is
+exactly what the will‑executors hold — not the in‑memory copy.
+
+| You do… | Tx already signed/sent? | Result | On‑chain fee? |
+|---|---|---|---|
+| **Move date LATER** (postpone) | **No** (never signed) | Plain **rebuild** (`HeirNotFound` fall‑through) | **No** |
+| **Move date LATER** (postpone) | **Yes** | **Invalidate first**, then rebuild (`WillPostponed`) | **Yes** |
+| **Move date EARLIER** (anticipate) | any | Old tx becomes **expired** → **invalidate** (`WillExpired`) | **Yes** |
+| Check‑Alive threshold already passed | — | **Invalidate** (`CheckAliveError`) | **Yes** |
+
+> **Why postpone needs an on‑chain invalidation:** the will‑executor still holds
+> the *old* transaction with the *earlier* locktime. If you simply re‑signed a
+> later one, a malicious or buggy executor could still broadcast the old one as
+> soon as its earlier locktime is reached — executing your inheritance too soon.
+> Spending the old transaction's inputs on‑chain makes the old tx **un‑minable**.
+> The plugin tells you this explicitly and offers to build the invalidation tx.
+
+> **Why anticipate is also on‑chain:** moving the date earlier makes the current
+> committed tx *expired* relative to the new check date; the safe path is the
+> same — invalidate, then rebuild.
+
+### 4.2 Adding an heir
+
+`check_willexecutors_and_heirs` walks every heir in the current set; an heir
+present in `heirs` but not yet found in the will raises **`HeirNotFoundException`**.
+
+- **Result:** **rebuild** (re‑prepare + re‑sign).
+- **On‑chain fee:** **No** — *unless* the will being changed was already
+ signed/sent and the change also moves a locktime later (then the postpone rule
+ in 4.1 applies).
+
+### 4.3 Removing an heir
+
+The will still carries an heir that is no longer in your current heirs set →
+**`HeirNotFoundException`** (the removed‑heir branch).
+
+- **Result:** **rebuild**, so the removed heir disappears from the new
+ transactions.
+- **On‑chain fee:** **No** for a will that was only *prepared*. If the old will
+ was already signed/sent, you must invalidate it on‑chain first (same safety
+ reasoning as a postpone), then rebuild.
+
+> **v0.3.2 fix:** removing an heir is now correctly detected on **Check** and on
+> Electrum **close**, not only on Prepare.
+
+### 4.4 Changing an heir's percentage or address
+
+If the stored heir `[address, amount/percentage]` differs from the current one,
+the will is no longer coherent → it is treated like an heir change
+(**`HeirChangeException`** / `HeirNotFound`).
+
+- **Result:** **rebuild** with the new amounts.
+- **On‑chain fee:** **No** (unless the old will was signed/sent → invalidate
+ first).
+
+> Reminder shown by the plugin: *“In the inheritance process the entire wallet is
+> always fully emptied”* — the amounts across all heirs must add up so that the
+> whole spendable balance is distributed; otherwise an `AmountException` warns you
+> to adjust.
+
+### 4.5 Changing the transaction fee (sat/byte)
+
+Each will item stores the fee rate it was built with. A different rate raises
+**`TxFeesChangedException`**.
+
+- **Result:** **rebuild** at the new fee rate.
+- **On‑chain fee:** **No** to rebuild (you only pay when the inheritance — or an
+ invalidation — is actually broadcast on‑chain).
+
+### 4.6 Changing or removing a will‑executor
+
+- A selected will‑executor that the will does not reference raises
+ **`WillExecutorNotPresent`**.
+- A will‑executor whose details changed raises **`WillexecutorChangeException`**.
+- Running with “no will‑executor” but no backup transaction raises
+ **`NoWillExecutorNotPresent`**.
+
+- **Result:** **rebuild** and re‑distribute to the (new) executor set.
+- **On‑chain fee:** **No** to rebuild. The new signed transactions are simply
+ pushed to the new/updated executors; the old executor will eventually fail its
+ own check and drop the obsolete tx.
+
+### 4.7 Nothing changed
+
+If heirs, percentages, fees, executors and locktimes all still match the signed
+transactions, `is_will_valid` returns `True` and **nothing happens** — your will
+stays exactly as broadcast to the executors.
+
+---
+
+## 5. What happens on the will‑executor servers
+
+| Your action | Effect on the servers |
+|---|---|
+| **Prepare** (rebuild) | Nothing yet — new txs exist only locally until you Sign + Broadcast. |
+| **Sign** | Still local; tx becomes `COMPLETE` (blue). |
+| **Broadcast to executors** | The signed txs are uploaded; items become `PUSHED`. |
+| **Check** | Each `PUSHED` will is queried; success → `CHECKED` (green), failure → `CHECK_FAIL` (red). |
+| **Invalidate (on‑chain)** | You spend the committed inputs on the Bitcoin network. Once confirmed, the executor's stored tx can no longer be mined; on the next check it is dropped / shown invalidated. |
+| **Re‑broadcast a new will** | Executors replace the obsolete copy with the new signed tx. |
+
+> A row turning **red** (`CHECK_FAIL`) after a Check means a will‑executor that
+> *should* hold your transaction did not return it — re‑Broadcast, or rebuild,
+> to fix it. A row that is merely **blue** is signed‑but‑not‑yet‑sent and is
+> perfectly normal.
+
+---
+
+## 6. Quick reference — does it cost a Bitcoin fee?
+
+| Change | Rebuild? | On‑chain invalidation (real fee)? |
+|---|---|---|
+| Add heir (will only prepared) | ✅ | ❌ |
+| Remove heir (will only prepared) | ✅ | ❌ |
+| Change % / address (only prepared) | ✅ | ❌ |
+| Change fee rate | ✅ | ❌ |
+| Change / remove will‑executor | ✅ | ❌ |
+| Move date **earlier** (anticipate) | ✅ after | ✅ **yes** |
+| Move date **later** (postpone) — will **signed/sent** | ✅ after | ✅ **yes** |
+| Move date **later** (postpone) — will **only prepared** | ✅ | ❌ |
+| Check‑Alive threshold already in the past | ✅ after | ✅ **yes** |
+| Any change to an **already signed/sent** will | ✅ after | ✅ **yes** (invalidate first) |
+| Nothing changed | ❌ | ❌ |
+
+---
+
+## 7. Golden rules
+
+1. **Before it's signed**, changing anything is free — just **Prepare** again.
+2. **After it's signed/sent**, moving the date or otherwise replacing it requires
+ an **on‑chain invalidation first** (a small Bitcoin fee) so an old transaction
+ can never be executed early.
+3. Always finish with **Sign → Broadcast → Check** so the will‑executors hold the
+ *current* plan (green), not an obsolete one.
+4. The wallet is always **fully emptied** by the inheritance, so heir amounts must
+ add up.
+
+---
+
+*This document reflects BAL plugin v0.3.3. Behaviour is derived directly from
+`core/will.py` and `gui/qt/window.py`.*
diff --git a/docs/manual/README.md b/docs/manual/README.md
new file mode 100644
index 0000000..0785141
--- /dev/null
+++ b/docs/manual/README.md
@@ -0,0 +1,508 @@
+
+ 
+
+
+BitcoinAfter.Life — BAL PROTOCOL 1.0
+USER MANUAL (revB)
+
+> This is the GitHub‑friendly (HTML/Markdown + images) edition of the official
+> BAL user manual. The original PDF lives in the
+> [bal_plugin_manual](https://bitcoin-after.life/gitea/bitcoinafterlife/bal_plugin_manual)
+> Gitea repository. A styled single‑page version is available as
+> [`manual.html`](./manual.html).
+
+---
+
+Welcome to using **BAL**, the open‑source plugin for Electrum Wallet, dedicated
+to managing **bitcoin digital inheritance**.
+
+An open‑source plugin is a software extension that adds functionality to an
+existing program, and whose source code is publicly available. This means that
+anyone can view, modify, and distribute the plugin code.
+
+The plugin was designed for **Electrum**, the Gold standard of Bitcoin wallets.
+
+It was not considered reasonable to proceed with the development of a new wallet
+or a fork of a wallet (a bifurcation of Electrum's code) so as not to put funds
+at risk. Instead, we thought it prudent to lean as a plugin on the most tested
+and therefore secure open‑source Bitcoin wallet (**Electrum**), trusting that in
+the future the plugin will be placed directly on Electrum by default.
+
+## Installing the BAL plugin
+
+The steps for installing the BAL plugin are very simple:
+
+1. Install the latest version of **Electrum** (Bitcoin wallet).
+2. Install the **BAL plugin** (find the files on the Bitcoin‑after.life site or
+ links on the Bitcointalk forum), copying it to the Electrum plugins folder.
+3. Activate the plugin from the Electrum menu (**Tools → Plugins → BAL**).
+4. **Restart Electrum.**
+
+Now you are ready to leave your digital legacy to your heirs!
+
+---
+
+## The BAL interface
+
+
+
+*Figure 1 — the screen that appears after starting Electrum with the BAL plugin
+installed.*
+
+As you can see there are now two new tabs (**HEIRS** and **WILL**) on the
+Electrum interface.
+
+- **HEIRS** = the screen of heirs to whom you want to leave your inheritance.
+- **WILL** = the screen that shows you the technical details of your inheritance:
+ - locktime
+ - creation time
+ - transaction fees for miners
+ - status
+ - heirs
+ - will‑executor with associated fees
+
+> **NB:** Inheritance with the BAL plugin can also be set on a wallet that is
+> still receiving incoming transactions not yet confirmed on the blockchain.
+
+---
+
+## The HEIRS parameters
+
+You can leave the default plugin parameters; they are more than fine for 99 % of
+inheritance cases.
+
+
+
+*Figure 2 — the parameters on the HEIRS tab: (1) Delivery Time, (2) Check Alive,
+(3) Fees.*
+
+### 1 — Delivery Time (Locktime)
+
+Indicates the date on which the inheritance of your wallet on the blockchain
+will be transferred to the recipient. You can enter the inheritance date either
+as **Relative** (example: 1 year from today → `RAW = 1y`) or as a **Precise
+Date** (`Date`).
+
+If you choose **Raw**, you can insert various options based on a suffix:
+
+- `d`: number of days after the current day (e.g. `1d` means tomorrow)
+- `y`: number of years after the current day (e.g. `1y` means one year from today)
+
+\* The locktime can be **anticipated** to update the will.
+
+### 2 — Check Alive (Threshold)
+
+*(i.e. check whether you are still alive, and then postpone the inheritance.)*
+
+This parameter — settable as relative (`RAW`) or absolute (`DATE`) — indicates
+the time by which the inheritance will **not** be changed by postponing it.
+
+> **NB:** if you set it negative (i.e. back in time) it is as if it were not
+> there. This can be useful for doing quick inheritance tests.
+
+**Example:** if you set the inheritance to one year from today and the Check
+Alive (threshold) parameter to 6 months, then in 8 months — if you open
+Electrum — the BAL plugin will ask whether you want to update the inheritance
+date.
+
+**Why does it do this?** Because it assumes that if you open the Electrum wallet
+with the plugin, you are still alive, and therefore estimates that you will
+still live a certain amount of time, so you probably want to postpone the
+inheritance so as not to transfer it too soon while you are still alive.
+
+#### A practical example
+
+Today is **January 1, 2025**. I set the inheritance for **December 1, 2025**
+(11 months from now) and the Check‑Alive (threshold) at **6 months** (so
+**June 1, 2025**):
+
+**Future case histories:**
+
+- **Case 1** — I no longer access the Electrum wallet: the inheritance on
+ December 1, 2025 will be transferred to the heir (sent to Bitcoin nodes by the
+ will‑executors).
+- **Case 2** — I access the wallet in 4 months (earlier than the set 6‑month
+ Check‑Alive threshold); the inheritance will remain set for December 1, 2025.
+- **Case 3** — I access the wallet in 7 months (later than the 6 months set);
+ the plugin will ask whether I want to **postpone** the date of the inheritance,
+ because it assumes I am still alive and may want to postpone the inheritance so
+ as not to transfer it while I am still alive.
+
+### 3 — Fees
+
+Denoted in **satoshi/vbyte**. This parameter indicates the fees that go to the
+**miners** to have the transaction validated on the blockchain at the time of
+inheritance. It is the classic fee/commission you pay every time you send
+bitcoin to another wallet.
+
+We recommend leaving the default value of **100 sat/vbyte**; this way you will be
+sure the inheritance is accepted by the miners, even on days when the blockchain
+is saturated and network costs are high. (As of January 2025, that is roughly
+$25 USD for a wallet without too many UTXOs — a value that allows the tx to be
+placed on the blockchain even on congested days.)
+
+---
+
+## IMPORTANT — sizing inheritance transaction amounts
+
+**Automatic sizing to 100 % of the wallet.** The plugin always makes sure that
+**ALL** the value of the wallet is delivered to the heirs.
+
+- **Example:** I have a wallet with 3 BTC. I write as inheritance 1 BTC to JONNY
+ and 10 % to ANDREA. The BAL plugin sends 1 BTC to Jonny and **all the rest**
+ (2 BTC) to Andrea.
+- Or: I set 5 % to Jonny and 80 % to Andrea. The plugin **recalculates** the
+ percentages proportionally so the wallet is completely emptied. Instead of
+ 5 %/80 % it sends **5.9 %** to Jonny and **94.1 %** to Andrea, for a total of
+ 100 %. (Otherwise 15 % would be left in the wallet.)
+
+> **NB:** if you wanted to send only 80 % of the wallet to the heirs and make
+> 20 % inaccessible forever (bitcoins lost forever — increasing digital scarcity
+> and giving wealth to all bitcoin participants), just set **yourself** as an
+> heir with a percentage (e.g. 20 %) to an internal wallet address. This also
+> improves the privacy of the transaction, as it is difficult to understand the
+> destination wallets.
+
+- **Another example:** I own 10 BTC and want to give Jonny exactly 4 BTC and
+ Andrea exactly 2 BTC. What about the missing 4? The plugin recalculates to
+ transfer 100 %. The only way to give Jonny and Andrea the exact BTC is to
+ transfer the missing 4 to another wallet by designating a **third heir**.
+
+---
+
+## Staggered inheritance over time
+
+Currently **BAL version 1.0** does not support this. It is already in development
+for **version 2** of the protocol. In version 2 it will be possible, for
+example, to stagger the inheritance 10 % per year until the tenth year, or even
+1 % per month, month by month for 10 years — as if it were a kind of annuity,
+but without the need for third parties or intermediaries.
+
+---
+
+## The [NEW HEIR] button
+
+After setting steps 1, 2, 3, press the **[New Heir]** button and the *BAL New
+Heirs* window appears:
+
+
+
+*Figure 3 — adding a new heir.*
+
+Here you enter the following parameters:
+
+- **Name:** name of the heir, with any details you prefer.
+- **Address:** the Bitcoin wallet address where the inheritance will be sent.
+- **Amount:** how much you want to send to this heir (as a **percentage** or a
+ **fixed value**). The plugin always makes sure that 100 % of the inheritance
+ is given to the heirs (see *Sizing inheritance transactions*).
+
+> **NB:** You can add several heirs — even 10 or more.
+
+---
+
+## Delivery time changes
+
+If you change the **Delivery Time** of a will, when Electrum closes the BAL
+plugin will notify you that you need to update the inheritance.
+
+- **If you postponed the Delivery Time:** the plugin will create a transaction to
+ **invalidate** the current inheritance and create a new, postponed one. To do
+ this safely, the BAL plugin creates a transaction that it sends to the miners,
+ which you will have to **sign**, costing **100 sat/vbyte**.
+- **If you anticipated the Delivery Time:** the plugin simply sends a new
+ inheritance transaction to the **Will‑Executor servers**, which anticipates and
+ thus invalidates the transactions already sent to them.
+
+> 👉 For a complete, code‑accurate breakdown of every change (add/remove heir,
+> change percentages, fee, executor, date earlier/later) and whether it costs an
+> on‑chain fee, see the companion
+> [**Inheritance Options Guide**](../inheritance-options.md).
+
+---
+
+## RAW settings
+
+If you set, for example, `RAW‑1d` and it is, say, 5 p.m., the plugin will not
+execute the inheritance precisely 24 hours later (5 p.m. the next day) but will
+roughly estimate the blockchain block number corresponding to that time — so
+with a tolerance of a few hours.
+
+> **NB:** Inheritance is executed on nodes, on average, with a tolerance of about
+> 1 hour after the date/time set in the BAL plugin (because of the 11‑block
+> Bitcoin median).
+
+---
+
+## Heirs sheet — quick test tip
+
+If you want a quick test run, enter an upcoming legacy date/time (e.g. 18 hours
+later). For such short intervals the **Check Alive** could create problems, so
+set the Check Alive parameter **in the past** (a date before today) — e.g. a
+previous month.
+
+---
+
+## Practical example — multiple dates
+
+I have 2 children, **Peter** (12) and **Arnold** (16). I own 10 BTC and want
+each to receive 5 BTC on their respective 18th birthdays.
+
+In the current BAL plugin (1.0) it is **not** possible to set different delivery
+dates — the inheritance date is unique. So in this case I prepare **two wallets**
+of 5 BTC each and set the respective inheritance with the BAL plugin. Electrum
+helps here, as it lets you easily create and manage multiple wallets.
+
+---
+
+## BAL plugin parameters
+
+Accessible from the menu **Tools → Plugins**.
+
+### Backup Transaction
+
+
+
+*Figure 4 — the Backup Transaction option (default: Disabled).*
+
+**Backup Transaction** (default *Disabled*) is used to manage the inheritance
+transaction (locktime tx) even **without** the BAL plugin automations that rely
+on the online Will‑Executor servers.
+
+By enabling this option you also keep an **offline backup** of the signed legacy
+transaction, useful in case all online Will‑Executor servers are destroyed (a
+highly unrealistic event).
+
+The backup transaction is saved locally — on a USB stick or wherever you prefer.
+For example, it can be delivered through a notary, trusted persons, or even
+directly to the heir. (In the latter case, however, the heir becomes aware that
+they will receive an inheritance on a specific date and amount, which could be
+imprudent.)
+
+The backup transaction, once delivered to the heir, can — at a later date than
+the inheritance delivery time — be sent to the nodes via Electrum to receive the
+funds in the inheritance wallet.
+
+**Difficulties and risks of using only the backup transaction** (versus trusting
+the automation of Will‑Executor servers):
+
+1. Risk of the transaction being **invalidated** later if you accidentally spend
+ even one satoshi from one of the wallets you pre‑signed the legacy transaction
+ from.
+2. Difficulty delivering the signed transaction to the heir (the heir would learn
+ about the inheritance and its value).
+3. Each step must be handled by hand, with the risk of errors.
+
+If you activated *Backup Transactions* in the parameters, this is visible in the
+**[WILL]** screen with the status **NONE** in the Will‑Executor column:
+
+
+
+*Figure 5 — backup transaction shown with "NONE" will‑executor.*
+
+Then, by right‑clicking it and selecting **[Details]**, the following screen
+appears, where you can save your transaction to your preferred medium (USB flash
+drive, cloud, NAS, etc.):
+
+
+
+*Figure 6 — transaction details / save dialog.*
+
+---
+
+## Wallet security — saving your will
+
+To keep a copy of your will, simply save the wallet from Electrum
+(**File → Save Backup**).
+
+If, for example, your notebook is stolen or breaks down, just install Electrum on
+a new computer together with the BAL plugin and open the previously saved wallet.
+
+> **Remember** to save (and not lose) your wallet **password** on Electrum, or
+> you will no longer be able to access the inheritance data saved with the
+> wallet. If you restore your wallet from **SEED only**, you will regain access
+> to your bitcoin funds but **lose the BAL inheritance data** saved with the
+> wallet file.
+
+You can also **export the heir list** to keep a printable copy of your
+inheritance:
+
+
+
+*Figure 7 — exporting / printing the heir list.*
+
+---
+
+## Will‑Executor service list
+
+This window opens from the Electrum menu, **Tools → Will‑executor**, and shows
+the official list of will‑executor servers.
+
+If you want to make changes — such as adding an additional will‑executor server —
+you can enter it manually or import a list of will‑executor servers (found on the
+bitcointalk.org forum or on the official BAL website).
+
+**Commands in the window:**
+
+- **Ping:** checks which servers in the list are online — a **green dot** means
+ active.
+- **Import:** imports a will‑executor list other than the default.
+- **Export:** exports the list of will‑executor servers in your plugin (useful to
+ move it to another Electrum + BAL installation).
+- **Add:** adds a will‑executor server manually.
+
+### List columns
+
+1. **URL** — the URL address of the will‑executor.
+2. **Base Fee** — the commission/reward for the will‑executor. This reward lets
+ the will‑executor cover the cost of keeping the server online. The
+ will‑executor earns the base fee **only on the date of inheritance**, and only
+ if it is the **first** to send the transaction to the nodes — which sets in
+ motion a competition among will‑executors to earn the base fee. *(Example: I
+ set up an inheritance that will happen in 4 years; in that case the
+ will‑executor will only earn the fee in 4 years.)*
+3. **Info** — server description or website link.
+4. **Default Address** — the bitcoin wallet address where the base fee will be
+ sent.
+5. **S** — server status. A **green dot** = server online.
+
+**Right‑click** on a server line opens four sub‑commands:
+
+
+
+*Figure 8 — the will‑executor context menu.*
+
+1. **Select** — right‑click the server, add the green check mark on the left, and
+ this will‑executor will be used in your inheritance.
+2. **Edit** — edit the relevant column field.
+3. **Ping** — verify that the server is online.
+4. **Delete** — delete the server from the list.
+
+---
+
+## Privacy of (online) will‑executors
+
+Transactions sent to will‑executor servers (*pushed*) by the BAL plugin are
+stored on the servers. They are **not** publicly accessible (for privacy), but
+from your BAL plugin you can check at any time whether the transaction is
+properly stored on the servers: right‑click the inheritance transaction in the
+**WILL** tab and choose **Check**. The transaction will be tagged in the
+**Status** column as **Checked** if it is indeed online on the server.
+
+### WILL tab columns
+
+a. **Locktime** — the date of inheritance.
+b. **Txid** — identification of the bitcoin transaction.
+c. **Will‑Executor** — address of the will‑executor.
+d. **Status** — see the table below.
+
+---
+
+## Colour progression of transaction statuses
+
+Transactions on the **WILL** page are coloured to conveniently display their
+**status** of progress. Below are the colour progression states your legacy
+transactions can have in the WILL tab, on each will‑executor that is online.
+
+### Chromatic progression table
+
+| # | Status | Meaning | Colour | HEX |
+|---|--------|---------|--------|-----|
+| 1 | **New** | TX new inheritance | White (transparent) | `#FFFFFF` |
+| 2 | **Signed** | TX inheritance signed into the wallet | Azure | `#2BC8ED` |
+| 3 | **Pushed** | TX sent to will‑executor | Azure‑green | `#73F3C8` |
+| 4 | **Checked** | TX actually present in the will‑executor | Bright green | `#8AFA6C` |
+| 5 | **Confirmed** | TX confirmed in the blockchain | Gray | `#BFBFBF` |
+| 6 | **Pending** | TX awaiting confirmation on blockchain | Yellow | `#FFCE30` |
+| 7 | **Failed** | Communication failure with will‑executor | Red | `#E83845` |
+| 8 | **Invalidated** | UTXO input is no longer available | Orange | `#F87838` |
+| 9 | **Replaced** | A backdated‑locktime transaction spends the same input | Violet | `#FF97E9` |
+
+---
+
+## WILL tab — commands
+
+
+
+*Figure 9 — the WILL tab with its commands.*
+
+1. **Prepare** — prepares the inheritance and puts it on the list.
+2. **Sign** — sign your legacy transaction with your private key (using your
+ wallet password or hardware key).
+3. **Broadcast** — sends the inheritance transaction to the online Will‑Executor
+ servers on your *Will‑Executor Service List*.
+4. **Display** — brings up the *Will‑Details* window, where you can see the
+ transactions with all available data:
+ - Locktime (date of inheritance)
+ - Creation time
+ - Transaction fee (to the miners)
+ - Status (see table)
+ - Heirs
+ - Will‑executor (server address)
+ - Commission (base fee) — reward for the will‑executor
+
+
+
+*Figure 10 — the Will‑Details window (Display).*
+
+> **NB:** When you close Electrum, the plugin automatically proceeds to execute
+> **Prepare → Sign → Broadcast** (if they have not already been completed) to
+> ensure the inheritance is correctly executed.
+
+---
+
+## Using hardware keys
+
+**Ledger, BitBox2, etc.** — all hardware keys that are compatible with and
+recognised by Electrum are compatible with the BAL plugin.
+
+---
+
+## Insights (privacy)
+
+### Caution: consolidation of UTXOs
+
+When you send the entire contents of a wallet, you risk losing the privacy of
+your UTXOs. It may be a good rule of thumb to execute the inheritance leaving a
+small remainder to another wallet, to improve the privacy of the transaction —
+especially if there is only one heir.
+
+> **Example:** 99.7 % inheritance to the heir and 0.3 % to a random bitcoin
+> address (e.g. taken randomly from a block explorer).
+
+---
+
+## Wallet inheritance behaviour when the balance / UTXO changes
+
+If your wallet managed with the BAL plugin changes in balance — e.g. you send
+additional funds or spend some — the inheritance **must be updated**.
+
+The BAL plugin takes care, when closing Electrum, to check whether there has been
+any such change (balance or UTXO) and then **updates the inheritance
+automatically**.
+
+Thanks to this you can use an *inheritance‑ready* wallet on Electrum even for
+everyday Bitcoin transactions (possibly with a hardware key to sign), knowing
+that in case of death the entire contents of the wallet will be sent to your
+heirs.
+
+If you use your **read‑only** wallet on devices other than your Electrum (using
+the public key `Zpub`/`Xpub`, e.g. to monitor funds remotely), any funds sent
+directly into the wallet **will not** be added to the inheritance already set up.
+To work around this, open your wallet on Electrum so the plugin can update the
+inheritance UTXOs and re‑send them to the will‑executors, updated with the new
+value.
+
+> ⚠️ **WARNING:** If you use the same **SEED** on multiple devices (a behaviour
+> always strongly discouraged), spending even one transaction of even one satoshi
+> **invalidates** the inheritance, because it changes the wallet's UTXO structure
+> and therefore the nodes discard the inheritance transaction.
+
+---
+
+About installing a will‑executor server or collaboration, send your request to:
+**info@bitcoin-after.life**
+
+---
+
+Signed,
Svātantrya