roadrunner-core

# RoadRunner Core

Foundation skill for all RoadRunner agent workflows. Manages the RoadRunner connection, project/scene/scenario lifecycle, and handle management from MATLAB. Produces the `rrApp` handle used by all downstream RoadRunner skills.

Execution: all MATLAB code runs via `evaluate_matlab_code` MCP tool. Never `matlab -batch`.

## When to Use

- Connecting to or launching RoadRunner from MATLAB
- Creating, opening, or saving projects, scenes, or scenarios
- Setting world origin or scene extents
- Checking RoadRunner status
- Closing RoadRunner safely
- Any downstream RoadRunner skill needs `rrApp` initialization

## When NOT to Use

- **RoadRunner is not installed** — this skill requires a working RoadRunner installation; it cannot install the product
- **MATLAB version below R2022a** — the `roadrunner` class and related APIs are not available in earlier releases
- **`rrApp` already exists and is valid** — re-running `rrCoreInitialize` is safe (it's idempotent) but unnecessary; prefer checking `exist('rrApp','var')` first to avoid the overhead
- **User has not provided installation or project paths** when first-time setup is needed — ask the user first, do not guess paths
- **RoadRunner is intentionally closed** — do not reconnect or relaunch without explicit user permission

---

## 1. How the Agent Uses This Skill

### First-time setup (once per machine — two-tier resolution)

`rrCoreInitialize` handles setup automatically using a two-tier approach:

| Tier | Condition | What happens |
|------|-----------|--------------|
| 1 | Settings valid + `roadrunner` class on path | Setup skipped — already configured |
| 2 | Agent has `installFolder` and `projectPath` variables | Programmatic setup: `addpath`, `savepath`, writes MATLAB settings. No GUI. |

**Just run `rrCoreInitialize`.** The script automatically:
1. Connects to a running instance (`roadrunner.connect()`)
2. If that fails, launches a new instance (`roadrunner()`) using saved settings
3. If not configured, errors with `PathsRequired` — then ask the user for `installFolder` and `projectPath`, set them, and re-run

Once setup succeeds, it persists forever (across MATLAB sessions). Never needed again.

**No GUI dialogs.** This skill never calls `roadrunnerSetup`. All configuration is done programmatically.

### First call in a session

1. **Add the skill scripts to the MATLAB path** (required before `rrCoreInitialize` can be found):
   ```matlab
   addpath("<absolute-path-to-this-skill>/scripts");
   ```
   Replace `<absolute-path-to-this-skill>` with the actual filesystem path to this skill's directory (the folder containing this SKILL.md file).
2. Run `rrCoreInitialize` → it handles everything: connects to a running instance, or launches one using saved settings, or errors with a clear message if not configured.
3. If it errors with `PathsRequired` → ask the user for `installFolder` and `projectPath`, set them as variables, re-run `rrCoreInitialize`.
4. Proceed with the user's request.

### Subsequent calls

1. Check `exist('rrApp','var')` — if missing, re-run `rrCoreInitialize`
2. Look up the operation in the Decision Logic table (Section 3)
3. Copy the exact pattern from `scripts/rrCoreCommands.m` under the matching `%%` heading
4. Substitute placeholders with actual values
5. Execute via `evaluate_matlab_code`

### Key principle

**Never improvise API calls.** Before every RoadRunner operation, **read the matching `%%` section** from `rrCoreCommands.m` and reproduce it exactly. Do not guess function names, argument syntax, or parameter orders from memory. This prevents hallucinated function names, missing guard rails, and forgotten handle invalidation.

If you are unsure of the correct syntax for any operation, **stop and read the pattern file** before attempting the call.

---

## 2. Files

| File | Role |
|------|------|
| `scripts/rrCoreInitialize.m` | **Runs directly.** Bootstraps path + connection + validation. |
| `scripts/rrCoreCommands.m` | **Pattern reference.** Agent reads `%%` section, substitutes placeholders, executes. |

### Deployment

On first use, the agent ensures the RoadRunner API is on the MATLAB path (one-time `savepath`). The scripts in this skill are pattern references — the agent reads them and reproduces the patterns via `evaluate_matlab_code`.

---

## 3. Decision Logic

| User Intent | Pattern (`%%` section) | Placeholders to substitute |
|-------------|------------------------|---------------------------|
| Connect / initialize | `INIT` | — |
| Connect without launching | `CONNECT_ONLY` | — (errors if no instance running) |
| Create a new project | `NEW_PROJECT` or `NEW_PROJECT_WITH_ASSETS` | `projectPath` — **ask user** whether to include base assets (asset library). Always `rrCoreInitialize` first (RoadRunner must be running with any project before `newProject` can be called). |
| Open an existing project | `OPEN_PROJECT` | `projectPath` |
| Save the project | `SAVE_PROJECT` | — |
| Create a new scene | `NEW_SCENE` | — |
| Open a scene | `OPEN_SCENE` | `sceneName` — if not found, use `LIST_SCENES` and present options |
| List available scenes | `LIST_SCENES` | — |
| Save the scene | `SAVE_SCENE` or `SAVE_SCENE_AS` | **Ask user**: "Save in place, or save with a new name?" If new name → use `SAVE_SCENE_AS` with `sceneName` |
| Create a new scenario | `NEW_SCENARIO` | — |
| Open a scenario | `OPEN_SCENARIO` | `scenarioName` — if not found, use `LIST_SCENARIOS` and present options |
| List available scenarios | `LIST_SCENARIOS` | — |
| Save the scenario | `SAVE_SCENARIO` | — |
| Set world origin | `CHANGE_WORLD_ORIGIN` | `lat`, `lon` |
| Set scene center and extents | `CHANGE_SCENE_BOUNDS` | `x`, `y`, `w`, `h` |
| Set scene center only | `CHANGE_SCENE_CENTER` | `x`, `y` |
| Set scene extents only | `CHANGE_SCENE_EXTENTS` | `w`, `h` |
| Clear world projection | `CLEAR_WORLD_PROJECTION` | — |
| Check status | `STATUS` | — |
| Close RoadRunner | `CLOSE` | — |

> **Available From:** `changeWorld