Adopter-facing config: one naming scheme, and say which values are Variables vs Secrets

[charlesgreen]

Why now

No adopters yet, so renaming a public config key costs nothing today and costs a migration note forever after. This is the last free moment.

Decided: the naming rule

Settled, so nobody implementing this has to choose.

The product token is simplycubed, spelled out. Abbreviate to sc only where display width is a real constraint, which today means labels and nothing else.

SIMPLYCUBED_, not SC_. The prefix exists so an entry on a shared settings page is attributable: someone auditing an org's secrets a year from now has to be able to tell what owns each one and whether deleting it breaks something. SC_AZURE_OPENAI_API_KEY does not answer that and is more collision-prone at org scope, which is where these live once an install covers several repositories. Length costs nothing on a page that is read rarely and pasted into once.

Labels are the exception because they render inline on every issue and pull request and compete for horizontal space. sc:go stays.

simplycubed-code also stays as the GitHub App name and the comment mention, since that is the product's actual name in a namespace we do not control. Stated exception, not drift.

The scheme is SIMPLYCUBED_<PROVIDER>_<THING>: ours, whose credential it is, which value.

Section	Name
Variables	SIMPLYCUBED_GH_APP_CLIENT_ID
Secrets	SIMPLYCUBED_GH_APP_PRIVATE_KEY
Variables	SIMPLYCUBED_AZURE_OPENAI_ENDPOINT
Secrets	SIMPLYCUBED_AZURE_OPENAI_API_KEY

GH_ stays. It is not disambiguating GitHub from another forge, it is saying what kind of credential this is. Without it, SIMPLYCUBED_APP_PRIVATE_KEY reads as the private key of the SimplyCubed application, which is precisely the misreading this issue exists to remove. It also names the thing the adopter is physically holding: they have just created a GitHub App and downloaded its key once, and the field should match.

With GH and AZURE_OPENAI both read as providers, the two pairs stop being two schemes and become one applied twice.

So the App keys do not change. Only the Azure pair gains the prefix, and SIMPLYCUBED_SELF_LOGIN becomes SIMPLYCUBED_GH_APP_LOGIN.

The surface that matters

Not our Go identifiers. The four values an adopter sets in their org or repository settings, having never read our code:

Section	Name
Variables	SIMPLYCUBED_GH_APP_CLIENT_ID
Secrets	SIMPLYCUBED_GH_APP_PRIVATE_KEY
Variables	AZURE_OPENAI_ENDPOINT
Secrets	AZURE_OPENAI_API_KEY

Three things are wrong with that page.

1. Two of the four are unprefixed

Half our config does not look like ours. On an org settings page holding dozens of entries, these four do not read as one tool's configuration, and someone auditing a year from now cannot tell what AZURE_OPENAI_API_KEY belongs to or whether removing it breaks something.

2. The unprefixed pair collides at org scope

AZURE_OPENAI_API_KEY is the conventional name for that credential. An organisation already using Azure OpenAI for anything else either hits a name conflict or, worse, silently shares one key between our runtime and something unrelated. Org-level scope makes this materially more likely than repo-level, and org-level is the sensible way to install across several repositories.

The prefix exists precisely to prevent this for the App key. It should do the same job for the engine credentials:

SIMPLYCUBED_AZURE_OPENAI_ENDPOINT
SIMPLYCUBED_AZURE_OPENAI_API_KEY

3. Variable vs secret is a silent trap

Two of the four go in Variables and two in Secrets, and nothing in the names says which. A Client ID looks credential-shaped, so putting it in Secrets is the natural instinct, and then vars.SIMPLYCUBED_GH_APP_CLIENT_ID resolves to empty.

This is not hypothetical. During a real install, AZURE_OPENAI_ENDPOINT was set as a secret. Nothing reads secrets.AZURE_OPENAI_ENDPOINT, so it sat there inert, and no output anywhere said so. It was found by reading the caller workflow.

Two gaps behind that:

• simplycubed preflight (cmd/simplycubed/main.go:377) validates the config file and engine settings and checks none of these four.
• The install self-test does check, and helpfully names the section: FAIL: AZURE_OPENAI_ENDPOINT is not set (repository VARIABLE). But the self-test is deleted once it passes, so the only check that catches this is thrown away at the end of install.

Suggested shape

• One prefix across all four values.
• Say the section next to every name, everywhere it appears: init output, docs/setup.md, and the README. "Variable" and "Secret" are different pages in GitHub's UI and the distinction has to survive being read once.
  Checking those values at runtime is preflight should check the four adopter-set values and name Variable vs Secret #115. Deleting the vestigial github-app-id input is Delete the vestigial github-app-id input that invites the wrong credential #116. Both were split out of this issue so this one stays a rename-and-document pass.

Secondary: internal names, same pass

• SIMPLYCUBED_SELF_LOGIN (cmd/simplycubed/main.go:469) means "the bot identity this run authenticates as", which the adopter fills with their bot. It parses as "SimplyCubed's login". SIMPLYCUBED_GH_APP_LOGIN says what it is and matches the other two App values.
• It also has one use in code and zero mentions in docs/: a public surface explained to nobody. Document it or make it internal. The workflow-file preflight never fires for an adopter, only for us #111 leans on it as the hermetic way to inject an adopter identity in tests, so if it stays it should be supported on purpose.
• SIMPLYCUBED_GH_APP_* carries a GH_ segment that SIMPLYCUBED_SELF_LOGIN does not, though both describe the same GitHub App. Resolve it by adding the segment, not removing it: SIMPLYCUBED_GH_APP_LOGIN.

Not in scope

The SIMPLYCUBED_ prefix itself stays. It is the product's config namespace and it is what makes an entry on a shared settings page attributable.

__SIMPLYCUBED_TAG__ (cmd/simplycubed/main.go:135) matches a SIMPLYCUBED_* grep but is not a config key. It is an internal placeholder in the caller template, substituted at init time.

Acceptance

• All four adopter-set values share one prefix and one scheme
• Every name is printed with its section (Variable or Secret) in init, docs/setup.md, and the README
• Every environment knob an adopter can set appears in the docs
• All sites updated: Go, .github/workflows/, cmd/simplycubed/*.tmpl, docs/templates/, docs/
• make check green

Split out of this issue: #115 (preflight checks these at runtime), #116 (delete the vestigial github-app-id input, which needs a workflow-file change the App cannot push).

Related: #110, #111, #112, #113 cover values that are wrong for an adopter, rather than names that are confusing to one.

Note for whoever runs this

Landing this renames two values currently set at org level on simplycubed. Order matters: rename in the repository first, set the new org values, merge, then delete the old ones. A run between those steps resolves an empty variable and fails.