---
name: repo-map
description: >
  Orient within the LunCoSim workspace: repository layout, crate ownership,
  runnable binaries, API launch modes, and the right evidence path for a task.
  Use when choosing an app, locating a feature or crate, launching the simulator,
  workbench, or server, using headless mode, or avoiding an ambiguous bare
  `cargo run`. It distinguishes production `luncosim` scene and visual evidence
  from numeric headless execution, identifies `lunica` as the Modelica
  workbench, explains the canonical API port, and points to the authoritative
  application and crate indexes.
---

# Repo map — layout, binaries, and when to use them

A Rust/Bevy Cargo workspace: **60+ library crates** + a handful of app binaries,
plus assets, docs, specs, and skills. This skill is the fast orientation; the two
**authoritative, always-current indexes** are:

- **[`docs/apps/README.md`](../../docs/apps/README.md)** — every runnable binary, full CLI flags, launch lines.
- **[`docs/crates-index.md`](../../docs/crates-index.md)** — every library crate, grouped by domain, with responsibilities.

When those disagree with anything here, they win.

## When a capability is hard to find

This map routes to owners; it is not an exhaustive capability list. Before
calling a feature missing, use
[**capability-discovery**](../capability-discovery/SKILL.md): search the relevant
skills and docs, then `crates/`, `assets/`, registrations/callers, maintained
dependencies, and the live API/runtime. Search alternate vocabulary and
standard USD schema/property names before adding a new command, field, tool, or
crate. Report the exact searched scope and distinguish “not found” from “not
verified” or “externally blocked”.

## Top-level layout

| Dir | What's in it |
|---|---|
| `crates/` | All Rust code — libraries **and** the app binaries (there is **no `apps/` dir**). |
| `assets/` | Runtime data: `scenes/` (USD), `models/` (Modelica `.mo`), `scripting/` (rhai prelude/examples/tools), `tutorials/`, `ui/` (runtime-authored HTML/CSS-like surfaces), `vessels/`, `shaders/`, `props/`, `missions/`, `config/`. |
| `docs/` | `architecture/` (numbered design docs), `apps/`, `tutorials/`, `crates-index.md`, `scripting-guide.md`, `principles.md`. |
| `specs/` | Numbered feature specs (`NNN-name/spec.md`) — the *intent* behind subsystems. |
| `skills/` | Agent skills (this one, `author-scenario`, `authoring-vessel-controllers`, `run-modelica`, `test-via-api`, `lunco-ui`, `runtime-ui`, `lunco-theme`). |
| `mcp/` | Node MCP server wrapping the HTTP API as tools for AI agents. |
| `scripts/` | `build*.sh`, `check_*.sh` (lints/wasm), `api/` (HTTP helpers), `deploy/`, `perf/`. |

## Binaries — which one do I run?

**Pick by task, not by habit:**

| I want to… | Run | Why |
|---|---|---|
| Ground physics / rovers / USD scenes / Modelica / visual evidence | **`luncosim`** | The production scene/runtime binary; use it for scene tests, screenshots, and visual acceptance. |
| Numeric headless simulation / CI automation | **`luncosim-server`** | The same simulation through `run_headless()`, with no GUI evidence; use it for numeric/API automation. |
| Author / compile / simulate Modelica models, browse source libraries | **`lunica`** | The **Modelica** workbench (⚠️ NOT the main sim). |
| Download / verify / process external assets | **`lunco-assets` + `lunco-assets-{transport,download,processing}`** | `-- download\|list\|process`; explicit workers/CLI compose shared transport, atomic installation, and native processors. |

Launch the installed production executable, or explicitly select a checkout
build when source validation is the goal. Workspace `default-members` make a
bare `cargo run` ambiguous — **always pass a target**:

```bash
# GitHub/release install on PATH (or override with an absolute installed path).
export LUNCOSIM_BIN="${LUNCOSIM_BIN:-luncosim}"
export LUNCOSIM_SERVER_BIN="${LUNCOSIM_SERVER_BIN:-luncosim-server}"
export LUNICA_BIN="${LUNICA_BIN:-lunica}"
"$LUNCOSIM_BIN"
"$LUNCOSIM_BIN" --api 4101
"$LUNCOSIM_SERVER_BIN" --api 4101

# Source checkout alternative: build, then override the variables before use.
# cargo build -p lunco-luncosim --bin luncosim -j 4
# export LUNCOSIM_BIN=target/debug/luncosim
# cargo build -p lunco-luncosim-server --bin luncosim-server -j 4
# export LUNCOSIM_SERVER_BIN=target/debug/luncosim-server

"$LUNICA_BIN" --api 4101

# Source checkout alternative for the Modelica workbench:
# cargo build -p lunco-modelica-ui --bin lunica -j 4
# export LUNICA_BIN=target/debug/lunica
```

**Utility / dev bins**: `modelica_run` (`lunco-modelica-execution`, headless Modelica CLI → CSV),
`modelica_library_indexer` (`lunco-modelica-assets`, rebuild the Modelica-library search index — re-run
after a source-library change), `lunica_worker` (`lunco-modelica-execution`, wasm compile worker, bundled not run),
`build_modelica_library_assets` (`lunco-modelica-assets`), `net_smoke` (`lunco-luncosim`, production
transport smoke test). Authored luncosim behavior tests run through `luncosim test` plus their Rhai scenarios.
Details:
[`docs/apps/README.md`](../../docs/apps/README.md).

## Talking to a running app (agents)

The windowed apps that embed the API bridge (`luncosim`, `lunica`, and anything with
`LunCoApiPlugin`) honor:

- `--api [PORT]` — enable the HTTP automation API. Default port **4101**. This is
  mandatory for luncosim visual/runtime validation; use an explicit free port.
  (`lunco_api_contracts::DEFAULT_API_PORT`); the MCP config points here via
  `LUNCO_API_PORT`. Without `--api`, no network surface.

- `--no-ui` — headless (skip winit/egui, run the shared sim loop).
- `--scene <path>` — (`luncosim`) load a USD scene on boot; path is relative to the
  `assets/` root (do **not** prefix with `assets/`).

Use production `luncosim` for scene-test and visual evidence. Use
`luncosim-server` (or `luncosim --no-ui`) for numeric/headless evidence only;
headless runs cannot prove screenshots, rendering, or visual acceptance. Keep
the binary, revision, readiness state, and evidence type explicit in reports;
these evidence paths are complementary, not interchangeable.

Drive it: `POST /api/commands` with `{"type":"ExecuteCommand","command":"<Name>","params":{...}}`; discover
the live command set with `DiscoverSchema` (it's introspected, never hard-coded). Full
recipe in the [`run-modelica`](../run-modelica/SKILL.md) / [`test-via-api`](../test-via-api/SKILL.md) skills.

## Crate domains at a glance

Crates are grouped into 8 domains in [`docs/crates-index.md`](../../docs/crates-index.md).
Use this to jump to the right one; read the index for the full responsibility.

| Domain | Crates own | Key crates |
|---|---|---|
| **Core foundation** | primitives, session/authority substrate, docs/journal, time, storage, hashing, cache, settings, theme | `lunco-core`, `lunco-core-session`, `lunco-doc`, `lunco-twin-journal`, `lunco-time`, `lunco-storage`, `lunco-hash` |
| **Simulation engine** | celestial, environment, terrain, experiments, cosim | `lunco-celestial`, `lunco-cosim`, `lunco-experiments`, `lunco-terrain-*` |
| **Vessel control & hardware** | semantic input, mobility, robotics, avatar, FSW/OBC/hardware, controller | `lunco-input-core`, `lunco-mobility`, `lunco-controller`, `lunco-cosim` |
| **USD integration** | OpenUSD↔Bevy: authored document, operation core, geometry, visuals, physics, joint admission, sim schemas, actuation, materials | `lunco-usd-document`, `lunco-usd-core`, `lunco-usd-geometry`, `lunco-usd-commands`, `lunco-usd-bevy`, `lunco-usd-avian`, `lunco-usd-avian-joints`, `lunco-usd-actuation`, `lunco-materials` |
| **Networking & API** | transport, transport-neutral replication, scenario wire contracts, HTTP API, telemetry, attributes | `lunco-networking`, `lunco-networking-core`, `lunco-networking-scenario`, `lunco-networking-sync`, `lunco-api`, `lunco-telemetry-core`, `lunco-telemetry` |
| **Workbench & UI** | IDE shell, shell-independent widgets, optional guided presentation, runtime-authored HUI/Flair surfaces, reusable Twin/Files browser, viz, 2D canvas, edit tools, focused transform gizmo, render intent/recovery, web boot | `lunco-workbench`, `lunco-workbench-core`, `lunco-workbench-widgets`, `lunco-workbench-guided-ui`, `lunco-workbench-runtime-ui`, `lunco-workbench-browser`, `lunco-ui`, `lunco-viz`, `lunco-canvas`, `lunco-luncosim-edit-core`, `lunco-luncosim-edit-gizmo-ui`, `lunco-luncosim-edit-ui`, `lunco-render-recovery` |
| **Scripting & modeling** | Modelica, event-driven Rhai, tools, hooks, behavior trees, authored lessons | `lunco-modelica-core`, `lunco-modelica-ui-core`, `lunco-modelica-ui`, `lunco-scripting`, `lunco-scripting-rhai-world`, `lunco-scripting-rhai-runtime`, `lunco-scripting-rhai-core`, `lunco-scripting-rhai`, `lunco-tools`, `lunco-hooks`, `lunco-behavior`, `lunco-luncosim` |
| **Applications** | the entry-point binaries above | `luncosim`, `luncosim-server`, `lunica` |

## Where does X live? (routing)

| Looking for… | Go to |
|---|---|
| A subsystem's design/intent | `docs/architecture/NN-*.md` (numbered) or `specs/NNN-*/spec.md` |
| Which crate owns a responsibility | `docs/crates-index.md` |
| How to run/launch anything | `docs/apps/README.md` |
| Writing rover/vehicle behavior (rhai) | skill `author-scenario` + `docs/scripting-guide.md` |
| Authoring a reloadable Twin-facing UI | skill `runtime-ui` + `docs/architecture/runtime-authored-ui.md` |
| A self-driving vessel / GNC / autopilot | skill `authoring-vessel-controllers` |
| Running Modelica / experiments over the API | skill `run-modelica` |
| Verifying a change end-to-end via the API | skill `test-via-api` |
| Runtime data (scenes, models, scripts) | `assets/` (see layout table) |
| Build/lint/deploy helpers | `scripts/` |

## Gotchas / naming traps

- **No `apps/` directory** — every binary lives in a `crates/<crate>/src/{main.rs,bin/}`.
- **`lunica` ≠ the main sim.** It is the Modelica workbench (crates `lunco-modelica-ui` (workbench), `lunco-modelica-ui-core` (shared UI contracts), `lunco-modelica-core` (runtime host), and `lunco-modelica-execution` (workers)); `luncosim` is the ground-physics simulator and `luncosim-server` is its headless launcher.
- **Web application features are explicit.** `build_web.sh` and `check_wasm.sh` select `api,ui` for lunica and `api-transport,networking,ui` for luncosim, without native `transport-http`. Native file watching stays in the UI host's native Bevy dependencies.
- **Do not launch LunCoSim through `cargo run`.** Build the named package/bin,
  then execute `$LUNCOSIM_BIN` directly. Bare `cargo run` is also
  ambiguous because the default members are `lunco-luncosim` and `lunco-modelica-ui`.
- **`lunco-luncosim` produces the `luncosim` binary** (crate name ≠ binary name); `luncosim-server` is a *separate crate* (`lunco-luncosim-server`) that exists only to default to headless.
- **API port is 4101** by default; always pass an explicit free port when another
  session owns it.
- **Don't `pkill`** a running app to restart — use the API `Exit` command (see `test-via-api`).
- Composition roots: `lunco-luncosim-core` owns the dependency-light Bevy substrate; `lunco-luncosim-simulation` owns renderer-independent domain composition; `lunco-luncosim-services` owns startup/API/network/persistence services; `lunco-luncosim-runtime` composes the substrate, simulation, services, and application scripting/policy integration; `lunco-luncosim` composes runtime with `lunco-luncosim-ui` for the GUI; `lunco-luncosim-server` launches runtime directly. USD stage composition is owned by `lunco-usd-bevy::flatten_stage`.