Documentation

Everything you need to know about MindForge.

For developers

Build MindForge from source

1 min read

MindForge is open source under the Apache License 2.0. Since it is not on the App Store yet, building it yourself is currently the way to run it.

What you need

Tool Version
Flutter 3.44.6 (Dart 3.12.2)
Xcode 26.6
CocoaPods 1.15.2

macOS only, because iOS is the only platform target in the repository today.

Getting it running

git clone https://github.com/zakariaf/mindforge.git
cd mindforge

flutter pub get
dart run build_runner build --delete-conflicting-outputs
flutter test
flutter run

Run build_runner before flutter analyze, not after — the database, the localizations and the Riverpod providers are all generated, and analyzing stale output produces errors that are not real.

The canonical simulator

The repository pins one device:

MindForge iPhone 14 · C13DDC02-375D-4E1B-8F81-44EB407D09A4 · iOS 18.6

It is the canonical device for one reason: it is exactly 390 x 844 logical points, which matches the reference screenshots every screen is signed off against. No iPhone 16-class simulator does — the 16 is 393 x 852 and the 16 Pro is 402 x 874 — so a screenshot comparison on one of those is not an honest comparison.

Why there is no android/ directory

Android is planned and the architecture is deliberately platform-neutral: no platform channel, no native UI. But generating an android/ directory nobody builds or tests buys a Gradle upgrade treadmill for no shipped value, so it is deferred rather than unsupported. Re-adding it is flutter create --platforms=android . plus one pull request to restore the build job.

A test asserts its absence, with that reason attached, so nobody has to guess whether it was an oversight.

Running the gates

Beyond the usual dart format, flutter analyze --fatal-infos and flutter test, the repository carries gate scripts that fail the build on a design or architecture violation — a raw hex outside the theme directory, a blurred shadow, a game that tries to navigate, a hardcoded left or right, a contrast ratio below its floor.

tool/skill_gates.sh

Run them through that script rather than globbing the skills directory; not every script there is a gate, and some take arguments.