cursor · Sep 28, 2026
diff --git a/docs/poc/CONFIGURATION.md b/docs/poc/CONFIGURATION.md
@@ -105,6 +105,22 @@ Runs after `so1` is **healthy**. Uses Alpine, installs `curl` and `jq`, then run
 
 **`config.env`** is tracked and holds non-secret settings (`SPLUNK_IMAGE`, `TZ`). **`make up`** loads it after secrets, so a copy of those keys in a secret file does not win. Passwords are not stored there.
 
+### Load order and effective config
+
+Host entrypoints that need stack secrets (`make up`, `make config`, token minting, S4R registration, NK shell fallback, and MCP auth stats) use the same helper path:
+
+1. **Secrets first** — `scripts/with-splunk-env.sh` sources **`.env`** when it exists. If **`.env`** is absent, it re-execs the caller under `op run --env-file=tpl.env`. If neither file exists, the command fails with Path A / Path B hints.
+2. **Non-secrets second** — `scripts/load-config-env.sh` requires **`config.env`**, exports only `SPLUNK_IMAGE` and `TZ`, and ignores other keys. This is intentional: image and timezone come from the tracked file, not from stale copies in **`.env`** or **`tpl.env`**.
+3. **Validation last** — callers that start or render Compose require non-empty `SPLUNK_PASSWORD`, `SPLUNKBASE_USER`, `SPLUNKBASE_PASS`, and `SPLUNK_MCP_PASSWORD`.
+
+Use **`make config`** before booting or after env edits to inspect the resolved Compose input without printing secret values:
+
+```bash
+make config
+```
+
+It runs `docker compose config` after the same load path as **`make up`**. Secret fields in the rendered Compose output are shown as **`<set>`** when populated and as `""` when empty. `SPLUNKBASE_USER` / `SPLUNKBASE_PASS` appear in Compose as `SPLUNKBASE_USERNAME` / `SPLUNKBASE_PASSWORD`, matching the Splunk image environment names.
+
 ### `tpl.env.example` and `tpl.env`
 
 - **`tpl.env.example`** is the **tracked** template (placeholder `op://` paths, safe to commit).
@@ -145,7 +161,7 @@ For a **plaintext `.env`** on disk (no 1Password at `make up` time), copy [`.env
 | Target | Behavior |
 | ------ | -------- |
 | `up` | `scripts/compose-up.sh` (`.env` or `op run --env-file=tpl.env`), then `update-all` (`MCP_UPDATE_ON_BOOT`, default `cursor`), then `register-s4r-mcp-tools` |
-| `config` | Print `docker compose config` after the same secret and `config.env` load as `up`. `SPLUNK_PASSWORD`, Splunkbase user/password, and `SPLUNK_MCP_PASSWORD` are shown as `<set>` |
+| `config` | Print `docker compose config` after the same secret and `config.env` load as `up`. `SPLUNK_PASSWORD`, `SPLUNKBASE_USERNAME`, `SPLUNKBASE_PASSWORD`, and `SPLUNK_MCP_PASSWORD` are redacted as `<set>` when populated; empty values stay `""` |
 | `down` | `scripts/mcp-client.sh park all` (no secrets), then `docker compose down`. `config.env` must be present so Compose can read `SPLUNK_IMAGE` and `TZ` |
 | `park-mcp-clients` | `scripts/mcp-client.sh park all` — remove `splunk-mcp-server` from client configs |
 | `update-mcp-clients` | `scripts/mcp-client.sh update-all` for cursor, goose, claude (one mint) |

diff --git a/docs/poc/INSTALLATION.md b/docs/poc/INSTALLATION.md
@@ -129,6 +129,12 @@ op read "op://YourVault/Splunkbase/username"
 test -s .env
 ```
 
+Confirm the effective Compose input before the first boot. This uses the same secret path as **`make up`**, loads image/timezone from tracked **`config.env`**, and redacts populated secrets as **`<set>`**:
+
+```bash
+make config
+```
+
 Network and ports:
 
 - The host must reach **splunkbase.splunk.com** and the container registry that serves `SPLUNK_IMAGE`.

diff --git a/docs/poc/PRESALES.md b/docs/poc/PRESALES.md
@@ -49,7 +49,7 @@ make demo-prep   # Splunkbase pins + status + MCP verify
 # Cursor: restart after make up (.cursor/mcp.json updated)
 ```
 
-Path B and env details: [CONFIGURATION.md](CONFIGURATION.md#tplenv-and-env). Long-form install: [INSTALLATION.md](INSTALLATION.md).
+Path B and env details: [CONFIGURATION.md](CONFIGURATION.md#load-order-and-effective-config). Long-form install: [INSTALLATION.md](INSTALLATION.md).
 
 **Do not commit:** `tpl.env`, `.env`, or client configs with live tokens ([AGENTS.md](../../AGENTS.md)).
 
@@ -65,7 +65,7 @@ Secrets are **not generated by this repo**; they come from **1Password** (`op://
 - **Path A (`tpl.env`, no `.env`):** `make up` runs `op run --env-file=tpl.env -- docker compose up -d`. Vault values are resolved **only for that process**—no plaintext `.env` on disk.
 - **Path B (`.env`):** Copy **`.env.example` → `.env`**, fill plain values. `make up` uses plain `docker compose`; Compose auto-loads **`.env`**. Use for CI or machines without 1Password.
 
-See [CONFIGURATION.md](CONFIGURATION.md#tplenv-and-env).
+See [CONFIGURATION.md](CONFIGURATION.md#load-order-and-effective-config).
 
 ## What you are demoing (URLs and roles)
 

diff --git a/docs/poc/TROUBLESHOOTING.md b/docs/poc/TROUBLESHOOTING.md
@@ -306,6 +306,24 @@ Edit **`tpl.env`** with your `op://` paths. **`tpl.env`** is gitignored—do not
 
 ---
 
+#### Issue: `make config` fails or shows blank Compose inputs
+
+**Context**: `make config` is the safe preflight for Compose input. It uses the same secret loader as **`make up`**, then loads tracked **`config.env`**, and redacts populated secret fields as **`<set>`**.
+
+**Common symptoms and fixes**:
+
+| Symptom | Meaning | Fix |
+| ------- | ------- | --- |
+| `Error: need .env or tpl.env for Splunk secrets` | Neither Path A nor Path B is configured | Copy **`tpl.env.example`** to **`tpl.env`** and sign in to `op`, or copy **`.env.example`** to **`.env`** and fill plain values |
+| `1Password CLI (op) not available` | Path A was selected but `op` cannot run | Install/sign in to **`op`**, or use Path B with a gitignored **`.env`** |
+| `Error: missing config.env (SPLUNK_IMAGE and TZ)` | The tracked non-secret config file is absent | Restore **`config.env`** from git; do not move `SPLUNK_IMAGE` / `TZ` into a secret file |
+| `SPLUNK_PASSWORD: ""`, `SPLUNKBASE_USERNAME: ""`, `SPLUNKBASE_PASSWORD: ""`, or `SPLUNK_MCP_PASSWORD: ""` | A required secret resolved empty | Fix the matching **`.env`** value or **`tpl.env`** `op://` path, then re-run **`make config`** |
+| Image or timezone differs from what you expected in **`.env`** | **`config.env`** wins over stale copies in secret files | Edit **`config.env`** for `SPLUNK_IMAGE` / `TZ`; keep secret files for passwords and Splunkbase credentials only |
+
+If **`make config`** is clean but **`docker compose up -d`** still fails, make sure you started through **`make up`** or **`./scripts/compose-up.sh`**. Bare **`docker compose up`** does not run the helper path unless a populated **`.env`** already exists.
+
+---
+
 #### Issue: Splunk logs show `Invalid Splunkbase credentials` / ansible inventory errors
 
 **Cause**: The **`so1`** container was created with **empty** `SPLUNKBASE_USER` / `SPLUNKBASE_PASS` (and often `SPLUNK_PASSWORD`). That happens if you run **`docker compose up -d`** without a **`.env`** file and without **`op run --env-file=tpl.env`**—Compose substitutes blank strings, and Splunk’s entrypoint refuses Splunkbase downloads.