diff --git a/docs_build/dev/dod/tool_ui_readiness_dod.md b/archive/docs_build/dev/dod/tool_ui_readiness_dod.md similarity index 100% rename from docs_build/dev/dod/tool_ui_readiness_dod.md rename to archive/docs_build/dev/dod/tool_ui_readiness_dod.md diff --git a/docs_build/dev/roadmaps/MASTER_ROADMAP_ENGINE.md b/archive/docs_build/dev/roadmaps/MASTER_ROADMAP_ENGINE.md similarity index 100% rename from docs_build/dev/roadmaps/MASTER_ROADMAP_ENGINE.md rename to archive/docs_build/dev/roadmaps/MASTER_ROADMAP_ENGINE.md diff --git a/docs_build/dev/roadmaps/MASTER_ROADMAP_ENGINE_LEVEL_8_APPEND.md b/archive/docs_build/dev/roadmaps/MASTER_ROADMAP_ENGINE_LEVEL_8_APPEND.md similarity index 100% rename from docs_build/dev/roadmaps/MASTER_ROADMAP_ENGINE_LEVEL_8_APPEND.md rename to archive/docs_build/dev/roadmaps/MASTER_ROADMAP_ENGINE_LEVEL_8_APPEND.md diff --git a/docs_build/dev/roadmaps/MASTER_ROADMAP_ENGINE_LEVEL_8_UPDATE.md b/archive/docs_build/dev/roadmaps/MASTER_ROADMAP_ENGINE_LEVEL_8_UPDATE.md similarity index 100% rename from docs_build/dev/roadmaps/MASTER_ROADMAP_ENGINE_LEVEL_8_UPDATE.md rename to archive/docs_build/dev/roadmaps/MASTER_ROADMAP_ENGINE_LEVEL_8_UPDATE.md diff --git a/docs_build/dev/roadmaps/MASTER_ROADMAP_ENGINE_LEVEL_8_UPDATE_8_19.md b/archive/docs_build/dev/roadmaps/MASTER_ROADMAP_ENGINE_LEVEL_8_UPDATE_8_19.md similarity index 100% rename from docs_build/dev/roadmaps/MASTER_ROADMAP_ENGINE_LEVEL_8_UPDATE_8_19.md rename to archive/docs_build/dev/roadmaps/MASTER_ROADMAP_ENGINE_LEVEL_8_UPDATE_8_19.md diff --git a/docs_build/dev/roadmaps/MASTER_ROADMAP_RECOVERY.md b/archive/docs_build/dev/roadmaps/MASTER_ROADMAP_RECOVERY.md similarity index 100% rename from docs_build/dev/roadmaps/MASTER_ROADMAP_RECOVERY.md rename to archive/docs_build/dev/roadmaps/MASTER_ROADMAP_RECOVERY.md diff --git a/docs_build/dev/roadmaps/MASTER_ROADMAP_SAMPLES2TOOLS.md b/archive/docs_build/dev/roadmaps/MASTER_ROADMAP_SAMPLES2TOOLS.md similarity index 100% rename from docs_build/dev/roadmaps/MASTER_ROADMAP_SAMPLES2TOOLS.md rename to archive/docs_build/dev/roadmaps/MASTER_ROADMAP_SAMPLES2TOOLS.md diff --git a/docs_build/dev/roadmaps/MASTER_ROADMAP_TOOLS.md b/archive/docs_build/dev/roadmaps/MASTER_ROADMAP_TOOLS.md similarity index 100% rename from docs_build/dev/roadmaps/MASTER_ROADMAP_TOOLS.md rename to archive/docs_build/dev/roadmaps/MASTER_ROADMAP_TOOLS.md diff --git a/docs_build/dev/roadmaps/MIDI_STUDIO_V2_ROADMAP.md b/archive/docs_build/dev/roadmaps/MIDI_STUDIO_V2_ROADMAP.md similarity index 100% rename from docs_build/dev/roadmaps/MIDI_STUDIO_V2_ROADMAP.md rename to archive/docs_build/dev/roadmaps/MIDI_STUDIO_V2_ROADMAP.md diff --git a/docs_build/dev/roadmaps/README.md b/archive/docs_build/dev/roadmaps/README.md similarity index 100% rename from docs_build/dev/roadmaps/README.md rename to archive/docs_build/dev/roadmaps/README.md diff --git a/docs_build/dev/roadmaps/phases.txt b/archive/docs_build/dev/roadmaps/phases.txt similarity index 100% rename from docs_build/dev/roadmaps/phases.txt rename to archive/docs_build/dev/roadmaps/phases.txt diff --git a/docs_build/dev/BUILD_PR.md b/docs_build/dev/BUILD_PR.md deleted file mode 100644 index 30700e9cd..000000000 --- a/docs_build/dev/BUILD_PR.md +++ /dev/null @@ -1,66 +0,0 @@ -# PR_26177_006-shared-time-foundation - -## Purpose - -Add a small shared time foundation. - -## Source Of Truth - -This `BUILD_PR.md`, `PLAN_PR.md`, and the user request are the source of truth for `PR_26177_006-shared-time-foundation`. - -## Stack - -- Base branch: `PR_26177_005-shared-text-foundation` - -## Exact Scope - -- Add `src/shared/time/` foundation. -- Include duration formatting, timestamp helpers, debounce/throttle/sleep helpers where safe for shared runtime. -- Add targeted tests for the shared time area. -- No scheduler/runtime behavior changes. -- Create required Codex reports under `docs_build/dev/reports/`. -- Create repo-structured delta ZIP under `tmp/`. - -## Exact Targets - -- `docs_build/dev/PLAN_PR.md` -- `docs_build/dev/BUILD_PR.md` -- `src/shared/time/time.js` -- `tests/shared/TimeFoundation.test.mjs` -- `docs_build/dev/reports/PR_26177_006-shared-time-foundation.md` -- `docs_build/dev/reports/PR_26177_006-shared-time-foundation_branch-validation.md` -- `docs_build/dev/reports/PR_26177_006-shared-time-foundation_requirement-checklist.md` -- `docs_build/dev/reports/PR_26177_006-shared-time-foundation_validation-lane.md` -- `docs_build/dev/reports/PR_26177_006-shared-time-foundation_manual-validation-notes.md` -- `docs_build/dev/reports/codex_review.diff` -- `docs_build/dev/reports/codex_changed_files.txt` - -## Out Of Scope - -- No scheduler/runtime behavior changes. -- No browser-owned product data. -- No runtime UI changes. -- No browser storage changes. -- No API/database changes. -- No `start_of_day` folder changes. -- No unrelated cleanup. -- No full samples smoke by default. - -## Validation - -Run exactly: - -```powershell -node ./scripts/run-node-test-files.mjs tests/shared/TimeFoundation.test.mjs -node --check src/shared/time/time.js -node --check tests/shared/TimeFoundation.test.mjs -git diff --check -``` - -## Artifact - -Create repo-structured delta ZIP: - -```text -tmp/PR_26177_006-shared-time-foundation_delta.zip -``` diff --git a/docs_build/dev/BUILD_PR_LEVEL_10_6B_STANDALONE_SAMPLE_GENERIC_FAILURE_CLOSEOUT.md b/docs_build/dev/BUILD_PR_LEVEL_10_6B_STANDALONE_SAMPLE_GENERIC_FAILURE_CLOSEOUT.md deleted file mode 100644 index 3c6e356d5..000000000 --- a/docs_build/dev/BUILD_PR_LEVEL_10_6B_STANDALONE_SAMPLE_GENERIC_FAILURE_CLOSEOUT.md +++ /dev/null @@ -1,64 +0,0 @@ -# BUILD_PR: LEVEL_10_6B_STANDALONE_SAMPLE_GENERIC_FAILURE_CLOSEOUT - -## One-pass Codex build instruction -Implement the smallest valid changes needed to close remaining generic standalone sample/tool data-flow failures. - -Use the existing failing report as the source of truth: - -```text -docs_build/dev/reports/level_10_6_standalone_tool_data_flow_report.md -``` - -Focus only on failures where a sample launches but the tool does not receive or bind the payload correctly. - -## Implementation boundaries -Codex may edit only files needed for standalone sample contract stability, typically: - -- affected `samples/phase-*/*` sample files -- affected `toolbox/*` tool entrypoints or adapters -- affected manifest/contract files already used by these samples -- the standalone data-flow test only if it currently reports a false generic failure without weakening coverage -- docs_build/dev reports for the new result - -Codex must not implement unrelated features. - -## Contract checks per tool -For every changed failing area, verify: - -1. Sample declares explicit payload/manifest input. -2. Schema or normalized contract accepts the payload shape. -3. Tool receives the payload from the standalone launch path. -4. Tool renders safe empty state only when the input is truly absent. -5. Tool does not auto-load hidden defaults, demo assets, or hardcoded paths. -6. Test report captures the corrected behavior. - -## Required validation commands -Run these from repo root: - -```powershell -npm run test:launch-smoke:games -npm run test:sample-standalone:data-flow -``` - -## Required output files -Update or create: - -```text -docs_build/dev/reports/level_10_6b_standalone_generic_failure_closeout_report.md -docs_build/dev/reports/level_10_6b_tool_contract_matrix.md -``` - -The closeout report must include: - -- before generic failure count -- after generic failure count -- list of tools fixed -- list of tools still failing, if any -- exact validation commands run -- whether game launch smoke still passes - -## Done criteria -- `npm run test:launch-smoke:games` passes. -- `npm run test:sample-standalone:data-flow` passes or materially reduces generic failures with a precise remaining list. -- No silent fallback data or hardcoded asset path was added. -- Roadmap status is advanced only through real validation-backed progress. diff --git a/docs_build/dev/NEXT_RESTART.md b/docs_build/dev/NEXT_RESTART.md deleted file mode 100644 index e44fe0fc4..000000000 --- a/docs_build/dev/NEXT_RESTART.md +++ /dev/null @@ -1,67 +0,0 @@ -# RESTART — PR 11.188 Palette Manager Tool v2 - -## Open repo - -```powershell -cd C:\Users\davidq\Documents\GitHub\HTML-JavaScript-Gaming -code . -``` - -## Sync - -```powershell -git status -git pull -``` - -## Active PR - -```text -BUILD_PR_LEVEL_11_188_PALETTE_MANAGER_REVERSE_ENGINEER_AND_REBUILD -``` - -## Locked Direction - -```text -Tool v2 lane only -Palette Manager first -No schema changes -No sample changes -No game changes -No Workspace Manager v1 wiring -No legacy tool patching -No toolbox/shared usage for new v2 code -No fallback/default data -``` - -## Visible Name - -```text -Palette Manager -``` - -Do not show: - -```text -Palette Browser / Manager -Palette Manager v2 -Palette Browser v2 -``` - -## Required Header Rule - -Use the header pattern from: - -```text -/index.html -``` - -Include an accordion to hide/show the header/details section. - -## Next Execution - -Run the Codex command in: - -```text -docs_build/dev/codex_commands.md -``` diff --git a/docs_build/dev/PLAN_PR.md b/docs_build/dev/PLAN_PR.md deleted file mode 100644 index 907936aee..000000000 --- a/docs_build/dev/PLAN_PR.md +++ /dev/null @@ -1,22 +0,0 @@ -# PLAN_PR: PR_26177_006-shared-time-foundation - -## Purpose - -Add a small shared time foundation. - -## Scope - -- Add `src/shared/time/` foundation. -- Include duration formatting, timestamp helpers, sleep, debounce, and throttle helpers. -- Add targeted tests. -- No scheduler/runtime behavior changes. -- No browser-owned product data. -- No runtime UI changes. -- No unrelated cleanup. - -## Implementation Plan - -1. Add `src/shared/time/time.js`. -2. Add `tests/shared/TimeFoundation.test.mjs`. -3. Validate duration, timestamp, sleep, debounce, and throttle helpers. -4. Produce required Codex reports and repo-structured ZIP. diff --git a/docs_build/dev/PLAN_PR_LEVEL_10_6B_STANDALONE_SAMPLE_GENERIC_FAILURE_CLOSEOUT.md b/docs_build/dev/PLAN_PR_LEVEL_10_6B_STANDALONE_SAMPLE_GENERIC_FAILURE_CLOSEOUT.md deleted file mode 100644 index f4a0ebc2c..000000000 --- a/docs_build/dev/PLAN_PR_LEVEL_10_6B_STANDALONE_SAMPLE_GENERIC_FAILURE_CLOSEOUT.md +++ /dev/null @@ -1,64 +0,0 @@ -# PLAN_PR: LEVEL_10_6B_STANDALONE_SAMPLE_GENERIC_FAILURE_CLOSEOUT - -## Purpose -Close the remaining generic failure signals in the standalone sample/tool data-flow contract test without adding new tools, schemas, or features. - -## Roadmap phase -Phase 10 = TOOL + SAMPLE CONTRACT STABILITY - -## Scope -Fix only standalone sample contract failures reported by: - -```powershell -npm run test:sample-standalone:data-flow -``` - -Target failing areas from the prior report: - -- Asset Browser / Import Hub -- Asset Pipeline Tool -- Parallax Scene Studio -- Performance Profiler -- Physics Sandbox -- Replay Visualizer -- Palette binding -- State Inspector JSON input -- Tile Model Converter -- Tilemap Studio -- Vector Asset Studio -- Vector Map Editor - -## Required rule -Every fix must preserve this contract chain: - -```text -sample -> schema -> normalized input -> tool -> UI/state -``` - -## Hard constraints -- Do not add silent fallback data. -- Do not add hardcoded asset paths. -- Do not hide failures by weakening assertions. -- Do not add new schemas unless an existing documented schema is missing from the sample contract path. -- Do not make repo-wide formatting or unrelated cleanup changes. -- Do not modify `start_of_day` folders. - -## Debug priority -For each failure, answer this first: - -```text -Did the tool receive the payload? -``` - -Then check: - -- payload shape -- binding slot -- manifest path -- stale route/path -- required field mismatch -- JSON validity -- UI state update after payload ingest - -## Expected result -The PR is complete when the standalone data-flow test report shows fewer generic failure signals than before, with all changed tools receiving explicit sample payloads through the documented contract path. diff --git a/docs_build/dev/PROJECT_INSTRUCTIONS.md b/docs_build/dev/PROJECT_INSTRUCTIONS.md deleted file mode 100644 index af9e9e2db..000000000 --- a/docs_build/dev/PROJECT_INSTRUCTIONS.md +++ /dev/null @@ -1,2430 +0,0 @@ -# PROJECT INSTRUCTIONS - -You are working in a docs-first repo workflow. - -Workflow: -PLAN_PR → BUILD_PR → APPLY_PR - -PR lifecycle gate: -PR Open → Plan → Build → Validation → Approved → Merged → Main Verified → Closed - -The PLAN_PR → BUILD_PR → APPLY_PR workflow remains preserved. PR Open is the first lifecycle status for active work, Plan happens after PR Open on the same PR branch, and Closed is the final repository-state gate. - -# WORKFLOW & EXECUTION - -## PR NAMING STANDARD - -PR names MUST follow: - -`PR___<###>-` - -Where: -- `YY` = year (2 digit) -- `JJJ` = Julian day (001-365) -- `TEAM` = required team ownership token from `docs_build/dev/PROJECT_MULTI_PC.txt` -- `###` = sequence for the day (001+) - -Example: -- `PR_26171_ALPHA_065-message-studio-parent-child-table-foundation` -- `PR_26171_BETA_069-message-tts-profile-contract-alignment` -- `PR_26171_GAMMA_071-main-merge-conflict-recovery` - -Branch names MUST mirror PR ownership: - -`pr/--<###>-` - -Branch examples: -- `pr/26171-ALPHA-065-message-studio-parent-child-table-foundation` -- `pr/26171-BETA-069-message-tts-profile-contract-alignment` -- `pr/26171-GAMMA-071-main-merge-conflict-recovery` - -Rules: -- Must be unique per day -- Must be sortable -- `TEAM` is required -- `TEAM` ownership comes from `docs_build/dev/PROJECT_MULTI_PC.txt` -- Team ownership is independent of machine, workspace, laptop, desktop, or environment -- Description must be short and hyphenated -- Do NOT reuse old `PR_11_*` format for new PRs -- Existing PC/LAPTOP, desktop/laptop, workspace, environment, or machine-parity examples are historical only -- Future PR reports, recovery reports, validation reports, and manual validation notes must include TEAM ownership - -## PR LIFECYCLE STATE GATE - -Required state order: - -1. PR Open -2. Plan -3. Build -4. Validation -5. Approved -6. Merged -7. Main Verified -8. Closed - -Definitions: -- PR Open is the first active lifecycle state. -- PR Open means the tracked PR identity and source branch have been created and named before Plan begins. -- Plan happens after PR Open on the same PR branch. -- Build, validation, reports, ZIP packaging, and closeout stay tied to that same PR identity and source branch. -- No BUILD_PR may proceed without a PR name and active branch/PR identity unless it is explicitly marked `PLAN_ONLY`. -- Build means scoped implementation, audit, report, validation, governance, or cleanup work is in progress for that PR identity. -- Validation means requested checks, required report creation, manual validation notes, and ZIP packaging are being completed. -- Approved means the owner or required reviewer has approved the PR outcome for merge. -- Merged means the PR has merged and changes have been pushed. -- Main Verified means Codex is back on `main`, `main` includes the merge commit or recorded final commit, the worktree is clean, local/origin sync is `0/0`, and no untracked files remain. -- Closed means every Closed gate below is PASS. - -Closed is valid only when all are PASS: -- PR merged and changes pushed. -- Current branch is `main`. -- `main` includes the merge commit or recorded final commit. -- Worktree clean. -- Local/origin sync is `0/0`. -- No untracked files. -- Branch disposition recorded as `retained`. -- Required reports exist. -- Required repo-structured ZIP under `tmp/` exists. -- Backlog updated. -- Tool state updated when applicable. - -Hard stop: -- A team must not begin another PR if its previous PR is not Closed. -- Exception is allowed only for explicitly documented stacked PR chains. - -Required final closeout output: - -```text -FINAL REPOSITORY STATE: -- Branch -- Worktree -- Local/origin sync -- PR number/name -- PR status -- Merge/final commit -- Branch disposition -- Backlog update status -- Tool state update status -- ZIP path -- Closeout PASS/FAIL -``` - -## CHATGPT EXECUTION ROLE - -ChatGPT no longer creates PLAN_PR, BUILD_PR, APPLY_PR docs, ZIP bundles, or implementation code. - -ChatGPT repo workflow response formatting is governed by `OUTPUT RULES` and the newest explicit ChatGPT workflow sections below. - -ChatGPT must not: -- create ZIP files -- reference ZIP delivery -- produce PLAN/BUILD/APPLY docs -- write implementation code unless explicitly requested - -## CODEX EXECUTION ROLE - -Codex creates: -- PLAN_PR docs -- BUILD_PR docs -- APPLY_PR docs when needed -- repo-structured ZIP bundles -- implementation changes -- Playwright/test updates when required -- review artifacts for ChatGPT code review - -Codex must place detailed content in: -- `docs_build/pr/*` -- `docs_build/dev/codex_commands.md` -- `docs_build/dev/commit_comment.txt` -- `docs_build/dev/reports/*` - -## USER ROLE - -User: -- runs Codex -- validates results -- commits approved changes -- uploads deltas/reports when ChatGPT review is needed - -## RULES - -- One PR purpose only -- Smallest scoped valid change -- BUILD must be one-pass executable -- No vague wording -- No repo-wide scanning unless required -- Do not expand scope beyond the PR -- Do not modify `start_of_day` folders unless requested - -## MAIN BRANCH EXECUTION GUARD - -Before any BUILD execution, Codex must verify the current git branch. - -Rules: -- The required execution branch is: - - `main` -- If the current branch is not `main`: - - HARD STOP. - - Do not create code changes. - - Do not create implementation PRs. - - Do not create ZIP artifacts. - - Do not continue execution. -- Codex must report: - - current branch - - expected branch (`main`) - - local branches found -- Codex may continue only after the user explicitly returns to `main`. - -Exception: -- Explicit branch-audit or branch-comparison PRs may inspect non-main branches but must not perform implementation work on them. - -Required report output: -- Current branch -- Branch validation PASS/FAIL - -## SLIDER VALUE VISIBILITY REQUIREMENT - -All user-adjustable slider controls must display their current value while being adjusted. - -Rules: -- Value display must update live during drag/input. -- Creators must not need to release the slider to see the value. -- Value display must remain visible at all times. -- Value display must not rely solely on browser-native tooltips. -- Sliders should prefer: - - Label + Slider + Current Value -- Example: - - `Contrast [------^------] 40%` - - `Saturation [------^------] 75%` - - `Hue Shift [------^------] +15°` -- Units should be displayed when meaningful: - - `%` - - degrees - - pixels - - milliseconds - - volume - - opacity -- Floating thumb tooltips are optional. -- Persistent visible values are required. -- Applies to: - - Toolbox tools - - Game Hub controls - - Account/Admin pages - - Theme V2 controls - - Future tools and pages - -## SLIDER RESET BEHAVIOR REQUIREMENT - -All user-adjustable sliders must support reset-to-default behavior. - -Rules: -- Double-clicking a slider resets it to its default value. -- Reset must occur immediately. -- Reset value must be visible through the live value display. -- Creators must not need a separate reset button for individual sliders. -- Tool-specific Reset buttons may still exist for resetting multiple controls. -- Slider tooltips/help text should identify the default value when practical. -- Applies to: - - Toolbox tools - - Game Hub controls - - Account/Admin pages - - Theme V2 controls - - Future tools and pages - -## RULE PRECEDENCE - -Newer appended sections override earlier overlapping rules. - -When rules overlap, use the most specific current section as authoritative. - -Conflicting workflow instructions must resolve to the newest explicit section. - -Future governance additions should extend existing sections instead of duplicating overlapping guidance. - -## GOVERNANCE CLOSEOUT - -Docs-only PRs should prefer bundling with related docs/workflow cleanup when safe. - -Stabilization/recovery lane rules supersede older generalized workflow assumptions. - -Engine/tool/integration boundaries are authoritative for validation routing. - -Hidden validation expansion is prohibited. - -Workflow and testing language must not assume implicit persisted workspace, toolState, `localStorage`, `sessionStorage`, sample, or runtime state. - -Required validation lane names are: -- contract -- runtime -- integration -- engine -- samples -- recovery/UAT - -## PROJECT INSTRUCTIONS STABILITY AND MAINTENANCE MODE - -`PROJECT_INSTRUCTIONS.md` is now considered architecturally stabilized. - -Future additions should prefer targeted amendments instead of broad workflow rewrites. - -New rules should extend existing authoritative sections whenever possible. - -Avoid introducing parallel governance systems or duplicate rule sets. - -Anti-drift governance: -- avoid capability drift across `src/`, deprecated `archive/v1-v2/tools/`, deprecated `archive/v1-v2/games/`, deprecated `archive/v1-v2/samples/`, and `toolbox/` -- avoid workflow drift across overlapping sections -- avoid validation drift between engine, tool, and integration lanes -- avoid UI/UX drift from Workspace V2 ecosystem contracts - -Stabilization intent: -- governance exists to reduce monolith growth, hidden coupling, and duplicated runtime behavior -- reusable/shared capability should converge into `src/` -- first-class tools should converge toward shared Workspace V2 lifecycle behavior -- targeted validation is the preferred operational mode - -Future guidance: -- future governance PRs should remain small and execution-backed -- implementation, runtime, and tool work should now take priority over additional governance expansion unless a real gap is discovered -- governance additions should solve demonstrated operational problems rather than hypothetical future issues - -## NAVIGATION, LIST, AND TOOLBOX MODEL GOVERNANCE - -Navigation menus, submenus, nested submenus, and user-facing lists must be alphabetically sorted when they are presented as browseable choices. - -Primary top-level header navigation is an explicit product IA exception and must remain: -- Games -- Toolbox -- Marketplace -- Learn -- Account -- Admin - -Allowed intentional-order exceptions: -- primary top-level header navigation -- Toolbox groups and tiles when they are presented as creator workflow surfaces -- workflow paths -- Build Path -- dependency paths -- Game Progress -- Launch Progress -- guided creator steps - -Every intentional-order exception must be documented in the PR report that introduces or preserves it. - -### Workflow Ordering Governance - -When a surface represents a creator workflow, items are ordered by the likely next action, not alphabetically. -Workflow ordering is an approved exception to alphabetical ordering. -This applies to Toolbox, Game Hub, Create, Publish, Progress, and future guided workflows. - -Rules: -- Order follows how users naturally work: - - Select -> Create -> Review - - Left -> Right - - Top -> Bottom -- The next tile should represent the most likely next creator action. -- Tile ordering should minimize navigation decisions. - -Create group order: -1. Game Hub -2. Game Crew -3. Game Configuration -4. Tags - -Team planning distinction: -- Studio Team is the account-level roster. -- Game Crew is the game-level assignment surface. -- Current Toolbox implementation focus is Game Crew. -- Creator functionality that previously lived in Account/Team planning should be planned through Create/Game Crew when it is game-specific. - -Toolbox status values are: -- Ready -- Wireframe -- Under Construction -- Planned -- Hidden -- Deprecated - -Toolbox progress foundation fields are: -- `requiredForTestable` -- `requiredForPublish` -- `requires` -- `status` -- `progressChecklist` - -Progress and Build Path views remain wireframe-only until a later implementation PR explicitly introduces a declared registry/data source and runtime behavior. - -Game Hub is the next first real Toolbox rebuild target. Its contract owns: -- Project Identity -- Project Status -- Project Progress -- Launch Progress - -Do not implement Game Hub runtime behavior, persistence, database behavior, authentication, or save/load flows before the rebuild PR explicitly scopes those capabilities. - -## TOOL STATUS GOVERNANCE - -The authoritative tool status values are: -- `planned` -- `wireframe` -- `beta` -- `complete` -- `deprecated` - -Status definitions: -- `planned`: Not designed yet. No meaningful UI. No ownership defined. -- `wireframe`: Tool exists. User can understand workflow. Data ownership is defined. Not functionally usable. -- `beta`: Functionally usable. Can be used in a real game. May still contain incomplete workflows, placeholder data, UI cleanup issues, unused fields, missing validation, or incomplete code review. -- `complete`: Functionally usable. Code reviewed. Dead code removed. Invalid fields removed. UI cleaned up. No known placeholder data. No known invalid controls. Ready for long-term support. -- `deprecated`: Tool remains supported but is not recommended for new workflows. Must remain deprecated before removal. - -UAT rule: -- A tool required for the current MVP game path must be `beta` or `complete` before UAT. -- `complete` is not required for MVP UAT, but `beta` is the minimum usable state. - -## TARGETED MSJ VALIDATION GOVERNANCE - -Every tool, page, or `src/` change must declare its impacted MSJ/test lane. - -Run only the affected MSJ/test lane by default. - -Do not run the full suite for small scoped changes unless one of these shared surfaces changes: -- shared runtime behavior -- shared parser behavior -- shared DB behavior -- shared Theme V2 behavior -- cross-tool integration behavior - -If a shared source file changes, name the affected dependent lanes and run only those targeted lanes unless the dependency impact proves broader validation is required. - -Reports must state: -- impacted lane -- skipped lanes -- why skipped lanes were safe to skip -- when the full suite is required - -## SHARED MOCK DB ADAPTER CONTRACT - -All current app and tool mock data must flow through the shared DB adapter under `src/engine/persistence`. - -Tools must not maintain isolated page-local DB snapshots for data that should be visible to the Mock DB viewer or to another current tool. - -The active browser mock implementation is the Mock adapter. UAT and production persistence must swap through the same module-level contract by deployment configuration rather than by changing tool UI code. - -The Mock DB viewer must render live adapter state and table schemas, including empty tables with headers. It must not render hardcoded table dumps, hardcoded row counts, or copied static JSON snapshots. - -Audit ownership is users-only: every shared table record uses `key`, `createdAt`, `updatedAt`, `createdBy`, and `updatedBy`; the ownership fields reference `users.key`. Roles are modeled with `roles` and `user_roles`. - -## DB-BACKED PRODUCT DATA SSOT GOVERNANCE - -Web UI must access product data only through API or service contracts backed by DB adapters. - -Allowed production flow: -- Web UI -> API/Service Contract -> Server DB - -Allowed dev/UAT/test flow: -- Web UI -> API/Service Contract -> DB Adapter -- The DB Adapter may be MEM DB, Local DB, Test DB, or Server DB. - -Prohibited product-data ownership: -- page-local product data arrays -- page-local metadata registries -- hardcoded product counts -- duplicated status, group, path, or order data -- duplicated lookup maps that compete with DB-backed metadata -- browser storage as the product source of truth -- UI-only vote, order, or status state -- direct DB-shaped product data embedded in HTML or browser JavaScript pages - -Toolbox and Admin tool metadata must use a shared DB-backed tool metadata source for `toolKey`, `toolName`, `group`, `path`, `order`, and `status`. Browser pages may render metadata returned by the API/service contract, but they must not own a separate runtime copy of that metadata. - -## DATABASE DIRECTION - -Postgres is the authoritative active runtime database. - -SQLite is deprecated/retired and is not an active runtime database for Local (VS Code), DEV, IST, UAT, or PROD. - -Rules: -- New database work must target Postgres. -- Local (VS Code) API -> Postgres is the required direction. -- New PRs must not introduce SQLite persistence. -- Do not add new SQLite services. -- Do not add new SQLite DDL. -- Do not add new SQLite seed data. -- Do not add new SQLite runtime persistence. -- Legacy SQLite references may remain only as documented technical debt when they already exist. -- Browser code must not own product data or generate authoritative persistence keys. - -## DEV RUNTIME BOUNDARY - -All mock/dev-only runtime implementation must live under `src/dev-runtime/`. - -Required dev-runtime folders: -- `src/dev-runtime/auth/` -- `src/dev-runtime/persistence/` -- `src/dev-runtime/admin/` -- `src/dev-runtime/testing/` -- `src/dev-runtime/guest-seeds/` - -Rules: -- UAT/PROD must never import, bundle, or deploy `src/dev-runtime/`. -- Active tools must use declared runtime contracts and must not import `src/dev-runtime/` directly. -- Dev-only adapters may be exposed through existing dev/runtime contract shims only when the deployment boundary keeps `src/dev-runtime/` out of UAT/PROD bundles. -- No fallback auth, session, user, admin, or system user data is allowed. -- Local session state must resolve selected users and roles from persisted Memory DB `users`, `roles`, and `user_roles` records. -- Missing users or roles must fail visibly with actionable diagnostics. - -## ENVIRONMENT CONFIGURATION GOVERNANCE - -Runtime startup loads `.env` only. - -Official environment model: -- `Local (VS Code)` -- `DEV` -- `IST` -- `UAT` -- `PROD` - -Promotion order: -- `Local (VS Code) -> DEV -> IST -> UAT -> PROD` - -Environment invariance rule: -- The deployable artifact is identical across every environment. -- Only `.env` values and environment-managed secret values differ between environments. -- Application code, runtime code, API/service code, database runtime scripts, migrations, and bundles must not fork by environment name. - -Shared API/service contract: -- One shared API/service contract is required across Local (VS Code), DEV, IST, UAT, and PROD. -- Browser/UI/runtime code must consume the same contract in every environment. -- Environment-specific URLs, endpoints, keys, buckets, and prefixes are `.env` or environment-managed secret/config values only. -- Do not create environment-specific API/service contracts. -- Do not split Local API and Public API contracts. Local and shared environments use the same API/service contract; URLs may differ by `.env` only. - -Required services in every environment: -- Supabase Auth -- Supabase Postgres -- Cloudflare R2 - -Guest seed data rule: -- All environments receive approved guest seed data for all tools. -- Guest seed data is shared environment setup data, not an environment-specific behavior fork. -- Guest seed data must be applied through the shared data/service contract and must not require per-environment application code. - -Required Cloudflare R2 top-level prefixes: -- Local (VS Code): `/local/` -- DEV: `/dev/` -- IST: `/ist/` -- UAT: `/uat/` -- PROD: `/prod/` - -Derived R2 paths for projects, backups, exports, or future storage lanes must stay under the matching top-level prefix for the active environment. - -Only `.env.example` is committed to the repository. - -Real `.env` files are user/environment-owned and must live outside the repo clone or be injected by deployment. - -Official external environment file names when a copy-source file is used outside the repo clone: -- `.env.local` -- `.env.dev` -- `.env.ist` -- `.env.uat` -- `.env.prod` - -Example external layout: -- `/env/local/.env` -- `/env/dev/.env` -- `/env/ist/.env` -- `/env/uat/.env` -- `/env/prod/.env` -- `/GFS/` repo clone - -The app/runtime reads `.env` values supplied by the target environment. It must not require real `.env` files to be committed inside the repo clone. - -`.env.prd` is legacy technical debt only. New environment governance uses `.env.prod` for external PROD copy-source naming and the `PROD` environment name. - -Allowed `GAMEFOUNDRY_ENVIRONMENT` values: -- `local` -- `dev` -- `ist` -- `uat` -- `prod` - -`GAMEFOUNDRY_ENVIRONMENT_LABEL` is display-only and must not drive runtime behavior, API/service selection, database selection, storage selection, or feature behavior. - -Valid environment stages are: -- `Local (VS Code)` -- `DEV` -- `IST` -- `UAT` -- `PROD` - -Manual deployment-target flow: -1. Copy the selected `.env.` file to `.env`. -2. Run validation. -3. Apply DDL/DML migrations. -4. Start runtime. - -Runtime environment parameters are prohibited. - -Do not introduce runtime parameters such as: -- `--env` -- `--environment` -- `ENVIRONMENT=LOCAL` -- `ENVIRONMENT=DEV` -- `ENVIRONMENT=UAT` -- `ENVIRONMENT=PROD` - -`Local (VS Code)`, `DEV`, `IST`, `UAT`, and `PROD` are environment stages, not application behaviors. - -Application code, runtime code, API/service code, and DB runtime scripts must not branch behavior by deployment target name. - -Host/domain configuration: -- Local (VS Code) uses `127.0.0.1` hostnames. -- DEV, IST, UAT, and PROD use configured `*.gamefoundrystudio.com` hostnames. -- Host/domain differences are configuration values only and must not create separate deployable artifacts or environment-specific code. - -Feature flag governance: -- Feature flags must not create permanent environment-specific behavior. -- Feature flags may be used only for staged rollout, testing, or emergency mitigation. -- Feature flags must be removed, promoted to normal behavior, or documented as active temporary controls when the rollout, test, or mitigation ends. - -## RUNTIME SCRIPT NAMING GOVERNANCE - -Active runtime script names should describe capability rather than vendor/provider. - -Preferred runtime naming nouns are: -- `auth` -- `database` -- `storage` -- `telemetry` -- `api` - -Avoid provider or vendor names in future active runtime script names. - -When an active script is renamed, a temporary compatibility wrapper may remain only when needed for command continuity. - -Compatibility wrappers must log: - -`Deprecated script name. Use .` - -## ARCHIVED V1/V2 REFERENCE MATERIAL - -Deprecated V1/V2 reference material lives under: - -- `archive/v1-v2/tools/` -- `archive/v1-v2/games/` -- `archive/v1-v2/samples/` - -Rules: -- Archive material is retained for reference and traceability, not active app ownership. -- Active app navigation must not point users into `archive/v1-v2/`. -- Active validation must not run tests against `archive/v1-v2/` unless a later PR explicitly reclassifies a target. -- New toolbox, game, sample, engine, and Theme V2 work must not use archived material as the implementation source of truth. -- Cleanup and governance docs should refer to archived V1/V2 reference material through `archive/v1-v2/`. - -## GAMEFOUNDRYSTUDIO NORTH STAR - -GameFoundryStudio should present as an open-web creator destination where players and makers can move fluidly between creator tools, playable games, marketplace assets, tutorials, cloud saves, and community discovery. - -The product guidance phrase is: - -`Build · Play · Share` - -Use that phrase as a compact IA and copywriting anchor: -- Build: tools and creation flow, including asset creation, prototypes, systems, and publishing preparation. -- Play: games and discovery, including playable games, arcade browsing, testing, and saves. -- Share: public game pages, share links, creator profiles, marketplace assets, tutorials/community, ratings, and future publish/export flows. - -## GAMEFOUNDRYSTUDIO THEME V2 GOVERNANCE - -`assets/theme-v2` is the only approved styling surface for public/root GameFoundryStudio page work as bounded below. - -V1/legacy CSS is deprecated and out of play. - -### Theme Surface Boundary - -`assets/theme-v2/css` owns public/root GameFoundryStudio page styling: -- root Home -- Company pages -- Tools index -- public/root tool pages -- marketing/content surfaces -- placeholder Admin/Account pages until DB/login implementation - -`src/engine/theme` owns engine/runtime first-class tool shell styling: -- runtime tool shell -- engine-facing first-class tools -- reusable runtime UI foundations - -Rules: -- Do not deprecate `src/engine/theme` at this time. -- Do not duplicate behavior between the two surfaces. -- Do not create competing `.tool-shell` implementations. -- If both public/root tools and runtime first-class tools need the same behavior, document the shared shell contract first. -- Shared behavior must be promoted intentionally rather than patched independently in both places. -- Collapse/rail behavior currently belongs only to the public/root `.tool-workspace` shell unless a later PR explicitly promotes it to shared runtime shell behavior. - -### Theme V2 Only CSS Rule - -- Theme V2 is the only active styling system for public/root GameFoundryStudio page work. -- V1/legacy CSS is deprecated and out of play. -- V1/legacy CSS must not be used as a source. -- V1/legacy CSS must not be copied. -- V1/legacy CSS must not be ported. -- V1/legacy CSS must not be compared as the desired target. -- V1/legacy CSS must not be extended. -- V1/legacy CSS must not be reintroduced through aliases, duplicate selectors, wrapper selectors, compatibility classes, or fallback imports. -- New CSS must be authored directly in Theme V2 only when approved as reusable Theme V2 design-system styling. -- Pages not migrated to Theme V2 may temporarily retain their existing references until their migration PR. -- Pages that have migrated to Theme V2 must not reference V1/legacy CSS. -- Migration means replacing the page with Theme V2 usage, not copying V1 styles into Theme V2. - -If Theme V2 lacks a needed pattern: -1. Document the design-system gap. -2. Request approval. -3. Implement the reusable pattern directly in Theme V2. -4. Do not solve it by using V1. - -Rules: -- Do not extend deprecated CSS. -- Do not create new CSS files outside `assets/theme-v2/css`. -- No page-local CSS. -- No tool-local CSS. -- No inline style attributes. -- No `