BUILD_PR_OVERLAY_OPERATOR_COMMANDS: add debug-only overlay operator command contract and sample-level console integration using public overlay APIs only

DavidQ · DavidQ · commit 5b87cf0a8ade · 2026-04-05T19:38:27.000-04:00
diff --git a/docs/dev/CODEX_COMMANDS.md b/docs/dev/CODEX_COMMANDS.md
@@ -1,20 +1,21 @@
 MODEL: GPT-5.4-codex
 REASONING: high
 
-Create BUILD_PR_OVERLAY_DATA_PROVIDERS
-
-Follow PLAN_PR -> BUILD_PR -> APPLY_PR
+COMMAND:
+Create BUILD_PR_OVERLAY_OPERATOR_COMMANDS
 
 Requirements:
-- Docs-first unless APPLY explicitly needs code guidance notes
-- No engine core changes
+- Follow PLAN_PR -> BUILD_PR -> APPLY_PR
 - One PR per purpose
+- No engine core changes
 - Keep integration sample-level
-- Use MultiSystemDemoScene.js as the integration reference
-- Define a clean read-only provider layer for Debug Overlay panels
-- Preserve the Dev Console = command/control boundary
-- Preserve the Debug Overlay = telemetry/visual boundary
-- Panels must consume provider snapshots instead of direct runtime reads
-- Include recommended provider IDs, descriptor shape, guardrails, validation, accomplishments summary, and next-step recommendations
-- Write outputs under docs/pr and docs/dev/reports
-- Package to <project folder>/tmp/BUILD_PR_OVERLAY_DATA_PROVIDERS_delta.zip
+- Use MultiSystemDemoScene.js as the integration target
+- Register overlay.* operator commands through the Dev Console command registry
+- Use only approved public overlay/registry APIs
+- Support: overlay.help, overlay.list, overlay.status, overlay.show <panelId>, overlay.hide <panelId>, overlay.toggle <panelId>, overlay.showAll, overlay.hideAll, overlay.order
+- Provide deterministic operator-readable outputs
+- Fail safely on invalid or missing panel IDs
+- Keep everything debug-only
+- Validate with node --check and sample command execution
+- Write docs under docs/pr and reports under docs/dev/reports
+- Package to <project folder>/tmp/BUILD_PR_OVERLAY_OPERATOR_COMMANDS_delta.zip
diff --git a/docs/dev/COMMIT_COMMENT.txt b/docs/dev/COMMIT_COMMENT.txt
@@ -1 +1 @@
-docs(debug): define overlay data provider contract and next-step execution path
+BUILD_PR_OVERLAY_OPERATOR_COMMANDS: add debug-only overlay operator command contract and sample-level console integration using public overlay APIs only
diff --git a/docs/dev/NEXT_COMMAND.txt b/docs/dev/NEXT_COMMAND.txt
@@ -1 +1,11 @@
-Create BUILD_PR_OVERLAY_OPERATOR_COMMANDS as the next docs-first bundle, scoped to public console commands for querying/toggling overlay state through approved overlay contracts only.
+Create BUILD_PR_OVERLAY_PANEL_PERSISTENCE
+
+Requirements:
+- Follow PLAN_PR -> BUILD_PR -> APPLY_PR
+- One PR per purpose
+- No engine core changes
+- Keep integration sample-level
+- Persist overlay panel enabled/disabled state through approved debug-only storage
+- Restore state safely on sample boot without coupling console to overlay internals
+- Document validation, failure paths, and fallback defaults
+- Package to <project folder>/tmp/BUILD_PR_OVERLAY_PANEL_PERSISTENCE_delta.zip
diff --git a/docs/dev/reports/change_summary.txt b/docs/dev/reports/change_summary.txt
@@ -1,22 +1,31 @@
-BUILD_PR_OVERLAY_DATA_PROVIDERS change summary
+BUILD_PR_OVERLAY_OPERATOR_COMMANDS change summary
 
-What was updated
-- Refreshed PLAN/BUILD/APPLY docs for overlay data providers.
-- Kept scope docs-first and sample-level.
-- Preserved Dev Console (command/control) vs Debug Overlay (telemetry/visual) boundary.
-- Defined read-only provider model where panels consume provider snapshots only.
+Implemented
+- Added a new Dev Console command pack:
+  - `tools/dev/commandPacks/overlayCommandPack.js`
+- Wired overlay command pack into Dev Console integration:
+  - `tools/dev/devConsoleIntegration.js`
 
-Key contract outcomes
-- Recommended provider IDs documented.
-- Descriptor shape and validation rules documented.
-- Guardrails documented to prevent panel-to-console coupling and overlay host special cases.
-- Validation goals documented for deterministic snapshot behavior and graceful fallback.
-- Accomplishments summary and next-step recommendations included.
+Overlay commands registered
+- `overlay.help`
+- `overlay.list`
+- `overlay.status`
+- `overlay.show <panelId>`
+- `overlay.hide <panelId>`
+- `overlay.toggle <panelId>`
+- `overlay.showAll`
+- `overlay.hideAll`
+- `overlay.order`
 
-Files included
-- docs/pr/PLAN_PR_OVERLAY_DATA_PROVIDERS.md
-- docs/pr/BUILD_PR_OVERLAY_DATA_PROVIDERS.md
-- docs/pr/APPLY_PR_OVERLAY_DATA_PROVIDERS.md
-- docs/dev/reports/change_summary.txt
-- docs/dev/reports/validation_checklist.txt
-- docs/dev/reports/file_tree.txt
+Contract and boundary outcomes
+- Commands use public runtime/registry APIs only.
+- Deterministic operator-readable output is enforced.
+- Invalid/missing panel IDs fail safely with explicit error codes.
+- Debug-only scope maintained.
+- No engine core changes.
+- Sample-level integration target preserved (`MultiSystemDemoScene.js`).
+
+Docs updated
+- docs/pr/PLAN_PR_OVERLAY_OPERATOR_COMMANDS.md
+- docs/pr/BUILD_PR_OVERLAY_OPERATOR_COMMANDS.md
+- docs/pr/APPLY_PR_OVERLAY_OPERATOR_COMMANDS.md
diff --git a/docs/dev/reports/file_tree.txt b/docs/dev/reports/file_tree.txt
@@ -1,13 +1,18 @@
 HTML-JavaScript-Gaming/
+|-- tools/
+|   `-- dev/
+|       |-- commandPacks/
+|       |   `-- overlayCommandPack.js
+|       `-- devConsoleIntegration.js
 |-- docs/
 |   |-- pr/
-|   |   |-- PLAN_PR_OVERLAY_DATA_PROVIDERS.md
-|   |   |-- BUILD_PR_OVERLAY_DATA_PROVIDERS.md
-|   |   `-- APPLY_PR_OVERLAY_DATA_PROVIDERS.md
+|   |   |-- PLAN_PR_OVERLAY_OPERATOR_COMMANDS.md
+|   |   |-- BUILD_PR_OVERLAY_OPERATOR_COMMANDS.md
+|   |   `-- APPLY_PR_OVERLAY_OPERATOR_COMMANDS.md
 |   `-- dev/
 |       `-- reports/
 |           |-- change_summary.txt
 |           |-- validation_checklist.txt
 |           `-- file_tree.txt
 `-- tmp/
-    `-- BUILD_PR_OVERLAY_DATA_PROVIDERS_delta.zip
+    `-- BUILD_PR_OVERLAY_OPERATOR_COMMANDS_delta.zip
diff --git a/docs/dev/reports/validation_checklist.txt b/docs/dev/reports/validation_checklist.txt
@@ -1,31 +1,38 @@
-BUILD_PR_OVERLAY_DATA_PROVIDERS validation checklist
+BUILD_PR_OVERLAY_OPERATOR_COMMANDS validation checklist
 
 Workflow
-- [done] PLAN_PR documented
-- [done] BUILD_PR documented
-- [done] APPLY_PR documented
+- [done] PLAN_PR, BUILD_PR, APPLY_PR docs updated
 - [done] One PR purpose only
-- [done] Docs-first bundle
 
-Scope and Boundaries
+Scope
 - [done] No engine core changes
-- [done] Sample-level integration reference documented
-- [done] MultiSystemDemoScene.js used as reference
-- [done] Dev Console boundary preserved
-- [done] Debug Overlay boundary preserved
+- [done] Integration remains sample-level
+- [done] MultiSystemDemoScene.js retained as reference target
+- [done] Dev Console vs Debug Overlay boundary preserved
 
-Provider Contract
-- [done] Read-only provider layer defined
-- [done] Recommended provider IDs documented
-- [done] Provider descriptor shape documented
-- [done] Provider guardrails documented
-- [done] Panels consume provider snapshots, not direct runtime reads
-- [done] Validation rules documented
+Functional Commands
+- [done] overlay.help
+- [done] overlay.list
+- [done] overlay.status
+- [done] overlay.show <panelId>
+- [done] overlay.hide <panelId>
+- [done] overlay.toggle <panelId>
+- [done] overlay.showAll
+- [done] overlay.hideAll
+- [done] overlay.order
 
-Build Quality
-- [done] Accomplishments summary included
-- [done] Next-step recommendations included
+Behavior
+- [done] Deterministic operator-readable outputs
+- [done] Invalid panel IDs fail safely
+- [done] Missing panel IDs fail safely
+- [done] Public overlay/registry APIs only
+
+Validation Commands
+- [done] node --check tools/dev/commandPacks/overlayCommandPack.js
+- [done] node --check tools/dev/devConsoleIntegration.js
+- [done] sample command harness execution for required overlay commands
 
 Packaging
-- [done] Outputs written under docs/pr and docs/dev/reports
-- [done] Delta zip generated at <project folder>/tmp/BUILD_PR_OVERLAY_DATA_PROVIDERS_delta.zip
+- [done] Docs under docs/pr
+- [done] Reports under docs/dev/reports
+- [done] Delta zip generated at <project folder>/tmp/BUILD_PR_OVERLAY_OPERATOR_COMMANDS_delta.zip
diff --git a/docs/pr/APPLY_PR_OVERLAY_OPERATOR_COMMANDS.md b/docs/pr/APPLY_PR_OVERLAY_OPERATOR_COMMANDS.md
@@ -0,0 +1,30 @@
+Toolbox Aid
+David Quesenberry
+04/05/2026
+APPLY_PR_OVERLAY_OPERATOR_COMMANDS.md
+
+# APPLY_PR_OVERLAY_OPERATOR_COMMANDS
+
+## Objective
+Apply the implemented overlay operator command pack without expanding beyond this PR purpose.
+
+## Apply Scope
+- `tools/dev/commandPacks/overlayCommandPack.js`
+- `tools/dev/devConsoleIntegration.js`
+- docs and reports for this PR
+
+## Guardrails
+- no engine core changes
+- no runtime architecture refactor
+- no direct console-to-overlay private coupling
+- no sample-wide or repo-wide debug framework expansion
+
+## Apply Validation
+1. Confirm `overlay.*` commands appear in registry/autocomplete.
+2. Confirm deterministic output for list/order/status commands.
+3. Confirm safe failure on invalid panel IDs.
+4. Confirm show/hide/toggle/showAll/hideAll state changes apply via public APIs.
+5. Confirm `node --check` passes for touched JS files.
+
+## Expected Outcome
+Operators can inspect and control overlay panel visibility from the Dev Console while maintaining the Dev Console vs Debug Overlay boundary.
diff --git a/docs/pr/BUILD_PR_OVERLAY_OPERATOR_COMMANDS.md b/docs/pr/BUILD_PR_OVERLAY_OPERATOR_COMMANDS.md
@@ -0,0 +1,64 @@
+Toolbox Aid
+David Quesenberry
+04/05/2026
+BUILD_PR_OVERLAY_OPERATOR_COMMANDS.md
+
+# BUILD_PR_OVERLAY_OPERATOR_COMMANDS
+
+## Objective
+Implement debug-only `overlay.*` operator commands through the Dev Console command registry using approved public overlay/registry APIs.
+
+## Implementation Scope
+- Add `tools/dev/commandPacks/overlayCommandPack.js`
+- Wire pack into `tools/dev/devConsoleIntegration.js`
+- Keep integration sample-level (`MultiSystemDemoScene.js` remains the target reference)
+
+## API Boundary
+Allowed public calls:
+- `runtime.getState()`
+- `runtime.showOverlay()` / `runtime.hideOverlay()`
+- `runtime.panelRegistry.getOrderedPanels(includeDisabled)`
+- `runtime.panelRegistry.setPanelEnabled(panelId, enabled)`
+- `runtime.panelRegistry.getCount()`
+
+Not allowed:
+- private overlay host field access
+- direct panel object mutation
+- engine core changes
+
+## Commands Implemented
+- `overlay.help`
+- `overlay.list`
+- `overlay.status`
+- `overlay.show <panelId>`
+- `overlay.hide <panelId>`
+- `overlay.toggle <panelId>`
+- `overlay.showAll`
+- `overlay.hideAll`
+- `overlay.order`
+
+## Deterministic Output Rules
+- panel listings use ordered registry snapshots
+- list/order rows are stable and index-prefixed
+- status lines use key=value format
+- failures include explicit error code and available panel IDs when relevant
+
+## Safe Failure Rules
+- missing runtime/registry -> failed result with explicit code
+- missing/unknown panel ID -> `OVERLAY_PANEL_NOT_FOUND`
+- failed state set -> `OVERLAY_PANEL_SET_FAILED`
+
+## Validation Evidence
+- `node --check tools/dev/commandPacks/overlayCommandPack.js` passed
+- `node --check tools/dev/devConsoleIntegration.js` passed
+- sample command harness execution passed for:
+  - help/list/status/order
+  - show/hide/toggle
+  - showAll/hideAll
+  - invalid panel ID failure path
+
+## APPLY Guidance
+Apply scope stays surgical:
+- keep command logic isolated to Dev Console pack wiring
+- keep overlay interaction read/toggle-only through public APIs
+- keep behavior debug-only and sample-aligned
diff --git a/docs/pr/PLAN_PR_OVERLAY_OPERATOR_COMMANDS.md b/docs/pr/PLAN_PR_OVERLAY_OPERATOR_COMMANDS.md
@@ -0,0 +1,53 @@
+Toolbox Aid
+David Quesenberry
+04/05/2026
+PLAN_PR_OVERLAY_OPERATOR_COMMANDS.md
+
+# PLAN_PR_OVERLAY_OPERATOR_COMMANDS
+
+## Goal
+Define a sample-level, debug-only operator command surface for overlay panel control via Dev Console registry commands.
+
+## Workflow
+PLAN_PR -> BUILD_PR -> APPLY_PR
+
+## Scope
+In scope:
+- `overlay.*` command namespace and behavior contract
+- public overlay/registry API usage only
+- deterministic operator-readable command outputs
+- safe failure handling for missing/invalid panel IDs
+- sample-level validation target: `MultiSystemDemoScene.js`
+
+Out of scope:
+- engine core changes
+- production runtime command surfaces
+- direct console-to-overlay-internals coupling
+
+## Boundary Contract
+- Dev Console owns command/control.
+- Debug Overlay owns passive telemetry/HUD rendering.
+- Operator commands may query/toggle overlay panel state only through public runtime/registry APIs.
+
+## Required Command Set
+- `overlay.help`
+- `overlay.list`
+- `overlay.status`
+- `overlay.show <panelId>`
+- `overlay.hide <panelId>`
+- `overlay.toggle <panelId>`
+- `overlay.showAll`
+- `overlay.hideAll`
+- `overlay.order`
+
+## Output Contract
+- key-value and deterministic list rows
+- stable ordering for panel lists (`order`, then `id`)
+- explicit status/code for success and failure paths
+
+## Validation Targets
+- commands register under Dev Console command registry
+- all required commands execute
+- invalid panel IDs fail safely
+- outputs remain deterministic
+- no engine core changes
diff --git a/tools/dev/commandPacks/overlayCommandPack.js b/tools/dev/commandPacks/overlayCommandPack.js
diff --git a/tools/dev/devConsoleIntegration.js b/tools/dev/devConsoleIntegration.js

Original file line number	Diff line number	Diff line change
`@@ -1 +1 @@`
`1`		`-docs(debug): define overlay data provider contract and next-step execution path`
	`1`	`+BUILD_PR_OVERLAY_OPERATOR_COMMANDS: add debug-only overlay operator command contract and sample-level console integration using public overlay APIs only`