Merge pull request #203 from ToolboxAid/PR_26177_OWNER_051-environment-configuration-standards

PR_26177_OWNER_051-environment-configuration-standards

Author: ToolboxAid

.env.example

@@ -4,6 +4,29 @@
 # Official environment model:
 # Local (VS Code) -> DEV -> IST -> UAT -> PROD
 #
+# Only this .env.example file is committed to the repository.
+# Real .env files are user/environment-owned and must live outside
+# the repo clone or be injected by deployment.
+#
+# Official external copy-source names when a copy-source file is used:
+# - .env.local
+# - .env.dev
+# - .env.ist
+# - .env.uat
+# - .env.prod
+# Legacy technical debt only:
+# - .env.prd
+#
+# Example external layout:
+# - /env/local/.env
+# - /env/dev/.env
+# - /env/ist/.env
+# - /env/uat/.env
+# - /env/prod/.env
+# - /GFS/ repo clone
+#
+# The app/runtime reads .env values supplied by the target environment.
+#
 # Environment invariance:
 # Use an identical deployable artifact in every environment.
 # Only .env values and environment-managed secret values differ.
@@ -19,10 +42,21 @@
 # Configure runtime auth, database, and storage connections here.
 # Missing connection configuration reports diagnostics instead of falling back.
 
-# Browser-safe public site configuration exposed through the server API.
+# Required environment identity.
+# Allowed values: local, dev, ist, uat, prod.
+GAMEFOUNDRY_ENVIRONMENT=local
+
+# Browser-safe public site/API configuration exposed through the server API.
 # These values may be sent to browser pages. Do not place secrets here.
+# Local uses 127.0.0.1 hostnames.
+# DEV/IST/UAT/PROD use configured *.gamefoundrystudio.com hostnames.
+# One shared API/service contract is used everywhere; URLs may differ by .env only.
+# Do not split Local API and Public API contracts.
 GAMEFOUNDRY_SITE_URL=
 GAMEFOUNDRY_API_URL=
+
+# Display-only environment label.
+# Do not use this value for runtime behavior, API/service selection, storage selection, or feature behavior.
 # Valid environment banner labels:
 # - Local Development Environment
 # - Development Environment

docs_build/dev/BUILD_PR.md

@@ -1,29 +1,40 @@
-# PR_26177_OWNER_050-environment-governance-model
+# PR_26177_OWNER_051-environment-configuration-standards
 
 ## Purpose
 
-Establish the official Game Foundry Studio environment governance model and align the active configuration example comments/placeholders with that model.
+Define the official Game Foundry Studio environment configuration standards that build on the OWNER_050 environment model.
 
 ## Source Of Truth
 
-This `BUILD_PR.md` and the user request are the source of truth for `PR_26177_OWNER_050-environment-governance-model`.
+This `BUILD_PR.md` and the user request are the source of truth for `PR_26177_OWNER_051-environment-configuration-standards`.
 
 ## Exact Scope
 
-- Documentation/governance only unless `.env.example` comment or placeholder updates are required.
-- Establish `Local (VS Code) -> DEV -> IST -> UAT -> PROD` as the official environment model.
-- Define the environment invariance rule: the deployable artifact is identical across all environments; only `.env` values and environment-managed secret values differ.
-- Define one shared API/service contract across all environments.
-- Define Supabase Auth, Supabase Postgres, and Cloudflare R2 as required for every environment.
-- Define R2 top-level prefixes:
-  - `/local/`
-  - `/dev/`
-  - `/ist/`
-  - `/uat/`
-  - `/prod/`
-- Define that all environments receive approved guest seed data for all tools.
-- State SQLite is deprecated/retired and is not an active runtime database.
-- Review `.env.example` and update comments/placeholders to match the official model.
+- Governance/documentation only.
+- Build on OWNER_050 environment model.
+- Standardize environment file names:
+  - `.env.local`
+  - `.env.dev`
+  - `.env.ist`
+  - `.env.uat`
+  - `.env.prod`
+- Treat `.env.prd` as legacy technical debt only.
+- Add `GAMEFOUNDRY_ENVIRONMENT` allowed values:
+  - `local`
+  - `dev`
+  - `ist`
+  - `uat`
+  - `prod`
+- Keep `GAMEFOUNDRY_ENVIRONMENT_LABEL` display-only.
+- Document that only `.env` values and environment-managed secrets differ.
+- Document that the deployable artifact must remain identical.
+- Document one shared API/service contract.
+- Document feature flags cannot create permanent environment-specific behavior.
+- Review `.env.example` comments/placeholders only.
+- Clarify that only `.env.example` is committed to the repository.
+- Clarify that real `.env` files are user/environment-owned and must live outside the repo clone or be injected by deployment.
+- Document the external `/env/<target>/.env` layout next to the `/GFS/` repo clone.
+- Do not change runtime behavior.
 - Create required Codex reports under `docs_build/dev/reports/`.
 - Create repo-structured delta ZIP under `tmp/`.
 
@@ -33,17 +44,16 @@ This `BUILD_PR.md` and the user request are the source of truth for `PR_26177_OW
 - `docs_build/dev/PROJECT_INSTRUCTIONS.md`
 - `docs_build/dev/ProjectInstructions/PROJECT_INSTRUCTIONS.md`
 - `docs_build/dev/ProjectInstructions/README.txt`
+- `docs_build/dev/ProjectInstructions/addendums/environment_configuration_standards.md`
 - `docs_build/dev/ProjectInstructions/addendums/environment_governance_model.md`
-- `docs_build/dev/ProjectInstructions/addendums/postgres_only.md`
 - `docs_build/dev/ProjectInstructions/addendums/release_gate.md`
-- `docs_build/dev/admin-notes/index.txt`
 - `.env.example`
-- `docs_build/dev/reports/PR_26177_OWNER_050-environment-governance-model.md`
-- `docs_build/dev/reports/PR_26177_OWNER_050-environment-governance-model_branch-validation.md`
-- `docs_build/dev/reports/PR_26177_OWNER_050-environment-governance-model_requirement-checklist.md`
-- `docs_build/dev/reports/PR_26177_OWNER_050-environment-governance-model_validation-lane.md`
-- `docs_build/dev/reports/PR_26177_OWNER_050-environment-governance-model_manual-validation-notes.md`
-- `docs_build/dev/reports/PR_26177_OWNER_050-environment-governance-model_instruction-compliance-checklist.md`
+- `docs_build/dev/reports/PR_26177_OWNER_051-environment-configuration-standards.md`
+- `docs_build/dev/reports/PR_26177_OWNER_051-environment-configuration-standards_branch-validation.md`
+- `docs_build/dev/reports/PR_26177_OWNER_051-environment-configuration-standards_requirement-checklist.md`
+- `docs_build/dev/reports/PR_26177_OWNER_051-environment-configuration-standards_validation-lane.md`
+- `docs_build/dev/reports/PR_26177_OWNER_051-environment-configuration-standards_manual-validation-notes.md`
+- `docs_build/dev/reports/PR_26177_OWNER_051-environment-configuration-standards_instruction-compliance-checklist.md`
 - `docs_build/dev/reports/codex_review.diff`
 - `docs_build/dev/reports/codex_changed_files.txt`
 
@@ -53,24 +63,27 @@ This `BUILD_PR.md` and the user request are the source of truth for `PR_26177_OW
 - No UI changes.
 - No engine core changes.
 - No `start_of_day` folder changes.
-- No `.env`, `.env.dev`, `.env.ist`, `.env.uat`, or `.env.prd` secret/value edits.
+- No actual `.env`, `.env.local`, `.env.dev`, `.env.ist`, `.env.uat`, `.env.prod`, or `.env.prd` secret/value file edits.
+- No committed real `.env.*` copy-source files.
 - No API implementation changes.
 - No storage implementation changes.
 - No database migration or DDL changes.
+- No feature flag implementation changes.
 
 ## Validation
 
 Run exactly:
 
 ```powershell
-git status
 git diff --check
 ```
 
+Playwright is not required unless runtime files change.
+
 ## Artifact
 
 Create repo-structured delta ZIP:
 
 ```text
-tmp/PR_26177_OWNER_050-environment-governance-model_delta.zip
+tmp/PR_26177_OWNER_051-environment-configuration-standards_delta.zip
 ```

docs_build/dev/PROJECT_INSTRUCTIONS.md

@@ -497,8 +497,9 @@ Environment invariance rule:
 Shared API/service contract:
 - One shared API/service contract is required across Local (VS Code), DEV, IST, UAT, and PROD.
 - Browser/UI/runtime code must consume the same contract in every environment.
-- Environment-specific endpoints, keys, buckets, and prefixes are configuration values only.
+- Environment-specific URLs, endpoints, keys, buckets, and prefixes are `.env` or environment-managed secret/config values only.
 - Do not create environment-specific API/service contracts.
+- Do not split Local API and Public API contracts. Local and shared environments use the same API/service contract; URLs may differ by `.env` only.
 
 Required services in every environment:
 - Supabase Auth
@@ -519,11 +520,37 @@ Required Cloudflare R2 top-level prefixes:
 
 Derived R2 paths for projects, backups, exports, or future storage lanes must stay under the matching top-level prefix for the active environment.
 
-The following files are copy-source files only:
+Only `.env.example` is committed to the repository.
+
+Real `.env` files are user/environment-owned and must live outside the repo clone or be injected by deployment.
+
+Official external environment file names when a copy-source file is used outside the repo clone:
+- `.env.local`
 - `.env.dev`
 - `.env.ist`
 - `.env.uat`
-- `.env.prd` is the legacy copy-source filename for PROD values; new environment governance uses the `PROD` environment name.
+- `.env.prod`
+
+Example external layout:
+- `/env/local/.env`
+- `/env/dev/.env`
+- `/env/ist/.env`
+- `/env/uat/.env`
+- `/env/prod/.env`
+- `/GFS/` repo clone
+
+The app/runtime reads `.env` values supplied by the target environment. It must not require real `.env` files to be committed inside the repo clone.
+
+`.env.prd` is legacy technical debt only. New environment governance uses `.env.prod` for external PROD copy-source naming and the `PROD` environment name.
+
+Allowed `GAMEFOUNDRY_ENVIRONMENT` values:
+- `local`
+- `dev`
+- `ist`
+- `uat`
+- `prod`
+
+`GAMEFOUNDRY_ENVIRONMENT_LABEL` is display-only and must not drive runtime behavior, API/service selection, database selection, storage selection, or feature behavior.
 
 Valid environment stages are:
 - `Local (VS Code)`
@@ -552,6 +579,16 @@ Do not introduce runtime parameters such as:
 
 Application code, runtime code, API/service code, and DB runtime scripts must not branch behavior by deployment target name.
 
+Host/domain configuration:
+- Local (VS Code) uses `127.0.0.1` hostnames.
+- DEV, IST, UAT, and PROD use configured `*.gamefoundrystudio.com` hostnames.
+- Host/domain differences are configuration values only and must not create separate deployable artifacts or environment-specific code.
+
+Feature flag governance:
+- Feature flags must not create permanent environment-specific behavior.
+- Feature flags may be used only for staged rollout, testing, or emergency mitigation.
+- Feature flags must be removed, promoted to normal behavior, or documented as active temporary controls when the rollout, test, or mitigation ends.
+
 ## RUNTIME SCRIPT NAMING GOVERNANCE
 
 Active runtime script names should describe capability rather than vendor/provider.

docs_build/dev/ProjectInstructions/PROJECT_INSTRUCTIONS.md

@@ -39,6 +39,8 @@ Existing Project Instructions remain preserved in their current locations. This
 
 `docs_build/dev/ProjectInstructions/addendums/environment_governance_model.md` defines the official environment model, environment invariance rule, shared API/service contract rule, required Supabase/Postgres/R2 services, required R2 prefixes, and SQLite retired status.
 
+`docs_build/dev/ProjectInstructions/addendums/environment_configuration_standards.md` defines official `.env` file names, environment variable values, host/domain configuration, API URL configuration, R2 prefix configuration, and feature flag governance.
+
 ## Merge Control
 
 No PR in this operating system is merged without explicit owner approval.

docs_build/dev/ProjectInstructions/README.txt

@@ -50,3 +50,4 @@ Addendum index:
 - Codex Project Instructions Startup: project-instructions/addendums/codex-project-instructions-startup.md
 - Project Reference Files Governance: docs_build/dev/ProjectInstructions/addendums/project_reference_files.md
 - Environment Governance Model: docs_build/dev/ProjectInstructions/addendums/environment_governance_model.md
+- Environment Configuration Standards: docs_build/dev/ProjectInstructions/addendums/environment_configuration_standards.md

docs_build/dev/ProjectInstructions/addendums/environment_configuration_standards.md

@@ -0,0 +1,112 @@
+# Environment Configuration Standards
+
+Status: Approved
+Owner: OWNER
+
+## Purpose
+
+Define the official environment configuration standards that build on the OWNER_050 environment model.
+
+This addendum is governance/documentation only. It does not change runtime behavior, API implementation, storage implementation, database DDL, or secret values.
+
+## Source Model
+
+This standard builds on:
+
+```text
+Local (VS Code) -> DEV -> IST -> UAT -> PROD
+```
+
+The deployable artifact must remain identical across all environments.
+
+Only `.env` values and environment-managed secret values may differ by environment.
+
+Deployable artifacts must not contain environment-specific application code, runtime code, API/service code, database code, storage code, or feature behavior.
+
+## Official Environment Files
+
+Only `.env.example` is committed to the repository.
+
+Real `.env` files are user/environment-owned and must live outside the repo clone or be injected by deployment.
+
+Official external environment copy-source file names when a copy-source file is used outside the repo clone:
+
+- `.env.local`
+- `.env.dev`
+- `.env.ist`
+- `.env.uat`
+- `.env.prod`
+
+Example external layout:
+
+- `/env/local/.env`
+- `/env/dev/.env`
+- `/env/ist/.env`
+- `/env/uat/.env`
+- `/env/prod/.env`
+- `/GFS/` repo clone
+
+The app/runtime reads `.env` values supplied by the target environment.
+
+Runtime startup still reads `.env` values only. The official flow is for each environment to supply those values from outside the repo clone or through deployment injection before validation/startup.
+
+`.env.prd` is legacy technical debt only. Do not introduce new references to `.env.prd` except when documenting migration or historical compatibility.
+
+## Environment Identity
+
+Allowed `GAMEFOUNDRY_ENVIRONMENT` values:
+
+- `local`
+- `dev`
+- `ist`
+- `uat`
+- `prod`
+
+`GAMEFOUNDRY_ENVIRONMENT` identifies the active configuration lane. It must not cause application, runtime, API/service, database, storage, or feature behavior forks.
+
+`GAMEFOUNDRY_ENVIRONMENT_LABEL` is display-only. It may be used for visual labels and diagnostics, but must not drive runtime behavior, API/service selection, database selection, storage selection, or feature behavior.
+
+## Host And Domain Configuration
+
+Local (VS Code) uses `127.0.0.1` hostnames.
+
+DEV, IST, UAT, and PROD use configured `*.gamefoundrystudio.com` hostnames.
+
+Host/domain differences are configuration values only. They must not create separate deployable artifacts or environment-specific code.
+
+## R2 Prefix Configuration
+
+Required Cloudflare R2 top-level prefixes:
+
+- Local (VS Code): `/local/`
+- DEV: `/dev/`
+- IST: `/ist/`
+- UAT: `/uat/`
+- PROD: `/prod/`
+
+R2 project, backup, export, import, or future storage paths must stay under the matching environment prefix.
+
+## API/Service Contract Configuration
+
+One shared API/service contract is required across Local (VS Code), DEV, IST, UAT, and PROD.
+
+Rules:
+
+- API URLs may differ by `.env` only.
+- Do not split Local API and Public API contracts.
+- Do not create environment-specific API/service contracts.
+- Browser/UI/runtime code must use the same API/service contract shape in every environment.
+
+## Feature Flag Governance
+
+Feature flags must not create permanent environment-specific behavior.
+
+Allowed feature flag uses:
+
+- staged rollout
+- testing
+- emergency mitigation
+
+Feature flags must be removed, promoted to normal behavior, or documented as active temporary controls when the rollout, test, or mitigation ends.
+
+Feature flags must not become a substitute for the environment invariance rule.

docs_build/dev/ProjectInstructions/addendums/environment_governance_model.md

@@ -112,3 +112,7 @@ Rules:
 ## Scope Boundary
 
 This governance addendum defines documentation and configuration contract rules only. It does not change runtime code, API implementation code, storage implementation code, database DDL, or secret values.
+
+## Related Configuration Standard
+
+`docs_build/dev/ProjectInstructions/addendums/environment_configuration_standards.md` defines the official `.env` file names, allowed `GAMEFOUNDRY_ENVIRONMENT` values, display-only environment label rule, host/domain configuration, API URL configuration, and feature flag governance.

docs_build/dev/ProjectInstructions/addendums/release_gate.md

@@ -38,6 +38,7 @@ The release gate should confirm these files when relevant to the PR:
 - `docs_build/dev/ProjectInstructions/addendums/pr_workflow.md`
 - `docs_build/dev/ProjectInstructions/addendums/project_reference_files.md`
 - `docs_build/dev/ProjectInstructions/addendums/environment_governance_model.md`
+- `docs_build/dev/ProjectInstructions/addendums/environment_configuration_standards.md`
 - `docs_build/dev/ProjectInstructions/team_assignments/team_ownership.md`
 - `docs_build/dev/admin-notes/Installs required.txt` when present
 - `docs_build/dev/admin-notes/Table layout.txt` when present