diff --git a/.gitea/workflows/deploy.yml b/.gitea/workflows/deploy.yml old mode 100644 new mode 100755 index 60f2f6e..4d6939a --- a/.gitea/workflows/deploy.yml +++ b/.gitea/workflows/deploy.yml @@ -8,11 +8,16 @@ jobs: deploy: runs-on: docs-runner # must match the label of your registered act_runner steps: - - name: Checkout - uses: actions/checkout@v4 - + - name: Load environment + run: | + echo "PATH=$HOME/venv/bin:$PATH" >> $GITHUB_ENV + + - name: Checkout repository + run: | + git clone --depth 1 https://oauth2:${GITHUB_TOKEN}@${GITHUB_SERVER_URL#https://}/${GITHUB_REPOSITORY} . + - name: Install dependencies - run: pip install --break-system-packages mkdocs-material mkdocs-macros-plugin pyyaml + run: pip install mkdocs-material mkdocs-macros-plugin pyyaml pillow mkdocs-glightbox - name: Generate placeholders for missing screenshots run: python3 tools/make_placeholders.py @@ -21,4 +26,4 @@ jobs: run: mkdocs build --strict - name: Publish - run: rsync -a --delete site/ /var/www/bal-docs/ + run: rsync -a --delete site/ $BAL_DOCS_DEPLOY_DIR diff --git a/.gitignore b/.gitignore old mode 100644 new mode 100755 diff --git a/internal/README.md b/internal/README.md old mode 100644 new mode 100755 diff --git a/internal/brand-assets.md b/internal/brand-assets.md old mode 100644 new mode 100755 diff --git a/internal/design-choices-DRAFT.md b/internal/design-choices-DRAFT.md old mode 100644 new mode 100755 diff --git a/internal/screenshot-checklist.md b/internal/screenshot-checklist.md old mode 100644 new mode 100755 index 6f49236..f868a4d --- a/internal/screenshot-checklist.md +++ b/internal/screenshot-checklist.md @@ -16,112 +16,27 @@ Placeholders never overwrite a real image. ## Capture rules — keep these identical everywhere - **Electrum window only**, not the whole desktop. - - Windows: ++win+shift+s++ (Snipping Tool) or use `grim -g "$(slurp)" shot.png` if you prefer - - macOS: ++cmd+shift+4++ then ++space++ to capture a window - - Linux: `gnome-screenshot -w` or `import -window root shot.png` (ImageMagick) -- **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. + 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 the **dedicated testnet wallet** set up above. -- **Fake heir names** (Jonny, Andrea, Emma — as in the original manual). -- **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 — use generated testnet addresses or Bitcoin StackExchange examples. -- **Obfuscate file paths**: the title bar will show your wallet filename. Use a generic name like `Screenshot_Test`, not `MyWallet_MainAccount`. -- 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. +- 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. -## 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/` 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`). diff --git a/internal/source-notes.md b/internal/source-notes.md index 7c133e8..9bf4315 100644 --- a/internal/source-notes.md +++ b/internal/source-notes.md @@ -21,26 +21,13 @@ 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~~ | **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. | +| 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 | -## Version bumps log - -| 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. | -| 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~~ — 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 - manual edit at every future release. 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 @@ -52,21 +39,6 @@ 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. -9. **`docs/comparison.md` (new, 2026-07-28) — competitor comparison, needs review.** Facts on - Nunchuk (Iron Hand ~$120/yr, Honey Badger ~$480/yr, no-KYC/email only, accepts BTC or card, - collaborative custody = 1 platform key; Nunchuk 2.0 added on-chain timelock+Miniscript - inheritance, Nov 2025) and Liana (free/open-source, Miniscript relative timelocks, self-hosted - or Liana Connect hosted backend) were pulled from public web sources mid-2026. **Prices change.** - Corrected the user's original premise: Nunchuk is NOT KYC — the honest BAL differentiator is - "no recurring subscription + no third-party-held key", not "no credit card". Cross-check with - `design-choices-DRAFT.md` editorial rules (no "investment/yield", no disparagement) before - publishing. Page carries a draft warning. -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 diff --git a/tools/make_placeholders.py b/tools/make_placeholders.py new file mode 100755 index 0000000..0bd0c06 --- /dev/null +++ b/tools/make_placeholders.py @@ -0,0 +1,80 @@ +#!/usr/bin/env python3 +"""Generate a visible placeholder for every screenshot listed in screenshots.yml +that does not yet exist in docs/img/. + +Real screenshots are never overwritten: drop the real PNG in docs/img/ with the +manifest filename and this script will simply skip it. + +Usage: + python3 tools/make_placeholders.py # fill in what's missing + python3 tools/make_placeholders.py --list # show what is still missing + python3 tools/make_placeholders.py --force # redraw ALL placeholders + # (never touches real screenshots + # unless they are placeholders) +""" +import sys +from pathlib import Path + +try: + import yaml +except ImportError: + sys.exit("Missing dependency: pip install pyyaml") +from PIL import Image, ImageDraw + +ROOT = Path(__file__).resolve().parent.parent +MANIFEST = ROOT / "screenshots.yml" +IMG_DIR = ROOT / "docs" / "img" +W, H = 1280, 720 +BG = (238, 241, 244) # --bal-bg #eef1f4 +FG = (91, 102, 114) # --bal-muted #5b6672 +ACCENT = (45, 108, 223) # --bal-accent #2d6cdf +# Backgrounds ever used by this script — lets --force recognise its own output +# (including older revisions) without ever touching a real screenshot. +KNOWN_PLACEHOLDER_BGS = {BG, (241, 243, 245)} + + +def draw_placeholder(path: Path, name: str, shows: str) -> None: + img = Image.new("RGB", (W, H), BG) + d = ImageDraw.Draw(img) + d.rectangle([8, 8, W - 8, H - 8], outline=ACCENT, width=4) + d.text((48, H // 2 - 60), "SCREENSHOT NEEDED", fill=ACCENT) + d.text((48, H // 2 - 20), f"file: docs/img/{name}", fill=FG) + d.text((48, H // 2 + 10), f"shows: {shows}", fill=FG) + d.text((48, H - 60), "Replace this file with the real screenshot (same filename).", fill=FG) + img.save(path) + + +def is_placeholder(path: Path) -> bool: + """A placeholder is exactly W x H with our flat background colour.""" + try: + with Image.open(path) as im: + return im.size == (W, H) and im.convert("RGB").getpixel((2, 2)) in KNOWN_PLACEHOLDER_BGS + except Exception: + return False + + +def main() -> None: + manifest = yaml.safe_load(MANIFEST.read_text(encoding="utf-8")) + IMG_DIR.mkdir(parents=True, exist_ok=True) + missing, created = [], 0 + for item in manifest["screenshots"]: + target = IMG_DIR / item["file"] + if target.exists() and not ("--force" in sys.argv and is_placeholder(target)): + continue + missing.append(item) + if "--list" not in sys.argv: + draw_placeholder(target, item["file"], item.get("shows", "")) + created += 1 + if "--list" in sys.argv: + if not missing: + print("All screenshots present.") + else: + print(f"{len(missing)} screenshot(s) still missing:") + for m in missing: + print(f" - {m['file']:38s} ({m.get('page','')}) — {m.get('shows','')}") + else: + print(f"{created} placeholder(s) generated, {len(manifest['screenshots']) - created} real image(s) already in place.") + + +if __name__ == "__main__": + main()