groundwork-method 0.0.1 → 0.10.0

package/src/generators/electron-app/generator.ts

@@ -0,0 +1,288 @@
+import {
+  formatFiles,
+  generateFiles,
+  Tree,
+  names,
+} from '@nx/devkit';
+import * as path from 'path';
+import { recordGeneratorProvenance } from '../shared/provenance';
+import {
+  promoteEngineerSkill,
+  deployStackDocs,
+  registerRunner,
+} from '../shared/scaffold-helpers';
+
+export interface ElectronAppGeneratorSchema {
+  name: string;
+  org?: string;
+}
+
+const BRAND_TOKENS_PATH = '.groundwork/config/brand-tokens.json';
+
+/** Palette roles the visual block commits to (templates/brand-tokens.md). */
+const PALETTE_ROLES = [
+  'primary',
+  'accent',
+  'surface',
+  'surfaceAlt',
+  'textBody',
+  'success',
+  'error',
+  'warning',
+  'info',
+] as const;
+
+/** camelCase palette role → kebab-case CSS custom property suffix. */
+function cssRoleName(role: string): string {
+  return role.replace(/[A-Z]/g, (c) => '-' + c.toLowerCase());
+}
+
+/** Neutral defaults used when no visual block (or no tokens at all) exists.
+ *  Mirrors how cli-app and flutter-app degrade: the app still themes
+ *  coherently, it just wears a restrained default brand. */
+const NEUTRAL_PALETTE: Record<string, { light: string; dark: string }> = {
+  primary: { light: '#3b6fd4', dark: '#7da7ef' },
+  accent: { light: '#7a5fd4', dark: '#b3a1f0' },
+  surface: { light: '#fafafa', dark: '#17181c' },
+  surfaceAlt: { light: '#f0f1f4', dark: '#1f2127' },
+  textBody: { light: '#26282e', dark: '#e4e6eb' },
+  success: { light: '#2f9e6e', dark: '#5fc398' },
+  error: { light: '#cf4444', dark: '#ef7f7f' },
+  warning: { light: '#c08a1f', dark: '#e0b35f' },
+  info: { light: '#3b6fd4', dark: '#7da7ef' },
+};
+
+const NEUTRAL_TYPOGRAPHY = {
+  display: { family: 'Inter', weight: 600 },
+  body: { family: 'Inter', weight: 400 },
+};
+
+const NEUTRAL_RADIUS = '8px';
+
+/** The renderer is CSS, so colour values pass through verbatim — the browser
+ *  resolves OKLCH natively (unlike the Dart projection, which converts at
+ *  generation time). Validation still gates what enters the file: a value the
+ *  regexes cannot recognise falls back to the neutral default instead of
+ *  emitting broken CSS. */
+function validCssColor(value: unknown): string | null {
+  if (typeof value !== 'string') return null;
+  const v = value.trim();
+  if (/^#([0-9a-fA-F]{3}|[0-9a-fA-F]{6})$/.test(v)) return v.toLowerCase();
+  if (/^oklch\(\s*[\d.]+%?\s+[\d.]+\s+[\d.]+(?:deg)?\s*\)$/i.test(v)) return v;
+  return null;
+}
+
+/** Validate a radius descriptor like "8px" / "0.5rem" / "12"; bare numbers are
+ *  treated as logical pixels. */
+function validCssRadius(value: unknown): string | null {
+  if (typeof value !== 'string' && typeof value !== 'number') return null;
+  const m = String(value)
+    .trim()
+    .match(/^([\d.]+)\s*(px|rem)?$/i);
+  if (!m || !Number.isFinite(parseFloat(m[1]))) return null;
+  return `${m[1]}${(m[2] || 'px').toLowerCase()}`;
+}
+
+interface ResolvedBrand {
+  palette: Record<string, { light: string; dark: string }>; // CSS color values
+  typography: {
+    display: { family: string; weight: number };
+    body: { family: string; weight: number };
+  };
+  radius: string;
+  source: 'visual-block' | 'identity-only' | 'default';
+}
+
+/** Project the design system's brand tokens into theme inputs. Three cases,
+ *  mirroring the cli-app/flutter-app token handling:
+ *   - a Tier 2 `visual` block → full projection (palette roles, typography, shape)
+ *   - Tier-1-only tokens → palette seeded from identity.primary/accent
+ *   - no tokens → the neutral default */
+function resolveBrand(tree: Tree): ResolvedBrand {
+  const palette: Record<string, { light: string; dark: string }> = {};
+  for (const role of PALETTE_ROLES) {
+    palette[role] = { ...NEUTRAL_PALETTE[role] };
+  }
+  const typography = {
+    display: { ...NEUTRAL_TYPOGRAPHY.display },
+    body: { ...NEUTRAL_TYPOGRAPHY.body },
+  };
+  let radius = NEUTRAL_RADIUS;
+  let source: ResolvedBrand['source'] = 'default';
+
+  if (!tree.exists(BRAND_TOKENS_PATH)) {
+    return { palette, typography, radius, source };
+  }
+
+  let raw: any = null;
+  try {
+    raw = JSON.parse(tree.read(BRAND_TOKENS_PATH, 'utf-8') || '{}');
+  } catch {
+    return { palette, typography, radius, source }; // malformed — neutral
+  }
+
+  const visual = raw?.visual;
+  if (visual && typeof visual === 'object') {
+    source = 'visual-block';
+    for (const role of PALETTE_ROLES) {
+      const entry = visual.palette?.[role];
+      const light = validCssColor(entry?.light);
+      const dark = validCssColor(entry?.dark);
+      if (light) palette[role].light = light;
+      if (dark) palette[role].dark = dark;
+    }
+    if (visual.typography?.display?.family) {
+      typography.display.family = String(visual.typography.display.family);
+      typography.display.weight =
+        Number(visual.typography.display.weight) || typography.display.weight;
+    }
+    if (visual.typography?.body?.family) {
+      typography.body.family = String(visual.typography.body.family);
+      typography.body.weight =
+        Number(visual.typography.body.weight) || typography.body.weight;
+    }
+    radius = validCssRadius(visual.shape?.radiusBase) ?? NEUTRAL_RADIUS;
+    return { palette, typography, radius, source };
+  }
+
+  // Tier-1-only tokens: derive the brand colours from identity, keep the
+  // neutral chrome. This is the mechanical Tier-1 projection the brand-tokens
+  // contract requires of every consumer.
+  const identity = raw?.identity;
+  if (identity && typeof identity === 'object') {
+    source = 'identity-only';
+    const primary = validCssColor(identity.primary);
+    const accent = validCssColor(identity.accent);
+    if (primary) {
+      palette.primary = { light: primary, dark: primary };
+      palette.info = { light: primary, dark: primary };
+    }
+    if (accent) palette.accent = { light: accent, dark: accent };
+  }
+
+  return { palette, typography, radius, source };
+}
+
+/** Render the generated brand stylesheet. The CSS custom properties are the
+ *  projection artifact (regenerate, never hand-edit); the static main.css maps
+ *  them into Tailwind theme tokens via `@theme inline`, so components consume
+ *  utilities, never these variables directly. */
+function renderBrandCss(brand: ResolvedBrand): string {
+  const lines: string[] = [];
+  lines.push('/* GENERATED by the GroundWork electron-app generator from');
+  lines.push(
+    ' * .groundwork/config/brand-tokens.json — do not hand-edit this file.',
+  );
+  lines.push(' *');
+  lines.push(
+    ' * Re-run the design system to evolve the brand, then regenerate (or update',
+  );
+  lines.push(
+    ' * this file to match brand-tokens.json). Components never read these',
+  );
+  lines.push(
+    ' * variables directly: main.css maps them into Tailwind theme tokens, and',
+  );
+  lines.push(
+    ' * components consume the utilities (docs/principles/stack/typescript/frontend.md).',
+  );
+  lines.push(` * Projection source: ${brand.source}.`);
+  lines.push(' */');
+  lines.push('');
+  lines.push('/* Palette roles — light theme. */');
+  lines.push(':root {');
+  for (const role of PALETTE_ROLES) {
+    lines.push(`  --gw-${cssRoleName(role)}: ${brand.palette[role].light};`);
+  }
+  lines.push('');
+  lines.push('  /* Typography (bundle or system-load the families to take effect). */');
+  lines.push(
+    `  --gw-font-display: '${brand.typography.display.family.replace(/'/g, '')}';`,
+  );
+  lines.push(`  --gw-font-display-weight: ${brand.typography.display.weight};`);
+  lines.push(
+    `  --gw-font-body: '${brand.typography.body.family.replace(/'/g, '')}';`,
+  );
+  lines.push(`  --gw-font-body-weight: ${brand.typography.body.weight};`);
+  lines.push('');
+  lines.push('  /* Shape. */');
+  lines.push(`  --gw-radius-base: ${brand.radius};`);
+  lines.push('}');
+  lines.push('');
+  lines.push('/* Palette roles — dark theme. The attribute is set from the');
+  lines.push(' * nativeTheme broadcast (src/renderer/src/main.tsx). */');
+  lines.push(":root[data-theme='dark'] {");
+  for (const role of PALETTE_ROLES) {
+    lines.push(`  --gw-${cssRoleName(role)}: ${brand.palette[role].dark};`);
+  }
+  lines.push('}');
+  lines.push('');
+  return lines.join('\n');
+}
+
+export default async function (tree: Tree, options: ElectronAppGeneratorSchema) {
+  const serviceNames = names(options.name);
+  const projectRoot = `services/${serviceNames.fileName}`;
+  const org = options.org || 'com.example';
+  // Reverse-domain application id (macOS bundle id, Windows AppUserModelID).
+  const appId = `${org}.${serviceNames.fileName.replace(/-/g, '')}`;
+
+  const templateOptions = {
+    ...options,
+    ...serviceNames,
+    org,
+    appId,
+    tmpl: '', // required by generateFiles
+  };
+
+  generateFiles(
+    tree,
+    path.join(__dirname, '..', '..', '..', '..', 'src', 'generators', 'electron-app', 'files'),
+    projectRoot,
+    templateOptions,
+  );
+
+  // Project brand-tokens.json's visual block into the renderer's CSS custom
+  // properties — the same Tailwind path nextjs-app uses, generated instead of
+  // hand-authored.
+  tree.write(
+    `${projectRoot}/src/renderer/src/assets/brand.css`,
+    renderBrandCss(resolveBrand(tree)),
+  );
+
+  deployStackDocs(tree, path.join(__dirname, '..', '..', '..', '..', 'src', 'generators', 'electron-app', 'docs'));
+
+  // An Electron app has no Docker boot — but it IS a managed unit. It never
+  // joins docker-compose.yml or the package.json workspaces list; instead it
+  // registers as a native runner so `./dev` start/stop/status/logs manage it
+  // like any other process. autostart: the desktop app comes up with `./dev
+  // start`. Its verification tiers are defined by the multi-surface contract:
+  // generation (snapshot), compilation (tsc + lint), boot (Playwright _electron
+  // under xvfb).
+  registerRunner(tree, {
+    name: serviceNames.fileName,
+    kind: 'surface',
+    cmd: 'bash tool/electron_exec.sh run',
+    cwd: projectRoot,
+    autostart: true,
+  });
+
+  promoteEngineerSkill(tree, 'groundwork-electron-engineer');
+
+  await formatFiles(tree);
+
+  recordGeneratorProvenance(tree, 'electron-app', options as unknown as Record<string, unknown>);
+
+  return () => {
+    // Deliberate deviation from the nextjs-app callback (which runs an install
+    // immediately): `npm install` here would pull the ~100 MB Electron binary
+    // into every scaffold run and every generation-test sandbox. Bootstrap is
+    // an explicit, guarded target instead — the same shape flutter-app uses
+    // for its SDK-dependent steps.
+    console.log(
+      `Scaffolded ${projectRoot}. Next steps:\n` +
+        `  npx nx run ${serviceNames.fileName}:bootstrap   # npm install (downloads the Electron binary)\n` +
+        `  npx nx run ${serviceNames.fileName}:smoke       # build + Playwright _electron boot smoke`,
+    );
+  };
+}

package/src/generators/electron-app/schema.json

@@ -0,0 +1,23 @@
+{
+  "$schema": "http://json-schema.org/schema",
+  "id": "electron-app",
+  "title": "Electron App",
+  "type": "object",
+  "properties": {
+    "name": {
+      "type": "string",
+      "description": "The name of the Electron application (surface slug)",
+      "$default": {
+        "$source": "argv",
+        "index": 0
+      },
+      "x-prompt": "What name would you like to use for the app?"
+    },
+    "org": {
+      "type": "string",
+      "description": "Reverse-domain organization identifier used for the macOS bundle id and the Windows AppUserModelID",
+      "default": "com.example"
+    }
+  },
+  "required": ["name"]
+}

package/src/generators/flutter-app/docs/principles/stack/flutter/architecture.md

@@ -0,0 +1,78 @@
+---
+title: Architecture
+description: MVVM over UI/Data layers, repositories and services, the core-access seam, freezed immutability, and the Riverpod default.
+status: active
+last_reviewed: 2026-06-12
+---
+# Architecture
+
+## TL;DR
+
+We follow the official Flutter architecture guide: a UI layer of MVVM features over a data layer of repositories and services, with a Domain layer added only when it earns its place. The capability core is reached through a typed contract client that lives in the data layer as a service — nothing above the data layer knows the transport. State management is Riverpod 3.x; models are immutable via `freezed`.
+
+## Why this matters
+
+Flutter spent years without an official architecture, and the vacuum filled with cargo-culted "Clean Architecture" folder mazes and state-management package wars. The Flutter team now ships a first-party, opinionated guide (MVVM + repositories), and we adopt it wholesale because an agent writing against the documented official pattern produces code every Flutter engineer and every future agent recognises — the training-set fluency axis applied within a stack.
+
+## The layers
+
+### UI and Data are mandatory; Domain is earned
+
+Two layers by default. The **UI layer** holds features; the **data layer** holds repositories and services. A **Domain layer** (use-cases) is added per-case only when logic merges multiple repositories, is genuinely complex, or is reused across view models — never preemptively, because empty pass-through use-cases are pure indirection tax.
+
+### MVVM in the UI layer
+
+Every feature is exactly one **View** paired with exactly one **ViewModel**:
+
+- The **View** is widgets only — layout, animation, conditional rendering, simple routing. No business logic, no direct repository access.
+- The **ViewModel** transforms repository data into UI state and exposes **commands** for user events. It is the only thing the View talks to.
+
+Naming follows the official convention: `HomeView`/`HomeViewModel`, `UserRepository`, `AuthService`. Predictable names are how an agent finds the right file on the first try.
+
+### Repositories and services in the data layer
+
+**Repositories** are the source of truth: they own caching, retry, polling, and the transformation of raw payloads into domain models. **Services** are stateless wrappers over external interfaces — API clients, platform APIs, local storage — exposing `Future`/`Stream`. Repositories consume services; they are many-to-many with view models and never aware of each other. View models depend on **abstract repository classes**, so tests substitute fakes without mocking frameworks.
+
+### The core-access seam
+
+A GroundWork Flutter app is a surface adapter over a headless capability core (see [capability core and surfaces](../../capability-core-and-surfaces.md)). The seam is precise:
+
+- A **typed client generated from the promoted contracts** (dio-based, via OpenAPI codegen — `openapi_generator`'s `dart-dio` path when sharing one HTTP stack) lives in the data layer **as a service**.
+- **Repositories consume that client** and translate contract types into domain models.
+- **Nothing above the data layer knows the transport.** A view model cannot tell whether the core is hosted or embedded, REST or gRPC — which is exactly what lets capability logic be proven once, headless, while the surface proves only wiring.
+
+Hand-rolled JSON mapping against an existing contract spec is a defect: the contract is promoted precisely so clients are generated from it.
+
+## Project organisation
+
+`ui/` is organised **by feature** (one folder per feature holding its view and view model); `data/` is organised **by type** (repositories and services are shared infrastructure, not feature property). For large apps, split features into local packages using Dart pub workspaces (`resolution: workspace`), with Melos 7.x — now configured under the `melos:` key in the root pubspec — for scripts and versioning. Layer-first roots (`/screens`, `/widgets`, `/models`) are legacy for anything non-trivial.
+
+## Immutability
+
+Data and domain models are immutable, generated with `freezed`. Mutable models invite state changes that bypass the unidirectional flow; `freezed` gives value equality, `copyWith`, and exhaustive pattern matching for the price of a build_runner step we already pay for contract codegen.
+
+## State management: the GroundWork default
+
+**Riverpod 3.x** for new builds. The reasoning: it is the converging ecosystem default for new projects in 2026, it is compile-safe and testable without widget-tree gymnastics, and its provider graph doubles as the app's dependency-injection mechanism — one tool for state and DI. Riverpod 3.0 added Mutations (action lifecycle without codegen). Pin conservatively: the maintainer flags a possible near-term 4.0 and the offline-persistence API is explicitly experimental — do not build on experimental Riverpod APIs.
+
+- **Bloc (flutter_bloc 9.x)** is the deliberate alternative for large, regulated, audit-trail-heavy teams — stable and slow-moving by design. Choosing it is a recorded decision, not a drift.
+- **GetX** is an anti-recommendation, full stop.
+
+DI stance: Riverpod providers are the composition mechanism — repositories and services are providers, view models read them. The official guide's `provider`-for-DI recommendation is what Riverpod subsumes; do not run both.
+
+See [State management](state-management.md) for the patterns in depth.
+
+## Anti-patterns we reject
+
+- **Business logic in widgets.** A `build` method that branches on domain rules belongs in a view model.
+- **Preemptive Domain layers.** Use-case classes that forward one repository call add a file and remove nothing.
+- **Repositories aware of each other.** Cross-repository orchestration is a view model or use-case concern.
+- **Hand-written API clients against a promoted contract.** Generate the client; the contract is the source of truth.
+- **Surface-side business rules.** If a rule is proven at the core's contract, the surface re-implementing it is divergence waiting to happen.
+- **Clean-Architecture folder cargo-culting.** entities/usecases/datasources scaffolding imported from blog folklore — the official two-layer guide replaced it.
+
+## Further reading
+
+- [Flutter architecture guide](https://docs.flutter.dev/app-architecture/guide) — the canonical source for this document.
+- [Architecture recommendations](https://docs.flutter.dev/app-architecture/recommendations) — the cross-cutting recommendations table.
+- The **Compass app** — the Flutter team's reference implementation of this architecture.

package/src/generators/flutter-app/docs/principles/stack/flutter/index.md

@@ -0,0 +1,38 @@
+---
+title: Flutter
+description: Architecture, state management, widgets, testing, native interop, and release engineering for Flutter mobile surfaces.
+status: active
+last_reviewed: 2026-06-12
+---
+# Flutter
+
+## TL;DR
+
+A GroundWork mobile surface is a Flutter app: MVVM over a two-layer architecture, Riverpod for state, go_router for navigation, widget tests as the bulk of coverage, Pigeon for native interop, and a CI pipeline that signs, versions, and ships to both stores without a human in the loop. The surface is a thin adapter — business logic lives in the capability core and is reached through a typed client over promoted contracts.
+
+## Scope
+
+This set is named for the framework, not the language, because the engineering knowledge that matters is platform knowledge: widget lifecycles, store signing, emulator CI, platform channels. Dart idioms appear only where they carry a platform decision (immutability, codegen). The set covers mobile surfaces; Flutter-desktop and Flutter-web are out of scope — GroundWork's standard picks route those platforms elsewhere (see [surface stack selection](../../surface-stack-selection.md)).
+
+## Toolchain currency
+
+**Flutter 3.44.0 stable / Dart 3.12.0** (May 2026). Notable for planning: Material and Cupertino are frozen in the core framework as of 3.44 and are moving to standalone `material_ui`/`cupertino_ui` packages with independent versioning — pin them deliberately when they land.
+
+## The set
+
+- **[Architecture](architecture.md)** — the two-layer (UI/Data, optional Domain) model from the official Flutter architecture guide: MVVM in the UI layer, repositories and services in the data layer, feature-first `ui/` with type-first `data/`, immutable models via `freezed`, and the core-access seam — how the surface reaches the capability core through a typed contract client. States the GroundWork state-management default (Riverpod 3.x) and why.
+- **[State management](state-management.md)** — Riverpod 3.x in depth: provider and Notifier patterns, Mutations for action lifecycle, what belongs in providers versus ephemeral widget state, and the testing seams (`ProviderContainer`, overrides). Names the legacy patterns — provider-as-state-management, setState-as-architecture, GetX — so they are recognised and refused.
+- **[Widgets and composition](widgets-and-composition.md)** — composition over inheritance, `const` discipline, build-method purity, keys, theming as a projection of `brand-tokens.json` into a generated `ThemeData` module, go_router navigation with typed routes, and the accessibility baseline.
+- **[Testing](testing.md)** — the unit/widget/integration taxonomy: pure-Dart unit tests with fakes, widget tests as the bulk, `integration_test` happy paths on a headless Android emulator as the CI-canonical loop, Patrol only where flows cross the Flutter/OS boundary, and golden tests via alchemist. Surface tests prove wiring, never re-prove core logic.
+- **[Platform channels](platform-channels.md)** — the native escape hatch: Pigeon for structured APIs today, ffigen/jnigen with build hooks as the tracked destination, raw `MethodChannel` only for trivial one-offs, and when dropping to Swift/Kotlin is justified.
+- **[Releases and distribution](releases-and-distribution.md)** — signing discipline on both stores, CI/CD with GitHub Actions + fastlane (Codemagic as the Flutter-native alternative), pubspec versioning, the backend-driven forced-upgrade floor that makes contract compatibility enforceable on a lagging mobile fleet, and Shorebird code push for Dart-only OTA patches.
+
+## Survey provenance
+
+This set was authored from a dated ecosystem survey, not from prior assumption. A future refresh supersedes this provenance block.
+
+**Survey date: 2026-06-12.** Load-bearing sources:
+
+- Official: [docs.flutter.dev/app-architecture/guide](https://docs.flutter.dev/app-architecture/guide) and [/recommendations](https://docs.flutter.dev/app-architecture/recommendations) (both updated 2026-05-05); Flutter 3.44 release notes and announcement (May 2026); [Flutter's path towards seamless interop](https://blog.flutter.dev/flutters-path-towards-seamless-interop-4bf7d4579d9a); [dart.dev/tools/pub/workspaces](https://dart.dev/tools/pub/workspaces) and [dart.dev/tools/hooks](https://dart.dev/tools/hooks); docs.flutter.dev deployment, integration-test, and bind-native-code pages.
+- Packages (versions checked 2026-06-12 on pub.dev): go_router 17.3.0 and pigeon 27.1.0 (flutter.dev verified publisher), patrol 4.6.1 (LeanCode), riverpod 3.0.x changelog + riverpod.dev "what's new", flutter_bloc 9.1.1, alchemist, upgrader, shorebird_code_push, openapi_generator.
+- Ecosystem: Very Good Ventures (flutter_bloc rationale, Very Good Core, alchemist tutorial); Codemagic docs (code signing, Shorebird publishing); ReactiveCircus android-emulator-runner; Code With Andrea project-structure guidance; 2026 state-management comparisons (foresightmobile, startdebugging.net, dasroot.net).

package/src/generators/flutter-app/docs/principles/stack/flutter/platform-channels.md

@@ -0,0 +1,51 @@
+---
+title: Platform Channels
+description: Pigeon for structured native APIs, ffigen/jnigen as the tracked destination, when to drop to Swift/Kotlin, and SwiftPM as the iOS default.
+status: active
+last_reviewed: 2026-06-12
+---
+# Platform Channels
+
+## TL;DR
+
+Native interop is Pigeon: define the API once in Dart, generate type-safe Kotlin and Swift. The ecosystem is mid-migration to channel-free codegen interop — ffigen/jnigen on build hooks — which we track as the destination but do not adopt for app code until it settles. Raw `MethodChannel` is for trivial one-offs only. Dropping to native is a capability decision, not a performance reflex. iOS native wiring uses Swift Package Manager; CocoaPods is legacy.
+
+## Why this matters
+
+The platform capability ceiling axis says a stack's reach is measured *with* its native escape hatches, because AI labor makes them nearly free — dropping to Swift or Kotlin for one capability is a slice, not a staffing decision. That only holds if the hatch is disciplined: a typed, generated boundary an agent can regenerate and test, not a pile of stringly-typed channel calls that fail at runtime on a misspelled key.
+
+## The interop ladder
+
+### Pigeon — today's default for structured APIs
+
+**Pigeon** (flutter.dev verified publisher) is the production answer for any real native API surface: declare the interface once in a Dart file, generate matching type-safe Kotlin/Swift (and Java/Obj-C/C++) stubs on both sides. Misspelled method names and mistyped arguments become compile errors instead of runtime channel exceptions. Every structured Flutter↔native API in a GroundWork app goes through Pigeon.
+
+### ffigen / jnigen — the tracked destination
+
+The Flutter team's declared direction is **direct codegen interop without channels**: `ffigen` for C/Obj-C/Swift bindings (stable; synchronous calls, tree-shaking), `jnigen` for Java/Kotlin via JNI (pre-1.0, production-usable), built on **build hooks / native assets** (stable since Dart 3.10, default-enabled since Flutter 3.38). The ecosystem is mid-migration: plugin authors are rebuilding on these tools. We name the destination so refactors aim at it, and we adopt it where a dependency already ships it — but Pigeon remains the app-code default until the jnigen path reaches 1.0. Re-evaluate at the next survey.
+
+### Raw `MethodChannel` — trivial one-offs only
+
+A raw channel is acceptable for a single fire-and-forget call with no evolving surface — toggling a platform flag, reading one value. It is not type-safe and not refactorable; the moment a channel grows a second method or a structured payload, it becomes a Pigeon definition. Hand-written channels for any real API surface are legacy.
+
+## When to drop to native
+
+Write Swift/Kotlin when Flutter **cannot reach the capability**: a platform API with no maintained plugin (HealthKit details, platform-specific background modes, a vendor SDK), OS-integrated UI Flutter cannot render (widgets/complications, App Intents), or hardware access below the plugin ecosystem. Do **not** drop to native as a performance reflex — profile first; Flutter's rendering and isolates cover almost every performance complaint, and a native detour taken for imagined speed buys two codebases for one feature.
+
+Check pub.dev before writing native code: a maintained, verified-publisher plugin is a dependency decision, not an interop project. Write native code when the plugin shelf is empty or unmaintained — and structure it as a small, Pigeon-fronted module the agent can regenerate, with the Dart side exposed as a **service** in the data layer like any other platform API (see [Architecture](architecture.md)).
+
+## iOS build wiring
+
+**Swift Package Manager is the iOS/macOS default as of Flutter 3.44.** New native modules and plugin dependencies use SwiftPM; CocoaPods is the legacy path, kept only where a required dependency has not migrated. Do not add new Podfile-based wiring.
+
+## Testing the boundary
+
+The Pigeon-fronted service is faked in Dart for unit and widget tests like any other service — the native side does not run in those tiers. The native implementation itself is exercised by Patrol or `integration_test` on the emulator (see [Testing](testing.md)) only where the capability is observable; pure pass-through wrappers over OS APIs get a thin smoke test, not a re-proof of the OS.
+
+## Anti-patterns we reject
+
+- **Hand-written channels for evolving APIs.** Stringly-typed, runtime-failing, agent-hostile. Pigeon exists.
+- **Native-by-reflex for performance.** Profile in Dart first; the ceiling axis funds capability gaps, not superstition.
+- **Skipping the plugin shelf.** Rewriting a maintained verified-publisher plugin is negative work.
+- **New CocoaPods wiring.** SwiftPM is the default; Pods are a compatibility tail.
+- **Native logic that grows business rules.** The native module is transport to an OS capability; rules live in the core or the view model, where they are proven.

package/src/generators/flutter-app/docs/principles/stack/flutter/releases-and-distribution.md

@@ -0,0 +1,59 @@
+---
+title: Releases and Distribution
+description: Store signing discipline, CI/CD with GitHub Actions + fastlane or Codemagic, pubspec versioning, the forced-upgrade floor, and Shorebird code push.
+status: active
+last_reviewed: 2026-06-12
+---
+# Releases and Distribution
+
+## TL;DR
+
+Both stores are shipped from CI: GitHub Actions + fastlane by default, Codemagic as the Flutter-native alternative. Signing material never touches git. Versions are `x.y.z+build` in pubspec with the build number CI-incremented. A backend-driven minimum-version floor with the `upgrader` package is mandatory — it is the mechanism that makes contract compatibility enforceable on a fleet that lags releases by months. Shorebird code push is the Dart-only OTA lane.
+
+## Why this matters
+
+A mobile surface cannot be rolled back and cannot be force-refreshed: every version ever shipped is potentially still running, store review adds days of latency, and a signing mistake can lock you out of your own listing permanently. Release engineering is therefore not a deploy script — it is the half of the architecture's compatibility story that lives outside the repo. The agent-closable loop axis also bites here: a release process with a human clicking through Xcode is a process the delivery loop stalls on, so everything below is CI-driven.
+
+## Signing
+
+**Android.** One upload keystore per app, generated once, stored in a secret manager with an independent secure copy — the official docs warn it is unrecoverable, and losing it means losing the update path. `key.properties` and the keystore are never in git; CI injects them from encrypted secrets (or Codemagic code-signing identities). **Play App Signing** holds the actual app signing key, so a compromised upload key is rotatable.
+
+**iOS.** **App Store Connect API keys** drive CI authentication — no human Apple ID sessions in automation. Certificates and provisioning profiles are managed fastlane-match-style (encrypted, centrally stored, CI-fetched); Codemagic automates the same with managed code signing.
+
+A keystore or service-account JSON committed to a repo is an incident, not a finding.
+
+## CI/CD
+
+Two converging stacks; both are sound, pick one per product and record it:
+
+- **GitHub Actions + fastlane** (default — it shares the runner platform every other GroundWork surface uses): `supply` publishes to Play, `deliver`/`pilot` to App Store Connect/TestFlight.
+- **Codemagic** — Flutter-native CI with built-in store publishing and managed signing; fastlane is preinstalled, so the stacks compose rather than compete.
+
+The 2026-standard flow: PRs run the test gate (see [Testing](testing.md) — widget tests plus the headless-emulator integration lane); merges to main build signed release artifacts; artifacts publish to the **internal track / TestFlight first**, then promote to production after staged rollout. No artifact reaches a store that CI did not build, sign, and test.
+
+## Versioning
+
+pubspec carries `version: x.y.z+buildNumber`. Humans own `x.y.z` (it is the user-visible and compatibility-relevant part); **CI owns the build number**, auto-incrementing per release build via `--build-number` (`--build-name` overrides the version when needed). Hand-bumped build numbers collide; collided build numbers are store-upload rejections.
+
+## Forced upgrade — the contract-compatibility floor
+
+The architecture's stance is that a published contract field is never broken — because the fleet consuming it lags releases by months and cannot be recalled. Forced upgrade is the other half of that bargain: the floor below which the core stops accommodating old clients.
+
+- The core (or a config endpoint / Firebase Remote Config) publishes a **minimum supported version**; the app compares at startup.
+- The **`upgrader`** package implements the prompt: `minAppVersion` below the floor auto-hides "Later"/"Ignore".
+- Two tiers, used deliberately: **soft prompt** (dismissible — new features, gentle migration pressure) and **hard force** (blocking — security issues, a contract the core can no longer serve).
+
+The floor advances slowly and is a recorded product decision each time, because a hard force on a user mid-task is the worst interaction the product will ever ship. Between "never break a field" and "hard floor," every fleet version in the window is served correctly; outside it, the app says so honestly. Shipping a contract-breaking core change without first raising the floor and waiting out adoption is a sequencing defect.
+
+## Shorebird code push
+
+**Shorebird** is the OTA lane: stable on Android and iOS, store-policy compliant, Dart-only patches with `shorebird_code_push` for in-app patch checks. Use it for what it is — a hotfix channel that skips store latency for Dart-level defects — not as a release process. Native-code changes (plugins, Pigeon modules, SDK bumps) still require a store release, so OTA never substitutes for the version floor; a patched 1.4.2 is still 1.4.2 to the contract.
+
+## Anti-patterns we reject
+
+- **Signing material in the repo.** Keystores, `key.properties`, ASC keys, service-account JSON — secrets infrastructure only.
+- **Manual store uploads.** A human with Xcode or the Play console in the loop is an unrepeatable release.
+- **Breaking a published contract field because "the new app is out."** The fleet lags by months; the floor, not the release date, defines what you may drop.
+- **Hard-forcing upgrades as a convenience.** Hard force is for security and served-contract limits; everything else is a soft prompt.
+- **Treating Shorebird as the release process.** OTA patches Dart defects; features, native changes, and version floors move through the stores.
+- **CodePush-era expectations.** Flutter never had Microsoft CodePush; Shorebird is the ecosystem answer, with Dart-only limits respected.

package/src/generators/flutter-app/docs/principles/stack/flutter/state-management.md

@@ -0,0 +1,85 @@
+---
+title: State Management
+description: Riverpod 3.x providers, Notifiers, Mutations, ephemeral vs app state, testing seams, and the legacy patterns we name and refuse.
+status: active
+last_reviewed: 2026-06-12
+---
+# State Management
+
+## TL;DR
+
+Riverpod 3.x is the default. Providers hold shared and derived state, `Notifier` classes hold state with behaviour, Mutations carry the lifecycle of user actions, and `setState` survives only for ephemeral widget-local state. Tests exercise providers in a `ProviderContainer` with overrides — no widget tree required. Provider-as-state-management, setState-as-architecture, and GetX are legacy.
+
+## Why this matters
+
+State management is where Flutter codebases historically rotted: a package chosen by fashion, state scattered between widgets and singletons, and tests that need a full widget pump to assert a counter incremented. Riverpod's compile-safe provider graph fixes the structural problems — no `BuildContext` dependency for reads, no runtime lookup failures, and a DI story for free — which is why it is the converging 2026 default for new builds and our pick. Pin 3.x APIs conservatively: persistence is experimental and the maintainer flags a possible 4.0.
+
+## The patterns
+
+### Providers are the graph
+
+Everything shared is a provider: repositories, services, the contract client, derived view state. The provider graph **is** the dependency-injection graph — a view model provider `ref.watch`es its repository provider, the repository provider reads the client provider. Construction order, disposal, and test substitution all fall out of the graph; there is no separate DI container.
+
+```dart
+final userRepositoryProvider = Provider<UserRepository>(
+  (ref) => UserRepository(ref.watch(apiClientProvider)),
+);
+```
+
+### Notifier for state with behaviour
+
+A view model is a `Notifier` (or `AsyncNotifier` when the initial state is asynchronous) exposing an immutable state object and methods as the MVVM commands:
+
+```dart
+class ProfileViewModel extends AsyncNotifier<ProfileState> {
+  @override
+  Future<ProfileState> build() async =>
+      ProfileState(user: await ref.watch(userRepositoryProvider).current());
+
+  Future<void> rename(String name) async { /* command */ }
+}
+```
+
+`build` declares dependencies via `ref.watch`; when a dependency changes, the state recomputes. Derived read-only state uses plain providers over Notifiers — do not write a class where a function suffices.
+
+### Mutations for action lifecycle
+
+User actions that need pending/success/error surfacing — submit, delete, retry — use Riverpod 3 **Mutations** (idle/pending/success/error, no codegen required). They replace the hand-rolled `isLoading` boolean and the per-action `AsyncValue` juggling; the view watches the mutation state and renders the spinner or the error.
+
+### What is state, and what is ephemeral
+
+A provider holds state that is **shared, derived from the core, or must survive the widget's lifetime**: session, fetched data, feature view state. `setState` in a `StatefulWidget` is correct for **ephemeral** state — text-field focus, animation progress, whether a tile is expanded — where lifting it into a provider adds graph noise for state nobody else reads. The boundary question: does anything outside this widget care? No → ephemeral.
+
+Client state must also be recoverable: anything not rebuildable from the core or the route is state the app loses on process death, and mobile processes die constantly. The route (go_router's URL) is a first-class state container.
+
+### Testing seams
+
+Providers test without widgets. A `ProviderContainer` with overrides substitutes fakes at any node of the graph:
+
+```dart
+final container = ProviderContainer(overrides: [
+  userRepositoryProvider.overrideWithValue(FakeUserRepository()),
+]);
+final state = await container.read(profileViewModelProvider.future);
+```
+
+Fakes over mocks, per the official guide: an abstract repository with an in-memory fake survives refactors that a stubbed mock breaks on. Widget tests override the same providers via `ProviderScope(overrides: ...)` — the same seam serves both tiers.
+
+## Legacy patterns — named so they are refused
+
+- **provider-as-state-management.** The 2019–2022 default. Riverpod is its designated successor by the same author; `provider` survives officially only as a DI mechanism, and with Riverpod even that role is subsumed.
+- **setState-as-architecture.** `StatefulWidget`s holding app state, passed down constructors, mutated in callbacks. Legacy for anything beyond ephemeral state.
+- **GetX.** Uniformly an anti-recommendation in serious 2026 comparisons — global mutable service locators and context-free magic that defeats both the type system and testability. Never.
+- **Riverpod experimental persistence.** Not legacy but forbidden for now: explicitly experimental, and we do not put experimental APIs in load-bearing paths.
+
+## Anti-patterns
+
+- **Reading providers in `build` methods imperatively.** `ref.watch` in build, `ref.read` only inside callbacks. A `ref.read` in build silently opts out of reactivity.
+- **Provider state that mirrors the route.** If go_router already encodes it (selected id, tab), the provider duplicating it will drift.
+- **One god-provider per screen.** Split by concern; the graph dedupes and recomputes at the right granularity only if you let it.
+- **Mocking your own Notifier.** Test the real Notifier with fake repositories; mocking the unit under test proves nothing.
+
+## Further reading
+
+- [riverpod.dev](https://riverpod.dev) — the official docs; the "what's new in 3.0" page covers Mutations.
+- [Flutter architecture recommendations](https://docs.flutter.dev/app-architecture/recommendations) — fakes-over-mocks and the command pattern this document assumes.