geogram: Instructions file for Codex

Repository Guidelines

Project Structure & Module Organization

• lib/ holds the Flutter application code and shared UI/business logic.
• bin/ contains CLI utilities and standalone Dart test runners such as station_api_test.dart.
• tests/ includes integration-style Dart tests and shell scripts for multi-device scenarios.
• Platform targets live in android/, ios/, linux/, macos/, windows/, and web/.
• Assets and data live in assets/, languages/, themes/, tiles/, and games/.
• Build and operational scripts are in the repo root and scripts/.

Core Workflow

• Run the relevant compiler or analyzer after code changes so the edited code is validated.
• Do not claim a feature works until you have verified it yourself.
• Use the debug API in docs/API.md for feature verification whenever possible.
• If the required debug API endpoint does not exist, add it, use it to test the feature, and document it in docs/API.md.
• For desktop and general client verification, always launch through ./launch-desktop.sh.
• For Android-specific verification, use ./launch-android.sh.
• For server-side deployment or validation, use ./server-deploy.sh.
• Plan and verify end-to-end behavior yourself instead of waiting for the user to list every validation step.
• Commit your changes after each task with a descriptive sentence-case message.
• Mention bug or ticket identifiers in commit messages when the task is tied to a specific issue.
• Never run git push, gh release, or other publish steps unless the user explicitly asks.
• Never auto-close bug tickets or issues after fixing them; wait for explicit confirmation.

Architecture Constraints

• When accessing anything inside the {callsign} profile folder, always use ProfileStorage methods rather than raw File or Directory.
• Obtain profile storage through AppService().profileStorage.
• This rule is mandatory because profile data may live in EncryptedProfileStorage backed by SQLite rather than the plain filesystem.
• Do not implement station features separately in CLI and Desktop station classes.
• Put shared station logic in reusable libraries or mixins, especially under lib/server/mixins/, and have both station implementations use the same code.
• The two station entry points are lib/cli/pure_station.dart and lib/station.dart; keep behavior aligned through shared code.
• EmailHandlerMixin is the shared email implementation for both station types; extend shared behavior there instead of duplicating email logic.
• The offline ECIES email cache path is intentionally disabled at the moment; reconnect delivery still relies on the pending-email path until encryption is redesigned.
• Prefer Dart libraries that can run from the command line so logic can be reused across platforms.
• Reuse existing components instead of duplicating them, and document new reusable building blocks in docs/reusable.md.