scripts/docs: fail loudly, fix names, document bring-up-only status

install-forgefirm.sh completed silently broken when the download, flash
write, mount or uEnv rewrite failed - add die() checks around every
critical step (audit N13/M12) and download the release asset under the
exact Scarthgap artifact name (forgefirm-image-glowforge.rootfs.wic.gz)
so uploads need no renaming. ffboot no longer depends on the never-
provisioned /etc/fw_env_mmcblk2.config: it falls back to
/etc/fw_env.config (which both the factory and ForgeFIRM images ship,
pointing at the eMMC env) and checks fw_setenv results (audit N16).
BUILD.md gets the real artifact name and marks the built u-boot
reference-only; INSTALL.md drops the stale script/ogboot names and the
cloud-connect promise, stating the image is bring-up-only (audit N11).

BUILD.md

@@ -53,9 +53,14 @@ kas fetches the upstream layers into `forgefirm/layers/`, builds in
 `forgefirm/build/`, and produces the bootable image at:
 
 ```
-forgefirm/build/tmp/deploy/images/glowforge/forgefirm-image-glowforge.wic.gz
+forgefirm/build/tmp/deploy/images/glowforge/forgefirm-image-glowforge.rootfs.wic.gz
 ```
 
+(The `u-boot-glowforge.imx` also deployed there is **reference-only**: every
+supported install/boot flow keeps the factory bootloader on the eMMC. Its env
+Kconfig now matches the factory layout — 0x80000 primary / 0x82000 redundant —
+but it is not wired into any install path and flashing it is unsupported.)
+
 For exact, reproducible layer versions, generate a lockfile once:
 
 ```console
@@ -69,7 +74,7 @@ and the Scarthgap migration backlog.
 
 ```console
 cd build/tmp/deploy/images/glowforge
-sudo zcat forgefirm-image-glowforge.wic.gz | dd of=/dev/sdX bs=1M
+sudo zcat forgefirm-image-glowforge.rootfs.wic.gz | dd of=/dev/sdX bs=1M
 ```
 
 To install onto the factory eMMC (dual-boot with the Glowforge firmware), see

INSTALL.md

@@ -47,7 +47,7 @@ After these steps have completed, you will be prompted to reboot:
 ### Stage 2
 After the device reboots, login as root and run the script again:
 ```bash
-./install-openglow.sh
+./install-forgefirm.sh
 ```
 
 This will complete the installation process by performing the following steps:
@@ -56,7 +56,7 @@ This will complete the installation process by performing the following steps:
 * Restarting the network services.
 * Downloads the [latest OpenGlow image](https://github.com/ScottW514/forgefirm/releases) from GitHub.
 * Writes the OpenGlow image to the flash (this takes a bit, be patient)
-* Installs the ```/data/ogboot``` utility so you can switch between OpenGlow and factory images.
+* Installs the ```/data/ffboot``` utility so you can switch between ForgeFIRM and factory images.
 
 Hit any key to reboot into your fancy new OpenGlow image.
 
@@ -68,7 +68,12 @@ Hit any key to reboot into your fancy new OpenGlow image.
 
 Login is ```root```, no password.  You can also connect via SSH - same user, no password (obviously, you should change this).
 
-The unit will automatically connect to the Glowforge service upon boot, and begin the homing sequence. You can use it from the GFUI like normal (mostly, don't try fancy stuff like setting the focus, snap marks, pass through, or the calibration tool).
+> **Current status: this image is bring-up-only.** No controller or cloud
+> client starts at boot — the machine boots to an idle shell with the kernel
+> driver, hardware libraries (gfhardware/gfutilities), and camera tooling
+> installed. The grblHAL controller (forgectrl) is under development; the
+> legacy cloud client (gfui-client) is deliberately not shipped. Nothing
+> homes, moves, or connects anywhere until you start it yourself.
 
 You can easily switch back and forth between factory and OpenGlow images:
 ```bash

scripts/ffboot

@@ -70,18 +70,27 @@ case "$1" in
     exit 2
 esac
 
-if [ -d "/factory" ]; then
+# The env always lives on the eMMC (mmcblk2 0x80000/0x82000). On the factory
-  FWCONFIG="/etc/fw_env.config"
+# firmware and on the ForgeFIRM image, /etc/fw_env.config already points
-else
+# there; the mmcblk2-specific override is honored if someone provisioned one,
+# but nothing ships it, so fall back rather than failing on a missing file
+# (audit N16).
+if [ -f "/etc/fw_env_mmcblk2.config" ] && [ ! -d "/factory" ]; then
   FWCONFIG="/etc/fw_env_mmcblk2.config"
+else
+  FWCONFIG="/etc/fw_env.config"
+fi
+if [ ! -f "$FWCONFIG" ]; then
+  echo "ERROR: $FWCONFIG not found; cannot switch boot device" >&2
+  exit 1
 fi
 
 MMCROOT="/dev/mmcblk"$(($MMCDEV + 1))"p"$MMCPART
 
 echo "Setting to boot from $MMCROOT"
-fw_setenv -c $FWCONFIG mmcdev $MMCDEV
+fw_setenv -c $FWCONFIG mmcdev $MMCDEV   || { echo "ERROR: fw_setenv mmcdev failed" >&2; exit 1; }
-fw_setenv -c $FWCONFIG mmcpart $MMCPART
+fw_setenv -c $FWCONFIG mmcpart $MMCPART || { echo "ERROR: fw_setenv mmcpart failed" >&2; exit 1; }
-fw_setenv -c $FWCONFIG mmcroot $MMCROOT
+fw_setenv -c $FWCONFIG mmcroot $MMCROOT || { echo "ERROR: fw_setenv mmcroot failed" >&2; exit 1; }
 
 if [ $REBOOT -gt 0 ]; then
   echo "Rebooting..."

scripts/install-forgefirm.sh

@@ -15,6 +15,16 @@ BRIGHT="\033[1;39m"
 RESET="\033[0m"
 ASTERISK="${LIGHTRED}✺${RESET}"
 
+# Abort loudly instead of completing silently broken: several steps below
+# (image download, flash write, uEnv rewrite) used to fail without stopping
+# the install (audit N13/M12/N16).
+die () {
+  echo
+  echo -e "${LIGHTRED}!! INSTALL FAILED:${RESET} $1"
+  echo -e "${LIGHTRED}!! The device was NOT fully installed. Fix the problem and re-run.${RESET}"
+  exit 1
+}
+
 stop_gf_services () {
   echo -n -e "${ASTERISK}Stopping Glowforge services"
   sv stop /sv/glowforge 2>&1 >/dev/null; echo -n "."
@@ -61,19 +71,27 @@ if [ -d "/ogtmp" ]; then
   echo
 
   echo -e "${ASTERISK}Downloading latest OpenGlow/ForgeFIRM image:"
-  curl -L https://github.com/ScottW514/forgefirm/releases/latest/download/forgefirm-image-glowforge.wic.gz --output /data/forgefirm-image-glowforge.wic.gz
+  # Asset name matches the Scarthgap deploy artifact verbatim (rootfs.wic.gz),
-  curl -L https://raw.githubusercontent.com/ScottW514/forgefirm/master/scripts/ffboot --output /data/ffboot
+  # so releases are uploaded without renaming (see kas/README.md release order).
+  curl -fL https://github.com/ScottW514/forgefirm/releases/latest/download/forgefirm-image-glowforge.rootfs.wic.gz --output /data/forgefirm-image-glowforge.rootfs.wic.gz \
+    || die "image download failed"
+  curl -fL https://raw.githubusercontent.com/ScottW514/forgefirm/master/scripts/ffboot --output /data/ffboot \
+    || die "ffboot download failed"
   chmod +x /data/ffboot
   echo
 
   echo -e "${ASTERISK}Writing OpenGlow/ForegFIRM image to flash:"
-  zcat /data/forgefirm-image-glowforge.wic.gz | dd of=/dev/mmcblk2p4 skip=2
+  zcat /data/forgefirm-image-glowforge.rootfs.wic.gz | dd of=/dev/mmcblk2p4 skip=2 \
-  mkdir /data/mnt
+    || die "flash write to /dev/mmcblk2p4 failed"
-  mount /dev/mmcblk2p4 /data/mnt
+  mkdir -p /data/mnt
-  sed -i 's/mmcblk1p1/mmcblk2p4/g' /data/mnt/boot/uEnv.txt
+  mount /dev/mmcblk2p4 /data/mnt || die "mounting the new image failed (bad flash write?)"
-  umount /data/mnt
+  [ -f /data/mnt/boot/uEnv.txt ] \
+    || { umount /data/mnt; die "/boot/uEnv.txt missing from the new image (bad or outdated image)"; }
+  sed -i 's/mmcblk1p1/mmcblk2p4/g' /data/mnt/boot/uEnv.txt \
+    || { umount /data/mnt; die "rewriting uEnv.txt for eMMC boot failed"; }
+  umount /data/mnt || die "unmounting the new image failed"
   rm -rf /data/mnt
-  rm -f /data/forgefirm-image-glowforge.wic.gz
+  rm -f /data/forgefirm-image-glowforge.rootfs.wic.gz
 
   echo 5 > /proc/sys/kernel/printk