Update documentation for GitHub Actions workflows

- Change reusable workflow reference from reusable-docker-build.yml to docker-build.yml
- Add `prepare` job for version resolution and define default version in `env`
- Update parameters to include `version_tag` and pass it to Dockerfile via `build_args`
- Clarify that images are only pushed to GHCR from the master branch

Author: hacker-cb

.cursor/rules/adding-new-images.mdc

@@ -50,10 +50,14 @@ Images published as: `ghcr.io/jethome-iot/jethome-dev-<image-name>`
 ## GitHub Actions Workflow
 
 Create `.github/workflows/<image-name>.yml`:
-- Use reusable workflow: `.github/workflows/reusable-docker-build.yml`
+- Use reusable workflow: `.github/workflows/docker-build.yml`
 - Set triggers for image directory and workflow file changes
-- Pass `image_name` and `context_path` parameters
-- Include manual trigger and monthly rebuild schedule
+- Define default version in `env` section
+- Add `prepare` job to resolve versions
+- Pass `image_name`, `context_path`, and `version_tag` parameters
+- Pass version to Dockerfile via `build_args`
+- Include manual trigger with required version input
+- Images only pushed to GHCR from master branch
 - Test locally with `act -j build -W .github/workflows/<image-name>.yml --dryrun`
 
 ## Testing

.cursor/rules/commit-conventions.mdc

@@ -18,6 +18,84 @@ Use clear, descriptive commit messages that explain **what** and **why**.
 Good: `Add new development image` with detailed list
 Bad: `Update files`, `Fix`, `WIP`, `changes`
 
+## Message Generation Guidelines
+
+When generating commit messages, analyze the actual changes:
+
+### Documentation-Only Changes
+
+If ONLY documentation files changed (README.md, .mdc files):
+
+```
+Update documentation for <feature/component>
+
+- Update <specific doc> to reflect <change>
+- Add <new information> to <doc>
+- Fix outdated <information> in <doc>
+```
+
+Example:
+```
+Update documentation for workflow changes
+
+- Update adding-new-images.mdc with prepare job pattern
+- Add PIO_VERSION to platformio README
+- Update project structure with scripts/ directory
+```
+
+### Code-Only Changes
+
+If ONLY code/workflow files changed:
+
+```
+<Action> <component/feature>
+
+- Detailed code change 1
+- Detailed code change 2
+```
+
+Example:
+```
+Add version tag parameter to workflows
+
+- Add version_tag to docker-build.yml
+- Implement prepare job for version resolution
+- Pass versions via build_args
+```
+
+### Mixed Changes (Code + Docs)
+
+If BOTH code AND documentation changed together:
+
+```
+<Action> <component/feature>
+
+Code changes:
+- Code change 1
+- Code change 2
+
+Documentation:
+- Doc update 1
+- Doc update 2
+```
+
+### Change Type Detection
+
+Analyze changed files to determine type:
+
+**Documentation files:**
+- `*.md` (README files)
+- `*.mdc` (Cursor rules)
+- Files in `.cursor/rules/`
+
+**Code files:**
+- `Dockerfile`
+- `*.yml` (workflows)
+- `*.sh` (scripts)
+- Source code files
+
+**Accurate classification is critical** - don't claim code changes if only docs changed!
+
 ## AI/Cursor Commit Policy
 
 **🚫 NEVER AUTO-COMMIT**

.cursor/rules/project-structure.mdc

@@ -9,11 +9,19 @@ Multi-image Docker project providing development environments for embedded syste
 
 ```
 jethome-dev/
+├── .github/
+│   └── workflows/             # GitHub Actions workflows
+│       ├── docker-build.yml   # Reusable Docker build workflow
+│       ├── esp-idf.yml        # ESP-IDF image workflow
+│       └── platformio.yml     # PlatformIO image workflow
 ├── images/
 │   └── <image-name>/          # Each image in its own directory
 │       ├── Dockerfile         # Image definition
 │       ├── README.md          # Detailed image documentation
 │       └── ...                # Supporting files
+├── scripts/
+│   ├── build.sh               # Local image build helper
+│   └── test-workflow.sh       # Workflow testing with act
 ├── .cursor/rules/             # Cursor AI rules
 ├── LICENSE                    # MIT License
 └── README.md                  # Root README (minimal, generic)

images/platformio/README.md

@@ -219,13 +219,15 @@ docker build -t jethome-dev-platformio .
 
 ```bash
 docker build \
+  --build-arg PIO_VERSION=6.1.18 \
   --build-arg ESP32_PLATFORM_VERSION=6.11.0 \
   --build-arg NATIVE_PLATFORM_VERSION=1.2.1 \
   --build-arg UNITY_VERSION=2.6.0 \
   -t jethome-dev-platformio .
 ```
 
 Available build arguments:
+- `PIO_VERSION` - PlatformIO Core version (default: 6.1.18)
 - `ESP32_PLATFORM_VERSION` - Espressif32 platform version (default: 6.11.0)
 - `NATIVE_PLATFORM_VERSION` - Native platform version (default: 1.2.1)
 - `UNITY_VERSION` - Unity test framework version (default: 2.6.0)
@@ -236,6 +238,7 @@ Available build arguments:
 | Component | Version | Notes |
 |-----------|---------|-------|
 | Base Image | Python 3.11 slim | Debian Bookworm |
+| PlatformIO Core | 6.1.18 | Latest stable release |
 | ESP32 Platform | 6.11.0 | Version 6.12.0 has compatibility issues |
 | Native Platform | 1.2.1 | For unit testing |
 | Unity Framework | 2.6.0 | Globally installed |