Replace draft with full manual (docs-as-code, colors, logo, versioning)

docs/user-guide/backup-transaction.md

@@ -0,0 +1,26 @@
+# Offline backup transaction
+
+Beyond the Will-Executor network, the plugin can save the signed inheritance transaction to a **file you keep yourself**. It is the fallback for the (unlikely) scenario where every Will-Executor holding your will has ceased to operate.
+
+![Backup Transaction option in plugin settings](../img/settings-backup-transaction.png){ .screenshot }
+*Enable it in the plugin parameters.*
+
+## How it works
+
+With the option enabled, the signed transaction is also written to a file you can store on a USB stick, a NAS, or wherever you prefer.
+
+![Saving the backup transaction](../img/backup-transaction-save.png){ .screenshot }
+*Save the transaction to your medium of choice.*
+
+You can then deliver it through a notary, a trusted person, or directly to the heir. On or after the delivery date, whoever holds it can broadcast it through Electrum and the funds move.
+
+## The trade-offs, honestly
+
+Relying on the offline backup alone has real drawbacks:
+
+1. **It goes stale.** Any change to the wallet — a satoshi spent, a new heir, a different date — invalidates the saved file. You have to regenerate and redistribute it every time.
+2. **It leaks information.** An heir who holds the file knows the exact date and amount of the inheritance, years in advance. That may not be prudent.
+3. **Every step is manual**, with the corresponding risk of error.
+
+!!! tip "Use it as a second layer, not the main plan"
+    The recommended setup is: select **as many Will-Executors as possible** (only one has to survive to the delivery date), and keep the offline backup as an additional safety net.

docs/user-guide/check-alive.md

@@ -0,0 +1,31 @@
+# Check Alive
+
+**Check Alive** is the plugin's "are you still around?" mechanism. It is available in **advanced mode**.
+
+![Advanced mode toggle](../img/settings-advanced-mode.png){ .screenshot }
+*Advanced mode exposes Check Alive and the other fine-grained parameters.*
+
+## What it does
+
+Check Alive defines a period of inactivity. When you open Electrum and more than that period has passed since the last postponement, the plugin asks whether you want to **push your delivery date further out** — because you are evidently still alive.
+
+![Check Alive parameter](../img/settings-check-alive.png){ .screenshot }
+*The threshold can be expressed as a relative period or an absolute date.*
+
+## Example
+
+You set a delivery date **2 years** out, with Check Alive at **6 months**.
+
+| What you do | What happens |
+|---|---|
+| You open Electrum after 3 months | Nothing — you are inside the Check Alive window |
+| You open Electrum after 7 months | The plugin points out that your delivery date is now only 1 year and 5 months away, and offers to postpone it |
+| You stop opening Electrum altogether | Nothing postpones the will. On the delivery date, the Will-Executors broadcast it |
+
+As long as you keep using Electrum within the Check Alive window and accept the prompts, your will is never executed.
+
+!!! tip "Disabling it for a quick test"
+    Setting Check Alive to a **date in the past** effectively switches it off. This is what you want when testing the plugin with a delivery time only a few hours away, so the prompt doesn't get in the way.
+
+!!! warning "Postponing is not free"
+    Accepting a postponement may require invalidating the previously committed transaction on-chain, which costs a miner fee. See [Postponing vs anticipating](updating.md#postponing-vs-anticipating).

docs/user-guide/compatibility.md

@@ -0,0 +1,34 @@
+# Compatibility
+
+## Wallet types
+
+| Wallet type | Status |
+|---|---|
+| Standard Electrum wallet (seed-based, single-signature) | **Supported** |
+| Hardware wallets supported by Electrum | **Supported** — see [Hardware wallets](hardware-wallets.md) |
+| Multisig wallets | **Not yet supported** — planned for a future release |
+| Electrum TrustedCoin (2FA) wallets | **Unknown / unsupported** — not yet determined |
+
+!!! danger "Do not rely on BAL with multisig or 2FA wallets"
+    If you use a multisig or TrustedCoin (2FA) wallet, do not use BAL for inheritance until compatibility is confirmed.
+
+## Electrum versions
+
+The plugin follows Electrum closely; each release states the Electrum version it was tested against.
+
+| Plugin release | Tested with |
+|---|---|
+| v{{ bal.plugin_version }} | Electrum {{ bal.electrum_tested }} (manual verified on {{ bal.electrum_latest }}) |
+| v0.2.3 | Electrum 4.7.0 |
+| v0.2.0 | Electrum 4.6.2 — introduced the will setup wizard and the remote Will-Executor list |
+| v0.1.0 | Electrum 4.5.8 — first release |
+
+Always check the [releases page](https://bitcoin-after.life/gitea/bitcoinafterlife/bal-electrum-plugin/releases) for the current pairing before upgrading Electrum.
+
+## Networks
+
+The protocol and the servers support **mainnet**, **testnet**, **testnet4**, **signet** and **regtest**. The [WeList](../will-executors/welist.md) lets you filter Will-Executors by network — useful when you want to run a full test before committing real funds.
+
+## Unconfirmed incoming transactions
+
+You can set up an inheritance on a wallet with an **incoming transaction still in the mempool**. It does not need to be confirmed — being visible in the mempool is enough. The plugin handles this case automatically.

docs/user-guide/delivery-time.md

@@ -0,0 +1,40 @@
+# Delivery time
+
+The **delivery time** (technically the transaction's `nLockTime`) is the date on which the Will-Executors broadcast your inheritance to the Bitcoin network.
+
+## How to express it
+
+| Form | Example | Meaning |
+|---|---|---|
+| **Date** | 1 December 2027 | A precise calendar date, pickable from the system calendar |
+| **Raw / relative** | `1y` | One year from today |
+| | `1d` | Tomorrow |
+
+## Timing tolerance
+
+The plugin converts your date into an estimated block height, so execution is not accurate to the minute:
+
+- With **relative** values, expect a tolerance of a few hours.
+- Bitcoin nodes accept a time-locked transaction based on the **median time past** of the last 11 blocks, so in practice the inheritance is executed on average about **one hour after** the time you set.
+
+For an inheritance measured in years, this is irrelevant. It only matters if you are running a short test.
+
+!!! info "Why nobody can execute it early"
+    A transaction with a future `nLockTime` is **rejected by the Bitcoin mempool** until that time is reached. This is a consensus rule, not a courtesy: even a malicious Will-Executor cannot make the inheritance happen sooner.
+
+## No expiry, no upper limit in practice
+
+Absolute time-locks are not subject to the ~15 month ceiling that affects *relative* time-locks (BIP 68). You can set a delivery date decades ahead.
+
+!!! tip "Even so, renew every 2–3 years"
+    A rolling deadline — "always five years from today", refreshed periodically — is the recommended way to use BAL:
+
+    - the network grows, so renewing lets you include **newer Will-Executors** and drop ones that have shut down;
+    - it keeps you far from the delivery date at all times;
+    - it picks up future protocol improvements.
+
+    See [Keeping the will up to date](updating.md).
+
+## Changing the date later
+
+Bringing the date **forward** and pushing it **back** are not symmetric operations — the difference is explained in [Keeping the will up to date](updating.md#postponing-vs-anticipating).

docs/user-guide/hardware-wallets.md

@@ -0,0 +1,17 @@
+# Hardware wallets
+
+BAL works with **any hardware wallet supported by Electrum** — Ledger, Trezor, Coldcard, BitBox02, Jade, KeepKey and others.
+
+![Confirming on the hardware wallet](../img/hardware-wallet-signing.png){ .screenshot }
+*The plugin builds the transaction; your device signs it.*
+
+The division of labour is the same as for a normal Electrum transaction:
+
+- the **plugin** builds the inheritance transaction,
+- **Electrum** submits it for signature,
+- **your device** signs — with your physical confirmation.
+
+The plugin never has access to your keys and never signs on your behalf.
+
+!!! tip "Cold signing setup"
+    For maximum security, use a dedicated computer for signing. Note that with BAL you will need to sign more than once over time: every refresh of the will requires a new signature — see [Keeping the will up to date](updating.md).

docs/user-guide/heirs.md

@@ -0,0 +1,44 @@
+# Heirs and shares
+
+The **HEIRS** tab is where you define who receives your bitcoin.
+
+![HEIRS tab](../img/heirs-tab.png){ .screenshot }
+*Two heirs configured, with their shares.*
+
+## Adding an heir
+
+![New heir dialog](../img/heirs-new-heir.png){ .screenshot }
+*Name, destination address, and share.*
+
+| Field | Meaning |
+|---|---|
+| **Name** | A label for the heir, with any details you find useful. Local only — it is never published on-chain. |
+| **Address** | The Bitcoin address that will receive the inheritance. |
+| **Amount** | The share, expressed either as a **percentage** of the wallet or as a **fixed amount**. |
+
+You can add many heirs — ten or more.
+
+!!! warning "Check the address twice"
+    The inheritance is sent to exactly the address you type, potentially years from now, with nobody available to correct a mistake. Prefer copy-paste over typing, and ask your heir for a fresh address from a wallet they actually control.
+
+## The wallet is always emptied to 100%
+
+The plugin makes sure that **all** the value in the wallet reaches the heirs — never a leftover balance stuck behind.
+
+| You set | The plugin sends |
+|---|---|
+| Wallet of 3 BTC: 1 BTC to Jonny, 10% to Andrea | 1 BTC to Jonny, **all the rest** (2 BTC) to Andrea |
+| 5% to Jonny, 80% to Andrea | Recalculated proportionally: **5.9%** to Jonny, **94.1%** to Andrea |
+| Wallet of 10 BTC: exactly 4 BTC to Jonny, exactly 2 BTC to Andrea | The remaining 4 BTC are redistributed — to keep the amounts exact, add a **third heir** (for example an address of your own) for those 4 BTC |
+
+The rule to remember: **if your shares don't add up to 100%, the plugin scales them until they do.** If you want a specific portion to go somewhere else, name that destination explicitly as an additional heir.
+
+!!! tip "Sending part of the wallet to yourself"
+    Adding one of your own addresses as an heir is a legitimate pattern. It is how you keep amounts exact, and it also improves the privacy of the transaction, since the destinations become harder to interpret.
+
+## One delivery date per wallet
+
+In the current version the delivery date is **unique per wallet**. If you need different dates for different heirs — for example two children reaching 18 in different years — prepare **one wallet per date**. Electrum makes creating and managing multiple wallets straightforward.
+
+!!! info "Planned for BAL 2.0"
+    Staggered inheritance — distributing gradually over time, for example 10% per year — is in development for version 2 of the protocol.

docs/user-guide/updating.md

@@ -0,0 +1,46 @@
+# Keeping the will up to date
+
+An inheritance transaction spends specific UTXOs. If those UTXOs change, the transaction the Will-Executors are holding becomes invalid — so the will has to be rebuilt.
+
+The plugin handles this for you: **every time you close Electrum it checks your balance and UTXO set**, and if something changed it asks you to refresh the will. You confirm the signature; it never signs on your behalf.
+
+This is what makes it practical to use an inheritance-ready wallet for everyday transactions.
+
+## What triggers a refresh
+
+- You receive funds.
+- You spend funds.
+- You add, remove, or edit an heir.
+- You change the delivery date.
+
+## Postponing vs anticipating
+
+The two directions are not symmetric, and the difference has a real cost:
+
+=== "Anticipating (earlier date)"
+
+    Bringing the delivery date **forward** is cheap. The plugin signs a new inheritance with an earlier locktime and sends it to the Will-Executors. Because it becomes valid sooner, it supersedes the previously distributed transaction — **no on-chain fee**.
+
+    This is also how balance and heir changes are handled: the will is anticipated by one day and redistributed, without invalidating the old one on-chain.
+
+=== "Postponing (later date)"
+
+    Pushing the delivery date **back** requires invalidating the committed coins **on-chain first**. Otherwise a Will-Executor still holding the old, earlier-locktime transaction could broadcast it and execute the inheritance too early.
+
+    That invalidation is a real Bitcoin transaction: you sign it and it costs a **miner fee**.
+
+!!! tip
+    If you expect to adjust the date often, plan for it: a rolling deadline that you re-anticipate is cheaper than repeatedly postponing.
+
+## Watch-only copies on other devices
+
+If you monitor the same wallet from another device using its public key (Zpub/Xpub), funds arriving there are **not** added to the inheritance automatically. Open the wallet in Electrum with the plugin so it can pick up the new UTXOs and re-send the updated will to the Will-Executors.
+
+!!! danger "The same seed on multiple devices invalidates the inheritance"
+    Using the same seed on more than one device is strongly discouraged in general. With BAL it has a specific consequence: spending even a single satoshi from the other device changes the wallet's UTXO structure, and the nodes will **discard the inheritance transaction** when the Will-Executors try to broadcast it.
+
+## How often to renew
+
+Renewing is not strictly required, but it is recommended roughly **every 2–3 years**. A practical approach is a rolling deadline — "always five years from today" — refreshed at regular intervals.
+
+Renewing serves two purposes: it lets you include Will-Executors that joined the network in the meantime (and drop the ones that shut down), and it picks up future protocol changes.

docs/user-guide/wallet-backup.md

@@ -0,0 +1,36 @@
+# Backing up wallet and will
+
+## Where your will actually lives
+
+Your heirs, dates, and inheritance transactions are stored **inside the Electrum wallet file** — not in your seed.
+
+!!! danger "Restoring from seed does not restore your will"
+    If you recreate the wallet from its seed phrase you get your **bitcoin** back, but the BAL inheritance configuration is **gone**. Only the wallet file carries it.
+
+## How to back it up
+
+Use Electrum's own command: **File → Save backup**.
+
+If your computer is stolen or fails, install Electrum plus the BAL plugin on a new machine and open the saved wallet file — your will is there, intact.
+
+!!! warning "Keep the wallet password"
+    Without it you cannot open the wallet file, and therefore cannot reach the inheritance data stored inside it.
+
+## Export the heirs list
+
+You can export the list of heirs to keep a readable, printable copy of your arrangement.
+
+![Exporting the heirs list](../img/heirs-export.png){ .screenshot }
+*A printable record of who inherits what.*
+
+!!! tip "Store it thoughtfully"
+    That export tells anyone who reads it who your heirs are and how much they receive. Treat it with the same care as any other sensitive document — and consider whether the heirs themselves should know in advance.
+
+## A sensible backup routine
+
+| What | Where | When |
+|---|---|---|
+| Wallet file (contains the will) | Two separate physical locations | After every meaningful change to the will |
+| Wallet password | Password manager or a sealed physical note | Once, and whenever you change it |
+| Seed phrase | Offline, separate from the above | Once |
+| [Offline backup transaction](backup-transaction.md) (optional) | USB / notary / trusted person | Every time the will is refreshed |

docs/user-guide/wallet-recovery.md

@@ -0,0 +1,21 @@
+# Using BAL as a wallet recovery net
+
+Inheritance is not the only use for a time-locked transaction. The same mechanism gives you a **decentralized safety net against losing your seed**.
+
+## The idea
+
+Set up an inheritance whose beneficiary is a **second wallet you control** — for example a mobile wallet on your phone.
+
+If you lose access to the original wallet and therefore stop opening Electrum, the Will-Executors broadcast the transaction on the delivery date and the funds arrive in your backup wallet. If you keep access, you simply keep postponing the date and nothing ever happens.
+
+## What you need
+
+- A **second wallet already set up**, whose receiving address you know and whose keys you can actually access.
+- The BAL plugin configured on the wallet you want to protect, with that address as the beneficiary.
+- A delivery date you are comfortable with, and the discipline to keep it refreshed — see [Keeping the will up to date](updating.md).
+
+!!! warning "The backup wallet must be genuinely independent"
+    A recovery destination whose keys live on the same device, or are derived from the same seed, protects you from nothing. Use a different device and a different seed, stored separately.
+
+!!! tip "It combines with inheritance"
+    Nothing stops you from listing both a recovery address of your own and your heirs. Remember that the plugin always distributes 100% of the wallet — see [Heirs and shares](heirs.md#the-wallet-is-always-emptied-to-100).

docs/user-guide/will-tab.md

@@ -0,0 +1,57 @@
+# The WILL tab
+
+The **WILL** tab is the technical view of your inheritance: one row per inheritance transaction, per Will-Executor.
+
+![WILL tab](../img/will-tab.png){ .screenshot }
+*Each row is a signed inheritance transaction held by one Will-Executor.*
+
+## Columns
+
+| Column | Meaning |
+|---|---|
+| **Locktime** | The delivery date of the inheritance |
+| **Txid** | Identifier of the Bitcoin transaction |
+| **Will-Executor** | Which server holds this copy |
+| **Server** | Whether that server actually has it (see below) |
+| **Status** | Progress of the transaction itself |
+
+## The Server column
+
+The Server column tells you, independently of the row colour, whether each inheritance transaction is really stored on its Will-Executor.
+
+![Server column](../img/will-server-column.png){ .screenshot }
+*The Server column reports storage state per Will-Executor.*
+
+| Label | Meaning |
+|---|---|
+| **Confirmed on server** | The Will-Executor confirmed it has stored the transaction |
+| **Sent (not checked)** | Pushed to the Will-Executor, not re-checked since |
+| **Send failed / Not on server** | The push failed, or the server no longer has it |
+| **Signed (not sent)** | Signed locally, not sent to any Will-Executor |
+| **Not sent** | Not signed or sent yet |
+
+!!! tip "Check your wills periodically"
+    Right-click a transaction and use the check action to re-query the servers. A row that drifts to *Not on server* is a signal that this Will-Executor is no longer reliable — consider [renewing your will](updating.md) with a different selection.
+
+## Actions
+
+![Right-click menu on a will transaction](../img/will-context-menu.png){ .screenshot }
+*Right-click a row to act on it.*
+
+| Action | What it does |
+|---|---|
+| **Prepare** | Builds the inheritance transaction and adds it to the list |
+| **Sign** | Signs it — Electrum asks for your password or hardware wallet confirmation |
+| **Broadcast / push** | Sends the signed transaction to the selected Will-Executors |
+| **Check** | Asks each server whether it still holds its copy, and updates the Server column |
+| **Display / Details** | Opens the Will-Details window |
+
+!!! note "The plugin finishes the job on close"
+    When you close Electrum, the plugin completes any of prepare / sign / broadcast that is still pending — asking you to confirm the signature. It never signs on your behalf.
+
+## Will details
+
+![Will-Details window](../img/will-details.png){ .screenshot }
+*Everything about one inheritance transaction in one window.*
+
+The details window shows the locktime (delivery date), the creation time, the miner fee, the current status, the list of heirs, the Will-Executor address, and the Will-Executor's fee.