BUILD_PR_LEVEL_10_3_MIGRATE_TOOL_LOCAL_SAMPLES_TO_SAMPLES

- Migrated tool-local samples into /samples
- Updated samples index
- Removed local sample dropdown/select entries from processed tools
- Preserved tool explicit-input behavior

PR Details:
- Processes Vector Map Editor, Vector Asset Studio, Parallax Scene Studio, and Tilemap Studio
- No validators
- No start_of_day changes

Author: DavidQ

docs/dev/reports/expected_delta_template.md

@@ -1,23 +1,24 @@
 # Expected Codex Return / Delta Template
 
-## Expected Changed Files
-- `games/GravityWell/game.manifest.json` if style defaults need adding
-- Vector Asset Studio / Workspace Manager binding file(s)
-- Runtime test file(s) for Vector Asset Studio binding
-- `docs/dev/reports/level_10_2f_vector_asset_palette_paint_binding_report.md`
+## Expected Changed/Added Files
+- `samples/phase-*/####/**`
+- `samples/index.html`
+- tool UI files for removing local sample dropdown/select entries
+- tests for sample index/launch behavior
+- `docs/dev/reports/level_10_3_tool_local_sample_migration_report.md`
 - `docs/dev/roadmaps/MASTER_ROADMAP_ENGINE.md` if status update needed
 
 ## Expected Validation Summary
-- `gravity_well_palette_loaded=true`
-- `gravity_well_vector_asset_present=true`
-- `gravity_well_vector_palette_selected=true`
-- `gravity_well_vector_stroke_selected=true`
-- `gravity_well_vector_paint_selected=<true|not-required-fill-false>`
-- `binding_test_added_or_updated=true`
-- `validators_added=0`
+- `tools_scanned=4`
+- `tool_local_samples_found=<count>`
+- `samples_migrated=<count>`
+- `duplicate_sample_ids=0`
+- `samples_index_updated=true`
+- `migrated_samples_launch=true`
+- `tool_local_sample_dropdowns_removed=true`
 - `start_of_day_changes=0`
 
 ## Expected Delta ZIP
 Codex must create:
 
-`tmp/BUILD_PR_LEVEL_10_2F_VECTOR_ASSET_PALETTE_PAINT_BINDING_FIX_delta.zip`
+`tmp/BUILD_PR_LEVEL_10_3_MIGRATE_TOOL_LOCAL_SAMPLES_TO_SAMPLES_delta.zip`

docs/dev/reports/level_10_3_tool_local_sample_migration_report.md

@@ -0,0 +1,163 @@
+# Level 10.3 Tool-Local Sample Migration Report
+
+Date: 2026-04-26
+Build: `BUILD_PR_LEVEL_10_3_MIGRATE_TOOL_LOCAL_SAMPLES_TO_SAMPLES`
+
+## Scope Summary
+- Migrated discovered tool-local sample/demo payloads for:
+  - `tools/Vector Map Editor`
+  - `tools/Vector Asset Studio`
+  - `tools/Parallax Scene Studio`
+- Audited `tools/Tilemap Studio` for tool-local sample/demo entries.
+- Added migrated sample entries under `samples/phase-12` using next available IDs `1212` to `1220`.
+- Updated samples hub indexing through `samples/metadata/samples.index.metadata.json` (the data source used by `samples/index.html`).
+- Removed tool-local sample dropdown/select UI entries from processed tools while keeping explicit query-based preset input support.
+
+## Source To Destination Mapping
+
+### Vector Map Editor
+- Source tool: `tools/Vector Map Editor`
+- Source sample/demo path: `tools/Vector Map Editor/samples/overworld_route_map.editor.json`
+- Destination sample path: `samples/phase-12/1212/`
+- Assigned phase/id: `phase-12 / 1212`
+- Files moved/copied:
+  - Created `samples/phase-12/1212/sample-1212-vector-map-editor.json`
+  - Created `samples/phase-12/1212/index.html`
+  - Created `samples/phase-12/1212/assets/images/preview.svg`
+
+- Source tool: `tools/Vector Map Editor`
+- Source sample/demo path: `tools/Vector Map Editor/samples/dungeon_layout_map.editor.json`
+- Destination sample path: `samples/phase-12/1213/`
+- Assigned phase/id: `phase-12 / 1213`
+- Files moved/copied:
+  - Created `samples/phase-12/1213/sample-1213-vector-map-editor.json`
+  - Created `samples/phase-12/1213/index.html`
+  - Created `samples/phase-12/1213/assets/images/preview.svg`
+
+- Source tool: `tools/Vector Map Editor`
+- Source sample/demo path: `tools/Vector Map Editor/samples/arena_zone_map.editor.json`
+- Destination sample path: `samples/phase-12/1214/`
+- Assigned phase/id: `phase-12 / 1214`
+- Files moved/copied:
+  - Created `samples/phase-12/1214/sample-1214-vector-map-editor.json`
+  - Created `samples/phase-12/1214/index.html`
+  - Created `samples/phase-12/1214/assets/images/preview.svg`
+
+### Vector Asset Studio
+- Source tool: `tools/Vector Asset Studio`
+- Source sample/demo path: `tools/Vector Asset Studio/samples/sky_gradient_scene.svg`
+- Destination sample path: `samples/phase-12/1215/`
+- Assigned phase/id: `phase-12 / 1215`
+- Files moved/copied:
+  - Created `samples/phase-12/1215/sample-1215-vector-asset-studio.json`
+  - Copied `samples/phase-12/1215/assets/data/vector/sky_gradient_scene.svg`
+  - Created `samples/phase-12/1215/index.html`
+  - Created `samples/phase-12/1215/assets/images/preview.svg`
+
+- Source tool: `tools/Vector Asset Studio`
+- Source sample/demo path: `tools/Vector Asset Studio/samples/mountain_range_scene.svg`
+- Destination sample path: `samples/phase-12/1216/`
+- Assigned phase/id: `phase-12 / 1216`
+- Files moved/copied:
+  - Created `samples/phase-12/1216/sample-1216-vector-asset-studio.json`
+  - Copied `samples/phase-12/1216/assets/data/vector/mountain_range_scene.svg`
+  - Created `samples/phase-12/1216/index.html`
+  - Created `samples/phase-12/1216/assets/images/preview.svg`
+
+- Source tool: `tools/Vector Asset Studio`
+- Source sample/demo path: `tools/Vector Asset Studio/samples/mario_style_learning_backdrop.svg`
+- Destination sample path: `samples/phase-12/1217/`
+- Assigned phase/id: `phase-12 / 1217`
+- Files moved/copied:
+  - Created `samples/phase-12/1217/sample-1217-vector-asset-studio.json`
+  - Copied `samples/phase-12/1217/assets/data/vector/mario_style_learning_backdrop.svg`
+  - Created `samples/phase-12/1217/index.html`
+  - Created `samples/phase-12/1217/assets/images/preview.svg`
+
+### Parallax Scene Studio
+- Source tool: `tools/Parallax Scene Studio`
+- Source sample/demo path: `tools/Parallax Scene Studio/samples/parallax_sample.json`
+- Destination sample path: `samples/phase-12/1218/`
+- Assigned phase/id: `phase-12 / 1218`
+- Files moved/copied:
+  - Created `samples/phase-12/1218/sample-1218-parallax-editor.json`
+  - Copied referenced assets into `samples/phase-12/1218/assets/data/parallax/`
+  - Created `samples/phase-12/1218/index.html`
+  - Created `samples/phase-12/1218/assets/images/preview.svg`
+
+- Source tool: `tools/Parallax Scene Studio`
+- Source sample/demo path: `tools/Parallax Scene Studio/samples/tilemap_parallax_sample.json`
+- Destination sample path: `samples/phase-12/1219/`
+- Assigned phase/id: `phase-12 / 1219`
+- Files moved/copied:
+  - Created `samples/phase-12/1219/sample-1219-parallax-editor.json`
+  - Copied referenced assets into `samples/phase-12/1219/assets/data/parallax/`
+  - Created `samples/phase-12/1219/index.html`
+  - Created `samples/phase-12/1219/assets/images/preview.svg`
+
+- Source tool: `tools/Parallax Scene Studio`
+- Source sample/demo path: `tools/Parallax Scene Studio/samples/mario_style_learning_level_parallax.json`
+- Destination sample path: `samples/phase-12/1220/`
+- Assigned phase/id: `phase-12 / 1220`
+- Files moved/copied:
+  - Created `samples/phase-12/1220/sample-1220-parallax-editor.json`
+  - Copied referenced assets into `samples/phase-12/1220/assets/data/parallax/`
+  - Created `samples/phase-12/1220/index.html`
+  - Created `samples/phase-12/1220/assets/images/preview.svg`
+
+### Tilemap Studio Audit Result
+- Source tool: `tools/Tilemap Studio`
+- Discovery result: no tool-local sample/demo `samples/` folder and no sample dropdown/select entries were found.
+- Migration action: none required for tool-local sample payloads.
+
+## Tool-Local Sample UI Removal
+- `tools/Vector Map Editor/index.html`
+  - Removed sample dropdown/select and load button controls.
+- `tools/Vector Asset Studio/index.html`
+  - Removed sample dropdown/select and refresh/load controls.
+- `tools/Parallax Scene Studio/index.html`
+  - Removed sample dropdown/select and load controls.
+- `tools/Vector Asset Studio/main.js`
+  - Added null-safe guards so removed controls do not break runtime.
+- `tools/Parallax Scene Studio/main.js`
+  - Added null-safe guards so removed controls do not break runtime.
+- `tools/Tilemap Studio`
+  - No sample dropdown/select existed, retained unchanged.
+
+## Samples Hub Update
+- Updated samples hub data source:
+  - `samples/metadata/samples.index.metadata.json`
+- Added migrated sample rows for IDs:
+  - `1212`, `1213`, `1214`, `1215`, `1216`, `1217`, `1218`, `1219`, `1220`
+- `samples/index.html` intro copy updated to reflect tool preset samples in hub listing.
+
+## Launch Test Result
+
+### Added/Updated Tests
+- Added `tests/tools/ToolLocalSampleMigration.test.mjs`
+  - Verifies migrated sample IDs are indexed in metadata and files exist.
+  - Verifies each migrated sample index launches correct tool route with `sampleId` and `samplePresetPath`.
+  - Verifies old tool-local sample dropdown/select controls are removed from processed tool HTML.
+  - Verifies query preset loading hooks remain in processed tool runtime files.
+
+- Updated `tests/run-tests.mjs`
+  - Added explicit run hook for `ToolLocalSampleMigration` test.
+
+### Executed
+- `node --input-type=module -e "import('./tests/tools/ToolLocalSampleMigration.test.mjs').then((m)=>m.run())"` -> PASS
+- `node --input-type=module -e "import('./tests/tools/ToolEntryLaunchContract.test.mjs').then((m)=>m.run())"` -> PASS
+
+### Note
+- `SamplesProgramCombinedPass` currently reports pre-existing metadata parity mismatch (`samples.curriculum.validation.json progression.totalSamples`) that is outside this PR’s migration-only scope.
+
+## Roadmap Status
+- `docs/dev/roadmaps/MASTER_ROADMAP_ENGINE.md` was not updated because no explicit Level 10.3 status markers were present for this migration slice.
+
+## Tool-Local Sample UI Removed/Retained Summary
+- Removed:
+  - Vector Map Editor sample select/load controls
+  - Vector Asset Studio sample select/refresh/load controls
+  - Parallax Scene Studio sample select/load controls
+- Retained:
+  - Query-based preset loading (`sampleId`, `samplePresetPath`) for explicit sample/workspace input
+  - Tilemap Studio explicit input flow (no local sample dropdown existed)

docs/operations/dev/codex_commands.md

@@ -2,31 +2,38 @@ MODEL: GPT-5.3-codex
 REASONING: high
 
 TASK:
-Apply BUILD_PR_LEVEL_10_2F_VECTOR_ASSET_PALETTE_PAINT_BINDING_FIX.
+Apply BUILD_PR_LEVEL_10_3_MIGRATE_TOOL_LOCAL_SAMPLES_TO_SAMPLES.
 
 STEPS:
-1. Read docs/pr/PLAN_PR_LEVEL_10_2F_VECTOR_ASSET_PALETTE_PAINT_BINDING_FIX.md.
-2. Read docs/pr/BUILD_PR_LEVEL_10_2F_VECTOR_ASSET_PALETTE_PAINT_BINDING_FIX.md.
-3. Inspect Gravity Well game manifest:
-   - tools["palette-browser"].palette
-   - tools["vector-asset-studio"].vectors
-4. Inspect Workspace Manager to Vector Asset Studio data passing.
-5. Inspect Vector Asset Studio palette/paint/stroke selection initialization.
-6. Fix binding so shared palette loads into Vector Asset Studio selection state.
-7. Ensure stroke-enabled vectors select a valid stroke swatch.
-8. Add/adjust defaults in Gravity Well manifest only if style data is missing.
-9. Add/update test coverage so palette loaded + vector asset present but palette/stroke selected false fails.
-10. Write docs/dev/reports/level_10_2f_vector_asset_palette_paint_binding_report.md.
-11. Update docs/dev/roadmaps/MASTER_ROADMAP_ENGINE.md status only if needed:
+1. Read docs/pr/PLAN_PR_LEVEL_10_3_MIGRATE_TOOL_LOCAL_SAMPLES_TO_SAMPLES.md.
+2. Read docs/pr/BUILD_PR_LEVEL_10_3_MIGRATE_TOOL_LOCAL_SAMPLES_TO_SAMPLES.md.
+3. Inspect these tool folders for local samples/demo entries:
+   - tools/Vector Map Editor
+   - tools/Vector Asset Studio
+   - tools/Parallax Scene Studio
+   - tools/Tilemap Studio
+4. Identify each tool-local sample/demo payload.
+5. Move/copy each sample into the correct `samples/phase-*` folder using next available sample IDs.
+6. Preserve sample behavior and required data.
+7. Update `samples/index.html`.
+8. Remove tool-local sample dropdown/select entries from the processed tools after migrated samples exist.
+9. Ensure tools still accept explicit manifest/input data.
+10. Add/update tests for:
+    - migrated sample presence in samples/index.html
+    - migrated sample launch
+    - removal of tool-local sample dropdown/select entries
+11. Write docs/dev/reports/level_10_3_tool_local_sample_migration_report.md.
+12. Update docs/dev/roadmaps/MASTER_ROADMAP_ENGINE.md status only if needed:
     - [ ] -> [.]
     - [.] -> [x]
     - no prose rewrite/delete
-12. Do not add validators.
 13. Do not modify start_of_day.
-14. Create Codex delta ZIP:
-    tmp/BUILD_PR_LEVEL_10_2F_VECTOR_ASSET_PALETTE_PAINT_BINDING_FIX_delta.zip
+14. Do not add validators.
+15. Create Codex delta ZIP:
+    tmp/BUILD_PR_LEVEL_10_3_MIGRATE_TOOL_LOCAL_SAMPLES_TO_SAMPLES_delta.zip
 
 ACCEPTANCE:
-- Gravity Well vector palette/stroke binding works
-- test covers selection state
+- all discovered tool-local samples from listed tools are migrated
+- samples/index.html updated
+- local sample dropdown/selects removed
 - delta ZIP exists

docs/operations/dev/commit_comment.txt

@@ -1,9 +1,11 @@
-BUILD_PR_LEVEL_10_2F_VECTOR_ASSET_PALETTE_PAINT_BINDING_FIX
+BUILD_PR_LEVEL_10_3_MIGRATE_TOOL_LOCAL_SAMPLES_TO_SAMPLES
 
-- Fixed Vector Asset Studio palette/paint/stroke binding from game manifest palette
-- Added Gravity Well vector selection regression coverage
-- Ensured stroke-enabled vectors select a valid palette swatch
+- Migrated tool-local samples into /samples
+- Updated samples index
+- Removed local sample dropdown/select entries from processed tools
+- Preserved tool explicit-input behavior
 
 PR Details:
+- Processes Vector Map Editor, Vector Asset Studio, Parallax Scene Studio, and Tilemap Studio
 - No validators
 - No start_of_day changes

docs/pr/BUILD_PR_LEVEL_10_3_MIGRATE_TOOL_LOCAL_SAMPLES_TO_SAMPLES.md

@@ -0,0 +1,76 @@
+# BUILD_PR_LEVEL_10_3_MIGRATE_TOOL_LOCAL_SAMPLES_TO_SAMPLES
+
+## Objective
+Make `/samples` the only home for samples.
+
+## Tools To Process
+1. `tools/Vector Map Editor`
+2. `tools/Vector Asset Studio`
+3. `tools/Parallax Scene Studio`
+4. `tools/Tilemap Studio`
+
+The user says each has three samples. Codex must discover the actual local sample/demo files.
+
+## Placement Rules
+Pick the correct `/samples/phase-*` location based on existing repo organization.
+
+Rules:
+- Preserve current sample phase numbering conventions.
+- Do not reuse existing sample IDs.
+- Continue the next available sample IDs in the correct phase.
+- Keep sample folder naming consistent:
+  - `samples/phase-XX/####/`
+- Each migrated sample should have:
+  - `index.html`
+  - sample tool payload file(s), if needed
+  - any manifest/data needed by that sample
+- Update `samples/index.html`.
+
+## Suggested Classification
+Use the current sample phase taxonomy if already present:
+- Vector Map Editor samples → vector/map/tool integration phase.
+- Vector Asset Studio samples → vector asset/tool integration phase.
+- Parallax Scene Studio samples → parallax/rendering/tool integration phase.
+- Tilemap Studio samples → tilemap/tool integration phase.
+
+If phase placement is ambiguous, use the closest existing phase containing related tool samples and document the decision.
+
+## Tool Cleanup Rule
+After migrated samples exist and launch:
+- remove those sample options from tool-local dropdown/select UI
+- tools should no longer show internal sample choices
+- tools should accept explicit manifest/tool input only
+
+Do not remove generic "Open" or "Load" functionality for real workspace/game data.
+
+## Required Audit
+Create:
+
+```text
+docs/dev/reports/level_10_3_tool_local_sample_migration_report.md
+```
+
+Report:
+- source tool
+- source sample/demo path
+- destination sample path
+- assigned phase/id
+- files moved/copied
+- tool-local sample UI removed/retained
+- launch test result
+
+## Required Tests
+Update or add tests to verify:
+- migrated samples appear in `samples/index.html`
+- migrated samples launch from `/samples`
+- old tool-local sample dropdown/select entries are gone
+- tools still open with explicit input
+
+## Acceptance
+- Tool-local samples from the four tools are migrated to `/samples`.
+- `samples/index.html` includes the migrated samples.
+- Migrated samples launch.
+- Tool-local sample dropdown/select entries are removed.
+- No duplicate sample IDs.
+- No `start_of_day` changes.
+- Delta ZIP returned.

docs/pr/PLAN_PR_LEVEL_10_3_MIGRATE_TOOL_LOCAL_SAMPLES_TO_SAMPLES.md

@@ -0,0 +1,27 @@
+# PLAN_PR_LEVEL_10_3_MIGRATE_TOOL_LOCAL_SAMPLES_TO_SAMPLES
+
+## Purpose
+Move tool-local sample/demo payloads out of tools and into `/samples`, preserving sample behavior while enforcing the rule that tools do not own samples.
+
+## User Request
+Move the three samples from each tool into `/samples`:
+- Vector Map Editor
+- Vector Asset Studio
+- Parallax Scene Studio
+- Tilemap Studio
+
+Vector Asset Studio was listed twice by the user; treat it once unless the repo contains two distinct sample groups.
+
+## Scope
+- Find tool-local samples/demos in the listed tools.
+- Move each to the correct `/samples/phase-*` location.
+- Use existing sample naming and directory conventions.
+- Update `samples/index.html`.
+- Remove tool-local sample dropdown/select entries only after sample parity exists.
+- Add/update tests so samples still launch from `/samples`.
+
+## Non-Goals
+- No broad tool UX rewrite beyond removing/migrating sample entry points.
+- No game manifest changes unless a migrated sample requires manifest input.
+- No validators.
+- No `start_of_day` changes.

samples/index.html

@@ -23,6 +23,7 @@ <h1>Samples Hub</h1>
       <p>
         Browse phase-based sample collections that demonstrate engine systems and gameplay patterns.
         Start from the phase links below and open individual sample entries from each phase page.
+        Tool preset launch samples are listed alongside gameplay samples in this hub.
       </p>
     </section>