Skip to content

skill: flash-cluster-iso-consumer-path + flash-cluster-iso-dev-path — sibling router-keyed procedures for both ISO flash paths (Aaron 2026-05-25) #5008

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Closed
AceHack wants to merge 2 commits into from
Closed

skill: flash-cluster-iso-consumer-path + flash-cluster-iso-dev-path — sibling router-keyed procedures for both ISO flash paths (Aaron 2026-05-25) #5008

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
ac137cc
skill: flash-cluster-iso-consumer-path + flash-cluster-iso-dev-path —…
AceHack May 25, 2026
aecbb8e
fix(skills): MD032 — rephrase multi-line 'operator effort' line so le…
AceHack May 25, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
132 changes: 132 additions & 0 deletions .claude/skills/flash-cluster-iso-consumer-path/SKILL.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,132 @@
---
name: flash-cluster-iso-consumer-path
description: Flash the Zeta AI-cluster installer ISO to a USB stick using the CONSUMER path — download a pre-built ISO from a CI workflow artifact + flash via zflash. No local Nix toolchain required. Use when the operator wants minimal local-toolchain dependency (just gh + bun + zflash) and is OK with the latest-CI-build version. For the dev path (local Nix build from source) see flash-cluster-iso-dev-path.
record_source: "skill-creator, B-0737 + B-0742 substrate"
load_datetime: "2026-05-25"
last_updated: "2026-05-25"
status: active
bp_rules_cited: [BP-NN — see .claude/rules/desktop-admin-consent-via-biometric-plus-small-challenge-i-execute-you-fingerprint.md]
---

# Flash Zeta AI-cluster installer ISO — CONSUMER path (CI-artifact download)

Capability skill. Procedure for the operator (or agent acting on operator's
behalf) who wants to flash the cluster installer ISO to a USB stick
WITHOUT building locally. Composes with B-0737 zflash + B-0742 reference
stack PoC + B-0728 destructive-tool authoring contract.

## When to use this skill

- Operator needs a fresh installer USB stick for a new cluster node
- Operator does NOT want to install the Determinate Systems Nix
toolchain locally (or already has it but doesn't need to build)
- Operator is OK with the LATEST CI-built ISO version (vs a custom
local build with WIP changes)
- Operator has a Mac with Touch ID-capable hardware + the zflash +
zflash-setup substrate from B-0737

## When NOT to use this skill

- Operator wants to test WIP cluster substrate changes that haven't
been pushed + CI-built yet → use flash-cluster-iso-dev-path
- Operator wants to verify determinism (build locally + compare SHA
vs CI artifact) → use flash-cluster-iso-dev-path AND consumer-path
both + compare
- Operator is on Linux or Windows → B-0738 (Linux variant scope) or
B-0739 (Windows variant scope) — not yet shipped
Comment on lines +35 to +36
- Operator does NOT have biometric hardware → zflash-setup falls
back to password gate (still better than NOPASSWD); proceed but
expect password prompt instead of Touch ID

## Prerequisites

- macOS (Touch ID-capable Mac recommended; substrate-honestly works
on older Macs without biometric — falls back to password)
- `bun` installed (per `tools/setup/macos.sh`)
- `gh` (GitHub CLI) authenticated against the Zeta repo
- `zflash` + `zflash-setup` substrate from B-0737 merged on origin/main
- One-time setup already done: `bun full-ai-cluster/tools/zflash-setup.ts
--install-alias` ran successfully + Touch ID PAM is installed
Comment on lines +47 to +49
- USB stick (115 GiB - 256 GiB recommended; 124 GiB tested per the
zflash sanity range)

## Procedure

### Step 1 — Find the latest successful build-ai-cluster-iso run

```bash
gh run list --workflow build-ai-cluster-iso.yml \
--limit 5 \
--json databaseId,conclusion,status,createdAt,headSha,headBranch
```

Pick the most-recent `"conclusion":"success"` on `"headBranch":"main"`.
Note its `databaseId`.

### Step 2 — Get artifact metadata

```bash
gh api repos/Lucent-Financial-Group/Zeta/actions/runs/<RUN_ID>/artifacts \
--jq '.artifacts[] | {name, size_in_bytes, expires_at}'
```

Note the artifact `name` (e.g., `zeta-installer-24.11.iso`).

### Step 3 — Download to ~/Downloads/

```bash
gh run download <RUN_ID> --name "<ARTIFACT_NAME>" --dir ~/Downloads
ls -lh ~/Downloads/<ARTIFACT_NAME>
```

Should be ~1.7 GiB; matches the `size_in_bytes` from Step 2.

### Step 4 — Flash via zflash

Plug in the USB stick. Then:

```bash
zflash
```

(Or, if shell alias not installed: `bun full-ai-cluster/tools/zflash.ts`)
Copy link
Copy Markdown

@chatgpt-codex-connector chatgpt-codex-connector Bot May 25, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

P1 Badge Use an existing flasher entrypoint in this skill

The fallback command here points to full-ai-cluster/tools/zflash.ts, but that file (and zflash-setup.ts referenced in prerequisites) is not present in the repository; the only committed flasher entrypoint is full-ai-cluster/tools/flash-usb.ts (see its usage docs/comments). On a fresh checkout, following this skill fails with “No such file or directory,” so the new consumer/dev flash procedures are not executable unless these commands are aligned to real tooling.

Useful? React with 👍 / 👎.


zflash auto-discovers the newest `~/Downloads/zeta-installer-*.iso`
(your just-downloaded one wins by mtime), runs all hardware sanity
rails, prints a per-run nonce, waits for `yes <4-hex>` consent token,
then unmounts + `sudo dd` triggers Touch ID PAM prompt + flashes.

Comment on lines +84 to +98
**Operator effort**: ~5 chars (`zflash`) plus ~8 chars (`yes <4-hex>`) plus 1 fingerprint on the trackpad.

### Step 5 — Verify + boot

After "Flash complete":

- Unplug + replug the USB stick (zflash ejects automatically; re-mount
to verify the EFI partition is present)
- `diskutil list external` should show a new partitioned + bootable
device
- Move USB to the target machine + boot from it (BIOS/firmware
setting: boot from USB first)
- On boot: drops to NixOS installer shell; run `zeta-install <hostname>`
per the disko + bootstrap order in Addison's STARTING-POINT.md

## Common failure modes

| Symptom | Diagnosis | Resolution |
|---|---|---|
| `gh run download` says "no artifacts" | Workflow run too old (>90 days; artifact expired) | Pick a more recent successful run |
| zflash bails: "no Zeta installer ISO found under ~/Downloads/" | ISO not named `zeta-installer-*.iso` OR wrong dir | Rename file OR pass explicit path: `zflash <path/to/iso>` |
| zflash bails: "multiple USB devices found" | Two USB sticks plugged in | Unplug all but the target |
| zflash bails: "device is internal" | Selected `/dev/diskN` is internal SSD | Check `diskutil list external` — USB stick may not have enumerated as external |
| Touch ID prompt doesn't appear | PAM Touch ID not installed | Run `bun full-ai-cluster/tools/zflash-setup.ts` |
| `sudo dd` exit 1 | dd error mid-flash | Check disk + USB controller; partial flash may be on device; re-flash |

## Composes with

- B-0737 (zflash Mac variant — the tool this skill invokes)
- B-0742 (reference k8s stack as Ace PoC — the ISO IS the reference stack)
- B-0728 (destructive-tool authoring contract — flash-usb safety substrate)
- B-0743 (desktop admin consent pattern — Touch ID gate is the consent floor)
- `.claude/skills/flash-cluster-iso-dev-path/SKILL.md` — sibling skill for local-build path
Comment on lines +127 to +131
- `.claude/rules/desktop-admin-consent-via-biometric-plus-small-challenge-i-execute-you-fingerprint.md` — the design pattern this skill instantiates
182 changes: 182 additions & 0 deletions .claude/skills/flash-cluster-iso-dev-path/SKILL.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,182 @@
---
name: flash-cluster-iso-dev-path
description: Flash the Zeta AI-cluster installer ISO to a USB stick using the DEV path — build the ISO LOCALLY from the Nix flake at full-ai-cluster/flake.nix + flash via zflash. Requires Determinate Systems Nix locally. Use when the operator wants to test WIP cluster substrate changes (not yet pushed/CI-built) OR validate determinism (compare local-build SHA vs CI-build SHA). For the consumer path (CI-artifact download; no local Nix) see flash-cluster-iso-consumer-path.
record_source: "skill-creator, B-0737 + B-0740 + B-0742 substrate"
load_datetime: "2026-05-25"
last_updated: "2026-05-25"
status: active
bp_rules_cited: [BP-NN — see .claude/rules/desktop-admin-consent-via-biometric-plus-small-challenge-i-execute-you-fingerprint.md]
---

# Flash Zeta AI-cluster installer ISO — DEV path (local Nix build)

Capability skill. Procedure for the operator (or agent acting on operator's
behalf) who wants to BUILD the cluster installer ISO LOCALLY from the
Nix flake + flash. Composes with B-0737 zflash + B-0740 (DeterminateSystems
Nix as the build-time-deps anchor) + B-0742 reference stack PoC +
B-0728 destructive-tool authoring contract.

## When to use this skill

- Operator is iterating on cluster substrate (`full-ai-cluster/`
files) + wants to test WIP changes before pushing
- Operator wants to validate determinism: build locally + compare
SHA256 vs a CI-built artifact (consumer-path skill provides the
CI side; this is the empirical anchor for the B-0742 "reliable
AI control + determinism" claim)
- Operator wants substrate-honest reproducibility: same flake.lock
input → same ISO output bytes; locally-verifiable
- Operator is doing substrate-engineering work that touches the
`full-ai-cluster/` substrate + needs same-day feedback (vs waiting
for CI)

## When NOT to use this skill

- Operator just wants the LATEST shipping ISO → flash-cluster-iso-consumer-path
- Operator does NOT have local Nix toolchain installed → install via
the DeterminateSystems installer first (see B-0740 Gap 1 anchor),
OR fall back to consumer-path
- Operator is on Linux/Windows → B-0738 / B-0739 (variant scopes; not
yet shipped)
Comment on lines +36 to +40
- Operator is on a low-resource Mac that can't handle a Nix build
(~3-15 min cold; ~1-3 min warm; needs ~10 GB free disk for the
Nix store) → use consumer-path

## Prerequisites

- macOS (per zflash; Touch ID-capable Mac recommended)
- `bun` installed (per `tools/setup/macos.sh`)
- **DeterminateSystems Nix installer** ran locally (per B-0740 Gap 1
anchor — Determinate Systems' installer is the canonical Mac Nix
install path; CI uses `DeterminateSystems/nix-installer-action`
for parity); install URL: <https://determinate.systems/posts/determinate-nix-installer/>
- `zflash` + `zflash-setup` substrate from B-0737 merged on origin/main
- One-time zflash setup already done: `bun full-ai-cluster/tools/zflash-setup.ts
--install-alias` ran successfully + Touch ID PAM installed
Comment on lines +53 to +55
- USB stick (115 GiB - 256 GiB recommended)
- Working tree on a Zeta branch (typically `main` for stable builds;
may be a feature branch for WIP testing)

## Procedure

### Step 1 — Verify Nix is available

```bash
nix --version # should show recent Nix; Determinate Systems ships v2.x
nix flake metadata full-ai-cluster --json --no-write-lock-file \
| jq '{description, lastModified, revision}'
```

If `nix` not found, install via the Determinate Systems installer FIRST
(see Prerequisites). If first-run, expect Nix to take a few minutes to
initialize substrate.

### Step 2 — Build the ISO locally

```bash
cd full-ai-cluster
nix build .#installer-iso --print-out-paths
```

(Adjust output name if the flake exposes `iso` or another attr instead
of `installer-iso`; check `nix flake show .` to inventory available
outputs.)

First build: ~10-15 min (cold Nix substrate; downloads base packages).
Subsequent builds with unchanged inputs: ~1-3 min (warm; cache hits).
Output ISO lands at `./result/iso/zeta-installer-<version>.iso` (or
similar; the exact path is in `nix build`'s `--print-out-paths`).

### Step 3 — Compute SHA256 + copy to ~/Downloads/

```bash
ISO_PATH="$(ls -t ./result/iso/zeta-installer-*.iso | head -1)"
shasum -a 256 "$ISO_PATH"
cp "$ISO_PATH" ~/Downloads/zeta-installer-dev-build-$(date +%Y%m%d%H%M%S).iso
```

The SHA256 is the empirical anchor for determinism testing. Compare
against the CI-built ISO's SHA256 (from consumer-path Step 4) — they
SHOULD match if the flake.lock + build environment are identical.
Substrate-honest expectation: small divergence is possible if Nix
substrate (e.g., installer scripts, timestamps) leak into the build;
exact-byte match validates the flake's reproducibility.

### Step 4 — Flash via zflash

Plug in the USB stick. Then:

```bash
zflash
```

(Or, if shell alias not installed: `bun full-ai-cluster/tools/zflash.ts`)

zflash auto-discovers the newest `~/Downloads/zeta-installer-*.iso`
— your local-build wins by mtime over any older CI download. All
hardware sanity rails fire; per-run nonce printed; `yes <4-hex>`
consent token + Touch ID PAM prompt; flash proceeds.

Comment on lines +105 to +119
**Operator effort**: ~5 chars (`zflash`) plus ~8 chars (`yes <4-hex>`) plus 1 fingerprint on the trackpad.

### Step 5 (optional) — Determinism cross-check

If validating B-0742's "reliable AI control + determinism" claim:

```bash
# Local-build SHA (from Step 3):
shasum -a 256 ~/Downloads/zeta-installer-dev-build-*.iso

# CI-build SHA (download via consumer-path Step 3, then):
shasum -a 256 ~/Downloads/zeta-installer-24.11.iso

# Compare. Substrate-honest expectations:
# - EXACT match: flake is fully deterministic; ship it
# - Mismatch but functionally-equivalent (boots same; same OS state):
# investigate which substrate-input leaks (timestamps, locale, etc.)
# - Functional mismatch: flake has nondeterminism bug; substrate-engineering
# work required
```

Document findings in `docs/research/2026-XX-XX-reference-stack-determinism-poc.md`
per B-0742 Scope item 4.

### Step 6 — Verify + boot

Same as consumer-path Step 5.

## Common failure modes

| Symptom | Diagnosis | Resolution |
|---|---|---|
| `nix: command not found` | DeterminateSystems Nix not installed | Install via <https://determinate.systems/posts/determinate-nix-installer/> |
| `nix build` fails: "evaluating flake" error | Flake syntax issue OR missing input | `nix flake check full-ai-cluster --no-write-lock-file` to inventory issues |
| `nix build` fails: "out of disk space" | Nix store grew too large | `nix store gc` to garbage-collect; needs ~10 GB free |
| Build succeeds but `./result/iso/` is empty | Flake output name mismatch | `nix flake show .` to inventory available outputs |
| Local SHA ≠ CI SHA | Substrate input divergence (timestamp / locale / Nix substrate version) | Investigate; document in determinism-PoC research doc per B-0742 |
| zflash auto-discovery picks wrong ISO | Older CI ISO has newer mtime than local build (unlikely; possible if `cp -p` preserved old timestamps) | Pass explicit path: `zflash ~/Downloads/zeta-installer-dev-build-*.iso` |

## Composes with

- B-0737 (zflash Mac variant — the flash tool this skill invokes)
- B-0740 (Determinate Systems Nix anchor — the build-time-deps Gap 1 entry)
- B-0742 (reference k8s stack as Ace PoC — the ISO IS the reference stack;
this skill enables the local-build leg of the determinism PoC)
- B-0728 (destructive-tool authoring contract — flash-usb safety substrate)
- B-0743 (desktop admin consent pattern — Touch ID gate is the consent floor)
- `.claude/skills/flash-cluster-iso-consumer-path/SKILL.md` — sibling skill for CI-artifact path
Comment on lines +161 to +167
- `.github/workflows/build-ai-cluster-iso.yml` — the CI workflow that produces the comparison artifact

## Why both skills exist

Per the B-0742 reference-stack-as-Ace-PoC substrate: validating "reliable
AI control over all the package managers, deterministically + declaratively"
requires demonstrating BOTH paths produce equivalent results. The
consumer-path proves the CI substrate works for downstream operators;
the dev-path proves local reproducibility + the determinism floor.
Together they establish the empirical anchor for the broader Ace
distribution claim (B-0288 + B-0247 + the OPERATOR-SELF-CLAIMED
trajectory).

Per `.claude/rules/default-to-both.md`: consumer AND dev paths are
both first-class; not either-or; operator picks per scope.
Loading