From 1349224ab648daf8e31216178e72b4220cbc7045 Mon Sep 17 00:00:00 2001
From: Michael Johns <user.name>
Date: Wed, 20 May 2026 18:39:00 -0400
Subject: [PATCH] docs(installation): clarify download/staging copy + collapse
 init script
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Three small wording clarifications + a render improvement so the
~400-line init script doesn't dominate the install page.

Clarifications (mjohns):
- "attaches three files" → "attaches three files (among others)" — set
  expectation that the release page has more than just these three.
- "**not** uploaded to the bundle Volume" → "**not** included in the
  bundle (from above)" — reads more naturally given the prior section
  introduced the bundle.
- Step 3.1: name VOL_DIR as a candidate staging location for the init
  script itself (one less decision for the reader).

Render improvement:
- Replace the always-expanded CodeFromTest with a 10-line preview +
  native `<details>` disclosure containing the full script. Avoids
  burying the rest of the page under the init script when readers are
  scrolling through the install flow; opt-in to expand for full review.

Co-authored-by: Isaac
---
 docs/docs/installation.mdx | 19 ++++++++++++++++---
 1 file changed, 16 insertions(+), 3 deletions(-)

diff --git a/docs/docs/installation.mdx b/docs/docs/installation.mdx
index 41cc1e9..137e692 100644
--- a/docs/docs/installation.mdx
+++ b/docs/docs/installation.mdx
@@ -39,7 +39,7 @@ from that release's assets over the version shown below.
 ### 1. Download Release Artifacts
 
 Each GeoBrix [release](https://github.com/databrickslabs/geobrix/releases)
-attaches three files for the GDAL install path:
+attaches three files for the GDAL install path (among others):
 
 - `geobrix-gdal-artifacts-v<version>-noble.tar.gz` — the bundle (JAR,
   `libgdalalljni.so`, GDAL `.deb`s, Python wheels — everything pre-built and
@@ -71,11 +71,11 @@ release/operator process.
 
 ### 3. Stage the Init Script
 
-The init script is **not** uploaded to the bundle Volume; it's the cluster's
+The init script is **not** included in the bundle (from above); it's the cluster's
 init-script attachment.
 
 1. Upload the release's `geobrix-gdal-init.sh` to a workspace file path or
-   a separate Volume the cluster can read.
+   a separate Volume the cluster can read, e.g. the same `VOL_DIR` you set (below) or elsewhere.
 2. Edit `VOL_DIR` (one line near the top of the script) to point at the
    Volume from step 2.
 3. No other edits are required — the script reads the expected tarball
@@ -108,8 +108,21 @@ are installed by this script. This lets the GeoBrix Python wheel be
 bumped independently of the GDAL platform layer.
 :::
 
+Preview of the first 10 lines — expand below for the full script (~400 lines).
+
+<CodeFromTest
+  code={initScript.split('\n').slice(0, 10).join('\n') + '\n# ... (expand the disclosure below for the full script)'}
+  language="bash"
+  title="GeoBrix Init Script — preview (scripts/geobrix-gdal-init.sh)"
+/>
+
+<details>
+  <summary>Show the full init script</summary>
+
 <CodeFromTest code={initScript} language="bash" title="GeoBrix Init Script (scripts/geobrix-gdal-init.sh)" />
 
+</details>
+
 ### 4. Configure Cluster
 
 #### Add Init Script