docs(v4): the stick's sizes -- a minimum, and Artemis grows to fill the stick

Captain Bob, 2026-10-26: sized for an off-the-shelf thumb drive, "a minimum
and then ... no max or reasonable max size"; "all to Artemis, identity stays
at 500 MiB". The image is 2 GiB (ESP 64 MiB, identity 500 MiB, Artemis the
rest); the minimum stick 8 GB; at first boot Artemis grows to fill the stick,
up to 2 TiB, writing metadata only (GPT, volume header, free map, fence); a
stick under 8 GB is not grown. With genesis, increment 5; the GPT writer is
INSTALL's too.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

docs/v4.0.0/STICK.md

@@ -84,11 +84,21 @@ gains the partitions below). Three partitions:
   subsystem) runs unchanged on the partition device.
 - **Raw identity drives stay accepted:** a device with no valid GPT is read as today (the minted
   scratch pair in `disk/zuse-scratch/`, any v3 identity drive).
-- **Sizes:** the image is a fixed size and does not grow to fill a bigger stick. Partition sizes are
-  set at build time, in one place, `kernel/Makefile`, and are not fixed by the formats: ESP 64 MiB,
-  identity 500 MiB to start (Captain Bob, 2026-10-26: "64 megabytes does not need to be an engraved
-  in stone size ... start maybe 500 megabytes"; the identity format records its own size,
-  `homeblocks_sig_t.metadata_devblocks`), Artemis the rest of a 2 GiB image (my call).
+- **Sizes: a minimum, and dynamic above it** (Captain Bob, 2026-10-26: "pick like the generic size of
+  any old ... thumb drive off the shelf ... I want the sizing to be dynamic, so like a minimum and then
+  ... no max or reasonable max size"; "all to Artemis, identity stays at 500 MiB"). Set in one place,
+  `kernel/Makefile`; none is fixed by the formats (the identity format records its own size,
+  `homeblocks_sig_t.metadata_devblocks`):
+  - **The image as built: 2 GiB** — ESP 64 MiB, identity 500 MiB, Artemis the rest. Small, so it is
+    quick to write to a stick.
+  - **The minimum stick: 8 GB.** Sticks on the shelf are 16–64 GB; 8 GB is the floor.
+  - **The identity partition stays 500 MiB.** About half a million 1 KiB blocks for Zuse's keys and
+    her own pool.
+  - **Artemis grows to fill the stick at its first boot (§5a),** up to **2 TiB** for the partition
+    (the block layer numbers 1 KiB blocks with 32 bits: 4 TiB is its hard limit; 2 TiB keeps a margin
+    and is past any thumb drive). Space past 2 TiB is left unused, and the boot says so.
+  - **A stick under 8 GB** is not grown: it runs at the 2 GiB it was written with, and the boot says
+    so.
 - **The Artemis partition is formatted when the image is built (my call),** not on first boot:
   the image builder writes its `STFR` volume header and its `artemis_sig_t` genesis signature,
   so the kernel never meets a blank Artemis on a stick and never has to decide whether a disk may
@@ -124,6 +134,25 @@ Everything the identity gate does today (`kernel/src/v4/sk_v4_identity.c`), with
    StarshipOS partition types), `system=v3` is not obeyed: "System: v3 is not on this stick --
    StarForth v4", and v4 boots.
 
+## 5a. First boot: Artemis grows to fill the stick
+
+Before genesis, on a stick whose GPT ends where the 2 GiB image ended and whose disk is larger (the
+first boot of a freshly written stick), the kernel grows Artemis:
+
+- It moves the backup GPT header and entry array to the disk's end, extends the Artemis partition's
+  last LBA to the end of the usable space (capped at 2 TiB of partition), and rewrites both headers
+  with their CRCs (the GPT writer; `INSTALL` reuses it).
+- It grows Artemis's volume to the partition: its `STFR` header's size, its free map for the new
+  blocks, and its metadata fence (with the genesis marker's slot) moved to the new top, as the block
+  subsystem lays a volume out (`v3/src/block_subsystem.c`).
+- **Growth writes metadata only** — the GPT, the volume header, the free map, the fence — never the
+  partition's data blocks. Through USB under QEMU's TCG, writing 16 GB would take hours; on a real
+  stick, many minutes. The first boot's time is measured in the tests.
+- It happens once: a stick already grown (its GPT reaches the disk's end) is not grown again. If
+  power is lost mid-growth, the next boot finds either the old GPT (and grows again) or the new one
+  (the backup header is written before the primary, so a torn write leaves one valid header).
+- A stick under the 8 GB minimum is not grown (§4).
+
 ## 6. First boot: genesis on the stick
 
 On the first boot of a stick, the identity partition is blank and the Artemis partition's fence
@@ -205,7 +234,7 @@ Standing rule: "we must ALWAYS maintain QEMU and bare metal builds hold parity."
 
 **Non-goals (later designs):** `INSTALL`; `DOE`, `SDK`, demos; WIREBIND identities and other
 users on the stick; ARM and RISC-V sticks (the Pi build later adds a GPIO vocabulary/VM, which does
-not exist yet); growing the image to fill a bigger stick.
+not exist yet).
 
 **Anti-goals — a failure even if it boots:**
 - Anything written to the PC's own disks before `INSTALL`.
@@ -229,7 +258,10 @@ first and seen to fail:
 4. **Artemis and Zuse from one disk:** the boot device from the loader, the partitions found and
    attached, virtio Artemis off the v4 path; recognition of a minted stick; entropy on the v4 path;
    `system=v3` refused on a stick (§4, §5).
-5. **Genesis on the stick** (§6).
+5. **Genesis on the stick, and growth** (§5a, §6): the GPT writer; Artemis grown to fill the stick,
+   metadata only; genesis. Tested on a fresh 16 GB sparse stick image (first boot: grows, mints, the
+   prompt; the second boot of the same copy: recognised, not grown again; the first boot's time
+   recorded) and a 4 GB one (below the minimum: not grown, said so).
 6. **Pull and replug** (§7), and the flush.
 7. **The splash and progress bar** (§8), with the mkcapsule PNG converter.
 8. **Acceptance moves** to the stick boot for x86_64 (§9).