PR 8.10: Sample multi-file tool payload alignment

- Converted samples to one-file-per-tool model
- Removed tools arrays from sample files
- Aligned sample payloads with workspace tool payload structure
- Standardized naming convention

Author: DavidQ

docs/dev/codex_commands.md

@@ -2,12 +2,25 @@ MODEL: GPT-5.3-codex
 REASONING: medium
 
 TASK:
-- Update workspace.schema.json:
-  - Add phase and level fields
-  - Add conditional rules:
-    - sample → phase required, level forbidden
-    - game → level required, phase forbidden
-- Validate manifest against schema
-- Do NOT modify runtime
-- Do NOT add validators
-- Do NOT modify start_of_day
+Refactor samples to multi-file tool payload model.
+
+STEPS:
+1. Remove any "tools" arrays inside sample JSON files.
+2. For each tool used in a sample:
+   - Create file: sample.<id>.<tool>.json
+3. Ensure each file:
+   - references tool schema via $schema
+   - matches EXACT structure of workspace manifest tool payload
+4. Remove wrapper fields:
+   - documentKind
+   - id
+   - type
+5. Keep palette as separate file if exists.
+6. Do NOT modify runtime.
+7. Do NOT add validators.
+8. Do NOT modify start_of_day.
+
+ACCEPTANCE:
+- Each sample tool is its own file
+- File format matches workspace tool payload
+- No arrays or wrappers remain

docs/dev/commit_comment.txt

@@ -1,4 +1,6 @@
-PR 8.8: Entity progression dimension (phase vs level)
+PR 8.10: Sample multi-file tool payload alignment
 
-- Added phase and level fields
-- Enforced type-based conditional requirements
+- Converted samples to one-file-per-tool model
+- Removed tools arrays from sample files
+- Aligned sample payloads with workspace tool payload structure
+- Standardized naming convention

docs/pr/PR_8.10_SAMPLE_MULTI_FILE_TOOL_PAYLOAD_ALIGNMENT.md

@@ -0,0 +1,96 @@
+# PR 8.10 — Sample Multi-File Tool Payload Alignment
+
+## Purpose
+Clarify that "multiple tools" in samples means multiple files, not arrays inside a single file.
+
+Each file represents a single tool payload and matches the exact format used in workspace/game manifest tool entries.
+
+## Key Correction
+
+### ❌ WRONG (array inside one file)
+```json
+{
+  "tools": [ ... ]
+}
+```
+
+### ✅ CORRECT (multiple files)
+```
+sample.0305.vector-map-editor.json
+sample.0305.vector-asset-studio.json
+```
+
+Each file:
+- references ONE tool schema
+- contains ONE tool payload
+- is identical in shape to what goes inside:
+  workspace.manifest.json → games[].tools[]
+
+## File Naming Standard
+
+```
+sample.<id>.<tool>.json
+```
+
+Examples:
+- sample.0305.vector-map-editor.json
+- sample.0305.palette-editor.json
+- sample.0101.sprite-editor.json
+
+## Payload Rule
+
+Each sample tool file MUST match EXACTLY the structure used in game/workspace manifests.
+
+Example:
+
+```json
+{
+  "$schema": "../../../tools/vector-map-editor/tool.schema.json",
+  "tool": "vector-map-editor",
+  "config": {}
+}
+```
+
+This is identical to:
+
+```json
+{
+  "tools": [
+    {
+      "tool": "vector-map-editor",
+      "config": {}
+    }
+  ]
+}
+```
+
+## Rules
+
+- One file = one tool
+- No arrays inside sample files
+- File = tool payload
+- Same structure as workspace manifest tool entry
+- $schema must point to tool schema
+- Naming must be deterministic
+- No wrapper objects (no documentKind, no sample envelope)
+
+## Palette
+
+If needed:
+```
+sample.palette.json
+```
+
+Referenced by convention, not embedded.
+
+## Non-Goals
+
+- No runtime logic
+- No validators
+- No workspace schema changes
+
+## Acceptance
+
+- No sample files contain tools arrays
+- All sample tool files match workspace tool payload shape
+- Naming convention enforced

docs/pr/sample_file_naming_rules.md

@@ -0,0 +1,15 @@
+# Sample File Naming Rules
+
+## Format
+sample.<id>.<tool>.json
+
+## Constraints
+- id matches sample folder
+- tool matches tool name exactly
+- lowercase kebab-case
+- no spaces
+
+## Examples
+sample.0101.palette-editor.json
+sample.0305.vector-map-editor.json
+sample.0305.vector-asset-studio.json

…1/sample-0201-3d-camera-path-editor.json …1/sample.0201.3d-camera-path-editor.jsonsamples/phase-02/0201/sample-0201-3d-camera-path-editor.json renamed to samples/phase-02/0201/sample.0201.3d-camera-path-editor.json samples/phase-02/0201/sample-0201-3d-camera-path-editor.json renamed to samples/phase-02/0201/sample.0201.3d-camera-path-editor.json

@@ -1,13 +1,8 @@
 {
-  "$schema": "../../../tools/schemas/sample.tool-payload.schema.json",
-  "sampleId": "0201",
-  "phase": "02",
-  "title": "Camera Follow",
-  "description": "Shared sample preset for Sample 0201 and 3D Camera Path Editor preload.",
-  "toolHints": [
-    "3d-camera-path-editor"
-  ],
-  "payload": {
+  "$schema": "../../../tools/schemas/tools/3d-camera-path-editor.schema.json",
+  "tool": "3d-camera-path-editor",
+  "version": "1",
+  "config": {
     "cameraPath": {
       "schema": "tools.3d-camera-path.path/1",
       "pathId": "sample-0201-follow-orbit",
@@ -53,16 +48,5 @@
         }
       ]
     }
-  },
-  "runtime": {
-    "sampleEntryPoint": "/samples/phase-02/0201/index.html"
-  },
-  "toolState": {
-    "preferredToolId": "3d-camera-path-editor"
-  },
-  "provenance": {
-    "path": "/samples/phase-02/0201/sample-0201-3d-camera-path-editor.json",
-    "createdAt": "2026-04-24T00:00:00.000Z",
-    "version": 1
   }
 }

…2/sample-0202-3d-camera-path-editor.json …2/sample.0202.3d-camera-path-editor.jsonsamples/phase-02/0202/sample-0202-3d-camera-path-editor.json renamed to samples/phase-02/0202/sample.0202.3d-camera-path-editor.json samples/phase-02/0202/sample-0202-3d-camera-path-editor.json renamed to samples/phase-02/0202/sample.0202.3d-camera-path-editor.json

@@ -1,13 +1,8 @@
 {
-  "$schema": "../../../tools/schemas/sample.tool-payload.schema.json",
-  "sampleId": "0202",
-  "phase": "02",
-  "title": "Camera Bounds",
-  "description": "Shared sample preset for Sample 0202 and 3D Camera Path Editor preload.",
-  "toolHints": [
-    "3d-camera-path-editor"
-  ],
-  "payload": {
+  "$schema": "../../../tools/schemas/tools/3d-camera-path-editor.schema.json",
+  "tool": "3d-camera-path-editor",
+  "version": "1",
+  "config": {
     "cameraPath": {
       "schema": "tools.3d-camera-path.path/1",
       "pathId": "sample-0202-camera-bounds-tour",
@@ -53,16 +48,5 @@
         }
       ]
     }
-  },
-  "runtime": {
-    "sampleEntryPoint": "/samples/phase-02/0202/index.html"
-  },
-  "toolState": {
-    "preferredToolId": "3d-camera-path-editor"
-  },
-  "provenance": {
-    "path": "/samples/phase-02/0202/sample-0202-3d-camera-path-editor.json",
-    "createdAt": "2026-04-24T00:00:00.000Z",
-    "version": 1
   }
 }

samples/phase-02/0204/sample-0204-asset-browser.json

@@ -1,13 +1,8 @@
 {
-  "$schema": "../../../tools/schemas/sample.tool-payload.schema.json",
-  "sampleId": "0204",
-  "phase": "02",
-  "title": "Asset Registry",
-  "description": "Shared sample preset for Sample 0204 and 3D Asset Viewer preload.",
-  "toolHints": [
-    "3d-asset-viewer"
-  ],
-  "payload": {
+  "$schema": "../../../tools/schemas/tools/3d-asset-viewer.schema.json",
+  "tool": "3d-asset-viewer",
+  "version": "1",
+  "config": {
     "asset3d": {
       "schema": "tools.3d-asset-viewer.asset/1",
       "assetId": "sample-0204-registry-node",
@@ -43,16 +38,5 @@
         "sourceToolId": "asset-browser"
       }
     }
-  },
-  "runtime": {
-    "sampleEntryPoint": "/samples/phase-02/0204/index.html"
-  },
-  "toolState": {
-    "preferredToolId": "3d-asset-viewer"
-  },
-  "provenance": {
-    "path": "/samples/phase-02/0204/sample-0204-3d-asset-viewer.json",
-    "createdAt": "2026-04-24T00:00:00.000Z",
-    "version": 1
   }
 }

…02/0204/sample-0204-3d-asset-viewer.json …02/0204/sample.0204.3d-asset-viewer.jsonsamples/phase-02/0204/sample-0204-3d-asset-viewer.json renamed to samples/phase-02/0204/sample.0204.3d-asset-viewer.json samples/phase-02/0204/sample-0204-3d-asset-viewer.json renamed to samples/phase-02/0204/sample.0204.3d-asset-viewer.json

@@ -0,0 +1,15 @@
+{
+  "$schema": "../../../tools/schemas/tools/asset-browser.schema.json",
+  "tool": "asset-browser",
+  "version": "1",
+  "config": {
+    "assetBrowserPreset": {
+      "selectedCategory": "Vector Assets",
+      "selectedAssetId": "asset-vector-player",
+      "search": "vector",
+      "importCategory": "Vector Assets",
+      "importDestination": "games/<project>/assets/vectors/",
+      "importName": "sample-0204-import.vector.json"
+    }
+  }
+}

samples/phase-02/0204/sample.0204.asset-browser.json

@@ -1,13 +1,8 @@
 {
-  "$schema": "../../../tools/schemas/sample.tool-payload.schema.json",
-  "sampleId": "0205",
-  "phase": "02",
-  "title": "Save Load State",
-  "description": "Shared sample preset for Sample 0205 and State Inspector preload.",
-  "toolHints": [
-    "state-inspector"
-  ],
-  "payload": {
+  "$schema": "../../../tools/schemas/tools/state-inspector.schema.json",
+  "tool": "state-inspector",
+  "version": "1",
+  "config": {
     "snapshot": {
       "schema": "tools.debug-state-inspector.snapshot/1",
       "capturedAt": "2026-04-24T00:00:00.000Z",
@@ -50,16 +45,5 @@
       },
       "notes": "Sample snapshot payload for State Inspector launch validation."
     }
-  },
-  "runtime": {
-    "sampleEntryPoint": "/samples/phase-02/0205/index.html"
-  },
-  "toolState": {
-    "preferredToolId": "state-inspector"
-  },
-  "provenance": {
-    "path": "/samples/phase-02/0205/sample-0205-state-inspector.json",
-    "createdAt": "2026-04-24T00:00:00.000Z",
-    "version": 1
   }
 }