Appendix: Common Tasks

• Add a new file parser
  1. Implement the parser in io/pipelines/src/formats/<format>.rs.
  2. Register it in io/pipelines/src/registry.rs.
  3. Extend LoaderService tests or add a regression case under tests/regression.
  4. Document the format in docs/USER_GUIDE.md.
• Add a keyboard shortcut
  1. Define the key mapping in ui/shell/src/keyboard.rs.
  2. Handle the action inside viewer_loop/key_actions/ (update KeyActionContext if new state is required).
  3. Update the User Guide’s shortcut tables.
• Create a new viewer panel
  1. Add a module under ui/shell/src/panels/.
  2. Expose actions via enums in panels.rs and wire them through ViewerLoop.
  3. Persist any new state in UiState and update serialisation logic if applicable.
• Extend remote access
  1. Add the capability to SftpDataSource (core/services/src/data_source/sftp/mod.rs), or to the DataSource trait if it should apply to every backend.
  2. Update RemoteContext (ui/shell/src/remote/) to use it.
  3. Surface the feature in the GUI remote browser or CLI remote commands.
• Expose a new CLI subcommand
  1. Update automation/cli/src/main.rs with the Clap definition.
  2. Implement the logic using OrbitronServices instead of re-implementing loaders.
  3. Add user-facing documentation and tests (ideally under automation/cli/tests or as integration binaries).
• Expose functionality in the Python bridge
  1. Add public methods to PyOrbitron or PyScene in extensions/python-bridge/src/lib.rs.
  2. Reuse existing service helpers; avoid duplicating logic already present in the CLI.
  3. Update docstrings and provide a short example in the User Guide or Python README.
  4. Rebuild via maturin develop and add a smoke test under extensions/python-bridge/tests if possible.
• Add an analysis module shared by CLI/TUI
  1. Implement the core logic under automation/cli/src/analyze_<module>.rs (follow existing modules for geometry/orbitals).
  2. Expose the module through the AnalyzeCommands enum and handler.
  3. If the TUI should display the data, add a helper in automation/tui/src/analysis.rs and render it inside the appropriate panel.
  4. Capture representative fixtures in regression tests.

By following the patterns described in this guide and reusing existing abstractions, new features remain consistent with the rest of the Orbitron workspace while minimising regressions.