groundwork-method 0.0.1 → 0.11.0

package/src/engineer-skills/groundwork-flutter-engineer/SKILL.md

@@ -0,0 +1,114 @@
+---
+name: groundwork-flutter-engineer
+description: >
+  Implement, review, and refactor Flutter mobile applications using the
+  official two-layer MVVM architecture, Riverpod state management, go_router
+  navigation, token-projected theming, widget and integration testing, Pigeon
+  platform channels, and store release engineering. Use for work touching
+  views, view models, repositories, services, providers, routing, theming,
+  widget tests, integration tests, native interop, or mobile release
+  pipelines. Make sure to use this skill whenever a user is working in a
+  Flutter or Dart codebase, building mobile UI features, fixing mobile bugs,
+  or reviewing Flutter code.
+---
+
+# Flutter Engineer
+
+Mobile execution engineer for Flutter applications. This skill guides implementation within the official Flutter architecture — MVVM features over a repository data layer, a compile-safe Riverpod provider graph, token-projected theming, and a test pyramid whose expensive tiers stay thin because the surface proves wiring, not business logic.
+
+## Operating Contract
+
+1. Locate the architectural layer before editing. Views, view models, repositories, services, and domain models each have distinct responsibilities; a change that blurs them is wrong even when it works.
+2. The capability core owns business logic. The surface is wired to it through a typed client in the data layer — never re-implement a rule the core's contract already proves.
+3. Route durable mobile policy to the canonical docs (`docs/principles/stack/flutter/`) instead of duplicating it in code comments or this skill.
+4. Verify lints, widget tests, theme consumption, and accessibility semantics before declaring work complete.
+
+## Code intelligence (repo map + Serena)
+
+GroundWork gives you a deterministic **repo map** (`npx groundwork-method repo-map` — tree-sitter import edges + PageRank centrality, cached to `.groundwork/cache/repo-map.json`) and the **Serena** MCP server (LSP-backed symbol navigation and editing), registered at init. Orient before reading widely: refresh the map, read its `centrality` ranking to find the hubs, then use Serena to navigate them (`get_symbols_overview` / `find_symbol` / `find_referencing_symbols`) and make reference-aware edits (`replace_symbol_body` / `rename`). Full workflow and the graceful-degradation contract live in `.groundwork/skills/code-intelligence.md`; fall back to ordinary reads and edits when they are unavailable.
+
+## Core Pillars
+
+1. **MVVM Over Two Layers** — Every feature is one View (widgets only) paired with one ViewModel (state + commands). Repositories are the data layer's source of truth; services wrap external interfaces. A Domain layer is added only when it earns its place. This is the official Flutter architecture, adopted wholesale — code written against it is code every Flutter engineer recognises.
+
+2. **The Provider Graph Is the App** — Riverpod 3.x providers carry shared state and double as dependency injection. Construction order, disposal, and test substitution fall out of the graph. There is no service locator, no `provider`-package DI, and no GetX — ever.
+
+3. **Theming Is a Projection** — `ThemeData` is built from a palette module generated from the design system's brand tokens. Widgets consume `Theme.of(context)` and theme extensions; a `Color(0xFF...)` literal in a widget file is a review finding.
+
+4. **Tests Prove Wiring, Not Rules** — Widget tests are the bulk of coverage; `integration_test` happy paths run on a headless Android emulator; Patrol enters only at the Flutter/OS boundary. Business rules are proven once at the core's contract — surface tests never re-prove them.
+
+5. **Native Is a Disciplined Hatch** — Dropping to Swift/Kotlin is a capability decision made through Pigeon's typed boundary, wrapped as a data-layer service. Never a performance reflex, never a raw `MethodChannel` for a real API surface.
+
+## How to Use This Skill
+
+**Orient first.** On any non-trivial task, refresh the repo map (`npx groundwork-method repo-map`), read its `centrality` ranking to find the hubs, and navigate them with Serena before reading widely (see Code intelligence above) — this is the first step, not optional; fall back to ordinary reads only when those tools are unavailable. Then match the user's task to the smallest relevant reference set. Most tasks touch one or two references.
+
+| Topic | Reference | Load When |
+|-------|-----------|-----------|
+| Architecture & Layers | `references/architecture.md` | Placing new code, understanding the MVVM/repository split, file organization, the core-access seam. |
+| State Management | `references/state-management.md` | Providers, Notifiers, Mutations, ephemeral vs app state, provider testing seams. |
+| Widgets & Composition | `references/widgets-and-composition.md` | Building or refactoring widgets, const discipline, build purity, keys, extraction. |
+| Theming & Design Tokens | `references/theming-and-design-tokens.md` | Theme consumption, the generated palette, ThemeExtensions, dark mode, typography. |
+| Navigation | `references/navigation.md` | go_router routes, shell routes, redirects, typed routes, deep links. |
+| Data & Contracts | `references/data-and-contracts.md` | Repositories, services, the dio contract client, error mapping, contract-client tooling. |
+| Testing | `references/testing.md` | Unit/widget/integration taxonomy, fakes, emulator CI, Patrol, goldens, test commands. |
+| Platform Channels | `references/platform-channels.md` | Pigeon APIs, native modules, when to drop to Swift/Kotlin, SwiftPM wiring. |
+| Releases & Distribution | `references/releases-and-distribution.md` | Signing, CI/CD pipelines, versioning, forced upgrade, Shorebird code push. |
+| Accessibility | `references/accessibility.md` | Semantics, tap targets, dynamic type, contrast, a11y-driven testing. |
+| Security | `references/security.md` | Secure storage vs SharedPreferences, no secrets in the bundle, cert pinning, deep-link/intent validation, biometrics. |
+| Performance & Reliability | `references/performance-and-reliability.md` | Frame budget, rebuild discipline, list/image memory, isolates, retry/offline, graceful degradation. |
+| Observability | `references/observability.md` | Crash/error reporting, structured breadcrumbs, client performance traces, PII discipline. |
+| Documentation | `references/documentation.md` | Dartdoc on public API, naming-as-documentation, structure-as-documentation, why-comments. |
+
+## Task Routing
+
+- **New feature/screen** → Load `references/architecture.md`. One View + one ViewModel under `ui/<feature>/`; repository access only through the view model.
+- **State or data-flow work** → Load `references/state-management.md`. Verify what is app state (provider) vs ephemeral (`setState`).
+- **UI/visual work** → Load `references/widgets-and-composition.md` and `references/theming-and-design-tokens.md`. Check the generated palette before adding any colour.
+- **API/contract work** → Load `references/data-and-contracts.md`. The client is the seam; repositories translate payloads to domain models.
+- **Routing/deep-link work** → Load `references/navigation.md`. Check the existing route table conventions first.
+- **Test work** → Load `references/testing.md`. Pick the cheapest tier that can carry the assertion.
+- **Native capability work** → Load `references/platform-channels.md`. Check pub.dev for a maintained plugin before writing native code.
+- **Release/store work** → Load `references/releases-and-distribution.md`. Signing material never enters the repo.
+- **Security / secure-storage work** → Load `references/security.md`. The client is hostile territory; secrets and trust live server-side.
+- **Performance or offline/resilience work** → Load `references/performance-and-reliability.md`. SLOs and load shedding live in the core, not the client.
+
+## Safety Gates
+
+- Do not put business logic in widgets or `build` methods — it belongs in the view model, or more likely in the capability core.
+- Do not introduce hardcoded colours, text styles, radii, or spacing. The theme module is generated from brand tokens.
+- Do not add state-management or DI packages (`provider`, `get_it`, GetX, Bloc) without a recorded decision; Riverpod is the standing default.
+- Do not re-implement a rule the core's contract proves, and do not hand-map a large promoted contract — generated clients exist for that.
+- Do not build on experimental Riverpod APIs (offline persistence) in load-bearing paths.
+- Run `flutter analyze` and `flutter test` where the SDK is available; report the tier as skipped (never silently green) where it is not.
+
+## Hallucination Controls
+
+Before presenting Flutter guidance as factual:
+
+- Check `pubspec.yaml` for actual package versions and available dependencies.
+- Check the existing `ui/`, `data/`, and `domain/` directories for naming conventions and patterns before proposing new ones.
+- Check the generated theme module for colour and shape values before recommending visual changes.
+- Check the route table in the router module before inventing paths or navigation flows.
+- Label any recommendation based on general Flutter knowledge (rather than project-specific patterns) as an inference.
+
+## Output Expectations
+
+- Feature changes name the layer each file belongs to and why.
+- UI changes reference the theme roles or extensions used, or justify an explicit deviation.
+- New features include accessibility considerations (semantic labels, tap targets, dynamic type behaviour).
+- Verification steps include the specific Nx targets or `flutter` commands to run, with the skipped-with-reason caveat when the SDK is absent.
+- Recommendations distinguish project conventions from general Flutter practice.
+
+## Antipatterns
+
+Reject these patterns:
+
+- **Logic in build methods** — Domain branching inside widgets instead of the view model. Build renders state.
+- **setState as architecture** — App state held in `StatefulWidget`s and threaded through constructors. Ephemeral state only.
+- **Hardcoded visual values** — Hex colours, raw `TextStyle`s, magic paddings that fork the design system silently.
+- **Hand-written clients for large promoted contracts** — The contract is promoted precisely so clients can be generated from it.
+- **Re-proving core logic on the surface** — Surface tests assert wiring and rendering; the contract suite already proved the rules.
+- **Fat integration suites** — Emulator minutes are the most expensive test currency; widget tests carry the bulk.
+- **Raw MethodChannels for real APIs** — Stringly-typed, runtime-failing. Pigeon exists.
+- **Preemptive Domain layers** — Pass-through use-case classes add indirection and remove nothing.

package/src/engineer-skills/groundwork-flutter-engineer/references/accessibility.md

@@ -0,0 +1,92 @@
+# Accessibility
+
+## Table of Contents
+- [The Baseline](#the-baseline)
+- [Semantics](#semantics)
+- [Tap Targets](#tap-targets)
+- [Dynamic Type](#dynamic-type)
+- [Contrast](#contrast)
+- [Accessibility as the Test Seam](#accessibility-as-the-test-seam)
+- [Review Checklist](#review-checklist)
+
+---
+
+## The Baseline
+
+Accessibility is a merge gate, not a backlog item. The baseline for every feature: semantic labels on interactive widgets, 48dp tap targets, WCAG AA contrast (inherited from the token palette), and layouts that survive large text scales. An accessibility failure blocks the slice the way a failing test does.
+
+## Semantics
+
+Every interactive widget exposes a meaningful semantic label — through the widget's built-in semantics (`Text`, `Tooltip`, button labels) or an explicit `Semantics` wrapper when the visual content alone is ambiguous:
+
+```dart
+// Icon-only button: the tooltip doubles as the semantic label.
+IconButton(
+  icon: const Icon(Icons.refresh),
+  tooltip: 'Refresh gateway status',
+  onPressed: onRefresh,
+)
+
+// Composite tile whose meaning isn't the sum of its texts:
+Semantics(
+  label: 'Order ${order.id}, ${order.statusLabel}',
+  button: true,
+  child: OrderTile(order: order),
+)
+```
+
+Guidelines:
+
+- Labels describe **meaning, not appearance** ("Refresh gateway status", not "circular arrow icon").
+- Don't over-wrap: redundant `Semantics` around already-labelled widgets produces double announcements. Use `MergeSemantics` to combine fragments that should read as one.
+- Purely decorative visuals get `ExcludeSemantics`.
+- Dynamic state (loading, error) is announced — render it as text or update the label, don't communicate it by colour alone.
+
+## Tap Targets
+
+Interactive targets meet the **48dp minimum** in both dimensions. Material widgets enforce this by default (`materialTapTargetSize`); the rule bites with custom `GestureDetector`/`InkWell` wrappers around small visuals:
+
+```dart
+// Small visual, full-size target:
+InkWell(
+  onTap: onTap,
+  child: const SizedBox(
+    width: 48,
+    height: 48,
+    child: Center(child: Icon(Icons.close, size: 20)),
+  ),
+)
+```
+
+## Dynamic Type
+
+Layouts must not break at large text scales. Practical rules:
+
+- Never set fixed heights on text-bearing containers; let text size drive layout.
+- Test at scale: pump widget tests with `MediaQuery(textScaler: TextScaler.linear(2.0))` for layout-sensitive components, and exercise device large-text settings during manual passes.
+- Truncation (`overflow: TextOverflow.ellipsis`) is for genuinely unbounded user content, not a fix for layouts that can't absorb scale.
+
+## Contrast
+
+Contrast meets WCAG AA **via the token palette** — it is enforced at the design-system layer and inherited here. The implementation duty: consume theme roles (see `references/theming-and-design-tokens.md`) so the audited pairs stay paired. Hand-mixed colours (opacity hacks, lightened variants) silently break audited contrast and are review findings on two counts.
+
+## Accessibility as the Test Seam
+
+Flutter's semantics tree is also the widget-test seam: tests find by `find.bySemanticsLabel` and visible text, so **inaccessible UI is untestable UI**. This makes the baseline self-enforcing — a widget you cannot address semantically in a test is a widget a screen reader cannot address either. When a test reaches for `find.byType` or a key because nothing semantic exists, treat it as the accessibility defect it is and label the widget.
+
+```dart
+testWidgets('refresh is reachable by semantics', (tester) async {
+  await tester.pumpWidget(harness());
+  expect(find.bySemanticsLabel('Refresh gateway status'), findsOneWidget);
+});
+```
+
+## Review Checklist
+
+- [ ] Every interactive widget has a meaningful semantic label.
+- [ ] Icon-only buttons carry `tooltip` or `Semantics`.
+- [ ] Custom gesture surfaces meet 48dp.
+- [ ] No state communicated by colour alone.
+- [ ] Layout verified (or tested) at 2.0 text scale.
+- [ ] All colours via theme roles — no hand-mixed variants.
+- [ ] Widget tests find by semantics, not widget types.

package/src/engineer-skills/groundwork-flutter-engineer/references/architecture.md

@@ -0,0 +1,189 @@
+# Architecture
+
+## Table of Contents
+- [The Layer Model](#the-layer-model)
+- [File Organization](#file-organization)
+- [Views and ViewModels](#views-and-viewmodels)
+- [Repositories and Services](#repositories-and-services)
+- [The Core-Access Seam](#the-core-access-seam)
+- [Domain Models and Immutability](#domain-models-and-immutability)
+- [When a Domain Layer Is Earned](#when-a-domain-layer-is-earned)
+- [Placement Checklist](#placement-checklist)
+
+---
+
+## The Layer Model
+
+This codebase follows the official Flutter architecture: a **UI layer** of MVVM features over a **data layer** of repositories and services. A Domain layer of use-cases exists only where it has earned its place. Dependency direction is strict and single-direction:
+
+```
+View  →  ViewModel  →  Repository (abstract)  →  Service (ApiClient, platform APIs)
+                              ↓
+                       domain models
+```
+
+- A View never imports a repository, a service, or `dio`.
+- A ViewModel never imports widgets or `BuildContext`.
+- A repository never imports another repository — cross-repository orchestration belongs in a view model (or an earned use-case).
+- Services are stateless and never aware of repositories.
+
+The app is a **surface adapter** over the workspace's capability core. Business rules live behind the promoted contracts and are proven there; if you find yourself implementing a pricing rule, a permission check, or validation semantics in Dart, stop — that logic belongs in the core, and the surface renders its results.
+
+---
+
+## File Organization
+
+`ui/` is feature-first; `data/` and `domain/` are type-first:
+
+```
+lib/
+├── main.dart                  # ProviderScope root — nothing else
+├── app.dart                   # MaterialApp.router + theme wiring
+├── router.dart                # the go_router route table
+├── config/app_config.dart     # --dart-define configuration
+├── ui/
+│   ├── core/theme/            # generated palette + theme builder
+│   └── <feature>/
+│       ├── <feature>_view.dart
+│       └── <feature>_view_model.dart
+├── data/
+│   ├── repositories/          # <entity>_repository.dart: abstract + impl
+│   └── services/              # api_client.dart, platform service wrappers
+└── domain/
+    └── models/                # immutable models
+```
+
+Naming is the official convention and is load-bearing — predictable names are how the next agent finds the right file on the first try: `HomeView`/`HomeViewModel`, `UserRepository`/`RemoteUserRepository`, `AuthService`. Do not invent variants (`HomeScreen`, `HomeController`, `UserStore`).
+
+For large apps, split features into local packages with Dart pub workspaces (`resolution: workspace`); Melos 7.x (configured under the `melos:` key in the root pubspec) handles scripts and versioning. Layer-first roots (`/screens`, `/widgets`, `/models`) are legacy — do not recreate them.
+
+---
+
+## Views and ViewModels
+
+Every feature is exactly one View paired with exactly one ViewModel.
+
+**The View** is widgets only — layout, animation, conditional rendering, simple navigation calls. It watches its view model provider and dispatches commands:
+
+```dart
+class ProfileView extends ConsumerWidget {
+  const ProfileView({super.key});
+
+  @override
+  Widget build(BuildContext context, WidgetRef ref) {
+    final state = ref.watch(profileViewModelProvider);
+    return state.when(
+      loading: () => const CircularProgressIndicator(),
+      error: (e, _) => ErrorPanel(error: e),
+      data: (profile) => ProfileBody(
+        profile: profile,
+        onRename: (name) =>
+            ref.read(profileViewModelProvider.notifier).rename(name),
+      ),
+    );
+  }
+}
+```
+
+**The ViewModel** is an `AsyncNotifier` (or `Notifier` for synchronous state) exposing an immutable state object and methods as commands:
+
+```dart
+class ProfileViewModel extends AsyncNotifier<ProfileState> {
+  @override
+  Future<ProfileState> build() async {
+    final user = await ref.watch(userRepositoryProvider).current();
+    return ProfileState(user: user);
+  }
+
+  Future<void> rename(String name) async {
+    state = const AsyncLoading();
+    state = await AsyncValue.guard(() async {
+      final user = await ref.read(userRepositoryProvider).rename(name);
+      return ProfileState(user: user);
+    });
+  }
+}
+```
+
+Red flags: a `build` method with an `if` on a domain rule; a view model importing `material.dart`; a widget calling a repository.
+
+---
+
+## Repositories and Services
+
+**Repositories** are the source of truth. They own caching, retry, polling, and translating contract payloads into domain models. Always an abstract class plus an implementation, exposed as a provider:
+
+```dart
+abstract class OrderRepository {
+  Future<List<Order>> recent();
+  Stream<Order> watch(String id);
+}
+
+class RemoteOrderRepository implements OrderRepository {
+  RemoteOrderRepository(this._client);
+  final ApiClient _client;
+  // translate contract DTOs → domain models here, nowhere else
+}
+
+final orderRepositoryProvider = Provider<OrderRepository>(
+  (ref) => RemoteOrderRepository(ref.watch(apiClientProvider)),
+);
+```
+
+The abstract class is the test seam: an in-memory `FakeOrderRepository` serves unit and widget tests without a mocking framework.
+
+**Services** are stateless wrappers over external interfaces — the contract client, platform APIs (via Pigeon), local storage — exposing `Future`/`Stream`. They hold no app state and know nothing about repositories or features.
+
+---
+
+## The Core-Access Seam
+
+The typed contract client lives in `data/services/` and is consumed only by repositories:
+
+- The client is **thin and hand-rolled while the contract surface is small**: one method per promoted-contract operation, typed models in `domain/models/`. (This is the recorded tooling stance; see `references/data-and-contracts.md`.)
+- When the promoted `openapi.yaml` grows past a handful of operations, switch to generated clients (`openapi_generator` dart-dio) — the repositories keep their shape, so nothing above the data layer changes.
+- **Nothing above the data layer knows the transport.** A view model cannot tell whether the core is REST or gRPC, hosted or embedded. If a view model is constructing URLs or reading `DioException`s, the seam has leaked.
+
+---
+
+## Domain Models and Immutability
+
+Domain models are immutable. Plain `const` classes suffice while models are trivial; introduce **freezed** when models carry real shape — unions, `copyWith`, exhaustive matching, JSON round-trips — because at that point its codegen earns the build_runner step:
+
+```dart
+@freezed
+sealed class Order with _$Order {
+  const factory Order.draft({required String id}) = DraftOrder;
+  const factory Order.placed({required String id, required DateTime at}) = PlacedOrder;
+  factory Order.fromJson(Map<String, dynamic> json) => _$OrderFromJson(json);
+}
+```
+
+Never add a mutable field to a domain model to "simplify" an update path — that is the unidirectional flow breaking.
+
+---
+
+## When a Domain Layer Is Earned
+
+Add a use-case class only when at least one of these is true:
+
+1. Logic **merges multiple repositories** (and would otherwise live awkwardly in one view model).
+2. The logic is **genuinely complex** and burying it in a view model harms testability.
+3. The logic is **reused across view models**.
+
+A use-case that forwards a single repository call is indirection tax — delete it. Default is two layers.
+
+---
+
+## Placement Checklist
+
+Before creating a file, answer:
+
+| The code... | It goes in |
+|---|---|
+| renders widgets | `ui/<feature>/<feature>_view.dart` |
+| holds feature state / handles user events | `ui/<feature>/<feature>_view_model.dart` |
+| decides which data is the truth (cache, retry, merge) | `data/repositories/` |
+| talks to the network, OS, or storage | `data/services/` |
+| is a value the app passes around | `domain/models/` |
+| is a business rule | the capability core, not this app |

package/src/engineer-skills/groundwork-flutter-engineer/references/data-and-contracts.md

@@ -0,0 +1,136 @@
+# Data and Contracts
+
+## Table of Contents
+- [The Seam](#the-seam)
+- [The Thin Client (Current Stance)](#the-thin-client-current-stance)
+- [When to Switch to Generated Clients](#when-to-switch-to-generated-clients)
+- [Repositories: Translation and Truth](#repositories-translation-and-truth)
+- [Error Mapping](#error-mapping)
+- [Configuration](#configuration)
+- [dio Conventions](#dio-conventions)
+- [Anti-patterns](#anti-patterns)
+
+---
+
+## The Seam
+
+The app reaches the capability core through exactly one seam:
+
+```
+ViewModel → Repository (abstract) → ApiClient (data/services/) → gateway
+```
+
+Nothing above the data layer knows the transport. A view model cannot tell whether the core is hosted or embedded, REST or gRPC. If transport details (URLs, status codes, `DioException`) appear above `data/`, the seam has leaked — fix the leak before the feature.
+
+## The Thin Client (Current Stance)
+
+The recorded contract-tooling stance (O8, settled 2026-06-12): while the promoted contract surface is small, the client is **hand-rolled and thin** — one method per contract operation, typed models in `domain/models/`, no codegen dependency:
+
+```dart
+class ApiClient {
+  ApiClient(this._dio);
+  final Dio _dio;
+
+  Future<Order> order(String id) async {
+    final res = await _dio.get<Map<String, dynamic>>('/api/v1/orders/$id');
+    return Order.fromJson(res.data ?? const {});
+  }
+
+  Future<Order> placeOrder(PlaceOrderRequest req) async {
+    final res = await _dio.post<Map<String, dynamic>>(
+      '/api/v1/orders',
+      data: req.toJson(),
+    );
+    return Order.fromJson(res.data ?? const {});
+  }
+}
+```
+
+Discipline that keeps "thin" honest:
+
+- Every method maps 1:1 to a promoted-contract operation — the method set is the contract's operation list, nothing speculative.
+- Request/response models live in `domain/models/` with explicit `fromJson`/`toJson` that match the contract schema field-for-field.
+- When the contract changes, the client changes in the same slice — the promoted `openapi.yaml` is the source of truth, and drift between it and this client is a defect.
+
+## When to Switch to Generated Clients
+
+The thin client is the lightest path **while the surface is small**. Once the promoted `openapi.yaml` grows past a handful of operations (or starts carrying complex schemas you are hand-mapping), switch to generation: `openapi_generator`'s **dart-dio** output via build_runner, consuming the promoted spec directly.
+
+The migration is contained by construction: repositories keep consuming a client; only the client's implementation becomes generated. Nothing above the data layer changes. Hand-mapping a large promoted contract is the defect the principles warn about — the contract is promoted precisely so clients can be generated from it.
+
+## Repositories: Translation and Truth
+
+Repositories own the boundary between contract types and domain models:
+
+```dart
+class RemoteOrderRepository implements OrderRepository {
+  RemoteOrderRepository(this._client);
+  final ApiClient _client;
+
+  List<Order>? _cache;
+
+  @override
+  Future<List<Order>> recent({bool refresh = false}) async {
+    if (!refresh && _cache != null) return _cache!;
+    _cache = await _client.recentOrders();
+    return _cache!;
+  }
+}
+```
+
+- Caching, retry policy, polling, and merge logic live here — not in view models, not in the client.
+- Contract DTO → domain model translation happens here and nowhere else.
+- Repositories are many-to-many with view models and never aware of each other.
+
+## Error Mapping
+
+The data layer converts transport failures into domain-meaningful states; `DioException` never crosses upward:
+
+```dart
+@override
+Future<HealthStatus> status() async {
+  try {
+    return await _client.health();
+  } on DioException catch (e) {
+    if (e.type == DioExceptionType.connectionTimeout ||
+        e.type == DioExceptionType.connectionError) {
+      return const HealthStatus.unreachable();
+    }
+    rethrow; // programming errors still surface loudly
+  }
+}
+```
+
+Rules of thumb:
+
+- **Expected failures** (offline, gateway down, 404 on an optional resource) become domain states the UI renders.
+- **Contract violations** (schema mismatch, unexpected 500s) surface as errors — they indicate a defect, and the view renders the error state.
+- Business rules about failures (retry budgets, "is this recoverable") still do not belong in views.
+
+## Configuration
+
+The gateway URL arrives at build time via `--dart-define`:
+
+```dart
+static const String apiBaseUrl = String.fromEnvironment(
+  'API_BASE_URL',
+  defaultValue: 'http://localhost:4000',
+);
+```
+
+- Android emulator → host: `http://10.0.2.2:4000`. iOS simulator → `http://localhost:4000`.
+- No `.env` files baked into the binary; no secrets in `--dart-define` either — a mobile binary is fully inspectable, so anything secret stays server-side.
+
+## dio Conventions
+
+- One `Dio` instance, configured in the client provider: `baseUrl`, timeouts, `Accept: application/json`.
+- Cross-cutting concerns (auth header injection, logging, retry) are **interceptors** on that instance — not per-call options scattered through methods.
+- dio throws on non-2xx by default; keep that behaviour and map in repositories rather than checking status codes inline.
+
+## Anti-patterns
+
+- **Transport above the data layer** — a view model importing `dio` or parsing status codes.
+- **Hand-mapping a grown contract** — switch to dart-dio generation; the seam is built for it.
+- **Speculative client methods** — operations the promoted contract does not define.
+- **Business rules in the surface** — validation semantics, pricing, permissions re-implemented in Dart. The core proves them; the surface renders results.
+- **Repositories calling repositories** — orchestration belongs in a view model or an earned use-case.

package/src/engineer-skills/groundwork-flutter-engineer/references/documentation.md

@@ -0,0 +1,122 @@
+# Documentation
+
+## Table of Contents
+- [Hierarchy](#hierarchy)
+- [Dartdoc on Public API](#dartdoc-on-public-api)
+- [Names Are the Documentation](#names-are-the-documentation)
+- [Structure as Documentation](#structure-as-documentation)
+- [Inline Comments](#inline-comments)
+- [A Comment Is Often a Smell](#a-comment-is-often-a-smell)
+- [In-Code Markers](#in-code-markers)
+- [What NOT to Document](#what-not-to-document)
+
+---
+
+Dart ships its documentation discipline in the toolchain: `dart doc` renders `///` comments to API pages, the formatter normalises them, and the `public_member_api_docs` lint flags missing ones on a public surface. The language — sound null safety, immutable widgets, `const` — is built so that well-shaped code carries most of its own meaning. Lean on that before reaching for prose.
+
+## Hierarchy
+
+Structure documents more reliably than comments. A comment is a promise no analyzer checks; when the widget tree changes, the comment silently lies. Documentation priority — the foundations principle (`docs/principles/foundations/documentation.md`) written the Flutter way:
+
+1. **Types and null safety** — the analyzer rejects incorrect types and unhandled nulls. Zero drift risk.
+2. **Naming** — the official View/ViewModel/Repository conventions, which are load-bearing (`references/architecture.md`). Rename before you comment.
+3. **`const` and immutability** — an immutable model and a `const` constructor declare intent the analyzer enforces (`references/widgets-and-composition.md`).
+4. **Test names** — a widget test named for its behaviour is executable documentation verified by CI.
+5. **Dartdoc `///` on public API** — rendered by `dart doc`; written only when types cannot carry the contract.
+6. **Inline "why" comments** — last resort for a genuinely non-obvious decision.
+
+Levels 1–4 are verified by tooling. Levels 5–6 are human promises that drift. Minimise them.
+
+## Dartdoc on Public API
+
+A dartdoc comment uses `///`, leads with a one-sentence summary, and references other API in square brackets so `dart doc` links them:
+
+```dart
+/// Holds stock for an [order] until the reservation TTL expires.
+///
+/// Throws [OutOfStockException] when the requested quantity is unavailable.
+Future<Reservation> reserve(Order order, int quantity);
+```
+
+Document the **public** surface — the exported API a consumer in another library calls. A private widget (`_Header`) is read with the build method that uses it; a doc comment there usually restates the code below.
+
+State what the signature cannot: the exceptions a caller must catch, the lifecycle of a returned `Stream`, the units of a parameter. Do not narrate the type.
+
+```dart
+// BAD — restates the signature
+/// Returns the user with the given id.
+Future<User> getUser(String id);
+
+// GOOD — skip it; the name + types already say this
+Future<User> getUser(String id);
+```
+
+## Names Are the Documentation
+
+The cheapest documentation is the official name. The architecture conventions are not style preferences — `ProfileView`/`ProfileViewModel`, `OrderRepository`/`RemoteOrderRepository`, `AuthService` are how the next agent finds the right file on the first try (`references/architecture.md`). A `HomeController` or `UserStore` documents nothing because it matches no convention.
+
+A small, single-purpose widget names its job in its class declaration:
+
+```dart
+// The name is the contract; no comment adds anything.
+class OrderStatusBadge extends StatelessWidget {
+  const OrderStatusBadge({super.key, required this.status});
+  final OrderStatus status;
+  // ...
+}
+```
+
+## Structure as Documentation
+
+A composed widget tree documents itself when it is built from small, named, `const` pieces. A `build` method that reads as a list of well-named child widgets needs no comment to explain its layout — the composition *is* the explanation (`references/widgets-and-composition.md`).
+
+This is why `Widget _buildHeader()` helpers are a documentation failure as much as a performance one: a method named `_buildHeader` hides a subtree behind a verb, where an extracted `_Header` widget names the thing. Extract the widget; the name replaces the comment.
+
+Immutability documents the data flow. A `freezed` sealed union spells out every state a value can hold, exhaustively matched at the call site — prose listing "the order can be draft, placed, or cancelled" is the type, written worse (`references/architecture.md`).
+
+## Inline Comments
+
+Inline comments explain **why**, never **what**. The widget already says what it renders; the comment captures the reason the next reader cannot recover from the tree.
+
+```dart
+// LayoutBuilder, not MediaQuery: this card also renders inside a side
+// pane and a test harness, where screen size is the wrong signal.
+return LayoutBuilder(builder: (context, constraints) { /* ... */ });
+```
+
+A comment narrating the obvious is noise — the reader can see the `Column`.
+
+```dart
+// BAD — narrates the tree
+// a column with a title and a body
+return Column(children: [Title(), Body()]);
+```
+
+## A Comment Is Often a Smell
+
+When you reach for a comment to explain *what* a block does, the widget is asking to be refactored. The comment is debt; the fix is in the code:
+
+- A comment heading a chunk of a long `build` → extract a named widget.
+- A comment explaining a magic number → move it to the theme/density system as a named token (`references/theming-and-design-tokens.md`).
+- A comment decoding a boolean argument → name the parameter or introduce an enum.
+- A comment explaining why a field is mutable → it should be immutable; the comment is covering a broken data flow.
+
+Delete the comment and fix the structure. The refactor cannot drift; the comment can.
+
+## In-Code Markers
+
+```dart
+// TODO(bob): paginate once the repository exposes a cursor. Issue #231.
+// FIXME(carol): rebuild storm when the parent re-themes. Issue #245.
+// HACK(dave): clamp negative durations from the platform clock until SDK fix.
+```
+
+Always include `(username)` and an issue reference. A marker without one will never be resolved.
+
+## What NOT to Document
+
+- Self-evident widgets where the class name and props tell the whole story.
+- Private widgets (`_Header`) read in context with their parent's build method.
+- `@override Widget build(...)` — never document an override the framework defines.
+- Provider declarations whose name states what they expose (`orderRepositoryProvider`).
+- Generated code (`*.g.dart`, `*.freezed.dart`) — never hand-edit comments into it.