Running the app

Day to day

# List devices
fvm flutter devices

# Run on a device (use the iOS Simulator, not a physical iPhone)
fvm flutter run -d <device_id>

For daily work, use the chorki (staging) launch config in VS Code (or pass --dart-define=USE_STAGING=true) so you build against the staging API and the Turnstile test site key.

Build-time configuration

Builds hit the production API by default. Options are read in lib/core/config/app_config.dart:

--dart-define	Effect
USE_STAGING=true	Staging API hosts + Turnstile test site key
SENTRY_DSN	Empty value disables Sentry entirely
SENTRY_ENVIRONMENT	e.g. staging, production
SENTRY_RELEASE	Release tag attached to events
SENTRY_TRACES_SAMPLE_RATE	Traces sampling, 0.0–1.0

Sentry never runs in debug builds, regardless of these flags.

iOS: debug on the simulator

A physical iPhone on iOS 17+ is slow to install and launch for toolchain reasons, and can appear as a black screen at launch. That is a known toolchain issue, not an app bug — read docs/ios-iteration-speed.md (published here as a deep dive) before chasing it. Rule of thumb: Simulator for iteration, physical device only when you specifically need one (e.g. AirPlay).

Also keep use_frameworks! :linkage => :static in ios/Podfile. Plain use_frameworks! puts ~60 signed framework bundles back into every install and destroys iteration speed.

Shipping

.github/workflows/main.yml deploys the deploy branch to TestFlight. That workflow is stale in two ways — it runs an old Flutter (3.24.4) and cannot resolve the absolute player paths — so treat it as the packaging pipeline only. No CI runs the tests; the local quality gate is the only gate.