docs(stick): plug and play -- a proxy Zuse on every stick's first boot, the real Zuse on a second stick

Captain Bob, 2026-10-29: "i want this a plug & play solution" -- "plug it in, it boots to the
prompt, no setup". STICK.md amended (§2, §3, §4, §6, new §6a, §7, §9, §10, §11), each change
saying what the text said before:

- A stick's first boot mints its own proxy Zuse (§6's genesis, minted at first boot, not at
  build, so no two sticks share a key): full Zuse "until the real one is minted".
- MINT-ZUSE mints the real Zuse onto a second stick, after a typed YES, read back before the
  genesis marker (version 2: the proxy's key and the real Zuse's) records her.
- With a real Zuse, the system stick alone gives a fixed screen whose only action is minting a
  replacement ("the later"); a replacement kills the old stick "for good".
- Amends R2 ("only this system's stick is used") for the real Zuse stick, and supersedes "Zuse's
  identity is on the same stick that boots". The open risk -- the system stick stays a master
  key through the fallback -- is written down in §6a.
- §11: the proxy goes into increment 5; the real Zuse stick is a new increment 5a.

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

docs/v4.0.0/STICK.md

@@ -4,6 +4,10 @@ Design, 2026-10-26, from Captain Bob's answers the same day (each quoted where i
 first of three designs toward the goal below; the other two, `INSTALL` and `DOE`/`SDK`/demos, are
 written after this one is approved.
 
+**Amended 2026-10-29 -- plug and play, a proxy Zuse, and the real Zuse on a second stick**
+(Captain Bob: "i want this a plug & play solution" -- "plug it in, it boots to the prompt, no
+setup"). §2, §3, §4, §6, §6a, §7, §9, §10 and §11 carry the change; each says what it said before.
+
 ## 1. Intent
 
 > "the goal is to be able to deliver an entirely self hosted thumbdrive `build` that can deliver
@@ -27,10 +31,17 @@ and demos.
 2. The screen shows only the StarshipOS splash with a progress bar ("splash only, log on
    serial"). The whole boot log goes to the serial port, if there is one.
 3. **First boot of a stick:** the kernel finds no Zuse on it and mints one — "minted on first
-   boot, each stick its own Zuse."
+   boot, each stick its own Zuse." **Amended 2026-10-29:** the Zuse minted there is the stick's
+   **proxy Zuse** (§6). Until a real Zuse is minted she is full Zuse ("full zuse until the real
+   one is minted"): plug the stick in, boot, `[zuse@Hera] ok>`, nothing to set up.
 4. **Every boot:** the kernel recognises Zuse on the stick and logs her in by itself —
    "automatic, like v3 does when the drive is attached." The splash gives way to the console:
    `[zuse@Hera] ok>`, typed to with the PC's USB or PS/2 keyboard.
+4a. **The real Zuse (amended 2026-10-29):** from a session, Zuse mints the real Zuse onto a
+   second stick (§6a). From then on she logs in with that stick plugged in beside the system
+   stick. Booted with the system stick alone, the proxy can do one thing: "only mint a
+   replacement zuse stick", on a fixed screen, not at a prompt (§6a). A replacement kills the
+   old Zuse stick: "the old stick dies for good".
 5. While they try it, what they write persists on the stick across reboots — "persist on the
    stick until INSTALL." Nothing is written to the PC's own disk.
 6. If they pull the stick mid-session: "go headless until it's plugged back in." The console
@@ -53,6 +64,10 @@ and demos.
 | The GPT code runs on every ISA; every `clean qemu` boot attaches a small GPT **data stick** (identity and Artemis partitions) over USB in place of virtio; virtio Artemis leaves v4 | §9 |
 | The splash: a PNG-only converter now, the general converter interface later; scaled at build to 1024×683; its capsule ID is the hash of the converted pixels | §8 |
 | **QEMU and bare metal ALWAYS hold parity** (standing rule) | §9 |
+| **Plug and play** (2026-10-29): "plug it in, it boots to the prompt, no setup" | §2, §6 |
+| Every stick boots first as a **proxy Zuse**, full Zuse "until the real one is minted" on a second drive (2026-10-29; amends "Zuse's identity is on the same stick that boots", above) | §6, §6a |
+| The proxy stays as a fallback, but once a real Zuse exists it may "only mint a replacement zuse stick", on a fixed screen ("the later" of a prompt or a fixed screen) (2026-10-29) | §6a |
+| Minting a replacement: "the old stick dies for good" (2026-10-29) | §6a |
 
 ## 4. The stick's layout
 
@@ -86,7 +101,11 @@ gains the partitions below). Three partitions:
   `plans/2026-10-27-stick-4-one-disk.md`): this bullet said "raw identity drives stay accepted",
   which contradicted "one disk" above. **On v4, Artemis and Zuse come only from this system's
   stick, and no other drive is attached** — raw or GPT, blank or minted: "USB: a drive that is not
-  this system's stick -- not used". Once Artemis is only on the stick, a raw drive could be Zuse's
+  this system's stick -- not used". **Amended again 2026-10-29 (§6a):** one other drive is used --
+  this system's **real Zuse stick**, a GPT disk with one StarshipOS identity partition whose
+  identity matches the real Zuse key in the genesis marker. It is attached after the system stick's
+  two partitions, so Artemis keeps the first disk slot. And while the minting of §6a asks for one,
+  a stick the person names is written (after they confirm). Every other drive is still not used. Once Artemis is only on the stick, a raw drive could be Zuse's
   only as a copy of the stick's own identity partition, and attaching it before the stick would
   take the first disk slot, where the fence must be. **This is not a "never" for other people's
   drives:** drives of users minted by this system's Zuse, and checked by WIREBIND against her key,
@@ -181,6 +200,53 @@ the genesis marker (her public key) is written to the Artemis partition's fence
 - If the mint fails (no entropy, a write error): "Zuse: genesis mint failed", and the system
   stays headless behind the splash. Nothing half-written is taken for an identity.
 
+**Amended 2026-10-29 -- the Zuse minted here is the stick's proxy Zuse.** Everything above stands
+(the same genesis, at the same moment, onto the same partition); what changes is what she is:
+- She is the **proxy Zuse**: full Zuse while no real Zuse exists ("full zuse until the real one is
+  minted"), and after that only the fallback of §6a.
+- **Minted at first boot, not at build (my call).** Captain Bob: "id always want the image to be
+  with zuse as the first boot". The image could carry a proxy minted when it is built, but then
+  every stick written from one image would share one proxy key -- an anti-goal (§10). Minted at
+  first boot, each stick has its own, and the image holds no key at all. The person sees the same
+  thing: the first boot ends at `[zuse@Hera] ok>`.
+- **The genesis marker gains a version (2)** that holds two keys: the proxy's (written here) and
+  the real Zuse's (zero until §6a writes it). Version 1 markers -- the minted pair in
+  `disk/zuse-scratch/`, sticks built with `STICK_PAIR` -- read as a proxy with no real Zuse, so
+  they log in as today. v3 reads only version 1, but v3 never runs from a stick (§5.5).
+- **Plug and play is reached here:** `make boot_image TARGET=PC`, `make write_stick DEVICE=...`,
+  plug in, boot, prompt. `STICK_PAIR` stays only for tests that need a known Zuse.
+
+## 6a. The real Zuse, on a second stick (amended 2026-10-29)
+
+**Minting her.** At the prompt, Zuse (the proxy, or a real Zuse) types `MINT-ZUSE` (name my
+call). The kernel asks for a stick to be plugged in, shows the one that arrives (its size and,
+from USB, its vendor and product), says everything on it will be erased, and writes nothing until
+the person types `YES` (my call: Captain Bob's other stick may not be blank). It then writes a GPT
+with one StarshipOS identity partition (the whole stick up to 500 MiB, as §4's identity partition;
+my call), mints a fresh Zuse identity into it (`capsule_mint_identity`, as genesis does), reads it
+back, and only then writes the real key into the genesis marker on the system stick's Artemis.
+"Zuse: real Zuse minted onto the second stick". The session goes on as the real Zuse.
+- **A failure writes no marker:** if the mint or its read-back fails, the marker is not touched
+  and nothing changes -- the old real Zuse stick, if there was one, still works.
+- **Done from the real Zuse's own session too** it is how she replaces herself on purpose; the
+  same steps, the same effect.
+
+**Every boot after.** The system stick's proxy is recognised as before, then:
+- **The real Zuse stick plugged in** (at boot, or later): her identity is checked against the
+  marker's real key; she is logged in, `[zuse@Hera] ok>`. Pulling it ends her session (§7).
+- **No real Zuse stick:** the proxy does not get a prompt. A **fixed screen** (screen and serial,
+  my wording) says: "Zuse's stick is not here. Plug it in to log in. Or plug in another stick and
+  press R to mint a replacement -- the old Zuse stick will stop working." Every other key is read
+  and dropped, as typed-ahead keys are today (the identity gate's review item 4). Plugging in the
+  real Zuse stick logs her in, as above. R runs the minting above, then she is logged in.
+- **The old stick dies:** a replacement overwrites the marker's real key, so the old stick's
+  identity no longer matches: "Zuse: not this system's Zuse stick -- not used".
+
+**What this leaves open (written down, not hidden):** whoever holds the system stick can use the
+fallback to mint themselves a Zuse -- the old one then stops working, so the owner finds out, but
+the system stick stays a master key. Captain Bob chose the fallback knowing this (2026-10-29).
+Copying a system stick before a replacement and booting the copy later is not guarded against.
+
 ## 7. A session, and pulling the stick
 
 - **Writes persist on the stick** — the Artemis partition — and nowhere else. The idle beat
@@ -194,6 +260,10 @@ the genesis marker (her public key) is written to the Artemis partition's fence
 - **Plugging it back in** finds the same partitions again; Artemis is reattached, Zuse is
   recognised and logged in, the console comes back.
 - The kernel keeps running from memory while the stick is out: it was loaded into RAM at boot.
+- **With a real Zuse (amended 2026-10-29, §6a):** pulling her stick ends her session and the
+  fixed screen of §6a comes up (the system stick is still in). Pulling the system stick ends any
+  session and the system is headless, as above; the kernel lets the Zuse stick go first, since
+  the block subsystem detaches only the last device in its chain and hers was attached last.
 
 ## 8. The splash
 
@@ -233,6 +303,11 @@ Standing rule: "we must ALWAYS maintain QEMU and bare metal builds hold parity."
   `[zuse@Hera] ok>` with POST passing and `dict_hash` equal; and for x86_64 the stick image booted
   as above, from a fresh copy (first boot: genesis) and then the same copy again (recognition).
   The identity gate's QEMU defaults (D4: `disk/zuse-scratch/`) are retired then.
+  **Amended 2026-10-29 (§6a):** QEMU tests the real Zuse stick with a second USB stick on the
+  same xHCI controller (as the two-stick session does today): `MINT-ZUSE` onto it; reboot with the
+  system stick alone (the fixed screen; keys typed there do not run); plug the Zuse stick in (the
+  prompt); mint a replacement with R onto a third stick; plug the old one in ("not this system's
+  Zuse stick -- not used").
 - **What QEMU cannot show** (written down, not assumed): the PC's own firmware and its USB
   controller's firmware handoff (`BRINGUP.md` A1), its real framebuffer modes, a legacy-free PC's
   PIC (S3). Those wait for the bench.
@@ -248,6 +323,12 @@ not exist yet).
 **Anti-goals — a failure even if it boots:**
 - Anything written to the PC's own disks before `INSTALL`.
 - Two sticks sharing one Zuse (every stick mints its own).
+- **(2026-10-29)** Setup before the first prompt: anything to type, edit or choose between
+  writing the stick and `[zuse@Hera] ok>` (the PC's firmware settings -- Secure Boot off, the
+  stick first -- are the PC's, written in the stick's notes, not ours).
+- **(2026-10-29)** Once a real Zuse exists: a prompt for the proxy, or anything she can do but
+  mint a replacement; an old Zuse stick that still logs in after a replacement; a marker written
+  before the new stick's identity has been read back.
 - A prompt on screen with no Zuse logged in, or typed-ahead keys run as her (the identity gate's
   review items 1 and 4 stand).
 - A path that works in QEMU and not on a PC, or the reverse.
@@ -274,6 +355,11 @@ first and seen to fail:
    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).
+   **Amended 2026-10-29:** the genesis is the proxy's, with the version 2 marker (§6); the fresh
+   stick's first boot reaching `[zuse@Hera] ok>` with nothing set up is the test of plug and play.
+5a. **The real Zuse stick (2026-10-29)** (§6a): `MINT-ZUSE` and its confirmation, the GPT and
+   identity written to the second stick, the marker's real key; recognition of the real Zuse
+   stick; the fixed screen and its R; the old stick refused after a replacement.
 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).