Fix GRUB splash: convert bee-logo.png from RGBA to RGB

GRUB does not support RGBA PNG (color_type=6) — loading it returns a
null bitmap, triggering "null src bitmap in grub_video_bitmap_create_scaled".
Alpha channel composited onto black background (#000000 matches desktop-color).

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

audit/internal/collector/storage.go

@@ -250,6 +250,8 @@ func enrichWithSmartctl(dev lsblkDevice) schema.HardwareStorage {
 	}
 
 	var info smartctlInfo
+	var raw map[string]any
+	_ = json.Unmarshal(out, &raw)
 	if err := json.Unmarshal(out, &info); err == nil {
 		if v := cleanDMIValue(info.ModelName); v != "" {
 			s.Model = &v
@@ -302,8 +304,11 @@ func enrichWithSmartctl(dev lsblkDevice) schema.HardwareStorage {
 				value := float64(attr.Raw.Value)
 				s.LifeRemainingPct = &value
 			case 241:
-				value := attr.Raw.Value
+				value := smartLBAsToBytes(attr.Raw.Value)
 				s.WrittenBytes = &value
+			case 242:
+				value := smartLBAsToBytes(attr.Raw.Value)
+				s.ReadBytes = &value
 			case 197:
 				pending = attr.Raw.Value
 				s.CurrentPendingSectors = &pending
@@ -321,6 +326,7 @@ func enrichWithSmartctl(dev lsblkDevice) schema.HardwareStorage {
 			offlineUncorrectable: uncorrectable,
 			lifeRemainingPct:     lifeRemaining,
 		}
+		applySCSISmartctlTelemetry(&s, raw, &status)
 		setStorageHealthStatus(&s, status)
 		return s
 	}
@@ -477,6 +483,127 @@ func nvmeDataUnitsToBytes(units int64) int64 {
 	return units * 512000
 }
 
+func smartLBAsToBytes(lbas int64) int64 {
+	if lbas <= 0 {
+		return 0
+	}
+	return lbas * 512
+}
+
+func applySCSISmartctlTelemetry(s *schema.HardwareStorage, raw map[string]any, status *storageHealthStatus) {
+	if s == nil || len(raw) == 0 {
+		return
+	}
+	if v, ok := firstInt64(raw,
+		"path:power_on_time.hours",
+		"path:accumulated_power_on_time.hours",
+		"path:power_on_time.hour",
+		"path:accumulated_power_on_time.hour",
+	); ok && v > 0 && s.PowerOnHours == nil {
+		s.PowerOnHours = &v
+	}
+	if v, ok := firstInt64(raw,
+		"path:power_cycle_count",
+		"path:start_stop_cycle_count",
+		"path:accumulated_start_stop_cycles",
+	); ok && v > 0 && s.PowerCycles == nil {
+		s.PowerCycles = &v
+	}
+	if v, ok := firstInt64(raw,
+		"path:scsi_grown_defect_list",
+		"path:grown_defect_list",
+	); ok && v > 0 && s.ReallocatedSectors == nil {
+		s.ReallocatedSectors = &v
+		if status != nil && status.reallocatedSectors == 0 {
+			status.reallocatedSectors = v
+		}
+	}
+	if v, ok := firstInt64(raw,
+		"path:percentage_used_endurance_indicator",
+		"path:scsi_percentage_used_endurance_indicator",
+	); ok && v > 0 {
+		if s.LifeUsedPct == nil {
+			fv := float64(v)
+			s.LifeUsedPct = &fv
+		}
+		if s.LifeRemainingPct == nil && v <= 100 {
+			remaining := float64(100 - v)
+			s.LifeRemainingPct = &remaining
+			if status != nil && status.lifeRemainingPct == 0 {
+				status.lifeRemainingPct = int64(remaining)
+			}
+		}
+	}
+	blockSize, hasBlockSize := firstInt64(raw,
+		"path:logical_block_size",
+		"path:block_size",
+		"path:user_capacity.block_size",
+	)
+	if hasBlockSize && blockSize > 0 {
+		if v, ok := firstInt64(raw,
+			"path:logical_blocks_written",
+			"path:total_lbas_written",
+		); ok && v > 0 && s.WrittenBytes == nil {
+			bytes := v * blockSize
+			s.WrittenBytes = &bytes
+		}
+		if v, ok := firstInt64(raw,
+			"path:logical_blocks_read",
+			"path:total_lbas_read",
+		); ok && v > 0 && s.ReadBytes == nil {
+			bytes := v * blockSize
+			s.ReadBytes = &bytes
+		}
+	}
+}
+
+func firstInt64(root map[string]any, candidates ...string) (int64, bool) {
+	for _, candidate := range candidates {
+		if !strings.HasPrefix(candidate, "path:") {
+			continue
+		}
+		path := strings.TrimPrefix(candidate, "path:")
+		if v, ok := nestedInt64(root, strings.Split(path, ".")); ok {
+			return v, true
+		}
+	}
+	return 0, false
+}
+
+func nestedInt64(root map[string]any, path []string) (int64, bool) {
+	var current any = root
+	for _, key := range path {
+		obj, ok := current.(map[string]any)
+		if !ok {
+			return 0, false
+		}
+		current, ok = obj[key]
+		if !ok {
+			return 0, false
+		}
+	}
+	switch v := current.(type) {
+	case float64:
+		return int64(v), true
+	case float32:
+		return int64(v), true
+	case int:
+		return int64(v), true
+	case int64:
+		return v, true
+	case int32:
+		return int64(v), true
+	case json.Number:
+		n, err := v.Int64()
+		return n, err == nil
+	case string:
+		n, err := strconv.ParseInt(strings.TrimSpace(v), 10, 64)
+		return n, err == nil
+	default:
+		return 0, false
+	}
+}
+
 type storageHealthStatus struct {
 	hasOverall           bool
 	overallPassed        bool

audit/internal/collector/storage_scsi_test.go

@@ -0,0 +1,89 @@
+package collector
+
+import (
+	"testing"
+
+	"bee/audit/internal/schema"
+)
+
+func TestApplySCSISmartctlTelemetry(t *testing.T) {
+	t.Parallel()
+
+	raw := map[string]any{
+		"power_on_time": map[string]any{
+			"hours": float64(32123),
+		},
+		"accumulated_start_stop_cycles":       float64(17),
+		"scsi_grown_defect_list":              float64(4),
+		"percentage_used_endurance_indicator": float64(12),
+		"logical_block_size":                  float64(4096),
+		"logical_blocks_written":              float64(1000),
+		"logical_blocks_read":                 float64(2000),
+	}
+
+	var disk schema.HardwareStorage
+	status := storageHealthStatus{}
+	applySCSISmartctlTelemetry(&disk, raw, &status)
+
+	if disk.PowerOnHours == nil || *disk.PowerOnHours != 32123 {
+		t.Fatalf("power_on_hours=%v want 32123", disk.PowerOnHours)
+	}
+	if disk.PowerCycles == nil || *disk.PowerCycles != 17 {
+		t.Fatalf("power_cycles=%v want 17", disk.PowerCycles)
+	}
+	if disk.ReallocatedSectors == nil || *disk.ReallocatedSectors != 4 {
+		t.Fatalf("reallocated=%v want 4", disk.ReallocatedSectors)
+	}
+	if disk.WrittenBytes == nil || *disk.WrittenBytes != 4096000 {
+		t.Fatalf("written_bytes=%v want 4096000", disk.WrittenBytes)
+	}
+	if disk.ReadBytes == nil || *disk.ReadBytes != 8192000 {
+		t.Fatalf("read_bytes=%v want 8192000", disk.ReadBytes)
+	}
+	if disk.LifeUsedPct == nil || *disk.LifeUsedPct != 12 {
+		t.Fatalf("life_used_pct=%v want 12", disk.LifeUsedPct)
+	}
+	if disk.LifeRemainingPct == nil || *disk.LifeRemainingPct != 88 {
+		t.Fatalf("life_remaining_pct=%v want 88", disk.LifeRemainingPct)
+	}
+	if status.reallocatedSectors != 4 {
+		t.Fatalf("status.reallocated=%d want 4", status.reallocatedSectors)
+	}
+	if status.lifeRemainingPct != 88 {
+		t.Fatalf("status.life_remaining_pct=%d want 88", status.lifeRemainingPct)
+	}
+}
+
+func TestApplySCSISmartctlTelemetryDoesNotOverwriteExistingValues(t *testing.T) {
+	t.Parallel()
+
+	powerOnHours := int64(10)
+	writtenBytes := int64(20)
+	lifeRemaining := 30.0
+	disk := schema.HardwareStorage{
+		PowerOnHours:     &powerOnHours,
+		WrittenBytes:     &writtenBytes,
+		LifeRemainingPct: &lifeRemaining,
+	}
+	raw := map[string]any{
+		"power_on_time":                       map[string]any{"hours": float64(999)},
+		"logical_block_size":                  float64(512),
+		"logical_blocks_written":              float64(999),
+		"percentage_used_endurance_indicator": float64(50),
+	}
+
+	applySCSISmartctlTelemetry(&disk, raw, nil)
+
+	if *disk.PowerOnHours != 10 {
+		t.Fatalf("power_on_hours overwritten: got %d want 10", *disk.PowerOnHours)
+	}
+	if *disk.WrittenBytes != 20 {
+		t.Fatalf("written_bytes overwritten: got %d want 20", *disk.WrittenBytes)
+	}
+	if *disk.LifeRemainingPct != 30 {
+		t.Fatalf("life_remaining_pct overwritten: got %v want 30", *disk.LifeRemainingPct)
+	}
+	if disk.LifeUsedPct == nil || *disk.LifeUsedPct != 50 {
+		t.Fatalf("life_used_pct=%v want 50", disk.LifeUsedPct)
+	}
+}

audit/internal/collector/storage_telemetry_test.go

@@ -0,0 +1,25 @@
+package collector
+
+import "testing"
+
+func TestSmartLBAsToBytes(t *testing.T) {
+	t.Parallel()
+
+	tests := []struct {
+		name string
+		lbas int64
+		want int64
+	}{
+		{name: "zero", lbas: 0, want: 0},
+		{name: "single lba", lbas: 1, want: 512},
+		{name: "multiple lbas", lbas: 2048, want: 1048576},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			if got := smartLBAsToBytes(tt.lbas); got != tt.want {
+				t.Fatalf("smartLBAsToBytes(%d)=%d want %d", tt.lbas, got, tt.want)
+			}
+		})
+	}
+}

audit/internal/schema/hardware_test.go

@@ -44,3 +44,48 @@ func TestHardwareSnapshotMarshalsNewContractFields(t *testing.T) {
 		t.Fatalf("missing event_logs payload: %s", text)
 	}
 }
+
+func TestHardwareSnapshotMarshalsStorageTelemetryFields(t *testing.T) {
+	powerOnHours := int64(12450)
+	writtenBytes := int64(9876543210)
+	readBytes := int64(1234567890)
+	lifeRemainingPct := 91.0
+
+	payload := HardwareIngestRequest{
+		CollectedAt: "2026-03-15T15:00:00Z",
+		Hardware: HardwareSnapshot{
+			Board: HardwareBoard{SerialNumber: "SRV-001"},
+			Storage: []HardwareStorage{
+				{
+					SerialNumber:     stringPtr("DISK-001"),
+					Model:            stringPtr("TestDisk"),
+					PowerOnHours:     &powerOnHours,
+					WrittenBytes:     &writtenBytes,
+					ReadBytes:        &readBytes,
+					LifeRemainingPct: &lifeRemainingPct,
+				},
+			},
+		},
+	}
+
+	data, err := json.Marshal(payload)
+	if err != nil {
+		t.Fatalf("marshal: %v", err)
+	}
+	text := string(data)
+	for _, needle := range []string{
+		`"storage":[{`,
+		`"power_on_hours":12450`,
+		`"written_bytes":9876543210`,
+		`"read_bytes":1234567890`,
+		`"life_remaining_pct":91`,
+	} {
+		if !strings.Contains(text, needle) {
+			t.Fatalf("missing %q in payload: %s", needle, text)
+		}
+	}
+}
+
+func stringPtr(v string) *string {
+	return &v
+}

bible-local/README.md

@@ -10,4 +10,4 @@ Generic engineering rules live in `bible/rules/patterns/`.
 | `architecture/system-overview.md` | What bee does, scope, tech stack |
 | `architecture/runtime-flows.md` | Boot sequence, audit flow, service order |
 | `docs/hardware-ingest-contract.md` | Current Reanimator hardware ingest JSON contract |
-| `decisions/` | Architectural decision log |
+| `decisions/` | Architectural decision log, including read-only submodule policy |

bible-local/architecture/system-overview.md

@@ -58,6 +58,8 @@ Fills gaps where Redfish/logpile is blind:
 - `bee` should populate current component state, hardware inventory, telemetry, and `status_checked_at`.
 - Historical status transitions and component replacement logic belong to the centralized ingest/lifecycle system, not to `bee`.
 - Contract fields that have no honest local source on a generic Linux host may remain empty.
+- Embedded submodules such as `internal/chart/` and `bible/` are read-only for `bee` feature work.
+- If the UI needs extra information, `bee` must emit it through the standard audit JSON contract rather than patching `chart`.
 
 ## Tech stack
 
@@ -101,7 +103,7 @@ Fills gaps where Redfish/logpile is blind:
 | `iso/builder/` | ISO build scripts and `live-build` profile |
 | `iso/overlay/` | Source overlay copied into a staged build overlay |
 | `iso/vendor/` | Optional pre-built vendor binaries (storcli64, sas2ircu, sas3ircu, arcconf, ssacli, …) |
-| `internal/chart/` | Git submodule with `reanimator/chart`, embedded into `bee web` |
+| `internal/chart/` | Git submodule with `reanimator/chart`, embedded into `bee web`; update by submodule pointer only, never by local `bee`-specific edits |
 | `iso/builder/VERSIONS` | Pinned versions: Debian, Go, NVIDIA driver, kernel ABI |
 | `iso/builder/smoketest.sh` | Post-boot smoke test — run via SSH to verify live ISO |
 | `iso/overlay/etc/profile.d/bee.sh` | tty1 welcome message with web UI URLs |

bible-local/decisions/2026-04-29-read-only-embedded-submodules.md

@@ -0,0 +1,39 @@
+# Decision: Treat embedded submodules as read-only
+
+## Context
+
+`bee` embeds external git submodules such as:
+
+- `internal/chart/` — `reanimator/chart`, a generic read-only viewer for Reanimator JSON snapshots
+- `bible/` — shared engineering rules and contracts
+
+These repositories are reused by other projects. A local feature request in `bee`
+must not be solved by silently changing shared submodule behavior.
+
+The concrete failure mode here was attempting to add project-specific storage
+telemetry presentation by editing `internal/chart/`. That couples a shared viewer
+to one host application's needs and creates hidden cross-project regressions.
+
+## Decision
+
+Embedded submodules are read-only from the point of view of `bee`.
+
+- Do not implement `bee`-specific behavior by editing `internal/chart/`.
+- Do not implement `bee`-specific behavior by editing `bible/`.
+- If `bee` needs new data in the report, produce it in the standard audit JSON
+  emitted by `bee` itself.
+- `chart` must continue to consume the canonical snapshot as an external viewer,
+  without host-specific forks.
+- Updating a submodule pointer to an upstream commit is allowed.
+- Carrying local unmerged submodule commits as part of a `bee` feature is forbidden.
+
+## Consequences
+
+- Audit/report features must be expressed through the contract in
+  `bible-local/docs/hardware-ingest-contract.md`.
+- `bee` owns collection, normalization, and serialization of storage telemetry in
+  `hardware.storage[]`.
+- `chart` remains a pure visualization module that reads the snapshot it is given.
+- If a capability is genuinely missing in a shared submodule, it must be proposed
+  and landed upstream as a generic change first, then pulled into `bee` via a
+  normal submodule update.

bible-local/decisions/README.md

@@ -6,3 +6,4 @@ One file per decision, named `YYYY-MM-DD-short-topic.md`.
 |---|---|---|
 | 2026-03-05 | Use NVIDIA proprietary driver | active |
 | 2026-04-01 | Treat memtest as explicit ISO content | active |
+| 2026-04-29 | Treat embedded submodules as read-only | active |

bible-local/rules/patterns/ascii-safe-text/contract.md

@@ -0,0 +1,31 @@
+# Contract: ASCII-Safe Text in Scripts and Boot Configs
+
+Version: 1.0
+
+## Principle
+
+Shell scripts, bootloader configs, and any text rendered on serial/SOL consoles must use only printable ASCII characters. Non-ASCII Unicode — including typographic punctuation such as the em-dash (U+2014 `—`), en-dash (U+2013 `–`), curly quotes, and ellipsis (U+2026 `…`) — breaks rendering on serial terminals, GRUB text/serial mode, IPMI SOL, and tooling that assumes ASCII.
+
+## Rules
+
+- Never use em-dash (`—`) or en-dash (`–`) in any shell script, GRUB config, syslinux/isolinux config, or service unit file. Use ASCII double-hyphen `--` or single hyphen `-` instead.
+- Never use curly quotes (`"` `"` `'` `'`) in shell scripts or configs. Use straight quotes `"` and `'`.
+- Never use the Unicode ellipsis (`…`). Use `...`.
+- GRUB `menuentry` and `submenu` titles must be ASCII-only — GRUB serial terminal output is ASCII; non-ASCII characters render as garbage or are dropped.
+- Comments in GRUB theme files (`.txt`) must also be ASCII-only, as GRUB may parse the entire file.
+
+## Why
+
+GRUB renders menus over both `gfxterm` (graphical, Unicode-capable) and `serial` (ASCII-only) simultaneously when `terminal_output gfxterm serial` is set. The serial output — used by IPMI SOL and BMC remote consoles — cannot display multi-byte UTF-8 sequences and shows raw bytes or drops characters. A menuentry title `"EASY-BEE — GSP=off"` appears as `"EASY-BEE â€" GSP=off"` or `"EASY-BEE  GSP=off"` on SOL, making the menu unreadable.
+
+## Anti-patterns
+
+- `menuentry "EASY-BEE — GSP=off"` — em-dash in GRUB title
+- `# bee logo — centered` — em-dash in GRUB theme comment
+- `echo "done — reboot"` in a shell script displayed over serial
+
+## Correct form
+
+- `menuentry "EASY-BEE -- GSP=off"`
+- `# bee logo - centered`
+- `echo "done - reboot"`

iso/README.md

@@ -31,10 +31,10 @@ Build with explicit SSH keys baked into the ISO:
 sh iso/builder/build-in-container.sh --authorized-keys ~/.ssh/id_ed25519.pub
 ```
 
-Rebuild the builder image:
+Force a clean rebuild of the builder image and build caches:
 
 ```sh
-sh iso/builder/build-in-container.sh --rebuild-image
+sh iso/builder/build-in-container.sh --clean-build
 ```
 
 Use a custom cache directory:

iso/builder/build-in-container.sh

@@ -10,7 +10,6 @@ IMAGE_TAG="${BEE_BUILDER_IMAGE:-bee-iso-builder}"
 BUILDER_PLATFORM="${BEE_BUILDER_PLATFORM:-linux/amd64}"
 CACHE_DIR="${BEE_BUILDER_CACHE_DIR:-${REPO_ROOT}/dist/container-cache}"
 AUTH_KEYS=""
-REBUILD_IMAGE=0
 CLEAN_CACHE=0
 VARIANT="all"
 
@@ -22,17 +21,12 @@ while [ $# -gt 0 ]; do
             CACHE_DIR="$2"
             shift 2
             ;;
-        --rebuild-image)
-            REBUILD_IMAGE=1
-            shift
-            ;;
         --authorized-keys)
             AUTH_KEYS="$2"
             shift 2
             ;;
         --clean-build)
             CLEAN_CACHE=1
-            REBUILD_IMAGE=1
             shift
             ;;
         --variant)
@@ -41,7 +35,7 @@ while [ $# -gt 0 ]; do
             ;;
         *)
             echo "unknown arg: $1" >&2
-            echo "usage: $0 [--cache-dir /path] [--rebuild-image] [--clean-build] [--authorized-keys /path/to/authorized_keys] [--variant nvidia|nvidia-legacy|amd|nogpu|all]" >&2
+            echo "usage: $0 [--cache-dir /path] [--clean-build] [--authorized-keys /path/to/authorized_keys] [--variant nvidia|nvidia-legacy|amd|nogpu|all]" >&2
             exit 1
             ;;
     esac
@@ -105,7 +99,7 @@ image_matches_platform() {
 }
 
 NEED_BUILD_IMAGE=0
-if [ "$REBUILD_IMAGE" = "1" ]; then
+if [ "$CLEAN_CACHE" = "1" ]; then
     NEED_BUILD_IMAGE=1
 elif ! "$CONTAINER_TOOL" image inspect "${IMAGE_REF}" >/dev/null 2>&1; then
     NEED_BUILD_IMAGE=1

iso/builder/build.sh

@@ -848,6 +848,72 @@ reset_live_build_stage() {
     done
 }
 
+# Marker written after every successful full lb build for this variant
+FULL_BUILD_MARKER="${BUILD_WORK_DIR}/.bee-full-build-marker"
+
+# Returns 0 if full lb build is needed, 1 if fast-path is safe.
+# Fast-path is safe when only light files changed since the last full build
+# (Go source, overlay scripts/configs). Heavy changes (VERSIONS, package lists,
+# hooks, archives, Dockerfile, auto/config) require a full lb build.
+needs_full_build() {
+    [ -f "${FULL_BUILD_MARKER}" ]                                        || return 0
+    [ -f "${BUILD_WORK_DIR}/binary/live/filesystem.squashfs" ]           || return 0
+    [ -f "${BUILD_WORK_DIR}/live-image-amd64.hybrid.iso" ]               || return 0
+
+    _heavy=$(find \
+        "${BUILDER_DIR}/VERSIONS" \
+        "${BUILDER_DIR}/auto/config" \
+        "${BUILDER_DIR}/Dockerfile" \
+        "${BUILDER_DIR}/config/package-lists" \
+        "${BUILDER_DIR}/config/hooks" \
+        "${BUILDER_DIR}/config/archives" \
+        -newer "${FULL_BUILD_MARKER}" 2>/dev/null | head -1)
+
+    if [ -n "$_heavy" ]; then
+        echo "=== full build required: heavy config changed: $(basename "$_heavy") ==="
+        return 0
+    fi
+
+    return 1
+}
+
+# Fast-path: unsquash existing filesystem, rsync overlay on top, repack.
+# Requires ~10 GB free in BEE_CACHE_DIR for the unpacked squashfs.
+fast_path_repack_squashfs() {
+    _sq="${BUILD_WORK_DIR}/binary/live/filesystem.squashfs"
+    _tmp="${BEE_CACHE_DIR}/fast-unsquash-${BUILD_VARIANT}"
+    echo "=== fast-path: unsquash ($(du -sh "$_sq" | cut -f1) compressed) ==="
+    rm -rf "$_tmp"
+    unsquashfs -d "$_tmp" "$_sq"
+    echo "=== fast-path: syncing overlay stage ==="
+    rsync -a --checksum "${OVERLAY_STAGE_DIR}/" "$_tmp/"
+    echo "=== fast-path: repacking squashfs ==="
+    _sq_new="${_sq}.new"
+    rm -f "$_sq_new"
+    mksquashfs "$_tmp" "$_sq_new" -comp zstd -b 1048576 -noappend -no-progress
+    mv "$_sq_new" "$_sq"
+    rm -rf "$_tmp"
+    echo "=== fast-path: squashfs repacked ($(du -sh "$_sq" | cut -f1)) ==="
+}
+
+# Fast-path: rebuild ISO by replacing only live/filesystem.squashfs via xorriso.
+# Boot structure (El Torito, EFI, MBR hybrid) is replayed from the prior ISO.
+fast_path_rebuild_iso() {
+    _sq="${BUILD_WORK_DIR}/binary/live/filesystem.squashfs"
+    _prior="${BUILD_WORK_DIR}/live-image-amd64.hybrid.iso"
+    _new="${BUILD_WORK_DIR}/live-image-amd64.hybrid.iso.new"
+    echo "=== fast-path: rebuilding ISO with xorriso ==="
+    rm -f "$_new"
+    xorriso \
+        -indev  "$_prior" \
+        -outdev "$_new" \
+        -map    "$_sq" /live/filesystem.squashfs \
+        -boot_image any replay \
+        -commit
+    mv "$_new" "$_prior"
+    echo "=== fast-path: ISO rebuilt ==="
+}
+
 recover_iso_memtest() {
     lb_dir="$1"
     iso_path="$2"
@@ -1487,6 +1553,21 @@ if [ -f "${LB_INCLUDES}/root/.ssh/authorized_keys" ]; then
     chmod 600 "${LB_INCLUDES}/root/.ssh/authorized_keys"
 fi
 
+# --- auto fast-path: squashfs surgery if only light files changed ---
+if ! needs_full_build; then
+    echo "=== fast-path build (no heavy config changes since last full build) ==="
+    fast_path_repack_squashfs
+    fast_path_rebuild_iso
+    ISO_RAW="${LB_DIR}/live-image-amd64.hybrid.iso"
+    validate_iso_live_boot_entries "$ISO_RAW"
+    validate_iso_nvidia_runtime "$ISO_RAW"
+    cp "$ISO_RAW" "$ISO_OUT"
+    echo ""
+    echo "=== done (${BUILD_VARIANT}, fast-path) ==="
+    echo "ISO: $ISO_OUT"
+    exit 0
+fi
+
 # --- build ISO using live-build ---
 echo ""
 echo "=== building ISO (variant: ${BUILD_VARIANT}) ==="
@@ -1535,6 +1616,7 @@ if [ -f "$ISO_RAW" ]; then
     validate_iso_live_boot_entries "$ISO_RAW"
     validate_iso_nvidia_runtime "$ISO_RAW"
     cp "$ISO_RAW" "$ISO_OUT"
+    touch "${FULL_BUILD_MARKER}"
     echo ""
     echo "=== done (${BUILD_VARIANT}) ==="
     echo "ISO: $ISO_OUT"