FlyCrys: Instructions file for Codex

AGENTS.md - FlyCrys

Instructions for AI agents working on this codebase.

Rules

• NEVER use deprecated GTK4 APIs. No TreeView, TreeStore, CellRenderer*, ListStore (deprecated one). Use modern replacements: ListView, ColumnView, TreeListModel, SignalListItemFactory, TreeExpander, gio::ListStore. No #[allow(deprecated)] annotations.

• ALWAYS check latest GTK4 API docs before using any GTK API. Do NOT rely on memory or training data — GTK4 APIs change between versions and many are deprecated. Use Context7 (resolve-library-id + query-docs for gtk4-rs) or fetch the official docs at https://docs.rs/gtk4 and https://docs.gtk.org/gtk4/ to verify that the API you're about to use is current and not deprecated. When in doubt, look it up.

• Handle errors properly — show the reason to the user. Never silently swallow errors. Follow these rules:

  In UI code: Show meaningful error messages to the user. Use gtk::AlertDialog (NOT the deprecated MessageDialog):

  // Correct pattern — AlertDialog with detail
  let dialog = gtk::AlertDialog::builder()
      .message("Operation failed")
      .detail(&format!("Could not open file: {err}"))
      .build();
  dialog.show(Some(&window));
  

  For errors inside the agent panel, use agent_widgets::create_system_message() to display the error inline with the reason.

  In service code: Return Result<T, String> (or a proper error type) with a descriptive message that includes the underlying cause. Never discard the why:

  // Bad — reason is lost
  fs::read_to_string(path).ok();
  command.spawn().ok();
  
  // Good — reason is propagated
  fs::read_to_string(path).map_err(|e| format!("Failed to read {}: {e}", path.display()))?;
  

  Specifically:

  • eprintln!() is acceptable for debug/logging but is NOT a substitute for user-visible feedback
  • .unwrap() is only acceptable on infallible operations (e.g., GTK widget downcasts inside factory callbacks where the type is guaranteed). Never on I/O, parsing, or network operations.
  • .ok() that discards a result is a code smell — justify it with a comment or handle the error
  • For async dialog callbacks (FileDialog, AlertDialog), check for GtkDialogError::Dismissed — that's the user choosing to cancel, not an error worth reporting