Adds template-based game creation scripting with tool scaffolding and enforces updated script location and commit format.

BUILD_PR_LEVEL_09_19_TEMPLATE_GAME_CREATION_SCRIPTING

Author: DavidQ

docs/dev/CODEX_COMMANDS.md

@@ -1,74 +1,13 @@
-# MODEL
-GPT-5.4
 
-# REASONING
-high
-
-# COMMAND
-Create BUILD_PR_LEVEL_09_18_CODEX_PLAN_SWITCH_AND_API_KEY_SCRIPTING as a docs-first, surgical PR for `HTML-JavaScript-Gaming`.
-
-## Mission
-Add a small PowerShell-based repo automation slice that:
-- switches between Pay-as-you-go and Codex plan modes
-- inputs/updates API key configuration
-- validates the configured API key state safely
-
-## Required scope
-- add PowerShell scripts for plan switching
-- add PowerShell scripts for API key input/update
-- add PowerShell scripts for API key validation
-- keep the scripts local-repo/operator focused
-- document usage and guardrails
-- add focused validation or smoke checks where practical
-
-## Preferred implementation style
-- PowerShell first
-- obvious operator-facing script names
-- outputs/helper artifacts routed to the project folder when applicable
-- keep scripts lightweight, deterministic, and easy to inspect
-
-## Hard rules
-- do not change engine code
-- do not add gameplay/runtime features
-- do not redesign tools
-- do not expand into broad deployment automation in this PR
-- do not implement the website prep/update/delete scripts in this PR
-- do not implement the game-template asset conversion scripts in this PR
-- keep this PR surgical and purpose-specific
-
-## Roadmap instruction
-Update roadmap status where this PR clearly advances tracked work.
-
-Also add these new roadmap items as explicitly requested:
-1. Existing games asset folders should be updated so existing images / vectors / related runtime assets can be transformed into tool-editable `data/` objects, with corresponding project JSON updates.
-2. Add the ability for a PowerShell script to create a new game from template, including a project scaffold for the tools.
-3. Add scripts to prep / update / delete the repo so it can be placed on a website.
-4. Add scripts to switch between Pay-as-you-go and Codex plan modes, and scripts to input API key material and validate it.
-
-These roadmap additions are allowed text additions for this PR.
-
-## Deliverables
-Return a single repo-structured ZIP at:
-`<project folder>/tmp/BUILD_PR_LEVEL_09_18_CODEX_PLAN_SWITCH_AND_API_KEY_SCRIPTING.zip`
-
-Include:
-- docs/pr/BUILD_PR_LEVEL_09_18_CODEX_PLAN_SWITCH_AND_API_KEY_SCRIPTING.md
-- docs/dev/codex_commands.md
-- docs/dev/commit_comment.txt
-- docs/dev/next_command.txt
-- docs/dev/reports/change_summary.txt
-- docs/dev/reports/validation_checklist.txt
-
-## Validation
-Run focused checks only:
-- PowerShell parse/readiness checks on touched scripts
-- focused smoke checks for plan switching logic
-- focused smoke checks for API key input/update path
-- focused smoke checks for API key validation path
-
-## Success definition
-- repo has clear scripts for plan switching
-- repo has clear scripts for API key input/update
-- repo has clear scripts for API key validation
-- roadmap includes the requested new items
-- final output is one ZIP in `<project folder>/tmp/`
+MODEL: GPT-5.4
+REASONING: high
+
+COMMAND:
+- use scripts/PS/codex/ as the base path for all codex scripts
+- implement template game creation script
+- include tool project scaffolding
+- enforce asset/data folder structure
+- reverse commit comment format:
+  description first
+  PR name last
+- update roadmap status only (no text changes except previously approved additions)

docs/dev/CODEX_PLAN_AND_API_KEY_SCRIPTING.md

@@ -1,15 +1,15 @@
 # Codex Plan And API Key Scripting
 
-This repo includes a focused operator scripting surface in `scripts/PS` for:
+This repo includes a focused operator scripting surface in `scripts/PS/codex` for:
 - switching active Codex billing/plan workflow mode
 - setting/updating local API key configuration
 - validating API key readiness safely
 
 ## Scripts
-- `scripts/PS/Switch-CodexPlanMode.ps1`
-- `scripts/PS/Set-CodexApiKey.ps1`
-- `scripts/PS/Validate-CodexApiKey.ps1`
-- `scripts/PS/Get-CodexOperatorState.ps1`
+- `scripts/PS/codex/Switch-CodexPlanMode.ps1`
+- `scripts/PS/codex/Set-CodexApiKey.ps1`
+- `scripts/PS/codex/Validate-CodexApiKey.ps1`
+- `scripts/PS/codex/Get-CodexOperatorState.ps1`
 
 ## State File
 - Default state file: `.codex/local/codex-operator-state.json`
@@ -20,37 +20,37 @@ This repo includes a focused operator scripting surface in `scripts/PS` for:
 Switch to Pay-as-you-go mode:
 
 ```powershell
-.\scripts\PS\Switch-CodexPlanMode.ps1 -Mode payg
+.\scripts\PS\codex\Switch-CodexPlanMode.ps1 -Mode payg
 ```
 
 Switch to Codex mode:
 
 ```powershell
-.\scripts\PS\Switch-CodexPlanMode.ps1 -Mode codex
+.\scripts\PS\codex\Switch-CodexPlanMode.ps1 -Mode codex
 ```
 
 Set or update API key for current process only (safe for smoke checks):
 
 ```powershell
-.\scripts\PS\Set-CodexApiKey.ps1 -ApiKey "sk-your-key" -Scope Process
+.\scripts\PS\codex\Set-CodexApiKey.ps1 -ApiKey "sk-your-key" -Scope Process
 ```
 
 Set or update API key for current user profile:
 
 ```powershell
-.\scripts\PS\Set-CodexApiKey.ps1 -Scope User
+.\scripts\PS\codex\Set-CodexApiKey.ps1 -Scope User
 ```
 
 Validate configured key state:
 
 ```powershell
-.\scripts\PS\Validate-CodexApiKey.ps1 -EnvVarName OPENAI_API_KEY -RequireStateRecord
+.\scripts\PS\codex\Validate-CodexApiKey.ps1 -EnvVarName OPENAI_API_KEY -RequireStateRecord
 ```
 
 Inspect current mode + metadata:
 
 ```powershell
-.\scripts\PS\Get-CodexOperatorState.ps1
+.\scripts\PS\codex\Get-CodexOperatorState.ps1
 ```
 
 ## Guardrails

docs/dev/CODEX_TEMPLATE_GAME_CREATION_SCRIPTING.md

@@ -0,0 +1,26 @@
+# Codex Template Game Creation Scripting
+
+Use `scripts/PS/codex/New-CodexTemplateGame.ps1` to create a new game scaffold from `games/_template` with the standardized asset/data and tool-project contract.
+
+## Script
+- `scripts/PS/codex/New-CodexTemplateGame.ps1`
+
+## Example
+```powershell
+.\scripts\PS\codex\New-CodexTemplateGame.ps1 -GameId "my-new-game" -DisplayName "My New Game"
+```
+
+## Generated Structure
+- `games/<game>/` copied from `games/_template/`
+- `games/<game>/assets/<domain>/` and `games/<game>/assets/<domain>/data/` for:
+  - `sprites`
+  - `tilemaps`
+  - `parallax`
+  - `vectors`
+- `games/<game>/assets/<game>.assets.json` (manifest scaffold)
+- `games/<game>/config/<game>.project.json` (tool project scaffold)
+
+## Guardrails
+- Script normalizes `-GameId` to slug format for deterministic paths.
+- Script fails if the target game folder already exists.
+- Script writes empty scaffold metadata only; no engine or gameplay files are altered.

docs/dev/COMMIT_COMMENT.txt

@@ -1,3 +1,4 @@
-BUILD_PR_LEVEL_09_18_CODEX_PLAN_SWITCH_AND_API_KEY_SCRIPTING
 
-Adds a focused PowerShell operator automation slice with repo-local plan mode switching, API key input/update, and API key validation scripts (`scripts/PS/*Codex*.ps1`). Includes usage/guardrails documentation and roadmap updates with the four requested scripting/asset-conversion items.
+Adds `scripts/PS/codex/New-CodexTemplateGame.ps1` to create new games from `games/_template`, scaffold tool project metadata, and enforce runtime/domain + tool-data folder structure under `games/<game>/assets/<domain>/data/`. Keeps codex scripts under `scripts/PS/codex/` and applies roadmap status-only updates.
+
+BUILD_PR_LEVEL_09_19_TEMPLATE_GAME_CREATION_SCRIPTING

docs/dev/NEXT_COMMAND.txt

@@ -1 +1 @@
-BUILD_PR_LEVEL_09_19_TEMPLATE_GAME_CREATION_SCRIPTING
+BUILD_PR_LEVEL_09_20_WEBSITE_REPO_PREP_SCRIPTING

docs/dev/reports/change_summary.txt

@@ -1,15 +1,13 @@
 Summary
-- Added focused operator scripts under `scripts/PS`:
-  - `Switch-CodexPlanMode.ps1`
-  - `Set-CodexApiKey.ps1`
-  - `Validate-CodexApiKey.ps1`
-  - `Get-CodexOperatorState.ps1`
-  - shared helper: `CodexOperatorState.ps1`
-- Added usage + guardrails documentation at `docs/dev/CODEX_PLAN_AND_API_KEY_SCRIPTING.md`.
-- Implemented repo-local metadata state at `.codex/local/codex-operator-state.json` (generated at runtime), with no raw key persisted to disk by scripts.
-- Updated roadmap with the four requested new items and marked the plan/API-key scripting item as completed by this PR.
-
-Behavior implemented
-- Plan mode switching between `payg` and `codex` with explicit persisted state metadata.
-- API key input/update for `Process` and `User` scopes via environment variable configuration.
-- Safe API key validation (presence + format + metadata fingerprint consistency check) without printing raw secret values.
+- Added `scripts/PS/codex/New-CodexTemplateGame.ps1` as a focused template game creation script.
+- Script copies `games/_template` into `games/<game>` and enforces active asset domains with runtime/data split:
+  - `assets/sprites/data`
+  - `assets/tilemaps/data`
+  - `assets/parallax/data`
+  - `assets/vectors/data`
+- Script scaffolds:
+  - `games/<game>/assets/<game>.assets.json`
+  - `games/<game>/config/<game>.project.json`
+- Updated codex scripting doc paths to use `scripts/PS/codex/` as the base location.
+- Updated roadmap with status-only bracket change for template game creation scripting.
+- Commit comment format remains description first and PR name last.

docs/dev/reports/validation_checklist.txt

@@ -1,37 +1,10 @@
-Validation Checklist - BUILD_PR_LEVEL_09_18_CODEX_PLAN_SWITCH_AND_API_KEY_SCRIPTING
-
-Scope
-[x] PR remains in the repo scripting lane only
-[x] No engine changes introduced
-[x] No gameplay/runtime feature changes introduced
-[x] No tool UI redesign introduced
-[x] No broad deployment automation introduced in this PR
-[x] No asset conversion automation introduced in this PR
-
-Scripts
-[x] PowerShell plan-switch script(s) added
-[x] Active mode is clear and inspectable
-[x] API key input/update script(s) added
-[x] API key validation script(s) added
-[x] Script usage is documented clearly
-[x] Script outputs/errors are actionable
-
-Validation
-[x] Touched PowerShell files parse/read cleanly
-[x] Focused plan-switch smoke checks pass
-[x] Focused API key input/update smoke checks pass
-[x] Focused API key validation smoke checks pass
-
-Roadmap
-[x] Existing roadmap status updated where applicable
-[x] Requested new roadmap items added
-[x] Added roadmap items are limited to the explicitly requested scripting/asset items
-
-Packaging
-[x] docs/pr document included
-[x] docs/dev/codex_commands.md included
-[x] docs/dev/commit_comment.txt included
-[x] docs/dev/next_command.txt included
-[x] docs/dev/reports/change_summary.txt included
-[x] docs/dev/reports/validation_checklist.txt included
-[x] Single ZIP produced at `<project folder>/tmp/BUILD_PR_LEVEL_09_18_CODEX_PLAN_SWITCH_AND_API_KEY_SCRIPTING.zip`
+Validation Checklist - BUILD_PR_LEVEL_09_19_TEMPLATE_GAME_CREATION_SCRIPTING
+
+[x] `scripts/PS/codex/` used as base path for codex scripts in touched docs/scripts
+[x] template game creation script added
+[x] tool project scaffolding generated by script
+[x] asset/data folder structure enforced by script
+[x] commit comment format is description first, PR name last
+[x] roadmap updated with status-only bracket change
+[x] PowerShell parse check passes on touched codex scripts
+[x] focused template-creation smoke check passes

docs/dev/roadmaps/MASTER_ROADMAP_HIGH_LEVEL.md

@@ -599,7 +599,7 @@
 
 ### Repo Operator + Asset Conversion Scripting Lanes
 - [ ] Existing games asset folders updated so existing images / vectors / related runtime assets can be transformed into tool-editable `data/` objects, with corresponding project JSON updates
-- [ ] Add the ability for a PowerShell script to create a new game from template, including a project scaffold for the tools
+- [x] Add the ability for a PowerShell script to create a new game from template, including a project scaffold for the tools
 - [ ] Add scripts to prep / update / delete the repo so it can be placed on a website
 - [x] Add scripts to switch between Pay-as-you-go and Codex plan modes, and scripts to input API key material and validate it
 

docs/pr/BUILD_PR_LEVEL_09_19_TEMPLATE_GAME_CREATION_SCRIPTING.md

@@ -0,0 +1,22 @@
+
+# BUILD_PR — LEVEL 09_19 — TEMPLATE GAME CREATION SCRIPTING
+
+## Objective
+Introduce PowerShell scripting to create a new game from a standardized template, including tool project scaffolding.
+
+## Key Updates
+- Codex scripts are now located at: scripts/PS/codex/
+- Commit comment format reversed (details first, PR name last)
+
+## Scope
+- script to create new game from template
+- include assets, folders, and tool project structure
+- align with asset/data split conventions
+
+## Out of Scope
+- no engine changes
+- no gameplay features
+
+## Roadmap Instruction
+- Update roadmap status only where applicable
+- Continue including previously added roadmap items