PAROCLAW v0.2 - ESP32-S3 LOCAL AI AGENT
=======================================

This is an upgrade of the supplied EmbodiedS3 v0.1.1 sketch.

FILES
-----
- Paroclaw_v0.2.ino: upgraded firmware sketch.
- Keep your existing config.h in the same sketch folder.
- Keep your existing SearchCandidate.h in the same sketch folder.

The two existing headers are intentionally not replaced because their
configuration and SearchCandidate structure are already part of your project.

WHAT CHANGED
------------
1. Project identity changed to Paroclaw v0.2.
2. Added rgb_off_then_set:
   - Turns the onboard GPIO48 NeoPixel off.
   - Waits for the requested interval (bounded to 0-5000 ms).
   - Sets the requested RGB color and brightness.
   - This action is synchronous; the agent does not process another prompt
     during the delay.
3. GPIO digital reads now distinguish input samples from output-pin readback.
   - An unknown pin is initialized as INPUT.
   - A PWM-configured pin is rejected for digital input measurement until the
     user explicitly configures it as an input.
   - Output readback is identified as output readback, not external input.
4. GPIO mode transitions detach LEDC PWM before switching to another mode.
5. ADC reads no longer silently take over an output/PWM pin. Configure that
   pin as input first. Internal pull modes are removed before an ADC sample.
6. Direct live hardware requests get one tool-call retry if the model answers
   without invoking a hardware tool. If no hardware tool is executed after
   the retry, the unverified response is suppressed.
7. Board status identifies Paroclaw v0.2.

PERSISTENT MEMORY COMPATIBILITY
-------------------------------
The existing LittleFS paths and JSONL record layout are unchanged:
- /agent_log.jsonl
- /agent_log_old.jsonl

The sketch still calls LittleFS.begin(false) and does not auto-format on boot.
Do NOT run /formatfs CONFIRM or /clearlogs CONFIRM during this upgrade.

REQUIRED EXISTING PROJECT CONFIGURATION
---------------------------------------
- ESP32-S3 board and the same working board/partition settings used by v0.1.1.
- Arduino-ESP32 core 3.x (the sketch uses the core 3.x LEDC API).
- ArduinoJson
- Adafruit NeoPixel
- Built-in ESP32 WiFi, HTTPClient and LittleFS libraries.
- Your existing config.h and SearchCandidate.h.

UPGRADE PROCEDURE
-----------------
1. Make a backup copy of the current v0.1.1 sketch and its config.h and
   SearchCandidate.h files.
2. Create a sketch folder named Paroclaw_v0.2.
3. Put Paroclaw_v0.2.ino, your existing config.h and your existing
   SearchCandidate.h in that folder.
4. Open the sketch and keep the exact ESP32-S3 board, flash size, flash mode,
   PSRAM setting and partition scheme that worked with v0.1.1.
5. Ensure any IDE option named "Erase All Flash Before Sketch Upload" is
   disabled. Upload the sketch without erasing the flash filesystem.
6. Open Serial Monitor at 115200 baud. Confirm that the startup banner says
   "Paroclaw v0.2" and that LittleFS mounts with the existing log statistics.

FIRST TESTS
-----------
A. Timed RGB sequence:
   "Turn the onboard RGB LED off for 2 seconds, then set it to red at full
   brightness."
   Expected tool: rgb_off_then_set
   Expected result: off_ms=2000, red=255, green=0, blue=0, brightness=100.

B. GPIO input:
   "Configure GPIO4 as input. Do not write to it."
   Connect GPIO4 to 3V3, then ask:
   "Read GPIO4 and report its current mode and digital state."
   Expected mode/input sample: input, HIGH (1).
   Move GPIO4 from 3V3 to GND and repeat. Expected: LOW (0).

C. Tool-call guard:
   Ask a direct live GPIO or RGB request. Confirm a matching [AGENT TOOL]
   line appears. If Gemma initially answers without a tool call, the firmware
   should print [AGENT GUARD] and request one retry. It must not report an
   unverified live state as a board measurement.

VALIDATION NOTE
---------------
This source was checked for balanced C/C++ delimiters and key upgrade
invariants. An Arduino/PlatformIO toolchain was not installed in the build
container, so this file has not been compiled here. Compile/upload with the
same working local toolchain and board settings before relying on it.
