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.005
+- Project Instructions Version: 2026.06.28.006
 - Date: 2026-06-28
 - Owner: OWNER
 
@@ -196,6 +196,7 @@ That file owns Start of Day, PLAN_PR, BUILD_PR, APPLY_PR, and invalid command be
 - 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`
+- `www/` migration map: `dev/build/ProjectInstructions/repository/www_migration_map.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.005
+Current Project Instructions Version: 2026.06.28.006
 
 Last Updated: 2026-06-28
 
@@ -13,6 +13,7 @@ Last Updated: 2026-06-28
 - 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/`.
+- Added `www/` migration map for safe browser-served application movement planning.
 - 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/PROJECT_STATE.md b/dev/build/ProjectInstructions/PROJECT_STATE.md
@@ -1,7 +1,7 @@
 # Project State
 
 ```yaml
-project_state_version: "2026.06.28.005"
+project_state_version: "2026.06.28.006"
 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.005"
-repository_structure_version: "2026.06.28.005"
-canonical_layout_version: "2026.06.28.005"
+project_instructions_version: "2026.06.28.006"
+repository_structure_version: "2026.06.28.006"
+canonical_layout_version: "2026.06.28.006"
 active_teams:
   - "Owner"
   - "Alfa"
   - "Bravo"
   - "Charlie"
   - "Delta"
   - "Golf"
-latest_owner_pr: "PR_26180_OWNER_005-repository-layout-scaffold"
-latest_structure_pr: "PR_26180_OWNER_005-repository-layout-scaffold"
+latest_owner_pr: "PR_26180_OWNER_006-www-migration-map"
+latest_structure_pr: "PR_26180_OWNER_006-www-migration-map"
 valid_top_level_folders:
   - "account/"
   - "admin/"

diff --git a/dev/build/ProjectInstructions/backlog/BACKLOG_MASTER.md b/dev/build/ProjectInstructions/backlog/BACKLOG_MASTER.md
@@ -39,10 +39,10 @@ The backlog is the authoritative source for determining the next logical PRs.
 - Team: Owner
 - Product Area: Repository Architecture Simplification
 - Status: Active
-- Percent Complete: 10%
-- Active PR: PR_26180_OWNER_005-repository-layout-scaffold
+- Percent Complete: 15%
+- Active PR: PR_26180_OWNER_006-www-migration-map
 - Next Milestone: Move browser-served application to `www/`
-- Source / Reference: `dev/build/ProjectInstructions/repository/repository_layout_architecture_plan.md`
+- Source / Reference: `dev/build/ProjectInstructions/repository/repository_layout_architecture_plan.md`; `dev/build/ProjectInstructions/repository/www_migration_map.md`
 
 ## Game Journey MVP
 

diff --git a/dev/build/ProjectInstructions/repository/repository_layout_architecture_plan.md b/dev/build/ProjectInstructions/repository/repository_layout_architecture_plan.md
@@ -12,13 +12,15 @@ This plan does not authorize moving files, changing runtime behavior, changing p
 
 ## Current Migration Status
 
-`PR_26180_OWNER_005-repository-layout-scaffold` creates the empty canonical destination shells:
+`PR_26180_OWNER_005-repository-layout-scaffold` created the empty canonical destination shells:
 
 - `www/`
 - `api/`
 - `dev/local-runtime/`
 
-No browser, API, server, test, script, or runtime files move in the scaffold PR.
+`PR_26180_OWNER_006-www-migration-map` documents the current browser-served surface and safe move requirements before any browser files move into `www/`.
+
+No browser, API, server, test, script, or runtime files move in the scaffold or migration-map PRs.
 
 ## Proposed Future Layout
 
@@ -110,37 +112,41 @@ Rules:
    - Create `www/`, `api/`, and `dev/local-runtime/` shells.
    - Update architecture docs and backlog status only.
 
-2. `PR_26180_OWNER_006-move-www-application`
+2. `PR_26180_OWNER_006-www-migration-map`
+   - Document current browser-served root paths, imports, local server behavior, test assumptions, compatibility needs, and validation lanes.
+   - Do not move browser files or change package commands.
+
+3. `PR_26180_OWNER_007-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. `PR_26180_OWNER_007-move-api-application`
+4. `PR_26180_OWNER_008-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. `PR_26180_OWNER_008-move-dev-local-runtime`
+5. `PR_26180_OWNER_009-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. `PR_26180_OWNER_009-move-tests-and-validation`
+6. `PR_26180_OWNER_010-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. `PR_26180_OWNER_010-update-ci-and-scripts`
+7. `PR_26180_OWNER_011-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. `PR_26180_OWNER_011-remove-legacy-layout`
+8. `PR_26180_OWNER_012-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. `PR_26180_OWNER_012-final-layout-validation`
+9. `PR_26180_OWNER_013-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.

diff --git a/dev/build/ProjectInstructions/repository/www_migration_map.md b/dev/build/ProjectInstructions/repository/www_migration_map.md
@@ -0,0 +1,221 @@
+# www Migration Map
+
+Status: Active planning map
+Owner: Owner
+Workstream: Repository Architecture Simplification
+PR: PR_26180_OWNER_006-www-migration-map
+
+## Purpose
+
+Document the current browser-served repository surface and the safe sequence required before moving files into `www/`.
+
+This map is a no-runtime-change governance artifact. It does not move browser files, change package commands, change local server behavior, or update runtime imports.
+
+## Executive Summary
+
+The browser-served application currently depends on repository-root static serving.
+
+Current local runtime, test helpers, and browser pages assume URLs such as `/index.html`, `/toolbox/index.html`, `/assets/theme-v2/css/theme.css`, `/account/sign-in.html`, `/admin/system-health.html`, and `/games/index.html` resolve from the repository root.
+
+Moving browser files into `www/` is feasible, but the move must preserve public route URLs while changing the filesystem lookup root. A direct folder move without route compatibility would break Playwright tests, local API static serving, team-aware bootstrap static serving, Node test root aliases, and browser imports that still reference root-level `src/`, `toolbox/`, and `assets/`.
+
+## Current Browser-Served Surface
+
+Current root-level browser-served entry points and folders include:
+
+| Path | Current role | Files | HTML files | Move target |
+| --- | --- | ---: | ---: | --- |
+| `index.html` | Root marketing/product entry | 1 | 1 | `www/index.html` |
+| `account/` | Account pages | 13 | 11 | `www/account/` |
+| `admin/` | Admin/Owner pages | 18 | 16 | `www/admin/` |
+| `assets/` | Browser assets, Theme V2, tool assets, partials | 328 | 5 | `www/assets/` |
+| `community/` | Community/public pages | 3 | 3 | `www/community/` |
+| `company/` | Company/public pages | 7 | 7 | `www/company/` |
+| `docs/` | Production Docs & Help pages | 5 | 4 | `www/docs/` only when route preservation is ready |
+| `games/` | Public game discovery pages | 12 | 8 | `www/games/` |
+| `learn/` | Learning pages | 11 | 11 | `www/learn/` |
+| `legal/` | Legal pages | 17 | 9 | `www/legal/` |
+| `marketplace/` | Marketplace page | 1 | 1 | `www/marketplace/` |
+| `memberships/` | Membership page | 1 | 1 | `www/memberships/` |
+| `owner/` | Owner governance/admin pages | 8 | 8 | `www/owner/` |
+| `toolbox/` | Creator toolbox pages and legacy sidecars | 57 | 49 | `www/toolbox/` |
+
+No top-level `play/` folder exists in the current tracked repository root. Any existing `play/` string references must be reviewed as route/content references before a future move introduces or preserves a `play/` route.
+
+## Current Reference Inventory
+
+Broad active-reference search across browser roots, `src/`, `dev/scripts/`, and `dev/tests/` found:
+
+| Reference | Approximate active files | Notes |
+| --- | ---: | --- |
+| `assets/` | 230 | Theme CSS/JS, images, tool JS, workers, partials, and test fixtures. |
+| `toolbox/` | 241 | Tool routes, registry routes, tests, validation scripts, and server route compatibility. |
+| `account/` | 43 | Account routes, return URLs, and Playwright coverage. |
+| `legal/` | 13 | Footer/navigation route references and page links. |
+| `learn/` | 9 | Learn route links and navigation. |
+| `play/` | 7 | No root folder exists; review references manually before introducing a route. |
+| `src/` | 451 | Browser imports, server imports, tests, validation aliases, and current runtime/source modules. |
+
+The high `src/` count means the browser migration cannot be treated as static files only. Several browser-facing pages import modules from root-level `src/`, including account/admin/toolbox flows.
+
+## Examples Of References That Must Be Preserved Or Rewritten
+
+### Preserve public route URLs
+
+These URLs should continue working for users and tests during the move:
+
+- `/index.html`
+- `/toolbox/index.html`
+- `/toolbox/{tool}/index.html`
+- `/account/{page}.html`
+- `/admin/{page}.html`
+- `/games/index.html`
+- `/learn/index.html`
+- `/legal/index.html`
+- `/marketplace/index.html`
+- `/memberships/index.html`
+
+### Rewrite filesystem lookup paths
+
+Static servers and test helpers should map public URLs to `www/` filesystem paths after the move:
+
+- `/index.html` -> `www/index.html`
+- `/toolbox/index.html` -> `www/toolbox/index.html`
+- `/assets/theme-v2/css/theme.css` -> `www/assets/theme-v2/css/theme.css`
+
+### Preserve service/API route behavior
+
+API routes must remain API routes and must not be resolved as static browser files:
+
+- `/api/*`
+- `/api/toolbox/*`
+- `/api/session/*`
+- `/api/auth/*`
+
+### Browser import references needing migration review
+
+Examples of current references that depend on root-level path relationships:
+
+- `account/user-controls-page.js` imports from `../src/api/` and `../src/engine/`.
+- `admin/tool-votes.js` imports from `../src/api/` and `../toolbox/tool-registry-api-client.js`.
+- `admin/db-viewer.js` imports from `../src/api/`.
+- `owner/notes.html` loads `../src/dev-runtime/admin/admin-notes-viewer.js`.
+- `toolbox/toolRegistry.js` imports from `../src/shared/toolbox/tool-metadata-inventory.js`.
+- `assets/toolbox/*/js/index.js` imports from `../../../../src/` or `../../../../toolbox/` in several tool flows.
+
+These references can be preserved temporarily by serving compatibility paths from the repository root, but the final architecture should move browser-facing runtime modules into `www/` or an approved deployable browser module surface.
+
+## Current Local Web Server Root Behavior
+
+Three active server/helper surfaces currently resolve static browser paths from the repository root:
+
+| File | Current behavior |
+| --- | --- |
+| `dev/scripts/start-dev.mjs` | Team-aware bootstrap static server resolves requests with `path.resolve(repoRoot, \`.\${normalizedPath}\`)`. `/` maps to `/index.html`; `/tools/*` maps to `/toolbox/*`; `/admin/admin-notes.html` maps to `/src/dev-runtime/admin/notes.html`. |
+| `src/dev-runtime/server/local-api-server.mjs` | Legacy local API alias serves API routes and falls back to static files from `repoRoot`. `/tools/*` maps to `/toolbox/*`; `/admin/admin-notes.html` maps to `/src/dev-runtime/admin/notes.html`. |
+| `dev/tests/helpers/playwrightRepoServer.mjs` | Playwright test server mirrors repo-root static serving and the `/tools/*` and admin-notes compatibility routes. |
+
+The actual `www/` move must update these filesystem lookup roots or introduce a shared route resolver that can resolve public routes to `www/` while preserving API route ownership.
+
+## Current Test Assumptions
+
+Playwright and runtime tests currently assume root-based public routes and root-relative filesystem paths:
+
+- 96 Playwright/helper/runtime files reference public routes such as `/toolbox`, `/account`, `/admin`, `/games`, `/learn`, `/legal`, `/marketplace`, `/memberships`, or `/index.html`.
+- `dev/tests/playwright/tools/ToolNavigationPrevNext.spec.mjs` opens `/toolbox/index.html` and `/toolbox/game-design/index.html`.
+- `dev/tests/playwright/tools/BuildPathProgressSimplification.spec.mjs` opens `/index.html`, `/toolbox/index.html`, and `/admin/tool-votes.html`.
+- `dev/tests/playwright/tools/EnvironmentBannerCoverage.spec.mjs` covers root/home, marketplace, learn, and memberships route families.
+- `dev/tests/runtime/V2*` tests frequently assert `toolbox/{tool}/index.html` filesystem or URL behavior.
+- `dev/scripts/run-node-tests.mjs` and `dev/scripts/run-node-test-files.mjs` register root aliases for `/src/` and `/toolbox/`.
+
+The move PR must update test helpers and route expectations in the same PR that changes the filesystem root. Browser-visible URLs should remain stable unless Owner explicitly approves a public URL change.
+
+## Preserve Versus Rewrite
+
+### Preserve
+
+- Public browser URLs.
+- `/tools/*` compatibility routing to toolbox pages until Owner approves route removal.
+- `/api/*` service contract routes.
+- Theme V2 asset URLs as browser routes, even if filesystem paths move under `www/`.
+- Tool route semantics and Product Owner test flows.
+- Existing package commands until the PR explicitly scoped to command migration.
+
+### Rewrite
+
+- Filesystem path resolution in local static servers and Playwright test helpers.
+- Internal static file lookup roots from repository root to `www/`.
+- Relative links/imports that break because source and target files move together.
+- Validation scripts that inspect browser-served file locations.
+- Coverage mapping that classifies `toolbox/`, `assets/theme-v2/js/`, and browser routes after the move.
+
+### Defer
+
+- Moving server/API code into `api/`.
+- Moving developer bootstrap into `dev/local-runtime/`.
+- Removing legacy root compatibility routes.
+- Changing package commands.
+- Renaming public URLs.
+
+## Compatibility Redirects Or Shims
+
+Temporary compatibility is likely required.
+
+Recommended approach for the actual move PR:
+
+1. Preserve public URLs while changing filesystem roots.
+2. Add a shared route resolution helper or equivalent route table for local runtime/test servers.
+3. Keep `/tools/*` -> `/toolbox/*` compatibility.
+4. Keep root URL families stable: `/account`, `/admin`, `/assets`, `/games`, `/learn`, `/legal`, `/marketplace`, `/memberships`, `/owner`, `/toolbox`.
+5. Do not introduce browser redirects unless a static route cannot be served directly.
+6. Document every temporary shim with removal criteria for the legacy-layout cleanup PR.
+
+## Required Sequence For Safe www Move
+
+1. Freeze the public route contract.
+2. Move `index.html` and browser-served folders into `www/`.
+3. Update local static server filesystem roots to resolve from `www/` for browser routes.
+4. Preserve `/api/*` API routing before static fallback.
+5. Preserve compatibility route aliases such as `/tools/*`.
+6. Update Playwright repo server helper to mirror runtime static route resolution.
+7. Update browser relative imports and links only where the move changes relative depth.
+8. Update validation scripts and coverage prefix mapping for `www/` paths.
+9. Run targeted Playwright lanes for root/home, account/admin, toolbox navigation, environment banner, and impacted tool flows.
+10. Produce a compatibility ledger for any root path still supported temporarily.
+
+## Validation Lanes Required For The Actual Move PR
+
+Minimum validation for the actual `www/` move:
+
+- `git diff --check`
+- `npm run validate:canonical-structure`
+- `node ./dev/scripts/run-platform-validation-suite.mjs`
+- targeted Playwright route lanes touching:
+  - root/home
+  - account sign-in/session
+  - admin owner navigation
+  - toolbox navigation
+  - Tool Display Mode
+  - environment banner coverage
+  - games index/discovery
+- targeted runtime tests that assert `toolbox/{tool}/index.html` or filesystem existence.
+
+Fallback validation if targeted routing failures are broad:
+
+- `npm run test:workspace-v2`
+- `npm run test:lane:tool-navigation`
+- `npm run test:lane:tool-display-mode`
+- impacted Playwright specs under `dev/tests/playwright/account/`, `dev/tests/playwright/games/`, and `dev/tests/playwright/tools/`.
+
+## Owner Recommendation
+
+Do not perform the browser move until the actual move PR explicitly owns:
+
+- static server filesystem root migration,
+- Playwright helper root migration,
+- route compatibility ledger,
+- browser relative import/link rewrites,
+- validation script prefix updates,
+- and targeted Playwright execution.
+
+The next implementation PR should be a focused `www/` move PR that preserves public URLs while moving the filesystem root to `www/`.
diff --git a/dev/reports/PR_26180_OWNER_006-www-migration-map_branch-validation.md b/dev/reports/PR_26180_OWNER_006-www-migration-map_branch-validation.md
@@ -0,0 +1,14 @@
+# PR_26180_OWNER_006-www-migration-map Branch Validation
+
+| Check | Result | Notes |
+| --- | --- | --- |
+| Startup validation completed | PASS | Project Instructions v2026.06.28.005 loaded before branch creation; PR updates version to v2026.06.28.006. |
+| Current branch | PASS | `PR_26180_OWNER_006-www-migration-map` |
+| Expected stacked base | PASS | Created from `PR_26180_OWNER_005-repository-layout-scaffold`. |
+| 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_005-repository-layout-scaffold` |
+| Next dependency documented | PASS | `PR_26180_OWNER_007-move-www-application` |
+| Runtime/API/UI/database scope | PASS | No implementation files changed. |
+
+Starting HEAD: `31bb8f9238e0f7d81bc64fb8d2e15c4fb82875ff`
diff --git a/dev/reports/PR_26180_OWNER_006-www-migration-map_manual-validation-notes.md b/dev/reports/PR_26180_OWNER_006-www-migration-map_manual-validation-notes.md
@@ -0,0 +1,7 @@
+# PR_26180_OWNER_006-www-migration-map Manual Validation Notes
+
+- Confirmed this PR documents the `www/` migration and does not perform it.
+- Confirmed current browser-served paths rely on repository-root static serving.
+- Confirmed public URLs should be preserved during the actual move.
+- Confirmed compatibility route handling is needed before moving files into `www/`.
+- Confirmed no Product Owner UI validation is required for this no-runtime-change map.