[New Feature]: Let plugins declare their own ENVs and docs #1156

Checked for duplicates

Yes - I've already checked

Alternatives considered

Yes - and alternatives don't suffice

Related problems

Came up while adding the LDAP login provider in #1155, which adds about 20 LDAP_* settings plus general AUTH_* ones.

Today a plugin reads process.env itself, names its settings with its own prefix (LDAP_*, PROXY_*), checks them in validate(env) / warnings(env), and its settings are documented by hand in the central docs/pages/Setup/ENVs/ENVs.md and sample.env (the AGENTS.md "ENV triple-update" rule). Problems this causes:

• Defaults live in three places (plugin code, sample.env, ENVs.md) and can drift.
• Every plugin parses values its own way. For example, AUTH_PROVIDER_NEW_ACCOUNTS=FALSE was silently ignored until it was caught in review.
• The central ENVs.md grows with every plugin, and plugin guides (e.g. docs/pages/Setup/LDAP/LDAP.md) live outside the plugin, so removing a plugin means editing the core docs.
• External plugins in plugins/<container>/ (gitignored, not part of this repo) can't add their settings to the core ENVs.md or sample.env.
• Nothing catches typos such as LDAP_URl; the setting is just treated as unset.
• Secrets (e.g. LDAP_BIND_PASSWORD) have to be kept out of logs and diagnostics by each plugin.

Describe the feature request

Let a plugin own both its ENVs and its docs. First, let a plugin declare its ENVs in its plugin.json, much as tools and layer types already declare their Configure settings there. For example:

"envs": [
  { "name": "LDAP_URL", "type": "string", "description": "ldaps:// or ldap:// URL of the directory" },
  { "name": "LDAP_STARTTLS", "type": "boolean", "default": false, "description": "Upgrade ldap:// with StartTLS" },
  { "name": "LDAP_TIMEOUT_MS", "type": "number", "default": 5000, "description": "Directory request timeout" },
  { "name": "LDAP_BIND_PASSWORD", "type": "secret", "description": "Service account password" }
]

Types could be string, boolean, number, enum (with allowed values), path and secret. Core would then:

1. Parse and check every value the same way (e.g. booleans accept true/false in any case), refuse bad values at startup with a message naming the setting, and pass the plugin a typed config instead of raw process.env.
2. Generate the docs: each plugin's section of ENVs.md and its sample.env block, from the declarations, with a CI check that the generated files are up to date. The triple update becomes a single update.
3. Keep secret settings out of logs and diagnostics automatically.
4. Warn about unknown variables that use a plugin's declared prefix (e.g. LDAP_URl), to catch typos.

Plugin-owned docs. A plugin's setup guide should live in the plugin too (e.g. plugins/core/auth/Ldap/docs/LDAP.md instead of docs/pages/Setup/LDAP/LDAP.md), and the docs site would pull each plugin's pages and its generated ENV table into its navigation. Then adding or removing a plugin adds or removes its docs, with no edits to the core docs tree.

validate(env) / warnings(env) stay, for rules that involve several settings (e.g. plain ldap:// needs LDAP_STARTTLS or LDAP_ALLOW_INSECURE).

Rollout and costs

• It changes the plugin contract, and the AGENTS.md ENV rule would change with it.
• Reading process.env directly keeps working, so existing plugins can move over one at a time. The LDAP and proxy auth providers would be good first candidates.
• ENVs.md would become partly generated, and the docs site has to collect pages from plugin folders, so both have to fit into the Jekyll build.