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

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.