docs(local): document docker-container driver for buildx builders

justfile

@@ -7,9 +7,11 @@
 # refreshed so the result is immediately servable.
 #
 # Prerequisites:
-#   - buildx builders named `artemis` (amd64) and `gaia` (arm64), e.g.
+#   - buildx builders named `artemis` (amd64) and `gaia` (arm64), created with the
-#       docker buildx create --name artemis --node artemis ssh://<host-amd64>
+#     docker-container driver (runs BuildKit on the remote host's docker daemon over
-#       docker buildx create --name gaia    --node gaia    ssh://<host-arm64>
+#     SSH). The default `remote` driver does NOT work with an ssh:// docker host.
+#       docker buildx create --name artemis --driver docker-container ssh://<user@host-amd64>
+#       docker buildx create --name gaia    --driver docker-container ssh://<user@host-arm64>
 #   - exported secrets: B2_S3_ACCESS_KEY, B2_S3_SECRET_KEY, PGPASS (GITHUB_PAT optional)
 #
 # Overridable (env or `just VAR=… rebuild …`):
@@ -38,20 +40,28 @@ rebuild os tag arch package *versions:
       arm64) builder="{{ arm64_builder }}" ;;
       *) echo "error: arch must be 'amd64' or 'arm64'" >&2; exit 1 ;;
     esac
-    : "${B2_S3_ACCESS_KEY:?set B2_S3_ACCESS_KEY in your environment}"
+    # Accept TF_VAR_-prefixed names (direnv) or plain names.
-    : "${B2_S3_SECRET_KEY:?set B2_S3_SECRET_KEY in your environment}"
+    export B2_S3_ACCESS_KEY="${B2_S3_ACCESS_KEY:-${TF_VAR_B2_S3_ACCESS_KEY:-}}"
-    : "${PGPASS:?set PGPASS in your environment}"
+    export B2_S3_SECRET_KEY="${B2_S3_SECRET_KEY:-${TF_VAR_B2_S3_SECRET_KEY:-}}"
-    : "${GITHUB_PAT:=}"
+    : "${B2_S3_ACCESS_KEY:?set B2_S3_ACCESS_KEY or TF_VAR_B2_S3_ACCESS_KEY}"
+    : "${B2_S3_SECRET_KEY:?set B2_S3_SECRET_KEY or TF_VAR_B2_S3_SECRET_KEY}"
+    : "${PGPASS:?set PGPASS}"
+    secret_args=(
+      --secret id=b2_access,env=B2_S3_ACCESS_KEY
+      --secret id=b2_secret,env=B2_S3_SECRET_KEY
+      --secret id=pgpass,env=PGPASS
+    )
+    # GITHUB_PAT is optional (raises the GitHub API rate limit); pass only if set.
+    if [ -n "${GITHUB_PAT:-}" ]; then
+      secret_args+=(--secret id=github_pat,env=GITHUB_PAT)
+    fi
     echo "Dispatching build of {{ package }} ({{ versions }}) on {{ os }}:{{ tag }}/{{ arch }} (R {{ r_version }}) to builder '$builder'"
     docker buildx build \
       --builder "$builder" \
       --platform "linux/{{ arch }}" \
       --no-cache \
       --output type=cacheonly \
-      --secret id=b2_access,env=B2_S3_ACCESS_KEY \
+      "${secret_args[@]}" \
-      --secret id=b2_secret,env=B2_S3_SECRET_KEY \
-      --secret id=pgpass,env=PGPASS \
-      --secret id=github_pat,env=GITHUB_PAT \
       --build-arg OS="{{ os }}" \
       --build-arg OS_VERSION="{{ tag }}" \
       --build-arg R_VERSION="{{ r_version }}" \