Clean remaining legacy layout roots

Author: ToolboxAid

dev/build/ProjectInstructions/PROJECT_INSTRUCTIONS.md

@@ -117,7 +117,7 @@ Rules:
 
 ## Current Version/Date
 
-- Project Instructions Version: 2026.06.28.013
+- Project Instructions Version: 2026.06.28.014
 - Date: 2026-06-28
 - Owner: OWNER
 

dev/build/ProjectInstructions/PROJECT_INSTRUCTIONS_VERSION.md

@@ -1,6 +1,6 @@
 # Project Instructions Version
 
-Current Project Instructions Version: 2026.06.28.013
+Current Project Instructions Version: 2026.06.28.014
 
 Last Updated: 2026-06-28
 
@@ -21,6 +21,7 @@ Last Updated: 2026-06-28
 - Finalized moved test and validation path assumptions for the `www/`, `api/`, and `dev/local-runtime/` layout.
 - Updated CI, package scripts, and developer utilities for the `www/`, `api/`, and `dev/` layout.
 - Removed active references to obsolete legacy layout paths after the `www/`, `api/`, and `dev/` migration steps.
+- Moved the tracked browser-served favicon under `www/`, added remaining root/src audit governance, and documented root `.env` placement policy.
 - Codex must read this version file and the latest repository copy of `PROJECT_INSTRUCTIONS.md` before performing work.
 - Codex must discard previously remembered Project Instructions and treat the repository copy as authoritative.
 - Codex must validate canonical report and ZIP paths, branching model, and legacy path avoidance before work proceeds.

dev/build/ProjectInstructions/PROJECT_STATE.md

@@ -1,7 +1,7 @@
 # Project State
 
 ```yaml
-project_state_version: "2026.06.28.013"
+project_state_version: "2026.06.28.014"
 last_updated: "2026-06-28"
 current_main_commit: "40de767476d70cadfd1292c916844c2f31b6f185"
 repository_status:
@@ -10,18 +10,18 @@ repository_status:
   runtime_database: "Postgres"
   creator_metadata: "API to Postgres"
   creator_assets: "API to R2"
-project_instructions_version: "2026.06.28.013"
-repository_structure_version: "2026.06.28.013"
-canonical_layout_version: "2026.06.28.013"
+project_instructions_version: "2026.06.28.014"
+repository_structure_version: "2026.06.28.014"
+canonical_layout_version: "2026.06.28.014"
 active_teams:
   - "Owner"
   - "Alfa"
   - "Bravo"
   - "Charlie"
   - "Delta"
   - "Golf"
-latest_owner_pr: "PR_26180_OWNER_013-remove-legacy-layout"
-latest_structure_pr: "PR_26180_OWNER_013-remove-legacy-layout"
+latest_owner_pr: "PR_26180_OWNER_014-remaining-legacy-layout-cleanup"
+latest_structure_pr: "PR_26180_OWNER_014-remaining-legacy-layout-cleanup"
 valid_top_level_folders:
   - "api/"
   - "deploy/"

dev/build/ProjectInstructions/addendums/environment_configuration_standards.md

@@ -56,6 +56,18 @@ Runtime startup still reads `.env` values only. The official flow is for each en
 
 `.env.prd` is legacy technical debt only. Do not introduce new references to `.env.prd` except when documenting migration or historical compatibility.
 
+## Runtime Placement Policy
+
+Local `.env` may exist at repository root for developer startup only.
+
+Root `.env` is user/environment-owned, ignored, and never deployed as part of `www/` or `api/`.
+
+Production uses deployment environment variables and environment-managed secrets instead of committed `.env` files.
+
+`www/` must never contain secrets or environment-owned `.env` files.
+
+`api/` reads environment values from `process.env` and the deployment environment.
+
 ## Environment Identity
 
 Allowed `GAMEFOUNDRY_ENVIRONMENT` values:

dev/build/ProjectInstructions/backlog/BACKLOG_MASTER.md

@@ -39,8 +39,8 @@ The backlog is the authoritative source for determining the next logical PRs.
 - Team: Owner
 - Product Area: Repository Architecture Simplification
 - Status: Active
-- Percent Complete: 80%
-- Active PR: PR_26180_OWNER_013-remove-legacy-layout
+- Percent Complete: 90%
+- Active PR: PR_26180_OWNER_014-remaining-legacy-layout-cleanup
 - Next Milestone: Final layout validation and completion report
 - Source / Reference: `dev/build/ProjectInstructions/repository/repository_layout_architecture_plan.md`; `dev/build/ProjectInstructions/repository/www_migration_map.md`
 

dev/build/ProjectInstructions/repository/canonical_repository_structure.md

@@ -121,6 +121,15 @@ These legacy transition buckets may remain until explicit migration PRs move the
 - Environment differences must come from `.env` values or environment-managed secrets.
 - Runtime source filenames must not use team names.
 
+## Environment File Placement
+
+- Local `.env` may exist at repository root for developer startup only.
+- Root `.env` is user/environment-owned, ignored, and never deployed as part of `www/` or `api/`.
+- Production uses deployment environment variables and environment-managed secrets instead of committed `.env` files.
+- `www/` must never contain secrets or environment-owned `.env` files.
+- `api/` reads environment values from `process.env` and the deployment environment.
+- Only `.env.example` is tracked as a repository template.
+
 ## PR Chain Boundary
 
 The development workspace restructure must proceed through sequential scoped PRs. A PR may only move or update the paths named in its purpose.

dev/build/ProjectInstructions/repository/repository_layout_architecture_plan.md

@@ -36,6 +36,8 @@ No browser, API, server, test, script, or runtime files move in the scaffold or
 
 `PR_26180_OWNER_013-remove-legacy-layout` removes active stale references to obsolete legacy paths after the tracked `www/`, `api/`, and `dev/` migration steps.
 
+`PR_26180_OWNER_014-remaining-legacy-layout-cleanup` audits remaining tracked root and `src/` layout items, moves the browser-served favicon into `www/`, and records root `.env` placement policy before final validation.
+
 ## Proposed Future Layout
 
 ```text
@@ -165,7 +167,13 @@ Rules:
    - Remove or retire obsolete legacy paths after all references are updated.
    - Hard stop if any runtime, test, or CI reference still points to old locations.
 
-10. `PR_26180_OWNER_014-final-layout-validation`
+10. `PR_26180_OWNER_014-remaining-legacy-layout-cleanup`
+   - Audit remaining tracked root and `src/` layout items after the `www/`, `api/`, and `dev/` migrations.
+   - Move browser-served root assets that now belong under `www/`.
+   - Document `.env` placement policy for local and deployed environments.
+   - Preserve product behavior and public routes.
+
+11. `PR_26180_OWNER_015-final-layout-validation`
    - Validate final repository layout.
    - Confirm `www/` owns the browser-served app, `api/` owns the server app, and `dev/` owns the developer workspace.
    - Confirm runtime does not depend on `dev/`, browser code does not import `api/`, and legacy references are removed or documented.

dev/reports/PR_26180_OWNER_014-remaining-legacy-layout-cleanup_branch-validation.md

@@ -0,0 +1,10 @@
+# PR_26180_OWNER_014 Branch Validation
+
+| Check | Result | Evidence |
+|---|---:|---|
+| Current branch | PASS | `PR_26180_OWNER_014-remaining-legacy-layout-cleanup` |
+| Expected stacked base | PASS | Created from `PR_26180_OWNER_013-remove-legacy-layout` |
+| Project Instructions loaded | PASS | Repository Project Instructions version `2026.06.28.014` |
+| Branching policy loaded | PASS | `PROJECT_BRANCHING_POLICY.md` version `2026.06.28.002` |
+| Scope | PASS | Remaining layout cleanup, favicon move, environment policy documentation, tests/references only |
+| Runtime/API/database implementation changes | PASS | None |

dev/reports/PR_26180_OWNER_014-remaining-legacy-layout-cleanup_manual-validation-notes.md

@@ -0,0 +1,8 @@
+# PR_26180_OWNER_014 Manual Validation Notes
+
+- Public favicon URL remains `/favicon.svg`.
+- Static route compatibility now verifies that `/favicon.svg` resolves to the browser-served `www/favicon.svg` file.
+- No `.env` files were moved into `www/` or `api/`.
+- `src/` remains in place because current application, API client, shared runtime, dev tooling, and tests still reference it.
+- Root ignored/generated artifacts were not staged.
+- Playwright coverage output generated by the local run was not included as a PR change.

dev/reports/PR_26180_OWNER_014-remaining-legacy-layout-cleanup_report.md

@@ -0,0 +1,48 @@
+# PR_26180_OWNER_014 Remaining Legacy Layout Cleanup Report
+
+## Executive Summary
+
+PR_26180_OWNER_014 audits the remaining tracked repository layout after the `www/`, `api/`, and `dev/` migration stack. The only tracked browser-served root file found in scope was `favicon.svg`, which is now under `www/favicon.svg` while public references remain `/favicon.svg`.
+
+The PR also documents environment file placement policy: local `.env` files remain user/environment-owned at the repository root and are never deployed; production uses deployment-managed environment variables/secrets; `www/` must not contain secrets; `api/` reads environment values from `process.env` and the deployment environment.
+
+## Scope Decision
+
+- Browser-served favicon moved from repository root to `www/`.
+- Public favicon URL `/favicon.svg` preserved.
+- `src/` retained as an active transition namespace because tracked browser, API, dev tooling, and tests still import from it.
+- No `.env` files moved into `www/` or `api/`.
+- No runtime/API/UI/database behavior changed.
+
+## Root Audit
+
+Tracked root entries are limited to standard repository metadata/config plus `api/`, `dev/`, `src/`, and `www/`. Ignored local folders/files such as local `.env*`, generated workspace outputs, and dependency folders are not part of this PR and were not staged.
+
+Additional standard root files retained as repository configuration/history:
+
+- `.codex/`
+- `.gitattributes`
+- `.githooks/`
+- `.gitignore`
+- `AGENTS.md`
+- `LICENSE`
+
+## src/ Audit
+
+`src/` is not empty and remains referenced by current `www/`, `api/`, `dev/tests/`, and `dev/tools/` surfaces. Current Project Instructions document `src/advanced`, `src/api`, `src/engine`, `src/shared`, `src/tools`, and `src/dev-runtime/admin` as legacy transition buckets pending explicit follow-up migration. This PR does not move or delete `src/`.
+
+## File Evidence
+
+- `www/favicon.svg`: browser-served favicon location after the move.
+- `dev/tests/dev-runtime/StaticWebRootCompatibility.test.mjs`: verifies `/favicon.svg` resolves to `www/favicon.svg`.
+- `dev/scripts/PS/deploy/WebsiteRepoDeploymentCommon.ps1`: deployment include list now references `www/favicon.svg`.
+- `dev/build/ProjectInstructions/repository/canonical_repository_structure.md`: documents root `.env`, `www/`, and `api/` environment ownership.
+- `dev/build/ProjectInstructions/addendums/environment_configuration_standards.md`: adds the runtime placement policy for environment values.
+
+## Remaining Technical Debt
+
+The PowerShell deployment helper still contains broader legacy include defaults such as root `index.html`, `games`, `samples`, `src`, and `tools`. This PR updates only the tracked favicon path because changing the broader deploy staging semantics would be a separate deployment-layout PR.
+
+## Owner Recommendation
+
+Keep this PR focused as the remaining legacy layout cleanup pass. Follow with the final layout validation PR after stacked dependencies land.