PR_26177_OWNER_050-environment-governance-model

Merge OWNER_050 environment governance model.

Author: ToolboxAid

.env.example

@@ -1,19 +1,35 @@
-# Game Foundry Studio local development environment
+# Game Foundry Studio environment-managed configuration example
 # ENVIRONMENT
 
-# Configure the runtime auth and database connections here.
+# Official environment model:
+# Local (VS Code) -> DEV -> IST -> UAT -> PROD
+#
+# Environment invariance:
+# Use an identical deployable artifact in every environment.
+# Only .env values and environment-managed secret values differ.
+#
+# Approved guest seed data for all tools belongs in every environment.
+# Do not store guest seed payloads in .env.
+#
+# Required services in every environment:
+# - Supabase Auth
+# - Supabase Postgres
+# - Cloudflare R2
+#
+# 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.
 # These values may be sent to browser pages. Do not place secrets here.
 GAMEFOUNDRY_SITE_URL=
 GAMEFOUNDRY_API_URL=
 # Valid environment banner labels:
+# - Local Development Environment
 # - Development Environment
 # - Integration Testing Environment
 # - User Acceptance Testing Environment
 # - Production
-GAMEFOUNDRY_ENVIRONMENT_LABEL="Development Environment"
+GAMEFOUNDRY_ENVIRONMENT_LABEL="Local Development Environment"
 
 # Database SSL mode is required and authoritative.
 # Supported values:
@@ -33,13 +49,14 @@ GAMEFOUNDRY_DATABASE_URL=
 
 # Server-only Postgres backup storage.
 # Copy this file to .env and keep the active deployment target's prefix:
+# LOCAL /local/backups/postgres/
 # DEV /dev/backups/postgres/
 # IST /ist/backups/postgres/
 # UAT /uat/backups/postgres/
-# PRD /prd/backups/postgres/
+# PROD /prod/backups/postgres/
 # R2 object prefixes are created by object upload; no manual folder creation is required.
 GAMEFOUNDRY_DB_BACKUP_STORAGE_PROVIDER=r2
-GAMEFOUNDRY_DB_BACKUP_PREFIX=/dev/backups/postgres/
+GAMEFOUNDRY_DB_BACKUP_PREFIX=/local/backups/postgres/
 
 # Optional temporary server-side pg_dump staging override.
 # Leave blank to use the OS temp directory. Do not point this at repo tmp/.
@@ -50,17 +67,25 @@ GAMEFOUNDRY_DB_BACKUP_DIR=
 
 # Server-only project asset storage configuration.
 # Browser uploads must go through the server API and must not receive these secrets.
+# Official Cloudflare R2 top-level prefixes:
+# LOCAL /local/
+# DEV /dev/
+# IST /ist/
+# UAT /uat/
+# PROD /prod/
+#
 # Approved GAMEFOUNDRY_STORAGE_PROJECTS_PREFIX values:
+# LOCAL /local/projects/
 # DEV /dev/projects/
 # IST /ist/projects/
 # UAT /uat/projects/
-# PRD /prod/projects/
+# PROD /prod/projects/
 GAMEFOUNDRY_STORAGE_ENDPOINT=
 GAMEFOUNDRY_STORAGE_ACCESS_KEY_ID=
 
 GAMEFOUNDRY_STORAGE_SECRET_ACCESS_KEY=
 GAMEFOUNDRY_STORAGE_BUCKET=
-GAMEFOUNDRY_STORAGE_PROJECTS_PREFIX=
+GAMEFOUNDRY_STORAGE_PROJECTS_PREFIX=/local/projects/
 
 # Environment-specific service limit placeholders.
 # Leave empty when live usage/limit reporting is not configured.

docs_build/dev/BUILD_PR.md

@@ -1,109 +1,76 @@
-# PR_26175_ALFA_047-theme-v2-svg-icon-registry
+# PR_26177_OWNER_050-environment-governance-model
 
 ## Purpose
-Create a shared Theme V2 SVG icon asset registry and authoritative validation specification so toolbox and platform UI can use approved standalone SVG files from one repo-owned source instead of page-local SVG, ad hoc CSS drawings, Font Awesome glyphs, conversation screenshots, vague row references, CSS-only generation, or a JS-only registry.
+
+Establish the official Game Foundry Studio environment governance model and align the active configuration example comments/placeholders with that model.
 
 ## Source Of Truth
-This `BUILD_PR.md` is the source of truth for `PR_26175_ALFA_047-theme-v2-svg-icon-registry`.
+
+This `BUILD_PR.md` and the user request are the source of truth for `PR_26177_OWNER_050-environment-governance-model`.
 
 ## Exact Scope
-- Remove the incorrect JS-only icon registry implementation from the ALFA_047 delta.
-- Use the user-authored SVG files already present under `assets/theme-v2/svg/` as the authoritative source.
-- Do not regenerate, redesign, simplify, optimize, or redraw any SVG icon artwork in this PR.
-- Required SVG files:
-  - `gfs-chevron-left.svg`
-  - `gfs-chevron-right.svg`
-  - `gfs-chevron-up.svg`
-  - `gfs-chevron-down.svg`
-  - `gfs-add.svg`
-  - `gfs-subtract.svg`
-  - `gfs-trash.svg`
-  - `gfs-close.svg`
-  - `gfs-warning.svg`
-  - `gfs-error.svg`
-  - `gfs-success.svg`
-  - `gfs-info.svg`
-  - `gfs-fullscreen.svg`
-  - `gfs-exit-fullscreen.svg`
-  - `gfs-menu.svg`
-  - `gfs-search.svg`
-  - `gfs-settings.svg`
-- Validate each required SVG is well-formed XML.
-- Validate each SVG uses `viewBox="0 0 24 24"`, `fill="none"`, `stroke="currentColor"`, `stroke-linecap="round"`, and `stroke-linejoin="round"`.
-- Do not create `expand` or `collapse` icon naming.
-- Do not create `delete` icon naming.
-- Do not replace the standalone SVG assets with a JS-only icon registry.
-- Do not replace the standalone SVG assets with CSS-only icon generation.
-- Create `docs_build/design/theme-v2-icons/theme-v2-icon-style-guide.md` as the authoritative specification for all future Theme V2 SVG icons.
-- Create or update `assets/theme-v2/svg/README.md` as the registry documentation for the authoritative SVG asset pack.
-- Document the approved validation rules and the no-regeneration/no-redesign policy.
-- If any required SVG is missing, report validation failure instead of generating a replacement.
-- Do not convert existing UI controls in this PR.
+
+- 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.
+- Create required Codex reports under `docs_build/dev/reports/`.
+- Create repo-structured delta ZIP under `tmp/`.
 
 ## Exact Targets
+
 - `docs_build/dev/BUILD_PR.md`
-- `assets/theme-v2/svg/gfs-chevron-left.svg`
-- `assets/theme-v2/svg/gfs-chevron-right.svg`
-- `assets/theme-v2/svg/gfs-chevron-up.svg`
-- `assets/theme-v2/svg/gfs-chevron-down.svg`
-- `assets/theme-v2/svg/gfs-add.svg`
-- `assets/theme-v2/svg/gfs-subtract.svg`
-- `assets/theme-v2/svg/gfs-trash.svg`
-- `assets/theme-v2/svg/gfs-close.svg`
-- `assets/theme-v2/svg/gfs-warning.svg`
-- `assets/theme-v2/svg/gfs-error.svg`
-- `assets/theme-v2/svg/gfs-success.svg`
-- `assets/theme-v2/svg/gfs-info.svg`
-- `assets/theme-v2/svg/gfs-fullscreen.svg`
-- `assets/theme-v2/svg/gfs-exit-fullscreen.svg`
-- `assets/theme-v2/svg/gfs-menu.svg`
-- `assets/theme-v2/svg/gfs-search.svg`
-- `assets/theme-v2/svg/gfs-settings.svg`
-- `assets/theme-v2/svg/README.md`
-- `docs_build/design/theme-v2-icons/theme-v2-icon-style-guide.md`
-- `tests/playwright/tools/ThemeV2SvgIconRegistry.spec.mjs`
-- `docs_build/dev/reports/PR_26175_ALFA_047-theme-v2-svg-icon-registry_report.md`
-- `docs_build/dev/reports/PR_26175_ALFA_047-theme-v2-svg-icon-registry_validation-lane.md`
-- `docs_build/dev/reports/PR_26175_ALFA_047-theme-v2-svg-icon-registry_requirements-checklist.md`
-- `docs_build/dev/reports/PR_26175_ALFA_047-theme-v2-svg-icon-registry_manual-validation-notes.md`
+- `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_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/codex_review.diff`
 - `docs_build/dev/reports/codex_changed_files.txt`
 
-## Evidence Sources
-- `docs_build/pr/PLAN_PR_26175_ALFA_047-theme-v2-svg-icon-registry.md`
-- `assets/theme-v2/images/gfs-chevron-down.svg`
-- `assets/theme-v2/images/gfs-chevron-up.svg`
-
 ## Out Of Scope
-- No chevron conversion.
-- No status/action icon conversion.
-- No layout utility icon conversion.
-- No JS-only icon registry.
-- No CSS-only icon generation.
-- No Theme V2 CSS changes.
-- No runtime UI conversion.
-- No accordion conversion.
-- No Font Awesome removal.
-- No broad visual redesign.
-- No page-local CSS.
-- No inline styles.
-- No style blocks.
-- No browser-owned product data as source of truth.
-- No API/service/repository contract changes.
+
+- No runtime code changes.
+- 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 API implementation changes.
+- No storage implementation changes.
+- No database migration or DDL changes.
 
 ## Validation
+
 Run exactly:
 
 ```powershell
-npx playwright test tests/playwright/tools/ThemeV2SvgIconRegistry.spec.mjs --workers=1
-rg -n "<[s]tyle|[s]tyle=" docs_build/design/theme-v2-icons/theme-v2-icon-style-guide.md tests/playwright/tools/ThemeV2SvgIconRegistry.spec.mjs
+git status
+git diff --check
 ```
 
 ## Artifact
+
 Create repo-structured delta ZIP:
 
 ```text
-tmp/PR_26175_ALFA_047-theme-v2-svg-icon-registry_delta.zip
+tmp/PR_26177_OWNER_050-environment-governance-model_delta.zip
 ```

docs_build/dev/PROJECT_INSTRUCTIONS.md

@@ -441,12 +441,13 @@ Toolbox and Admin tool metadata must use a shared DB-backed tool metadata source
 
 ## DATABASE DIRECTION
 
-SQLite is deprecated.
-Postgres is authoritative.
+Postgres is the authoritative active runtime database.
+
+SQLite is deprecated/retired and is not an active runtime database for Local (VS Code), DEV, IST, UAT, or PROD.
 
 Rules:
 - New database work must target Postgres.
-- Local API -> Postgres is the required direction.
+- Local (VS Code) API -> Postgres is the required direction.
 - New PRs must not introduce SQLite persistence.
 - Do not add new SQLite services.
 - Do not add new SQLite DDL.
@@ -478,17 +479,58 @@ Rules:
 
 Runtime startup loads `.env` only.
 
+Official environment model:
+- `Local (VS Code)`
+- `DEV`
+- `IST`
+- `UAT`
+- `PROD`
+
+Promotion order:
+- `Local (VS Code) -> DEV -> IST -> UAT -> PROD`
+
+Environment invariance rule:
+- The deployable artifact is identical across every environment.
+- Only `.env` values and environment-managed secret values differ between environments.
+- Application code, runtime code, API/service code, database runtime scripts, migrations, and bundles must not fork by environment name.
+
+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.
+- Do not create environment-specific API/service contracts.
+
+Required services in every environment:
+- Supabase Auth
+- Supabase Postgres
+- Cloudflare R2
+
+Guest seed data rule:
+- All environments receive approved guest seed data for all tools.
+- Guest seed data is shared environment setup data, not an environment-specific behavior fork.
+- Guest seed data must be applied through the shared data/service contract and must not require per-environment application code.
+
+Required Cloudflare R2 top-level prefixes:
+- Local (VS Code): `/local/`
+- DEV: `/dev/`
+- IST: `/ist/`
+- UAT: `/uat/`
+- PROD: `/prod/`
+
+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:
 - `.env.dev`
 - `.env.ist`
 - `.env.uat`
-- `.env.prd`
+- `.env.prd` is the legacy copy-source filename for PROD values; new environment governance uses the `PROD` environment name.
 
-Valid deployment targets are:
+Valid environment stages are:
+- `Local (VS Code)`
 - `DEV`
 - `IST`
 - `UAT`
-- `PRD`
+- `PROD`
 
 Manual deployment-target flow:
 1. Copy the selected `.env.<target>` file to `.env`.
@@ -501,11 +543,12 @@ Runtime environment parameters are prohibited.
 Do not introduce runtime parameters such as:
 - `--env`
 - `--environment`
+- `ENVIRONMENT=LOCAL`
 - `ENVIRONMENT=DEV`
 - `ENVIRONMENT=UAT`
-- `ENVIRONMENT=PRD`
+- `ENVIRONMENT=PROD`
 
-`DEV`, `IST`, `UAT`, and `PRD` are deployment targets, not application behaviors.
+`Local (VS Code)`, `DEV`, `IST`, `UAT`, and `PROD` are environment stages, not application behaviors.
 
 Application code, runtime code, API/service code, and DB runtime scripts must not branch behavior by deployment target name.
 

docs_build/dev/ProjectInstructions/PROJECT_INSTRUCTIONS.md

@@ -16,6 +16,7 @@ The Project Instructions operating system provides additive governance for:
 - deprecation workflow
 - archive and history preservation
 - recognized project instruction/reference files
+- environment governance
 
 ## Preservation
 
@@ -34,6 +35,10 @@ Existing Project Instructions remain preserved in their current locations. This
 
 `docs_build/dev/ProjectInstructions/addendums/project_reference_files.md` defines additional valid project instruction/reference files that must be included in future Project Instructions reviews when present in `ProjectInstructions.zip`, the active project instruction directory, or `docs_build/dev/admin-notes/`.
 
+## Environment Governance
+
+`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.
+
 ## Merge Control
 
 No PR in this operating system is merged without explicit owner approval.

docs_build/dev/ProjectInstructions/README.txt

@@ -49,3 +49,4 @@ Addendum index:
 - Codex Artifact and Reporting Standard: project-instructions/addendums/codex-artifact-and-reporting-standard.md
 - 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