[Docs] Add Simulator MCP and real-device workflows to the generated Codename One agent skill

[jsfan3]

Summary

Please include the recently added MCP and on-device development workflows for both Android and iOS in the Codename One authoring skill shipped with new Java 17 projects, and keep the web Initializr and Maven archetype outputs in parity.

These features are especially valuable to coding agents, but an agent that only reads the files generated with a new project currently cannot discover them.

Relevant official material already exists:

• Skills, Java 17, And Theme Accents explains that generated Java 17 projects provide AGENTS.md and a vendor-neutral authoring skill.
• On-Device AI and MCP on Every Port explains semantic UI inspection and control over a guarded loopback MCP server.
• MCP Headless API documents the Simulator menu, built-in UI tools, screenshots, host registration, device support, and release-build guard.
• On-Device Debugging And JUnit 5, On-Device Debugging (Android), and On-Device Debugging (iOS) document the new Maven/JDWP workflows on both mobile platforms.

Current gap

I checked both:

1. A clean Java 17 project generated with com.codenameone:cn1app-archetype:7.0.267.
2. The current canonical skill on master at commit ac826b1.

Across the 35 canonical skill files, searches for the following terms produce no matches:

MCP
ui_snapshot
ui_activate
startSocketServer
loopback
adb forward
android-on-device-debugging
ios-on-device-debugging
onDeviceDebug

The generated references/debugging.md only describes attaching jdb to the JavaSE Simulator. build-and-run.md and testing-and-screenshots.md do not describe the newer Android or iOS on-device Maven goals, device-side MCP, or platform-specific device connectivity.

There is also a discovery/parity issue:

• The current web Initializr generator creates AGENTS.md, .agent-skills/codename-one/, and a Claude stub.
• The Maven archetype currently copies the canonical bundle only to .claude/skills/codename-one/; see its resource configuration. A project generated only with Maven therefore has no root AGENTS.md pointer and no vendor-neutral .agent-skills/ copy.

That makes the workflow harder to discover for Codex and other agents even before considering the missing content.

Practical verification

I verified the JavaSE and Android capabilities end to end with CN1 7.0.267 rather than relying only on the documentation. I did not have an iOS target available in this test environment, so the iOS request below is based on the current official Codename One documentation and asks for platform parity; it is not presented as a completed iOS test.

JavaSE Simulator

• Started a project with mvn -pl common cn1:run and exposed MCP on loopback port 8765.
• Completed the MCP JSON-RPC handshake.
• Listed the built-in tools: ui_snapshot, ui_perform_action, ui_activate, ui_set_text, and ui_find.
• Retrieved the semantic tree, found buttons by label, opened the side menu, activated a command, inspected the resulting modal dialog, and closed it.

Real Android device over USB

• Built a debuggable APK and ran cn1:android-on-device-debugging.
• The goal selected adb from the Android SDK, installed and launched the APK, forwarded JDWP to localhost:5005, and streamed PID-filtered logcat.
• Started the CN1 MCP socket server in the debug app and ran:

adb forward tcp:8765 tcp:8765

• Connected to the device-side MCP server from the development machine, retrieved the semantic UI tree, activated Hello World, opened the hamburger menu, activated Hello Command, and verified the dialog state.

This is precisely the kind of stable, semantic interaction an agent should prefer over guessed screen coordinates.

Relevant versions

• Codename One framework, Maven plugin, and archetype: 7.0.267
• Canonical skill audited on master: ac826b1df873e52f3965928c21c22f17cb1d303e
• JDK: OpenJDK 17.0.20
• Maven: 3.8.7
• Development host: Linux x86_64
• Physical target: Android 11 over authorized USB ADB
• iOS target: not available for this practical test; current official iOS workflow audited from the developer guide and generated Maven/IDE configuration

Requested additions

1. Add an MCP reference to the generated skill

For example, add references/mcp.md and route agents to it from SKILL.md. It should cover:

• Simulator menu workflow: MCP → Expose This Tool To Agents, Install in MCP Hosts, detection/removal, restart requirement, and the menu's default port 8765.
• The built-in UI tools and screenshot resource.
• Using semantic identifiers/labels and refreshing the snapshot after state changes.
• Programmatic startup with MCP.startSocketServer(port), guarded by Display.isDebuggableBuild().
• Device attachment through each platform's supported forwarding mechanism: adb forward tcp:<port> tcp:<port> on Android, plus explicit instructions for the native iOS Simulator and a physical iPhone.
• The security model: loopback is not authentication, release builds are blocked by default, and agents can inspect and drive the app once connected.
• Cleanup: stop the server and remove port forwards when the session ends.

2. Add real-device Android and iOS references

For example, add a shared references/on-device-debugging.md with Android and iOS sections (or two platform-specific references), then route agents to the correct section from SKILL.md.

Android

Document the complete CLI-first flow:

codename1.arg.android.onDeviceDebug=true

# Cloud debug APK
mvn cn1:buildAndroidOnDeviceDebug

# Or fully local
mvn cn1:buildAndroidGradleProject
cd android/target/*-android-source
./gradlew assembleDebug
cd -

# Install, launch, forward JDWP, and stream logcat
mvn cn1:android-on-device-debugging

The Android section should mention ANDROID_HOME / ANDROID_SDK_ROOT, USB authorization, APK autodetection, -Dcn1.android.onDeviceDebug.apk=..., deviceSerial, wireless ADB, skipInstall, and waitForAttach=false for sessions that must launch immediately (for example, to start MCP before attaching a debugger).

iOS

Document the equivalent CLI-first workflow for both the native iOS Simulator and a physical iPhone, including the generated build hints:

codename1.arg.ios.onDeviceDebug=true
codename1.arg.ios.onDeviceDebug.proxyHost=127.0.0.1
codename1.arg.ios.onDeviceDebug.proxyPort=55333
codename1.arg.ios.onDeviceDebug.waitForAttach=true

The iOS section should explain that proxyHost remains 127.0.0.1 for the native iOS Simulator but must be the development machine's reachable LAN address for a physical iPhone. It should cover:

# Cloud debug build for a physical device
mvn cn1:buildIosOnDeviceDebug

# Or a local Xcode project (requires macOS/Xcode)
mvn cn1:buildIosXcodeProject

# Start the CN1 device-to-JDWP proxy
mvn cn1:ios-on-device-debugging

# Attach a CLI debugger; IDEs use the same JDWP endpoint
jdb -attach localhost:8000

Please describe the two proxy ports unambiguously: the iOS app connects to the development-machine proxy on port 55333, while the IDE or jdb attaches to localhost:8000.

The same reference should explain how to expose device-side CN1 MCP on iOS. In particular, it should give exact supported connection/forwarding steps for:

• the native iOS Simulator, where the app and development host can share loopback;
• a physical iPhone, including the required Apple/libimobiledevice tooling or network route;
• starting MCP.startSocketServer(port) only in a development build and removing the forwarding route after the session.

3. Make generated-project discovery consistent

For Java 17 projects generated by either path, please generate the same structure:

AGENTS.md
.agent-skills/codename-one/...
.claude/skills/codename-one/SKILL.md   # thin compatibility stub

Both the web Initializr and mvn archetype:generate should expose equivalent, discoverable content through the vendor-neutral path and root pointer.

Acceptance criteria

• A fresh Java 17 project from both the web Initializr and Maven archetype gives a generic agent a root-level pointer to the same Codename One skill.
• By reading only generated project files, the agent can discover how to expose and drive the Simulator through MCP.
• The generated guidance is sufficient to build/install/launch a debuggable Android APK from the command line, attach JDWP/logcat, and connect to device-side MCP through ADB forwarding.
• The generated guidance is sufficient to build and run an on-device-debug iOS app through either the cloud/physical-device path or the local Xcode/iOS-Simulator path, start the CN1 debug proxy, attach an IDE or jdb to port 8000, and connect an agent to device-side MCP using the documented iOS route.
• The release-build security guard and loopback security limitations are explicit.

Why this matters

The new MCP and on-device Maven features remove the two largest sources of fragility in agent-assisted mobile debugging on Android and iOS: guessed UI coordinates and manual device/IDE orchestration. They were added after the first version of the generated authoring skill, so this appears to be documentation drift rather than a missing runtime capability. Updating the generated skill would make these capabilities available automatically in exactly the environment where they are most useful.

Report check

• I checked that the referenced pages and generated files are part of the current Maven-based workflow rather than an explicitly archived guide.