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

.gitea/workflows/deploy.yml

@@ -0,0 +1,24 @@
+name: Build and deploy docs
+
+on:
+  push:
+    branches: [main]
+
+jobs:
+  deploy:
+    runs-on: docs-runner        # must match the label of your registered act_runner
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Install dependencies
+        run: pip install --break-system-packages mkdocs-material mkdocs-macros-plugin pyyaml
+
+      - name: Generate placeholders for missing screenshots
+        run: python3 tools/make_placeholders.py
+
+      - name: Build site (strict — fails on broken links)
+        run: mkdocs build --strict
+
+      - name: Publish
+        run: rsync -a --delete site/ /var/www/bal-docs/

.gitignore

@@ -0,0 +1,4 @@
+site/
+__pycache__/
+*.pyc
+.venv/

README.md

@@ -0,0 +1,100 @@
+# Bitcoin After Life — Manual
+
+Docs-as-code source for the BAL documentation, built with [MkDocs Material](https://squidfunk.github.io/mkdocs-material/).
+Published at <https://bitcoin-after.life/docs/>.
+
+## Quick start
+
+**Windows:** double-click `serve.bat`.
+**Linux / macOS:** run `./serve.sh`.
+
+Either one installs the dependencies and opens a live preview at
+<http://127.0.0.1:8000>, with working search and auto-reload on save.
+
+Manually:
+
+```bash
+pip install mkdocs-material mkdocs-macros-plugin 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/
+```
+
+> Opening the built HTML files directly from disk (`file://`) works for reading,
+> but **search will not run** — browsers block the index fetch. Use the server.
+
+## Layout
+
+```
+docs/                 published pages (Markdown)
+docs/img/             screenshots — filenames fixed by screenshots.yml
+docs/stylesheets/     screenshot framing CSS
+screenshots.yml       manifest of every image the manual expects
+tools/                helper scripts
+internal/             NOT published — drafts and working notes
+.gitea/workflows/     CI: build + deploy on push to main
+```
+
+## Versions in one place
+
+Plugin and Electrum versions, and the WeList fee, are **not** hardcoded in the pages.
+They live in `mkdocs.yml` under `extra.bal:` and are referenced as `{{ bal.plugin_version }}`.
+Change the value once and every page updates on the next build.
+
+| Variable | Meaning |
+|---|---|
+| `plugin_version` | Latest plugin release |
+| `electrum_tested` | Electrum version that release was tested against |
+| `electrum_latest` | Latest stable Electrum the manual assumes |
+| `welist_fee_sats` / `welist_period_days` | WeList listing terms |
+| `last_reviewed` | Bump after a full editorial pass |
+
+A typo in a variable name **fails the build** (`on_error_fail: true`), so a broken
+reference can never reach the published site.
+
+## Brand assets
+
+`docs/assets/logo.svg` and `docs/assets/favicon.png` are **placeholders**.
+See `internal/brand-assets.md` for the official sources and how to swap them in.
+
+## Updating the documentation
+
+**Text.** Edit the `.md` files in `docs/`, commit, push. Pages have an edit link
+pointing back at Gitea, so small fixes can be made from the web editor.
+
+**Screenshots.** Save the new image over `docs/img/<name>.png` using the filename in
+`screenshots.yml`. Nothing else to change. See `internal/screenshot-checklist.md`
+for capture rules and data-hygiene warnings.
+
+**Adding a page.** Create the `.md` file under `docs/`, then add it to `nav:` in
+`mkdocs.yml`. `mkdocs build --strict` fails on broken internal links, so a typo in a
+cross-reference is caught before deploy.
+
+## Italian translation
+
+The configuration is prepared but not enabled. To turn it on:
+
+```bash
+pip install mkdocs-static-i18n
+```
+
+then uncomment the `plugins:` block in `mkdocs.yml` and add `page.it.md` files next to
+the English ones. Untranslated pages fall back to English automatically, so you can
+translate progressively.
+
+## Deployment
+
+`.gitea/workflows/deploy.yml` builds and publishes to `/var/www/bal-docs/` on every push
+to `main`. It requires Gitea Actions enabled and a registered runner labelled
+`docs-runner`. Until that is set up, deploy manually:
+
+```bash
+mkdocs build
+rsync -a --delete site/ /var/www/bal-docs/
+```
+
+## Status
+
+Based on the website, the WeList, the Gitea repositories and the BAL MANUAL revB PDF
+(July 2026). Open questions and points needing developer validation are tracked in
+`internal/source-notes.md`.

docs/faq.md

@@ -0,0 +1,96 @@
+# FAQ
+
+## The project
+
+??? question "What is the Bitcoin After Life Protocol for?"
+    It manages the **inheritance of bitcoin** held in a seed-based wallet, and can also serve as an **emergency backup** if you lose your seed. It uses time-locked transactions held by Will-Executor servers, which broadcast them to the network on the delivery date you set.
+
+??? question "Who created it, and when?"
+    It is open-source software, belonging to everyone, like Bitcoin itself. The first public post about Bitcoin After Life appeared on BitcoinTalk on **31 October 2024**, signed *Svātantrya*. Anyone can contribute.
+
+??? question "Why a plugin for Electrum rather than a dedicated wallet?"
+    Because Electrum is **heavily tested** and considered the gold standard among Bitcoin wallets. Building a new wallet — or forking one — would put funds at unnecessary risk. The plugin does not sign transactions itself: that is entirely Electrum's job.
+
+??? question "Is BAL 2.0 planned?"
+    Yes. The main new feature will be **staggered inheritance**: gradual distributions over time (for example 10% per year) instead of a single lump-sum transfer.
+
+## Using the plugin
+
+??? question "How much does it cost?"
+    Two fees, both paid **exclusively in bitcoin** — no subscriptions, no cards:
+
+    - **Miner fee**, chosen by you at signing time. Set it generously so the transaction confirms even under congestion.
+    - **Will-Executor fee**, deducted from the inheritance at execution.
+
+??? question "Is it hard to use?"
+    The plugin includes a **guided wizard** and was designed for ordinary users, not only technical ones. See [Create your first will](getting-started/quick-start.md).
+
+??? question "Can I use a hardware wallet?"
+    Yes — any hardware wallet supported by Electrum (Ledger, Trezor, Coldcard, BitBox02, Jade, KeepKey and others). See [Hardware wallets](user-guide/hardware-wallets.md).
+
+??? question "Is it compatible with every Electrum wallet type?"
+    Standard seed-based single-signature wallets and hardware wallets: yes. **Multisig is not yet supported**, and TrustedCoin (2FA) compatibility is **unknown**. See [Compatibility](user-guide/compatibility.md).
+
+??? question "What if my balance changes after setting up the inheritance?"
+    The plugin monitors your UTXOs every time you close Electrum and prompts you to update the will. This prevents both new funds being excluded and the old transaction being rejected because its inputs were spent. See [Keeping the will up to date](user-guide/updating.md).
+
+??? question "What if an incoming transaction is still unconfirmed during setup?"
+    Not a problem. It only needs to be **visible in the mempool** — the plugin handles this case automatically.
+
+??? question "Can I use the plugin to back up my wallet?"
+    Yes. Set a second wallet you control as the beneficiary. If you lose access to the original and stop opening Electrum, the funds are sent automatically to the backup address on the delivery date. See [Wallet recovery use case](user-guide/wallet-recovery.md).
+
+??? question "Do I have to do anything after creating the will, or is it set-and-forget?"
+    Not strictly required, but renewing every **2–3 years** is recommended. A rolling deadline — "always five years from today" — refreshed periodically keeps newer Will-Executors in your selection and picks up protocol improvements.
+
+??? question "What is Check Alive?"
+    A period of inactivity after which the plugin asks whether to postpone your delivery date. Available in **advanced mode** — see [Check Alive](user-guide/check-alive.md).
+
+## Will-Executors
+
+??? question "Does the plugin use one Will-Executor or several?"
+    Several — as many as possible. It downloads the full [WeList](will-executors/welist.md) by default; you can also add servers manually or use alternative lists. For the inheritance to succeed, **only one** of the selected Will-Executors has to still be operating on the delivery date.
+
+??? question "Who receives the fee if several Will-Executors broadcast the same inheritance?"
+    The plugin creates a **separate transaction for each Will-Executor**, each paying that specific server. Only one can confirm: the fee goes to whoever broadcast it successfully. A competitive mechanism that rewards servers that are actually operating.
+
+??? question "Why aren't the fees redistributed among all Will-Executors?"
+    Three practical reasons: it would require including every active server's address in every inheritance transaction, it would increase transaction size and cost, and it would reward servers that do nothing.
+
+    But the decisive reason is different: **anyone who wants to share proceeds can already do so**, without changing the protocol — see the next question. Writing redistribution into the protocol would impose a policy on everyone; leaving it out keeps it a voluntary choice.
+
+??? question "Does a Will-Executor have to be a single person or company?"
+    No. The protocol sees a service plus a Bitcoin address. Several operators can form a consortium, present themselves as one Will-Executor, and use a shared **multisig** address for fees, splitting them by whatever agreement they prefer. The plugin knows nothing about it — it pays an address, as always.
+
+    Two caveats: for a user's redundancy the consortium counts as **one** Will-Executor, and the internal split is outside the protocol, neither arbitrated nor guaranteed by BAL.
+
+??? question "Can a newly joined Will-Executor handle wills created before it existed?"
+    No. Transactions are pre-signed and already name the Will-Executor to be paid; back-dating is neither possible nor appropriate. A new server receives wills created from its arrival onwards.
+
+??? question "Do Will-Executors talk to each other?"
+    No. Each one is completely independent — no coordination, no shared state. This removes central points of coordination and reduces the attack surface.
+
+??? question "Why not use miners to broadcast inheritance transactions?"
+    Technical reasons: the mempool rejects transactions with a future locktime, and a signed transaction cannot be modified to add an "anyonecanspend" output without invalidating it.
+
+    Privacy reasons: Will-Executors are **chosen by the user**. Handing transactions to a network of miners nobody selected would expose wallet data to unwanted observers. A network of independent Will-Executors whose only incentive is broadcasting is also more resistant to regulation and censorship than dependence on large pools.
+
+??? question "Can Will-Executors see the contents of my wallet?"
+    The servers you select receive pre-signed transactions that reflect your wallet's state. This is exactly why their selection stays in your hands, and why privacy — together with reliability — is what Will-Executors really compete on.
+
+??? question "What if every Will-Executor I selected shuts down before the delivery date?"
+    This is what the [offline backup transaction](user-guide/backup-transaction.md) is for: saved to physical media and handed to your heirs, who can broadcast it themselves. It must be kept up to date as your wallet changes — which is why the better strategy remains selecting as many Will-Executors as possible.
+
+??? question "Who decides the Will-Executor fees?"
+    Each server sets its own; the market sets the price. When creating your will you can exclude servers you find too expensive — or suspiciously cheap, since an unsustainable price suggests a service unlikely to last for years.
+
+??? question "Are the miner fees enough if the network is congested?"
+    The plugin sets a deliberately generous default fee to ensure confirmation even under congestion. A Will-Executor can additionally use **CPFP (Child Pays For Parent)** to accelerate confirmation.
+
+## Running a server
+
+??? question "Do I need a powerful machine to run a Will-Executor?"
+    No — recent versions run on even a small VPS, and at least one active Will-Executor runs on Umbrel OS. What matters is uptime over years, not raw power. See [Running a Will-Executor](will-executors/running-a-server.md).
+
+??? question "Can I add my server to the WeList?"
+    Yes. The WeList is open to everyone; listing costs approximately **{{ bal.welist_fee_sats }} satoshis per year** to cover the directory's running costs. Once listed, your server is visible to all BAL users directly inside the plugin. Listing is optional — users can also add servers manually.

docs/getting-started/installation.md

@@ -0,0 +1,53 @@
+# Installation
+
+## Requirements
+
+| | |
+|---|---|
+| **Electrum** | {{ bal.electrum_latest }} (last stable release tested) |
+| **Platform** | Desktop — Linux, Windows, macOS |
+| **License** | MIT |
+| **Wallet type** | Standard seed-based single-signature, or a [hardware wallet](../user-guide/hardware-wallets.md). See [Compatibility](../user-guide/compatibility.md). |
+
+Install Electrum first, from the official site [electrum.org](https://electrum.org), and verify its signature as you normally would.
+
+## 1. Download the plugin
+
+Get the latest release from the [plugin releases page](https://bitcoin-after.life/gitea/bitcoinafterlife/bal-electrum-plugin/releases).
+
+!!! tip "Verify the archive"
+    Check that the zip's SHA-256 matches the value printed by `build_zip.py`. If you built the zip yourself from source, compare it against the published release.
+
+## 2. Install it in Electrum
+
+![Electrum Tools menu with Plugins](../img/install-electrum-plugins-menu.png){ .screenshot }
+*Electrum → Tools → Plugins.*
+
+1. Open Electrum and go to **Tools → Plugins**.
+2. Choose **install from file** and select the BAL zip.
+
+![Install from file dialog](../img/install-from-file.png){ .screenshot }
+*Selecting the plugin archive.*
+
+## 3. Enable and restart
+
+Tick **Bitcoin After Life** in the plugin list, then restart Electrum.
+
+![Plugin list with Bitcoin After Life enabled](../img/install-plugin-enabled.png){ .screenshot }
+*The plugin enabled and ready.*
+
+## 4. Check that it loaded
+
+After restarting you will see two new tabs in the Electrum window: **HEIRS** and **WILL**.
+
+![Electrum with the HEIRS and WILL tabs](../img/overview-tabs.png){ .screenshot }
+*HEIRS is where you define who inherits; WILL shows the technical state of your inheritance transactions.*
+
+Next: [create your first will](quick-start.md).
+
+## Platform-specific notes
+
+Step-by-step installation notes for specific platforms are kept in their own repositories:
+
+- [Windows installation](https://bitcoin-after.life/gitea/bitcoinafterlife/bal_plugin_windows_installation)
+- [Linux installation](https://bitcoin-after.life/gitea/bitcoinafterlife/bal_plugin_linux_installation)

docs/getting-started/quick-start.md

@@ -0,0 +1,54 @@
+# Create your first will
+
+The plugin ships with a **guided wizard** that walks you through the whole setup. You only need two decisions: *who inherits* and *when*.
+
+!!! tip "Do a dry run first"
+    Set a delivery time a few hours away on a test wallet, and watch the transaction move through the states in the [WILL tab](../user-guide/will-tab.md). On such a short horizon, remember to disable or back-date [Check Alive](../user-guide/check-alive.md) so it doesn't interfere.
+
+## Step 1 — Start the wizard
+
+![Wizard welcome screen](../img/wizard-01-start.png){ .screenshot }
+*The wizard walks through heirs, date, and Will-Executors in order.*
+
+## Step 2 — Add your heirs
+
+Enter the Bitcoin address of each heir and the share of the wallet they receive — as a percentage or as a fixed amount.
+
+![Wizard: adding an heir](../img/wizard-02-heirs.png){ .screenshot }
+*One row per heir. You can add as many as you need.*
+
+The plugin always distributes **100%** of the wallet. If your shares don't add up, it recalculates them proportionally — see [Heirs and shares](../user-guide/heirs.md#the-wallet-is-always-emptied-to-100).
+
+## Step 3 — Choose the delivery time
+
+This is the date on which the Will-Executors broadcast the inheritance to the Bitcoin network.
+
+![Wizard: delivery date](../img/wizard-03-delivery-time.png){ .screenshot }
+*You can pick a date from the calendar or express it as a relative delay.*
+
+See [Delivery time](../user-guide/delivery-time.md) for how relative values and execution tolerance work.
+
+## Step 4 — Select the Will-Executors
+
+The plugin downloads the [WeList](../will-executors/welist.md) directory and shows the available servers with their fees.
+
+![Wizard: selecting Will-Executors](../img/wizard-04-willexecutors.png){ .screenshot }
+*Select as many as you can: one transaction is created per Will-Executor.*
+
+!!! info "Pick many, not few"
+    Each selected Will-Executor gets its own copy of the inheritance, with its own fee output. For the inheritance to succeed, **only one of them** has to still be operating on the delivery date. More servers means more redundancy.
+
+## Step 5 — Review and sign
+
+![Wizard: final summary](../img/wizard-05-summary.png){ .screenshot }
+*Review everything before signing.*
+
+Electrum then asks for your wallet password — or confirmation on your hardware wallet — and signs the transactions. The plugin never signs for you.
+
+Once signed, the wills are sent to the selected Will-Executors and appear in the [WILL tab](../user-guide/will-tab.md), where you can verify that each server has actually stored its copy.
+
+## What happens from now on
+
+- Keep using Electrum normally. The plugin watches your balance and asks you to refresh the will when it changes — see [Keeping the will up to date](../user-guide/updating.md).
+- If you enabled [Check Alive](../user-guide/check-alive.md) (advanced mode), opening your wallet after the threshold prompts you to postpone the delivery date.
+- If you stop opening Electrum, the Will-Executors broadcast the inheritance on the date you set.

docs/index.md

@@ -0,0 +1,48 @@
+<div class="bal-hero">
+  <img class="logo-light" src="assets/logo-mark-black.svg" alt="Bitcoin After Life">
+  <img class="logo-dark"  src="assets/logo-mark-white.svg" alt="Bitcoin After Life">
+  <span class="name">Bitcoin After Life</span>
+  <span class="tagline">BAL Protocol — decentralized Bitcoin inheritance</span>
+</div>
+
+# Bitcoin After Life
+
+**Bitcoin After Life (BAL)** is an open-source plugin for [Electrum](https://electrum.org) that makes **decentralized Bitcoin inheritance** possible: no notary, no lawyer, no custodian.
+
+You set your heirs and a delivery date. The plugin builds a time-locked transaction, Electrum signs it with your key, and a network of independent **Will-Executor** servers holds it and broadcasts it to the Bitcoin network on that date.
+
+!!! info "This manual covers"
+    Plugin **v{{ bal.plugin_version }}** on **Electrum {{ bal.electrum_latest }}**. Both the plugin and the protocol are under active development — check the [releases page](https://bitcoin-after.life/gitea/bitcoinafterlife/bal-electrum-plugin/releases) for the version you are running.
+
+## Core ideas in one minute
+
+- **Your keys never leave your device.** The plugin never signs on your behalf: it asks, you decide — password or hardware wallet.
+- **The transaction is pre-signed and time-locked.** Bitcoin nodes reject it until the delivery date arrives, so nobody can execute it early.
+- **Will-Executors cannot steal or alter anything.** They only store the signed transaction and broadcast it at the right time.
+- **Redundancy is the guarantee.** The plugin creates one transaction per selected Will-Executor. Only one of them has to still be alive on the delivery date.
+- **The incentive is on-chain.** Each transaction carries a fee for its Will-Executor, paid only when that server successfully broadcasts and the transaction confirms.
+
+## Where to start
+
+<div class="grid cards" markdown>
+
+- **New here?** → [Installation](getting-started/installation.md), then [create your first will](getting-started/quick-start.md).
+- **Want the details?** → [Heirs and shares](user-guide/heirs.md), [Delivery time](user-guide/delivery-time.md), [The WILL tab](user-guide/will-tab.md).
+- **Curious about the servers?** → [What Will-Executors are](will-executors/what-they-are.md).
+- **Want to run one?** → [Running a Will-Executor](will-executors/running-a-server.md).
+
+</div>
+
+!!! warning "Test before you trust it with real funds"
+    BAL builds **real** Bitcoin inheritance transactions with time-locks. Try it on **testnet**, or with a small-amount wallet, before setting up an inheritance that matters. You can always review the generated transactions before broadcasting.
+
+## Project links
+
+| Resource | Link |
+|---|---|
+| Website | [bitcoin-after.life](https://bitcoin-after.life) |
+| Plugin source & releases | [bal-electrum-plugin](https://bitcoin-after.life/gitea/bitcoinafterlife/bal-electrum-plugin) |
+| Will-Executor server source | [bal-server](https://bitcoin-after.life/gitea/bitcoinafterlife/bal-server) |
+| Public Will-Executor directory | [WeList](https://welist.bitcoin-after.life/) |
+| All repositories | [Gitea](https://bitcoin-after.life/gitea/bitcoinafterlife) |
+| Contact | [info@bitcoin-after.life](mailto:info@bitcoin-after.life) |

docs/protocol/how-it-works.md

@@ -0,0 +1,54 @@
+# How the protocol works
+
+A summary of the mechanism, for readers who want to understand what happens underneath the interface.
+
+## 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.
+
+BAL builds on exactly this. Your inheritance is an ordinary Bitcoin transaction, signed by you today, that the network will simply refuse to accept until the date you chose.
+
+Absolute time-locks are not subject to the ceiling that limits *relative* time-locks (BIP 68, capped at 65,535 units). In practice you can set a date decades away.
+
+## Why someone has to broadcast it
+
+Because the mempool rejects it, a time-locked transaction **cannot simply be left with the network** to be picked up later. Someone has to hold it and submit it when the time comes. That is the entire reason Will-Executors exist.
+
+## The lifecycle
+
+1. **Prepare.** The plugin builds a transaction spending the wallet's UTXOs, with outputs to your heirs and one extra output paying the Will-Executor's fee. One transaction per selected Will-Executor.
+2. **Sign.** Electrum signs with your key. The plugin never signs on your behalf.
+3. **Distribute.** Each signed transaction goes to its Will-Executor, which stores it.
+4. **Wait.** You keep using your wallet. Balance changes trigger a refresh; [Check Alive](../user-guide/check-alive.md) offers to postpone the date while you are around.
+5. **Execute.** On the delivery date, each Will-Executor holding a copy broadcasts. The first one to get its transaction confirmed collects the fee; the heirs receive the funds.
+
+## Why one transaction per Will-Executor
+
+Each transaction pays a *specific* server. That has three consequences worth understanding:
+
+- **Competition.** Servers race to broadcast, so the reward reaches whoever is actually operating rather than whoever is merely listed somewhere.
+- **Independence.** Will-Executors never need to talk to each other. No coordination layer means no central point of failure or attack.
+- **No retroactive participation.** A signed transaction cannot be modified, and it already names its payee — so a server joining today can only receive wills created from today on.
+
+## What invalidates a will
+
+The transaction spends specific UTXOs. Spending any of them elsewhere makes it permanently invalid: nodes will reject it as a double-spend attempt.
+
+This cuts both ways. It is why the plugin has to rebuild the will whenever your balance changes — and it is also **your escape hatch**: you can revoke a pending inheritance at any time, without anyone's permission, simply by moving a coin.
+
+## Fees
+
+Two distinct fees, both in bitcoin:
+
+| Fee | Paid to | When |
+|---|---|---|
+| **Miner fee** | Bitcoin miners | On confirmation, like any transaction. Set generously so the inheritance confirms even under congestion, possibly years from now. |
+| **Will-Executor fee** | The server that broadcast successfully | Deducted from the inheritance at execution. |
+
+## Known design trade-off
+
+BAL optimises for **simplicity on the heir's side**: one date, one transaction, nothing for the heir to do or even know about in advance.
+
+The cost of that choice falls on the wallet owner: there is **no cancellation window**. On the delivery date the transaction becomes valid and the Will-Executors broadcast it. If you are alive and want to stop it, you must act *before* that date — by postponing it, or by spending a UTXO to invalidate it.
+
+This is why the recommended practice is a **rolling deadline renewed every 2–3 years**: it keeps you structurally far from the delivery date, so the question never becomes urgent. See [Keeping the will up to date](../user-guide/updating.md).

docs/security-privacy.md

@@ -0,0 +1,45 @@
+# Security & Privacy
+
+## Where trust actually sits
+
+BAL does not ask you to trust a Will-Executor. It asks you not to depend on any single one:
+
+- Servers hold **no keys** and cannot spend, alter, or accelerate anything.
+- You select **as many as possible**; only one has to survive to the delivery date.
+- Whether a given operator is a person, a company, or a consortium is not observable from outside — and by design it does not need to be. Protection comes from **redundancy and competition**, not from certifying operators.
+
+## What a Will-Executor sees
+
+The servers you select receive pre-signed transactions that reflect the state of your wallet. That is real information about a living person, refreshed over time as your balance changes.
+
+This is precisely why the choice of *which* servers receive it stays with you, and why privacy is a competitive dimension between Will-Executors — not just price.
+
+Stored transactions are not publicly accessible. You can verify at any time that yours is still held, via the [Server column](user-guide/will-tab.md#the-server-column).
+
+## UTXO consolidation
+
+Sending the entire contents of a wallet in one transaction damages the privacy of your UTXOs: it links everything together, publicly and permanently.
+
+A useful habit, especially when there is a single heir: leave a small remainder to another address. For example 99.7% to the heir and 0.3% elsewhere — an address of your own, or one picked at random from a block explorer. It makes the transaction considerably harder to interpret.
+
+## The heirs list export
+
+The [exported heirs list](user-guide/wallet-backup.md#export-the-heirs-list) states who inherits and how much. Anyone who reads it learns both. Store it accordingly.
+
+The same applies, more strongly, to an [offline backup transaction](user-guide/backup-transaction.md) handed directly to an heir: it reveals the exact date and amount, years in advance. A notary or trusted third party is often the more prudent route.
+
+## The same seed on multiple devices
+
+Strongly discouraged in general, and specifically damaging here: spending a single satoshi from another device changes the wallet's UTXO structure and **invalidates the inheritance transaction**. The Will-Executors will broadcast something the nodes reject.
+
+## Your wallet file is your will
+
+The inheritance data lives in the Electrum **wallet file**, not in the seed. Restoring from seed recovers the funds and loses the will. Back up the file, keep the password — see [Backing up wallet and will](user-guide/wallet-backup.md).
+
+## Long time horizons
+
+Any very long time-lock carries a theoretical risk tied to how the Bitcoin network evolves over decades. This is a further argument for **renewing periodically** rather than signing a thirty-year will once and forgetting it.
+
+## Before real funds
+
+Test on **testnet** or with a small-amount wallet first. Review the generated transactions before broadcasting. The plugin builds real transactions with real consequences, and it never signs without asking you.

docs/stylesheets/extra.css

@@ -0,0 +1,228 @@
+/* ==========================================================================
+   Bitcoin After Life — manual theme
+   Palette taken from the bitcoin-after.life landing page ("Slate" system).
+   Change a value here and it propagates through the whole manual.
+   ========================================================================== */
+
+:root {
+  --bal-accent:       #2d6cdf;
+  --bal-accent-soft:  #e6eefc;
+  --bal-accent-line:  #cfe0fb;
+  --bal-accent-dark:  #2559b8;
+  --bal-ink:          #1a2027;
+  --bal-muted:        #5b6672;
+  --bal-bg:           #eef1f4;
+  --bal-panel:        #ffffff;
+  --bal-line:         #dfe4ea;
+  --bal-line-strong:  #cbd2da;
+  --bal-ok:           #1f9d57;
+  --bal-ok-soft:      #e3f4ea;
+  --bal-warn:         #b5701b;
+  --bal-warn-soft:    #fbf0df;
+  --bal-btc:          #f7931a;
+  --bal-mono: ui-monospace, "SF Mono", Menlo, Consolas, monospace;
+}
+
+/* -------- Light scheme ---------------------------------------------------- */
+[data-md-color-scheme="default"] {
+  --md-primary-fg-color:          var(--bal-accent);
+  --md-primary-fg-color--light:   #4f85e6;
+  --md-primary-fg-color--dark:    var(--bal-accent-dark);
+  --md-primary-bg-color:          #ffffff;
+  --md-primary-bg-color--light:   rgba(255, 255, 255, .7);
+
+  --md-accent-fg-color:           var(--bal-accent-dark);
+  --md-accent-fg-color--transparent: var(--bal-accent-soft);
+  --md-accent-bg-color:           #ffffff;
+
+  --md-default-bg-color:          var(--bal-bg);
+  --md-default-fg-color:          var(--bal-ink);
+  --md-default-fg-color--light:   var(--bal-muted);
+  --md-default-fg-color--lighter: var(--bal-line-strong);
+  --md-default-fg-color--lightest: var(--bal-line);
+
+  --md-typeset-color:             var(--bal-ink);
+  --md-typeset-a-color:           var(--bal-accent);
+
+  --md-code-bg-color:             #e4e9ef;
+  --md-code-fg-color:             var(--bal-ink);
+
+  --md-footer-bg-color:           var(--bal-ink);
+  --md-footer-bg-color--dark:     #12171c;
+}
+
+/* Content sits on white panels, like the cards on the website. */
+[data-md-color-scheme="default"] .md-main__inner .md-content__inner {
+  background: var(--bal-panel);
+  border: 1px solid var(--bal-line);
+  border-radius: 10px;
+  padding: 8px 28px 40px;
+  box-shadow: 0 1px 2px rgba(20, 30, 50, .05);
+}
+
+/* -------- Dark scheme ----------------------------------------------------- */
+/* The website has no dark mode; this is a faithful dark counterpart built
+   around the same accent blue. */
+[data-md-color-scheme="slate"] {
+  --md-hue: 215;
+
+  --md-primary-fg-color:          #5b8ce8;
+  --md-primary-fg-color--light:   #7ea6ee;
+  --md-primary-fg-color--dark:    var(--bal-accent);
+  --md-primary-bg-color:          #0f1419;
+
+  --md-accent-fg-color:           #7ea6ee;
+  --md-accent-fg-color--transparent: rgba(45, 108, 223, .12);
+
+  --md-default-bg-color:          #12171c;
+  --md-typeset-a-color:           #7ea6ee;
+
+  --md-code-bg-color:             #1a2027;
+  --md-footer-bg-color:           #0f1419;
+}
+
+[data-md-color-scheme="slate"] .md-main__inner .md-content__inner {
+  background: #171d24;
+  border: 1px solid #262e37;
+  border-radius: 10px;
+  padding: 8px 28px 40px;
+}
+
+/* -------- Typography ------------------------------------------------------ */
+.md-typeset h1,
+.md-typeset h2,
+.md-typeset h3 {
+  font-weight: 600;
+  letter-spacing: -.015em;
+}
+.md-typeset h1 { color: var(--md-default-fg-color); }
+.md-typeset h2 { border-bottom: 1px solid var(--md-default-fg-color--lightest); padding-bottom: .3em; }
+
+.md-typeset code,
+.md-typeset pre > code { font-family: var(--bal-mono); }
+
+/* Code blocks use the site's dark "ink" background in both schemes. */
+[data-md-color-scheme="default"] .md-typeset pre > code {
+  background: var(--bal-ink);
+  color: #e8edf3;
+}
+
+/* -------- Tables ---------------------------------------------------------- */
+.md-typeset table:not([class]) {
+  border: 1px solid var(--md-default-fg-color--lightest);
+  border-radius: 10px;
+  overflow: hidden;
+  box-shadow: none;
+  font-size: .78rem;
+}
+.md-typeset table:not([class]) th {
+  background: var(--md-default-bg-color);
+  color: var(--md-default-fg-color--light);
+  font-size: .68rem;
+  font-weight: 600;
+  letter-spacing: .08em;
+  text-transform: uppercase;
+}
+
+/* -------- Admonitions mapped to the site's semantic colours --------------- */
+.md-typeset .admonition,
+.md-typeset details { border-radius: 10px; font-size: .76rem; }
+
+:root {
+  --md-admonition-icon--note: var(--md-admonition-icon--abstract);
+}
+.md-typeset .admonition.info,
+.md-typeset .admonition.note,
+.md-typeset details.info,
+.md-typeset details.note      { border-color: var(--bal-accent); }
+.md-typeset .info > .admonition-title,
+.md-typeset .note > .admonition-title,
+.md-typeset .info > summary,
+.md-typeset .note > summary   { background: var(--bal-accent-soft); }
+
+.md-typeset .admonition.tip,
+.md-typeset details.tip       { border-color: var(--bal-ok); }
+.md-typeset .tip > .admonition-title,
+.md-typeset .tip > summary    { background: var(--bal-ok-soft); }
+
+.md-typeset .admonition.warning,
+.md-typeset details.warning   { border-color: var(--bal-warn); }
+.md-typeset .warning > .admonition-title,
+.md-typeset .warning > summary { background: var(--bal-warn-soft); }
+
+[data-md-color-scheme="slate"] .md-typeset .info > .admonition-title,
+[data-md-color-scheme="slate"] .md-typeset .note > .admonition-title,
+[data-md-color-scheme="slate"] .md-typeset .info > summary,
+[data-md-color-scheme="slate"] .md-typeset .note > summary   { background: rgba(45, 108, 223, .16); }
+[data-md-color-scheme="slate"] .md-typeset .tip > .admonition-title,
+[data-md-color-scheme="slate"] .md-typeset .tip > summary     { background: rgba(31, 157, 87, .16); }
+[data-md-color-scheme="slate"] .md-typeset .warning > .admonition-title,
+[data-md-color-scheme="slate"] .md-typeset .warning > summary { background: rgba(181, 112, 27, .18); }
+
+/* FAQ accordions read better with a little separation. */
+.md-typeset details { margin-bottom: .5rem; }
+
+/* -------- Screenshots ----------------------------------------------------- */
+img.screenshot {
+  border: 1px solid var(--md-default-fg-color--lightest);
+  border-radius: 8px;
+  box-shadow: 0 6px 20px rgba(20, 30, 50, .08);
+  max-width: 100%;
+}
+img.screenshot + em,
+p > img.screenshot + em {
+  display: block;
+  margin-top: .4rem;
+  font-size: .72rem;
+  font-style: normal;
+  color: var(--md-default-fg-color--light);
+}
+
+/* -------- Misc ------------------------------------------------------------ */
+.md-typeset .grid.cards > :is(ul, ol) > li,
+.md-typeset .grid > .card { border-radius: 10px; }
+
+.md-typeset a.btc,
+.md-typeset .btc { color: var(--bal-btc); font-weight: 700; }
+
+:focus-visible { outline: 2px solid var(--bal-accent); outline-offset: 2px; }
+
+
+/* -------- Brand ----------------------------------------------------------- */
+/* Header sits on the accent blue, so it uses the white mark directly
+   (docs/assets/logo.svg is a copy of logo-mark-white.svg). */
+.md-header__button.md-logo img,
+.md-header__button.md-logo svg {
+  height: 1.6rem;
+  width: auto;
+}
+
+/* Homepage lockup: the mark plus the name set in Inter — the same construction
+   the website uses in its top bar, and immune to the Optima dependency of the
+   SVG wordmark. */
+.bal-hero {
+  display: flex;
+  flex-direction: column;
+  align-items: center;
+  gap: .7rem;
+  margin: 1.4rem 0 2.2rem;
+  text-align: center;
+}
+.bal-hero img { width: 116px; height: auto; }
+.bal-hero .name {
+  font-size: 1.35rem;
+  font-weight: 600;
+  letter-spacing: -.015em;
+  line-height: 1.1;
+  color: var(--md-default-fg-color);
+}
+.bal-hero .tagline {
+  font-size: .68rem;
+  letter-spacing: .14em;
+  text-transform: uppercase;
+  color: var(--md-default-fg-color--light);
+}
+/* Swap black / white mark with the colour scheme. */
+.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; }

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.

docs/will-executors/choosing.md

@@ -0,0 +1,47 @@
+# Choosing Will-Executors in the plugin
+
+The plugin downloads the [WeList](welist.md) directory by default and tries to use as many Will-Executors as possible. You can also add servers manually, or draw from alternative lists — the WeList makes discovery easier, it does not control access to the network.
+
+The service list window opens from the Electrum menu: **Tools → Will-executor**.
+
+![Will-Executor service list](../img/willexecutors-window.png){ .screenshot }
+*The list of known Will-Executors, with fees and online status.*
+
+## Columns
+
+| Column | Meaning |
+|---|---|
+| **URL** | Address of the Will-Executor |
+| **Base fee** | The commission that server asks, paid only on execution |
+| **Info** | Description or website link |
+| **Default address** | Bitcoin address where the fee will be sent |
+| **Status** | Green dot = server responding |
+
+## Commands
+
+| Command | What it does |
+|---|---|
+| **Ping** | Checks which servers are online |
+| **Import** | Imports a Will-Executor list other than the default |
+| **Export** | Exports your list — useful when moving to another Electrum installation |
+| **Add** | Adds a Will-Executor manually |
+
+## Per-server actions
+
+![Right-click menu on a Will-Executor](../img/willexecutors-context-menu.png){ .screenshot }
+*Right-click a row for per-server actions.*
+
+- **Select** — includes this Will-Executor in your inheritance (green check mark).
+- **Edit** — edits the corresponding field.
+- **Ping** — checks whether that server is online.
+- **Delete** — removes it from your list.
+
+## How to choose well
+
+- **Quantity first.** One transaction is created per selected server, and only one has to survive to the delivery date. Select generously.
+- **Ignore extremes on price.** Too expensive eats into the inheritance; suspiciously cheap may not survive for years.
+- **Prefer diversity.** Different operators, different hosting, different jurisdictions — the point of redundancy is that failures are uncorrelated.
+- **Re-check periodically.** Use the [Server column](../user-guide/will-tab.md#the-server-column) to confirm your wills are still stored, and renew the will if servers have disappeared.
+
+!!! info "Adding a server by hand"
+    You are not limited to the WeList. Servers announced on BitcoinTalk or shared through alternative directories can be added manually with **Add**.

docs/will-executors/running-a-server.md

@@ -0,0 +1,127 @@
+# Running a Will-Executor
+
+This page covers setting up your own Will-Executor node. If you are wondering *why* you would, start with [What Will-Executors are](what-they-are.md).
+
+!!! warning "Read this first"
+    Running a Will-Executor is a **long-horizon commitment**, not a quick return. You will hold pre-signed transactions belonging to living people, and you are compensated only when you successfully broadcast an inheritance that confirms on-chain — potentially years from now. Costs are certain; revenue is not.
+
+    Nothing on this page is an offer, a solicitation, or a promise of any economic result. It describes a technical role.
+
+## What the role actually requires
+
+- **A server that stays up.** A dedicated machine, a VPS, or a home node — at least one Will-Executor on the network runs on Umbrel OS. Modern releases run comfortably on a small VPS.
+- **Reliable connectivity.** Tor-only operation is possible: at least one active Will-Executor is reachable exclusively that way.
+- **A Bitcoin full node** with ZMQ enabled (see below).
+- **Real maintenance.** Updates, backups, monitoring. A server that fails to broadcast when it matters earns nothing — and, more importantly, fails the user who relied on the network.
+- **Discretion.** You will be handling data that reflects the wallets of living people. Privacy and reliability, not just price, are what Will-Executors compete on.
+
+!!! tip "A Will-Executor doesn't have to be one person"
+    From the protocol's point of view a Will-Executor is a service plus a Bitcoin address. Several operators can pool resources, present themselves as a single Will-Executor, and use a shared **multisig** address for the fee, splitting proceeds however they agree. A meetup, an association, or a group of friends can run one together.
+
+    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.
+
+## The two components
+
+| Component | Role |
+|---|---|
+| **`bal-server`** | Receives and stores the pre-signed inheritance transactions sent by plugins |
+| **`bal-pusher`** | Watches for new Bitcoin blocks via ZMQ and broadcasts stored transactions once their locktime passes the median time past (MTP) |
+
+Both live in the [bal-server repository](https://bitcoin-after.life/gitea/bitcoinafterlife/bal-server) (Rust, [releases](https://bitcoin-after.life/gitea/bitcoinafterlife/bal-server/releases)).
+
+## Prerequisites
+
+1. **Bitcoin Core compiled with ZMQ support**, with this line in `bitcoin.conf`:
+
+    ```text
+    zmqpubhashblock=tcp://127.0.0.1:28332
+    ```
+
+2. **Rust and Cargo** — see the [official installation instructions](https://www.rust-lang.org/tools/install).
+
+## Installing `bal-server`
+
+```bash
+git clone https://bitcoin-after.life/gitea/bitcoinafterlife/bal-server.git
+cd bal-server
+
+# Ed25519 keypair identifying this Will-Executor
+openssl genpkey -algorithm ED25519 -out private_key.pem
+openssl pkey -in private_key.pem -pubout -out public_key.pem
+
+cargo build --release
+sudo cp target/release/bal-server /usr/local/bin
+bal-server
+```
+
+!!! danger "Back up `private_key.pem`"
+    It is the identity of your Will-Executor. Store it securely and restrict its permissions (`chmod 600`).
+
+### Configuration
+
+`bal-server` is configured through environment variables:
+
+| Variable | Description | Default |
+|---|---|---|
+| `BAL_SERVER_CONFIG_FILE` | Configuration file path — created if missing | `$HOME/.config/bal-server/default-config.toml` |
+| `BAL_SERVER_DB_FILE` | SQLite3 database file — created if missing | `bal.db` |
+| `BAL_SERVER_BIND_ADDRESS` | Public listening address | `127.0.0.1` |
+| `BAL_SERVER_BIND_PORT` | Listening port | `9137` |
+| `BAL_SERVER_PUB_KEY_PATH` | Will-Executor Ed25519 public key | `public_key.pem` |
+| `BAL_SERVER_BITCOIN_ADDRESS` | Address that receives fees on **mainnet** | — |
+| `BAL_SERVER_BITCOIN_FIXED_FEE` | Fixed fee on mainnet | `50000` |
+| `BAL_SERVER_TESTNET_ADDRESS` / `..._FIXED_FEE` | Same, for testnet | — / `50000` |
+| `BAL_SERVER_SIGNET_ADDRESS` / `..._FIXED_FEE` | Same, for signet | — / `50000` |
+| `BAL_SERVER_REGTEST_ADDRESS` / `..._FIXED_FEE` | Same, for regtest | — / `50000` |
+
+A sample environment file (`bal-server.env`) and a systemd unit (`bal-server.service`) ship with the repository.
+
+!!! warning "Bind address and exposure"
+    The default `127.0.0.1` is local-only. To be reachable by users you must expose the service deliberately — typically behind a reverse proxy with TLS, or as a Tor hidden service. Do not expose it carelessly.
+
+## Installing `bal-pusher`
+
+`bal-pusher` reads the same database and does the broadcasting.
+
+```bash
+bal-pusher [bitcoin|testnet|regtest]
+```
+
+### Configuration
+
+| Variable | Description | Default |
+|---|---|---|
+| `BAL_PUSHER_CONFIG_FILE` | Configuration file path — created if missing | `$HOME/.config/bal-pusher/default-config.toml` |
+| `BAL_PUSHER_DB_FILE` | SQLite3 database file | `bal.db` |
+| `BAL_PUSHER_ZMQ_LISTENER` | ZMQ endpoint for block updates | `tcp://127.0.0.1:28332` |
+| `BAL_PUSHER_BITCOIN_HOST` | Bitcoin RPC host | `http://127.0.0.1` |
+| `BAL_PUSHER_BITCOIN_PORT` | Bitcoin RPC port | `8332` |
+| `BAL_PUSHER_BITCOIN_COOKIE_FILE` | Bitcoin RPC cookie file | `$HOME/.bitcoin/.cookie` |
+| `BAL_PUSHER_BITCOIN_RPC_USER` | Bitcoin RPC username | — |
+| `BAL_PUSHER_BITCOIN_RPC_PASSWORD` | Bitcoin RPC password | — |
+| `BAL_PUSHER_SEND_STATS` | Report timing statistics to the WeList | `false` |
+| `WELIST_SERVER_URL` | WeList server URL | `https://welist.bitcoin-after.life` |
+| `BAL_SERVER_URL` | URL of your Will-Executor | — |
+| `SSL_KEY_PATH` | Ed25519 private key (PEM) | `private_key.pem` |
+
+!!! note "`bal-pusher` must point at the same database as `bal-server`"
+    `BAL_PUSHER_DB_FILE` and `BAL_SERVER_DB_FILE` have to resolve to the same SQLite file, otherwise the pusher will have nothing to broadcast.
+
+## RPC interface
+
+The request/response interface used by the plugin is documented in [`RPC.md`](https://bitcoin-after.life/gitea/bitcoinafterlife/bal-server/src/branch/main/RPC.md) in the repository.
+
+## Going live
+
+1. **Test on testnet or regtest first.** The WeList lets users filter by network, so a testnet server is a legitimate way to validate the whole chain of events.
+2. **Verify reachability** from outside your own network, at the exact URL you intend to publish.
+3. **Set up monitoring and restart policies** (the provided systemd unit is a starting point).
+4. **Plan your backups** — the SQLite database holds the wills you have accepted; the Ed25519 key is your identity.
+5. **List on the [WeList](welist.md)** if you want automatic discovery by plugin users — {{ bal.welist_fee_sats }} sats per year. Listing is optional; users can also add your server manually.
+
+!!! tip "CPFP for congested conditions"
+    Inheritance transactions are built with a prudent miner fee, but a Will-Executor can use **CPFP (Child Pays For Parent)** to speed up confirmation if the network is congested at delivery time. Being the first to get a transaction confirmed is what earns the fee.
+
+## Getting in touch
+
+For help setting up a Will-Executor, or to collaborate on the project: **[info@bitcoin-after.life](mailto:info@bitcoin-after.life)**

docs/will-executors/welist.md

@@ -0,0 +1,35 @@
+# The WeList directory
+
+The **WeList** is the public directory of Will-Executors, published at [welist.bitcoin-after.life](https://welist.bitcoin-after.life/). The plugin downloads it by default, so listed servers appear automatically when you set up a will.
+
+![The WeList leaderboard](../img/welist-website.png){ .screenshot }
+*The public Will-Executor leaderboard.*
+
+## What it shows
+
+For each server: URL, description, fee, software version, block height, wins, and score. You can filter by network (**Bitcoin**, **Testnet**, **Testnet4**, **Regtest**) and choose whether to include **Tor** servers. The list is also available as **JSON** for programmatic use.
+
+!!! note "Data freshness"
+    Fee, description and version refresh roughly once a day, and may be outdated. The plugin remains the authoritative source at the moment you build your will.
+
+## Ranking
+
+Servers are ordered by: excess donated over the yearly fee, then total amount paid, then lower base fee, then WeTime points.
+
+## Listing your own server
+
+| | |
+|---|---|
+| **Yearly fee** | {{ bal.welist_fee_sats }} sats |
+| **Listing period** | {{ bal.welist_period_days }} days, starting when the payment reaches 3 confirmations (~30 min) |
+| **Renewal window** | From 6 months before expiry, for one additional year |
+| **Plugin integration** | Automatic once listed |
+
+The procedure: enter your server URL on the WeList site, accept the [terms](https://welist.bitcoin-after.life/terms.html), and pay the invoice. Your server appears once the deposit confirms.
+
+!!! warning "Before you pay"
+    Make sure your server is **online and reachable** at the exact URL you submit. There are no refunds after payment, and later URL changes require proof of ownership.
+
+## Listing is optional
+
+Being on the WeList is **not** required to operate a Will-Executor. Users can add servers manually, and the plugin can draw from alternative lists. The WeList exists to simplify discovery, not to gate participation in the network.

docs/will-executors/what-they-are.md

@@ -0,0 +1,44 @@
+# What Will-Executors are
+
+A Will-Executor is a server with one narrow job: **it stores pre-signed inheritance transactions and broadcasts them to the Bitcoin network on the date the user chose.** Nothing else.
+
+## What a Will-Executor cannot do
+
+- **It cannot spend your funds.** It holds no keys.
+- **It cannot alter the transaction.** The transaction is already fully signed by you; any modification would invalidate the signature.
+- **It cannot execute early.** The transaction carries an absolute `nLockTime`, and Bitcoin nodes reject it until that date is reached.
+- **It does not coordinate with other Will-Executors.** Every node is independent. There is no central point to attack or compromise.
+
+What it *does* require is longevity: being still there, still working, years from now.
+
+## 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.
+
+On the delivery date, every Will-Executor holding a copy can broadcast. Only one transaction can confirm — and the fee goes to whoever broadcast the one that made it into a block. It is a competitive mechanism, conceptually close to mining: **the reward goes to whoever is actually operating**, not to whoever is merely listed in a directory.
+
+For you, the consequence is simple and reassuring: **only one of your selected Will-Executors has to still be alive on the delivery date** for the inheritance to be executed.
+
+!!! tip "Select as many as you can"
+    Redundancy is the whole guarantee. Each additional Will-Executor is another independent chance that someone is still there when it matters.
+
+## Who sets the fees
+
+Each Will-Executor freely sets its own commission — there is no price imposed by the protocol. The market sets the price.
+
+When creating your will you can exclude servers you consider too expensive. It is also worth being wary of **suspiciously cheap** ones: a price that cannot cover the cost of running a server for years is a hint that the service may not last.
+
+!!! warning "Don't lower the fee manually"
+    Fees are shown both on the [WeList](welist.md) and inside the plugin. Setting a fee below what a server asks will typically get your transaction rejected by that server.
+
+## New servers cannot join old wills
+
+Inheritance transactions are pre-signed and already contain the address of the Will-Executor that will be paid. A signed transaction cannot be modified — so a server that joins the network today receives the wills created **from today onwards**, never the ones already out there.
+
+This is why renewing your will periodically is useful: it brings newer Will-Executors into your selection. See [Keeping the will up to date](../user-guide/updating.md).
+
+## What they can see
+
+The Will-Executors you select receive pre-signed transactions that reflect the state of your wallet. That is why the choice of which servers receive them stays entirely in your hands, and why privacy — alongside reliability — is the real ground of competition between Will-Executors.
+
+Transactions stored on the servers are **not publicly accessible**. From the plugin you can verify at any time that yours is still there: see the [Server column](../user-guide/will-tab.md#the-server-column).

internal/README.md

@@ -0,0 +1,14 @@
+# Internal notes — NOT published
+
+Everything in this folder is versioned in Gitea but **excluded from the built site**
+(`mkdocs build` only reads `docs/`). Use it for material that is not ready — or not
+intended — for public publication.
+
+| File | Purpose |
+|---|---|
+| `design-choices-DRAFT.md` | Competitor comparison and the BIP 128 critique. **Not validated by the devs.** |
+| `source-notes.md` | Where each part of the manual came from, and what still needs verification. |
+| `screenshot-checklist.md` | How to produce and replace the screenshots. |
+
+To publish something from here: move the file into `docs/`, add it to the `nav` in
+`mkdocs.yml`, and remove the draft warnings.

internal/brand-assets.md

@@ -0,0 +1,54 @@
+# Brand assets
+
+The official logo files are installed. This page explains what each one is and when to use it.
+
+## Files in `docs/assets/`
+
+| File | What it is | Used by |
+|---|---|---|
+| `logo.svg` | Copy of `logo-mark-white.svg` | Site header (Material reads `theme.logo`) |
+| `logo-mark-white.svg` | Symbol only, white | Header (on the accent blue), dark scheme |
+| `logo-mark-black.svg` | Symbol only, black | Homepage lockup in light scheme |
+| `logo-lockup-black.svg` | Symbol **+ "Bitcoin After Life"** wordmark, black | Print, covers, external use |
+| `logo-lockup-white.svg` | Same lockup, white | Dark backgrounds, external use |
+| `favicon.png` | Symbol in `#2d6cdf`, 256×256 | Browser tab (`theme.favicon`) |
+
+All were derived from the official `Logo nero.svg`: recoloured, and — for the mark-only
+versions — cropped to `viewBox="0 0 205.29 212.5"` to remove the wordmark band.
+
+## The Optima dependency — important
+
+The wordmark in the **lockup** files is live `<text>` in **Optima-Bold**, not outlines.
+On any machine without Optima installed, the browser substitutes another face and the
+wordmark no longer matches the brand.
+
+Two mitigations are already in place:
+
+1. A fallback stack — `'Optima-Bold', Optima, Candara, 'Segoe UI', 'Trebuchet MS', sans-serif`.
+2. The three original absolutely-positioned text runs (`Bitcoin` / ` ` / `After Life`) were
+   merged into a **single centred `<text>`**. In the original they overlapped badly whenever
+   Optima was missing.
+
+**The proper fix**, when someone has Optima and a vector editor: open the lockup, convert
+the text to outlines (Illustrator: *Type → Create Outlines*; Inkscape: *Path → Object to Path*),
+re-export, and replace the two lockup files. After that the wordmark is font-independent.
+
+Until then, prefer the **mark-only** files wherever the rendering environment is unknown.
+
+## Why the homepage does not use the lockup SVG
+
+The homepage builds its own lockup: the mark, then "Bitcoin After Life" as HTML text in
+**Inter**. This mirrors what the website's top bar does, and sidesteps the Optima problem
+entirely. See `.bal-hero` in `docs/stylesheets/extra.css`.
+
+## Typeface note
+
+`OPTIMA.TTF` ships in the `bal-website` repo, but Optima is a licensed commercial typeface.
+Do **not** self-host it as a webfont in this repository unless the project holds a webfont
+licence. The manual uses Inter, matching the landing page's `--display` / `--body` stack.
+
+## Replacing a logo later
+
+Keep the filenames. Drop the new file over the old one and rebuild — `mkdocs.yml`,
+`index.md` and the CSS all reference these names, so nothing else changes. If you replace
+`logo-mark-white.svg`, copy it over `logo.svg` too (that is the header logo).

internal/design-choices-DRAFT.md

@@ -0,0 +1,133 @@
+# DRAFT — Design choices and comparison with other approaches
+
+> **STATUS: NOT PUBLISHED. NOT VALIDATED BY THE DEVELOPERS.**
+>
+> This page contains technical positioning material that must be reviewed before it
+> becomes an official project statement. It is kept here, out of the published site,
+> so it is ready when that review happens.
+>
+> Source: internal drafts (July 2026), corrected version of 24/07/2026.
+> Tone rule: factual, no disparagement — these are design trade-offs, not mistakes.
+
+## Three different approaches
+
+| | Liana (Wizardsardine) | Timelock Recovery (Electrum plugin) | BAL |
+|---|---|---|---|
+| Mechanism | **Script-based** wallet (Miniscript): the timelock lives in the script locking the UTXOs | **Pre-signed transactions**: an Alert + Recovery pair | **Pre-signed transactions** with absolute `nLockTime` |
+| Timelock type | Relative (CSV / BIP 68), per UTXO | Relative (nSequence / BIP 68) on the *second* transaction | Absolute (`nLockTime`) |
+| What the BIP 68 cap limits | Maximum inactivity before the recovery key becomes usable | Only the **cancellation window** (2–388 days), not the inheritance horizon | — (does not use relative timelocks) |
+| Distribution | None: on-chain | User/heir keeps the plan; monitoring services exist | Decentralized Will-Executor network |
+
+## Liana: where the ~15 month limit comes from
+
+Liana uses **relative** timelocks (CSV/BIP 68) inside the script: the countdown starts
+when each individual UTXO is received. The field is 2 bytes, so it cannot exceed 65,535 —
+a **Bitcoin consensus limit**, not a wallet limitation. In blocks: 65,535 blocks ≈ **455
+theoretical days (~15 months)**. In the time variant (512-second units) the cap is
+equivalent to **~388 days**.
+
+Documented consequence, acknowledged by its own developers: the user must periodically
+"rotate" coins (send them to a new address of their own) to reset the timer — paying fees
+each time — otherwise the recovery path opens. The project itself notes this fits poorly
+with cold wallets that are never touched, and that a non-technical heir may struggle,
+since not all UTXOs unlock at the same block height.
+
+**The DCA example (valid for Liana, NOT for Timelock Recovery):** someone buying monthly
+for a year accumulates twelve UTXOs with twelve distinct countdowns. If they die after the
+last purchase, the heirs do not find a single inheritance but **unlocks staggered over more
+than a year**, with several recovery transactions to execute at different moments — unless
+the user had manually consolidated the UTXOs (which is the same periodic rotation already
+required).
+
+## Timelock Recovery: NOT like Liana — closer to BAL
+
+Timelock Recovery is **not** a script wallet and does **not** cap the inheritance horizon
+at ~1 year. It uses a pair of pre-signed transactions:
+
+1. **Alert Transaction** — consolidates funds to a new address of the user's own wallet
+   (plus small anchor outputs for CPFP). The heir broadcasts it when needed, and its
+   appearance on-chain acts as an *alert* to the user.
+2. **Recovery Transaction** — spends the Alert's output to the heirs' wallets, with a
+   **relative nSequence** imposing a waiting period.
+
+The **388** figure belongs here: it is the maximum **cancellation window** (whole days,
+2 to 388), not the duration of the inheritance. Beyond 388 days you overflow BIP 68's
+bits. The logic is the opposite of Liana's: that window gives a still-living user time to
+cancel everything (by spending the funds) if the plan is triggered by mistake or under
+duress.
+
+**Positioning note:** the author of Timelock Recovery has filed **BIP 128** (draft,
+assigned 5 February 2026) to standardise the JSON format of such plans, with a reference
+implementation in the plugin officially included in Electrum's repository. This is a
+competitor on a standardisation trajectory — to be treated with respect and precision.
+
+## BIP 128's critique of BAL's approach — have the answer ready
+
+The Motivation section of BIP 128 explicitly criticises the scheme BAL uses: the single
+pre-signed transaction with a future `nLockTime`. The argument: in the "all is well"
+scenario (user alive, seed not lost), as the date approaches the user **must** access the
+wallet and spend a UTXO to revoke the transaction, otherwise it becomes valid and moves
+the funds **with no cancellation period**. There is no window for second thoughts: on the
+date, the transaction is valid and the Will-Executors broadcast it.
+
+This is the most serious technical objection BAL will face from a competent audience. It
+should be met head-on, not avoided. Elements of a reply (**to be validated by the devs**):
+
+- The **2–3 year renewal policy** with a rolling deadline is precisely the safeguard: someone
+  who renews never gets close to the date.
+- The user always retains control: spending a single UTXO invalidates the inheritance.
+  Revocation is always in their hands and requires nobody's permission.
+- The plugin allows setting a reminder in the system calendar.
+- Declared trade-off: BAL chooses **simplicity for the heir** (one date, one transaction,
+  nothing to execute) at the price of requiring **renewal discipline from the owner**.
+  Timelock Recovery chooses the opposite: no looming deadline for the owner, but the heir
+  must execute two transactions in sequence and wait out the cancellation period.
+- Possible future improvement (issue for [DEV]): an alert / cancellation-window mechanism
+  in BAL as well.
+
+## BAL's real advantage, stated precisely
+
+Not "the others are limited to one year" — that is imprecise and easy to attack. The
+correct positioning rests on three points:
+
+1. **Nothing required of the heirs.** With Timelock Recovery someone must broadcast the
+   Alert, wait days or months, then broadcast the Recovery — knowing what they are doing
+   and having kept the plan. With BAL the Will-Executor network broadcasts on its own: the
+   heir may not even know in advance.
+2. **No consensus-forced rotation** (vs Liana), and no problem of UTXOs unlocking at
+   different times: a single date for the whole wallet.
+3. **Distributed redundancy.** The plan does not depend on a file someone must keep and
+   find: one Will-Executor out of N still operating is enough. (The USB file remains as an
+   extra backup.)
+
+## Technical points not to get wrong in public
+
+- The 65,535 limit is a **Bitcoin consensus** limit (BIP 68) and applies only to **relative**
+  timelocks. Absolute `nLockTime` has no such cap: in practice it can set dates decades away
+  (with 32-bit Unix timestamps the practical limit is the year 2106).
+- Do **not** say "Timelock Recovery only allows one year of inheritance" — it is **false**,
+  and anyone familiar with the project would dismantle it instantly. The 388 is the maximum
+  cancellation window.
+- Do **not** say "Liana is limited to 388 days" without qualification: in the block variant
+  it is 65,535 blocks (~455 theoretical days, ~15 months); 388 days is the time variant.
+- Remember that transactions with a future `nLockTime` are **not accepted by the mempool**
+  until the date is reached — this is why someone (the Will-Executors) must broadcast them
+  at the right moment.
+- Balance note: any very long timelock carries a theoretical risk tied to the future
+  evolution of the Bitcoin network — a further argument for periodic renewal.
+
+## Editorial rules carried over from the source drafts
+
+- Never use, in any public version: "investment", "return", "yield", "pension",
+  "passive income", or any projection of future sat or fee prices.
+- Always keep the risk disclaimer when publishing Will-Executor recruitment material.
+- Correct formula for Electrum: "listed in Electrum's third-party plugin directory" —
+  **never** "approved by Electrum".
+
+## Open actions
+
+1. Have the devs validate the technical FAQ answers (what a Will-Executor can actually see,
+   CPFP) and above all the reply to the BIP 128 critique — the most exposed point of BAL's design.
+2. Evaluate as a [DEV] issue a possible alert / cancellation mechanism in BAL.
+3. Turn the Will-Executor recruitment article into a blog post (the remaining `[to complete]`
+   fields need dev input: current fee range, minimum system requirements).

internal/screenshot-checklist.md

@@ -0,0 +1,50 @@
+# Screenshots — how to produce and replace them
+
+## The short version
+
+Every image in the manual is listed in **`screenshots.yml`** at the project root.
+To replace one, save your screenshot as `docs/img/<filename>` using **exactly** the
+filename from the manifest. No Markdown edit is needed — the pages already point there.
+
+```bash
+python3 tools/make_placeholders.py --list   # what's still missing
+python3 tools/make_placeholders.py          # fill gaps with placeholders
+```
+
+Placeholders never overwrite a real image.
+
+## Capture rules — keep these identical everywhere
+
+- **Electrum window only**, not the whole desktop.
+  Windows: ++win+shift+s++ · macOS: ++cmd+shift+4++ then ++space++ · Linux: your screenshot tool's window mode.
+- **~1280×800**, system zoom at 100%.
+- **One theme** for the entire manual — never mix light and dark shots.
+- **PNG** format.
+
+## Data hygiene — this is the important part
+
+Screenshots of an inheritance plugin leak real information if you are careless.
+
+- Use a **dedicated test wallet**, ideally on testnet.
+- **Fake heir names** (Jonny, Andrea — as in the original manual).
+- **Round, obviously fake amounts.**
+- **No real Bitcoin address** that belongs to you or anyone you know.
+- Check the window title bar, the status bar, and any visible file paths — they often
+  contain a username or a real wallet filename.
+
+## Annotations
+
+If you add arrows or highlight boxes, keep one consistent style across the whole manual:
+same colour, same stroke width, same arrowhead. Inconsistent annotation looks worse than none.
+
+## Adding a new image
+
+1. Add an entry to `screenshots.yml` (`file`, `page`, `shows`).
+2. Reference it in the page:
+
+    ```markdown
+    ![Alt text](../img/your-file.png){ .screenshot }
+    *Caption line.*
+    ```
+
+3. Run `python3 tools/make_placeholders.py` so the build stays green until the real shot exists.

internal/source-notes.md

@@ -0,0 +1,47 @@
+# Source notes — where this manual came from, and what to verify
+
+Compiled July 2026. Keep this updated whenever the manual is revised.
+
+## Sources used
+
+| Source | Used for |
+|---|---|
+| [bitcoin-after.life](https://bitcoin-after.life) (homepage + FAQ) | Current behaviour: wizard, Server column, postpone/anticipate logic, compatibility, wallet-backup use case. **Primary source — most current.** |
+| [WeList](https://welist.bitcoin-after.life/) | Listing fee, ranking, networks, renewal window |
+| [bal-server](https://bitcoin-after.life/gitea/bitcoinafterlife/bal-server) README + RPC.md | The entire "Running a Will-Executor" page |
+| [bal-electrum-plugin](https://bitcoin-after.life/gitea/bitcoinafterlife/bal-electrum-plugin) releases | Version/Electrum compatibility table |
+| BAL MANUAL revB (PDF, Jan 2025) | Operational detail retained where still valid: 100% sizing rules, heir fields, wallet-file vs seed, UTXO privacy, export list |
+| Internal drafts (July 2026) | Will-Executor FAQ, competition/incentive model, consortium & multisig, renewal cadence |
+
+## Where the old PDF is now WRONG — do not reuse
+
+| PDF revB says | Reality |
+|---|---|
+| Install by copying files into the `plugins/` folder | Tools → Plugins → **install from file** (zip), Electrum 4.7.2 |
+| "BAL 1.0" | Plugin v0.2.6 |
+| Manual step-by-step parameter setup | Guided **wizard** since v0.2.0 |
+| Check Alive is a base parameter | **Advanced mode** only |
+| 9-state colour table for transaction status | **Server column** with 5 textual labels |
+| Postponing always requires an on-chain invalidation | Balance/heir changes → will **anticipated by one day and redistributed**, no on-chain fee. On-chain invalidation only for a genuine postponement |
+| 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 |
+
+## To verify with the developers before the next revision
+
+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
+   suffixes the current wizard accepts, and whether Raw input still exists alongside the calendar.
+3. **What a Will-Executor can actually see** — the FAQ answer is deliberately cautious.
+   A precise formulation would be better.
+4. **Default miner fee.** The PDF said 100 sat/vbyte. The current wording says only "a prudent
+   default" — confirm the actual value so it can be stated.
+5. **Fee range currently charged** by Will-Executors on the network (for the recruitment article).
+6. **Minimum system requirements** for a Will-Executor node, stated concretely.
+7. **BIP 128 critique** — see `design-choices-DRAFT.md`. The single most exposed point.
+
+## Deliberately left out of the published manual
+
+- Competitor comparison and BIP 128 response → `design-choices-DRAFT.md` (needs dev validation).
+- Will-Executor recruitment article → belongs on the blog, not in a manual, and still has
+  `[to complete]` fields.

mkdocs.yml

@@ -0,0 +1,117 @@
+site_name: Bitcoin After Life — Manual
+site_description: Manual for the Bitcoin After Life (BAL) Electrum plugin and the Will-Executor network
+site_url: https://bitcoin-after.life/docs/
+use_directory_urls: false
+repo_url: https://bitcoin-after.life/gitea/bitcoinafterlife/bal-docs
+repo_name: Gitea
+edit_uri: _edit/main/docs/
+
+theme:
+  name: material
+  # Brand assets — see internal/brand-assets.md for where the official files live.
+  logo: assets/logo.svg
+  favicon: assets/favicon.png
+  palette:
+    - media: "(prefers-color-scheme: light)"
+      scheme: default
+      primary: custom
+      accent: custom
+      toggle: { icon: material/weather-night, name: Switch to dark mode }
+    - media: "(prefers-color-scheme: dark)"
+      scheme: slate
+      primary: custom
+      accent: custom
+      toggle: { icon: material/weather-sunny, name: Switch to light mode }
+  font:
+    text: Inter
+    code: Roboto Mono
+  features:
+    - navigation.sections
+    - navigation.top
+    - navigation.footer
+    - navigation.indexes
+    - search.suggest
+    - content.action.edit
+    - content.code.copy
+
+extra_css:
+  - stylesheets/extra.css
+
+nav:
+  - Home: index.md
+  - Getting started:
+      - Installation: getting-started/installation.md
+      - Create your first will: getting-started/quick-start.md
+  - User guide:
+      - Heirs and shares: user-guide/heirs.md
+      - Delivery time: user-guide/delivery-time.md
+      - Check Alive: user-guide/check-alive.md
+      - The WILL tab: user-guide/will-tab.md
+      - Keeping the will up to date: user-guide/updating.md
+      - Offline backup transaction: user-guide/backup-transaction.md
+      - Wallet recovery use case: user-guide/wallet-recovery.md
+      - Backing up wallet and will: user-guide/wallet-backup.md
+      - Hardware wallets: user-guide/hardware-wallets.md
+      - Compatibility: user-guide/compatibility.md
+  - Will-Executors:
+      - What they are: will-executors/what-they-are.md
+      - Choosing them in the plugin: will-executors/choosing.md
+      - The WeList directory: will-executors/welist.md
+      - Running a Will-Executor: will-executors/running-a-server.md
+  - Protocol:
+      - How it works: protocol/how-it-works.md
+  - Security & Privacy: security-privacy.md
+  - FAQ: faq.md
+
+plugins:
+  - search
+  - macros:
+      on_error_fail: true             # a typo in a variable breaks the build, not the page
+
+markdown_extensions:
+  - admonition
+  - attr_list
+  - md_in_html
+  - tables
+  - footnotes
+  - pymdownx.details
+  - pymdownx.superfences
+  - pymdownx.tabbed: { alternate_style: true }
+  - toc: { permalink: true }
+
+# --- Italian translation (not enabled yet) ------------------------------------
+# To add Italian:  pip install mkdocs-static-i18n   then uncomment:
+# plugins:
+#   - search
+#   - i18n:
+#       docs_structure: suffix          # index.md (EN) + index.it.md (IT)
+#       languages:
+#         - locale: en
+#           default: true
+#           name: English
+#         - locale: it
+#           name: Italiano
+# Create it.md siblings only for the pages you have translated; untranslated
+# pages automatically fall back to English.
+# ------------------------------------------------------------------------------
+
+# =============================================================================
+# SINGLE SOURCE OF TRUTH FOR VERSIONS
+# Change a value here and it updates everywhere in the manual.
+# Used in pages as {{ bal.plugin_version }} etc.
+# =============================================================================
+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
+    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
+  social:
+    - icon: material/web
+      link: https://bitcoin-after.life
+    - icon: material/source-repository
+      link: https://bitcoin-after.life/gitea/bitcoinafterlife
+
+copyright: Bitcoin After Life Protocol — open source, Bitcoin-only, no FIAT used.

screenshots.yml

@@ -0,0 +1,94 @@
+# Screenshot manifest — single source of truth for the images used in the manual.
+#
+# HOW TO UPDATE AN IMAGE
+#   1. Take the screenshot.
+#   2. Save it as docs/img/<file> using EXACTLY the filename below.
+#   3. Done. No Markdown edit needed — pages already point at these filenames.
+#
+# Anything still missing is auto-filled with a visible placeholder by:
+#   python3 tools/make_placeholders.py
+#
+# Recommended capture settings (keep identical across all shots):
+#   - Electrum window only (not the whole desktop), ~1280x800, 100% system zoom
+#   - Same Electrum theme for every shot (do not mix light/dark)
+#   - Dummy data only: fake heir names, round amounts, no real address or balance
+
+screenshots:
+  - file: install-electrum-plugins-menu.png
+    page: getting-started/installation.md
+    shows: "Electrum menu Tools -> Plugins, before installing BAL"
+  - file: install-from-file.png
+    page: getting-started/installation.md
+    shows: "The 'install from file' dialog with the BAL zip selected"
+  - file: install-plugin-enabled.png
+    page: getting-started/installation.md
+    shows: "Plugin list with Bitcoin After Life enabled (checkbox ticked)"
+  - file: overview-tabs.png
+    page: getting-started/installation.md
+    shows: "Electrum main window with the new HEIRS and WILL tabs visible"
+
+  - file: wizard-01-start.png
+    page: getting-started/quick-start.md
+    shows: "First screen of the guided will wizard"
+  - file: wizard-02-heirs.png
+    page: getting-started/quick-start.md
+    shows: "Wizard step: entering heir address and share"
+  - file: wizard-03-delivery-time.png
+    page: getting-started/quick-start.md
+    shows: "Wizard step: choosing the delivery date (calendar)"
+  - file: wizard-04-willexecutors.png
+    page: getting-started/quick-start.md
+    shows: "Wizard step: selecting Will-Executors, with fees visible"
+  - file: wizard-05-summary.png
+    page: getting-started/quick-start.md
+    shows: "Wizard final summary before signing"
+
+  - file: heirs-tab.png
+    page: user-guide/heirs.md
+    shows: "HEIRS tab with two heirs configured"
+  - file: heirs-new-heir.png
+    page: user-guide/heirs.md
+    shows: "New Heir dialog: name, address, amount/percentage"
+  - file: heirs-export.png
+    page: user-guide/wallet-backup.md
+    shows: "Exporting the heirs list to a printable file"
+
+  - file: settings-advanced-mode.png
+    page: user-guide/check-alive.md
+    shows: "Plugin settings with Advanced mode toggle"
+  - file: settings-check-alive.png
+    page: user-guide/check-alive.md
+    shows: "Check Alive parameter in advanced settings"
+  - file: settings-backup-transaction.png
+    page: user-guide/backup-transaction.md
+    shows: "Backup Transaction option in the plugin parameters"
+
+  - file: will-tab.png
+    page: user-guide/will-tab.md
+    shows: "WILL tab listing inheritance transactions"
+  - file: will-server-column.png
+    page: user-guide/will-tab.md
+    shows: "Close-up of the Server column with different labels"
+  - file: will-context-menu.png
+    page: user-guide/will-tab.md
+    shows: "Right-click context menu on a will transaction"
+  - file: will-details.png
+    page: user-guide/will-tab.md
+    shows: "Will-Details window with locktime, fee, heirs, executor"
+  - file: backup-transaction-save.png
+    page: user-guide/backup-transaction.md
+    shows: "Saving the offline backup transaction to a file"
+
+  - file: willexecutors-window.png
+    page: will-executors/choosing.md
+    shows: "Will-Executor service list window inside Electrum"
+  - file: willexecutors-context-menu.png
+    page: will-executors/choosing.md
+    shows: "Right-click menu on a Will-Executor row (select/edit/ping/delete)"
+  - file: welist-website.png
+    page: will-executors/welist.md
+    shows: "The public WeList leaderboard at welist.bitcoin-after.life"
+
+  - file: hardware-wallet-signing.png
+    page: user-guide/hardware-wallets.md
+    shows: "Hardware wallet confirmation prompt while signing the will"