Capability Discovery

Discover LunCoSim capabilities

Use this runbook before writing “LunCoSim cannot do X”, “X is not implemented”, or adding a replacement mechanism. A failed first search is not evidence of absence: the capability may be named after its owner, exposed only through a registration, available in a skill, or implemented in a different format.

1. Start from the current checkout

Confirm the worktree, branch, and dirty state. Treat old reports, another worktree, a stale binary, and a failed build as leads rather than current capability evidence. Preserve unrelated changes.

Translate the request into several search terms: the user's phrase, the likely architecture noun, a probable crate or schema, and a command/query/tool name. Then search generated-output-free paths:

rg -n -i --glob '!target/**' '<terms>' \
  AGENTS.md skills docs specs crates assets scripts
rg -n -i --glob '!target/**' '<symbol|schema|command|query>' \
  skills docs crates assets scripts

Read only the routed material, but always begin with:

• skills/README.md for skill routing and cross-cutting rules;
• docs/README.md for the documentation map;
• docs/crates-index.md for ownership;
• docs/apps/README.md for binaries and launch modes;
• the relevant architecture document, specification, skill, crate README, and authored asset examples.

If the first vocabulary is empty, search synonyms, the owning domain, standard USD schema/property names, and likely Command, query, observer, registration, or Rhai tool names. Do not conclude from one README, one crate, or one failed symbol lookup.

2. Trace the authoritative owner

For each promising result, follow the complete path:

format or authored asset
  -> loader/composer/parser
  -> owner and registration
  -> public caller/API/query/command
  -> runtime projection or execution
  -> test, example, or acceptance evidence

Check the maintained dependency when the question concerns OpenUSD, Bevy, Avian, Modelica/Rumoca, wgpu, or another library. Search Cargo features and registration macros as well as function names. A source file without a registration or caller is not the same as a usable capability; a missing name in one crate is not proof that the capability is absent.

For live behavior, use the production binary and its API. Start a rebuilt $LUNCOSIM_BIN with an explicit free --api PORT, then use:

curl -s http://127.0.0.1:PORT/api/commands/schema | jq .
curl -s -X POST http://127.0.0.1:PORT/api/commands \
  -H 'content-type: application/json' \
  -d '{"type":"DiscoverSchema"}' | jq .

Use ListEntities, ScriptingCatalog, ListToolLibraries, GetToolLibrary, and the relevant typed query/command to verify a live surface. --validate proves parsing/preflight only; it does not prove runtime behavior. Use a production authored scene test, API verdict, or headful visual capture when that is what the requested capability requires.

3. Know the format boundary

Choose the format whose owner already matches the requested fact:

A composed USD stage is data; it does not by itself execute Modelica, Rhai, physics, or rendering. Standard USD schemas and properties own authored facts before a custom lunco: field is considered. Asset identity and storage use the existing asset resolver and @lunco://...@ references.

4. Use dynamic Rhai tools when the capability is policy

LunCoSim can gain reusable authoring, inspection, lint, and test behavior without a Rust rebuild. Before creating a tool, query DiscoverSchema, ListToolLibraries, and GetToolLibrary, then search:

• shared libraries in assets/scripting/tools/;
• Twin-scoped libraries in <twin>/tools/;
• prelude helpers and the relevant author-rhai-tool skill;
• docs/scripting-guide.md and its tool-library section.

Compose or minimally extend an existing library when possible. Use a new library only for a reusable contract, missing generic operation composition, or repeatable report/test boundary. Keep one owner: a tool may choose policy and produce typed plans, but USD/document owners apply edits, Rust owns generic engine mechanisms, and Modelica owns continuous equations. A one-off mission belongs in a scenario, not a shared tool.

The normal dynamic-tool cycle is:

edit .rhai
  -> RegisterToolLibrary { name, source }
  -> ListToolLibraries / GetToolLibrary
  -> minimal RunRhai or RunScenario call
  -> authored scene test or runtime evidence

Registration validates the source in the production Rhai engine and, with an active Twin, persists it in the Twin tool directory. Tool/source changes do not need a Rust rebuild; Rust observers, command types, schemas, and projection changes do. Discovery is not invocation proof: verify the exact function from the actual execution context.

5. Follow the normal development cycle

Use this sequence for a capability request or implementation:

1. Frame the intent. Define the observable result, format/domain, and evidence needed. Choose the primary skill from skills/README.md.
2. Discover before designing. Search skills/docs, then owner source, registrations/callers, maintained dependencies, assets, and live API surfaces. Record the existing mechanism or the bounded gap.
3. Establish a baseline. Reproduce the current behavior with the narrowest relevant test, production binary, API call, or visual capture.
4. Change the owner. Extend the existing mechanism in its authoritative layer. Keep policy in Rhai, authored identity/topology in USD, equations in Modelica, and generic engine work in Rust.
5. Validate the smallest sufficient path. Use --validate for asset preflight, the owning Rust target for low-level mechanisms, authored Rhai scene tests for observable behavior, and the production luncosim binary for runtime/visual evidence. Reuse valid evidence when inputs are unchanged.
6. Review integration. Search callers, docs, skills, registrations, tests, and examples for stale names. Check git diff --check; remove retired paths, shims, fallbacks, and duplicate owners.
7. Hand off. Report exact files/symbols, commands, revision, evidence type, and remaining blockers. For non-trivial LunCoSim work, keep the Trello card in the correct lifecycle state and do not claim acceptance without observed evidence.