Clarify external environment file ownership

Author: ToolboxAid

.env.example

@@ -4,7 +4,11 @@
 # Official environment model:
 # Local (VS Code) -> DEV -> IST -> UAT -> PROD
 #
-# Official copy-source file names:
+# 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
@@ -13,6 +17,16 @@
 # 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.

docs_build/dev/BUILD_PR.md

@@ -31,6 +31,9 @@ This `BUILD_PR.md` and the user request are the source of truth for `PR_26177_OW
 - 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/`.
@@ -61,6 +64,7 @@ This `BUILD_PR.md` and the user request are the source of truth for `PR_26177_OW
 - No engine core changes.
 - No `start_of_day` folder changes.
 - 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.

docs_build/dev/PROJECT_INSTRUCTIONS.md

@@ -520,14 +520,28 @@ 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.prod`
 
-`.env.prd` is legacy technical debt only. New environment governance uses `.env.prod` and the `PROD` environment name.
+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`

docs_build/dev/ProjectInstructions/addendums/environment_configuration_standards.md

@@ -25,15 +25,30 @@ Deployable artifacts must not contain environment-specific application code, run
 
 ## Official Environment Files
 
-Official environment copy-source file names:
+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`
 
-Runtime startup still loads `.env` only. The official flow is to copy the selected source file to `.env` before validation/startup.
+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.
 

docs_build/dev/reports/PR_26177_OWNER_051-environment-configuration-standards.md

@@ -8,8 +8,12 @@ Status: PASS
 ## Summary
 
 - Built on OWNER_050 by adding official environment configuration standards.
-- Standardized official copy-source file names: `.env.local`, `.env.dev`, `.env.ist`, `.env.uat`, and `.env.prod`.
+- Clarified that only `.env.example` is committed to the repository.
+- Clarified that real `.env` files are user/environment-owned and must live outside the repo clone or be injected by deployment.
+- Documented external environment layout: `/env/local/.env`, `/env/dev/.env`, `/env/ist/.env`, `/env/uat/.env`, `/env/prod/.env`, and `/GFS/` repo clone.
+- Standardized official external copy-source file names: `.env.local`, `.env.dev`, `.env.ist`, `.env.uat`, and `.env.prod`.
 - Documented `.env.prd` as legacy technical debt only.
+- Clarified that `.env.prod` remains the official PROD naming when a copy-source file is used outside the repo.
 - Added allowed `GAMEFOUNDRY_ENVIRONMENT` values: `local`, `dev`, `ist`, `uat`, and `prod`.
 - Clarified that `GAMEFOUNDRY_ENVIRONMENT_LABEL` is display-only.
 - Preserved the identical deployable artifact rule and the rule that only `.env` values and environment-managed secret values may differ.

docs_build/dev/reports/PR_26177_OWNER_051-environment-configuration-standards_branch-validation.md

@@ -19,7 +19,8 @@
 - No runtime files changed: PASS.
 - No UI files changed: PASS.
 - No engine core files changed: PASS.
-- No actual `.env.*` secret/value files changed: PASS.
+- Only `.env.example` was changed; no actual `.env.*` secret/value files changed: PASS.
+- Real `.env` files are documented as external or deployment-injected, not repo-owned: PASS.
 
 ## Result
 

docs_build/dev/reports/PR_26177_OWNER_051-environment-configuration-standards_instruction-compliance-checklist.md

@@ -13,6 +13,8 @@
 - [x] Avoided engine core changes.
 - [x] Avoided `start_of_day` changes.
 - [x] Avoided actual `.env.*` secret/value file edits.
+- [x] Clarified only `.env.example` is committed.
+- [x] Clarified real `.env` files are external or deployment-injected.
 - [x] Did not run Playwright because no runtime files changed.
 - [x] Created required Codex reports under `docs_build/dev/reports/`.
 - [x] Created repo-structured delta ZIP under `tmp/`.

docs_build/dev/reports/PR_26177_OWNER_051-environment-configuration-standards_manual-validation-notes.md

@@ -4,8 +4,12 @@ Manual validation was limited to governance/documentation review because this PR
 
 ## Notes
 
-- Confirmed official environment file names are `.env.local`, `.env.dev`, `.env.ist`, `.env.uat`, and `.env.prod`.
+- Confirmed only `.env.example` is committed to the repository.
+- Confirmed real `.env` files are user/environment-owned and must live outside the repo clone or be injected by deployment.
+- Confirmed external layout documents `/env/local/.env`, `/env/dev/.env`, `/env/ist/.env`, `/env/uat/.env`, `/env/prod/.env`, and `/GFS/` repo clone.
+- Confirmed official external copy-source names are `.env.local`, `.env.dev`, `.env.ist`, `.env.uat`, and `.env.prod`.
 - Confirmed `.env.prd` is documented as legacy technical debt only.
+- Confirmed `.env.prod` remains the official PROD naming when a copy-source file is used outside the repo.
 - Confirmed allowed `GAMEFOUNDRY_ENVIRONMENT` values are `local`, `dev`, `ist`, `uat`, and `prod`.
 - Confirmed `GAMEFOUNDRY_ENVIRONMENT_LABEL` is display-only.
 - Confirmed only `.env` values and environment-managed secret values may differ by environment.

docs_build/dev/reports/PR_26177_OWNER_051-environment-configuration-standards_requirement-checklist.md

@@ -2,12 +2,21 @@
 
 - [x] Keep scope governance/documentation only.
 - [x] Build on OWNER_050 environment model.
-- [x] Standardize `.env.local`.
-- [x] Standardize `.env.dev`.
-- [x] Standardize `.env.ist`.
-- [x] Standardize `.env.uat`.
-- [x] Standardize `.env.prod`.
+- [x] Clarify only `.env.example` is committed to the repository.
+- [x] Clarify real `.env` files are user/environment-owned and must live outside the repo clone or be injected by deployment.
+- [x] Document `/env/local/.env`.
+- [x] Document `/env/dev/.env`.
+- [x] Document `/env/ist/.env`.
+- [x] Document `/env/uat/.env`.
+- [x] Document `/env/prod/.env`.
+- [x] Document `/GFS/` repo clone layout.
+- [x] Standardize external copy-source `.env.local`.
+- [x] Standardize external copy-source `.env.dev`.
+- [x] Standardize external copy-source `.env.ist`.
+- [x] Standardize external copy-source `.env.uat`.
+- [x] Standardize external copy-source `.env.prod`.
 - [x] Treat `.env.prd` as legacy technical debt only.
+- [x] Keep `.env.prod` as the official PROD naming when a copy-source file is used outside the repo.
 - [x] Define `GAMEFOUNDRY_ENVIRONMENT=local`.
 - [x] Define `GAMEFOUNDRY_ENVIRONMENT=dev`.
 - [x] Define `GAMEFOUNDRY_ENVIRONMENT=ist`.
@@ -24,6 +33,7 @@
 - [x] Document no Local API vs Public API split.
 - [x] Document feature flags cannot create permanent environment-specific behavior.
 - [x] Review and update `.env.example` comments/placeholders only.
+- [x] Remove wording that implies `.env.local`, `.env.dev`, `.env.ist`, `.env.uat`, or `.env.prod` are repo files.
 - [x] Do not change runtime behavior.
 - [x] Produce PR-specific report.
 - [x] Produce branch validation report.

docs_build/dev/reports/PR_26177_OWNER_051-environment-configuration-standards_validation-lane.md

@@ -17,6 +17,7 @@ Documentation/governance lane.
 - Database migration validation skipped: no DDL, migration, or runtime database implementation changed.
 - Storage runtime validation skipped: no storage implementation changed.
 - Feature flag runtime validation skipped: no feature flag implementation changed.
+- External environment file layout validation is documentation-only: no filesystem or deployment changes were made.
 
 ## Result