a whole bunch of agent assisted updates to myrobotlab.

.cursor/rules/arduino-generated.mdc

@@ -0,0 +1,12 @@
+---
+description: Arduino Msg/VirtualMsg are generated — edit schema only
+globs: src/main/java/org/myrobotlab/arduino/Msg.java,src/main/java/org/myrobotlab/arduino/VirtualMsg.java,src/main/resources/resource/Arduino/generate/**
+alwaysApply: false
+---
+
+# Arduino protocol edits
+
+- `Msg.java` and `VirtualMsg.java` are **generated**. Do not patch message methods by hand.
+- Edit `src/main/resources/resource/Arduino/generate/arduinoMsgs.schema` (and templates here).
+- Regenerate with `org.myrobotlab.arduino.ArduinoMsgGenerator`.
+- Details: `doc/GENERATED.md`.

.cursor/rules/myrobotlab-agents.mdc

@@ -0,0 +1,15 @@
+---
+description: Core MyRobotLab agent orientation — read AGENTS.md, prefer service triple, respect Meta/Ivy deps
+alwaysApply: true
+---
+
+# MyRobotLab agent rules
+
+- Read `AGENTS.md` and `doc/agent/` before large changes.
+- Prefer fixing `Service` + `Config` + `Meta` + `resource/<Service>/` over editing `Runtime.java` / `Service.java`.
+- New services: follow `doc/agent/adding-a-service.md` (copy `_TemplateService*`, WebGui, logo, tests).
+- Runtime deps live in `*Meta.addDependency` (Ivy → `libraries/`). Sync `pom.xml` too — see `doc/agent/dependency-updates.md`.
+- Never hand-edit generated `arduino/Msg.java` or `VirtualMsg.java`; edit `arduinoMsgs.schema` and regenerate.
+- InMoov2 / ProgramAB may live in sibling repos under `resource/` — confirm location before editing.
+- Verify with `mvn test -Pagent-tests` and a focused `-Dtest=...` for the area changed.
+- Prefer typed `*Config` / interfaces for new APIs over string-only `invoke`.

.cursor/rules/runtime-service-hotspots.mdc

@@ -0,0 +1,12 @@
+---
+description: Minimize edits to Runtime/Service megaclass hotspots; use AGENT REGION map
+globs: src/main/java/org/myrobotlab/service/Runtime.java,src/main/java/org/myrobotlab/framework/Service.java
+alwaysApply: false
+---
+
+# Runtime / Service hotspots
+
+- Prefer fixing a specific service before changing these files.
+- Search `AGENT REGION` banners to jump to CREATE_START, REGISTRY, INSTALL, NETWORK, CONFIG_PLAN, MAIN_CLI (Runtime) or MESSAGING, INVOKE, PEERS, CONFIG, LIFECYCLE, STATUS (Service).
+- New process-level helpers belong under `org.myrobotlab.framework.runtime` (or existing Repo/Plan/MethodCache), with Runtime delegating — do not grow Runtime further when avoidable.
+- Map: `doc/agent/hotspot-map.md`.

.cursor/rules/service-meta-deps.mdc

@@ -0,0 +1,12 @@
+---
+description: Keep service Meta dependencies in sync with pom.xml
+globs: src/main/java/org/myrobotlab/service/meta/**/*.java,pom.xml
+alwaysApply: false
+---
+
+# Meta + Maven dependencies
+
+- Service runtime jars are declared with `addDependency(...)` in `*Meta` classes.
+- Mirror GAV (and classifiers/excludes) in root `pom.xml` (usually `provided` scope).
+- After bumps, clear stale `libraries/` if needed and run `mvn test -Dtest=org.myrobotlab.framework.DependencyTest`.
+- Full cookbook: `doc/agent/dependency-updates.md`.

.dockerignore

@@ -0,0 +1,25 @@
+# Build context exclusions — keep image builds small and deterministic
+target/
+libraries/
+data/
+resource/
+repo/
+dist/
+bin/
+build/
+.idea/
+.settings/
+.project
+.classpath
+.vscode/
+*.log
+*.mp4
+myrobotlab.jar
+**/node_modules/
+src/main/resources/resource/WebGui/react/
+.git/logs/
+.git/objects/
+agent-transcripts/
+terminals/
+**/.DS_Store
+**/Thumbs.db

.github/workflows/build.yml

@@ -15,11 +15,11 @@ jobs:
     steps:
       - uses: actions/checkout@v3
 
-      - name: Set up JDK 11
+      - name: Set up JDK 17
         uses: actions/setup-java@v3
         with:
-          java-version: "11"
-          distribution: "adopt"
+          java-version: "17"
+          distribution: "temurin"
           cache: "maven"
 
       - name: Install Missing Dependencies
@@ -117,7 +117,7 @@ jobs:
             * [JavaDocs](https://build.myrobotlab.org:8443/job/myrobotlab/job/develop/$build/artifact/target/site/apidocs/org/myrobotlab/service/package-summary.html)  
 
             ## Base Requirements
-            You will need **Java 11 or newer**. If you are only running MyRobotLab, you need the JRE (Java Runtime Environment).  
+            You will need **Java 17 or newer**. If you are only running MyRobotLab, you need the JRE (Java Runtime Environment).  
             If you are building from source, you will need the JDK (Java Development Kit). Oracle or OpenJDK will work.
 
             ${{ env.CHANGELOG }}

.github/workflows/pr-agent-tests.yml

@@ -0,0 +1,31 @@
+name: Agent / PR fast tests
+
+on:
+  pull_request:
+    branches:
+      - develop
+      - master
+  workflow_dispatch:
+
+jobs:
+  agent-tests:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up JDK 17
+        uses: actions/setup-java@v4
+        with:
+          java-version: "17"
+          distribution: "temurin"
+          cache: "maven"
+
+      - name: Fast agent test suite
+        run: mvn -B test -Pagent-tests
+
+      - name: Surefire reports
+        if: failure()
+        uses: actions/upload-artifact@v4
+        with:
+          name: surefire-reports
+          path: target/surefire-reports/

AGENTS.md

@@ -0,0 +1,169 @@
+# AGENTS.md — MyRobotLab for AI / agentic development
+
+This file is the orientation guide for automated agents (and humans) working in this repo.
+Read it before changing framework code, dependencies, Arduino protocol, or WebGui.
+
+More detail lives under [`doc/agent/`](doc/agent/).
+
+## Quick facts
+
+| Item | Value |
+|------|--------|
+| Language / JDK | Java 17 |
+| Build | Single-module Maven (`pom.xml`) |
+| Entry point | `org.myrobotlab.service.Runtime` |
+| Primary UI | AngularJS WebGui (`src/main/resources/resource/WebGui/`) |
+| Default branch | `develop` |
+| Runtime deps | Per-service `*Meta` + Ivy → `libraries/` (not Maven alone) |
+
+## Safe change surfaces (prefer these)
+
+1. **One service**: `ServiceX.java` + `ServiceXConfig.java` + `ServiceXMeta.java` + `resource/ServiceX/`
+2. **Service UI**: `resource/WebGui/app/service/js/ServiceXGui.js` (+ related HTML/views)
+3. **Tests**: `src/test/java/...` mirroring the package under test
+4. **Templates**: copy `_TemplateService*` when adding a new service — full steps in [`doc/agent/adding-a-service.md`](doc/agent/adding-a-service.md)
+
+## Hotspots (high regression risk — minimize edits)
+
+| File | Approx. size | Touch when… |
+|------|-------------:|-------------|
+| `service/Runtime.java` | ~5.4k lines | Process entry, registry, install, networking, config plans |
+| `framework/Service.java` | ~3k lines | Inbox/outbox, invoke, peers, lifecycle, status |
+| `codec/CodecUtils.java` | ~1.7k lines | JSON/YAML/Message serialization |
+| `arduino/Msg.java` | generated | **Do not edit** — see [Generated files](#generated-files) |
+
+See [`doc/agent/hotspot-map.md`](doc/agent/hotspot-map.md) for region navigation inside Runtime/Service.
+
+## Architecture (mental model)
+
+```
+Runtime.main / getInstance
+    → create/start services from CLI (-s) or YAML config (-c)
+    → each Service has Inbox/Outbox + MethodCache invoke
+    → MetaData (*Meta) describes deps/peers; Ivy installs into libraries/
+    → WebGui / Python / remote gateways speak Message JSON over WS/HTTP
+```
+
+Lifecycle details: [`doc/service-life-cycle.md`](doc/service-life-cycle.md).
+
+### Service triple (always keep in sync)
+
+```
+org.myrobotlab.service.Foo
+org.myrobotlab.service.config.FooConfig
+org.myrobotlab.service.meta.FooMeta
+src/main/resources/resource/Foo/   # scripts, yml samples, assets
+src/main/resources/resource/Foo.png  # 48×48 service logo (WebGui)
+```
+
+How to add one: [`doc/agent/adding-a-service.md`](doc/agent/adding-a-service.md).
+
+## Dual dependency system (critical)
+
+There are **two** dependency truths:
+
+1. **`pom.xml`** — compile / shade classpath. Most deps are `provided`.
+2. **`*Meta.addDependency(...)`** — runtime install via Ivy into `libraries/`.
+
+Fixing only `pom.xml` often leaves runtime broken (or the reverse).
+
+**Cookbook:** [`doc/agent/dependency-updates.md`](doc/agent/dependency-updates.md).
+
+## Generated files
+
+Do **not** hand-edit:
+
+| Generated | Edit instead | Generator |
+|-----------|--------------|-----------|
+| `src/main/java/org/myrobotlab/arduino/Msg.java` | `src/main/resources/resource/Arduino/generate/arduinoMsgs.schema` | `ArduinoMsgGenerator` |
+| `src/main/java/org/myrobotlab/arduino/VirtualMsg.java` | same schema + templates | `ArduinoMsgGenerator` |
+| Related Arduino C++ under `resource/Arduino/` from generator | schema / templates | `ArduinoMsgGenerator` |
+
+See [`doc/GENERATED.md`](doc/GENERATED.md).
+
+## Sibling repositories
+
+Not always present in this clone (often gitignored / separate):
+
+| Repo | Expected path for local WebGui/dev |
+|------|-------------------------------------|
+| InMoov2 | `src/main/resources/resource/InMoov2` |
+| ProgramAB | `src/main/resources/resource/ProgramAB` |
+
+Use `make_web_dev.bat` (Windows) to clone siblings when needed. Robot/chatbot bugs may live **outside** this repo.
+
+## Build / test / smoke
+
+```bash
+# Full build
+mvn clean install
+
+# Skip tests
+mvn clean install -DskipTests
+
+# Single test
+mvn test -Dtest=org.myrobotlab.framework.MethodCacheTest
+
+# Fast agent / PR suite (curated framework/codec tests; skips InMoov/install-heavy)
+mvn test -Pagent-tests
+
+# Run from Maven
+mvn exec:java -Dexec.mainClass=org.myrobotlab.service.Runtime -Dexec.args="-s webgui WebGui intro Intro python Python"
+
+# Packaged
+./myrobotlab.sh   # or myrobotlab.bat
+```
+
+**Dev smoke (healthy):** Runtime starts, WebGui listens on `http://localhost:8888`, no continuous install storm if `libraries/` already populated.
+
+VS Code launch: `.vscode/launch.json` → **Runtime** (`-s webgui WebGui intro Intro python Python -c dev`).
+
+Scripts: [`scripts/agent-smoke.ps1`](scripts/agent-smoke.ps1), [`scripts/agent-smoke.sh`](scripts/agent-smoke.sh).
+
+Docker: [`Dockerfile`](Dockerfile), [`doc/docker.md`](doc/docker.md) (full `--install` at image build, WebGui `:8888`, serial/video/GPU passthrough, Windows `usbipd-win` notes, InMoov `-c` config mounts).
+
+### Test conventions
+
+- Extend `org.myrobotlab.test.AbstractTest` for service/framework tests (virtual Runtime, resource path).
+- Prefer unit tests that do **not** require internet, cameras, or `installAll()`.
+- Many hardware/chaos tests are `@Ignore` — do not treat ignored tests as coverage.
+- Surefire excludes `**/integration/*` by default.
+
+## Typed API preference (new code)
+
+Prefer:
+
+- Typed `*Config` fields and `apply()` / getters-setters
+- Interfaces under `org.myrobotlab.service.interfaces`
+- `Runtime.getService(name, new StaticType<MyService>() {})` when type matters
+
+Avoid for **new** public surfaces:
+
+- Stringly `invoke("methodName", ...)` as the only API
+- Untyped `Object` bags where a Config or DTO fits
+
+Reflection invoke remains core for the message bus; keep typed seams at service boundaries so agents and IDEs can navigate.
+
+## Domain map
+
+Service categories / where to look: [`doc/agent/service-domain-map.md`](doc/agent/service-domain-map.md).
+
+## WebGui notes
+
+- Stack: AngularJS 1.x under `resource/WebGui/app/`
+- Per-service GUI: `*Gui.js` + views
+- Message bus client: `mrl.js`
+- React tree under `resource/WebGui/react` is experimental/ignored — do not assume it is the primary UI
+
+## Maven clean side effects
+
+`mvn clean` deletes `libraries/`, `data/`, and copied `resource/` trees (see `maven-clean-plugin` in `pom.xml`). After clean, the next run may re-download large native deps.
+
+## PR checklist for agents
+
+1. Touch the smallest surface that fixes the bug (service triple before Runtime/Service).
+2. If changing deps → follow dependency cookbook (Meta **and** pom sync).
+3. If changing Arduino protocol → edit schema, regenerate, never hand-patch `Msg.java`.
+4. Add or update a focused unit test when practical.
+5. Run `mvn test -Pagent-tests` (and the specific test for the area you changed).
+6. Do not commit secrets, local `libraries/`, or `data/` runtime state.

CONTRIBUTING.md

@@ -0,0 +1,30 @@
+# Contributing to MyRobotLab
+
+## Branching
+
+- Develop on branches from **`develop`**.
+- Open PRs against **`develop`**.
+- Prefer an issue number in the branch name when available.
+
+## For humans and agents
+
+Start with **[`AGENTS.md`](AGENTS.md)** — architecture, safe edit surfaces, dependency rules, generated files, and verify commands.
+
+Additional guides:
+
+- [`doc/agent/`](doc/agent/) — dependency cookbook, domain map, hotspot map
+- [`doc/agent/adding-a-service.md`](doc/agent/adding-a-service.md) — creating a new service (triple, WebGui, logo, tests)
+- [`doc/GENERATED.md`](doc/GENERATED.md) — do-not-edit artifacts
+- [`doc/service-life-cycle.md`](doc/service-life-cycle.md) — service lifecycle
+
+## Verify locally
+
+```bash
+mvn test -Pagent-tests
+# plus a focused test for your change:
+mvn test -Dtest=org.myrobotlab.service.YourServiceTest
+```
+
+## Code review
+
+Expect review on PRs to `develop`. Address feedback, then a maintainer merges and deletes the branch.