Development Workflow & Conventions

• Set up your development environment (see §2 Development Environment Setup). Ensure environment variables are set if using system packages or conda.
• Follow existing module organisation; large viewer subsystems live under ui/shell/src/<area>/. When adding new functionality, prefer creating a dedicated module rather than expanding viewer_loop::run.
• Error handling uses anyhow::Result at the binary/application level and typed thiserror::Error enums inside core crates.
• Avoid unwrap()/expect() in production paths; prefer early Result returns or explicit fallbacks. Core crates deny clippy::unwrap_used/clippy::expect_used, while tests may allow them when a panic is the expected outcome.
• Instrument long-running tasks with tracing::instrument (already adopted across scheduler, renderer, and selection code).
• Keep documentation up to date: public APIs must have doc comments, and significant behavioural changes should be reflected in docs/USER_GUIDE.md and this guide.
• The workspace lints forbid unsafe and warn on missing docs/unnecessary imports; do not suppress these without discussion.

12.1 Error Handling Patterns

• Use anyhow::Context at CLI/UI boundaries so errors report the path or operation that failed.
• Prefer typed errors in core crates (IoPipelineError, EditError, etc.) and convert to anyhow only at edges.
• Treat optional parse fields as Option<T> and log/record warnings rather than panicking on missing data.
• For malformed input, return ParseError { path, message } with enough detail to debug fixtures.
• Avoid unwrap/expect in non-test code; use ?, ok_or_else, or a documented fallback.
• Clippy enforces unwrap_used/expect_used at the workspace level; test crates and examples may opt out with #![allow(clippy::unwrap_used, clippy::expect_used)].