qol-arch-codelisted

# qol-arch-code: Plugin and Cross-Platform Code Layout ## Principle **Don't sprinkle `#[cfg(target_os)]` through business code.** Compartmentalize platform differences behind a trait or struct facade, with one implementation per OS unless a specific feature capability has its own backend split. Business code calls the abstraction; cfg gates exist only at the wiring layer in `mod.rs`. `target_os` is the first question, not automatically the final module boundary. Start from the feature capability. If it only needs OS primitives, keep one OS module form: `platform/linux.rs` inside an all-flat `platform/` directory, or `platform/linux/mod.rs` inside an all-directory `platform/` directory. If that capability must choose between runtime substrates with different contracts, model those as private backends behind the capability facade. The substrate split belongs next to the capability it implements, not as a global Linux taxonomy. This makes the codebase: - Compile on every host (no `compile_error!` blocking macOS devs) - Easy to verify in CI on a matrix - Clear about which behavior is genuinely platform-specific vs accidentally so ## Headless-first feature shape Prefer applications and plugins that work as standalone headless tools first. The qol-tray integration should be an adapter over that tool, not where the feature's core behavior lives. Layer Rust plugins like this: ``` plugin-name/ ui/ # optional host-served HTML, JavaScript, and CSS src/