From cbdc629f20e4cb30ea3631b31bdb6ff5b358a9d1 Mon Sep 17 00:00:00 2001 From: Valentin Kivachuk Burda Date: Fri, 3 Jul 2026 08:16:56 +0200 Subject: [PATCH] docs: clarify the warm-start capture workflow (--seed flag + validate switch) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Spell out how the warm-start seed is actually applied (a user asked): the seed is the --seed given to `motatool serve`, NOT a file dropped into the --dir destination (which starts empty). motatool stamps that one seed into the fresh .part on every `… folder validate` begin, so it's always the named file — no guessing. `validate` is the switch (a plain folder pull fetches from 0); a re-pull re-begins fresh (never resumes a stale partial); a mismatched/absent seed just falls back to fetching those blocks over the radio (correct result, only slower). --- docs/ota_user_guide.md | 9 +++++++++ 1 file changed, 9 insertions(+) diff --git a/docs/ota_user_guide.md b/docs/ota_user_guide.md index 1e74c3ec..10831ad6 100644 --- a/docs/ota_user_guide.md +++ b/docs/ota_user_guide.md @@ -106,6 +106,15 @@ otherwise have. (`ota get` is an alias.) every block your seed already matches, and pulls over the radio only the handful that actually differ — turning a ~30-minute capture into seconds. The result is still a byte-exact, verified copy of the target. +*Where the seed comes from:* it is the **`--seed ` you pass to `motatool serve`** — **not** a file you +drop into the capture (`--dir`) folder, which is only the destination and starts empty. There is exactly one +configured seed. When you run `... folder validate`, the node asks motatool to begin the capture and motatool +stamps that seed's payload into the fresh `.part` in the same step — so it is always the file you named, with +no guessing. **`validate` is the switch:** a plain `folder` pull ignores any seed and fetches from scratch; +re-running a `validate` pull re-begins fresh (it never resumes a stale partial). Nothing about the seed is +trusted — every kept block is checked against the target's own fingerprints, so a mismatched or missing seed +just means those blocks are fetched over the radio (correct result, only slower). + The node fetches in the background, **at low priority**, a piece at a time — possibly from several neighbours at once. Check progress with `ota status`. You can keep using your node normally meanwhile.