Glossary

Sandbox — A disposable (or, for main, persistent) Dentolize deployment used for previewing a PR, demoing, training, or manual QA. Managed by a CLI (/opt/homelab/sandbox/bin/sandbox) that lives on the self-hosted runner, outside this repository.

sandbox-ops.yml — The manually-dispatched (workflow_dispatch) GitHub Actions workflow (.github/workflows/sandbox-ops.yml) used to run one of five operations — reseed, reset-data, redeploy, destroy, update-docs — against a chosen branch's sandbox.

sandbox.yml — The automatic workflow (.github/workflows/sandbox.yml) that deploys/destroys a PR's sandbox in response to PR open/sync/close events. Reads its settings from the PR description, not from the sandbox GitHub Environment this PR adds.

sandbox-main.yml — The workflow (.github/workflows/sandbox-main.yml) that redeploys main's persistent demo/training sandbox on every push to main. Always deploys data-preservingly; does not itself read the sandbox GitHub Environment — that only happens when sandbox-ops.yml's redeploy action is run manually.

sandbox GitHub Environment — A named bucket of variables and secrets configured under this repository's Settings → Environments, introduced by this PR as a config source for branches without a PR (chiefly main). Distinct from a Dentolize sandbox deployment — same word, two different things: one is a GitHub configuration object, the other is a running preview environment.

## 🧪 Sandbox block — The YAML settings block engineers write into a PR description (templated in .github/PULL_REQUEST_TEMPLATE.md) to configure that PR's own sandbox. The only pre-existing settings channel before this PR; still the only channel for PR sandboxes.

SANDBOX_ALL_<KEY> — A variable/secret name prefix in the sandbox Environment meaning "apply to every branch this mechanism deploys."

SANDBOX_<REF>_<KEY> — A variable/secret name prefix meaning "apply only to this one branch," where <REF> is the branch name uppercased with non-alphanumeric runs collapsed to _ (e.g. main → SANDBOX_MAIN_).

Profile toggle — One of four reserved settings keys (WHATSAPP, TWO_REGIONS, CRON, QUEUE) that, after the SANDBOX_* prefix is stripped, map to a boolean flag (whatsapp, two_regions, cron, queue) controlling which services/regions the deployed stack brings up — rather than becoming a plain environment variable.

Seed mode — The SEED reserved key (maps to seed in the composed settings), either rich (full demo dataset) or basic (minimal, idempotent seed).

SANDBOX_SETTINGS_FILE — The environment variable (set via $GITHUB_ENV) pointing at the JSON settings file, shared by both the PR-body path (sandbox.yml) and the new environment-sourced path (sandbox-ops.yml), that the sandbox CLI's load_settings reads at deploy time.

load_settings — The (external, not in this repo) sandbox CLI routine that reads SANDBOX_SETTINGS_FILE and applies its whatsapp / two_regions / cron / queue / seed / env contents when deploying a branch's stack.

Truthy value — For profile toggles, any of 1, true, yes, on (case-insensitive, whitespace-trimmed) reads as true; every other value — including empty string or a typo — reads as false. There is no error path for an unrecognized value.