Create repository layout scaffold

Author: ToolboxAid

api/.gitkeep

@@ -0,0 +1 @@
+

dev/build/ProjectInstructions/PROJECT_INSTRUCTIONS.md

@@ -117,7 +117,7 @@ Rules:
 
 ## Current Version/Date
 
-- Project Instructions Version: 2026.06.28.004
+- Project Instructions Version: 2026.06.28.005
 - 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.004
+Current Project Instructions Version: 2026.06.28.005
 
 Last Updated: 2026-06-28
 
@@ -12,6 +12,7 @@ Last Updated: 2026-06-28
 - 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.
+- Added repository layout scaffold governance for `www/`, `api/`, and `dev/local-runtime/`.
 - 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.PR_26179_OWNER_010"
+project_state_version: "2026.06.28.005"
 last_updated: "2026-06-28"
 current_main_commit: "40de767476d70cadfd1292c916844c2f31b6f185"
 repository_status:
@@ -10,21 +10,22 @@ repository_status:
   runtime_database: "Postgres"
   creator_metadata: "API to Postgres"
   creator_assets: "API to R2"
-project_instructions_version: "2026-06-28.PR_26179_OWNER_010"
-repository_structure_version: "2026-06-28.PR_26179_OWNER_010"
-canonical_layout_version: "2026-06-28.PR_26179_OWNER_010"
+project_instructions_version: "2026.06.28.005"
+repository_structure_version: "2026.06.28.005"
+canonical_layout_version: "2026.06.28.005"
 active_teams:
   - "Owner"
   - "Alfa"
   - "Bravo"
   - "Charlie"
   - "Delta"
   - "Golf"
-latest_owner_pr: "PR_26179_OWNER_010-canonical-project-folder-instructions"
-latest_structure_pr: "PR_26179_OWNER_010-canonical-project-folder-instructions"
+latest_owner_pr: "PR_26180_OWNER_005-repository-layout-scaffold"
+latest_structure_pr: "PR_26180_OWNER_005-repository-layout-scaffold"
 valid_top_level_folders:
   - "account/"
   - "admin/"
+  - "api/"
   - "assets/"
   - "community/"
   - "company/"
@@ -39,10 +40,12 @@ valid_top_level_folders:
   - "owner/"
   - "src/"
   - "toolbox/"
+  - "www/"
 valid_dev_folders:
   - "dev/archive/"
   - "dev/build/"
   - "dev/config/"
+  - "dev/local-runtime/"
   - "dev/reports/"
   - "dev/scripts/"
   - "dev/templates/"

dev/build/ProjectInstructions/backlog/BACKLOG_MASTER.md

@@ -38,10 +38,10 @@ The backlog is the authoritative source for determining the next logical PRs.
 
 - 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
+- Status: Active
+- Percent Complete: 10%
+- Active PR: PR_26180_OWNER_005-repository-layout-scaffold
+- Next Milestone: Move browser-served application to `www/`
 - Source / Reference: `dev/build/ProjectInstructions/repository/repository_layout_architecture_plan.md`
 
 ## Game Journey MVP

dev/build/ProjectInstructions/repository/canonical_repository_structure.md

@@ -9,6 +9,7 @@ Establish the canonical repository structure for future development and reduce t
 Valid top-level folders:
 - account/
 - admin/
+- api/
 - assets/
 - community/
 - company/
@@ -23,16 +24,19 @@ Valid top-level folders:
 - owner/
 - src/
 - toolbox/
+- www/
 
 Root product and repo sections:
 - account/, admin/, community/, company/, learn/, legal/, marketplace/, memberships/, and owner/ are production website sections.
 - assets/ contains production website and tool assets.
+- api/ is the target Node/API/server application surface for the repository layout simplification workstream.
 - docs/ is production Docs & Help content.
 - games/ is public game discovery.
 - toolbox/ is the Creator toolbox/workspace.
 - deploy/ contains deployment configuration.
 - dev/ contains the development workspace.
 - src/ contains deployable application/runtime/API source.
+- www/ is the target browser-served application surface for the repository layout simplification workstream.
 
 Deployable application source:
 - src/web/{feature-name}/
@@ -51,6 +55,7 @@ Valid dev workspace folders:
 - dev/archive/
 - dev/build/
 - dev/config/
+- dev/local-runtime/
 - dev/reports/
 - dev/scripts/
 - dev/templates/
@@ -62,6 +67,7 @@ Dev workspace ownership:
 - dev/archive/ owns historical reference material only.
 - dev/build/ owns active Project Instructions, architecture, database DDL/DML/seed docs, standards, backlog, PR planning, and governance.
 - dev/config/ owns development-only runner and tooling configuration.
+- dev/local-runtime/ owns developer-only local runtime bootstrap, team port resolution, local diagnostics, and browser launch orchestration after the migration step that moves those files.
 - dev/reports/ owns authoritative Codex reports for the repository. Reports committed to `main` are the official record.
 - dev/scripts/ owns development-only scripts and runners.
 - dev/templates/ owns reusable development templates.
@@ -96,6 +102,8 @@ These legacy transition buckets may remain until explicit migration PRs move the
 ## Rules
 
 - Root is production website and standard repository configuration only.
+- www/ is the browser-served application target surface for migration.
+- api/ is the Node/API/server application target surface for migration.
 - src/ is deployable application/runtime/API code.
 - dev/ is development workspace only.
 - deploy/ is deployment configuration.

dev/build/ProjectInstructions/repository/repository_layout_architecture_plan.md

@@ -1,6 +1,6 @@
 # Repository Layout Architecture Plan
 
-Status: Proposed
+Status: Active Scaffold
 Owner: Owner
 Scope: Documentation/governance only
 
@@ -10,6 +10,16 @@ Document the proposed repository architecture simplification before any file mov
 
 This plan does not authorize moving files, changing runtime behavior, changing package commands, or mixing feature work into layout migration PRs.
 
+## Current Migration Status
+
+`PR_26180_OWNER_005-repository-layout-scaffold` creates the empty canonical destination shells:
+
+- `www/`
+- `api/`
+- `dev/local-runtime/`
+
+No browser, API, server, test, script, or runtime files move in the scaffold PR.
+
 ## Proposed Future Layout
 
 ```text
@@ -94,38 +104,47 @@ Rules:
 - 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
+## Active Stacked PR Sequence
 
-1. `www/` shell and governance
-   - Create the destination shell and document browser-served ownership.
-   - Do not move product pages yet.
+1. `PR_26180_OWNER_005-repository-layout-scaffold`
+   - Create `www/`, `api/`, and `dev/local-runtime/` shells.
+   - Update architecture docs and backlog status only.
 
-2. `api/` shell and governance
-   - Create the destination shell and document API/server ownership.
-   - Do not move API/runtime implementation yet.
+2. `PR_26180_OWNER_006-move-www-application`
+   - Move browser-served application files into `www/`.
+   - Include root HTML pages, `assets/`, `toolbox/`, `account/`, `legal/`, `learn/`, `play/`, and other browser-served static routes.
+   - Update internal static references only as needed.
+   - Do not move API/server files.
 
-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.
+3. `PR_26180_OWNER_007-move-api-application`
+   - Move server/API application files into `api/`.
+   - Include Local API server runtime files, API routes, services, database, storage, auth, publishing, and admin server code.
+   - Do not move developer-only startup orchestration.
+   - Browser code must not import from `api/`.
 
-4. Browser asset moves
-   - Move browser assets into `www/` ownership.
-   - Preserve asset URLs or update references in the same PR.
+4. `PR_26180_OWNER_008-move-dev-local-runtime`
+   - Move developer-only local runtime into `dev/local-runtime/`.
+   - Include team-aware bootstrap, port config, local startup orchestration, local diagnostics, and browser launch support.
+   - Update `package.json` commands to point to the new local-runtime paths.
 
-5. API/server moves
-   - Move Node/API/server entry points and service code into `api/`.
-   - Preserve API contract shape and route behavior.
+5. `PR_26180_OWNER_009-move-tests-and-validation`
+   - Ensure all tests and validation suites live under `dev/tests/` or the current canonical dev test structure.
+   - Update test paths after the `www/`, `api/`, and `dev/` migrations.
+   - Do not change 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.
+6. `PR_26180_OWNER_010-update-ci-and-scripts`
+   - Update CI, package scripts, validation scripts, and developer utilities for the new layout.
+   - Preserve `npm run dev:bootstrap`, `npm run dev:api`, `npm run dev:web`, and `npm run dev:local-api`.
 
-7. Developer bootstrap and validation updates
-   - Update local developer bootstrap and validation paths after deployable surfaces are moved.
-   - Keep `dev/` developer-only.
+7. `PR_26180_OWNER_011-remove-legacy-layout`
+   - 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.
 
-8. Legacy path cleanup
-   - Remove or archive obsolete empty folders and compatibility shims only after validation proves they are unused.
+8. `PR_26180_OWNER_012-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.
+   - Mark Repository Architecture Simplification complete in `BACKLOG_MASTER.md`.
 
 ## Hard Rules
 
@@ -148,4 +167,3 @@ npm run validate:canonical-structure
 ```
 
 Additional targeted validation must match the moved surface.
-

dev/local-runtime/.gitkeep

@@ -0,0 +1 @@
+

dev/reports/PR_26180_OWNER_005-repository-layout-scaffold_branch-validation.md

@@ -0,0 +1,14 @@
+# PR_26180_OWNER_005-repository-layout-scaffold Branch Validation
+
+| Check | Result | Notes |
+| --- | --- | --- |
+| Startup validation completed | PASS | Project Instructions v2026.06.28.004 loaded before branch creation; PR updates version to v2026.06.28.005. |
+| Current branch | PASS | `PR_26180_OWNER_005-repository-layout-scaffold` |
+| Expected stacked base | PASS | Created from `PR_26180_OWNER_004-repository-layout-architecture-plan`. |
+| Worktree clean before edits | PASS | Branch started with no modified files. |
+| PR model | PASS | Owner stacked PR under Repository Architecture Simplification. |
+| Previous dependency documented | PASS | `PR_26180_OWNER_004-repository-layout-architecture-plan` |
+| Next dependency documented | PASS | `PR_26180_OWNER_006-move-www-application` |
+| Runtime/API/UI/database scope | PASS | No implementation files changed. |
+
+Starting HEAD: `906a0970acd4e3f896cde02a0cc1a593c3122cd9`

dev/reports/PR_26180_OWNER_005-repository-layout-scaffold_manual-validation-notes.md

@@ -0,0 +1,7 @@
+# PR_26180_OWNER_005-repository-layout-scaffold Manual Validation Notes
+
+- Confirmed new scaffold directories are tracked only by `.gitkeep` files.
+- Confirmed no browser pages, assets, API/server code, scripts, tests, or package commands moved in this PR.
+- Confirmed the active stacked PR sequence is documented in the repository layout architecture plan.
+- Confirmed BACKLOG_MASTER.md now identifies PR005 as the active Repository Architecture Simplification milestone.
+- No Product Owner UI validation is required for this scaffold/governance-only step.