Update docs to reflect engine overview refactor and new recording

workflow.

Author: joocer

Makefile

@@ -3,7 +3,8 @@
 PORT ?= 3000
 
 .PHONY: serve serve-prod build install validate deploy-firebase \
-        sql-definitions sql-docs check-sql-definitions check-window-aggregates
+        sql-definitions sql-docs check-sql-definitions check-window-aggregates \
+        recordings
 
 serve:
 	@echo "Starting docs-site dev server on http://localhost:$(PORT)"
@@ -30,6 +31,14 @@ install:
 validate:
 	@cd docs-site && npm run validate:docs
 
+# Terminal GIFs used for REPL/TUI walkthroughs (opteryx-cli.md, upload-cli.md).
+# Each .tape is a VHS script driving the real, installed CLI - see
+# docs-site/scripts/recordings/README.md. Requires `brew install vhs`.
+recordings: ## Regenerate every terminal recording GIF from its .tape script
+	@cd docs-site/scripts/recordings && for tape in *.tape; do \
+		echo "-- $$tape"; vhs "$$tape" || exit 1; \
+	done
+
 # --- SQL reference generation ------------------------------------------------
 # The chain, first link to last. Nothing in it is hand-edited; to change what the
 # docs say about a function, edit the registrar in opteryx-core.

docs-site/content/docs/guides/upload-cli.md

@@ -160,30 +160,7 @@ Same flow, same calls. What it adds is that the plan stays on screen: at a
 scrolling prompt the table goes past once and correcting a type means retyping
 the whole command, and here the cursor moves down it.
 
-```
- opteryx upload                                        https://upload.opteryx.app
-
- FILES
-   part-0000.parquet  412.9 MB
-   part-0001.parquet  398.1 MB
-
- ACCOUNT
-   acme-etl
-
- TO
-   acme.security.findings
-
- PLAN   a new dataset; these types were read from your data
-   column     sample                type
-   cve_id     CVE-2026-00001        VARCHAR
-   published  2026-08-02T04:22:07Z  TIMESTAMP[us]   was VARCHAR, converted
- › source_ip  10.1.7.13             IPV4            was VARCHAR, converted
-   hosts      1                     INT64
-   score      0.5                   FLOAT64         read and not written
-
- these types were read from your data - nothing is written until you accept
- ↑↓ column  e retype  x ignore  ⏎ accept  u upload  h keys  q quit
-```
+<img src="/images/cli/upload-tui.gif" alt="The opteryx-upload TUI: negotiating a contract for findings.csv against acme.security.findings, reviewing the plan (published cast to TIMESTAMP[us], source_ip cast to IPV4, score read and not written), then uploading and committing" width="1040">
 
 `h` lists every key. `c` signs in, `a` browses for files, `t` sets the
 destination, `n` negotiates, `e` changes the type under the cursor, `x` drops a

docs-site/public/images/cli/opteryx-repl.gif

@@ -10,7 +10,7 @@ This document walks the path a query takes from SQL text to results.
 
 The engine is a loop. SQL goes down one side, is progressively refined into a runnable plan, executes, and results come back up the other side.
 
-![How Opteryx plans and runs a query: SQL is refined into a plan down the left and across the bottom, then the plan is refined until it runs going up the right, before results return to the user. Python stages are blue, native stages (Parser, Executor) are rust, and the Catalogue is green. The Physical Planner's handover to the Executor is the one boundary the engine crosses without calling back into Python.](/images/engine-overview.svg)
+![How Opteryx plans and runs a query: SQL is refined into a plan down the left and across the bottom, then the plan is refined until it runs going up the right, before results return to the user. Python stages are blue, native stages (Parser, Executor) are rust, and the Catalogue is green.](/images/engine-overview.svg)
 
 The left column transforms *text*; the bottom row transforms a *plan*; the right column refines that plan until it can run. Each stage has a single, narrow responsibility.
 

docs-site/public/images/cli/upload-tui.gif

@@ -12,6 +12,12 @@ CLI; nothing in the GIFs is mocked up.
 
 ```bash
 brew install vhs  # if you don't have it
+make recordings   # from the repo root — regenerates every .tape here
+```
+
+Or one at a time:
+
+```bash
 cd docs-site/scripts/recordings
 vhs opteryx-repl.tape
 ```
@@ -23,14 +29,24 @@ recording looks stale.
 Run from a directory outside `/tmp` — pyenv-shimmed `python -m <module>`
 invocations have been seen to fail there with an unrelated
 `No module named 'compression'` error caused by something in this machine's
-`/tmp`, not by Opteryx. `~` or the repo itself are fine.
+`/tmp`, not by Opteryx. `~` or the repo itself are fine. `make recordings`
+already runs from the repo root, so this only matters if you run `vhs` by hand.
 
 If you use pyenv and `python -m opteryx` isn't on the version that has
 `opteryx-core` installed, set `PYENV_VERSION` before running `vhs`, e.g.
 `PYENV_VERSION=3.13.12 vhs opteryx-repl.tape`.
 
+`upload-tui.tape` records against `mock_upload_server.py`, a small stand-in for
+the real upload service (see that file's docstring) — the tape starts and stops
+it itself, so nothing needs to be running first. It speaks the real
+`/v2/contracts` protocol and returns a fixed, scripted plan, so the real,
+installed `opteryx-upload` command runs unmodified. `acme` is a reserved
+workspace name kept for exactly this kind of example — use it for any workspace
+a recording or a doc example needs.
+
 ## Recordings
 
 | Tape | Shows | Used in |
 |---|---|---|
 | `opteryx-repl.tape` | Starting the REPL, running a query, exiting | [The Opteryx Command Line](/docs/guides/opteryx-cli) |
+| `upload-tui.tape` | Negotiating, reviewing the plan, uploading and committing | [The Upload Command Line](/docs/guides/upload-cli) |

docs-site/public/images/engine-overview.svg

@@ -6,7 +6,7 @@ Set Shell "bash"
 Set FontSize 15
 Set FontFamily "Menlo"
 Set Width 1040
-Set Height 640
+Set Height 480
 Set Padding 20
 Set Theme "Dracula"
 Set TypingSpeed 45ms