feat(selfhost): support an S3-compatible bucket for visual-capture storage

.env.example

@@ -181,7 +181,11 @@ GITTENSORY_REVIEW_DRAFT=false
 #                                            #   PUBLIC_SITE_ORIGIN look like a private/internal hostname (e.g. a
 #                                            #   bare Tailscale MagicDNS `*.ts.net` address) once you've confirmed
 #                                            #   it's genuinely public (Funnel enabled, a reverse proxy in front of
-#                                            #   it, etc.). Default false (warning shown).
+#                                            #   it, etc.). Default false (warning shown). If your instance is
+#                                            #   NOT genuinely public and you'd rather not expose it, see
+#                                            #   REVIEW_AUDIT_S3_BUCKET below instead -- it moves screenshot
+#                                            #   serving to a public bucket so this warning never applies to
+#                                            #   PUBLIC_API_ORIGIN in the first place.
 # SELFHOST_SETUP_TOKEN=change-this-long-random-value  # REQUIRED to unlock the first-run /setup wizard. Without it
 #                                            #   /setup returns 400; with it, enter the token in the browser form
 #                                            #   or send an x-setup-token / Bearer header. Never put this token in
@@ -268,7 +272,27 @@ REDIS_URL=redis://redis:6379                # REQUIRED for the self-host review
 # BROWSERLESS_MEM_LIMIT=2g                   # (--profile visual-review) container memory cap.
 # REVIEW_AUDIT_DIR=                          # persist visual-review screenshot PNGs to this filesystem path
 #                                            #   instead of re-rendering on demand. Unset = re-render each time.
-#                                            #   Only relevant when BROWSER_WS_ENDPOINT above is set.
+#                                            #   Only relevant when BROWSER_WS_ENDPOINT above is set. Ignored
+#                                            #   when REVIEW_AUDIT_S3_BUCKET below is configured (S3 wins).
+# --- Visual-review screenshot storage in an S3-compatible bucket (optional; an operator's own Cloudflare R2
+#     bucket, or any other S3-compatible provider) instead of the local filesystem above. Recommended once
+#     GITTENSORY_REVIEW_SCREENSHOTS is on: screenshots embedded in a PUBLIC GitHub PR comment need to be
+#     reachable by GitHub itself and by anyone viewing the PR, not just by this instance's own network. All
+#     four of the following must be set together to enable it. ---
+# REVIEW_AUDIT_S3_BUCKET=                    # bucket name.
+# REVIEW_AUDIT_S3_ENDPOINT=                  # e.g. https://<account_id>.r2.cloudflarestorage.com for R2.
+# REVIEW_AUDIT_S3_ACCESS_KEY_ID=             # e.g. an R2 API token's Access Key ID (Object Read & Write,
+#                                            #   scoped to this one bucket, is enough).
+# REVIEW_AUDIT_S3_SECRET_ACCESS_KEY=         # the matching Secret Access Key.
+# REVIEW_AUDIT_S3_REGION=auto                # "auto" for R2 (its own S3-API convention); a real AWS region
+#                                            #   string for other S3-compatible providers. Default "auto".
+# REVIEW_AUDIT_S3_PUBLIC_URL=                # the bucket's own public base URL (an R2 public r2.dev bucket
+#                                            #   URL, or a custom domain connected to the bucket) -- when set,
+#                                            #   screenshots link DIRECTLY at this URL instead of proxying
+#                                            #   through this instance's own /gittensory/shot route. Strongly
+#                                            #   recommended alongside the bucket vars above; without it,
+#                                            #   screenshots are stored in the bucket but still served through
+#                                            #   this instance (same reachability requirement as REVIEW_AUDIT_DIR).
 # DISCORD_WEBHOOK_URL=                        # one Discord channel for per-action notifications (merged/closed/
 #                                            #   manual) on ANY repo you review. Unset = no Discord notifications.
 #                                            #   Collection and schema are auto-created at startup. Off when unset.

apps/gittensory-ui/src/lib/selfhost-env-reference.ts

@@ -369,6 +369,26 @@ export const SELFHOST_ENV_REFERENCE_ROWS: SelfHostEnvReferenceRow[] = [
     name: "REVIEW_AUDIT_DIR",
     firstReference: "src/server.ts",
   },
+  {
+    name: "REVIEW_AUDIT_S3_ACCESS_KEY_ID",
+    firstReference: "src/server.ts",
+  },
+  {
+    name: "REVIEW_AUDIT_S3_BUCKET",
+    firstReference: "src/server.ts",
+  },
+  {
+    name: "REVIEW_AUDIT_S3_ENDPOINT",
+    firstReference: "src/server.ts",
+  },
+  {
+    name: "REVIEW_AUDIT_S3_REGION",
+    firstReference: "src/server.ts",
+  },
+  {
+    name: "REVIEW_AUDIT_S3_SECRET_ACCESS_KEY",
+    firstReference: "src/server.ts",
+  },
   {
     name: "SELFHOST_BUNDLE_ALL",
     firstReference: "scripts/build-selfhost.mjs",
@@ -505,6 +525,11 @@ export const SELFHOST_ENV_REFERENCE_MARKDOWN = [
   "| `QUEUE_STARTUP_JITTER_MIN_JOBS` | `src/selfhost/queue-common.ts` |",
   "| `REDIS_URL` | `src/selfhost/preflight.ts` |",
   "| `REVIEW_AUDIT_DIR` | `src/server.ts` |",
+  "| `REVIEW_AUDIT_S3_ACCESS_KEY_ID` | `src/server.ts` |",
+  "| `REVIEW_AUDIT_S3_BUCKET` | `src/server.ts` |",
+  "| `REVIEW_AUDIT_S3_ENDPOINT` | `src/server.ts` |",
+  "| `REVIEW_AUDIT_S3_REGION` | `src/server.ts` |",
+  "| `REVIEW_AUDIT_S3_SECRET_ACCESS_KEY` | `src/server.ts` |",
   "| `SELFHOST_BUNDLE_ALL` | `scripts/build-selfhost.mjs` |",
   "| `SELFHOST_SERVICE` | `scripts/smoke-observability-traces.mjs` |",
   "| `SELFHOST_SETUP_TOKEN` | `src/selfhost/preflight.ts` |",

apps/gittensory-ui/src/routes/docs.self-hosting-configuration.tsx

@@ -232,6 +232,18 @@ MCP_ACTUATION_REPO_ALLOWLIST=owner/repo-one, owner/repo-two
           <Link to="/docs/self-hosting-rees">REES enrichment</Link>) is also set — visual review is
           fully inert without it.
         </li>
+        <li>
+          <code>REVIEW_AUDIT_S3_BUCKET</code> / <code>_ENDPOINT</code> / <code>_ACCESS_KEY_ID</code>{" "}
+          / <code>_SECRET_ACCESS_KEY</code> — an alternative to <code>REVIEW_AUDIT_DIR</code>:
+          persist screenshots in an S3-compatible bucket (your own Cloudflare R2 bucket, or any
+          other S3-compatible provider) instead of the local filesystem, and set{" "}
+          <code>REVIEW_AUDIT_S3_PUBLIC_URL</code> to that bucket&rsquo;s own public base URL so
+          screenshots link directly at the bucket instead of proxying through this instance. This
+          matters if your instance sits behind a private network (a VPN, a firewall, no public DNS)
+          — without a public bucket, screenshots embedded in a public PR comment are unreachable by
+          GitHub and by anyone viewing the PR who isn&rsquo;t on that same private network. Takes
+          priority over <code>REVIEW_AUDIT_DIR</code> when both are set.
+        </li>
         <li>
           <code>CODEX_HOME</code> — do not set this for the app container. The Codex provider
           rejects a container-set <code>CODEX_HOME</code> outright (fails closed with{" "}