ToolboxAid · ToolboxAid · Jun 28, 2026
diff --git a/dev/build/ProjectInstructions/PROJECT_INSTRUCTIONS.md b/dev/build/ProjectInstructions/PROJECT_INSTRUCTIONS.md
@@ -117,7 +117,7 @@ Rules:
 
 ## Current Version/Date
 
-- Project Instructions Version: 2026.06.28.003
+- Project Instructions Version: 2026.06.28.004
 - Date: 2026-06-28
 - Owner: OWNER
 
@@ -195,6 +195,7 @@ That file owns Start of Day, PLAN_PR, BUILD_PR, APPLY_PR, and invalid command be
 - Project branching policy: `dev/build/ProjectInstructions/PROJECT_BRANCHING_POLICY.md`
 - Project state: `dev/build/ProjectInstructions/PROJECT_STATE.md`
 - Repository folder placement SSoT: `dev/build/ProjectInstructions/repository/canonical_repository_structure.md`
+- Proposed repository layout architecture plan: `dev/build/ProjectInstructions/repository/repository_layout_architecture_plan.md`
 - Codex workflow commands: `dev/build/ProjectInstructions/standards/CODEX_WORKFLOW_COMMANDS.md`
 - Codex Start-of-Day bootstrap: `dev/build/ProjectInstructions/bootstrap/codex_start_of_day_bootstrap.md`
 - Branch lifecycle: `dev/build/ProjectInstructions/addendums/project_instructions_single_source_eod_lock.md`

diff --git a/dev/build/ProjectInstructions/PROJECT_INSTRUCTIONS_VERSION.md b/dev/build/ProjectInstructions/PROJECT_INSTRUCTIONS_VERSION.md
@@ -1,6 +1,6 @@
 # Project Instructions Version
 
-Current Project Instructions Version: 2026.06.28.003
+Current Project Instructions Version: 2026.06.28.004
 
 Last Updated: 2026-06-28
 
@@ -11,6 +11,7 @@ Last Updated: 2026-06-28
 - Added dedicated branching policy document.
 - Startup validation now verifies the branching policy document was loaded instead of duplicating policy text.
 - Added backlog startup assignment policy requiring `BACKLOG_MASTER.md` and Tool Votes/Admin Owner priority signal review during team startup.
+- Added proposed repository layout architecture plan for future `www/`, `api/`, and `dev/` separation.
 - 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.
diff --git a/dev/build/ProjectInstructions/backlog/BACKLOG_MASTER.md b/dev/build/ProjectInstructions/backlog/BACKLOG_MASTER.md
@@ -32,6 +32,18 @@ Completion percentages are updated at SOD, after every accepted PR, and at EOD.
 
 The backlog is the authoritative source for determining the next logical PRs.
 
+## Owner Assignments
+
+### Repository Architecture Simplification
+
+- Team: Owner
+- Product Area: Repository Architecture Simplification
+- Status: Planned
+- Percent Complete: 0%
+- Active PR: PR_26180_OWNER_004-repository-layout-architecture-plan
+- Next Milestone: Architecture plan
+- Source / Reference: `dev/build/ProjectInstructions/repository/repository_layout_architecture_plan.md`
+
 ## Game Journey MVP
 
 ### Idea

diff --git a/dev/build/ProjectInstructions/repository/repository_layout_architecture_plan.md b/dev/build/ProjectInstructions/repository/repository_layout_architecture_plan.md
@@ -0,0 +1,151 @@
+# Repository Layout Architecture Plan
+
+Status: Proposed
+Owner: Owner
+Scope: Documentation/governance only
+
+## Purpose
+
+Document the proposed repository architecture simplification before any file moves occur.
+
+This plan does not authorize moving files, changing runtime behavior, changing package commands, or mixing feature work into layout migration PRs.
+
+## Proposed Future Layout
+
+```text
+www/
+api/
+dev/
+```
+
+### www/
+
+`www/` is the browser-served application.
+
+It will own deployable browser pages, browser assets, and static application entry points currently spread across root product folders, `assets/`, `docs/`, `games/`, `toolbox/`, and browser-facing runtime surfaces.
+
+`www/` must not own authoritative product data.
+
+### api/
+
+`api/` is the Node/API/server application.
+
+It will own server entry points, API routing, API services, environment adapters, database access, storage access, server-side setup, and deployable API/runtime support code.
+
+`api/` owns the Browser -> API -> Postgres/R2 boundary.
+
+### dev/
+
+`dev/` is the developer-only workspace.
+
+It owns Project Instructions, governance, architecture docs, reports, tests, scripts, templates, local developer bootstrap, generated output, zips, logs, and historical archive material.
+
+Production runtime, browser application code, and API deployment code must never depend on `dev/`.
+
+## Deployment Model
+
+The proposed target deployment model has two deployable application surfaces:
+
+- `www/` deploys the browser-served application.
+- `api/` deploys the Node/API/server application.
+
+`dev/` is not deployed as product runtime and must be excluded from runtime dependency paths.
+
+Environment differences remain governed by `.env` values and environment-managed secrets. The same deployable browser and API code paths must be promoted through Local, DEV, IST, UAT, and PROD.
+
+## Browser/API/Database Flow
+
+Required product-data flow:
+
+```text
+Browser -> API -> Postgres/R2
+```
+
+Rules:
+
+- Browser code reads and writes authoritative product data only through the API/service contract.
+- Product metadata is persisted in Postgres.
+- Product assets are persisted in Cloudflare R2.
+- Browser storage, page arrays, source JSON files, `/tmp`, and dev workspace files are not authoritative product-data sources.
+- Seed data is allowed only when it seeds the database through server/API/setup ownership.
+
+## Developer Local-Runtime Flow
+
+Local development may use the team-aware developer bootstrap and local runtime support, but the runtime boundary remains the same:
+
+```text
+Developer command -> dev bootstrap -> local www server + local api server -> Postgres/R2 or approved local provider
+```
+
+Current local bootstrap commands remain unchanged by this plan. This PR does not modify `package.json` commands.
+
+The local developer workflow must continue to prove the same browser/API/database contract that deployed environments use.
+
+## Migration Strategy
+
+Migration must happen through small, reviewable, stacked PRs after this architecture plan is accepted.
+
+Rules:
+
+- No file moves occur in this plan PR.
+- No feature work may be mixed into migration PRs.
+- Each migration PR moves or rewires one bounded ownership area.
+- Each migration PR must preserve the same product behavior unless the PR is explicitly a behavior change.
+- Each migration PR must update references, validation, reports, and ZIP artifacts for only its scoped move.
+- Each migration PR must include rollback notes or clear validation evidence.
+
+## Proposed Stacked PR Sequence
+
+1. `www/` shell and governance
+   - Create the destination shell and document browser-served ownership.
+   - Do not move product pages yet.
+
+2. `api/` shell and governance
+   - Create the destination shell and document API/server ownership.
+   - Do not move API/runtime implementation yet.
+
+3. Browser-served public section moves
+   - Move root browser-served product sections into `www/` in small groups.
+   - Preserve routes through compatibility redirects or server/static configuration as needed.
+
+4. Browser asset moves
+   - Move browser assets into `www/` ownership.
+   - Preserve asset URLs or update references in the same PR.
+
+5. API/server moves
+   - Move Node/API/server entry points and service code into `api/`.
+   - Preserve API contract shape and route behavior.
+
+6. Runtime/shared source boundary cleanup
+   - Move deployable browser/runtime/API modules into `www/` or `api/` ownership as appropriate.
+   - Keep shared runtime dependency direction explicit.
+
+7. Developer bootstrap and validation updates
+   - Update local developer bootstrap and validation paths after deployable surfaces are moved.
+   - Keep `dev/` developer-only.
+
+8. Legacy path cleanup
+   - Remove or archive obsolete empty folders and compatibility shims only after validation proves they are unused.
+
+## Hard Rules
+
+- No feature work may be mixed into repository layout migration.
+- Runtime must never depend on `dev/`.
+- Browser code must never own authoritative product data.
+- Browser code must use Browser -> API -> Postgres/R2 for product data.
+- API/server code must not import from developer-only reports, Project Instructions, tests, or workspace artifacts.
+- Migration PRs must not change package commands unless the PR explicitly owns command migration.
+- Migration PRs must not introduce Creator-writeable repository folders.
+- Migration PRs must not hide behavior changes inside path moves.
+
+## Validation Expectations
+
+Every layout migration PR must at minimum run:
+
+```text
+git diff --check
+npm run validate:canonical-structure
+```
+
+Additional targeted validation must match the moved surface.
+
diff --git a/...rts/PR_26180_OWNER_004-repository-layout-architecture-plan_branch-validation.md b/...rts/PR_26180_OWNER_004-repository-layout-architecture-plan_branch-validation.md
@@ -0,0 +1,13 @@
+# PR_26180_OWNER_004 Branch Validation
+
+| Gate | Result | Evidence |
+|---|---|---|
+| Project Instructions loaded | PASS | Version `2026.06.28.003` loaded before work began; PR bumps to `2026.06.28.004`. |
+| Repository source | PASS | Loaded from `dev/build/ProjectInstructions/`. |
+| Cached memory discarded | PASS | Repository files used as authority. |
+| Branching policy loaded | PASS | `dev/build/ProjectInstructions/PROJECT_BRANCHING_POLICY.md`. |
+| Start branch | PASS | Started from synchronized `main`. |
+| Working branch | PASS | `PR_26180_OWNER_004-repository-layout-architecture-plan`. |
+| Worktree before edits | PASS | Clean before edits. |
+| Scope | PASS | Documentation/governance only. |
+
diff --git a/..._26180_OWNER_004-repository-layout-architecture-plan_manual-validation-notes.md b/..._26180_OWNER_004-repository-layout-architecture-plan_manual-validation-notes.md
@@ -0,0 +1,11 @@
+# PR_26180_OWNER_004 Manual Validation Notes
+
+- Confirmed the new architecture plan is proposal-only and explicitly does not authorize file moves.
+- Confirmed proposed future layout documents `www/`, `api/`, and `dev/`.
+- Confirmed migration hard rules prohibit feature work mixed with path migration.
+- Confirmed runtime dependency on `dev/` is prohibited.
+- Confirmed browser-owned authoritative product data is prohibited.
+- Confirmed `BACKLOG_MASTER.md` contains the planned Owner backlog item.
+- Confirmed Project Instructions version is updated to `2026.06.28.004`.
+- Confirmed no package command changes.
+
diff --git a/dev/reports/PR_26180_OWNER_004-repository-layout-architecture-plan_report.md b/dev/reports/PR_26180_OWNER_004-repository-layout-architecture-plan_report.md
@@ -0,0 +1,53 @@
+# PR_26180_OWNER_004 Repository Layout Architecture Plan Report
+
+## Executive Summary
+
+PASS: Added a documentation/governance-only architecture plan for future repository layout simplification before any file moves.
+
+The proposed future layout is:
+
+- `www/` = browser-served application
+- `api/` = Node/API/server application
+- `dev/` = developer-only workspace
+
+No files were moved. No runtime, UI, API implementation, database implementation, or `package.json` command changes were made.
+
+## Changes
+
+- Added `dev/build/ProjectInstructions/repository/repository_layout_architecture_plan.md`.
+- Updated `PROJECT_INSTRUCTIONS.md` to reference the new proposed layout plan.
+- Bumped Project Instructions version to `2026.06.28.004`.
+- Updated `BACKLOG_MASTER.md` with Owner planned work:
+  - Team: Owner
+  - Product Area: Repository Architecture Simplification
+  - Status: Planned
+  - Percent Complete: 0%
+  - Next Milestone: Architecture plan
+
+## Architecture Plan Coverage
+
+| Required Topic | Result |
+|---|---|
+| Proposed `www/`, `api/`, `dev/` layout | PASS |
+| Deployment model | PASS |
+| Browser/API/database flow | PASS |
+| Developer local-runtime flow | PASS |
+| Migration strategy | PASS |
+| Stacked PR sequence | PASS |
+| No feature work mixed into migration | PASS |
+| Runtime must never depend on `dev/` | PASS |
+| Browser must never own authoritative product data | PASS |
+
+## Scope Validation
+
+Changed files are limited to Project Instructions, backlog governance, and reports.
+
+Implementation files, runtime code, UI files, API implementation files, database implementation files, and package commands were not changed.
+
+## Artifact
+
+Repo-structured outcome ZIP:
+
+```text
+dev/workspace/zips/PR_26180_OWNER_004-repository-layout-architecture-plan_delta.zip
+```
diff --git a/...PR_26180_OWNER_004-repository-layout-architecture-plan_requirement-checklist.md b/...PR_26180_OWNER_004-repository-layout-architecture-plan_requirement-checklist.md
@@ -0,0 +1,19 @@
+# PR_26180_OWNER_004 Requirement Checklist
+
+| Requirement | Result | Notes |
+|---|---|---|
+| Document proposed future layout `www/`, `api/`, `dev/` | PASS | Added to repository layout architecture plan. |
+| Include deployment model | PASS | `www/` and `api/` deployable surfaces documented; `dev/` non-runtime. |
+| Include browser/API/database flow | PASS | Browser -> API -> Postgres/R2 documented. |
+| Include developer local-runtime flow | PASS | Developer command -> dev bootstrap -> local www/API flow documented. |
+| Include migration strategy | PASS | Strategy and constraints documented. |
+| Include stacked PR sequence | PASS | Eight-step proposed sequence documented. |
+| Hard rule: no feature work mixed into migration | PASS | Documented. |
+| Hard rule: runtime must never depend on `dev/` | PASS | Documented. |
+| Hard rule: browser must never own authoritative product data | PASS | Documented. |
+| Update `BACKLOG_MASTER.md` Owner planned item | PASS | Added Team/Product Area/Status/Percent/Next Milestone entry. |
+| Increment Project Instructions version if ProjectInstructions changed | PASS | Version bumped to `2026.06.28.004`. |
+| Do not move files | PASS | No file moves performed. |
+| Do not modify runtime code | PASS | No runtime files changed. |
+| Do not change `package.json` commands | PASS | `package.json` unchanged. |
+
diff --git a/...rts/PR_26180_OWNER_004-repository-layout-architecture-plan_validation-report.md b/...rts/PR_26180_OWNER_004-repository-layout-architecture-plan_validation-report.md
@@ -0,0 +1,23 @@
+# PR_26180_OWNER_004 Validation Report
+
+## Validation Commands
+
+| Command | Result |
+|---|---|
+| `git diff --check` | PASS |
+| `npm run validate:canonical-structure` | PASS |
+
+## Canonical Structure Output
+
+```text
+Canonical repository structure guardrail: PASS
+Blocking violations: 0
+Approved legacy exceptions: 501
+```
+
+## Scope Validation
+
+No runtime, UI, API implementation, database implementation, or package command files changed.
+
+Playwright was not run because this is documentation/governance-only and no runtime/UI files changed.
+
diff --git a/dev/reports/codex_changed_files.txt b/dev/reports/codex_changed_files.txt
@@ -1,23 +1,25 @@
-dev/reports/PR_26179_CHARLIE_022-sprites-tool-shell.md
-dev/reports/PR_26179_CHARLIE_023-sprites-toolbar-placeholders.md
-dev/reports/PR_26179_CHARLIE_024-sprites-canvas-grid.md
-dev/reports/PR_26179_CHARLIE_025-sprites-basic-drawing.md
-dev/reports/PR_26179_CHARLIE_026-sprites-palette-panel.md
-dev/reports/PR_26179_CHARLIE_027-sprites-preview-export.md
-dev/reports/PR_26179_CHARLIE_028-sprites-editor-polish.md
-dev/reports/PR_26179_CHARLIE_029-sprites-clear-reset-controls.md
-dev/reports/PR_26179_CHARLIE_030-sprites-undo-redo.md
-dev/reports/PR_26179_CHARLIE_031-sprites-picker-zoom.md
-dev/reports/PR_26179_CHARLIE_032-sprites-shape-tools.md
-dev/reports/PR_26179_CHARLIE_033-sprites-canvas-preview-sync.md
-dev/reports/PR_26179_CHARLIE_034-sprites-frame-strip.md
-dev/reports/PR_26179_CHARLIE_035-sprites-frame-editing.md
-dev/reports/PR_26179_CHARLIE_036-sprites-animation-preview.md
-dev/reports/PR_26179_CHARLIE_037-sprites-animation-export.md
-dev/reports/PR_26179_CHARLIE_038-sprites-grid-dimension-fix.md
-dev/reports/PR_26179_CHARLIE_039-sprites-color-and-zoom-fix.md
-dev/reports/PR_26179_CHARLIE_040-dev-artifact-location-cleanup.md
-dev/reports/codex_changed_files.txt
-dev/reports/codex_review.diff
-docs_build/dev/reports/codex_changed_files.txt
-docs_build/dev/reports/codex_review.diff
+# git diff --name-status merge-base(origin/main, HEAD)..working-tree
+M	dev/build/ProjectInstructions/PROJECT_INSTRUCTIONS.md
+M	dev/build/ProjectInstructions/PROJECT_INSTRUCTIONS_VERSION.md
+M	dev/build/ProjectInstructions/backlog/BACKLOG_MASTER.md
+M	dev/reports/codex_changed_files.txt
+M	dev/reports/codex_review.diff
+
+# git ls-files --others --exclude-standard
+dev/build/ProjectInstructions/repository/repository_layout_architecture_plan.md
+dev/reports/PR_26180_OWNER_004-repository-layout-architecture-plan_branch-validation.md
+dev/reports/PR_26180_OWNER_004-repository-layout-architecture-plan_manual-validation-notes.md
+dev/reports/PR_26180_OWNER_004-repository-layout-architecture-plan_report.md
+dev/reports/PR_26180_OWNER_004-repository-layout-architecture-plan_requirement-checklist.md
+dev/reports/PR_26180_OWNER_004-repository-layout-architecture-plan_validation-report.md
+
+# git diff --stat merge-base(origin/main, HEAD)..working-tree
+.../ProjectInstructions/PROJECT_INSTRUCTIONS.md    |    3 +-
+ .../PROJECT_INSTRUCTIONS_VERSION.md                |    3 +-
+ .../ProjectInstructions/backlog/BACKLOG_MASTER.md  |   12 +
+ dev/reports/codex_changed_files.txt                |   46 +-
+ dev/reports/codex_review.diff                      | 1085 +++++++-------------
+ 5 files changed, 430 insertions(+), 719 deletions(-)
+
+# merge-base
+b3a2b30f51a1050596bbad2d7db211e1cba45b66