From 29cf9654d540fc1351aa2c920d8cbf5ad6ed51ea Mon Sep 17 00:00:00 2001 From: Lior Date: Thu, 28 May 2026 14:12:34 -0400 Subject: [PATCH] =?UTF-8?q?feat(skills):=20zflash-overview=20capability=20?= =?UTF-8?q?skill=20=E2=80=94=20end-to-end=20runbook=20+=20substrate-cluste?= =?UTF-8?q?r=20map=20(B-0844=20+=20B-0852=20+=20B-0884=20+=20B-0891=20+=20?= =?UTF-8?q?B-0737=20+=20B-0852.3)=20(zflash=20lane=20Track=20C=20docs/skil?= =?UTF-8?q?ls=20push=202026-05-28)?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit zflash lane Track C push per B-0892 three-lanes-concurrent operating discipline + operator authorization "feel free to push the three lanes forward" 2026-05-28. New capability skill that consolidates substrate-cluster knowledge: 1. What zflash IS (ultra-short wrapper around flash-usb.ts) 2. First-time setup (zflash-setup PAM Touch ID install) 3. End-to-end runbook (flash → boot → install → first SSH; 11 steps) 4. Substrate-cluster map (which row solves which problem; B-0844 + B-0852 + B-0852.3 + B-0884 + B-0891 + B-0737 + B-0892) 5. Companion skills (zflash-creds + git-expert + dst-substrate-engineer) 6. Substrate-anchors (canonical implementation files + test harness + next-steps plan) 7. When-NOT-to-apply discipline Per asymmetric-critic-with-clarity-first: skill description is specific + triggering-keyword-rich so the router can find it for newcomer "what does zflash do" + operator end-to-end runbook questions + composition-with-encryption-lane questions. Composes with existing zflash-creds skill (placeholder for --bake-cred flag); B-0892 three-lanes-concurrent operating discipline; full-ai- cluster/tools/zflash.ts canonical implementation. 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude --- .claude/skills/zflash-overview/SKILL.md | 100 ++++++++++++++++++++++++ 1 file changed, 100 insertions(+) create mode 100644 .claude/skills/zflash-overview/SKILL.md diff --git a/.claude/skills/zflash-overview/SKILL.md b/.claude/skills/zflash-overview/SKILL.md new file mode 100644 index 0000000000..4766904b74 --- /dev/null +++ b/.claude/skills/zflash-overview/SKILL.md @@ -0,0 +1,100 @@ +--- +name: zflash-overview +description: zflash end-to-end overview + substrate-cluster map (B-0844 + B-0852 + B-0884 + B-0891 + B-0737 + B-0852.3) + canonical flash-and-install runbook. Use when newcomer needs to understand zflash substrate-cluster, when operator asks "what does zflash do", when picking which substrate-row solves a specific zflash-substrate-target, when running zflash end-to-end (flash USB → boot PC → install → first SSH). +record_source: "zflash lane Track C docs/skills push, 2026-05-28 per operator 'feel free to push the three lanes forward'" +load_datetime: "2026-05-28" +last_updated: "2026-05-28" +status: active +--- + +# zflash overview + substrate-cluster map + +Capability skill. No persona. Wear this hat when: + +- Newcomer needs to understand the zflash substrate-cluster end-to-end +- Operator asks "what does zflash do" / "how do I flash a USB" / "what's the install runbook" +- Picking which substrate-row solves a specific zflash-substrate-target +- Running zflash end-to-end (flash USB → boot PC → install → first SSH) +- Composing zflash with encryption substrate (B-0884) or state-machine substrate + +## What zflash IS + +`bun full-ai-cluster/tools/zflash.ts` is the ultra-short wrapper around `flash-usb.ts` for the AI-cluster installer. + +**Canonical end-to-end (after first-time setup)**: + +```bash +$ bun full-ai-cluster/tools/zflash.ts +ISO: ~/Downloads/zeta-installer-25.11.iso (1.70 GiB) +USB: /dev/disk6 (115 GiB, USB 3.2.1 FD) +*** ALL DATA ON /dev/disk6 WILL BE DESTROYED *** +type: yes a3f9 +``` + +**One command + one short challenge + Touch ID + sudo PAM** → fully-flashed USB ready to boot a PC into the Zeta installer, with operator's SSH pubkey already injected. + +## First-time setup + +```bash +# Once per machine: +bun full-ai-cluster/tools/zflash-setup.ts +# Installs sudo PAM Touch ID hook so zflash can dd without typed password +``` + +## End-to-end runbook (flash → boot → install → SSH) + +1. **Pre-flight**: ensure ISO downloaded (auto-discovers newest `~/Downloads/zeta-installer-*.iso`) +2. **Insert USB**: any 8GB+ USB stick; auto-detects newest plugged-in device +3. **Run zflash**: `bun full-ai-cluster/tools/zflash.ts` +4. **Confirm challenge**: type `yes <4-char-code>` (short challenge format per B-0737) +5. **Touch ID**: PAM gates the dd command via Touch ID +6. **dd runs**: ISO written to USB +7. **SSH pubkey injection** (B-0789 iter-4.2): zflash mounts the freshly-flashed ESP partition + writes operator's pubkey as `/zeta-authorized-keys.pub` +8. **Boot target PC** from the USB +9. **zeta-install.sh runs** on the booted installer; picks up the SSH pubkey + injects into `operator-ssh-keys.nix` +10. **nixos-install completes**; PC reboots into Zeta cluster +11. **Operator SSHes as `zeta` user** with existing SSH key — zero-typing flow + +## Substrate-cluster map + +Which row solves which problem: + +| Row | Substrate-target | Status | +|---|---|---| +| **B-0844** | zflash agent-mode native implementation (`--agent` flag); close doc-vs-implementation gap | Shipped | +| **B-0852** | USB-bound creds substrate (Track B `--bake-cred`; multi-USB provisioning) | In progress per Track B | +| **B-0852.3** | zeta-install.sh Step 6.77 cred-picker integration (interactive bake vs zflash token override) | In progress | +| **B-0884** | Integrate post-quantum git-crypt with zflash USB-bound credential substrate | In progress per encryption lane | +| **B-0891** | zflash done-acceptance-criteria QEMU test harness (5 scenarios: initial-format, cluster-up, reformat-with-retention, reformat-from-scratch, cluster-joining) | 5-scenario substrate landed per PR #5866 | +| **B-0737** | zflash Touch ID + PAM + short-challenge format + ISO auto-discovery | Substrate landed | +| **B-0892** | Three-lanes concurrent operating discipline (encryption + zflash + state-machine; lane definitions + critical-path next-steps) | Discipline substrate | + +## Companion skills + +When wearing this hat, may compose with: + +- `zflash-creds` — bake operator credentials into USB-bound encrypted blob via `--bake-cred` (PLACEHOLDER until B-0884 ships) +- `git-expert` — git operations during ISO build + install +- `dst-substrate-engineer` — deterministic-substrate-engineering substrate (composes with B-0891 5-scenario test acceptance) + +## Substrate-anchors + +- `full-ai-cluster/tools/zflash.ts` — canonical implementation +- `full-ai-cluster/tools/zflash-lib.ts` — substrate-engineering substrate-engineering substrate library +- `full-ai-cluster/tools/zflash-setup.ts` — first-time PAM substrate setup +- `tools/zflash/test-harness/` — QEMU 5-scenario test harness (B-0891) +- `docs/research/2026-05-28-zflash-and-usb-credential-substrate-next-steps-plan.md` — substrate-engineering substrate-engineering substrate next-steps plan + +## When this skill does NOT apply + +- Implementing new zflash substrate (use row-specific skills + read implementation) +- Debugging dd/PAM issues at substrate-engineering substrate-engineering substrate scope (use `bash-expert` + `macos-expert` + relevant substrate-engineering substrate) +- Designing encryption substrate (compose with encryption agenda + B-0883 substrate cluster instead) +- Picking zflash sub-mechanism without operator-direction (lanes within zflash require operator-direction per B-0892) + +## Composes with rules + +- `.claude/rules/zeta-ships-with-skills-immediate-value.md` — TS substrate ships first; F# crystallization later +- `.claude/rules/rule-0-no-sh-files.md` — TS-first for cross-platform DST +- `.claude/rules/dep-pin-search-first-authority.md` — version-pinning discipline composes with zflash ISO substrate +- B-0892 three-lanes-concurrent operating discipline — zflash lane substrate-anchor