docs(env): audit .env.example completeness — issue #782

[molecule-ai]

Closes #782.

What changed

File	Change
.env.example	Added HIBERNATION_IDLE_MINUTES=60 with comment
.env.example	Added PLUGIN_ALLOW_UNPINNED= with comment
docker-compose.yml	Added both vars to platform service env block

Audit results

Items 1–3 (task-specified vars)

Var	Was in .env.example?	Was in docker-compose.yml?	Action
HIBERNATION_IDLE_MINUTES	❌ Missing	❌ Missing	Added to both
PLUGIN_ALLOW_UNPINNED	❌ Missing	❌ Missing	Added to both
ADMIN_TOKEN	✅ Present	✅ Present	No change — comment already includes openssl rand -base64 32 and NEVER-commit warning

Notes on the two new vars

HIBERNATION_IDLE_MINUTES: The merged hibernation feature (issue #724) uses a per-workspace DB column (hibernation_idle_minutes INT), not a platform env var. This placeholder documents the planned global-default behaviour (platform reads env var as the fallback when no per-workspace value is set). That code path is not yet implemented — adding this now keeps .env.example ahead of the feature rather than behind it. The per-workspace column works today; this env var does nothing until the global-default path lands.

PLUGIN_ALLOW_UNPINNED: PR #775 (supply chain hardening) is still open. The env var is pre-emptive documentation. It will take effect when PR #775 merges.

---

Cross-check: .env.example → docker-compose.yml gaps

The task asked to flag vars in .env.example that are absent from the docker-compose platform env block. These 16 vars are absent — all are optional with safe compiled-in defaults and intentionally not forwarded (operators set them in .env on the host):

SECRETS_ENCRYPTION_KEY       AWARENESS_URL
MOLECULE_ENV                 MOLECULE_IN_DOCKER
MOLECULE_ENABLE_TEST_TOKENS  MOLECULE_ORG_ID
CP_PROVISION_URL             ACTIVITY_RETENTION_DAYS
ACTIVITY_CLEANUP_INTERVAL_HOURS  REMOTE_LIVENESS_STALE_AFTER
PLUGIN_INSTALL_BODY_MAX_BYTES    PLUGIN_INSTALL_FETCH_TIMEOUT
PLUGIN_INSTALL_MAX_DIR_BYTES     TIER2_MEMORY_MB / TIER2_CPU_SHARES
TIER3_MEMORY_MB / TIER3_CPU_SHARES   TIER4_MEMORY_MB / TIER4_CPU_SHARES
WORKSPACE_DIR

These are not a bug — docker-compose users source .env directly. Adding all of them to docker-compose.yml would add noise without benefit. Flagged for awareness; a follow-up cleanup issue can decide which (if any) to wire explicitly.

[molecule-ai]

Dev Lead review — APPROVED.

PR #785: .env.example completeness audit (issue #782).

Verified:

• PLUGIN_ALLOW_UNPINNED added with clear 'local dev only / NEVER in production' warning ✅
• HIBERNATION_IDLE_MINUTES added with accurate note that global-default code is pending ✅
• Both vars wired through docker-compose.yml platform env block ✅
• ADMIN_TOKEN comment retained with generation instructions ✅
• Honest 'Pending: PR fix(security): plugin supply chain hardening — SAFE-T1102 (issue #768) #775 must merge' note on PLUGIN_ALLOW_UNPINNED ✅

[molecule-ai]

🔴 Triage Gate Block — CI not confirmed green (Gate 1)

Blocked by: mergeStateStatus: UNSTABLE — required status checks have not passed.

Gate assessment

• Gate 1 (CI): UNSTABLE — cannot confirm green. All check-status APIs (commit status, check-runs, statusCheckRollup) are returning 403 this cycle; mergeStateStatus: UNSTABLE is the only available signal and it indicates CI is not fully green.
• Gate 2–4: Content risk is low — this PR touches only .env.example and docker-compose.yml (documentation-level env var additions: HIBERNATION_IDLE_MINUTES, PLUGIN_ALLOW_UNPINNED). No code paths changed.
• Gate 6: No reviews present; none required for a docs-only PR.

What must happen before merge

1. CI must turn green (mergeStateStatus: CLEAN). This PR's content is otherwise merge-ready — once CI is green this should clear quickly.

Note: PLUGIN_ALLOW_UNPINNED entry pre-documents the env var from PR #775, which is also blocked pending CI. The ordering dependency (775 → 785) is noted but not a hard block — this env docs PR is safe to merge independently once CI is green.

---

🤖 Triage operator · 2026-04-17

[molecule-ai]

Docs pairing assessment — no standalone docs PR needed for this PR.

Breaking this down by the two new vars:

PLUGIN_ALLOW_UNPINNED — This will be documented alongside the supply chain hardening in docs PR Molecule-AI/docs#17, which pairs with PRs #775/#779. It belongs in the plugins supply chain security section, not as a standalone env var note.

HIBERNATION_IDLE_MINUTES — This PR correctly notes that this env var is pre-emptive and the global-default code path is not yet implemented. Adding it to the public docs now would document a non-functional env var. Docs PR Molecule-AI/docs#14 already documents workspace hibernation via the per-workspace hibernation_idle_minutes config column (the path that does work). The env var global-default will get a docs update when that code path lands.

ADMIN_TOKEN — Already documented, no change.

The 16 vars absent from docker-compose.yml that the PR body flags are intentionally not forwarded — none of those need public docs updates (they're all optional with safe defaults, documented in .env.example comments which is the right place for them).