First Release Manual BAL Plugin v0.6.1

docs/examples.md

@@ -0,0 +1,41 @@
+# REAL EXAMPLE
+
+!!! danger "Draft — needs review before publishing"
+    This page has not been checked against the plugin's actual behaviour. It
+    was written from the manual's own descriptions elsewhere, which may not
+    be complete or precise enough on their own — treat every claim below,
+    especially about costs and timing, as unverified until confirmed with
+    the developers or by testing directly. Do not treat it as authoritative
+    yet.
+
+Real-world scenarios, to make the mechanics concrete.
+
+## Inheritance across three continents, renewed for years at no cost
+
+**The setup.** Four heirs, living in three different countries. A delivery time of **5 years**, and several Will-Executors selected from the [WeList](will-executors/welist.md) for redundancy.
+
+**Cost at setup: zero.** Both fees — the miner fee and the Will-Executor fee — are only paid **once**, at the moment a Will-Executor actually broadcasts the inheritance. Setting up the will, signing it, and sending it to several servers costs nothing beyond the wallet's own normal use.
+
+**Staying current costs nothing, as long as you don't push the date later.** Ordinary use of the wallet — receiving funds, spending some, adding or editing an heir — makes the plugin rebuild the will automatically. Because this **anticipates** the delivery date by one day and redistributes it to the same Will-Executors, it is a free operation: no on-chain fee, no signature beyond the one Electrum already asks for. See [Postponing vs anticipating](user-guide/updating.md#postponing-vs-anticipating).
+
+!!! warning "One thing this does *not* do for free"
+    Bringing forward the inheritance simply brings the date forward by one day and resends it to the Will-Executors, at no cost.
+    If, on the other hand, you wish to maintain a fixed time horizon — "always 5 years from today", as explained in the [Delivery time](user-guide/delivery-time.md) section — in this case the date is postponed each time it is updated.
+    This involves postponing the date further into the future, which requires a full on-chain transaction to first invalidate the previously distributed will. This incurs a mining fee on the Bitcoin blockchain.
+
+**What this looks like over time:**
+
+- **Year 0.** The will is created: 5 years out, 4 heirs, several Will-Executors. Cost: 0.
+- **Year 1–2.** The wallet is used normally — a few incoming and outgoing transactions. Each one triggers a free refresh. The delivery date itself hasn't moved, so the horizon has quietly shrunk to 3–4 years. Cost: 0.
+- **Year 3.** Time to push the horizon back out to 5 years. This is a postponement: one small on-chain transaction to invalidate the old will before signing the new one. Cost: one miner fee, paid by the wallet owner.
+- **Onward.** Repeat every 2–3 years — see [How often to renew](user-guide/updating.md#how-often-to-renew). Each cycle also picks up newer Will-Executors that joined the network since the last renewal.
+
+The heirs are not involved in any way throughout this entire process. They simply need to keep their receiving wallet safe, or the sheets on which the seed is written (Bitcoin private keys, 12 or 24 words), which we will have taken care to give them if they do not already have a Bitcoin wallet or are not old enough to manage one.
+They do not need to know the date of the will, nor do they need to take any action: the entire mechanism operates invisibly until the day it is needed.
+Furthermore, they do not know how much in Bitcoin funds awaits them, unless we choose to tell them.
+
+---
+
+!!! question "Still have a question?"
+    The [FAQ](faq.md) answers the most common ones — costs, hardware wallets,
+    privacy, and what happens if a Will-Executor disappears.

docs/faq.md

@@ -19,7 +19,7 @@
 ??? 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.
+    - **Mining fee**, which you choose when signing. Set it generously so that the transaction is confirmed even during periods of congestion. *The plugin suggests a very high fee, which is designed to work under all blockchain conditions. We strongly advise against lowering it.*
     - **Will-Executor fee**, deducted from the inheritance at execution.
 
 ??? question "Is it hard to use?"

docs/getting-started/installation.md

@@ -31,7 +31,7 @@ BAL is an **external plugin**, so it is added from a `.zip` file:
 4. Some plugins (hardware wallets) are enabled automatically when you create or restore a hardware wallet.
 
 ![Install from file dialog](../img/install-from-file.png){ .screenshot }
-*Selecting the plugin archive.*
+*Selecting the plugin archive, and click Open.*
 
 ### First-time setup: the plugin authorization password
 
@@ -61,22 +61,22 @@ Tick **Bitcoin After Life** in the plugin list, then restart Electrum.
 
 ## 4. Check that it loaded
 
-After restarting you will see two new tabs in the Electrum window: **HEIRS** and **WILL**.
+After restarting you will see a new tab in the Electrum window: **WILL** and **BAL ICON** at the bottom right.
 
-![Electrum with the HEIRS and WILL tabs](../img/overview-tabs.png){ .screenshot }
+![Electrum with the WILL tab](../img/overview-tabs.png){ .screenshot }
-*HEIRS is where you define who inherits; WILL shows the technical state of your inheritance transactions.*
+*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)
 
 ## More on Electrum plugins
 
 For how Electrum's plugin system works in general — internal vs external plugins, the
 authorization password, and the plugin directory — see the official reference:
 [plugins.electrum.org](https://plugins.electrum.org/)
+
+---
+
+!!! question "Still have a question?"
+    The [FAQ](../faq.md) answers the most common ones — costs, hardware wallets,
+    privacy, and what happens if a Will-Executor disappears.

docs/getting-started/quick-start.md

@@ -24,18 +24,19 @@ The plugin always distributes **100%** of the wallet. If your shares don't add u
 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.*
+*You can pick a date from the calendar (BASIC mode) or express it as a relative delay (ADVANCED mode).*
 
 See [Delivery time](../user-guide/delivery-time.md) for how relative values and execution tolerance work.
 
 ## Step 4 — Select the Will-Executors
+Select- Automatically download and select willexecutor
 
 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"
+!!! info "Pick many Will-Executors, 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
@@ -47,8 +48,17 @@ Electrum then asks for your wallet password — or confirmation on your hardware
 
 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.
 
+![WILL tab after signing, with the selected Will-Executors listed](../img/wizard-06-will-list.png){ .screenshot }
+*Each row is one Will-Executor holding a copy of your inheritance.*
+
 ## 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.
+
+---
+
+!!! question "Still have a question?"
+    The [FAQ](../faq.md) answers the most common ones — costs, hardware wallets,
+    privacy, and what happens if a Will-Executor disappears.

docs/index.md

@@ -30,9 +30,12 @@ You set your heirs and a delivery date. The plugin builds a time-locked transact
 - **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).
+- **Just have a question?** → [**FAQ**](faq.md) — costs, hardware wallets, what happens if a server disappears, and more.
 
 </div>
 
+[Read the FAQ](faq.md){ .md-button .md-button--primary }
+
 !!! 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.
 

docs/protocol/how-it-works.md

@@ -21,11 +21,14 @@ Because the mempool rejects it, a time-locked transaction **cannot simply be lef
 
 ## 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.
+Each stage below has a matching label and colour in the WILL tab, shown in brackets — see
-2. **Sign.** Electrum signs with your key. The plugin never signs on your behalf.
+[The Status column](../user-guide/will-tab.md#the-status-column) for the full table.
-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.
+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. *[`New`]*{: #stage-prepare }
-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.
+2. **Sign.** Electrum signs with your key. The plugin never signs on your behalf. *[`Signed`]*{: #stage-sign }
+3. **Distribute.** Each signed transaction goes to its Will-Executor, which stores it. *[`Pushed`, then `Checked` once the server confirms it holds the copy — or `Failed` if it cannot be reached]*{: #stage-distribute }
+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. *[`Invalidated` or `Replaced` if the will no longer matches the wallet]*{: #stage-wait }
+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. *[`Pending`, then `Confirmed`]*{: #stage-execute }
 
 ## Why one transaction per Will-Executor
 
@@ -57,3 +60,9 @@ BAL optimises for **simplicity on the heir's side**: one date, one transaction,
 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).
+
+---
+
+!!! question "Still have a question?"
+    The [FAQ](../faq.md) answers the most common ones — costs, hardware wallets,
+    privacy, and what happens if a Will-Executor disappears.

docs/stylesheets/extra.css

@@ -126,7 +126,15 @@
 
 /* -------- Admonitions mapped to the site's semantic colours --------------- */
 .md-typeset .admonition,
-.md-typeset details { border-radius: 10px; font-size: .76rem; }
+.md-typeset details {
+  border-radius: 10px;
+  font-size: .76rem;
+  /* Material sets `overflow: visible` on <details>, so any child background
+     (title bar, icon, chevron) that doesn't share the container's 10px
+     radius shows through as a notch at the corners. Clipping here fixes the
+     whole class of mismatch at once, regardless of which child causes it. */
+  overflow: hidden;
+}
 
 :root {
   --md-admonition-icon--note: var(--md-admonition-icon--abstract);
@@ -159,6 +167,20 @@
 [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); }
 
+/* Admonition bodies get dense fast — give the text room to breathe. */
+.md-typeset .admonition > p,
+.md-typeset .admonition > ul,
+.md-typeset .admonition > ol { line-height: 1.65; }
+.md-typeset .admonition > p + p,
+.md-typeset .admonition > p + ul,
+.md-typeset .admonition > ul + p { margin-top: .7em; }
+.md-typeset .admonition > ul { padding-left: 1.1em; }
+.md-typeset .admonition > ul > li + li { margin-top: .35em; }
+
+/* Title: slightly larger than the body, so the box has a clear entry point. */
+.md-typeset .admonition-title { font-size: .8rem; letter-spacing: .005em; }
+
+
 /* FAQ accordions read better with a little separation. */
 .md-typeset details { margin-bottom: .5rem; }
 
@@ -247,3 +269,135 @@ img.diagram + em {
   font-style: normal;
   color: var(--md-default-fg-color--light);
 }
+
+/* -------- Status colour swatches (WILL tab table) ------------------------- */
+/* Usage in Markdown:  <span class="sw" style="--c:#8AFA6C"></span> Bright green */
+.md-typeset .sw {
+  display: inline-block;
+  width: .78em;
+  height: .78em;
+  margin-right: .45em;
+  vertical-align: -.06em;
+  border-radius: 3px;
+  background: var(--c);
+  border: 1px solid rgba(0, 0, 0, .28);
+}
+
+/* -------- WILL-tab status table ------------------------------------------- */
+/* Fixed layout with explicit column widths, so every row is one line high
+   and the rhythm stays even. */
+/* Material renders tables as `display: inline-block`, which makes the browser
+   ignore `table-layout: fixed` and auto-distribute the spare width — that is
+   what was inflating the "#" column. Force a real table box first. */
+.md-typeset .status-table table:not([class]) {
+  display: table;
+  table-layout: fixed;
+  width: 100%;
+}
+.md-typeset .status-table th:nth-child(1),
+.md-typeset .status-table td:nth-child(1) {
+  width: 1.5em;
+  text-align: left;
+  padding-left: .5em;
+  padding-right: .1em;
+  color: var(--md-default-fg-color--light);
+}
+/* Stage sits right next to the number, not a column-width away. */
+.md-typeset .status-table th:nth-child(2),
+.md-typeset .status-table td:nth-child(2) {
+  width: 7.5em;
+  padding-left: .35em;
+}
+/* Longest cell is "Azure-green #73F3C8" ≈ 12em of content. 14.5em with tight
+   padding clears it without stealing space the Meaning column needs. */
+.md-typeset .status-table th:nth-child(4),
+.md-typeset .status-table td:nth-child(4) {
+  width: 14.5em;
+  padding-left: .6em;
+  padding-right: .5em;
+}
+.md-typeset .status-table td:nth-child(2),
+.md-typeset .status-table td:nth-child(4) { white-space: nowrap; }
+.md-typeset .status-table td { vertical-align: middle; }
+.md-typeset .status-table code {
+  font-size: .8em;
+  padding: .1em .3em;
+}
+.md-typeset .status-table .sw { margin-right: .35em; }
+
+/* Below ~55em the fixed widths stop fitting; let it scroll instead of wrap. */
+@media screen and (max-width: 55em) {
+  .md-typeset .status-table { overflow-x: auto; }
+  .md-typeset .status-table table:not([class]) { min-width: 34em; }
+}
+
+/* -------- "question" admonition (end-of-page FAQ prompt, and the FAQ page
+   itself) ---------------------------------------------------------------- */
+/* Material ships a lime green (#64dd17) for this type — border, background
+   tint, the "?" icon, AND the expand/collapse chevron all use it. Realign
+   every one of those with the brand accent blue. */
+.md-typeset .admonition.question,
+.md-typeset details.question       { border-color: var(--bal-accent); }
+.md-typeset .question > .admonition-title,
+.md-typeset .question > summary    { background: var(--bal-accent-soft); }
+.md-typeset .question > .admonition-title::before,
+.md-typeset .question > summary::before { background-color: var(--bal-accent); }
+.md-typeset .question > .admonition-title::after,
+.md-typeset .question > summary::after  { color: var(--bal-accent); }
+[data-md-color-scheme="slate"] .md-typeset .question > .admonition-title,
+[data-md-color-scheme="slate"] .md-typeset .question > summary { background: rgba(45, 108, 223, .16); }
+
+/* -------- Wider navigation sidebar ---------------------------------------- */
+/* Material defaults: .md-sidebar = 12.1rem, .md-grid = 61rem.
+   The nav labels in this manual are long ("Wallet recovery use case (or wallet
+   backup)") and wrapped onto three lines. Widening the sidebar by 4rem (+33%)
+   and the grid by the same 4rem keeps the centre column at its original
+   36.8rem — the extra space comes from the unused margin on the right.
+   Only applies where the primary sidebar is actually shown. */
+@media screen and (min-width: 76.25em) {
+  .md-sidebar--primary   { width: 16.1rem; }
+  /* Same treatment for the table of contents: its longest heading
+     ("The building block: absolute time-locks") needs ~232px against the
+     158px Material allows, so it wrapped onto two lines. */
+  .md-sidebar--secondary { width: 16.7rem; }
+  /* 61rem default + 4rem (primary) + 4.6rem (secondary) — the centre column
+     keeps its original 36.8rem. */
+  .md-grid               { max-width: 69.6rem; }
+}
+
+/* -------- Sidebar left indent ---------------------------------------------- */
+/* Material's nav text sits almost flush against the browser edge (~.4rem).
+   Give the whole left sidebar some breathing room, so section titles and
+   links read as a column with a margin, not text stuck to the window edge. */
+.md-sidebar--primary .md-sidebar__inner {
+  padding-left: 1rem;
+}
+
+/* -------- Sidebar hierarchy: section titles vs. their pages ---------------- */
+/* On desktop Material gives every .md-nav__link inside the primary sidebar
+   the same left padding (.6rem .8rem), regardless of nesting — its per-level
+   indent rules only exist for the mobile/merged nav. That makes section
+   titles ("User guide") and the pages under them ("Heirs and shares") sit at
+   the same x position, with no visual hierarchy. Nudge just the pages right. */
+.md-nav--primary .md-nav__item--nested > .md-nav .md-nav__link {
+  padding-left: 1.175rem; /* Material's default .8rem + 6px */
+}
+
+
+/* -------- Let the widened sidebar actually be used ------------------------ */
+/* Material pins the nav's text column to 11.5rem via
+   `padding-right: calc(100% - 11.5rem)` (inside an @supports block for
+   webkit scrollbars), leaving the rest as dead padding. Because we widened
+   .md-sidebar--primary to 16.1rem, all 4 extra rem went into that padding —
+   the labels kept wrapping next to visibly empty space. Re-derive it from
+   the new width, keeping Material's ~.6rem scrollbar gutter. */
+@media screen and (min-width: 76.25em) {
+  [dir="ltr"] .md-sidebar--primary .md-sidebar__inner {
+    padding-right: calc(100% - 15.5rem);
+  }
+  /* The clamp applies to both sidebars, so the table of contents needs the
+     same treatment against its own 16.7rem width. */
+  [dir="ltr"] .md-sidebar--secondary .md-sidebar__inner {
+    padding-right: calc(100% - 16.1rem);
+  }
+}

docs/user-guide/backup-transaction.md

@@ -23,4 +23,13 @@ Relying on the offline backup alone has real drawbacks:
 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.
+    The recommended setup: 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.
+
+!!! warning "Digital media ages badly"
+    Check the file periodically and re-save it to fresh media — USB sticks, SD cards, and similar storage degrade over time and can silently fail.
+
+---
+
+!!! question "Still have a question?"
+    The [FAQ](../faq.md) answers the most common ones — costs, hardware wallets,
+    privacy, and what happens if a Will-Executor disappears.

docs/user-guide/compatibility.md

@@ -18,7 +18,7 @@ The plugin follows Electrum closely; each release states the Electrum version it
 
 | Plugin release | Tested with |
 |---|---|
-| v{{ bal.plugin_version }} | Electrum {{ bal.electrum_tested }} (manual verified on {{ bal.electrum_latest }}) |
+| v{{ bal.plugin_version }} | Electrum {{ bal.electrum_tested }} |
 | 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 |

docs/user-guide/heirs.md

@@ -41,4 +41,10 @@ The rule to remember: **if your shares don't add up to 100%, the plugin scales t
 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.
+    Staggered inheritance — distributing gradually over time, for example 10% per year — is in development for version 2 of the protocol. You'll be able to update your inheritance later with these new features as they become available.
+
+---
+
+!!! question "Still have a question?"
+    The [FAQ](../faq.md) answers the most common ones — costs, hardware wallets,
+    privacy, and what happens if a Will-Executor disappears.

docs/user-guide/wallet-recovery.md

@@ -1,4 +1,4 @@
-# Using BAL as a wallet recovery net
+# Using BAL as a wallet recovery net (or wallet backup)
 
 Inheritance is not the only use for a time-locked transaction. The same mechanism gives you a **decentralized safety net against losing your seed**.
 

docs/user-guide/will-tab.md

@@ -12,12 +12,48 @@ The **WILL** tab is the technical view of your inheritance: one row per inherita
 | **Locktime** | The delivery date of the inheritance |
 | **Txid** | Identifier of the Bitcoin transaction |
 | **Will-Executor** | Which server holds this copy |
+| **Status** | How far the transaction has progressed (see below) |
 | **Server** | Whether that server actually has it (see below) |
-| **Status** | Progress of the transaction itself |
+
+The two rightmost columns answer different questions. **Status** describes the life of the
+transaction itself; **Server** describes only whether one particular Will-Executor is holding
+its copy.
+
+## The Status column
+
+Status is **cumulative**: it keeps the whole history, joining each stage with a dot. A freshly
+signed will that has not been sent yet reads `New.Signed`, while one stored and verified on a
+server reads `New.Signed.Pushed.Checked`.
+
+The **row's background colour** shows the latest stage reached, so you can read the state of
+every will at a glance without parsing the text. Each stage name below links to the point in
+[How the protocol works](../protocol/how-it-works.md#the-lifecycle) where that step happens.
+
+<div class="status-table" markdown>
+
+| # | Stage | Meaning | Colour |
+|---|---|---|---|
+| 1 | [**New**](../protocol/how-it-works.md#stage-prepare) | Created, not yet signed | <span class="sw" style="--c:#FFFFFF"></span> White `#FFFFFF` |
+| 2 | [**Signed**](../protocol/how-it-works.md#stage-sign) | Signed in the wallet | <span class="sw" style="--c:#2BC8ED"></span> Azure `#2BC8ED` |
+| 3 | [**Pushed**](../protocol/how-it-works.md#stage-distribute) | Sent to the Will-Executor | <span class="sw" style="--c:#73F3C8"></span> Azure-green `#73F3C8` |
+| 4 | [**Checked**](../protocol/how-it-works.md#stage-distribute) | Verified on the server | <span class="sw" style="--c:#8AFA6C"></span> Bright green `#8AFA6C` |
+| 5 | [**Confirmed**](../protocol/how-it-works.md#stage-execute) | Confirmed on-chain | <span class="sw" style="--c:#BFBFBF"></span> Grey `#BFBFBF` |
+| 6 | [**Pending**](../protocol/how-it-works.md#stage-execute) | Awaiting confirmation | <span class="sw" style="--c:#FFCE30"></span> Yellow `#FFCE30` |
+| 7 | [**Failed**](../protocol/how-it-works.md#stage-distribute) | Server could not be reached | <span class="sw" style="--c:#E83845"></span> Red `#E83845` |
+| 8 | [**Invalidated**](../protocol/how-it-works.md#what-invalidates-a-will) | An input UTXO was spent | <span class="sw" style="--c:#F87838"></span> Orange `#F87838` |
+| 9 | [**Replaced**](../protocol/how-it-works.md#what-invalidates-a-will) | Superseded by a newer will | <span class="sw" style="--c:#FF97E9"></span> Violet `#FF97E9` |
+
+</div>
+
+!!! tip "The three colours you want to see"
+    In normal operation a will sits at **Checked** (bright green) until the delivery date, then
+    moves to **Pending** (yellow) and finally **Confirmed** (grey). **Failed** (red) means a server
+    is unreachable; **Invalidated** (orange) means the will no longer matches your wallet and must
+    be rebuilt — see [Keeping the will up to date](updating.md).
 
 ## The Server column
 
-The Server column tells you, independently of the row colour, whether each inheritance transaction is really stored on its Will-Executor.
+The Server column tells you, independently of the row colour, whether each inheritance transaction is really stored on its Will-Executor. It is a plain textual label — no colour coding.
 
 ![Server column](../img/will-server-column.png){ .screenshot }
 *The Server column reports storage state per Will-Executor.*
@@ -55,3 +91,9 @@ The Server column tells you, independently of the row colour, whether each inher
 *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.
+
+---
+
+!!! question "Still have a question?"
+    The [FAQ](../faq.md) answers the most common ones — costs, hardware wallets,
+    privacy, and what happens if a Will-Executor disappears.

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

@@ -23,11 +23,6 @@ This page covers setting up your own Will-Executor node. If you are wondering *w
 See the [architecture diagram](../protocol/how-it-works.md#architecture-at-a-glance) for how
 `bal-server` and `bal-pusher` fit into the full flow from plugin to Bitcoin node.
 
-## Architecture at a glance
-
-![BAL architecture: plugin, Will-Executor, Bitcoin Core](../img/architecture.svg){ .diagram }
-*How a will travels from the Electrum plugin to the Bitcoin network. Click to enlarge.*
-
 ## The two components
 
 | Component | Role |
@@ -133,3 +128,9 @@ The request/response interface used by the plugin is documented in [`RPC.md`](ht
 ## 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)**
+
+---
+
+!!! question "Still have a question?"
+    The [FAQ](../faq.md) answers the most common ones — costs, hardware wallets,
+    privacy, and what happens if a Will-Executor disappears.

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

@@ -46,3 +46,9 @@ This is why renewing your will periodically is useful: it brings newer Will-Exec
 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).
+
+---
+
+!!! question "Still have a question?"
+    The [FAQ](../faq.md) answers the most common ones — costs, hardware wallets,
+    privacy, and what happens if a Will-Executor disappears.

internal/screenshot-checklist.md

@@ -16,27 +16,112 @@ 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.
+  - Windows: ++win+shift+s++ (Snipping Tool) or use `grim -g "$(slurp)" shot.png` if you prefer
-- **~1280×800**, system zoom at 100%.
+  - macOS: ++cmd+shift+4++ then ++space++ to capture a window
-- **One theme** for the entire manual — never mix light and dark shots.
+  - Linux: `gnome-screenshot -w` or `import -window root shot.png` (ImageMagick)
-- **PNG** format.
+- **1280×720** at system zoom 100%** — this matches Electrum's typical window size when maximized on a laptop.
+- **Light theme** (default Electrum) for consistency. Never mix light and dark.
+- **PNG** format, no JPEG.
+- **Crop tightly** to the Electrum window; include title bar and the relevant tab/dialog.
+
+## Setting up the test wallet
+
+Use **testnet** (not mainnet) so no real Bitcoin is at risk. In Electrum:
+1. Create → New wallet
+2. Name: `Screenshot_Test` or similar (will show in the title bar)
+3. Standard wallet → Create new seed
+4. Write down the seed (you'll need to restore it later)
+5. Set a simple password like `test` (will be shown in password dialogs)
+6. In Electrum's Network tab, switch to testnet servers
+
+Get testnet Bitcoin from a faucet (e.g. testnet-faucet.mempool.space) to populate the wallet so screenshots show real-looking balances.
 
 ## 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.
+- Use the **dedicated testnet wallet** set up above.
-- **Fake heir names** (Jonny, Andrea — as in the original manual).
+- **Fake heir names** (Jonny, Andrea, Emma — as in the original manual).
-- **Round, obviously fake amounts.**
+- **Round, obviously fake amounts** (0.05 BTC, 0.1 BTC, never suspicious multiples like 0.0314 BTC).
-- **No real Bitcoin address** that belongs to you or anyone you know.
+- **No real Bitcoin address** that belongs to you or anyone you know — use generated testnet addresses or Bitcoin StackExchange examples.
-- Check the window title bar, the status bar, and any visible file paths — they often
+- **Obfuscate file paths**: the title bar will show your wallet filename. Use a generic name like `Screenshot_Test`, not `MyWallet_MainAccount`.
-  contain a username or a real wallet filename.
+- Check the window title bar, the status bar, tooltips, and any dialogs — they often contain a username or a real wallet filename. Crop or blur them if necessary.
 
 ## 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.
 
+## The 24 screenshots — what to capture
+
+All are from the **HEIRS and WILL tabs** or the **startup wizard**. Placeholder images already exist in `docs/img/`; replace them with real shots.
+
+### Installation & setup (6 images)
+
+| File | Where | What to show |
+|---|---|---|
+| `install-electrum-plugins-menu.png` | Electrum → Tools → Plugins | The "Plugins" dialog with built-in plugins listed. Show the internal plugins, and note the "Add" button for external plugins. |
+| `install-from-file.png` | Electrum → Tools → Plugins → Add | File selector dialog, pointing to the BAL `.zip` file. |
+| `install-plugin-enabled.png` | Electrum → Tools → Plugins | Plugin list with "Bitcoin After Life" checked/enabled. |
+| `overview-tabs.png` | Electrum main window | The Electrum window with HEIRS and WILL tabs visible. Show the tab bar clearly. |
+| `hardware-wallet-signing.png` | During signing on a hardware wallet | A hardware wallet confirmation screen (Ledger, Trezor, etc.) asking the user to confirm. If you don't have one, skip and update the manual to note it's optional. |
+| `welist-website.png` | https://welist.bitcoin-after.life/ | The WeList website showing available Will-Executors and their fees. |
+
+### Wizard — 5 steps (5 images)
+
+Start the wizard from **HEIRS → Add new heir → (wizard opens)**.
+
+| File | Wizard step | What to show |
+|---|---|---|
+| `wizard-01-start.png` | Welcome screen | The first wizard dialog with the title and brief explanation. |
+| `wizard-02-heirs.png` | Add heirs | A few heir rows filled in: e.g., Jonny (50%), Andrea (50%), with Bitcoin addresses. |
+| `wizard-03-delivery-time.png` | Delivery date | The date/time picker. Show either the calendar view or the Raw input field. |
+| `wizard-04-willexecutors.png` | Select Will-Executors | The list of available Will-Executors from WeList with checkboxes, fees visible. Check a few (e.g., 3–4 servers). |
+| `wizard-05-summary.png` | Review & sign | The final summary showing all choices: heirs, date, servers, total fee. |
+
+### HEIRS tab (3 images)
+
+| File | What to show |
+|---|---|
+| `heirs-tab.png` | The HEIRS tab overview with a list of added heirs (if any). |
+| `heirs-new-heir.png` | The "Add new heir" button or dialog. |
+| `heirs-export.png` | The export dialog/list (if available in the plugin UI). |
+
+### WILL tab (3 images)
+
+| File | What to show |
+|---|---|
+| `will-tab.png` | The WILL tab with one or more inheritance transactions listed. Show the columns and status. |
+| `will-server-column.png` | Zoom in on the "Server" column showing the 5 textual states (OK, pending, awaiting first broadcast, unknown, overdue). |
+| `will-context-menu.png` | Right-click on a will entry to show the context menu (e.g., "View details", "Copy fee address", etc.). |
+| `will-details.png` | The details dialog for a single will, showing transaction data, date, servers, status. |
+
+### Backup & signing (3 images)
+
+| File | Where | What to show |
+|---|---|---|
+| `backup-transaction-save.png` | WILL tab → right-click → Backup transaction | File save dialog, showing the default `.psbt` filename. |
+| `settings-*.png` (general, auth, advanced) | HEIRS or WILL tab settings | Plugin settings dialogs (if they exist in the UI). Capture the "General", "Authentication", and "Advanced" tabs or panels. |
+
+### Check Alive (advanced mode) (1 image)
+
+| File | Where | What to show |
+|---|---|---|
+| `check-alive-prompt.png` | Opening the wallet after Check Alive triggers | The dialog asking the user to refresh the will. |
+
+---
+
+## Workflow to capture all 24
+
+1. **Set up testnet wallet** (see "Setting up the test wallet" above).
+2. **Install BAL plugin** in your Electrum instance.
+3. **Go through the wizard** once to understand the flow, then capture each step.
+4. **Create a few test wills** (different dates, different heir counts) so you have variety for the WILL tab screenshots.
+5. **Capture the HEIRS tab** at various states (empty, with heirs, export dialog).
+6. **Capture the WILL tab** at various states (wills in different states, details dialog, context menus).
+7. **Save each** as `docs/img/<filename>` using the names from the table above.
+8. **Run** `python3 tools/make_placeholders.py --list` to verify all 24 are found (should show 0 missing).
+
 ## Adding a new image
 
 1. Add an entry to `screenshots.yml` (`file`, `page`, `shows`).

internal/source-notes.md

@@ -21,7 +21,7 @@ Compiled July 2026. Keep this updated whenever the manual is revised.
 | "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 |
+| ~~9-state colour table for transaction status~~ | **Still correct — this was my error.** Verified 2026-07-27 by sampling pixels from `will-tab.png` (v0.6.1): `#2BC8ED` Signed and `#8AFA6C` Checked match the PDF exactly. Status (9 colour-coded stages, cumulative, dot-joined) and Server (5 textual labels) are **two different columns** that coexist. The PDF documents only Status because Server is newer. |
 | 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 |
@@ -31,11 +31,12 @@ Compiled July 2026. Keep this updated whenever the manual is revised.
 | Date | plugin_version | electrum_latest | Note |
 |---|---|---|---|
 | 2026-07 (initial) | 0.2.6 | 4.7.2 | Last version explicitly documented in a release ("tested with electrum 4.7.1") |
-| 2026-07-26 | 0.6.1 | 4.8.0 | Jump from 0.2.6 → 0.6.1: releases v0.5.18/v0.6.0/v0.6.1 mostly cover Tor/onion will-executor support. **`electrum_tested` left at 4.7.1 — unconfirmed for 0.6.1**, neither release's notes state an Electrum version. Verify with svatantrya before the next public update. |
+| 2026-07-26 | 0.6.1 | 4.8.0 | Jump from 0.2.6 → 0.6.1: releases v0.5.18/v0.6.0/v0.6.1 mostly cover Tor/onion will-executor support. |
+| 2026-07-27 | 0.6.1 | 4.8.0 | Confirmed: v0.6.1 tested against Electrum 4.8.0. `electrum_tested` updated from 4.7.1 → 4.8.0; the compatibility table row simplified to a single Electrum version. |
 
 ## To verify with the developers before the next revision
 
-0. **Electrum version actually tested for plugin v0.6.1** (see table above) — highest priority, since it's a user-facing compatibility claim.
+0. ~~Electrum version actually tested for plugin v0.6.1~~ — confirmed 2026-07-27: Electrum 4.8.0.
 0b. ~~Architecture diagram version label mismatch~~ — fixed 2026-07-26: `docs/img/architecture.svg`
    now reads "Python · v0.6.1", matching `plugin_version`. Still worth asking the diagram's source
    (likely a design tool, not this repo) to drop the hardcoded version label so it doesn't need a
@@ -51,6 +52,12 @@ Compiled July 2026. Keep this updated whenever the manual is revised.
 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.
+8. **`docs/examples.md` (new, 2026-07-28) — needs a full accuracy pass.** Written from
+   `updating.md`/`delivery-time.md` rather than tested behaviour; user flagged it as containing
+   "parecchie imprecisioni" without specifying which. Marked with a draft warning on the page
+   itself. Re-check in particular: whether ordinary balance/heir changes really re-anticipate for
+   free every time (vs. some limit or condition), and whether postponing to hold a rolling 5-year
+   horizon really costs only "a small miner fee" as stated.
 
 ## Deliberately left out of the published manual
 

mkdocs.yml

@@ -35,10 +35,13 @@ theme:
     - content.code.copy
 
 extra_css:
-  - stylesheets/extra.css
+  # The ?v= suffix defeats browser caching of the stylesheet. Bump the number
+  # whenever you change extra.css and the browser keeps showing the old style.
+  - stylesheets/extra.css?v=13
 
 nav:
   - Home: index.md
+  - FAQ: faq.md
   - Getting started:
       - Installation: getting-started/installation.md
       - Create your first will: getting-started/quick-start.md
@@ -49,7 +52,7 @@ nav:
       - 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
+      - Wallet recovery use case (or wallet backup): 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
@@ -60,8 +63,8 @@ nav:
       - Running a Will-Executor: will-executors/running-a-server.md
   - Protocol:
       - How it works: protocol/how-it-works.md
+  - REAL EXAMPLE: examples.md
   - Security & Privacy: security-privacy.md
-  - FAQ: faq.md
 
 plugins:
   - search
@@ -110,7 +113,7 @@ markdown_extensions:
 extra:
   bal:
     plugin_version: "0.6.1"           # latest plugin release
-    electrum_tested: "4.7.1"          # UNCONFIRMED for v0.6.1 — see internal/source-notes.md
+    electrum_tested: "4.8.0"          # Electrum version v0.6.1 was tested against
     electrum_latest: "4.8.0"          # latest stable Electrum the manual assumes
     welist_fee_sats: "50,000"         # WeList yearly listing fee
     welist_period_days: "365"
@@ -121,4 +124,4 @@ extra:
     - icon: material/source-repository
       link: https://bitcoin-after.life/gitea/bitcoinafterlife
 
-copyright: Bitcoin After Life Protocol — open source, Bitcoin-only, no FIAT used.
+copyright: Bitcoin After Life Protocol — open source. The whole project is built to run on Bitcoin only, with no fiat currency involved anywhere in its design.

screenshots.yml

@@ -42,6 +42,9 @@ screenshots:
   - file: wizard-05-summary.png
     page: getting-started/quick-start.md
     shows: "Wizard final summary before signing"
+  - file: wizard-06-will-list.png
+    page: getting-started/quick-start.md
+    shows: "WILL tab right after signing, listing the selected Will-Executors and their stored status"
 
   - file: heirs-tab.png
     page: user-guide/heirs.md