From a78754d90924e1942f9e4f4e3e43cbf83e7403d8 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Onur=20=C3=96zkan?= <work@onurozkan.dev>
Date: Sat, 7 Nov 2026 18:12:11 +0300
Subject: [PATCH] build(ground-suite): add a separate pinned Flutter shell

Provide a separate Flutter development shell from the existing locked
Nix input and document the application build commands.

Validation: locked environment/version probe; no native application
qualification is claimed.
---
 docs/src/development.md | 18 ++++++++++++++++++
 flake.nix               | 17 +++++++++++++++++
 ground_suite/README.md  | 32 ++++++++++++++++++++++++++------
 3 files changed, 61 insertions(+), 6 deletions(-)

diff --git a/docs/src/development.md b/docs/src/development.md
index 0aec768..be7f919 100644
--- a/docs/src/development.md
+++ b/docs/src/development.md
@@ -52,3 +52,21 @@ The strict gate requires 100% line and branch coverage for `kaptan-math`,
 core package's coverage artifacts, unions LCOV source-line records, and uses
 full LLVM source spans to merge generic branch instantiations without lowering
 the gate.
+
+## Ground suite builds
+
+The separate locked shell supplies Flutter, Dart and desktop dependencies:
+
+```sh
+nix develop .#ground-suite
+cd ground_suite
+flutter pub get --enforce-lockfile
+dart format --output=none --set-exit-if-changed lib
+dart analyze
+flutter analyze --no-pub
+flutter build web --release --no-pub
+flutter build linux --release --no-pub
+```
+
+The app currently has no widget-test suite. Windows and macOS need their native
+build and runtime checks.
diff --git a/flake.nix b/flake.nix
index bd8594c..1c49716 100644
--- a/flake.nix
+++ b/flake.nix
@@ -33,6 +33,23 @@
               pkgs.python3
             ];
           };
+          ground-suite = pkgs.mkShell {
+            packages = [
+              (pkgs.flutterPackages.v3_41.override {
+                supportedTargetFlutterPlatforms = [
+                  "universal"
+                  "web"
+                  "linux"
+                ];
+              })
+              pkgs.clang
+              pkgs.cmake
+              pkgs.ninja
+              pkgs.pkg-config
+              pkgs.gtk3
+            ];
+            CMAKE_BUILD_PARALLEL_LEVEL = "2";
+          };
         }
       );
     };
diff --git a/ground_suite/README.md b/ground_suite/README.md
index 667a128..ab779ab 100644
--- a/ground_suite/README.md
+++ b/ground_suite/README.md
@@ -1,21 +1,41 @@
 # Kaptan Ground Suite
 
+## Environment
+
+From the repository root, optionally enter the app development shell pinned by
+`flake.lock`:
+
+```sh
+nix develop .#ground-suite
+```
+
+This shell supplies Flutter 3.41.9, Dart 3.11.5 and Linux desktop build
+dependencies. The default firmware shell does not include these tools.
+
 ## Run
 
+From the repository root, in that shell or an equivalent Flutter environment:
+
 ```sh
 cd ground_suite
-flutter pub get
+flutter pub get --enforce-lockfile
 flutter run -d linux
 ```
 
-On NixOS, enter `nix shell nixpkgs#flutter` first.
-For web, use `flutter run -d chrome`.
+For web, run `flutter run -d chrome` from `ground_suite/` with Chrome available.
 
 ## Check
 
+Run from `ground_suite/` after the locked dependency fetch above:
+
 ```sh
 dart format --output=none --set-exit-if-changed lib
-flutter analyze
-flutter build web
-flutter build linux
+dart analyze
+flutter analyze --no-pub
+flutter build web --release --no-pub
+flutter build linux --release --no-pub
 ```
+
+There is currently no `test/` directory or widget test suite. Web and Linux
+builds do not verify the Windows or macOS runners. See the central
+[development guide](../docs/src/development.md#ground-suite-builds).