chore(release): rc-stack pulls the pushed image + optional --with-runtimes (#1133)

Retro improvements from the v1.13.0 release:
- rc-stack.sh 'up' now docker-pulls lfnovo/open_notebook:<tag> by default so a
  same-named local build can't shadow the registry artifact during Phase 6
  verification (non-fatal for local-only tags).
- New --with-runtimes flag enables the opt-in heavy engines (Docling +
  Crawl4AI) on the RC stack via RC_ENABLE_DOCLING/RC_ENABLE_CRAWL4AI, so the
  published image's opt-in install path can be exercised with real data. The
  release-test compose defaults these empty, keeping fresh/upgrade tests fast.
- Documented both gotchas (local-tag shadowing; judging opt-in gating on a
  clean image vs a dev venv with runtimes installed out-of-band) in
  RELEASE_PROCESS.md.

.github/RELEASE_PROCESS.md

@@ -172,3 +172,15 @@ accepted improvements immediately — update this document, the scripts under
   `.env` is loaded. During bucket A, snapshot record counts per table before
   and after the suite (e.g. credentials count) — a diff means a test is
   leaking writes (this caught 48 leaked `Test` credentials in v1.12.0).
+- **A local `docker-build-local` tag shadows the pushed image.** Both are
+  `lfnovo/open_notebook:<ver>`, so Phase 6 could verify your own local build
+  instead of the registry artifact. `rc-stack.sh up` now `docker pull`s the tag
+  by default; if you boot the image any other way, pull first (v1.13.0 lesson).
+- **Judge opt-in runtime gating on a clean image, not the dev venv.** A dev
+  venv may have `crawl4ai`/`docling` installed out-of-band (not via the opt-in
+  flag), so `GET /api/capabilities` reports them available and the UI enables
+  the engines — which does NOT reflect the lean default image. Verify the
+  gating on the RC stack (fresh pushed image) where the runtimes are genuinely
+  absent until enabled. To exercise the real install path with your data, use
+  `make release-stack TAG=<ver> DUMP=<dump>` plus `rc-stack.sh ... --with-runtimes`
+  (sets `OPEN_NOTEBOOK_ENABLE_DOCLING`/`_CRAWL4AI`; first boot is slow) (v1.13.0 lesson).

scripts/release-test/docker-compose.release-test.yml

@@ -22,6 +22,11 @@ services:
       - SURREAL_PASSWORD=root
       - SURREAL_NAMESPACE=${RC_SURREAL_NS:-open_notebook}
       - SURREAL_DATABASE=${RC_SURREAL_DB:-open_notebook}
+      # Opt-in heavy runtimes: empty by default (fresh/upgrade tests stay fast);
+      # rc-stack.sh --with-runtimes sets these to install Docling/Crawl4AI so the
+      # published image's opt-in path can be exercised with real data.
+      - OPEN_NOTEBOOK_ENABLE_DOCLING=${RC_ENABLE_DOCLING:-}
+      - OPEN_NOTEBOOK_ENABLE_CRAWL4AI=${RC_ENABLE_CRAWL4AI:-}
     volumes:
       - ${DATA_DIR}/notebook:/app/data
     # Reach host services (e.g. Ollama on localhost:11434) via

scripts/release-test/rc-stack.sh

@@ -4,8 +4,16 @@
 # verification without touching the dev environment.
 #
 # Usage:
-#   rc-stack.sh up <tag> [dump.surql]   # start (imports the dump if given)
-#   rc-stack.sh down <tag>              # stop and remove everything
+#   rc-stack.sh up <tag> [dump.surql] [--with-runtimes]   # start (imports the dump if given)
+#   rc-stack.sh down <tag>                                 # stop and remove everything
+#
+# --with-runtimes enables the opt-in heavy engines (Docling + Crawl4AI) so the
+# published image installs them on first boot — lets you exercise the real
+# opt-in path with real data (the first boot then takes several minutes).
+#
+# `up` docker-pulls the pushed image by default, so you always verify the
+# registry artifact and not a same-named local build shadowing it. A local-only
+# tag (no registry push) still works — the pull failure is a warning, not fatal.
 #
 # To produce a data copy from a running dev SurrealDB (originals untouched):
 #   docker exec <surreal-container> /surreal export \
@@ -16,8 +24,14 @@
 set -euo pipefail
 DIR="$(cd "$(dirname "$0")" && pwd)"
 REPO="$(cd "$DIR/../.." && pwd)"
-TAG="${2:?usage: rc-stack.sh <up|down> <tag> [dump.surql]}"
-DUMP="${3:-}"
+TAG="${2:?usage: rc-stack.sh <up|down> <tag> [dump.surql] [--with-runtimes]}"
+
+# Optional flag can appear anywhere after the tag; the remaining positional is the dump.
+WITH_RUNTIMES=""
+DUMP=""
+for arg in "${@:3}"; do
+  if [ "$arg" = "--with-runtimes" ]; then WITH_RUNTIMES="true"; else DUMP="$arg"; fi
+done
 RC_DATA=/tmp/onrel-rc-data
 
 # Reuse the dev encryption key so copied credentials decrypt; the DB name must
@@ -30,6 +44,7 @@ compose() {
   API_PORT=15055 FE_PORT=18502 PROXY_PORT=18080 \
   RC_API_URL="http://localhost:15055" \
   RC_ENCRYPTION_KEY="${KEY:-release-test-key}" RC_SURREAL_DB="${DB:-open_notebook}" \
+  RC_ENABLE_DOCLING="${WITH_RUNTIMES:+true}" RC_ENABLE_CRAWL4AI="${WITH_RUNTIMES:+true}" \
   docker compose -p onrelrc -f "$DIR/docker-compose.release-test.yml" "$@"
 }
 
@@ -40,6 +55,11 @@ case "$1" in
     echo "RC stack removed."
     ;;
   up)
+    # Pull the pushed image so a same-named local build can't shadow the
+    # registry artifact we mean to verify (non-fatal for local-only tags).
+    docker pull "lfnovo/open_notebook:$TAG" || \
+      echo "WARNING: could not pull lfnovo/open_notebook:$TAG — using the local image if present."
+    [ -n "$WITH_RUNTIMES" ] && echo "Opt-in runtimes ENABLED (Docling + Crawl4AI) — first boot will be slow."
     compose down -v >/dev/null 2>&1 || true
     rm -rf "$RC_DATA"; mkdir -p "$RC_DATA/surreal" "$RC_DATA/notebook"
     if [ -n "$DUMP" ]; then