docs: add AI coding agent rules and skills

Author: Gui-FernandesBR

.agents/skills/add-component-extractor/SKILL.md

@@ -0,0 +1,52 @@
+---
+name: add-component-extractor
+description: Add or modify a rocket component extractor in the serialization pipeline (motor, fins, nose cone, parachute, transition, environment, flight, stored results, etc.). Use when a parameter is missing from parameters.json, when supporting a new OpenRocket feature, or when editing anything under rocketserializer/components/ or ork_extractor.py.
+---
+
+# Adding a component extractor
+
+The serializer builds `parameters.json` in `ork_extractor.ork_extractor()` by calling one
+`search_*` function per rocket concern from `rocketserializer/components/`. To add or extend
+a component, follow the existing pattern exactly.
+
+## Anatomy of a component module
+Each `components/<thing>.py`:
+- Starts with `import logging` and `logger = logging.getLogger(__name__)`.
+- Exposes `search_<thing>(bs, ...)` returning a **dict or list of dicts** (never prints;
+  logs instead).
+- Uses NumPy-style docstrings (Parameters / Returns).
+- Reads scalars from the BeautifulSoup tree `bs`; reads geometry/positions from the
+  `elements` map produced by `open_rocket_wrangler.process_elements_position` (which needs
+  the Java `ork` document). See `nose_cone.py` and `fins.py` for the `elements` pattern.
+
+## Wiring it into the pipeline
+In `ork_extractor.py`:
+1. Import your function at the top with the other `from .components.<x> import ...` lines.
+2. Call it through the local `_safe_search(func, default_ret, *args)` wrapper so a failure
+   logs and returns the default instead of aborting the whole extraction. Choose a sensible
+   default (`{}`, `[]`, or a minimal dict) matching the shape callers expect.
+3. Assign the result into `settings["<key>"]`. The top-level keys are a **contract** with
+   `nb_builder.py` and the acceptance golden files — don't rename existing keys casually.
+
+Current keys: `id`, `environment`, `rocket`, `nosecones`, `trapezoidal_fins`,
+`elliptical_fins`, `tails`, `parachutes`, `rail_buttons`, `motors`, `flight`,
+`stored_results` (plus `rocket.drag_curve` and `motors.thrust_source` which point to CSVs
+written into the output folder).
+
+## If the notebook must use the new value
+Add/adjust the matching `build_*` method in `nb_builder.NotebookBuilder` so the value flows
+into the generated RocketPy notebook. The builder reads only from `parameters.json`.
+
+## Validate the change
+1. `make format && make lint`
+2. Run the pipeline on an example that exercises the component:
+   `ork2json --filepath "examples/EPFL--BellaLui--2020/rocket.ork" --verbose`
+   and inspect the resulting `parameters.json`.
+3. `pytest tests/acceptance/test_ork_extractor.py -v`. Acceptance tests compare against
+   committed `examples/<name>/parameters.json`. If your change **intentionally** alters
+   output, regenerate those golden files and review the diff carefully before committing.
+4. Add unit coverage under `tests/unit/` when practical.
+
+## Remember the input limitations
+The pipeline assumes a single stage, single motor, and single nose cone, and English-only
+`.ork` files with at least one run simulation. Don't silently break these assumptions.

.agents/skills/openrocket-jpype-interop/SKILL.md

@@ -0,0 +1,55 @@
+---
+name: openrocket-jpype-interop
+description: Work with the OpenRocket Java library through JPype — start/stop the JVM, load .ork documents, traverse the rocket component tree, and read data from both the XML (BeautifulSoup) and the live Java object. Use when touching openrocket_runtime.py, open_rocket_wrangler.py, ork_extractor.py, the JVM/Java setup, or anything that calls into net.sf.openrocket / info.openrocket.
+---
+
+# OpenRocket ↔ JPype interop
+
+## The two-source model
+`ork_extractor(bs, filepath, output_folder, ork)` reads from **two sources
+simultaneously** — always know which one a given value comes from:
+
+- `bs` — a `BeautifulSoup` tree of the `.ork` XML (`_helpers.parse_ork_file`). Source of
+  the simulation **datapoints** and most numeric parameters. Access via `bs.find(...)`,
+  `bs.find_all("datapoint")`, and `bs.find("databranch").attrs["types"]` (the comma-joined
+  column labels).
+- `ork` — the **live Java OpenRocket document** (`OpenRocketSession.load_doc`). Source of
+  **geometry and component positions** that the XML doesn't expose cleanly. Reached via
+  `ork.getRocket()` and traversed in `components/open_rocket_wrangler.py`.
+
+When adding an extractor, prefer `bs` for scalar/sim data and only reach into `ork` when the
+value requires walking the component hierarchy.
+
+## The JVM lifecycle (read before changing session code)
+JPype is pinned **`jpype1<1.5`**, which **cannot restart a JVM in one process**. Consequences:
+
+- `OpenRocketSession.__exit__` must **not** call `jpype.shutdownJVM()`. It only disposes AWT
+  windows. The JVM is cleaned up by JPype's atexit hook.
+- Never open a second `OpenRocketSession` in a test. `tests/conftest.py` opens **one**
+  session at import time and caches every example's settings in `_cached_settings`.
+- To use the session: `with OpenRocketSession(jar_path, log_level="OFF") as s: doc = s.load_doc(path)`.
+
+## Package namespaces
+OpenRocket moved from `net.sf.openrocket` (legacy, ≤ ~22) to `info.openrocket` (modern).
+`OpenRocketSession._resolve_packages()` tries legacy first, then modern, returning
+`(core, swing)`. If you support a new jar and a symbol is missing, extend that method rather
+than hard-coding a namespace anywhere else.
+
+## Java version compatibility
+`ensure_java_compatibility(jar_path)` picks the minimum Java: OpenRocket 23+ → Java 17,
+else Java 8. On Windows it auto-discovers a JDK under `C:/Program Files/Java` (and Adoptium
+/ AdoptOpenJDK) and sets `JAVA_HOME`/`PATH`. On other OSes it only warns — the user must
+provide a compatible JVM. Jar version is parsed from the filename by `_jar_version_tuple`.
+
+## Traversing the component tree
+`open_rocket_wrangler.py` helpers: `is_sub_component(ork)` (depth > 1 from root),
+`parent_is_a_stage(ork)` (parent class is `Stage`/`AxialStage`), and
+`process_elements_position(...)` which builds the position map used by fins, nose cone,
+transitions, and rail buttons. Component Java classes are identified by
+`ork.getClass().getSimpleName()`.
+
+## Gotchas
+- Java calls raise `jpype.JException` (plus `AttributeError`/`TypeError`/`RuntimeError` when
+  internals change between versions). Catch these narrowly — see `_block_loader`.
+- The `.ork` file is a **zip** containing `rocket.ork` (XML). `extract_ork_from_zip` handles
+  both the zipped and already-extracted cases (it catches `BadZipFile`).

.agents/skills/python-conventions/SKILL.md

@@ -0,0 +1,40 @@
+---
+name: python-conventions
+description: Python style, tooling, and testing conventions for this repo — ruff/black formatting, pylint config, NumPy docstrings, logging, and the pytest layout (unit/integration/acceptance) with the single-JVM constraint. Use before writing or reviewing any Python change here so it passes CI on the first try.
+---
+
+# Python conventions
+
+## Formatting & linting (must pass CI)
+- **ruff** is the formatter and primary linter. Line length **88**, black-compatible.
+  - Format: `make format` = `ruff check --select I --fix` (import sort) + `ruff format .`
+  - Lint: `make ruff-lint` = `ruff check .`
+- **pylint** also runs: `make pylint` = `pylint examples/ rocketserializer/ tests/`. The
+  disabled checks are in `pyproject.toml` `[tool.pylint]` (e.g. missing docstrings,
+  too-many-locals/arguments, `raise-missing-from`, `fixme`). Don't re-enable them ad hoc.
+- CI (`.github/workflows/linter.yml`) runs `ruff format --check`, `ruff check`, and pylint
+  on Python 3.9. Run `make lint` locally first.
+- Supported Python: 3.8–3.12 (`requires-python = ">= 3.8"`). Don't use syntax newer than 3.8.
+
+## Docstrings & logging
+- **NumPy-style docstrings** with `Parameters` / `Returns` / `Raises` sections — match the
+  existing modules (`_helpers.py`, `ork_extractor.py`).
+- Every module defines `logger = logging.getLogger(__name__)`. Log instead of `print`.
+  User-facing CLI messages are prefixed with the command name, e.g. `[ork2json] ...`.
+- Public functions raise precise exceptions with actionable messages (`FileNotFoundError`,
+  `ValueError`); the CLI surfaces them.
+
+## Testing
+- Layout: `tests/unit/`, `tests/integration/`, `tests/acceptance/`.
+- Run: `make tests` (`pytest`); CI: `pytest tests/ -v --timeout=120` (the `--timeout` guards
+  against a hung JVM). One case: `pytest tests/acceptance/test_ork_extractor.py -k valetudo -v`.
+- **Single-JVM rule:** JPype (`<1.5`) can't restart a JVM in-process, so `tests/conftest.py`
+  opens exactly one `OpenRocketSession` and caches every example's settings as fixtures.
+  Never open another session in a test.
+- **Acceptance tests are golden-file comparisons** against `examples/<name>/parameters.json`.
+  Intentional output changes require regenerating and reviewing those files.
+
+## Dependencies
+Runtime deps are in `requirements.in` (consumed by `pyproject.toml` dynamic dependencies);
+dev tools in `requirements-dev.txt`. Add runtime deps to `requirements.in`, not directly to
+`pyproject.toml`.

.agents/skills/rocketpy-simulation/SKILL.md

@@ -0,0 +1,43 @@
+---
+name: rocketpy-simulation
+description: Understand how generated parameters.json maps onto the RocketPy API (Environment, SolidMotor/Motor, Rocket, Flight) and how nb_builder.py assembles a runnable RocketPy notebook. Use when editing nb_builder.py, changing what a component contributes to the notebook, debugging a generated simulation, or aligning output with a RocketPy version.
+---
+
+# RocketPy simulation mapping
+
+`rocketserializer` produces inputs for **RocketPy** (`rocketpy>=1.1.0`). The generated
+notebook (`nb_builder.NotebookBuilder`) reads `parameters.json` and constructs a standard
+RocketPy simulation. Keep the mapping below in mind when changing extraction or the builder.
+
+## The RocketPy objects the notebook builds
+The `build_*` methods in `NotebookBuilder` map settings sections onto RocketPy classes:
+
+- `build_environment` → `Environment` (latitude, longitude, elevation, date, atmospheric
+  model). Fed by `settings["environment"]` + `settings["flight"]`.
+- `build_motor` → a motor object (e.g. `SolidMotor`) using `settings["motors"]`, with
+  `thrust_source` pointing at the generated `thrust_source.csv`.
+- `build_rocket` → `Rocket` with mass/inertia/radius from `settings["rocket"]`, the
+  `power_off`/`power_on` drag from the generated `drag_curve.csv`, then aerodynamic surfaces
+  added via `add_nose`, `add_trapezoidal_fins` / `add_elliptical_fins`, `add_tail`, and
+  parachutes via `add_parachute`, plus rail buttons.
+- `build_flight` → `Flight` (rocket + environment + rail length + inclination + heading).
+- `build_compare_results` → compares RocketPy output against `settings["stored_results"]`
+  (the values OpenRocket itself computed), which is how a user sanity-checks the conversion.
+
+## Practical guidance
+- The builder is a **codegen** step: each method appends notebook cells (`nbf.v4`), so you
+  are writing Python *source strings* that must run under the pinned `rocketpy` version.
+  When you reference a RocketPy method/argument, verify it exists in that version's API
+  rather than assuming.
+- Coordinate systems and positions matter: RocketPy places surfaces relative to a reference
+  (nose tip / center of dry mass). The positions come from `open_rocket_wrangler` — if a
+  surface lands in the wrong place in the simulation, suspect the position map, not RocketPy.
+- `stored_results` are the ground truth from OpenRocket (apogee, max velocity, etc.). Use
+  them to validate: a good conversion makes the RocketPy `Flight` results land close to the
+  stored ones.
+
+## When aligning with RocketPy
+If a generated notebook fails to run, first reproduce with an example
+(`ork2notebook --filepath "examples/NDRT--Rocket--2020/rocket.ork"`) and open the notebook.
+Fix the offending `build_*` method's emitted code, not the extraction, unless the underlying
+parameter is genuinely wrong in `parameters.json`.

.claude/settings.json

@@ -0,0 +1,8 @@
+{
+  "permissions": {
+    "allow": [
+      "Bash(.venv/Scripts/python.exe -c \"import rocketserializer; print\\(''Import OK''\\)\")",
+      "Bash(java -version)"
+    ]
+  }
+}

.claude/skills/add-component-extractor/SKILL.md

@@ -0,0 +1,52 @@
+---
+name: add-component-extractor
+description: Add or modify a rocket component extractor in the serialization pipeline (motor, fins, nose cone, parachute, transition, environment, flight, stored results, etc.). Use when a parameter is missing from parameters.json, when supporting a new OpenRocket feature, or when editing anything under rocketserializer/components/ or ork_extractor.py.
+---
+
+# Adding a component extractor
+
+The serializer builds `parameters.json` in `ork_extractor.ork_extractor()` by calling one
+`search_*` function per rocket concern from `rocketserializer/components/`. To add or extend
+a component, follow the existing pattern exactly.
+
+## Anatomy of a component module
+Each `components/<thing>.py`:
+- Starts with `import logging` and `logger = logging.getLogger(__name__)`.
+- Exposes `search_<thing>(bs, ...)` returning a **dict or list of dicts** (never prints;
+  logs instead).
+- Uses NumPy-style docstrings (Parameters / Returns).
+- Reads scalars from the BeautifulSoup tree `bs`; reads geometry/positions from the
+  `elements` map produced by `open_rocket_wrangler.process_elements_position` (which needs
+  the Java `ork` document). See `nose_cone.py` and `fins.py` for the `elements` pattern.
+
+## Wiring it into the pipeline
+In `ork_extractor.py`:
+1. Import your function at the top with the other `from .components.<x> import ...` lines.
+2. Call it through the local `_safe_search(func, default_ret, *args)` wrapper so a failure
+   logs and returns the default instead of aborting the whole extraction. Choose a sensible
+   default (`{}`, `[]`, or a minimal dict) matching the shape callers expect.
+3. Assign the result into `settings["<key>"]`. The top-level keys are a **contract** with
+   `nb_builder.py` and the acceptance golden files — don't rename existing keys casually.
+
+Current keys: `id`, `environment`, `rocket`, `nosecones`, `trapezoidal_fins`,
+`elliptical_fins`, `tails`, `parachutes`, `rail_buttons`, `motors`, `flight`,
+`stored_results` (plus `rocket.drag_curve` and `motors.thrust_source` which point to CSVs
+written into the output folder).
+
+## If the notebook must use the new value
+Add/adjust the matching `build_*` method in `nb_builder.NotebookBuilder` so the value flows
+into the generated RocketPy notebook. The builder reads only from `parameters.json`.
+
+## Validate the change
+1. `make format && make lint`
+2. Run the pipeline on an example that exercises the component:
+   `ork2json --filepath "examples/EPFL--BellaLui--2020/rocket.ork" --verbose`
+   and inspect the resulting `parameters.json`.
+3. `pytest tests/acceptance/test_ork_extractor.py -v`. Acceptance tests compare against
+   committed `examples/<name>/parameters.json`. If your change **intentionally** alters
+   output, regenerate those golden files and review the diff carefully before committing.
+4. Add unit coverage under `tests/unit/` when practical.
+
+## Remember the input limitations
+The pipeline assumes a single stage, single motor, and single nose cone, and English-only
+`.ork` files with at least one run simulation. Don't silently break these assumptions.

.claude/skills/openrocket-jpype-interop/SKILL.md

@@ -0,0 +1,55 @@
+---
+name: openrocket-jpype-interop
+description: Work with the OpenRocket Java library through JPype — start/stop the JVM, load .ork documents, traverse the rocket component tree, and read data from both the XML (BeautifulSoup) and the live Java object. Use when touching openrocket_runtime.py, open_rocket_wrangler.py, ork_extractor.py, the JVM/Java setup, or anything that calls into net.sf.openrocket / info.openrocket.
+---
+
+# OpenRocket ↔ JPype interop
+
+## The two-source model
+`ork_extractor(bs, filepath, output_folder, ork)` reads from **two sources
+simultaneously** — always know which one a given value comes from:
+
+- `bs` — a `BeautifulSoup` tree of the `.ork` XML (`_helpers.parse_ork_file`). Source of
+  the simulation **datapoints** and most numeric parameters. Access via `bs.find(...)`,
+  `bs.find_all("datapoint")`, and `bs.find("databranch").attrs["types"]` (the comma-joined
+  column labels).
+- `ork` — the **live Java OpenRocket document** (`OpenRocketSession.load_doc`). Source of
+  **geometry and component positions** that the XML doesn't expose cleanly. Reached via
+  `ork.getRocket()` and traversed in `components/open_rocket_wrangler.py`.
+
+When adding an extractor, prefer `bs` for scalar/sim data and only reach into `ork` when the
+value requires walking the component hierarchy.
+
+## The JVM lifecycle (read before changing session code)
+JPype is pinned **`jpype1<1.5`**, which **cannot restart a JVM in one process**. Consequences:
+
+- `OpenRocketSession.__exit__` must **not** call `jpype.shutdownJVM()`. It only disposes AWT
+  windows. The JVM is cleaned up by JPype's atexit hook.
+- Never open a second `OpenRocketSession` in a test. `tests/conftest.py` opens **one**
+  session at import time and caches every example's settings in `_cached_settings`.
+- To use the session: `with OpenRocketSession(jar_path, log_level="OFF") as s: doc = s.load_doc(path)`.
+
+## Package namespaces
+OpenRocket moved from `net.sf.openrocket` (legacy, ≤ ~22) to `info.openrocket` (modern).
+`OpenRocketSession._resolve_packages()` tries legacy first, then modern, returning
+`(core, swing)`. If you support a new jar and a symbol is missing, extend that method rather
+than hard-coding a namespace anywhere else.
+
+## Java version compatibility
+`ensure_java_compatibility(jar_path)` picks the minimum Java: OpenRocket 23+ → Java 17,
+else Java 8. On Windows it auto-discovers a JDK under `C:/Program Files/Java` (and Adoptium
+/ AdoptOpenJDK) and sets `JAVA_HOME`/`PATH`. On other OSes it only warns — the user must
+provide a compatible JVM. Jar version is parsed from the filename by `_jar_version_tuple`.
+
+## Traversing the component tree
+`open_rocket_wrangler.py` helpers: `is_sub_component(ork)` (depth > 1 from root),
+`parent_is_a_stage(ork)` (parent class is `Stage`/`AxialStage`), and
+`process_elements_position(...)` which builds the position map used by fins, nose cone,
+transitions, and rail buttons. Component Java classes are identified by
+`ork.getClass().getSimpleName()`.
+
+## Gotchas
+- Java calls raise `jpype.JException` (plus `AttributeError`/`TypeError`/`RuntimeError` when
+  internals change between versions). Catch these narrowly — see `_block_loader`.
+- The `.ork` file is a **zip** containing `rocket.ork` (XML). `extract_ork_from_zip` handles
+  both the zipped and already-extracted cases (it catches `BadZipFile`).