hackolade · bigorn0 · Aug 19, 2026
diff --git a/README.md b/README.md
@@ -24,6 +24,7 @@ Details: [Getting started — writable paths](./Studio/doc/getting-started-hck-c
 | Guide | When to use it |
 | --- | --- |
 | **[Getting started](./Studio/doc/getting-started-hck-cli.md)** | First run — `/data` + `/tmp` mounts, deployment profiles, quick commands |
+| **[Image variants, preflight, arbitrary UID](./Studio/doc/image-variants.md)** | Ubuntu vs `-hardened` (DHI) tags, startup checks, OpenShift/K8s UID |
 | **[Offline pipeline example](./Studio/doc/example-offline-metadata-pipeline.md)** | **Full CI walkthrough** — image upgrade, offline license, revEng → compMod → DDL → docs |
 | **[Docker CLI how-to](./Studio/doc/docker-cli-howto.md)** | `docker run` without Compose (local and hardened) |
 | **[License validation](./Studio/doc/license-validation.md)** | Online / offline floating license |

diff --git a/Studio/README.md b/Studio/README.md
@@ -23,6 +23,7 @@ Full breakdown: [getting-started-hck-cli.md](./doc/getting-started-hck-cli.md#wr
 | Guide | Description |
 | --- | --- |
 | **[getting-started-hck-cli.md](./doc/getting-started-hck-cli.md)** | Start here — `/data` + `/tmp` layout, profiles, quick start |
+| **[image-variants.md](./doc/image-variants.md)** | Ubuntu vs `-hardened` (DHI) tags, startup preflight, arbitrary UID |
 | **[example-offline-metadata-pipeline.md](./doc/example-offline-metadata-pipeline.md)** | **Full worked example** — image upgrade, offline license, `version` / `showLicense` / `listLogs` / `showLogs`, revEng → compMod → forweng → genDoc |
 | **[docker-cli-howto.md](./doc/docker-cli-howto.md)** | `docker run` templates (local and hardened) |
 | **[license-validation.md](./doc/license-validation.md)** | Floating license — online and offline |
@@ -41,7 +42,7 @@ Always use **`run --rm`** for one-off CLI jobs — without it, stopped `…-run-
 | File | Profile |
 | --- | --- |
 | [compose.yml](./compose.yml) | Local — `/data` + `/tmp`, writable rootfs |
-| [compose.hardened.yml](./compose.hardened.yml) | **Hardened** (CI / production) — read-only rootfs, `cap_drop: ALL` |
+| [compose.hardened.yml](./compose.hardened.yml) | **Runtime profile** (CI / production) — read-only rootfs, `cap_drop: ALL`. Works with the Ubuntu tag or `*-hardened` |
 | [k8s/](./k8s/) | Kubernetes — same mounts + Restricted Pod Security Standard |
 
 ## Custom builds (legacy)

diff --git a/Studio/compose.hardened.yml b/Studio/compose.hardened.yml
@@ -19,6 +19,11 @@
 #   - read-only root filesystem
 #   - all capabilities dropped, no privilege escalation
 #   - non-root user (1000:1001 by default)
+#   - group_add: ["0"] so an overridden user: still matches OpenShift (arbitrary UID, group 0)
+#
+# Image tag: hackolade/hck-cli:<version> (Ubuntu 26.04 LTS as of 8.12.8) or
+# <version>-hardened (Docker Hardened Debian). The file name is the runtime
+# profile, not the -hardened tag.
 #
 # Usage:
 #   docker compose -f compose.hardened.yml run --rm hck-cli
@@ -28,15 +33,20 @@
 # For the same /data + /tmp layout without read-only rootfs, use compose.yml.
 # For Kubernetes manifests with a PVC, see k8s/hck-cli-job.yaml.
 # Documentation: doc/getting-started-hck-cli.md
+# Image tags, preflight, arbitrary UID: doc/image-variants.md
 
 services:
   hck-cli: &hck-cli
     init: true
-    image: hackolade/hck-cli:8.12.7
+    image: hackolade/hck-cli:8.12.8
     command: ["version"]
     restart: 'no'
     read_only: true
     user: "1000:1001"
+    # OpenShift restricted-v2: arbitrary UID in group 0. Keep GID 0 as a supplemental group
+    # so overriding user: to "<uid>:<gid>" still matches the cluster (same as fsGroup: 0).
+    group_add:
+      - "0"
     cap_drop:
       - ALL
     security_opt:
@@ -73,6 +83,8 @@ services:
 
   # OpenShift restricted-v2 assigns an arbitrary UID in the root supplementary group.
   # Proves nss_wrapper and group-0 ownership of /data work without a passwd entry.
+  # Primary GID may also be the assigned UID (user: "<uid>:<uid>"); group_add: ["0"] on
+  # the base service still grants write to /data.
   hck-cli-arbitrary-uid:
     <<: *hck-cli
     user: "31337:0"

diff --git a/Studio/compose.yml b/Studio/compose.yml
@@ -17,6 +17,7 @@
 # on a writable rootfs, but use /data + /tmp for new setups (see getting-started-hck-cli.md).
 #
 # Same two paths in compose.hardened.yml and k8s/ — hardened adds read-only rootfs + caps.
+# Image: hackolade/hck-cli:<version> or <version>-hardened (see doc/image-variants.md).
 #
 # Documentation: doc/getting-started-hck-cli.md
 # Custom builds on hackolade/studio: docker-compose.yml + doc/getting-started.md
@@ -33,7 +34,7 @@ services:
   #     --model '/data/models/MongoDB/Yelp Challenge dataset.hck.json' \
   #     --doc /data/output/doc-test --jsonSchema
   hck-cli: &hck-cli
-    image: hackolade/hck-cli:8.12.7
+    image: hackolade/hck-cli:8.12.8
     command: ["version"]
     restart: 'no'
     # network_mode: 'none'

diff --git a/Studio/doc/docker-cli-howto.md b/Studio/doc/docker-cli-howto.md
@@ -8,7 +8,7 @@ Every example below includes both mounts.
 
 For a full end-to-end pipeline (offline license, revEng, compMod, forweng, genDoc), see **[example-offline-metadata-pipeline.md](./example-offline-metadata-pipeline.md)**.
 
-Pin the image tag (example: `hackolade/hck-cli:8.12.7`). `latest` is not published.
+Pin the image tag (example: `hackolade/hck-cli:8.12.8` or `hackolade/hck-cli:8.12.8-hardened`). `latest` is not published. Ubuntu vs Docker Hardened Image, startup preflight, and arbitrary UID: **[image-variants.md](./image-variants.md)**.
 
 ## Local profile
 
@@ -21,37 +21,49 @@ docker run --rm \
   -v hackolade-studio-data:/data \
   -v "${PWD}/models:/data/models" \
   --tmpfs /tmp:rw,size=1g,mode=1777 \
-  hackolade/hck-cli:8.12.7 version
+  hackolade/hck-cli:8.12.8 version
 ```
 
 Expect `Hackolade version: …` and an `Installed plugins (N):` list (name, version, commit, build date per plugin).
 
 ## Hardened profile (CI / production)
 
-Read-only root filesystem, non-root, dropped capabilities — mirrors [`compose.hardened.yml`](../compose.hardened.yml):
+Read-only root filesystem, non-root, dropped capabilities — mirrors [`compose.hardened.yml`](../compose.hardened.yml). `group_add` / `--group-add 0` keeps **group 0** so an overridden UID can still write `/data` (OpenShift `restricted-v2` does the same). Either image tag works:
 
 ```bash
 docker run --rm \
   --init \
   --read-only \
   --user 1000:1001 \
+  --group-add 0 \
   --cap-drop ALL \
   --security-opt no-new-privileges:true \
   -v hackolade-studio-data:/data \
   -v "${PWD}/models:/data/models" \
   --tmpfs /tmp:rw,size=1g,mode=1777 \
-  hackolade/hck-cli:8.12.7 version
+  hackolade/hck-cli:8.12.8 version
+```
+
+OpenShift-style arbitrary UID (no passwd entry, group 0):
+
+```bash
+docker run --rm \
+  --init --read-only --user 31337:0 --group-add 0 \
+  --cap-drop ALL --security-opt no-new-privileges:true \
+  -v hackolade-studio-data:/data \
+  --tmpfs /tmp:rw,size=1g,mode=1777 \
+  hackolade/hck-cli:8.12.8-hardened version
 ```
 
 ## Diagnostics
 
 Wrapper commands — no full Studio session:
 
 ```bash
-docker run --rm ... hackolade/hck-cli:8.12.7 showLicense
-docker run --rm ... hackolade/hck-cli:8.12.7 showLicense --json
-docker run --rm ... hackolade/hck-cli:8.12.7 listLogs
-docker run --rm ... hackolade/hck-cli:8.12.7 showLogs <runId> --tail 50 --logfile re
+docker run --rm ... hackolade/hck-cli:8.12.8 showLicense
+docker run --rm ... hackolade/hck-cli:8.12.8 showLicense --json
+docker run --rm ... hackolade/hck-cli:8.12.8 listLogs
+docker run --rm ... hackolade/hck-cli:8.12.8 showLogs <runId> --tail 50 --logfile re
 ```
 
 Replace `...` with the same volume and security flags as above. Details: [getting-started-hck-cli.md](./getting-started-hck-cli.md#inspecting-the-image-license-and-logs).
@@ -60,12 +72,12 @@ Replace `...` with the same volume and security flags as above. Details: [gettin
 
 ```bash
 docker run --rm \
-  --init --read-only --user 1000:1001 --cap-drop ALL \
+  --init --read-only --user 1000:1001 --group-add 0 --cap-drop ALL \
   --security-opt no-new-privileges:true \
   -v hackolade-studio-data:/data \
   -v "${PWD}/models:/data/models" \
   --tmpfs /tmp:rw,size=1g,mode=1777 \
-  hackolade/hck-cli:8.12.7 genDoc \
+  hackolade/hck-cli:8.12.8 genDoc \
   --format=HTML \
   --model /data/models/my-model.hck.json \
   --doc /data/output/doc
@@ -79,11 +91,12 @@ docker run --rm --user root \
   -v hackolade-studio-data:/data:ro \
   -v "${PWD}/artifacts:/host" \
   --entrypoint cp \
-  hackolade/hck-cli:8.12.7 -r /data/output/. /host/
+  hackolade/hck-cli:8.12.8 -r /data/output/. /host/
 ```
 
 ## See also
 
 - [Getting started with hck-cli](./getting-started-hck-cli.md)
+- [Image variants, preflight, arbitrary UID](./image-variants.md)
 - [Example: offline metadata pipeline](./example-offline-metadata-pipeline.md)
 - [License validation](./license-validation.md)
diff --git a/Studio/doc/example-offline-metadata-pipeline.md b/Studio/doc/example-offline-metadata-pipeline.md
@@ -4,7 +4,7 @@
 
 End-to-end story using [`compose.hardened.yml`](../compose.hardened.yml): a new `hackolade/hck-cli` image is available, your runner has **no Internet**, and you want to refresh a production model, diff it against a baseline, then publish **DDL** and **documentation**.
 
-Every step uses the hardened profile (read-only rootfs) with **consolidated `/data` + `/tmp` mounts** (recommended over legacy `/home/hackolade/…` paths).
+Every step uses the hardened **runtime profile** (read-only rootfs) with **consolidated `/data` + `/tmp` mounts** (recommended over legacy `/home/hackolade/…` paths). Point `image:` at `hackolade/hck-cli:<version>` or `<version>-hardened` — [image-variants.md](./image-variants.md).
 
 ```bash
 cd /path/to/docker/Studio

diff --git a/Studio/doc/getting-started-hck-cli.md b/Studio/doc/getting-started-hck-cli.md
@@ -9,6 +9,7 @@ Ready-to-use Docker image: Hackolade Studio CLI, all target plugins, no build st
 | Guide | Use when |
 | --- | --- |
 | **This page** | First run, deployment profiles, troubleshooting |
+| **[Image variants, preflight, arbitrary UID](./image-variants.md)** | Ubuntu vs `-hardened` (DHI) tags, startup checks, OpenShift/K8s UID |
 | **[Offline pipeline example](./example-offline-metadata-pipeline.md)** | **Complete CI story** — new image tag, offline license, revEng → compMod → DDL → docs, plus `version`, `showLicense`, `listLogs`, `showLogs` |
 | **[Docker CLI how-to](./docker-cli-howto.md)** | You prefer **`docker run`** instead of Compose |
 | **[License validation](./license-validation.md)** | Online or offline floating license setup |
@@ -35,7 +36,7 @@ This is the same rule in [`compose.yml`](../compose.yml), [`compose.hardened.yml
 | Profile | Compose / manifest | Read-only rootfs | Extra hardening |
 | --- | --- | --- | --- |
 | **Local** | [`compose.yml`](../compose.yml) | No | Same `/data` + `/tmp` mounts |
-| **Hardened** (recommended for CI / production) | [`compose.hardened.yml`](../compose.hardened.yml) | Yes | `cap_drop: ALL`, non-root, no privilege escalation |
+| **Hardened** (recommended for CI / production) | [`compose.hardened.yml`](../compose.hardened.yml) | Yes | `cap_drop: ALL`, non-root, no privilege escalation. Runtime profile — not the `-hardened` image tag |
 | **Kubernetes** | [`k8s/hck-cli-job.yaml`](../k8s/hck-cli-job.yaml) | Yes | Same as hardened Compose (Restricted Pod Security Standard) |
 
 ```bash
@@ -44,12 +45,14 @@ This is the same rule in [`compose.yml`](../compose.yml), [`compose.hardened.yml
 docker compose -f compose.hardened.yml run --rm hck-cli
 ```
 
-OpenShift arbitrary UID: [`compose.hardened.yml`](../compose.hardened.yml) (`hck-cli-arbitrary-uid`) or [`k8s/hck-cli-job-openshift.yaml`](../k8s/hck-cli-job-openshift.yaml).
+OpenShift arbitrary UID: [`compose.hardened.yml`](../compose.hardened.yml) (`hck-cli-arbitrary-uid`) or [`k8s/hck-cli-job-openshift.yaml`](../k8s/hck-cli-job-openshift.yaml). Details: [image-variants.md](./image-variants.md#arbitrary-uid).
+
+`compose.hardened.yml` is the **runtime profile** (read-only rootfs). The **`-hardened` image tag** is a different OS base (Docker Hardened Debian). Either tag works with either compose file — [image-variants.md](./image-variants.md).
 
 ## Before you start
 
 - **Floating license only** — workstation licenses do not work in Docker.
-- **Pin a version tag** — `latest` is not published. Example: `hackolade/hck-cli:8.12.7`. Weekly plugin refreshes may appear as `8.12.7-YYYY-MM-DD` on the [current release only](https://hub.docker.com/r/hackolade/hck-cli/tags).
+- **Pin a version tag** — `latest` is not published. Example: `hackolade/hck-cli:8.12.8` (**Ubuntu 26.04 LTS**) or `hackolade/hck-cli:8.12.8-hardened` (Docker Hardened Image). Weekly plugin refreshes may appear as `8.12.8-YYYY-MM-DD` on the [current release only](https://hub.docker.com/r/hackolade/hck-cli/tags). See [image tags](./image-variants.md#image-tags).
 - **Re-validate when the image tag changes** — license state is tied to the image UUID.
 - **Mount `/data` and `/tmp` on every run** — recommended consolidated layout; legacy `/home/hackolade/…` bind mounts may still work on a writable rootfs (see [Writable paths](#writable-paths-data-and-tmp-recommended)).
 - **Always use `docker compose run --rm`** — removes the one-off container when the command exits. Without `--rm`, stopped `…-run-…` containers accumulate and Compose warns about **orphan containers** on the next run.
@@ -140,10 +143,11 @@ $COMPOSE run --rm hck-cli showLicense || exit 1
 
 | Tag | Meaning |
 | --- | --- |
-| `hackolade/hck-cli:8.12.7` | Current Hackolade Studio release |
-| `hackolade/hck-cli:8.12.7-2026-08-07` | Example intermediate tag (plugin updates on the current release) |
+| `hackolade/hck-cli:8.12.8` | Current Studio release (**Ubuntu 26.04 LTS** / Resolute Raccoon) |
+| `hackolade/hck-cli:8.12.8-hardened` | Same release, [Docker Hardened Image](https://docs.docker.com/dhi/) (Debian) base |
+| `hackolade/hck-cli:8.12.8-2026-08-07` | Example intermediate tag (plugin updates on the current release) |
 
-Update the `image:` line in your compose file, then `docker compose pull`.
+Update the `image:` line in your compose file, then `docker compose pull`. Ubuntu vs `-hardened`, startup preflight, and arbitrary UID: **[image-variants.md](./image-variants.md)**.
 
 ## Docker CLI (without Compose)
 
@@ -153,7 +157,8 @@ See **[docker-cli-howto.md](./docker-cli-howto.md)** for local and hardened `doc
 
 | Problem | Check |
 | --- | --- |
-| Permission denied on `./models` | `chown -R 1000:1001 ./models` |
+| Permission denied on `./models` | `chown -R 1000:1001 ./models` (default user). For an OpenShift-style UID see [arbitrary UID](./image-variants.md#bind-mounted-host-folders) |
+| `The container has no writable location` | Preflight: `/data` and `/tmp` must be writable by this UID. Mount both; keep **group 0** for an arbitrary UID (`group_add: ["0"]`, `user: "<uid>:0"`, or `fsGroup: 0`). Recreate a named volume stuck at `root:root` `755`. Details: [preflight](./image-variants.md#startup-preflight) |
 | Fails with read-only rootfs | Mount **`/data`** (volume) and **`/tmp`** (tmpfs) — with `read_only: true`, only these paths are writable |
 | `Read-only file system` / writes not landing on a legacy mount | Prefer **`/data/…`** — the image redirects runtime writes to `/data` and `/tmp`; legacy `/home/hackolade/…` bind mounts may still work on a writable rootfs but are not recommended |
 | License validation fails | Same image tag for UUID + validation; floating seat available |
@@ -164,6 +169,7 @@ See **[docker-cli-howto.md](./docker-cli-howto.md)** for local and hardened `doc
 
 ## See also
 
+- [Image variants, preflight, arbitrary UID](./image-variants.md)
 - [Offline metadata pipeline example](./example-offline-metadata-pipeline.md) — **full CI walkthrough**
 - [Docker CLI how-to](./docker-cli-howto.md)
 - [License validation](./license-validation.md)