Docs: README + W axis docs cover macOS build/flash and new UI

- README.md (was a one-liner): describe the layout, the macOS quick
  path including the esbuild platform-pin gotcha, and how to flash
  with curl or 'make update'.
- docs/AUX_W_AXIS.md: document the new Control jog row layout, the
  Settings 'W Axis (auxcnc)' section, and list the additional UI
  files touched by this fork.

README.md

@@ -1 +1,122 @@
-#OneFinity CNC Controller Firmware
+# OneFinity CNC Controller Firmware (W-axis fork)
+
+This is the OneFinity / Buildbotics bbctrl firmware with a virtual W
+axis driven by an auxcnc ESP32 over USB serial. See
+[docs/AUX_W_AXIS.md](docs/AUX_W_AXIS.md) for the design and config.
+
+## Layout
+
+```
+src/avr/        AVR firmware (motion controller, AtxMega)
+src/boot/       AVR bootloader
+src/bbserial/   Linux kernel module for the bbserial driver
+src/py/bbctrl/  Python control daemon (Tornado + websockets)
+src/js/         Vue.js UI (legacy)
+src/svelte-components/  Newer Svelte UI for dialogs and settings
+src/pug/        Pug templates compiled into build/http/index.html
+src/resources/  Static assets and config templates
+scripts/        Install / update / RPi build helpers
+docs/           Architecture, dev setup, W-axis docs
+```
+
+## Build & flash (quick path, macOS or Linux)
+
+The full build (`make`) requires `avr-gcc`, but the controller and UI
+only depend on the Python + web parts. If you're shipping a UI/Python
+change you don't need the AVR toolchain.
+
+### Prerequisites
+
+- Node.js (any recent LTS) with npm
+- Python 3 with setuptools
+- `npm install` once at the project root (this is wired into the
+  `node_modules` Make target, but on a fresh checkout it's clearer to
+  do it explicitly)
+
+```bash
+npm install
+(cd src/svelte-components && npm install)
+```
+
+#### macOS gotcha: esbuild platform pin
+
+The Pi build leaves `node_modules/esbuild` pinned to
+`linux-arm64`, which won't run on Darwin. If `npm run build` inside
+`src/svelte-components` complains about esbuild, reinstall it for the
+host:
+
+```bash
+cd src/svelte-components
+rm -rf node_modules/esbuild
+npm install esbuild@0.14.49 --no-save
+```
+
+(Use the version that matches `package-lock.json`.)
+
+### Build the web UI + Python sdist
+
+```bash
+# Build the Svelte components
+(cd src/svelte-components && npm run build)
+
+# Render pug templates and copy assets into build/http
+make all          # AVR step will fail without avr-gcc; safe to ignore
+                  # if you didn't change anything under src/avr or src/boot
+
+# Package
+./setup.py sdist
+ls dist/bbctrl-*.tar.bz2
+```
+
+`make pkg` is the canonical target but it tries to build AVR first. On
+hosts without avr-gcc, run the steps above directly.
+
+If `bbctrl-*.tar.bz2` is missing `src/bbserial/bbserial.ko`, copy the
+prebuilt `.ko` from a previous official release into `src/bbserial/`
+before running `setup.py sdist` (the install script on the controller
+just installs the existing module if a newer one isn't shipped).
+
+### Flash to a controller
+
+```bash
+curl -X PUT -H "Content-Type: multipart/form-data" \
+  -F "firmware=@dist/bbctrl-1.6.7.tar.bz2" \
+  -F "password=onefinity" \
+  http://onefinity.local/api/firmware/update
+```
+
+…or use the Make target:
+
+```bash
+make update HOST=onefinity.local PASSWORD=onefinity
+```
+
+The controller stops bbctrl, untars the package, runs
+`scripts/install.sh`, and brings the service back up. Total downtime
+is ~30-45s. Watch progress at `http://<host>/` (you'll get 404s while
+bbctrl restarts, then the new UI).
+
+### Verify the flash
+
+```bash
+curl -s http://onefinity.local/ | grep -c "OneFinity"
+curl -s http://onefinity.local/api/aux/status   # if W axis is enabled
+```
+
+## Build & flash (full path, Debian/Linux)
+
+For AVR + GPlan rebuilds, see [docs/development.md](docs/development.md).
+That path uses qemu + chroot to cross-compile gplan for ARM and needs
+the `gcc-avr` / `avr-libc` toolchain.
+
+## W axis (auxcnc)
+
+This fork adds a virtual W axis. See
+[docs/AUX_W_AXIS.md](docs/AUX_W_AXIS.md) for:
+
+- G-code surface (`G28 W0`, `G1 W25`, etc.)
+- The G-code preprocessor and hook architecture
+- aux.json keys
+- REST API (`/api/aux/*`)
+- UI surface (jog row in Control, settings panel in Settings)
+- Edge cases (ESP reboot mid-job, limit closed at home start, …)

docs/AUX_W_AXIS.md

@@ -100,7 +100,30 @@ persisted there in NVS.
 Steps-mode jog ignores soft limits (use it to inch the axis to the
 limit switch when the axis isn't homed yet).
 
-## State surface (UI)
+## UI
+
+**Control view**
+
+- A jog row appears under the XYZ jog grid when `aux_enabled` is true,
+  with three buttons: `W-`, `W+`, and a wide `Home W`. There is
+  intentionally no separate "set zero" or "W origin" button - homing
+  lands the axis at `home_position_mm` (0 by default), so home and
+  zero are the same point.
+- The DRO table shows a W axis row with position, status (OFFLINE /
+  UNHOMED / HOMED), and a single Home button in the actions column
+  (the cog and map-marker columns are placeholders for layout).
+
+**Settings view**
+
+A "W Axis (auxcnc)" section exposes every aux.json field except
+`enabled` (which stays read-only - flipping the W axis on/off requires
+editingaux.json on the controller, so a fresh install can't surprise
+the user with hardware that isn't there). Saving PUTs the merged
+config to `/api/aux/config/save`, which writes aux.json and pushes
+`HOMECFG` to the ESP. A status line shows whether the axis is
+disabled / offline / connected-unhomed / homed at `<pos> mm`.
+
+## State surface
 
 These are pushed via `state.set` and visible in the websocket stream:
 
@@ -139,6 +162,11 @@ These are pushed via `state.set` and visible in the websocket stream:
 - `src/py/bbctrl/FileHandler.py`: rewrite uploads in place
 - `src/py/bbctrl/Web.py`: REST endpoints
 - `src/py/bbctrl/__init__.py`: export AuxAxis
+- `src/pug/templates/control-view.pug`: W jog row + DRO row
+- `src/js/control-view.js`: aux_home / aux_jog / aux_jog_incr handlers
+- `src/js/axis-vars.js`: `_compute_aux_axis` for W state
+- `src/svelte-components/src/components/WAxisSettings.svelte`: settings panel
+- `src/svelte-components/src/components/SettingsView.svelte`: hosts WAxisSettings
 - `auxcnc/src/main.cpp`: new commands HOME, HOMECFG, WPOS, HOMED?,
   LIMIT?, ABORT-able STEPS with limit-aware abort, trapezoidal ramps,
   NVS-persisted config, `[boot]` banner, deterministic reply tokens