Skip to content

Commit 8887f5d

Browse files
TheWayWithinclaude
andcommitted
docs: README ergonomics — a Get-the-tool section for people who have never cloned a repo
The quickstart assumed the repo was already on your machine; a GitHub visitor had no download path. New section: release-tarball download with double-click unpack and an exact cd, git clone as the alternative, Terminal-opening instructions, Homebrew fallback, and an honest Windows (WSL) note. Jump-link added at the top; release checklist now includes bumping the tarball filename each release. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
1 parent f4aba32 commit 8887f5d

2 files changed

Lines changed: 37 additions & 3 deletions

File tree

README.md

Lines changed: 35 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -9,6 +9,8 @@ Two artefacts carry everything:
99
- **Your Executor File** — the encrypted register (`estate.yaml.age`).
1010
- **The Executor Instructions** — one printed page, stored with the will, that tells your executor how to open it.
1111

12+
**New here and ready to try it? Jump straight to [Get the tool](#get-the-tool-2-minutes).**
13+
1214
## The promises this design keeps
1315

1416
A security-literate reader should be able to verify each of these directly from this repo:
@@ -33,9 +35,40 @@ On death, the executor reads the printed Executor Instructions, collects shares
3335

3436
**Your own way back in is simpler:** the passphrase lives in your password manager, like every other credential you own. The shares exist so your *executor* can get in without you; they are not your access path. At review time you type the passphrase, not collect shares.
3537

36-
## Quickstart (you, the owner)
38+
## Get the tool (2 minutes)
39+
40+
There is nothing to install for the tool itself — it is a folder of small scripts you run in place. You need it on your machine one of two ways:
41+
42+
**Option A — download (no git, no GitHub account needed):**
43+
44+
1. Go to the [latest release](https://github.com/TheWayWithin/executor-file/releases/latest) and download **`executor-file-v0.3.0.tar.gz`** (under "Assets").
45+
2. Double-click the downloaded file — macOS unpacks it into a folder called `executor-file-v0.3.0`.
46+
3. Open the **Terminal** app (press ⌘–space, type `Terminal`, press Enter) and type:
47+
48+
```bash
49+
cd ~/Downloads/executor-file-v0.3.0
50+
```
51+
52+
**Option B — clone with git** (if you know you have git):
53+
54+
```bash
55+
git clone https://github.com/TheWayWithin/executor-file.git
56+
cd executor-file
57+
```
58+
59+
Either way you are now "in the folder" — every command below is typed into that same Terminal window, and the `scripts/...` paths will just work.
60+
61+
**Two small tools to install once** (these do the encryption and the share-splitting; both are free, open-source, and standard):
62+
63+
```bash
64+
brew install age ssss
65+
```
66+
67+
(If Terminal says `brew` is not found, install Homebrew first from [brew.sh](https://brew.sh) — one copy-paste command — then run the line above again. On Ubuntu/Debian Linux it's `sudo apt install age ssss` instead.)
3768

38-
Requirements: `age` (≥ 1.3 recommended) and `ssss``brew install age ssss` on macOS, `sudo apt install age ssss` on Debian/Ubuntu.
69+
**On Windows?** The owner-side tooling is built for macOS and Linux. Windows works via Microsoft's built-in WSL feature — install it with `wsl --install` in an administrator PowerShell, then follow the Linux instructions inside Ubuntu. (Executor-side recovery on Windows has its own printed sheet: [`docs/WINDOWS-RECOVERY.md`](docs/WINDOWS-RECOVERY.md).)
70+
71+
## Quickstart (you, the owner)
3972

4073
One command per step — several are interactive, so run each and read what it says before moving on.
4174

RELEASE-CHECKLIST.md

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -53,7 +53,8 @@ re-run `scripts/make-guide.sh` and re-print so the guide carries the
5353
— tarball + `.sha256` attached, release notes honest about the pending
5454
gates. When both gates pass: fold findings into the docs, release
5555
v0.3.1 with "Windows 10/11 (manual dry run — date)" added to platforms
56-
tested, and update the site.
56+
tested, bump the tarball filename in README's "Get the tool" section,
57+
and update the site.
5758

5859
---
5960

0 commit comments

Comments
 (0)