@khalidsaidi/skillrunner 0.1.2 → 0.1.3

package/dist/registry/skills/openai-cloudflare-deploy/upstream/references/zaraz/gotchas.md

@@ -0,0 +1,81 @@
+# Zaraz Gotchas
+
+## Events Not Firing
+
+**Check:**
+1. Tool enabled in dashboard (green dot)
+2. Trigger conditions met
+3. Consent granted for tool's purpose
+4. Tool credentials correct (GA4: `G-XXXXXXXXXX`, FB: numeric only)
+
+**Debug:**
+```javascript
+zaraz.debug = true;
+console.log('Tools:', zaraz.tools);
+console.log('Consent:', zaraz.consent.getAll());
+```
+
+## Consent Issues
+
+**Modal not showing:**
+```javascript
+// Clear consent cookie
+document.cookie = 'zaraz-consent=; expires=Thu, 01 Jan 1970 00:00:00 UTC; path=/;';
+location.reload();
+```
+
+**Tools firing before consent:** Map tool to consent purpose with "Do not load until consent granted".
+
+## SPA Tracking
+
+**Route changes not tracked:**
+1. Configure History Change trigger in dashboard
+2. Hash routing (`#/path`) requires manual tracking:
+```javascript
+window.addEventListener('hashchange', () => {
+  zaraz.track('pageview', { page_path: location.pathname + location.hash });
+});
+```
+
+**React fix:**
+```javascript
+const location = useLocation();
+useEffect(() => {
+  zaraz.track('pageview', { page_path: location.pathname });
+}, [location]); // Include dependency
+```
+
+## Performance
+
+**Slow page load:**
+- Audit tool count (50+ degrades performance)
+- Disable blocking triggers unless required
+- Reduce event payload size (<100KB)
+
+## Tool-Specific Issues
+
+| Tool | Issue | Fix |
+|------|-------|-----|
+| GA4 | Events not in real-time | Wait 5-10 min, use DebugView |
+| Facebook | Invalid Pixel ID | Use numeric only (no `fbpx_` prefix) |
+| Google Ads | Conversions not attributed | Include `send_to: 'AW-XXX/LABEL'` |
+
+## Data Layer
+
+- Properties persist per page only - set on each page load
+- Nested access: `{{client.__zarazTrack.user.plan}}`
+
+## Limits
+
+| Resource | Limit |
+|----------|-------|
+| Request size | 100KB |
+| Consent purposes | 20 |
+| API rate | 1000 req/sec |
+
+## When NOT to Use Zaraz
+
+- Server-to-server tracking (use Workers)
+- Real-time bidirectional communication
+- Binary data transmission
+- Authentication flows

package/dist/registry/skills/openai-cloudflare-deploy/upstream/references/zaraz/patterns.md

@@ -0,0 +1,74 @@
+# Zaraz Patterns
+
+## SPA Tracking
+
+**History Change Trigger (Recommended):** Configure in dashboard - no code needed, Zaraz auto-detects route changes.
+
+**Manual tracking (React/Vue/Next.js):**
+```javascript
+// On route change
+zaraz.track('pageview', { page_path: pathname, page_title: document.title });
+```
+
+## User Identification
+
+```javascript
+// Login
+zaraz.set({ userId: user.id, email: user.email, plan: user.plan });
+zaraz.track('login', { method: 'oauth' });
+
+// Logout - set to null (cannot clear)
+zaraz.set('userId', null);
+```
+
+## E-commerce Funnel
+
+| Event | Method |
+|-------|--------|
+| View | `zaraz.ecommerce('Product Viewed', { product_id, name, price })` |
+| Add to cart | `zaraz.ecommerce('Product Added', { product_id, quantity })` |
+| Checkout | `zaraz.ecommerce('Checkout Started', { cart_id, products: [...] })` |
+| Purchase | `zaraz.ecommerce('Order Completed', { order_id, total, products })` |
+
+## A/B Testing
+
+```javascript
+zaraz.set('experiment_checkout', variant);
+zaraz.track('experiment_viewed', { experiment_id: 'checkout', variant });
+// On conversion
+zaraz.track('experiment_conversion', { experiment_id, variant, value });
+```
+
+## Worker Integration
+
+**Context Enricher** - Modify context before tools execute:
+```typescript
+export default {
+  async fetch(request, env) {
+    const body = await request.json();
+    body.system.userRegion = request.cf?.region;
+    return Response.json(body);
+  }
+};
+```
+Configure: Zaraz > Settings > Context Enrichers
+
+**Worker Variables** - Compute dynamic values server-side, use as `{{worker.variable_name}}`.
+
+## GTM Migration
+
+| GTM | Zaraz |
+|-----|-------|
+| `dataLayer.push({event: 'purchase'})` | `zaraz.ecommerce('Order Completed', {...})` |
+| `{{Page URL}}` | `{{system.page.url}}` |
+| `{{Page Title}}` | `{{system.page.title}}` |
+| Page View trigger | Pageview trigger |
+| Click trigger | Click (selector: `*`) |
+
+## Best Practices
+
+1. Use dashboard triggers over inline code
+2. Enable History Change for SPAs (no manual code)
+3. Debug with `zaraz.debug = true`
+4. Implement consent early (GDPR/CCPA)
+5. Use Context Enrichers for sensitive/server data

package/dist/registry/skills/openai-develop-web-game/SKILL.md

@@ -0,0 +1,164 @@
+---
+name: openai-develop-web-game
+description: "Use when Codex is building or iterating on a web game (HTML/JS) and needs a reliable development + testing loop: implement small changes, run a Playwright-based test script with short input bursts and intentional pauses, inspect screenshots/text, and review console errors with render_game_to_text. (Imported from openai upstream skills)"
+version: "1.0.0"
+tags: ["openai", "upstream", "imported"]
+kind: knowledge
+risk: low
+availability: advanced
+docs:
+  source: "https://github.com/openai/skills/tree/main/skills/.curated/develop-web-game"
+---
+
+# openai-develop-web-game
+
+Imported upstream skill.
+
+- Provider source: https://github.com/openai/skills/tree/main/skills/.curated/develop-web-game
+- Original skill name: develop-web-game
+
+## Upstream Content
+
+# Develop Web Game
+
+Build games in small steps and validate every change. Treat each iteration as: implement → act → pause → observe → adjust.
+
+## Skill paths (set once)
+
+```bash
+export CODEX_HOME="${CODEX_HOME:-$HOME/.codex}"
+export WEB_GAME_CLIENT="$CODEX_HOME/skills/develop-web-game/scripts/web_game_playwright_client.js"
+export WEB_GAME_ACTIONS="$CODEX_HOME/skills/develop-web-game/references/action_payloads.json"
+```
+
+User-scoped skills install under `$CODEX_HOME/skills` (default: `~/.codex/skills`).
+
+## Workflow
+
+1. **Pick a goal.** Define a single feature or behavior to implement.
+2. **Implement small.** Make the smallest change that moves the game forward.
+3. **Ensure integration points.** Provide a single canvas and `window.render_game_to_text` so the test loop can read state.
+4. **Add `window.advanceTime(ms)`.** Strongly prefer a deterministic step hook so the Playwright script can advance frames reliably; without it, automated tests can be flaky.
+5. **Initialize progress.md.** If `progress.md` exists, read it first and confirm the original user prompt is recorded at the top (prefix with `Original prompt:`). Also note any TODOs and suggestions left by the previous agent. If missing, create it and write `Original prompt: <prompt>` at the top before appending updates.
+6. **Verify Playwright availability.** Ensure `playwright` is available (local dependency or global install). If unsure, check `npx` first.
+7. **Run the Playwright test script.** You must run `$WEB_GAME_CLIENT` after each meaningful change; do not invent a new client unless required.
+8. **Use the payload reference.** Base actions on `$WEB_GAME_ACTIONS` to avoid guessing keys.
+9. **Inspect state.** Capture screenshots and text state after each burst.
+10. **Inspect screenshots.** Open the latest screenshot, verify expected visuals, fix any issues, and rerun the script. Repeat until correct.
+11. **Verify controls and state (multi-step focus).** Exhaustively exercise all important interactions. For each, think through the full multi-step sequence it implies (cause → intermediate states → outcome) and verify the entire chain works end-to-end. Confirm `render_game_to_text` reflects the same state shown on screen. If anything is off, fix and rerun.
+    Examples of important interactions: move, jump, shoot/attack, interact/use, select/confirm/cancel in menus, pause/resume, restart, and any special abilities or puzzle actions defined by the request. Multi-step examples: shooting an enemy should reduce its health; when health reaches 0 it should disappear and update the score; collecting a key should unlock a door and allow level progression.
+12. **Check errors.** Review console errors and fix the first new issue before continuing.
+13. **Reset between scenarios.** Avoid cross-test state when validating distinct features.
+14. **Iterate with small deltas.** Change one variable at a time (frames, inputs, timing, positions), then repeat steps 7–13 until stable.
+
+Example command (actions required):
+```
+node "$WEB_GAME_CLIENT" --url http://localhost:5173 --actions-file "$WEB_GAME_ACTIONS" --click-selector "#start-btn" --iterations 3 --pause-ms 250
+```
+
+Example actions (inline JSON):
+```json
+{
+  "steps": [
+    { "buttons": ["left_mouse_button"], "frames": 2, "mouse_x": 120, "mouse_y": 80 },
+    { "buttons": [], "frames": 6 },
+    { "buttons": ["right"], "frames": 8 },
+    { "buttons": ["space"], "frames": 4 }
+  ]
+}
+```
+
+## Test Checklist
+
+Test any new features added for the request and any areas your logic changes could affect. Identify issues, fix them, and re-run the tests to confirm they’re resolved.
+
+Examples of things to test:
+- Primary movement/interaction inputs (e.g., move, jump, shoot, confirm/select).
+- Win/lose or success/fail transitions.
+- Score/health/resource changes.
+- Boundary conditions (collisions, walls, screen edges).
+- Menu/pause/start flow if present.
+- Any special actions tied to the request (powerups, combos, abilities, puzzles, timers).
+
+## Test Artifacts to Review
+
+- Latest screenshots from the Playwright run.
+- Latest `render_game_to_text` JSON output.
+- Console error logs (fix the first new error before continuing).
+You must actually open and visually inspect the latest screenshots after running the Playwright script, not just generate them. Ensure everything that should be visible on screen is actually visible. Go beyond the start screen and capture gameplay screenshots that cover all newly added features. Treat the screenshots as the source of truth; if something is missing, it is missing in the build. If you suspect a headless/WebGL capture issue, rerun the Playwright script in headed mode and re-check. Fix and rerun in a tight loop until the screenshots and text state look correct. Once fixes are verified, re-test all important interactions and controls, confirm they work, and ensure your changes did not introduce regressions. If they did, fix them and rerun everything in a loop until interactions, text state, and controls all work as expected. Be exhaustive in testing controls; broken games are not acceptable.
+
+## Core Game Guidelines
+
+### Canvas + Layout
+- Prefer a single canvas centered in the window.
+
+### Visuals
+- Keep on-screen text minimal; show controls on a start/menu screen rather than overlaying them during play.
+- Avoid overly dark scenes unless the design calls for it. Make key elements easy to see.
+- Draw the background on the canvas itself instead of relying on CSS backgrounds.
+
+### Text State Output (render_game_to_text)
+Expose a `window.render_game_to_text` function that returns a concise JSON string representing the current game state. The text should include enough information to play the game without visuals.
+
+Minimal pattern:
+```js
+function renderGameToText() {
+  const payload = {
+    mode: state.mode,
+    player: { x: state.player.x, y: state.player.y, r: state.player.r },
+    entities: state.entities.map((e) => ({ x: e.x, y: e.y, r: e.r })),
+    score: state.score,
+  };
+  return JSON.stringify(payload);
+}
+window.render_game_to_text = renderGameToText;
+```
+
+Keep the payload succinct and biased toward on-screen/interactive elements. Prefer current, visible entities over full history.
+Include a clear coordinate system note (origin and axis directions), and encode all player-relevant state: player position/velocity, active obstacles/enemies, collectibles, timers/cooldowns, score, and any mode/state flags needed to make correct decisions. Avoid large histories; only include what's currently relevant and visible.
+
+### Time Stepping Hook
+Provide a deterministic time-stepping hook so the Playwright client can advance the game in controlled increments. Expose `window.advanceTime(ms)` (or a thin wrapper that forwards to your game update loop) and have the game loop use it when present.
+The Playwright test script uses this hook to step frames deterministically during automated testing.
+
+Minimal pattern:
+```js
+window.advanceTime = (ms) => {
+  const steps = Math.max(1, Math.round(ms / (1000 / 60)));
+  for (let i = 0; i < steps; i++) update(1 / 60);
+  render();
+};
+```
+
+### Fullscreen Toggle
+- Use a single key (prefer `f`) to toggle fullscreen on/off.
+- Allow `Esc` to exit fullscreen.
+- When fullscreen toggles, resize the canvas/rendering so visuals and input mapping stay correct.
+
+## Progress Tracking
+
+Create a `progress.md` file if it doesn't exist, and append TODOs, notes, gotchas, and loose ends as you go so another agent can pick up seamlessly.
+If a `progress.md` file already exists, read it first, including the original user prompt at the top (you may be continuing another agent's work). Do not overwrite the original prompt; preserve it.
+Update `progress.md` after each meaningful chunk of work (feature added, bug found, test run, or decision made).
+At the end of your work, leave TODOs and suggestions for the next agent in `progress.md`.
+
+## Playwright Prerequisites
+
+- Prefer a local `playwright` dependency if the project already has it.
+- If unsure whether Playwright is available, check for `npx`:
+  ```
+  command -v npx >/dev/null 2>&1
+  ```
+- If `npx` is missing, install Node/npm and then install Playwright globally:
+  ```
+  npm install -g @playwright/mcp@latest
+  ```
+- Do not switch to `@playwright/test` unless explicitly asked; stick to the client script.
+
+## Scripts
+
+- `$WEB_GAME_CLIENT` (installed default: `$CODEX_HOME/skills/develop-web-game/scripts/web_game_playwright_client.js`) — Playwright-based action loop with virtual-time stepping, screenshot capture, and console error buffering. You must pass an action burst via `--actions-file`, `--actions-json`, or `--click`.
+
+## References
+
+- `$WEB_GAME_ACTIONS` (installed default: `$CODEX_HOME/skills/develop-web-game/references/action_payloads.json`) — example action payloads (keyboard + mouse, per-frame capture). Use these to build your burst.

package/dist/registry/skills/openai-develop-web-game/upstream/LICENSE.txt

@@ -0,0 +1,201 @@
+Apache License
+Version 2.0, January 2004
+http://www.apache.org/licenses/
+
+TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+1. Definitions.
+
+   "License" shall mean the terms and conditions for use, reproduction,
+   and distribution as defined by Sections 1 through 9 of this document.
+
+   "Licensor" shall mean the copyright owner or entity authorized by
+   the copyright owner that is granting the License.
+
+   "Legal Entity" shall mean the union of the acting entity and all
+   other entities that control, are controlled by, or are under common
+   control with that entity. For the purposes of this definition,
+   "control" means (i) the power, direct or indirect, to cause the
+   direction or management of such entity, whether by contract or
+   otherwise, or (ii) ownership of fifty percent (50%) or more of the
+   outstanding shares, or (iii) beneficial ownership of such entity.
+
+   "You" (or "Your") shall mean an individual or Legal Entity
+   exercising permissions granted by this License.
+
+   "Source" form shall mean the preferred form for making modifications,
+   including but not limited to software source code, documentation
+   source, and configuration files.
+
+   "Object" form shall mean any form resulting from mechanical
+   transformation or translation of a Source form, including but
+   not limited to compiled object code, generated documentation,
+   and conversions to other media types.
+
+   "Work" shall mean the work of authorship, whether in Source or
+   Object form, made available under the License, as indicated by a
+   copyright notice that is included in or attached to the work
+   (an example is provided in the Appendix below).
+
+   "Derivative Works" shall mean any work, whether in Source or Object
+   form, that is based on (or derived from) the Work and for which the
+   editorial revisions, annotations, elaborations, or other modifications
+   represent, as a whole, an original work of authorship. For the purposes
+   of this License, Derivative Works shall not include works that remain
+   separable from, or merely link (or bind by name) to the interfaces of,
+   the Work and Derivative Works thereof.
+
+   "Contribution" shall mean any work of authorship, including
+   the original version of the Work and any modifications or additions
+   to that Work or Derivative Works thereof, that is intentionally
+   submitted to Licensor for inclusion in the Work by the copyright owner
+   or by an individual or Legal Entity authorized to submit on behalf of
+   the copyright owner. For the purposes of this definition, "submitted"
+   means any form of electronic, verbal, or written communication sent
+   to the Licensor or its representatives, including but not limited to
+   communication on electronic mailing lists, source code control systems,
+   and issue tracking systems that are managed by, or on behalf of, the
+   Licensor for the purpose of discussing and improving the Work, but
+   excluding communication that is conspicuously marked or otherwise
+   designated in writing by the copyright owner as "Not a Contribution."
+
+   "Contributor" shall mean Licensor and any individual or Legal Entity
+   on behalf of whom a Contribution has been received by Licensor and
+   subsequently incorporated within the Work.
+
+2. Grant of Copyright License. Subject to the terms and conditions of
+   this License, each Contributor hereby grants to You a perpetual,
+   worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+   copyright license to reproduce, prepare Derivative Works of,
+   publicly display, publicly perform, sublicense, and distribute the
+   Work and such Derivative Works in Source or Object form.
+
+3. Grant of Patent License. Subject to the terms and conditions of
+   this License, each Contributor hereby grants to You a perpetual,
+   worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+   (except as stated in this section) patent license to make, have made,
+   use, offer to sell, sell, import, and otherwise transfer the Work,
+   where such license applies only to those patent claims licensable
+   by such Contributor that are necessarily infringed by their
+   Contribution(s) alone or by combination of their Contribution(s)
+   with the Work to which such Contribution(s) was submitted. If You
+   institute patent litigation against any entity (including a
+   cross-claim or counterclaim in a lawsuit) alleging that the Work
+   or a Contribution incorporated within the Work constitutes direct
+   or contributory patent infringement, then any patent licenses
+   granted to You under this License for that Work shall terminate
+   as of the date such litigation is filed.
+
+4. Redistribution. You may reproduce and distribute copies of the
+   Work or Derivative Works thereof in any medium, with or without
+   modifications, and in Source or Object form, provided that You
+   meet the following conditions:
+
+   (a) You must give any other recipients of the Work or
+       Derivative Works a copy of this License; and
+
+   (b) You must cause any modified files to carry prominent notices
+       stating that You changed the files; and
+
+   (c) You must retain, in the Source form of any Derivative Works
+       that You distribute, all copyright, patent, trademark, and
+       attribution notices from the Source form of the Work,
+       excluding those notices that do not pertain to any part of
+       the Derivative Works; and
+
+   (d) If the Work includes a "NOTICE" text file as part of its
+       distribution, then any Derivative Works that You distribute must
+       include a readable copy of the attribution notices contained
+       within such NOTICE file, excluding those notices that do not
+       pertain to any part of the Derivative Works, in at least one
+       of the following places: within a NOTICE text file distributed
+       as part of the Derivative Works; within the Source form or
+       documentation, if provided along with the Derivative Works; or,
+       within a display generated by the Derivative Works, if and
+       wherever such third-party notices normally appear. The contents
+       of the NOTICE file are for informational purposes only and
+       do not modify the License. You may add Your own attribution
+       notices within Derivative Works that You distribute, alongside
+       or as an addendum to the NOTICE text from the Work, provided
+       that such additional attribution notices cannot be construed
+       as modifying the License.
+
+   You may add Your own copyright statement to Your modifications and
+   may provide additional or different license terms and conditions
+   for use, reproduction, or distribution of Your modifications, or
+   for any such Derivative Works as a whole, provided Your use,
+   reproduction, and distribution of the Work otherwise complies with
+   the conditions stated in this License.
+
+5. Submission of Contributions. Unless You explicitly state otherwise,
+   any Contribution intentionally submitted for inclusion in the Work
+   by You to the Licensor shall be under the terms and conditions of
+   this License, without any additional terms or conditions.
+   Notwithstanding the above, nothing herein shall supersede or modify
+   the terms of any separate license agreement you may have executed
+   with Licensor regarding such Contributions.
+
+6. Trademarks. This License does not grant permission to use the trade
+   names, trademarks, service marks, or product names of the Licensor,
+   except as required for reasonable and customary use in describing the
+   origin of the Work and reproducing the content of the NOTICE file.
+
+7. Disclaimer of Warranty. Unless required by applicable law or
+   agreed to in writing, Licensor provides the Work (and each
+   Contributor provides its Contributions) on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+   implied, including, without limitation, any warranties or conditions
+   of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+   PARTICULAR PURPOSE. You are solely responsible for determining the
+   appropriateness of using or redistributing the Work and assume any
+   risks associated with Your exercise of permissions under this License.
+
+8. Limitation of Liability. In no event and under no legal theory,
+   whether in tort (including negligence), contract, or otherwise,
+   unless required by applicable law (such as deliberate and grossly
+   negligent acts) or agreed to in writing, shall any Contributor be
+   liable to You for damages, including any direct, indirect, special,
+   incidental, or consequential damages of any character arising as a
+   result of this License or out of the use or inability to use the
+   Work (including but not limited to damages for loss of goodwill,
+   work stoppage, computer failure or malfunction, or any and all
+   other commercial damages or losses), even if such Contributor
+   has been advised of the possibility of such damages.
+
+9. Accepting Warranty or Additional Liability. While redistributing
+   the Work or Derivative Works thereof, You may choose to offer,
+   and charge a fee for, acceptance of support, warranty, indemnity,
+   or other liability obligations and/or rights consistent with this
+   License. However, in accepting such obligations, You may act only
+   on Your own behalf and on Your sole responsibility, not on behalf of
+   any other Contributor, and only if You agree to indemnify,
+   defend, and hold each Contributor harmless for any liability
+   incurred by, or claims asserted against, such Contributor by reason
+   of your accepting any such warranty or additional liability.
+
+END OF TERMS AND CONDITIONS
+
+APPENDIX: How to apply the Apache License to your work.
+
+   To apply the Apache License to your work, attach the following
+   boilerplate notice, with the fields enclosed by brackets "[]"
+   replaced with your own identifying information. (Don\'t include
+   the brackets!)  The text should be enclosed in the appropriate
+   comment syntax for the file format. We also recommend that a
+   file or class name and description of purpose be included on the
+   same "printed page" as the copyright notice for easier
+   identification within third-party archives.
+
+Copyright [yyyy] [name of copyright owner]
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+    http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.

package/dist/registry/skills/openai-develop-web-game/upstream/SKILL.md

@@ -0,0 +1,149 @@
+---
+name: "develop-web-game"
+description: "Use when Codex is building or iterating on a web game (HTML/JS) and needs a reliable development + testing loop: implement small changes, run a Playwright-based test script with short input bursts and intentional pauses, inspect screenshots/text, and review console errors with render_game_to_text."
+---
+
+
+# Develop Web Game
+
+Build games in small steps and validate every change. Treat each iteration as: implement → act → pause → observe → adjust.
+
+## Skill paths (set once)
+
+```bash
+export CODEX_HOME="${CODEX_HOME:-$HOME/.codex}"
+export WEB_GAME_CLIENT="$CODEX_HOME/skills/develop-web-game/scripts/web_game_playwright_client.js"
+export WEB_GAME_ACTIONS="$CODEX_HOME/skills/develop-web-game/references/action_payloads.json"
+```
+
+User-scoped skills install under `$CODEX_HOME/skills` (default: `~/.codex/skills`).
+
+## Workflow
+
+1. **Pick a goal.** Define a single feature or behavior to implement.
+2. **Implement small.** Make the smallest change that moves the game forward.
+3. **Ensure integration points.** Provide a single canvas and `window.render_game_to_text` so the test loop can read state.
+4. **Add `window.advanceTime(ms)`.** Strongly prefer a deterministic step hook so the Playwright script can advance frames reliably; without it, automated tests can be flaky.
+5. **Initialize progress.md.** If `progress.md` exists, read it first and confirm the original user prompt is recorded at the top (prefix with `Original prompt:`). Also note any TODOs and suggestions left by the previous agent. If missing, create it and write `Original prompt: <prompt>` at the top before appending updates.
+6. **Verify Playwright availability.** Ensure `playwright` is available (local dependency or global install). If unsure, check `npx` first.
+7. **Run the Playwright test script.** You must run `$WEB_GAME_CLIENT` after each meaningful change; do not invent a new client unless required.
+8. **Use the payload reference.** Base actions on `$WEB_GAME_ACTIONS` to avoid guessing keys.
+9. **Inspect state.** Capture screenshots and text state after each burst.
+10. **Inspect screenshots.** Open the latest screenshot, verify expected visuals, fix any issues, and rerun the script. Repeat until correct.
+11. **Verify controls and state (multi-step focus).** Exhaustively exercise all important interactions. For each, think through the full multi-step sequence it implies (cause → intermediate states → outcome) and verify the entire chain works end-to-end. Confirm `render_game_to_text` reflects the same state shown on screen. If anything is off, fix and rerun.
+    Examples of important interactions: move, jump, shoot/attack, interact/use, select/confirm/cancel in menus, pause/resume, restart, and any special abilities or puzzle actions defined by the request. Multi-step examples: shooting an enemy should reduce its health; when health reaches 0 it should disappear and update the score; collecting a key should unlock a door and allow level progression.
+12. **Check errors.** Review console errors and fix the first new issue before continuing.
+13. **Reset between scenarios.** Avoid cross-test state when validating distinct features.
+14. **Iterate with small deltas.** Change one variable at a time (frames, inputs, timing, positions), then repeat steps 7–13 until stable.
+
+Example command (actions required):
+```
+node "$WEB_GAME_CLIENT" --url http://localhost:5173 --actions-file "$WEB_GAME_ACTIONS" --click-selector "#start-btn" --iterations 3 --pause-ms 250
+```
+
+Example actions (inline JSON):
+```json
+{
+  "steps": [
+    { "buttons": ["left_mouse_button"], "frames": 2, "mouse_x": 120, "mouse_y": 80 },
+    { "buttons": [], "frames": 6 },
+    { "buttons": ["right"], "frames": 8 },
+    { "buttons": ["space"], "frames": 4 }
+  ]
+}
+```
+
+## Test Checklist
+
+Test any new features added for the request and any areas your logic changes could affect. Identify issues, fix them, and re-run the tests to confirm they’re resolved.
+
+Examples of things to test:
+- Primary movement/interaction inputs (e.g., move, jump, shoot, confirm/select).
+- Win/lose or success/fail transitions.
+- Score/health/resource changes.
+- Boundary conditions (collisions, walls, screen edges).
+- Menu/pause/start flow if present.
+- Any special actions tied to the request (powerups, combos, abilities, puzzles, timers).
+
+## Test Artifacts to Review
+
+- Latest screenshots from the Playwright run.
+- Latest `render_game_to_text` JSON output.
+- Console error logs (fix the first new error before continuing).
+You must actually open and visually inspect the latest screenshots after running the Playwright script, not just generate them. Ensure everything that should be visible on screen is actually visible. Go beyond the start screen and capture gameplay screenshots that cover all newly added features. Treat the screenshots as the source of truth; if something is missing, it is missing in the build. If you suspect a headless/WebGL capture issue, rerun the Playwright script in headed mode and re-check. Fix and rerun in a tight loop until the screenshots and text state look correct. Once fixes are verified, re-test all important interactions and controls, confirm they work, and ensure your changes did not introduce regressions. If they did, fix them and rerun everything in a loop until interactions, text state, and controls all work as expected. Be exhaustive in testing controls; broken games are not acceptable.
+
+## Core Game Guidelines
+
+### Canvas + Layout
+- Prefer a single canvas centered in the window.
+
+### Visuals
+- Keep on-screen text minimal; show controls on a start/menu screen rather than overlaying them during play.
+- Avoid overly dark scenes unless the design calls for it. Make key elements easy to see.
+- Draw the background on the canvas itself instead of relying on CSS backgrounds.
+
+### Text State Output (render_game_to_text)
+Expose a `window.render_game_to_text` function that returns a concise JSON string representing the current game state. The text should include enough information to play the game without visuals.
+
+Minimal pattern:
+```js
+function renderGameToText() {
+  const payload = {
+    mode: state.mode,
+    player: { x: state.player.x, y: state.player.y, r: state.player.r },
+    entities: state.entities.map((e) => ({ x: e.x, y: e.y, r: e.r })),
+    score: state.score,
+  };
+  return JSON.stringify(payload);
+}
+window.render_game_to_text = renderGameToText;
+```
+
+Keep the payload succinct and biased toward on-screen/interactive elements. Prefer current, visible entities over full history.
+Include a clear coordinate system note (origin and axis directions), and encode all player-relevant state: player position/velocity, active obstacles/enemies, collectibles, timers/cooldowns, score, and any mode/state flags needed to make correct decisions. Avoid large histories; only include what's currently relevant and visible.
+
+### Time Stepping Hook
+Provide a deterministic time-stepping hook so the Playwright client can advance the game in controlled increments. Expose `window.advanceTime(ms)` (or a thin wrapper that forwards to your game update loop) and have the game loop use it when present.
+The Playwright test script uses this hook to step frames deterministically during automated testing.
+
+Minimal pattern:
+```js
+window.advanceTime = (ms) => {
+  const steps = Math.max(1, Math.round(ms / (1000 / 60)));
+  for (let i = 0; i < steps; i++) update(1 / 60);
+  render();
+};
+```
+
+### Fullscreen Toggle
+- Use a single key (prefer `f`) to toggle fullscreen on/off.
+- Allow `Esc` to exit fullscreen.
+- When fullscreen toggles, resize the canvas/rendering so visuals and input mapping stay correct.
+
+## Progress Tracking
+
+Create a `progress.md` file if it doesn't exist, and append TODOs, notes, gotchas, and loose ends as you go so another agent can pick up seamlessly.
+If a `progress.md` file already exists, read it first, including the original user prompt at the top (you may be continuing another agent's work). Do not overwrite the original prompt; preserve it.
+Update `progress.md` after each meaningful chunk of work (feature added, bug found, test run, or decision made).
+At the end of your work, leave TODOs and suggestions for the next agent in `progress.md`.
+
+## Playwright Prerequisites
+
+- Prefer a local `playwright` dependency if the project already has it.
+- If unsure whether Playwright is available, check for `npx`:
+  ```
+  command -v npx >/dev/null 2>&1
+  ```
+- If `npx` is missing, install Node/npm and then install Playwright globally:
+  ```
+  npm install -g @playwright/mcp@latest
+  ```
+- Do not switch to `@playwright/test` unless explicitly asked; stick to the client script.
+
+## Scripts
+
+- `$WEB_GAME_CLIENT` (installed default: `$CODEX_HOME/skills/develop-web-game/scripts/web_game_playwright_client.js`) — Playwright-based action loop with virtual-time stepping, screenshot capture, and console error buffering. You must pass an action burst via `--actions-file`, `--actions-json`, or `--click`.
+
+## References
+
+- `$WEB_GAME_ACTIONS` (installed default: `$CODEX_HOME/skills/develop-web-game/references/action_payloads.json`) — example action payloads (keyboard + mouse, per-frame capture). Use these to build your burst.