RAVEN semantic planner + geometric exploration planner as modules (full_raven, full_exploration stacks)

.agents/skills/create-module/SKILL.md

@@ -101,6 +101,27 @@ is remapping other modules' topics or overriding canonical names in module launc
 files: in a conventional stack, including the module must require **zero** remaps,
 so only deviations appear in stack files.)
 
+## Heavy dependencies: overlay layer vs sidecar container
+
+Two patterns exist for deps that do not belong in the trunk robot image:
+
+- **Overlay layer** (`dockerfile: Dockerfile.module`, tier 2) — the module's
+  deps are built ON TOP of the robot image and its nodes run in the robot
+  container (asm_macvo: TensorRT + weights). Right when the module's nodes must
+  share the robot's process space/ROS distro and the deps are compatible with
+  the robot image's Ubuntu/Python.
+- **Sidecar container** (`compose: <fragment>.yaml` with its own `build:`) —
+  a second container next to the robot on `airstack_network`, same
+  `ROS_DOMAIN_ID`, talking DDS (asm_raven: RayFronts on Ubuntu 22.04 / ROS 2
+  Humble / torch cu130 / patched OpenVDB — incompatible with the Jazzy robot
+  image). The overlay absolutizes the fragment's `build.context`,
+  `build.dockerfile`, `env_file` and bind sources; `airstack up` builds the
+  image on first run. Keep a thin robot-side colcon package (`<name>_bridge`)
+  that owns the canonical launch file and relays the sidecar's module-private
+  topics onto canonical names — the launch-arg interface must still exist on
+  the robot side. Cross-distro DDS works for unchanged message types; note it
+  in the README.
+
 ## Steps (by hand, until `airstack module create` lands)
 
 1. Create the repo with the anatomy above; write `module.yaml` first.

.env

@@ -12,7 +12,7 @@ PROJECT_NAME="airstack"
 # If you've run ./airstack.sh setup, then this will auto-generate from the git commit hash every time a change is made 
 # to a Dockerfile or docker-compose.yaml file. Otherwise this can also be set explicitly to make a release version.
 # auto-generated from git commit hash
-VERSION="0.21.0-dev.13"
+VERSION="0.21.0-dev.14"
 # Image-tag discriminator ONLY (appears in the image tag suffix, e.g. ..._robot-x86-64_dev).
 # No Dockerfile consumes it: "prebuilt" does NOT bake the built ros_ws into the image today —
 # a real prebuilt (workspace-baked) stage is future work. Keep "dev" (mounted code, built live).

.vscode/c_cpp_properties.json

@@ -11,7 +11,6 @@
         "/home/andrew/Development/AirStack/robot/ros_ws/src/behavior/behavior_executive/include/**",
         "/home/andrew/Development/AirStack/robot/ros_ws/src/behavior/behavior_tree/include/**",
         "/home/andrew/Development/AirStack/robot/ros_ws/src/global/planners/ensemble_planner/include/**",
-        "/home/andrew/Development/AirStack/robot/ros_ws/src/global/planners/exploration/include/**",
         "/home/andrew/Development/AirStack/robot/ros_ws/src/global/planners/random_walk/include/**",
         "/home/andrew/Development/AirStack/robot/ros_ws/src/global/world_models/vdb_mapping/include/**",
         "/home/andrew/Development/AirStack/robot/ros_ws/src/global/world_models/vdb_mapping_ros2/vdb_mapping_ros2/include/**",

docs/development/stacks.md

@@ -30,6 +30,8 @@ Anatomy is enforced by a unit test: `tests/meta/test_stack_layout_contract.py`
 | [`full_default`](https://github.com/castacks/AirStack/tree/develop/stacks/full_default) | The full-autonomy topology with the MIGHTY map-based local planner (`asm_mighty` module: planner + acl-mapping voxel world model + NavigateTask bridge) — the baseline, and what launches when no stack is selected. |
 | [`full_droan`](https://github.com/castacks/AirStack/tree/develop/stacks/full_droan) | The GPU DROAN reactive planner (`droan_gl`, `asm_droan` module) in place of MIGHTY — for depth-camera-only vehicles and legacy comparisons. |
 | [`full_droan_cpu`](https://github.com/castacks/AirStack/tree/develop/stacks/full_droan_cpu) | CPU DROAN planner + live `disparity_expansion` (`asm_droan` module) for machines without a GPU planner. |
+| [`full_exploration`](https://github.com/castacks/AirStack/tree/develop/stacks/full_exploration) | `full_default` with the frontier-based geometric exploration planner in place of the random walk. Requires the `asm_exploration_planner` module (pinned in the stack's `modules.repos` alongside `asm_mighty`). |
+| [`full_raven`](https://github.com/castacks/AirStack/tree/develop/stacks/full_raven) | `full_default` with RAVEN open-set semantic navigation as the global planner: RayFronts GPU sidecar container + `raven_bridge`. Requires the `asm_raven` module (pinned alongside `asm_mighty`). |
 | [`full_macvo`](https://github.com/castacks/AirStack/tree/develop/stacks/full_macvo) | MAC-VO as the DROAN planner's disparity source. Requires the `asm_macvo` and `asm_droan` modules. |
 | [`lite_default`](https://github.com/castacks/AirStack/tree/develop/stacks/lite_default) | Onboard-lite topology, unsplit: interface, sensors, perception, flat Local layer, behavior; **no global, no logging**. |
 | [`lite_offload_global`](https://github.com/castacks/AirStack/tree/develop/stacks/lite_offload_global) | A **split stack**: `onboard.launch.xml` (= lite topology) + `offboard.launch.xml` (global layer only) + `bridge.yaml`. |
@@ -296,6 +298,8 @@ ignored. Select the topology with `--stack`:
 | The full-autonomy baseline | Nothing — `full_default` launches by default (or be explicit: `--stack full_default`) |
 | GPU DROAN reactive planner | `--stack full_droan` (`asm_droan` module) |
 | CPU DROAN topology | `--stack full_droan_cpu` (`asm_droan` module) |
+| Frontier exploration global planner | `--stack full_exploration` (requires the `asm_exploration_planner` module) |
+| RAVEN semantic (language-prompted) global planner | `--stack full_raven` (requires the `asm_raven` module; first run builds the sidecar image; Isaac Sim with GUI) |
 | MAC-VO disparity topology | `--stack full_macvo` (`asm_macvo` + `asm_droan` modules) |
 | Onboard-lite, unsplit | `--stack lite_default` |
 | Split onboard/offboard | `--stack lite_offload_global:onboard` / `:offboard` (+ generate the router config from `bridge.yaml`) |

docs/modules/exploration_planner.md

@@ -0,0 +1,56 @@
+# exploration_planner
+
+<!-- GENERATED by tools/gen_docs_catalog.py from the airstack-modules-index registry. Do not edit by hand: regenerate with
+     python3 tools/gen_docs_catalog.py --index <registry-checkout>
+     (the docs deploy workflows regenerate it against the live registry at build time) -->
+
+> Frontier-based geometric exploration global planner — OpenVDB occupancy map, frontier clustering, bounded viewpoint sampling and an RRT path to the chosen viewpoint, published as global_plan; developed for the CMU AirLab construction-site project
+
+| | |
+|---|---|
+| Repository | [castacks/asm_exploration_planner](https://github.com/castacks/asm_exploration_planner) |
+| Type | `ros_package` |
+| Maintainer | ajong@andrew.cmu.edu |
+| License | BSD-3-Clause-Clear |
+| Registered ref | [`v0.1.1`](https://github.com/castacks/asm_exploration_planner/tree/v0.1.1) |
+| Declared compat | `>=0.21.0-dev.8 <0.22.0` |
+| Registry entry | [modules/exploration_planner.yaml](https://github.com/castacks/airstack-modules-index/blob/main/modules/exploration_planner.yaml) |
+
+## Install
+
+From an AirStack checkout ([AirStack Modules guide](../development/modules.md)):
+
+```bash
+airstack module add https://github.com/castacks/asm_exploration_planner --version v0.1.1
+airstack up
+```
+
+`module add` pins the module in `modules.repos` and syncs it into the
+gitignored `modules/` overlay; `airstack up` automatically includes the
+generated compose override that mounts it into the containers.
+
+## Compatibility: declared vs verified
+
+The range `>=0.21.0-dev.8 <0.22.0` is **DECLARED** by the module author
+(copied from the module's `module.yaml`). The **VERIFIED** record — rows
+stamped exclusively by CI runs of the reusable
+[module-system-tests workflow](../development/module_ci.md) — lives in the
+registry's [compat/ matrix](https://github.com/castacks/airstack-modules-index/tree/main/compat)
+([compat/exploration_planner.yaml](https://github.com/castacks/airstack-modules-index/blob/main/compat/exploration_planner.yaml) once stamped).
+A compatibility claim that isn't CI-verified rots: trust the
+matrix, read the declaration as intent.
+
+## Documentation
+
+- [Module README on GitHub @ `v0.1.1`](https://github.com/castacks/asm_exploration_planner/blob/v0.1.1/README.md)
+- *The module repo was not fetched when this page was generated — the*
+  *links above go to GitHub at the registered ref (failure isolation:*
+  *an unreachable module repo never fails the docs deploy).*
+
+## Registered stacks using this module
+
+- [full_exploration](../../stacks/full_exploration/README.md)
+
+## Registry notes
+
+> Extracted from trunk (robot/ros_ws/src/global/planners/exploration, history preserved) together with the bounded-exploration additions from the construction-site demo branch. Publishes a path on global_plan and serves the behavior/global_plan_toggle service; the MIGHTY bridge (full_exploration) follows the published plan directly, while droan_gl-based stacks add the trunk global_plan_navigate_bridge. Consumed by trunk reference stack full_exploration.

docs/modules/index.md

@@ -20,9 +20,11 @@ directory and is never hand-edited.
 |--------|-------------|------|------------|-----------------|-------|
 | [dfm2_disturbances](dfm2_disturbances.md) | Isaac Sim disturbance library (fan/vent force fields, strobe lights, lens flare) | `isaac_extension` | ajong@andrew.cmu.edu | `>=0.19.0-alpha.18 <0.20.0` | [repo](https://github.com/castacks/asm_dfm2_disturbances) |
 | [droan](droan.md) | DROAN disparity-space local obstacle avoidance — the GPU (OpenGL) droan_gl planner and the CPU droan_local_planner with its disparity_expansion / disparity_graph / disparity_graph_cost_map world model, serving AirStack's NavigateTask / trajectory_controller seam from a stereo disparity image | `ros_package` | ajong@andrew.cmu.edu | `>=0.21.0-dev.10 <0.22.0` | [repo](https://github.com/castacks/asm_droan) · [full_droan](../../stacks/full_droan/README.md) · [full_droan_cpu](../../stacks/full_droan_cpu/README.md) · [full_macvo](../../stacks/full_macvo/README.md) |
+| [exploration_planner](exploration_planner.md) | Frontier-based geometric exploration global planner — OpenVDB occupancy map, frontier clustering, bounded viewpoint sampling and an RRT path to the chosen viewpoint, published as global_plan; developed for the CMU AirLab construction-site project | `ros_package` | ajong@andrew.cmu.edu | `>=0.21.0-dev.8 <0.22.0` | [repo](https://github.com/castacks/asm_exploration_planner) · [full_exploration](../../stacks/full_exploration/README.md) |
 | [macvo](macvo.md) | MAC-VO learned stereo visual odometry (ICRA 2025 best paper) — macvo_ros2 wrapper around the MAC-VO network, publishing odometry, a covariance-aware point cloud, and the disparity image the local planner can consume | `ros_package` | ajong@andrew.cmu.edu | `>=0.19.0-alpha.18 <0.20.0` | [repo](https://github.com/castacks/asm_macvo) · [full_macvo](../../stacks/full_macvo/README.md) |
-| [mighty](mighty.md) | MIGHTY Hermite-spline local planner (MIT ACL, RA-L 2026) with its acl-mapping voxel world model and a bridge to AirStack's NavigateTask / trajectory_controller seam — AirStack's default local planner (the map-based replacement for DROAN) | `ros_package` | ajong@andrew.cmu.edu | `>=0.21.0-dev.10 <0.22.0` | [repo](https://github.com/castacks/asm_mighty) · [full_default](../../stacks/full_default/README.md) |
+| [mighty](mighty.md) | MIGHTY Hermite-spline local planner (MIT ACL, RA-L 2026) with its acl-mapping voxel world model and a bridge to AirStack's NavigateTask / trajectory_controller seam — AirStack's default local planner (the map-based replacement for DROAN) | `ros_package` | ajong@andrew.cmu.edu | `>=0.21.0-dev.10 <0.22.0` | [repo](https://github.com/castacks/asm_mighty) · [full_default](../../stacks/full_default/README.md) · [full_exploration](../../stacks/full_exploration/README.md) · [full_raven](../../stacks/full_raven/README.md) |
 | [optitrack](optitrack.md) | OptiTrack NatNet mocap integration — natnet_ros2 client + PX4 external-vision fusion bridges on the robot, and the Motive-compatible NatNet server emulator for Isaac Sim | `ros_package` | ajong@andrew.cmu.edu | `>=0.19.0-alpha.18 <0.20.0` | [repo](https://github.com/castacks/asm_optitrack) |
+| [raven](raven.md) | RAVEN semantic aerial navigation (ICRA 2026) — the RayFronts open-set semantic ray-frontier map and behavior manager (voxel, ray, LVLM and frontier search) in a GPU sidecar container publishing global_plan toward a natural-language target, plus the raven_bridge plan/prompt relay on the robot | `ros_package` | ajong@andrew.cmu.edu | `>=0.21.0-dev.8 <0.22.0` | [repo](https://github.com/castacks/asm_raven) · [full_raven](../../stacks/full_raven/README.md) |
 
 ## Registered stacks
 
@@ -37,7 +39,9 @@ The stacks below are the ones REGISTERED in the index; the site nav's
 | [full_default](../../stacks/full_default/README.md) | The full-autonomy topology as a self-contained stack folder, with the MIGHTY map-based local planner (asm_mighty module: planner + acl-mapping voxel world model + NavigateTask bridge) — the baseline most users start from, the default when no stack is selected, and the stack other stacks are copied from | `>=0.21.0-dev.10 <0.22.0` | [wiring.md](../../stacks/full_default/wiring.md) | [full_default.yaml](https://github.com/castacks/airstack-modules-index/blob/main/stacks/full_default.yaml) |
 | [full_droan](../../stacks/full_droan/README.md) | Full autonomy with the GPU DROAN reactive local planner (droan_gl, asm_droan module) in place of the default MIGHTY planner — the 0.20.x full_default topology kept as a named stack for depth-camera-only vehicles and legacy comparisons | `>=0.21.0-dev.10 <0.22.0` | [wiring.md](../../stacks/full_droan/wiring.md) | [full_droan.yaml](https://github.com/castacks/airstack-modules-index/blob/main/stacks/full_droan.yaml) |
 | [full_droan_cpu](../../stacks/full_droan_cpu/README.md) | Full autonomy with the CPU DROAN local planner (droan_local_planner + live disparity_expansion world model, asm_droan module) in place of the default MIGHTY planner | `>=0.21.0-dev.10 <0.22.0` | [wiring.md](../../stacks/full_droan_cpu/wiring.md) | [full_droan_cpu.yaml](https://github.com/castacks/airstack-modules-index/blob/main/stacks/full_droan_cpu.yaml) |
+| [full_exploration](../../stacks/full_exploration/README.md) | Full autonomy (full_default topology: MIGHTY LiDAR-based local planner) with the frontier-based geometric exploration planner (exploration_planner module) in place of the random walk; everything else is identical to full_default | `>=0.21.0-dev.8 <0.22.0` | *not committed yet* | [full_exploration.yaml](https://github.com/castacks/airstack-modules-index/blob/main/stacks/full_exploration.yaml) |
 | [full_macvo](../../stacks/full_macvo/README.md) | Full autonomy with MAC-VO learned stereo visual odometry as the disparity source for the DROAN local planner (droan_gl, asm_droan module, consumes /$ROBOT_NAME/perception/macvo/disparity) | `>=0.21.0-dev.10 <0.22.0` | [wiring.md](../../stacks/full_macvo/wiring.md) | [full_macvo.yaml](https://github.com/castacks/airstack-modules-index/blob/main/stacks/full_macvo.yaml) |
+| [full_raven](../../stacks/full_raven/README.md) | Full autonomy (full_default topology: MIGHTY LiDAR-based local planner) with RAVEN open-set semantic navigation as the global planner (RayFronts GPU sidecar container + raven_bridge); everything else is identical to full_default | `>=0.21.0-dev.8 <0.22.0` | *not committed yet* | [full_raven.yaml](https://github.com/castacks/airstack-modules-index/blob/main/stacks/full_raven.yaml) |
 
 ## See also
 

docs/modules/mighty.md

@@ -50,6 +50,8 @@ matrix, read the declaration as intent.
 ## Registered stacks using this module
 
 - [full_default](../../stacks/full_default/README.md)
+- [full_exploration](../../stacks/full_exploration/README.md)
+- [full_raven](../../stacks/full_raven/README.md)
 
 ## Registry notes
 

docs/modules/raven.md

@@ -0,0 +1,56 @@
+# raven
+
+<!-- GENERATED by tools/gen_docs_catalog.py from the airstack-modules-index registry. Do not edit by hand: regenerate with
+     python3 tools/gen_docs_catalog.py --index <registry-checkout>
+     (the docs deploy workflows regenerate it against the live registry at build time) -->
+
+> RAVEN semantic aerial navigation (ICRA 2026) — the RayFronts open-set semantic ray-frontier map and behavior manager (voxel, ray, LVLM and frontier search) in a GPU sidecar container publishing global_plan toward a natural-language target, plus the raven_bridge plan/prompt relay on the robot
+
+| | |
+|---|---|
+| Repository | [castacks/asm_raven](https://github.com/castacks/asm_raven) |
+| Type | `ros_package` |
+| Maintainer | ajong@andrew.cmu.edu |
+| License | BSD-3-Clause-Clear |
+| Registered ref | [`v0.1.1`](https://github.com/castacks/asm_raven/tree/v0.1.1) |
+| Declared compat | `>=0.21.0-dev.8 <0.22.0` |
+| Registry entry | [modules/raven.yaml](https://github.com/castacks/airstack-modules-index/blob/main/modules/raven.yaml) |
+
+## Install
+
+From an AirStack checkout ([AirStack Modules guide](../development/modules.md)):
+
+```bash
+airstack module add https://github.com/castacks/asm_raven --version v0.1.1
+airstack up
+```
+
+`module add` pins the module in `modules.repos` and syncs it into the
+gitignored `modules/` overlay; `airstack up` automatically includes the
+generated compose override that mounts it into the containers.
+
+## Compatibility: declared vs verified
+
+The range `>=0.21.0-dev.8 <0.22.0` is **DECLARED** by the module author
+(copied from the module's `module.yaml`). The **VERIFIED** record — rows
+stamped exclusively by CI runs of the reusable
+[module-system-tests workflow](../development/module_ci.md) — lives in the
+registry's [compat/ matrix](https://github.com/castacks/airstack-modules-index/tree/main/compat)
+([compat/raven.yaml](https://github.com/castacks/airstack-modules-index/blob/main/compat/raven.yaml) once stamped).
+A compatibility claim that isn't CI-verified rots: trust the
+matrix, read the declaration as intent.
+
+## Documentation
+
+- [Module README on GitHub @ `v0.1.1`](https://github.com/castacks/asm_raven/blob/v0.1.1/README.md)
+- *The module repo was not fetched when this page was generated — the*
+  *links above go to GitHub at the registered ref (failure isolation:*
+  *an unreachable module repo never fails the docs deploy).*
+
+## Registered stacks using this module
+
+- [full_raven](../../stacks/full_raven/README.md)
+
+## Registry notes
+
+> Wrapper (raven_bridge, sidecar Dockerfile, compose fragment, test_stack) is BSD-3-Clause-Clear; the vendored RayFronts fork (seungchan-kim/RayFronts, branch raven) keeps its own license — see the module's VENDORED.md. The sidecar is declared through the manifest's compose fragment (first module to bring its own container) and is built on first `airstack up` (~20 GB image). Consumed by trunk reference stack full_raven.