rsc-universal 0.1.1

package/skills/flutter/references/ui-and-navigation.md

@@ -0,0 +1,378 @@
+# UI & navigation (deep dive)
+
+Back to [`../SKILL.md`](../SKILL.md).
+
+Widget composition, Material 3 theming and design tokens, responsive/adaptive layout,
+slivers, the **typed go_router** API (go_router 17.2.x + `go_router_builder` 4.3.x), and
+accessibility. All code targets **Flutter 3.44 / Dart 3.12**, Material 3.
+
+## Widget composition
+
+Extract subtrees to **widget classes**, never to `_build*()` helper methods.
+
+```dart
+// BAD — a private method returning a Widget. The whole parent rebuilds these,
+// they can't be const, and the framework can't reuse their Element.
+Widget _buildHeader(BuildContext context) => Padding(
+      padding: const EdgeInsets.all(16),
+      child: Text(title, style: Theme.of(context).textTheme.headlineMedium),
+    );
+
+// GOOD — a StatelessWidget class with a const constructor.
+class _PageHeader extends StatelessWidget {
+  const _PageHeader(this.title);
+  final String title;
+
+  @override
+  Widget build(BuildContext context) => Padding(
+        padding: const EdgeInsets.all(16),
+        child: Text(title, style: Theme.of(context).textTheme.headlineMedium),
+      );
+}
+```
+
+Why classes win: a `const _PageHeader('x')` is canonicalized — Flutter sees the same instance
+across rebuilds and skips its subtree entirely. Methods can't be `const`, give the framework
+no rebuild boundary, define no natural `RepaintBoundary` granularity, and break hot-reload
+state. The class also slots cleanly into `RepaintBoundary` and is independently testable.
+
+`const` propagation stops rebuilds at the boundary:
+
+```dart
+// BAD — new instances every frame.
+Padding(padding: EdgeInsets.all(16), child: Icon(Icons.home));
+// GOOD — const subtree is never rebuilt.
+const Padding(padding: EdgeInsets.all(16), child: Icon(Icons.home));
+```
+
+Keys taxonomy — use the right one, and never `UniqueKey` in `build`:
+
+| Key | Use for | Avoid |
+| --- | --- | --- |
+| `ValueKey` | list/grid item identity (preserve state across reorder) | when items have no stable id |
+| `ObjectKey` | identity based on a data object, not a single field | when a `ValueKey` on an id works |
+| `GlobalKey` | reaching widget state across the tree (`Form`, measuring) | as a default — it's expensive, use sparingly |
+| `UniqueKey` | forcing a fresh element on purpose (rare) | **NEVER in `build`** — forces a rebuild every frame |
+
+Slot-based reusable widgets take `Widget`/`WidgetBuilder` slots, not booleans:
+
+```dart
+class AppCard extends StatelessWidget {
+  const AppCard({super.key, this.leading, required this.body, this.actions = const []});
+
+  final Widget? leading;
+  final WidgetBuilder body;
+  final List<Widget> actions;
+
+  @override
+  Widget build(BuildContext context) => Card(
+        child: Padding(
+          padding: const EdgeInsets.all(16),
+          child: Column(
+            crossAxisAlignment: CrossAxisAlignment.start,
+            children: [
+              if (leading != null) leading!,
+              body(context),
+              if (actions.isNotEmpty)
+                Row(mainAxisAlignment: MainAxisAlignment.end, children: actions),
+            ],
+          ),
+        ),
+      );
+}
+```
+
+## Material 3 theming & design tokens
+
+Build light and dark schemes from one seed; `useMaterial3` is the default in 3.44 but state
+it for clarity.
+
+```dart
+ThemeData buildTheme(Brightness brightness) => ThemeData(
+      useMaterial3: true,
+      colorScheme: ColorScheme.fromSeed(
+        seedColor: const Color(0xFF6750A4),
+        brightness: brightness,
+      ),
+      extensions: const [AppSpacing.standard],
+    );
+
+final lightTheme = buildTheme(Brightness.light);
+final darkTheme = buildTheme(Brightness.dark);
+```
+
+App-specific tokens (spacing, radii) belong in a `ThemeExtension`, so they live in the theme
+and `lerp` smoothly across light/dark transitions:
+
+```dart
+@immutable
+class AppSpacing extends ThemeExtension<AppSpacing> {
+  const AppSpacing({required this.sm, required this.md, required this.lg});
+
+  static const standard = AppSpacing(sm: 8, md: 16, lg: 24);
+
+  final double sm;
+  final double md;
+  final double lg;
+
+  @override
+  AppSpacing copyWith({double? sm, double? md, double? lg}) =>
+      AppSpacing(sm: sm ?? this.sm, md: md ?? this.md, lg: lg ?? this.lg);
+
+  @override
+  AppSpacing lerp(ThemeExtension<AppSpacing>? other, double t) {
+    if (other is! AppSpacing) return this;
+    return AppSpacing(
+      sm: lerpDouble(sm, other.sm, t)!,
+      md: lerpDouble(md, other.md, t)!,
+      lg: lerpDouble(lg, other.lg, t)!,
+    );
+  }
+}
+```
+
+Read tokens through the theme, never as literals:
+
+```dart
+final spacing = Theme.of(context).extension<AppSpacing>()!;
+final titleStyle = Theme.of(context).textTheme.titleLarge;
+
+// GOOD — semantic tokens.
+Padding(padding: EdgeInsets.all(spacing.md), child: Text('Hi', style: titleStyle));
+// BAD — magic numbers + hardcoded color break dark mode and the design system.
+Padding(padding: const EdgeInsets.all(16), child: Text('Hi', style: TextStyle(color: Colors.blue, fontSize: 22)));
+```
+
+## Responsive & adaptive
+
+Define breakpoints once, switch layout on available width (not raw device size):
+
+```dart
+abstract final class Breakpoints {
+  static const double compact = 600;
+  static const double medium = 840;
+}
+
+class AdaptiveScaffold extends StatelessWidget {
+  const AdaptiveScaffold({super.key, required this.destinations, required this.body});
+
+  final List<NavigationDestination> destinations;
+  final Widget body;
+
+  @override
+  Widget build(BuildContext context) => LayoutBuilder(
+        builder: (context, constraints) {
+          final wide = constraints.maxWidth >= Breakpoints.medium;
+          if (wide) {
+            return Scaffold(
+              body: Row(
+                children: [
+                  NavigationRail(
+                    destinations: [
+                      for (final d in destinations)
+                        NavigationRailDestination(icon: d.icon, label: Text(d.label)),
+                    ],
+                    selectedIndex: 0,
+                  ),
+                  const VerticalDivider(width: 1),
+                  Expanded(child: SafeArea(child: body)),
+                ],
+              ),
+            );
+          }
+          return Scaffold(
+            body: SafeArea(child: body),
+            bottomNavigationBar: NavigationBar(destinations: destinations),
+          );
+        },
+      );
+}
+```
+
+Use the dimension-specific `MediaQuery` accessors so a widget rebuilds only when *that* aspect
+changes:
+
+```dart
+final size = MediaQuery.sizeOf(context);            // GOOD — only on size change
+final padding = MediaQuery.paddingOf(context);      // GOOD — only on padding change
+// final mq = MediaQuery.of(context);               // BAD  — rebuilds on ANY MediaQuery change
+```
+
+Prevent overflow with `Flexible`/`Expanded` in rows/columns and `FittedBox` for must-fit text:
+
+```dart
+Row(children: [
+  const Icon(Icons.label),
+  Expanded(child: Text(longTitle, overflow: TextOverflow.ellipsis)),
+  FittedBox(child: Text(price)),
+]);
+```
+
+## Slivers
+
+Mix a collapsing header, a list, and a grid in one scroll context with `CustomScrollView`:
+
+```dart
+CustomScrollView(
+  slivers: [
+    SliverAppBar.large(
+      title: const Text('Catalog'),
+      floating: true,
+      actions: [IconButton(onPressed: onSearch, icon: const Icon(Icons.search))],
+    ),
+    SliverList.builder(
+      itemCount: sections.length,
+      itemBuilder: (context, i) => SectionHeader(sections[i]),
+    ),
+    SliverGrid.builder(
+      gridDelegate: const SliverGridDelegateWithFixedCrossAxisCount(crossAxisCount: 2),
+      itemCount: products.length,
+      itemBuilder: (context, i) => ProductTile(products[i]),
+    ),
+  ],
+);
+```
+
+Slivers beat nested scrollables when you need a single scroll context (one scrollbar, shared
+physics), a collapsing/pinned header, or mixed-axis content (a list above a grid). Nesting a
+`ListView` inside a `Column` inside a `ScrollView` causes unbounded-height errors and double
+scroll bars — reach for slivers instead.
+
+## Typed go_router (current API)
+
+```yaml
+# pubspec.yaml
+dependencies:
+  go_router: ^17.2.0
+dev_dependencies:
+  go_router_builder: ^4.3.0   # generator only; pins go_router ^17.2.0 as its own dev dep — no runtime cap on your app
+  build_runner: ^2.6.0
+```
+
+Route classes are generated from `@TypedGoRoute` annotations; each mixes in `$RouteName`:
+
+```dart
+// common/router/app_router.dart
+part 'app_router.g.dart';
+
+@TypedGoRoute<HomeRoute>(
+  path: '/',
+  routes: [TypedGoRoute<DetailRoute>(path: 'detail/:id')],
+)
+class HomeRoute extends GoRouteData with $HomeRoute {
+  const HomeRoute();
+  @override
+  Widget build(BuildContext context, GoRouterState state) => const HomeScreen();
+}
+
+class DetailRoute extends GoRouteData with $DetailRoute {
+  const DetailRoute({required this.id, this.$extra});
+  final String id;
+  final Product? $extra; // non-serializable object passed in memory, not via URL
+  @override
+  Widget build(BuildContext context, GoRouterState state) =>
+      DetailScreen(id: id, product: $extra);
+}
+```
+
+Assemble the router from the generated `$appRoutes`, with a centralized guard:
+
+```dart
+@riverpod
+GoRouter router(Ref ref) {
+  final authStream = ref.watch(authStateStreamProvider.stream);
+  return GoRouter(
+    routes: $appRoutes,
+    refreshListenable: GoRouterRefreshStream(authStream),
+    redirect: (context, state) {
+      final loggedIn = ref.read(authControllerProvider).isAuthenticated;
+      final goingToLogin = state.matchedLocation == const LoginRoute().location;
+      if (!loggedIn && !goingToLogin) return const LoginRoute().location;
+      if (loggedIn && goingToLogin) return const HomeRoute().location;
+      return null;
+    },
+    onException: (context, state, router) => router.go(const HomeRoute().location),
+  );
+}
+```
+
+`GoRouterRefreshStream` re-runs `redirect` whenever auth changes:
+
+```dart
+class GoRouterRefreshStream extends ChangeNotifier {
+  GoRouterRefreshStream(Stream<dynamic> stream) {
+    notifyListeners();
+    _sub = stream.asBroadcastStream().listen((_) => notifyListeners());
+  }
+  late final StreamSubscription<dynamic> _sub;
+  @override
+  void dispose() {
+    _sub.cancel();
+    super.dispose();
+  }
+}
+```
+
+Persistent bottom-nav state uses a typed `StatefulShellRoute.indexedStack`:
+
+```dart
+@TypedStatefulShellRoute<MainShellRoute>(
+  branches: [
+    TypedStatefulShellBranch<FeedBranch>(routes: [TypedGoRoute<FeedRoute>(path: '/feed')]),
+    TypedStatefulShellBranch<CartBranch>(routes: [TypedGoRoute<CartRoute>(path: '/cart')]),
+  ],
+)
+class MainShellRoute extends StatefulShellRouteData {
+  const MainShellRoute();
+  @override
+  Widget builder(BuildContext context, GoRouterState state, StatefulNavigationShell shell) =>
+      ScaffoldWithNavBar(shell: shell); // each branch keeps its own Navigator stack
+}
+```
+
+Deep links: configure with the `app_links` package (Android `intent-filter`, iOS associated
+domains). **Validate and sanitize the incoming path before navigating** — a deep link is
+untrusted input:
+
+```dart
+String? sanitizeDeepLink(Uri uri) {
+  const allowed = {'/feed', '/cart', '/detail'};
+  final base = '/${uri.pathSegments.isEmpty ? '' : uri.pathSegments.first}';
+  return allowed.contains(base) ? uri.path : null; // reject anything off the allowlist
+}
+```
+
+Log navigation with a `NavigatorObserver`:
+
+```dart
+class AnalyticsObserver extends NavigatorObserver {
+  @override
+  void didPush(Route<dynamic> route, Route<dynamic>? previousRoute) {
+    analytics.logScreenView(route.settings.name ?? 'unknown');
+  }
+}
+```
+
+Typed navigation — no magic strings, args are type-checked:
+
+```dart
+const DetailRoute(id: '7').go(context);                       // replace
+DetailRoute(id: '7', $extra: product).push(context);          // push, pass object in memory
+```
+
+## Accessibility
+
+- Label what the framework can't infer; mark decoration as excluded:
+
+```dart
+Semantics(label: 'Add to cart', button: true, child: const Icon(Icons.add));
+Image.asset('assets/logo.png', semanticLabel: 'Acme logo');
+ExcludeSemantics(child: const DecorativeDivider());        // decorative only
+MergeSemantics(child: Row(children: [const Icon(Icons.star), const Text('4.8')]));
+```
+
+- Minimum 48×48 logical-pixel touch targets (wrap small icons in a sized `InkWell`/`IconButton`).
+- Respect text scaling — never hardcode row heights around text; let it grow. Use
+  `MediaQuery.textScalerOf(context)` if you must adapt layout.
+- Contrast ≥ 4.5:1 for body text; color is never the sole state indicator — pair it with an
+  icon or label (e.g. an error shows a red border *and* an error icon *and* text).

package/skills/flutter/scripts/verify.sh

@@ -0,0 +1,104 @@
+#!/usr/bin/env bash
+# verify.sh — Flutter/Dart project quality gate.
+#
+# Run from the root of a Flutter (or pure-Dart) project:
+#   bash scripts/verify.sh
+#
+# Runs, in order: dart format check, build_runner codegen (only if build_runner
+# is a dependency), dart analyze, then the test suite with coverage.
+#
+# Codegen runs BEFORE analyze on purpose: on a fresh checkout the ungenerated
+# .g.dart / .freezed.dart 'part' files would otherwise make analyze fail for the
+# wrong reason. Generating first means analyze sees a complete tree.
+#
+# Missing tools are SKIPPED with a yellow warning (never fail the run). A gate
+# that runs and finds real problems causes a non-zero exit. All gates run even
+# if an earlier one fails, so you see every problem at once.
+#
+# Portable to stock macOS bash 3.2 (no mapfile, no arrays, no associative maps).
+set -eu
+
+YELLOW=$'\033[1;33m'
+RED=$'\033[0;31m'
+GREEN=$'\033[0;32m'
+RESET=$'\033[0m'
+
+errors=0
+
+warn() { printf '%s[skip]%s %s\n' "$YELLOW" "$RESET" "$1"; }
+info() { printf '==> %s\n' "$1"; }
+fail() { printf '%s[fail]%s %s\n' "$RED" "$RESET" "$1"; errors=$((errors + 1)); }
+have() { command -v "$1" >/dev/null 2>&1; }
+
+# Guard: only meaningful inside a Dart/Flutter project.
+if [ ! -f pubspec.yaml ]; then
+  warn "no pubspec.yaml in $PWD — not a Flutter/Dart project; skipping"
+  exit 0
+fi
+
+has_dart=false
+has_flutter=false
+have dart && has_dart=true
+have flutter && has_flutter=true
+
+if [ "$has_dart" = false ] && [ "$has_flutter" = false ]; then
+  warn "neither 'dart' nor 'flutter' on PATH — install the Flutter SDK; skipping all checks"
+  exit 0
+fi
+
+# 1. Formatting gate.
+if [ "$has_dart" = true ]; then
+  info "dart format (check only)"
+  if ! dart format --output=none --set-exit-if-changed .; then
+    fail "code is not formatted — run: dart format ."
+  fi
+else
+  warn "dart not found — skipping format check"
+fi
+
+# 2. Code generation (only if build_runner is a dependency). Runs BEFORE analyze
+#    so generated 'part' files exist when the analyzer reads the tree.
+if grep -Eq '^[[:space:]]*build_runner[[:space:]]*:' pubspec.yaml; then
+  if [ "$has_dart" = true ]; then
+    info "build_runner codegen"
+    if ! dart run build_runner build --delete-conflicting-outputs; then
+      fail "build_runner failed — generated files may be stale"
+    fi
+  else
+    warn "dart not found — skipping build_runner"
+  fi
+else
+  info "build_runner not a dependency — skipping codegen"
+fi
+
+# 3. Static analysis gate.
+if [ "$has_dart" = true ]; then
+  info "dart analyze --fatal-infos"
+  if ! dart analyze --fatal-infos; then
+    fail "static analysis reported issues"
+  fi
+else
+  warn "dart not found — skipping analyze"
+fi
+
+# 4. Tests with coverage.
+if [ "$has_flutter" = true ]; then
+  info "flutter test --coverage"
+  if ! flutter test --coverage; then
+    fail "tests failed"
+  fi
+elif [ "$has_dart" = true ]; then
+  info "dart test (pure-Dart package — no flutter on PATH)"
+  if ! dart test; then
+    fail "tests failed"
+  fi
+else
+  warn "no test runner available — skipping tests"
+fi
+
+# Summary.
+if [ "$errors" -gt 0 ]; then
+  printf '%s%d gate(s) failed.%s\n' "$RED" "$errors" "$RESET"
+  exit 1
+fi
+printf '%sall checks passed.%s\n' "$GREEN" "$RESET"

package/skills/fly-io/SKILL.md

@@ -0,0 +1,206 @@
+---
+name: fly-io
+description: "Use when deploying or operating an app on Fly.io — writing fly.toml, running Machines across regions near users, attaching Volumes, managing secrets, or scaling (autostop/autostart, scale count, fly-replay). Triggers: 'fly deploy', 'fly launch', 'desplega a Fly.io a prop dels usuaris', 'users in Sydney see high latency but my app only runs in iad', 'scale my Fly app to zero overnight', 'attach a persistent disk to my Fly machine', 'forward writes to the primary region'. NOT a generic git-push PaaS (that is railway), NOT frontend edge hosting (that is vercel)."
+tags: [fly-io, deployment, machines, regions, scaling]
+recommends: [docker, scaling, postgresdb, railway, domains-dns]
+origin: risco
+---
+
+# Deploy on Fly.io
+
+You are deploying an app to Fly.io: a `fly.toml`, Machines (Firecracker microVMs) placed in regions close to users, optional region-pinned Volumes, secrets, and the right scaling lever. Get the mental model right first, then the config follows.
+
+## Mental model
+
+- **App** is the logical unit. It owns a name, a `primary_region`, and config in `fly.toml`. Why: every command targets an app.
+- **Process groups** (`[processes]`, e.g. `web`, `worker`) split one image into roles. Why: a web group takes traffic, a worker group does not — they bind services and VMs separately.
+- **Machines** are Firecracker microVMs running your image. Each runs in exactly one region. Why: latency and volumes are per-Machine, so placement is the whole game.
+- **Fly Proxy** is the anycast front door. It routes a request to the nearest running Machine, can start a stopped one, and obeys `fly-replay` headers. Why: it is what makes "global" cheap — you do not run a load balancer.
+- **Volumes** are local NVMe disks pinned to one Machine in one region. No replication. Why: this single fact dictates every stateful architecture decision below.
+
+## Deploy fast (4 commands)
+
+```bash
+fly launch                              # detects framework, generates fly.toml + Dockerfile, creates the app
+fly secrets set DATABASE_URL=postgres://...  # restarts every Machine; never put this in [env]
+fly deploy                              # builds image, runs release_command, rolls out Machines
+fly scale count 2 --region iad,ams      # place Machines in Virginia + Amsterdam
+```
+
+`fly launch` is interactive and writes a starter `fly.toml`. Treat that file as a draft — review it against the next section before the first real deploy. Run `fly status` and `fly logs` after any deploy.
+
+## A fly.toml that works
+
+```toml
+app            = "my-api"
+primary_region = "iad"            # 3-letter region code: iad, ord, ams, syd, gru, nrt...
+
+[build]
+  # dockerfile = "Dockerfile"     # Fly builds from your Dockerfile; see ../docker/SKILL.md
+
+[deploy]
+  release_command = "npm run migrate"   # one-shot Machine that runs BEFORE the new version goes live
+  strategy        = "rolling"            # rolling | bluegreen | canary | immediate
+
+[processes]
+  web    = "node server.js"
+  worker = "node worker.js"
+
+[http_service]
+  internal_port       = 8080
+  force_https         = true
+  auto_stop_machines  = "stop"   # "off" | "stop" | "suspend" — set WITH auto_start_machines
+  auto_start_machines = true
+  min_machines_running = 0       # 0 = scale to zero; honored only in primary_region
+  processes           = ["web"]
+
+  [http_service.concurrency]
+    type       = "requests"
+    soft_limit = 200             # Proxy starts spreading load past this
+    hard_limit = 250             # Proxy stops sending past this
+
+[[vm]]                            # formerly [[compute]]
+  size       = "shared-cpu-1x"
+  memory     = "512mb"
+  cpu_kind   = "shared"          # "shared" | "performance"
+  processes  = ["web"]
+
+[[mounts]]
+  source       = "data"          # volume NAME, created with `fly volumes create data`
+  destination  = "/data"
+  processes    = ["web"]
+  initial_size = "1gb"
+```
+
+Full field surface (`[[services]]` vs `[http_service]`, health checks, `[[statics]]`, `[[files]]`, all VM sizes, `[restart]`, `[metrics]`) lives in `references/fly-toml.md` — read it when you need a key that is not above.
+
+## Regions: place Machines near users
+
+Pick the branch first, then run the commands.
+
+| Your app is... | Strategy | How |
+| --- | --- | --- |
+| Stateless (no local disk; DB elsewhere) | Replicate the Machine into more regions | `fly scale count 2 --region iad,ams,syd` |
+| Stateful with a Volume | Keep writes in `primary_region`, add read replicas + `fly-replay` | see `references/multi-region.md` |
+| Needs one extra box now | Clone a single Machine (gets a fresh volume) | `fly machine clone <id> --region syd` |
+
+```bash
+fly platform regions              # list region codes + names
+fly scale count web=2 --region ams   # per-process, per-region count
+fly scale show                    # what runs where, right now
+```
+
+Rules:
+- A request with no pinned region goes to the **fastest Machine for that caller** via anycast — multi-region is mostly "run Machines in more places."
+- `fly scale count N --region a,b` is the per-region count, not a total. Why: `count 2 --region iad,ams` means 2 in *each*, i.e. 4 Machines.
+- If any target region is **out of capacity, the whole scale op fails** — no partial placement. Retry with fewer regions or a different code.
+- "Slow for users in Sydney, app runs in iad" => add `syd`, not a bigger VM. Latency is distance, not CPU.
+
+## Volumes
+
+A Fly Volume is a local NVMe disk **pinned to one Machine in one region**. There is **no automatic replication** between volumes. Encrypted at rest by default (`--no-encryption` to opt out — almost never do).
+
+```bash
+fly volumes create data --region iad --size 3
+fly volumes list
+```
+
+- **One volume attaches to one Machine.** Two Machines cannot share a volume. Why: it is block storage on one host, not a network filesystem.
+- `fly scale count` on a group with a `[[mounts]]` creates a **new empty volume per new Machine** — it does **not** copy your data. This is the #1 stateful gotcha.
+
+```toml
+# Bad: expecting two web Machines to "share" /data — they each get their own empty disk
+[[mounts]]
+  source      = "data"
+  destination = "/data"
+  processes   = ["web"]   # then `fly scale count web=3` => 3 separate, unsynced disks
+```
+
+```toml
+# Good: one writer with the volume; replicas are stateless and read via the DB/fly-replay
+[[mounts]]
+  source      = "data"
+  destination = "/data"
+  processes   = ["writer"]   # a single-Machine process group; scale `web` separately, stateless
+```
+
+Replication is **your app's job** (LiteFS, app-level streaming, or a managed DB), never the volume's. See `references/multi-region.md`.
+
+## Secrets
+
+```bash
+fly secrets set STRIPE_KEY=sk_live_... SESSION_SECRET=...   # one rollout
+fly secrets list           # shows NAME + digest + timestamp — never the value
+fly secrets unset OLD_KEY
+```
+
+- `fly secrets set` **updates every Machine and restarts them** — it resets the ephemeral filesystem. Why: batch your sets into one command so you trigger one rollout, not five.
+- Secrets arrive as **environment variables** in the guest. Read `process.env.STRIPE_KEY`.
+- Need a secret as a *file* on disk (a cert, a service-account JSON)? Use `[[files]]` with `secret_name` — see `references/fly-toml.md`.
+
+```toml
+# Bad: secret baked into the image / committed config
+[env]
+  STRIPE_KEY = "sk_live_51H..."   # in git, in the image layers, leaked
+```
+
+```bash
+# Good: out of the repo, out of the image, encrypted in Fly's vault
+fly secrets set STRIPE_KEY=sk_live_51H...
+```
+
+Treat secret hygiene as non-negotiable — see ../secure-coding/SKILL.md.
+
+## Scaling: pick the right lever
+
+| Lever | What it does | Reach for it when |
+| --- | --- | --- |
+| `auto_stop_machines` / `auto_start_machines` | Fly Proxy stops/starts a **pre-created pool** by load; never creates/destroys | Bursty or idle traffic; cut cost on quiet hours |
+| `fly scale count` | You set how many Machines exist per region/process | Steady baseline capacity; geographic spread |
+| `fly-autoscaler` (superfly/fly-autoscaler) | Scales **Machine count** off any Prometheus metric | Queue depth / custom-metric driven autoscaling |
+| `fly-replay` header | App returns `fly-replay` so Proxy replays the request elsewhere | Forward writes to primary region; route by tenant |
+
+Key distinction: **autostop ≠ autoscaler.** Autostop only toggles Machines that already exist; it never changes the count. The metrics autoscaler is what actually adds/removes Machines. Set `auto_stop_machines` and `auto_start_machines` **together** — configuring one without the other is undefined behavior.
+
+`fly-replay` is the multi-region write-forwarding pattern: read-replicas serve local reads, a write replies with `fly-replay: region=<primary>` and the Proxy re-runs the request there. Full header forms and the primary/replica split are in `references/multi-region.md`.
+
+## Cost & HA
+
+- **min 2 Machines for HA.** A single Machine = a single point of failure; Fly recommends ≥2 per group in production.
+- **Stopped Machines are cheap** — you pay for rootfs/volume storage, not running compute. So a warm pool with `auto_stop_machines = "stop"` is the default cost play.
+- **Scale to zero** (`min_machines_running = 0`) trades cost for a **cold start** on the next request. If the first-request latency hurts, set `min_machines_running = 1` to keep one warm. Note: `min_machines_running` is honored **only in the primary region**.
+- `"suspend"` resumes faster than `"stop"` (keeps memory snapshot) but is supported on fewer setups — verify before relying on it.
+
+## Verify
+
+After writing or editing a `fly.toml`, run the checker:
+
+```bash
+scripts/verify.sh path/to/fly.toml   # defaults to ./fly.toml
+```
+
+It prefers `fly config validate` when flyctl is on PATH, else does structural checks (app, primary_region, an internal_port, and the autostop-pair lint). Read-only; exits nonzero on any FAIL.
+
+## Anti-patterns
+
+| Anti-pattern | Why it bites | Do instead |
+| --- | --- | --- |
+| Secrets in `[env]` or the Dockerfile | Committed to git, baked into image layers | `fly secrets set` |
+| `fly scale count` on a `[[mounts]]` group expecting shared data | Each new Machine gets an empty volume | Single writer + stateless replicas + DB/fly-replay |
+| Setting only `auto_stop_machines` | Half-configured autostop is undefined | Set start + stop keys together |
+| Assuming autostop changes Machine count | It only toggles a fixed pool | Use `fly scale count` or `fly-autoscaler` |
+| One Machine in production | No HA; a host blip = downtime | ≥2 Machines per group |
+| Bigger VM to fix far-away latency | Distance, not CPU, is the cost | Add a Machine in the user's region |
+| Volume in a different region than its Machine | Cannot attach across regions | Create the volume in the Machine's region |
+| Treating Fly Postgres as managed | Fly Postgres is unmanaged; you operate it | Route to it here; operate it via ../postgresdb/SKILL.md |
+| `min_machines_running` in a non-primary region | Ignored outside primary | Keep warm capacity via `scale count` there |
+| `fly deploy` with no `release_command` for a schema change | New code hits an old schema mid-rollout | `release_command` runs the migration first |
+
+## Related skills
+
+- ../docker/SKILL.md — the Dockerfile/image build Fly consumes.
+- ../scaling/SKILL.md — generic horizontal-scaling theory (queues, sharding, load shedding).
+- ../postgresdb/SKILL.md — operating the Postgres engine itself; Fly Postgres is unmanaged.
+- ../railway/SKILL.md — git-push PaaS with no Machines/regions model.
+- ../domains-dns/SKILL.md — custom domains, certs, registrar-level DNS.
+- ../secure-coding/SKILL.md — secret handling beyond `fly secrets`.

package/skills/fly-io/evals/README.md

@@ -0,0 +1,3 @@
+# Evals for fly-io
+
+These cases are routing/trigger fixtures, not executed tests. To run them, read each `should_trigger` prompt against this skill's `description` and body and confirm it would load fly-io (the non-obvious ones — the `iad`/latency prompt with no "Fly" keyword, and the Catalan one — are the real checks). Read each `should_not_trigger` prompt and confirm it routes to the named sibling (`railway`, `vercel`, `docker`, `scaling`) instead. For the `capability` case, draft the fly.toml + commands the scenario asks for and check it against every `must_include` rubric line. There is no test runner; the rigor is whether a fresh agent reaches the same trigger, routing, and rubric decisions.