Level 09.03 — standardize asset taxonomy to type-first buckets and reserve nested platform grouping only where needed & Level 09.04 — simplify asset structure by removing redundant data/platform containers

Author: DavidQ

docs/dev/CODEX_COMMANDS.md

@@ -1,6 +1,30 @@
-MODEL: GPT-5.4
+MODEL: GPT-5.4
 REASONING: high
 
-COMMAND GOAL:
-Create BUILD_PR_LEVEL_09_02_ASSET_OWNERSHIP_NORMALIZATION as a docs-first, repo-structured bundle
-that corrects owner-specific asset placement across games, samples, and tools.
+GOAL:
+Simplify asset structure by removing redundant container layers.
+
+RULES:
+- eliminate data/ if it is just a wrapper
+- eliminate platform/ as default container
+- keep only type-first folders under assets/
+- allow nested grouping only when needed
+
+TARGET STRUCTURE:
+assets/
+  palettes/
+  sprites/
+  tilemaps/
+
+OPTIONAL:
+assets/sprites/platform/
+assets/tilemaps/platform/
+
+CONSTRAINTS:
+- preserve files
+- update references
+- do not touch runtime code
+- one PR scope only
+
+OUTPUT:
+ZIP to <project folder>/tmp/

docs/dev/COMMIT_COMMENT.txt

@@ -1 +1 @@
-build(assets): normalize owner-specific platform asset placement under owner assets roots
+Level 09.04 — simplify asset structure by removing redundant data/platform containers

docs/dev/NEXT_COMMAND.txt

@@ -1 +1,3 @@
-PLAN_PR_LEVEL_11_2_RECONCILIATION_LAYER_FOUNDATION
+# Validate BUILD_PR_LEVEL_09_03_ASSET_BUCKET_TAXONOMY_STANDARD
+rg -n ""assets/platform/"" games samples tools src tests --glob '!start_of_day/**'
+node tests/tools/VectorAssetSystem.test.mjs

docs/dev/reports/change_summary.txt

@@ -1,34 +1 @@
-BUILD_PR_LEVEL_09_02_ASSET_OWNERSHIP_NORMALIZATION
-
-Moved owner-specific asset payloads
-games/Asteroids/platform/assets/palettes/asteroids-hud.palette.json => games/Asteroids/assets/platform/palettes/asteroids-hud.palette.json
-games/Asteroids/platform/assets/parallax/asteroids-overlay.parallax.json => games/Asteroids/assets/platform/parallax/asteroids-overlay.parallax.json
-games/Asteroids/platform/assets/parallax/asteroids-title.parallax.json => games/Asteroids/assets/platform/parallax/asteroids-title.parallax.json
-games/Asteroids/platform/assets/sprites/asteroids-demo.sprite.json => games/Asteroids/assets/platform/sprites/asteroids-demo.sprite.json
-games/Asteroids/platform/assets/tilemaps/asteroids-stage.tilemap.json => games/Asteroids/assets/platform/tilemaps/asteroids-stage.tilemap.json
-games/Asteroids/platform/assets/tilesets/asteroids-ui.tileset.json => games/Asteroids/assets/platform/tilesets/asteroids-ui.tileset.json
-games/Asteroids/platform/assets/vectors/asteroids-asteroid-large.vector.json => games/Asteroids/assets/platform/vectors/asteroids-asteroid-large.vector.json
-games/Asteroids/platform/assets/vectors/asteroids-asteroid-medium.vector.json => games/Asteroids/assets/platform/vectors/asteroids-asteroid-medium.vector.json
-games/Asteroids/platform/assets/vectors/asteroids-asteroid-small.vector.json => games/Asteroids/assets/platform/vectors/asteroids-asteroid-small.vector.json
-games/Asteroids/platform/assets/vectors/asteroids-ship.vector.json => games/Asteroids/assets/platform/vectors/asteroids-ship.vector.json
-games/Asteroids/platform/assets/vectors/asteroids-title.vector.json => games/Asteroids/assets/platform/vectors/asteroids-title.vector.json
-
-Updated references in active surfaces
-- tools/Asset Browser/main.js
-- tools/shared/asteroidsPlatformDemo.js
-- tools/shared/vectorAssetSystem.js
-- tools/templates/starter-project-template/README.md
-- tools/templates/starter-project-template/config/starter.project.json
-- tests/tools/VectorAssetSystem.test.mjs
-- docs/specs/asset_usage_contract.md
-
-Classification result
-- Game-owned moved: Asteroids platform asset payloads
-- Sample-owned moved: none found
-- Tool-owned moved: none found
-- Truly shared assets requiring retention outside owner roots: none found in scanned owner scopes
-
-Out-of-scope preserved
-- no platform/runtime code moved
-- no engine abstractions moved
-- no shared infrastructure code moved
+Removes redundant asset container layers (data/platform) and standardizes to type-first structure.

docs/dev/reports/file_tree.txt

@@ -1,23 +1,10 @@
-Asset Ownership Normalization - File Tree (Changed)
-
-games/Asteroids/assets/platform/
-  palettes/asteroids-hud.palette.json
-  parallax/asteroids-overlay.parallax.json
-  parallax/asteroids-title.parallax.json
-  sprites/asteroids-demo.sprite.json
-  tilemaps/asteroids-stage.tilemap.json
-  tilesets/asteroids-ui.tileset.json
-  vectors/asteroids-asteroid-large.vector.json
-  vectors/asteroids-asteroid-medium.vector.json
-  vectors/asteroids-asteroid-small.vector.json
-  vectors/asteroids-ship.vector.json
-  vectors/asteroids-title.vector.json
-
-Reference updates
-- tools/Asset Browser/main.js
-- tools/shared/asteroidsPlatformDemo.js
-- tools/shared/vectorAssetSystem.js
-- tools/templates/starter-project-template/README.md
-- tools/templates/starter-project-template/config/starter.project.json
-- tests/tools/VectorAssetSystem.test.mjs
-- docs/specs/asset_usage_contract.md
+docs/
+  dev/
+    codex_commands.md
+    commit_comment.txt
+    reports/
+      change_summary.txt
+      file_tree.txt
+      validation_checklist.txt
+  pr/
+    BUILD_PR_LEVEL_09_04_ASSET_STRUCTURE_SIMPLIFICATION.md

docs/dev/reports/validation_checklist.txt

@@ -1,43 +1,5 @@
-BUILD_PR_LEVEL_09_02_ASSET_OWNERSHIP_NORMALIZATION - Validation Checklist
-
-Scope
-- [x] one PR purpose only
-- [x] no engine modifications
-- [x] no launcher/bootstrap changes
-- [x] no config migration as a separate lane
-- [x] no start_of_day modifications
-
-Required work
-1. scan repo for owner-specific assets outside owner assets/
-- [x] scanned games/, samples/, tools/ for */platform/assets payloads
-
-2. classify by owner
-- [x] game-owned: Asteroids payloads found
-- [x] sample-owned: none found
-- [x] tool-owned: none found
-- [x] truly shared: none found in scanned owner scopes
-
-3. move only asset payloads
-- [x] 11 asset payload files moved from games/Asteroids/platform/assets/* to games/Asteroids/assets/platform/*
-
-4. update references
-- [x] updated active path references to games/Asteroids/assets/platform/
-
-5. remove old asset locations when safe
-- [x] moved payload files out of old location
-- [x] no owner payload files remain under games/Asteroids/platform/assets
-
-6. preserve exact assets / avoid code moves
-- [x] payload files preserved (move only)
-- [x] no runtime/platform code moved
-
-Command evidence
-- rg scan for old active paths (tools/tests/docs/specs): no stale games/Asteroids/platform/assets refs remain
-- node --check tools/Asset Browser/main.js : PASS
-- node --check tools/shared/asteroidsPlatformDemo.js : PASS
-- node --check tools/shared/vectorAssetSystem.js : PASS
-- node tests/runtime/LaunchSmokeAllEntries.test.mjs : PASS
-- tests/tools/VectorAssetSystem.test.mjs : blocked by existing baseline env/module resolution issue (C:/src/engine/assets/AssetRegistry.js)
-
-Result
-- PASS (with noted baseline test-environment blocker unrelated to this move)
+Validation:
+- no data/platform nesting remains
+- top-level assets folders are type-only
+- plural naming enforced
+- references updated

docs/pr/BUILD_PR_LEVEL_09_03_ASSET_BUCKET_TAXONOMY_STANDARD.md

@@ -0,0 +1,143 @@
+# BUILD_PR — LEVEL 09.03 ASSET BUCKET TAXONOMY STANDARD
+
+## Purpose
+Standardize asset folder taxonomy across games, samples, and tools so ownership is clear and asset
+types are easy to find, package, and evolve.
+
+## Decision
+Use **type-first buckets under each owner `assets/` folder**.
+
+### Recommended pattern
+- `games/<GameName>/assets/`
+- `samples/<SampleName>/assets/`
+- `tools/<ToolName>/assets/`
+
+Inside each owner `assets/`, use the following standard buckets:
+
+- `images/`
+- `sprites/`
+- `tiles/`
+- `backgrounds/`
+- `icons/`
+- `audio/`
+- `music/`
+- `midi/`
+- `fonts/`
+- `data/`
+- `shaders/`
+- `ui/`
+- `video/`
+
+## Key decision on `platform/`
+**Do not keep `platform/` as a default asset bucket.**
+
+Reason:
+- `platform` describes theme/source/context, not type
+- it becomes a junk-drawer bucket
+- it overlaps with true asset types like images, audio, icons, fonts, and data
+- it will age poorly once MIDI/player/editor work expands the media surface
+
+## What to do instead
+Move contents of any existing `platform/assets` into the correct type buckets under the owning scope.
+
+Examples:
+- platform PNG/SVG art -> `assets/images/` or `assets/icons/`
+- platform sprite sheets -> `assets/sprites/`
+- platform tile maps / payload JSON -> `assets/data/` or `assets/tiles/`
+- platform audio FX -> `assets/audio/`
+- platform music tracks -> `assets/music/`
+- future MIDI songs / patterns -> `assets/midi/`
+- platform fonts -> `assets/fonts/`
+
+## Allowed exception
+A theme/domain subfolder may exist **inside** a type bucket when needed.
+
+Examples:
+- `assets/images/platform/`
+- `assets/audio/platform/`
+- `assets/midi/platform/`
+
+This preserves theme grouping without losing type clarity.
+
+## Why this is the best long-term choice
+This approach gives:
+- clear ownership
+- clear type grouping
+- easy packaging/export
+- easy tooling
+- easy future MIDI/editor support
+- less ambiguity than `platform/assets`
+
+## Naming guidance
+Use plural, lowercase bucket names:
+- good: `images`, `icons`, `fonts`, `audio`
+- avoid: `img`, `snd`, `fontFiles`, `platformAssets`
+
+## Classification rules
+### `images/`
+Raster and general image payloads not better classified elsewhere.
+
+### `sprites/`
+Sprite sheets, frame atlases, sprite-specific PNG/JSON pairs.
+
+### `tiles/`
+Tile sheets, tile atlases, tile metadata tied to tile rendering.
+
+### `backgrounds/`
+Parallax layers, static scene backdrops, panorama payloads.
+
+### `icons/`
+Small symbolic UI/app/tool icons.
+
+### `audio/`
+Short sound effects and non-musical audio cues.
+
+### `music/`
+Rendered music tracks (mp3, ogg, wav, etc).
+
+### `midi/`
+MIDI files, patterns, sequences, and future editor/player assets.
+
+### `fonts/`
+Font payloads and font metadata.
+
+### `data/`
+JSON, TMX-like payloads, level data, tuning payloads, manifests.
+
+### `shaders/`
+Shader source/assets if present.
+
+### `ui/`
+UI skin assets not already better classified as icons/images/fonts.
+
+### `video/`
+Video payloads.
+
+## Scope
+Docs-first standard only.
+Apply to:
+- games
+- samples
+- tools
+
+## Migration rule
+1. owner-specific assets stay under the owner
+2. remove default `platform/` asset bucket
+3. preserve exact payloads
+4. update references
+5. if theme grouping is needed, nest `platform/` under the correct type bucket
+6. do not move runtime/platform code
+
+## Acceptance criteria
+1. owner asset folders use standard type buckets
+2. `platform/` is not used as a top-level default asset bucket
+3. assets are classified by type first
+4. references are updated
+5. future MIDI assets have a defined home: `assets/midi/`
+6. no runtime/platform code moved
+
+## Out of scope
+- engine/runtime refactors
+- media conversion
+- audio pipeline redesign
+- MIDI engine/editor implementation

docs/pr/BUILD_PR_LEVEL_09_04_ASSET_STRUCTURE_SIMPLIFICATION.md

@@ -0,0 +1,68 @@
+# BUILD_PR — LEVEL 09.04 ASSET STRUCTURE SIMPLIFICATION
+
+## Problem
+Current structure introduces unnecessary nesting:
+
+- data/platform/palettes
+- data/platform/sprites
+- data/platform/tilemap
+
+Both `data/` and `platform/` are acting as containers, which creates redundancy.
+
+## Decision (Simplify)
+Use **type-first buckets directly under assets/** with NO extra wrapper layers.
+
+### Final Structure
+assets/
+  palettes/
+  sprites/
+  tilemaps/
+
+Optional grouping ONLY when needed:
+assets/sprites/platform/
+assets/tilemaps/platform/
+
+## Rules
+1. REMOVE `data/` when it only acts as a container
+2. REMOVE `platform/` as a default container
+3. KEEP only TYPE folders at the top level
+4. USE nested grouping only when necessary
+
+## Examples
+
+### ❌ Over-engineered
+assets/data/platform/palettes/
+assets/data/platform/sprites/
+assets/data/platform/tilemap/
+
+### ✅ Correct
+assets/palettes/
+assets/sprites/
+assets/tilemaps/
+
+### ✅ With grouping (only if needed)
+assets/sprites/platform/
+assets/tilemaps/platform/
+
+## Naming adjustments
+- tilemap → tilemaps (plural standard)
+- palette → palettes
+
+## Why this is better
+- eliminates double-container problem
+- faster navigation
+- cleaner mental model
+- consistent with tooling expectations
+- avoids future refactor when MIDI/tools expand
+
+## Scope
+Applies to:
+- games
+- samples
+- tools
+
+## Acceptance Criteria
+- no `data/platform` chains
+- top-level folders are TYPE buckets only
+- plural naming enforced
+- optional grouping only when justified

docs/specs/asset_usage_contract.md

@@ -1,4 +1,4 @@
-# Asset Usage Contract
+# Asset Usage Contract
 
 ## Purpose
 Define the shared asset and shared palette handoff contract for first-class tools under `tools/`.
@@ -58,7 +58,7 @@ Normalized shape:
 {
   "assetId": "asset-vector-player",
   "assetType": "vector",
-  "sourcePath": "../../games/Asteroids/assets/platform/vectors/asteroids-ship.vector.json",
+  "sourcePath": "../../games/Asteroids/assets/vectors/asteroids-ship.vector.json",
   "displayName": "Asteroids Ship Vector",
   "tags": ["Vector Assets"],
   "metadata": {