64kb cartridges, sdkconfig changes, new python tools for WiFi and Store settings, removed old scripts

.gitignore

@@ -71,10 +71,14 @@ vcpkg_installed/
 # test output & cache
 Testing/
 .cache/
+.pytest_cache/
 *.prg32
 
 # Local environment configuration
-prg32_env.h
+sdkconfig
+profiles/sdkconfig.defaults.local
+.vscode/c_cpp_properties.json
+.vscode/launch.json
 
 # Local Python tooling
 .venv/

.vscode/tasks.json

@@ -11,7 +11,7 @@
         "-D",
         "SDKCONFIG=build-esp32c6/sdkconfig",
         "-D",
-        "SDKCONFIG_DEFAULTS=sdkconfig.defaults",
+        "SDKCONFIG_DEFAULTS=profiles/sdkconfig.defaults",
         "set-target",
         "esp32c6"
       ],
@@ -27,7 +27,7 @@
         "-D",
         "SDKCONFIG=build-esp32c6/sdkconfig",
         "-D",
-        "SDKCONFIG_DEFAULTS=sdkconfig.defaults",
+        "SDKCONFIG_DEFAULTS=profiles/sdkconfig.defaults",
         "-D",
         "IDF_TARGET=esp32c6",
         "menuconfig"
@@ -44,7 +44,7 @@
         "-D",
         "SDKCONFIG=build-esp32c6/sdkconfig",
         "-D",
-        "SDKCONFIG_DEFAULTS=sdkconfig.defaults",
+        "SDKCONFIG_DEFAULTS=profiles/sdkconfig.defaults",
         "-D",
         "IDF_TARGET=esp32c6",
         "build"
@@ -62,7 +62,7 @@
         "-D",
         "SDKCONFIG=build-esp32c6/sdkconfig",
         "-D",
-        "SDKCONFIG_DEFAULTS=sdkconfig.defaults",
+        "SDKCONFIG_DEFAULTS=profiles/sdkconfig.defaults",
         "-D",
         "IDF_TARGET=esp32c6",
         "flash",
@@ -80,7 +80,7 @@
         "-D",
         "SDKCONFIG=build-qemu/sdkconfig",
         "-D",
-        "SDKCONFIG_DEFAULTS=sdkconfig.defaults.qemu",
+        "SDKCONFIG_DEFAULTS=profiles/sdkconfig.defaults;profiles/sdkconfig.defaults.qemu",
         "set-target",
         "esp32c3"
       ],
@@ -96,7 +96,7 @@
         "-D",
         "SDKCONFIG=build-qemu/sdkconfig",
         "-D",
-        "SDKCONFIG_DEFAULTS=sdkconfig.defaults.qemu",
+        "SDKCONFIG_DEFAULTS=profiles/sdkconfig.defaults;profiles/sdkconfig.defaults.qemu",
         "-D",
         "IDF_TARGET=esp32c3",
         "build"
@@ -114,7 +114,7 @@
         "-D",
         "SDKCONFIG=build-qemu/sdkconfig",
         "-D",
-        "SDKCONFIG_DEFAULTS=sdkconfig.defaults.qemu",
+        "SDKCONFIG_DEFAULTS=profiles/sdkconfig.defaults;profiles/sdkconfig.defaults.qemu",
         "-D",
         "IDF_TARGET=esp32c3",
         "qemu",
@@ -133,7 +133,7 @@
         "-D",
         "SDKCONFIG=build-qemu/sdkconfig",
         "-D",
-        "SDKCONFIG_DEFAULTS=sdkconfig.defaults.qemu",
+        "SDKCONFIG_DEFAULTS=profiles/sdkconfig.defaults;profiles/sdkconfig.defaults.qemu",
         "-D",
         "IDF_TARGET=esp32c3",
         "qemu",
@@ -153,7 +153,7 @@
         "-D",
         "SDKCONFIG=build-qemu/sdkconfig",
         "-D",
-        "SDKCONFIG_DEFAULTS=sdkconfig.defaults.qemu",
+        "SDKCONFIG_DEFAULTS=profiles/sdkconfig.defaults;profiles/sdkconfig.defaults.qemu",
         "-D",
         "IDF_TARGET=esp32c3",
         "gdb"
@@ -170,7 +170,7 @@
         "-D",
         "SDKCONFIG=build-esp32c6/sdkconfig",
         "-D",
-        "SDKCONFIG_DEFAULTS=sdkconfig.defaults",
+        "SDKCONFIG_DEFAULTS=profiles/sdkconfig.defaults",
         "-D",
         "IDF_TARGET=esp32c6",
         "fullclean"
@@ -278,4 +278,4 @@
       "default": "http://192.168.4.1"
     }
   ]
-}
+}

AGENTS.md

@@ -20,10 +20,17 @@ Before writing or modifying any code, you MUST complete these steps:
 
 ## [PHASE 2: VALIDATION RUNS]
 1. At the start of every session you must ask the user a question:
-"Would you like to validate my edits by building the prg32 framework or do you prefer to run the builds on your own?"
+"Would you like to validate my edits by allowing me to build the PRG32 framework or do you prefer to run the builds on your own?"
+The possible answers should include:
+- "Yes, please validate the edits by building the PRG32 framework.".
+- "No, I prefer to run the builds on my own.".
 
-2. If the answer to the builds is yes, you should then ask:
+2. IF AND ONLY IF the answer is yes, you should then ask:
 "For what architecture are you building for? ESP32C6 or QEMU?"
+The possible answers should include:
+- ESP32C6.
+- QEMU.
+- Both.
 
 ## [PHASE 3: EXECUTION & DOCUMENTATION]
 When modifying code, you are bound by these rules:
@@ -44,11 +51,22 @@ Run these exact commands to validate your work:
 git diff --check
 
 # 2. Run Python linting/tooling
+python3 -m compileall prg32 tests tools
 python3 -m prg32 doctor
-python3 -m py_compile python3 -m prg32
+python3 -m prg32 test
+
+# 3. Run CI Tests (from GitHub Actions)
+python3 -m prg32.esp32c6.ci_smoke_test
+python3 -m prg32 abi check
+cartridges/devicedemo/tests/check_source.sh
+cartridges/bachdemo/scripts/test.sh
+cartridges/poing/tests/run.sh
+cc -std=c11 -Wall -Wextra -Werror cartridges/blackjack/tests/test_rules.c cartridges/blackjack/blackjack_rules.c -o /tmp/prg32-blackjack-rules
+/tmp/prg32-blackjack-rules
+sha256sum --check cartridges/blackjack/SHA256SUMS
 ```
 
-If the user explicitly asked for you to do the builds after the edits, you should run one of these commands or both based on the architecture you are building on. 
+If the user explicitly asked for you to do the builds after the edits, you should run one of these commands or both based on the architecture the edits are targeting. 
 
 If you are working on ESP32c6, Build the physical firmware:
 ```bash
@@ -60,6 +78,6 @@ If you are working on QEMU, Build the QEMU firmware:
 python3 -m prg32 qemu build
 ```
 
-[PHASE 5: DOCUMENTATION EDITING]
-After being done with editing, you should modify all relevant documentation in docs/ and the repository structure.
-NEVER edit the README unless explicitly specified.
+## [PHASE 5: DOCUMENTATION EDITING]
+After being done with editing, you should modify all relevant documentation in docs/ and the [repository structure](docs/repository_structure.md).
+NEVER edit the [README](/README.md) unless explicitly specified.

CMakeLists.txt

@@ -16,6 +16,29 @@ if(NOT PRG32_FIRMWARE_VERSION)
 endif()
 set(PROJECT_VER "${PRG32_FIRMWARE_VERSION}")
 
+set(EXTRA_CONFIGS "")
+if(EXISTS "${CMAKE_CURRENT_LIST_DIR}/profiles/sdkconfig.defaults.local")
+    set(EXTRA_CONFIGS "${CMAKE_CURRENT_LIST_DIR}/profiles/sdkconfig.defaults.local")
+endif()
+
+if(NOT DEFINED SDKCONFIG_DEFAULTS AND NOT DEFINED ENV{SDKCONFIG_DEFAULTS})
+    if(EXISTS "${CMAKE_CURRENT_LIST_DIR}/sdkconfig.defaults")
+        set(SDKCONFIG_DEFAULTS "sdkconfig.defaults")
+    else()
+        set(SDKCONFIG_DEFAULTS "profiles/sdkconfig.defaults")
+    endif()
+elseif(DEFINED SDKCONFIG_DEFAULTS AND SDKCONFIG_DEFAULTS STREQUAL "sdkconfig.defaults" AND NOT EXISTS "${CMAKE_CURRENT_LIST_DIR}/sdkconfig.defaults")
+    set(SDKCONFIG_DEFAULTS "profiles/sdkconfig.defaults")
+endif()
+
+if(EXTRA_CONFIGS)
+    if(DEFINED ENV{SDKCONFIG_DEFAULTS})
+        set(SDKCONFIG_DEFAULTS "$ENV{SDKCONFIG_DEFAULTS};${EXTRA_CONFIGS}")
+    else()
+        set(SDKCONFIG_DEFAULTS "${SDKCONFIG_DEFAULTS};${EXTRA_CONFIGS}")
+    endif()
+endif()
+
 include($ENV{IDF_PATH}/tools/cmake/project.cmake)
 project(PRG32)
 

CONTRIBUTING.md

@@ -44,80 +44,23 @@ Reflection:
 - What would you improve next?
 ```
 
-## Local Setup
-
-Recommended setup:
-
-1. Open `PRG32.code-workspace` in VS Code.
-2. Install the recommended extensions.
-3. Install and source ESP-IDF for ESP32-C3 and ESP32-C6.
-4. Use QEMU for early graphics/debugging work.
-5. Use the ESP32-C6 board for final hardware validation.
-
-ESP-IDF commands:
-
-```bash
-idf.py set-target esp32c6
-idf.py build
-idf.py flash monitor
-```
-
-QEMU commands:
-
-```bash
-idf.py -B build-qemu -D SDKCONFIG_DEFAULTS=sdkconfig.defaults.qemu set-target esp32c3
-idf.py -B build-qemu -D SDKCONFIG_DEFAULTS=sdkconfig.defaults.qemu build
-idf.py -B build-qemu -D SDKCONFIG_DEFAULTS=sdkconfig.defaults.qemu qemu --graphics monitor
-```
-
-PlatformIO users can open the repository root and use the `prg32-esp32c6`
-environment for physical board builds.
-
 ## Validation Checklist
 
 Run these checks before opening a pull request:
 
 ```bash
-git diff --check
-PYTHONPYCACHEPREFIX=/tmp/prg32-pycache python3 -m py_compile \
-  python3 -m prg32 \
-  tools/prg32_metrics_paper.py
-PYTHONPYCACHEPREFIX=/tmp/prg32-pycache python3 -m unittest discover -s tests
-python3 -m prg32 doctor --host-only
-```
-
-When ESP-IDF is available, also run:
-
-```bash
-idf.py build
-idf.py -B build-qemu -D SDKCONFIG_DEFAULTS=sdkconfig.defaults.qemu build
-```
-
-For end-to-end QEMU cartridge testing:
-
-```bash
-./scripts/smoke_test.sh
+python3 -m compileall prg32 tests tools
+python3 -m prg32 doctor
+python3 -m prg32 test
 ```
 
-Changes under `cartridges/blackjack` or `cartridges/devicedemo` must also pass
-their local checks and package scripts. GitHub Actions repeats these commands
-and uploads both architecture variants plus each Cartridge Store bundle:
+Then verify that the project is building correctly:
 
 ```bash
-cc -std=c11 -Wall -Wextra -Werror \
-  cartridges/blackjack/tests/test_rules.c \
-  cartridges/blackjack/blackjack_rules.c \
-  -o /tmp/prg32-blackjack-rules
-/tmp/prg32-blackjack-rules
-cartridges/devicedemo/tests/check_source.sh
-cartridges/blackjack/build.sh
-PRG32_REPO="$PWD" PRG32_ARCHITECTURE=esp32c6 cartridges/devicedemo/scripts/build.sh
-PRG32_REPO="$PWD" PRG32_ARCHITECTURE=qemu cartridges/devicedemo/scripts/build.sh
-PRG32_REPO="$PWD" cartridges/devicedemo/scripts/pack-store-bundle.sh
+python3 -m prg32 qemu build-and-run
+python3 -m prg32 esp32c6 build-and-flash
 ```
 
-If a tool is missing, write that clearly in the pull request. Do not claim a
-firmware or QEMU build passed unless it actually ran.
 
 ## Coding Guidelines
 
@@ -128,9 +71,7 @@ firmware or QEMU build passed unless it actually ran.
   changes the default firmware behavior.
 - Keep example games in `examples/games`; do not move them into the default app.
 - Keep focused rendering demonstrations in `examples/features`.
-- Do not reintroduce legacy `urg32` paths or symbols.
-- Keep generated files, local databases, build outputs, and `.prg32` cartridges
-  out of commits.
+- Keep generated files, local databases, build outputs, and `.prg32` cartridges out of commits.
 - Keep docs in sync when commands, paths, APIs, examples, or lab flows change.
 
 ## Assembly Guidelines