docs: add DUST section to inheritance-options (v0.4.7) and translate agent memory to English

- inheritance-options.md/.html: new section 4.8 explaining the dust limit
  (some-dust continues vs all-dust blocks), dust quick-reference row,
  golden rule #5, and footer bumped to v0.4.7 referencing core/heirs.py.
- .agent_memory_tasks.md: translated remaining Italian user-quote lines
  to English (Point B2 = replace, English only, no Italian originals kept).
- Verified: no Italian text remains in any repo doc; md/html mirrors in sync.

.agent_memory_tasks.md

@@ -1,129 +1,129 @@
 
-## TASK A (proposto, NON ancora avviato) — Migliorare il messaggio "WILL EXPIRED"
+## TASK A (proposed, NOT yet started) — Improve the "WILL EXPIRED" message
 
-**Origine:** osservato dall'utente negli screenshot del 23/06/2026 (will scaduto -> percorso invalidate + re-sign). La LOGICA è corretta; si migliora solo la UX/chiarezza del messaggio.
+**Origin:** observed by the user in the screenshots of 2026-06-23 (expired will -> invalidate + re-sign path). The LOGIC is correct; only the UX/clarity of the message is improved.
 
-**3 miglioramenti approvati dall'utente (da implementare poi, in inglese, regole R1-R4 + zip-first):**
+**3 improvements approved by the user (to implement later, in English, rules R1-R4 + zip-first):**
-1. Tradurre il timestamp Unix grezzo (es. 1782118800) in data leggibile.
+1. Translate the raw Unix timestamp (e.g. 1782118800) into a readable date.
-   Esempio: invece di "Will Expired 9f1b0a75...: 1782118800"
+   Example: instead of "Will Expired 9f1b0a75...: 1782118800"
-   mostrare "Will expired (locktime 2026-06-22 11:00 UTC) - too late to anticipate, will invalidate and re-sign".
+   show "Will expired (locktime 2026-06-22 11:00 UTC) - too late to anticipate, will invalidate and re-sign".
-2. Rendere il messaggio INFORMATIVO e non un ERRORE: il rosso sembra un errore,
+2. Make the message INFORMATIVE and not an ERROR: red looks like an error,
-   ma e' un flusso normale. Usare colore di avviso (arancione) o aggiungere frase
+   but it is a normal flow. Use a warning colour (orange) or add a sentence
-   tipo "This is expected: the will is past its locktime, switching to invalidate + re-sign."
+   like "This is expected: the will is past its locktime, switching to invalidate + re-sign."
-3. Accorciare l'hash del will per leggibilita' (es. primi 8 + ultimi 4 caratteri).
+3. Shorten the will hash for readability (e.g. first 8 + last 4 characters).
 
-**Note tecniche da fare in DISCOVER quando si avvia:**
+**Technical notes to handle in DISCOVER when starting:**
-- Trovare il punto del codice che genera la stringa "Will Expired ... <timestamp>" (probabilmente nel wizard "Building Will").
+- Find the code point that builds the "Will Expired ... <timestamp>" string (probably in the "Building Will" wizard).
-- Verificare se il colore rosso e' impostato li' (rich text / stylesheet).
+- Check whether the red colour is set there (rich text / stylesheet).
-- Seguire METHOD: DISCOVER -> PLAN (attendere OK) -> EXECUTE -> VERIFY -> ZIP-first -> commit/PR/release solo dopo conferma.
+- Follow METHOD: DISCOVER -> PLAN (wait for OK) -> EXECUTE -> VERIFY -> ZIP-first -> commit/PR/release only after confirmation.
 
-## TASK B (proposto, NON ancora avviato) — Etichette descrizione transazioni in Cronologia
+## TASK B (proposed, NOT yet started) — Transaction description labels in History
 
-**Origine:** osservato dall'utente nello screenshot Cronologia del 23/06/2026.
+**Origin:** observed by the user in the History screenshot of 2026-06-23.
-Nella tab "Cronologia" di Electrum (transazioni on-chain), il plugin BAL scrive
+In Electrum's "History" tab (on-chain transactions) the BAL plugin writes
-una descrizione colorata nella colonna "Descrizione".
+a coloured description in the "Description" column.
 
-**Stato attuale:**
+**Current state:**
-- La transazione di EREDITA' e' etichettata "BAL Transaction" (colore rosso).
+- The INHERITANCE transaction is labelled "BAL Transaction" (red colour).
-- La transazione di INVALIDATE NON ha alcuna descrizione.
+- The INVALIDATE transaction has NO description.
 
-**Modifiche richieste (approvate dall'utente):**
+**Requested changes (approved by the user):**
-1. RINOMINARE l'etichetta dell'eredita': "BAL Transaction" -> "BAL Inheritance transaction".
+1. RENAME the inheritance label: "BAL Transaction" -> "BAL Inheritance transaction".
-2. CAMBIARE il colore dell'etichetta eredita' da ROSSO a VERDE.
+2. CHANGE the inheritance label colour from RED to GREEN.
-3. AGGIUNGERE una nuova etichetta per le transazioni di invalidate:
+3. ADD a new label for the invalidate transactions:
-   "BAL Invalidate transaction" in colore ARANCIONE (oggi compaiono senza descrizione).
+   "BAL Invalidate transaction" in ORANGE (today they appear with no description).
 
-**Riepilogo finale desiderato:**
+**Desired final summary:**
-| Transazione | Etichetta desiderata        | Colore    |
+| Transaction | Desired label               | Colour |
-|-------------|-----------------------------|-----------|
+|-------------|-----------------------------|--------|
-| Eredita'    | BAL Inheritance transaction | VERDE     |
+| Inheritance | BAL Inheritance transaction | GREEN  |
-| Invalidate  | BAL Invalidate transaction  | ARANCIONE |
+| Invalidate  | BAL Invalidate transaction  | ORANGE |
 
-**Note tecniche da fare in DISCOVER quando si avvia:**
+**Technical notes to handle in DISCOVER when starting:**
-- Trovare nel codice dove viene impostata l'etichetta "BAL Transaction"
+- Find in the code where the "BAL Transaction" label is set
-  (probabilmente wallet.set_label(txid, ...) o simile) e dove/come e' impostato il colore.
+  (probably wallet.set_label(txid, ...) or similar) and where/how the colour is set.
-- Capire come il plugin distingue una tx di eredita' da una di invalidate, per
+- Understand how the plugin distinguishes an inheritance tx from an invalidate tx, so
-  applicare l'etichetta corretta a ciascuna. La tx di invalidate oggi NON riceve
+  the correct label is applied to each. The invalidate tx today gets NO
-  label -> trovare il punto dove viene creata/broadcastata e aggiungere lì set_label.
+  label -> find where it is created/broadcast and add set_label there.
-- Verificare se il colore (rosso) e' gestito da Electrum o dal plugin, e come
+- Check whether the (red) colour is handled by Electrum or by the plugin, and how
-  impostare il verde per l'eredita'.
+  to set green for the inheritance.
-- Seguire METHOD: DISCOVER -> PLAN (attendere OK) -> EXECUTE -> VERIFY -> ZIP-first -> commit/PR/release solo dopo conferma.
+- Follow METHOD: DISCOVER -> PLAN (wait for OK) -> EXECUTE -> VERIFY -> ZIP-first -> commit/PR/release only after confirmation.
 
-## TASK C (proposto, NON ancora avviato) — Checkbox "no will-executor" anche in Plugin Settings
+## TASK C (proposed, NOT yet started) — "no will-executor" checkbox also in Plugin Settings
 
-**Origine:** richiesta utore del 23/06/2026.
+**Origin:** user request of 2026-06-23.
-Nel wizard "Create your WILL", finestra di download will-executor, esiste il checkbox
+In the "Create your WILL" wizard, will-executor download window, there is the checkbox
-"Add transactions without willexecutor". L'utente vuole lo STESSO checkbox anche nella
+"Add transactions without willexecutor". The user wants the SAME checkbox also in the
-finestra "Plugin settings" (stesso stile delle altre righe), default ON, con un
+"Plugin settings" window (same style as the other rows), default ON, with a
-HelpButton che spiega la funzione.
+HelpButton explaining the function.
 
-**Testo del tastino di aiuto (fornito dall'utente, da usare verbatim):**
+**Help-button text (provided by the user, to be used verbatim):**
 "Create a will that does not require a Will-executor; it can be saved, for example,
 on a USB stick, and a copy can be given to the heirs."
 
-**SCOPERTA IMPORTANTE (DISCOVER gia' fatto):**
+**IMPORTANT FINDING (DISCOVER already done):**
-- La config ESISTE GIA': `self.NO_WILLEXECUTOR = BalConfig(config, "bal_no_willexecutor", True)`
+- The config ALREADY EXISTS: `self.NO_WILLEXECUTOR = BalConfig(config, "bal_no_willexecutor", True)`
-  in `bal/core/plugin_base.py:193` (default True = ON). Quindi NON va creata.
+  in `bal/core/plugin_base.py:193` (default True = ON). So it must NOT be created.
-- Il checkbox del wizard e' in `bal/gui/qt/lists.py:916-918`:
+- The wizard checkbox is in `bal/gui/qt/lists.py:916-918`:
     hbox.addWidget(QLabel(_("Add transactions without willexecutor")))
     heir_no_willexecutor = BalCheckBox(self.bal_plugin.NO_WILLEXECUTOR)
-  -> usa BalCheckBox legato alla stessa config. Aggiungendo lo stesso checkbox nelle
+  -> uses BalCheckBox bound to the same config. Adding the same checkbox in the
-     settings, i due rimangono sincronizzati automaticamente (stessa BalConfig).
+     settings keeps the two automatically in sync (same BalConfig).
-- La finestra Settings e' `settings_dialog()` in `bal/gui/qt/plugin.py:372`.
+- The Settings window is `settings_dialog()` in `bal/gui/qt/plugin.py:372`.
-  Usa una griglia con la helper `add_widget(grid, label, widget, row, help_)`
+  It uses a grid with the helper `add_widget(grid, label, widget, row, help_)`
-  (definita in `bal/gui/qt/common.py:98`) che mette: QLabel(col0), widget(col1),
+  (defined in `bal/gui/qt/common.py:98`) which places: QLabel(col0), widget(col1),
-  HelpButton(col2). Le righe attuali vanno 1..8 (8 = bottone Rebroadcast).
+  HelpButton(col2). Current rows go 1..8 (8 = Rebroadcast button).
-- Esiste gia' codice COMMENTATO che faceva esattamente questo (plugin.py:382 e
+- There is ALREADY COMMENTED-OUT code that did exactly this (plugin.py:382 and
-  536-542): `# heir_no_willexecutor = BalCheckBox(self.NO_WILLEXECUTOR)` e un
+  536-542): `# heir_no_willexecutor = BalCheckBox(self.NO_WILLEXECUTOR)` and an
-  add_widget "Backup Transaction" -> si puo' riattivare/adattare.
+  add_widget "Backup Transaction" -> it can be re-enabled/adapted.
-- C'e' anche un blocco "Reset setting" (on_reset_defaults, plugin.py:560-596) con
+- There is also a "Reset setting" block (on_reset_defaults, plugin.py:560-596) with
-  una lista `resets = [...]`: per coerenza la nuova checkbox va AGGIUNTA a quella
+  a `resets = [...]` list: for consistency the new checkbox must be ADDED to that
-  lista cosi' il Reset la riporta al default (ON).
+  list so Reset returns it to the default (ON).
 
-**PLAN bozza (da rifinire e far approvare quando si avvia):**
+**Draft PLAN (to refine and get approved when starting):**
-1. In `settings_dialog()`: creare `heir_no_willexecutor = BalCheckBox(self.NO_WILLEXECUTOR)`.
+1. In `settings_dialog()`: create `heir_no_willexecutor = BalCheckBox(self.NO_WILLEXECUTOR)`.
-2. Aggiungere una riga con `add_widget(grid, "<label>", heir_no_willexecutor, <row>, "<help text utente>")`.
+2. Add a row with `add_widget(grid, "<label>", heir_no_willexecutor, <row>, "<user help text>")`.
-   - Decidere label breve (es. "No will-executor" / "Backup will (no will-executor)") -> CHIEDERE ALL'UTENTE quale label preferisce nella colonna sinistra.
+   - Decide a short label (e.g. "No will-executor" / "Backup will (no will-executor)") -> ASK THE USER which label they prefer in the left column.
-   - Decidere la riga: inserire prima del Rebroadcast (riga 8), eventualmente rinumerando le righe successive.
+   - Decide the row: insert before Rebroadcast (row 8), renumbering the following rows if needed.
-3. Aggiungere `(self.NO_WILLEXECUTOR, heir_no_willexecutor, "check")` alla lista `resets`
+3. Add `(self.NO_WILLEXECUTOR, heir_no_willexecutor, "check")` to the `resets` list
-   in on_reset_defaults, cosi' il "Reset setting" la riporta a ON.
+   in on_reset_defaults, so "Reset setting" returns it to ON.
-4. Mantenere lo stile esistente (HelpButton, griglia). Default gia' ON via config.
+4. Keep the existing style (HelpButton, grid). Default already ON via config.
 
-**DOMANDA DA PORRE PRIMA DI EXECUTE:** quale etichetta breve mostrare nella colonna
+**QUESTION TO ASK BEFORE EXECUTE:** which short label to show in the left column
-sinistra delle settings? (l'utente ha fornito solo il testo del tastino di aiuto).
+of the settings? (the user only provided the help-button text).
 
-- Seguire METHOD: DISCOVER(fatto) -> PLAN (attendere OK) -> EXECUTE -> VERIFY -> ZIP-first -> commit/PR/release solo dopo conferma.
+- Follow METHOD: DISCOVER(done) -> PLAN (wait for OK) -> EXECUTE -> VERIFY -> ZIP-first -> commit/PR/release only after confirmation.
 
-## TASK D (proposto, NON ancora avviato) — Rinominare il tastone del wizard
+## TASK D (proposed, NOT yet started) — Rename the wizard button
 
-**Origine:** richiesta utente del 23/06/2026.
+**Origin:** user request of 2026-06-23.
-Il tastone grande che apre il wizard mostra "Create your will" e l'utente vuole
+The big button that opens the wizard shows "Create your will" and the user wants
-cambiarlo in "Build your will" (aveva scritto "BUIL YOUR WILL" -> refuso per BUILD).
+to change it to "Build your will" (they wrote "BUIL YOUR WILL" -> typo for BUILD).
 
-**SCOPERTA (DISCOVER gia' fatto):**
+**FINDING (DISCOVER already done):**
-- Il bottone e' in `bal/gui/qt/lists.py:473`:
+- The button is in `bal/gui/qt/lists.py:473`:
     wizard = QPushButton("  " + _("Create your will"))
-- INCOERENZA esistente: il tooltip dello STESSO bottone (lists.py:483) dice gia'
+- EXISTING INCONSISTENCY: the tooltip of the SAME button (lists.py:483) already says
     wizard.setToolTip(_("Wizard - Build your will"))
-  e tutti i commenti del codice (8 occorrenze) chiamano il wizard "Build your will".
+  and all the code comments (8 occurrences) call the wizard "Build your will".
-  Quindi cambiare il testo del bottone in "Build your will" UNIFORMA tutto.
+  So changing the button text to "Build your will" UNIFIES everything.
 
-**PARERE AGENTE (concordato con l'utente):** "Build your will" e' la scelta migliore
+**AGENT OPINION (agreed with the user):** "Build your will" is the better choice
-(coerenza con tooltip/commenti/config; "Build" comunica meglio il processo guidato a step).
+(consistent with tooltip/comments/config; "Build" better conveys the step-by-step guided process).
 
-**FORMA SCELTA DALL'UTENTE:** "Build Your Will" (title case).
+**FORM CHOSEN BY THE USER:** "Build Your Will" (title case).
 
-**PLAN bozza:** sostituire la sola stringa "Create your will" -> "Build Your Will"
+**Draft PLAN:** replace only the string "Create your will" -> "Build Your Will"
-(title case) in `lists.py:473`. Verificare che non ci siano altre occorrenze del
+(title case) in `lists.py:473`. Check there are no other occurrences of the
-testo del bottone da allineare. Lasciare invariato il tooltip (gia' "Build your will").
+button text to align. Leave the tooltip unchanged (already "Build your will").
 
-- Seguire METHOD: DISCOVER(fatto) -> PLAN (attendere OK) -> EXECUTE -> VERIFY -> ZIP-first -> commit/PR/release solo dopo conferma.
+- Follow METHOD: DISCOVER(done) -> PLAN (wait for OK) -> EXECUTE -> VERIFY -> ZIP-first -> commit/PR/release only after confirmation.
 
 ================================================================
 ## PENDING TASK (post-v0.3.9) — UNIFY INVALIDATE PROCEDURE — NOT STARTED
 ## Status: WAITING for user to provide MORE input before planning/acting.
-## User said: "OPZIONE A ... ma aspetta prima di agire, che ho altro da darti in pasto"
+## User said (translated from Italian): "OPTION A ... but wait before acting, I have more to feed you"
-## then refined the requirement (see below), then: "pero attendi altro, intanto salva questo punto"
+## then refined the requirement (see below), then: "but wait for more, meanwhile save this point"
 ================================================================
 
 ### GOAL: make the "invalidate" procedure IDENTICAL for both CHECK button and WIZARD.
@@ -285,13 +285,13 @@ effectively NEUTRALIZED (no postpone proposal driven by threshold).
 
 ================================================================
 ## NEW TASKS (added by user, latest message) — TO-DO LIST ONLY, NOT STARTED
-## User: "ti aggiungo altri punti, da mettere in lista delle cose da fare"
+## User: "I'm adding more points for you to put on the to-do list"
 ## NO coding yet. Each needs DISCOVER(refine) -> PLAN -> wait OK (R4) -> zip-first.
 ================================================================
 
 ### TASK #01 — Fix misleading "heir not found" message after wizard when date was only anticipated
-**User (verbatim, IT):** "dopo aver fatto una rendita e il wizard, il plugin dice 'heir not found',
+**User (translated from Italian):** "after creating an annuity and running the wizard, the plugin says 'heir not found',
-ma in realtà è stato solo anticipata la data, il messaggio informativo è sbagliato, ma il resto funziona bene."
+but in reality the date was only anticipated; the informational message is wrong, but everything else works fine."
 **Problem:** the FUNCTIONAL behaviour is correct (the will is rebuilt with the anticipated/postponed
 date). Only the INFORMATIONAL message is wrong/misleading: it says "Heir not found" when actually the
 date was simply anticipated.
@@ -310,12 +310,12 @@ Possibly distinguish "genuine heir-not-found error" vs "date anticipated, rebuil
 accurate in both cases. ASK user for preferred wording if ambiguous (R3).
 
 ### TASK #02 — Will-executor server list: green-check ONLY servers that responded + green ping; re-evaluate each download
-**User (verbatim, IT):** "quando scarico dal wizard la lista dei will executor, il plugin deve spuntare
+**User (translated from Italian):** "when I download the will-executor list from the wizard, the plugin must green-check
-di verde solo i server che hanno risposto correttamente, e che hanno il pallino del ping verde.
+only the servers that responded correctly and that have a green ping dot.
-altrimenti poi si impalla tutto il plugin e continua a fare broadcast a quelli che non rispondono bene.
+otherwise the whole plugin gets stuck and keeps broadcasting to the ones that do not respond well.
-meglio scartare alla fonte i server che non rispondono subito bene. questo deve valere ogni volta che
+better to discard at the source the servers that do not respond well right away. this must apply every time I
-scarico la lista server; se la seconda volta scarico e un server che prima non rispondeva ora risponde,
+download the server list; if on the second download a server that previously did not respond now responds,
-il plugin lo aggiunge alla lista server."
+the plugin adds it to the server list."
 **Goal:**
 1. When downloading the will-executor list from the wizard, auto-select (green check) ONLY servers that
    (a) responded correctly AND (b) have a GREEN ping dot.
@@ -336,9 +336,9 @@ to re-evaluate on each download without losing manual user choices (ASK if confl
 untouched.
 
 ### TASK #03 — Invalidate tx missing "BAL Invalidate transaction" history label when invalidate done from the AUTO-opened window
-**User (verbatim, IT):** "come già detto prima con te, la transazione invalidate non ha scritto
+**User (translated from Italian):** "as already discussed with you before, the invalidate transaction did not write
-'BAL invalidate transaction' in cronologia del wallet, se fatto invalidate dalla finestra che si apre
+'BAL invalidate transaction' in the wallet history if the invalidate was done from the window that opens
-in automatico. mentre lo scrive solo quando faccio invalidate dal menu TOOLS, Invalidate manualmente."
+automatically; whereas it only writes it when I invalidate from the TOOLS menu, Invalidate manually."
 **Problem:** the history label "BAL Invalidate transaction" is written ONLY when invalidating manually via
 Tools -> Invalidate (PROCEDURE 1), NOT when invalidating from the window that opens automatically
 (PROCEDURE 2).
@@ -504,8 +504,8 @@ show a correct message instead of "Heir not found". DISCOVER will confirm the pr
 ---
 
 ## TASK #01b — Replace misleading "Heir not found" / "New" messages (NOT STARTED — analysis only)
-**User decision (Opzione 2):** change BOTH the CHECK window (dialogs.py) AND window.py for consistency.
+**User decision (Option 2):** change BOTH the CHECK window (dialogs.py) AND window.py for consistency.
-**User said:** "ma metti tutto in lista non fare modifiche per ora" (just add to list, do NOT modify yet).
+**User said (translated from Italian):** "just put everything on the list, do not make changes for now".
 
 ### GOAL
 Replace the two MISLEADING outcome texts shown in ROW 2 "Checking your will" with a single clear text:

docs/inheritance-options.html

@@ -235,6 +235,30 @@ Electrum <strong>close</strong>, not only on Prepare.</blockquote>
 <p>If heirs, percentages, fees, executors and locktimes all still match the signed transactions,
 <code>is_will_valid</code> returns <code>True</code> and <strong>nothing happens</strong>.</p>
 
+<h3>4.8 An heir's share is below the dust limit (DUST)</h3>
+<p>Bitcoin refuses outputs that are too small to spend — the <strong>dust limit</strong>
+(the wallet's <code>dust_threshold</code>). BAL resolves each heir's final amount when it builds
+the will (<code>Heirs.prepare_lists</code>) and compares every share against that limit.</p>
+<ul>
+<li><strong>Some heirs are dust, others valid → build continues.</strong> Each dust heir is
+<strong>skipped</strong> (its share would be unspendable) and listed in the build report as
+<em>“… is DUST – excluded (amount below dust limit)”</em>. The will is still prepared, signed and
+checked with the payable heirs (unchanged behaviour).</li>
+<li><strong>EVERY heir is dust → build blocked.</strong> If all shares are below the dust limit the
+inheritance would pay nobody. As of <strong>v0.4.7</strong> BAL refuses it
+(<code>HeirAmountIsDustException</code>) and the <strong>Building Will</strong> window stops with a
+clear <span class="pill red">red</span> message: <em>“All heirs' shares are below the dust limit:
+the inheritance cannot be created. Increase the amounts or reduce the number of heirs.”</em>
+Nothing is built, signed, checked or added to the list.</li>
+</ul>
+<blockquote><strong>When?</strong> Typically with a <strong>very small balance</strong> split among
+<strong>percentage</strong> heirs, or when every fixed amount is below the dust limit. Fix: raise the
+per‑heir amounts or use fewer heirs.</blockquote>
+<blockquote><strong>Note (v0.4.7):</strong> the dust check lives in <code>prepare_lists</code>, which sees
+<strong>all</strong> heirs across <strong>all</strong> locktimes — a single transaction only covers the
+earliest locktime, so checking there would wrongly block a will whose later dates still have valid
+heirs. <strong>On‑chain fee:</strong> none (pre‑build safety check).</blockquote>
+
 <h2>5. What happens on the will‑executor servers</h2>
 <table>
 <thead><tr><th>Your action</th><th>Effect on the servers</th></tr></thead>
@@ -267,6 +291,7 @@ executor that <em>should</em> hold your tx did not return it — re‑Broadcast
 <tr><td>Check‑Alive threshold already passed</td><td class="yes">Yes after</td><td class="fee">Yes</td></tr>
 <tr><td>Any change to an <strong>already signed/sent</strong> will <strong>that postpones it or expires it</strong></td><td class="yes">Yes after</td><td class="fee">Yes</td></tr>
 <tr><td>Nothing changed</td><td class="no">No</td><td class="no">No</td></tr>
+<tr><td>Every heir's share below the dust limit (all‑dust) — build <strong>blocked</strong> (§4.8)</td><td class="no">No</td><td class="no">No</td></tr>
 </tbody>
 </table>
 
@@ -280,10 +305,11 @@ executor that <em>should</em> hold your tx did not return it — re‑Broadcast
     it is just a free <strong>rebuild</strong>.</li>
 <li>Always finish with <strong>Sign → Broadcast → Check</strong> so executors hold the current plan (green).</li>
 <li>The wallet is always <strong>fully emptied</strong> by the inheritance, so heir amounts must add up.</li>
+<li><strong>Mind the dust limit.</strong> A share below Bitcoin's dust limit is skipped; if <strong>every</strong> heir is dust the build is blocked with a clear message (§4.8) — raise the amounts or use fewer heirs.</li>
 </ol>
 
-<footer>This document reflects BAL plugin v0.3.4. Behaviour is derived directly from
+<footer>This document reflects BAL plugin v0.4.7. Behaviour is derived directly from
-<code>core/will.py</code> and <code>gui/qt/window.py</code>.</footer>
+<code>core/will.py</code>, <code>core/heirs.py</code> and <code>gui/qt/window.py</code>.</footer>
 </div>
 
 <script type="module">

docs/inheritance-options.md

@@ -227,6 +227,10 @@ the will is no longer coherent → it is treated like an heir change
 > whole spendable balance is distributed; otherwise an `AmountException` warns you
 > to adjust.
 
+> **Watch the dust limit.** If a share is so small that it falls below Bitcoin's
+> *dust limit*, that heir is skipped (see §4.8). Splitting a tiny balance among
+> many heirs, or giving an heir a very small percentage, can produce dust shares.
+
 ### 4.5 Changing the transaction fee (sat/byte)
 
 Each will item stores the fee rate it was built with. A different rate raises
@@ -255,6 +259,43 @@ If heirs, percentages, fees, executors and locktimes all still match the signed
 transactions, `is_will_valid` returns `True` and **nothing happens** — your will
 stays exactly as broadcast to the executors.
 
+### 4.8 An heir's share is below the dust limit (DUST)
+
+Bitcoin refuses to create outputs that are too small to be worth spending — the
+so‑called **dust limit** (the wallet's `dust_threshold`). BAL resolves every
+heir's final amount when it builds the will (`Heirs.prepare_lists` →
+`fixed_percent_lists_amount` / `normalize_perc`) and compares each share against
+that limit.
+
+- **Some heirs are dust, others are valid → build continues.** Each dust heir is
+  **skipped** (its share would be unspendable). The build proceeds with the
+  remaining valid heirs, and the build report lists every excluded heir as
+  *“… is DUST – excluded (amount below dust limit)”* so you can see who was left
+  out. Behaviour is unchanged: the will is still prepared, signed and checked
+  with the payable heirs.
+
+- **EVERY heir is dust → the build is blocked.** If *all* heirs' shares are below
+  the dust limit, the inheritance would pay nobody (only the change and the
+  will‑executor fee). Previously such an *empty* will was still built, signed,
+  checked and shown in the list. As of **v0.4.7** BAL refuses it:
+  `Heirs.prepare_lists` raises `HeirAmountIsDustException`, and the **Building
+  Will** window stops with a clear **red** message:
+  *“All heirs' shares are below the dust limit: the inheritance cannot be
+  created. Increase the amounts or reduce the number of heirs.”*
+  Nothing is built, signed, checked or added to the list.
+
+> **When does this happen?** Typically with a **very small wallet balance** split
+> among **percentage** heirs (e.g. each heir ends up with a few hundred sats), or
+> when every fixed amount is set below the dust limit. The fix is exactly what
+> the message says: raise the per‑heir amounts, or reduce the number of heirs.
+
+> **Note (v0.4.7):** the dust check lives in `prepare_lists`, which sees **all**
+> heirs across **all** locktimes with their final amounts. This is deliberate: a
+> single transaction only ever covers the earliest locktime, so checking there
+> would wrongly block a will whose *later* dates still have valid heirs.
+
+- **On‑chain fee:** none — this is a pre‑build safety check; nothing is broadcast.
+
 ---
 
 ## 5. What happens on the will‑executor servers
@@ -291,6 +332,7 @@ stays exactly as broadcast to the executors.
 | Check‑Alive threshold already in the past | ✅ after | ✅ **yes** |
 | Any change to an **already signed/sent** will **that postpones it or expires it** | ✅ after | ✅ **yes** (invalidate first) |
 | Nothing changed | ❌ | ❌ |
+| Every heir's share below the dust limit (all‑dust) — build **blocked** (§4.8) | ❌ | ❌ |
 
 ---
 
@@ -306,8 +348,11 @@ stays exactly as broadcast to the executors.
    *current* plan (green), not an obsolete one.
 4. The wallet is always **fully emptied** by the inheritance, so heir amounts must
    add up.
+5. **Mind the dust limit.** A share below Bitcoin's dust limit is skipped; if
+   **every** heir is dust the build is blocked with a clear message (§4.8) —
+   raise the amounts or use fewer heirs.
 
 ---
 
-*This document reflects BAL plugin v0.3.4. Behaviour is derived directly from
+*This document reflects BAL plugin v0.4.7. Behaviour is derived directly from
-`core/will.py` and `gui/qt/window.py`.*
+`core/will.py`, `core/heirs.py` and `gui/qt/window.py`.*