docs(scripts): add --help to remaining scripts; document scripts + layout in README

- Add a -h/--help guard (prints the usage header) to the five scripts
  that lacked one: smoke.sh, smoke-e2e.sh, test-features.sh,
  demo-save-load.sh, sandbox-bootstrap.sh. All 15 hh/scripts/*.sh now
  respond to --help.
- README: new "Scripts" section detailing every script (setup, hosting,
  sandbox provisioning, tests) and noting each takes --help; plus an
  archive note for the film-* recording scripts.
- README: new "Window layout" section documenting live pane resizing
  (F4 fullscreen, click/F5 to select + arrows to resize) and the
  /layout save/load/list/rm/reset presets, with matching keybinding-table
  rows.

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

README.MD

@@ -50,8 +50,7 @@ Encrypted chat that runs in your terminal. You host the server, you control the
 | `cmd_chat/agent/` | The model-agnostic AI agent bridge (joins a room as an encrypted client) |
 | `models.toml` | Named provider profiles for `/ai start <profile>` (see `docs/providers.md`) |
 | `docs/providers.md` | Connect any model — profiles, flags, discovery, bring-your-own-provider |
-| `hh/scripts/lets-hack.sh` | Spin up a local test "clergy" in tmux (server + N client panes) |
-| `hh/scripts/bootstrap-ai.sh` | Optional: install Ollama + pull a model for the local `/ai` agent |
+| `hh/scripts/` | Helper scripts — setup, hosting, sandbox provisioning, tests (see [Scripts](#scripts); each takes `-h`/`--help`) |
 | `hh/direnv-autostart/` | `cd` into a directory to auto-launch a session (direnv) |
 
 ## Quick start
@@ -169,6 +168,8 @@ Type to chat. Slash commands and keys:
 | `Ctrl+C` (while driving) | Interrupt the running command |
 | `Ctrl+R` | Reconnect after a drop |
 | `↑/↓` · `PgUp/PgDn` · mouse wheel | Scroll chat / sandbox scrollback |
+| `F4` · `F5` · click | Layout: fullscreen terminal · select a pane to resize (then arrows · `Esc`) — see [Window layout](#window-layout) |
+| `/layout save \| load \| list \| rm \| reset` | Save / recall named pane arrangements |
 
 ### The shared sandbox
 
@@ -289,6 +290,32 @@ with `Ctrl+Alt+P` (and save it to disk), or load your own TOML at launch with
 `--theme <path>` (see `hh/themes/`). Each theme defines its own sigil, colours,
 and roster width.
 
+### Window layout
+
+The chat, roster (clergy), and sandbox-terminal panes are resizable and can be
+fullscreened — live, with no restart. Resizing the terminal also re-syncs the
+shared PTY grid so everyone in the room sees the same dimensions.
+
+- **Fullscreen** — `F4` cycles the sandbox terminal fullscreen → chat
+  fullscreen → back to the split. The 3-line input bar always stays visible, so
+  `F4` always brings you back.
+- **Resize a pane** — click a pane (or press `F5` to cycle the selection:
+  terminal → chat → roster). The selected pane gets a bold accent border and an
+  `✎` marker in its title. Then:
+  - `↑` / `↓` grow / shrink the **terminal** or **chat** pane's height share
+  - `←` / `→` narrow / widen the **roster** column (down to hidden)
+  - `Esc` or `Enter` finishes editing.
+- **Presets** — save the current arrangement and recall it later:
+
+  | Command | Effect |
+  |---|---|
+  | `/layout` | Show the current arrangement + a reminder of the keys |
+  | `/layout save <name>` | Save the current split/roster to `hh/layouts/<name>.toml` |
+  | `/layout load <name>` (or `/layout <name>`) | Re-apply a saved layout |
+  | `/layout list` | List saved presets |
+  | `/layout rm <name>` | Delete a saved preset |
+  | `/layout reset` | Restore the default split |
+
 ### Staying connected
 
 If the connection drops (network blip, laptop sleep), press `Ctrl+R` to re-run
@@ -296,6 +323,50 @@ the SRP handshake and re-attach — no restart needed. If you were hosting the
 sandbox, it's re-announced so the room re-syncs the shared shell. Chat keeps up
 to ~4000 lines of scrollback; the sandbox terminal keeps 2000.
 
+## Scripts
+
+Everything lives in `hh/scripts/`; run from the `hh/` directory. **Every script
+supports `-h` / `--help`** for full usage.
+
+**Setup**
+
+| Script | What it does |
+|---|---|
+| `bootstrap.sh` | One-shot first-run setup: checks prereqs, creates the Python venv, installs server deps, builds the Rust client (plus the AI layer unless `--no-ai`). |
+| `bootstrap-ai.sh` | Optional AI layer: runs the baseline, then installs Ollama and pulls a default local model for the `/ai` agent. |
+
+**Run a session**
+
+| Script | What it does |
+|---|---|
+| `lets-hack.sh` | Local demo/test: boots a `--no-tls` server and tiles one TUI client pane per user in tmux. |
+| `host-house.sh` | Host a real room *and* take a seat — builds the client, starts the server, and opens your own client, all in tmux. |
+| `host-room.sh` | Host the server only (no seat): mints a password, frees the port, prints the LAN/Tailscale join banner, runs in the foreground. |
+| `connect.sh` | Join a room with the password kept RAM-only (no-echo prompt). Flags: `--sync` (pull latest code before building), `--tls`, `--insecure`, `--no-build`, `-P PORT`. |
+
+**Sandbox provisioning** — driven by the client at runtime; you rarely run these by hand
+
+| Script | What it does |
+|---|---|
+| `ensure-docker.sh` | Install Docker and/or start its daemon (idempotent; `--check`/`--plan`/`--yes`). Invoked by `/sbx launch docker`. |
+| `ensure-multipass.sh` | Install Multipass. Invoked by `/sbx launch multipass`. |
+| `ensure-vbox.sh` | Install VirtualBox (warns on Secure Boot). Invoked by `/sbx launch virtualbox` and `/sbx gui`. |
+| `vbox-new.sh` | Create + boot a fresh Ubuntu VirtualBox VM via cloud-init. Invoked by `/sbx launch virtualbox`. |
+| `sandbox-bootstrap.sh` | Baseline dev-tool install piped into a Docker sandbox at provision time (package list from `sandbox-tools.json`). |
+| `sandbox-tools.json` | Editable package list consumed by `sandbox-bootstrap.sh`. |
+
+**Tests & demos** — for contributors
+
+| Script | What it does |
+|---|---|
+| `smoke-e2e.sh` | Headless CI smoke test: server + two real TUI clients in tmux; asserts SRP join, chat round-trip, `/sbx` dispatch. |
+| `smoke.sh` | Crypto smoke test: Rust unit tests → SRP self-test → live server → Rust handshake → Python decrypts the Rust-sent message. |
+| `test-features.sh` | Broad TUI regression: drives owner + member panes and scrapes the screen to assert ~13 UI features. |
+| `demo-save-load.sh` | PoC harness proving the persistent-sandbox flow (`/sbx save` → quit → `/sbx load`, code intact). |
+
+`hh/scripts/archive/` holds personal demo-*recording* scripts (`film-*.sh`) that
+depend on external video tooling — not needed to use or develop hack-house.
+
 ## Configuration
 
 | Variable | Where | Effect |

hh/scripts/demo-save-load.sh

@@ -14,6 +14,11 @@
 #   --keep   leave the server, container, image and tmux sessions up afterwards
 set -uo pipefail
 
+# -h/--help: print the usage header above and exit.
+case "${1:-}" in
+  -h|--help|-help) sed -n '2,/^set /{/^set /d;s/^# \{0,1\}//;p}' "$0"; exit 0 ;;
+esac
+
 # ---- config -----------------------------------------------------------------
 REPO="$(cd "$(dirname "${BASH_SOURCE[0]}")/../.." && pwd)"
 # Pick a free TCP port so we never collide with a stale server from another

hh/scripts/sandbox-bootstrap.sh

@@ -12,6 +12,13 @@
 #   HH_SBX_PKGS="vim tmux ripgrep" ./host-house.sh ...
 set -uo pipefail
 
+# -h/--help: print the usage header above and exit. (No effect in normal use —
+# hh pipes this to `bash -s` inside the container with no args; the flag is for
+# running it standalone to read what it does.)
+case "${1:-}" in
+  -h|--help|-help) sed -n '2,/^set /{/^set /d;s/^# \{0,1\}//;p}' "$0"; exit 0 ;;
+esac
+
 SENTINEL=/var/lib/hh-bootstrap.done
 [[ -f "$SENTINEL" ]] && exit 0      # this container is already provisioned
 

hh/scripts/smoke-e2e.sh

@@ -15,6 +15,11 @@
 # Env overrides: PY=<python> BIN=<client binary> PORT=<port> PW=<password>
 set -uo pipefail
 
+# -h/--help: print the usage header above and exit.
+case "${1:-}" in
+  -h|--help|-help) sed -n '2,/^set /{/^set /d;s/^# \{0,1\}//;p}' "$0"; exit 0 ;;
+esac
+
 REPO="$(cd "$(dirname "${BASH_SOURCE[0]}")/../.." && pwd)"
 # Python: prefer the repo venv locally, fall back to PATH (CI installs into the
 # job's own interpreter).

hh/scripts/smoke.sh

@@ -6,6 +6,11 @@
 # Run from anywhere:  hh/scripts/smoke.sh
 set -uo pipefail
 
+# -h/--help: print the usage header above and exit.
+case "${1:-}" in
+  -h|--help|-help) sed -n '2,/^set /{/^set /d;s/^# \{0,1\}//;p}' "$0"; exit 0 ;;
+esac
+
 HERE="$(cd "$(dirname "$0")/.." && pwd)"   # .../hh
 ROOT="$(cd "$HERE/.." && pwd)"          # repo root
 PY="$ROOT/.venv/bin/python"

hh/scripts/test-features.sh

@@ -14,6 +14,11 @@
 #   tmux attach -t hh-autotest
 set -uo pipefail
 
+# -h/--help: print the usage header above and exit.
+case "${1:-}" in
+  -h|--help|-help) sed -n '2,/^set /{/^set /d;s/^# \{0,1\}//;p}' "$0"; exit 0 ;;
+esac
+
 HERE="$(cd "$(dirname "$0")/.." && pwd)"   # .../hh
 ROOT="$(cd "$HERE/.." && pwd)"          # repo root
 PY="$ROOT/.venv/bin/python"