trunative 1.0.0

package/src/skills/references/fonts.json

@@ -0,0 +1,339 @@
+{
+  "note": "Typefaces reachable per platform and per stack, and what it costs to reach them. Lookup only: the rules are in heuristics/typography.md and the per-role sizes are in type-scales.md.",
+  "updated": "2026-09-06",
+  "sources": [
+    "https://developer.apple.com/fonts/",
+    "https://fonts.google.com",
+    "https://github.com/material-components/material-components-android"
+  ],
+  "rules_of_thumb": [
+    "A face that ships with the OS costs no download, no cold start and no licence review. Start there and leave it only for a reason you can state.",
+    "A face that arrives without a reason is the tell. Inter unchosen is not a choice.",
+    "Two families is the ceiling, and the second one needs a job the first cannot do.",
+    "Whichever face wins, it reaches the screen through the platform text style, so the user's size setting still applies.",
+    "Before committing to a face for a localised app, check that it covers the scripts the product ships in. Coverage is per family, not per foundry."
+  ],
+  "platforms": {
+    "ios": {
+      "ui_default": "SF Pro",
+      "licence": "SF Pro, SF Compact, SF Mono and New York are licensed by Apple for use on Apple platforms. They do not travel to an Android build or a website.",
+      "system_faces": [
+        {
+          "family": "SF Pro",
+          "kind": "sans",
+          "note": "the UI face. Optical sizes switch on their own: Text below 20pt, Display at 20pt and above"
+        },
+        {
+          "family": "SF Pro Rounded",
+          "kind": "sans",
+          "note": "softer register, same metrics"
+        },
+        {
+          "family": "SF Compact",
+          "kind": "sans",
+          "note": "narrower, drawn for cramped UI"
+        },
+        {
+          "family": "SF Mono",
+          "kind": "mono",
+          "note": "code and fixed-width data"
+        },
+        {
+          "family": "New York",
+          "kind": "serif",
+          "note": "the system serif, cut to pair with SF at the same optical sizes"
+        }
+      ],
+      "preinstalled": {
+        "note": "Reachable by family name with no bundling. These are not the UI face and Apple does not guarantee them across OS versions, so confirm before depending on one.",
+        "sans": [
+          "Arial",
+          "Avenir",
+          "Avenir Next",
+          "Futura",
+          "Gill Sans",
+          "Helvetica",
+          "Helvetica Neue",
+          "Optima",
+          "Trebuchet MS",
+          "Verdana"
+        ],
+        "serif": [
+          "American Typewriter",
+          "Baskerville",
+          "Bodoni 72",
+          "Charter",
+          "Cochin",
+          "Didot",
+          "Georgia",
+          "Hoefler Text",
+          "Palatino",
+          "Times New Roman"
+        ],
+        "mono": [
+          "Courier New",
+          "Menlo"
+        ],
+        "display_script": [
+          "Chalkboard SE",
+          "Copperplate",
+          "Marker Felt",
+          "Papyrus",
+          "Snell Roundhand",
+          "Zapfino"
+        ]
+      }
+    },
+    "android": {
+      "ui_default": "Roboto on AOSP",
+      "licence": "Roboto and Noto are Apache-2.0 and can be bundled anywhere, including into an iOS build or a website.",
+      "warning": "The UI face is whatever the OEM shipped. Samsung One UI, OnePlus and MIUI each substitute their own, and the user can change it in settings. Roboto is the AOSP default, not a promise, so never let a layout depend on Roboto metrics.",
+      "system_aliases": {
+        "note": "How the bundled faces are actually reached, in XML or in Compose FontFamily.",
+        "sans-serif": "Roboto",
+        "sans-serif-condensed": "Roboto Condensed",
+        "sans-serif-medium": "Roboto at 500",
+        "sans-serif-light": "Roboto at 300, below the weight floor for body text",
+        "sans-serif-thin": "Roboto at 100, display only, and rarely even then",
+        "serif": "Noto Serif",
+        "monospace": "Droid Sans Mono",
+        "serif-monospace": "Cutive Mono",
+        "casual": "Coming Soon",
+        "cursive": "Dancing Script"
+      },
+      "other_bundled": [
+        {
+          "family": "Roboto Flex",
+          "note": "variable, full axis set. Bundled only on recent releases: check the API level before relying on it instead of shipping it"
+        },
+        {
+          "family": "Noto",
+          "note": "the script coverage behind the system. This is what renders text the UI face has no glyphs for"
+        },
+        {
+          "family": "Noto Color Emoji",
+          "note": "emoji come from here, and they are not a substitute for an icon set"
+        }
+      ],
+      "downloadable_fonts": {
+        "note": "The whole Google Fonts catalogue without bundling a file, served and cached by Google Play Services. This is the Android answer to a brand face on a size budget.",
+        "provider": "com.google.android.gms.fonts",
+        "xml": "<font-family app:fontProviderAuthority=\"com.google.android.gms.fonts\" app:fontProviderQuery=\"Manrope\" .../>",
+        "compose": "androidx.compose.ui.text.googlefonts.GoogleFont with GoogleFont.Provider",
+        "caution": "The first request can miss, and the device may have no Play Services at all. Always declare a bundled or system fallback, and never let the first screen wait on it."
+      }
+    }
+  },
+  "stacks": {
+    "flutter": {
+      "default": "Material widgets fall back to Roboto, which the framework carries; Cupertino widgets take the system face on Apple platforms.",
+      "custom": "Declare the family in pubspec.yaml, or use the google_fonts package.",
+      "caution": "google_fonts downloads at runtime by default, which means a fallback frame and a network dependency. For a face used on the first screen, bundle the file instead."
+    },
+    "react_native_expo": {
+      "default": "fontFamily: 'System' resolves to SF on iOS and to the OEM UI face on Android.",
+      "custom": "expo-font, or the @expo-google-fonts/<family> packages, which bundle the file.",
+      "caution": "Fonts load asynchronously. Hold the splash screen until they are ready, or the first paint ships in the fallback face and reflows in front of the user."
+    },
+    "swiftui_uikit": {
+      "default": ".font(.body) and the rest of the text styles.",
+      "custom": "Font.custom(_:size:relativeTo:) in SwiftUI, UIFontMetrics in UIKit. A custom face without one of those does not scale and does not ship."
+    },
+    "jetpack_compose": {
+      "default": "MaterialTheme.typography, which resolves to the platform face.",
+      "custom": "FontFamily from a bundled resource or from the Google Fonts provider, wired into a Typography object rather than applied per Text."
+    },
+    "mobile_web": {
+      "default": "system-ui, -apple-system, 'Segoe UI', Roboto, 'Helvetica Neue', Arial, sans-serif",
+      "custom": "Self-host the subset files and declare font-display: swap. Preload only the faces the first screen needs.",
+      "caution": "Loading from the Google Fonts CDN sends the visitor's IP to a third party, which has been ruled a problem under GDPR in at least one jurisdiction. Self-hosting removes the question and is usually faster anyway."
+    }
+  },
+  "google_fonts": {
+    "note": "Open licence (OFL or Apache-2.0), free to bundle and subset. The catalogue is the practical answer for every stack except a pure Apple build, where the system face is already better integrated.",
+    "how_to_choose": [
+      "Pick the workhorse first: it carries body, labels and controls, and it needs every weight and the right scripts.",
+      "A display face is a second decision, and it only earns its place if the product has display-sized moments.",
+      "Prefer a variable family where the stack supports it: the weight axis interpolates, so a hierarchy step never lands on a cut that was never drawn.",
+      "Numeric columns need tabular figures. Most families here support the tnum feature, but confirm it before designing a table around it."
+    ],
+    "interface": [
+      {
+        "family": "Inter",
+        "variable": true,
+        "scripts": "latin, cyrillic, greek",
+        "good_for": "neutral UI at small sizes",
+        "caution": "the default a model reaches for. Fine when chosen on purpose, a tell when it just appears"
+      },
+      {
+        "family": "Roboto",
+        "variable": true,
+        "scripts": "latin, cyrillic, greek",
+        "good_for": "matching the Android platform look deliberately"
+      },
+      {
+        "family": "Roboto Flex",
+        "variable": true,
+        "axes": "weight, width, optical size, grade and more",
+        "scripts": "latin, cyrillic, greek",
+        "good_for": "one file covering the whole ramp, including the M3 expressive axes"
+      },
+      {
+        "family": "Noto Sans",
+        "variable": true,
+        "scripts": "the widest coverage in the catalogue",
+        "good_for": "a product shipping in scripts other families drop"
+      },
+      {
+        "family": "Open Sans",
+        "variable": true,
+        "scripts": "latin, cyrillic, greek",
+        "good_for": "plain, legible, very broad language support"
+      },
+      {
+        "family": "Source Sans 3",
+        "variable": true,
+        "scripts": "latin, cyrillic, greek",
+        "good_for": "a neutral workhorse with a matching serif and mono"
+      },
+      {
+        "family": "IBM Plex Sans",
+        "variable": true,
+        "scripts": "latin, cyrillic, greek",
+        "good_for": "an engineered voice, with Serif, Mono and Condensed siblings"
+      },
+      {
+        "family": "Public Sans",
+        "variable": true,
+        "scripts": "latin",
+        "good_for": "civic and utility products that want no accent at all"
+      },
+      {
+        "family": "DM Sans",
+        "variable": true,
+        "scripts": "latin",
+        "good_for": "geometric product UI with slightly rounded forms"
+      },
+      {
+        "family": "Plus Jakarta Sans",
+        "variable": true,
+        "scripts": "latin",
+        "good_for": "product UI with a little more character than Inter"
+      },
+      {
+        "family": "Manrope",
+        "variable": true,
+        "scripts": "latin, cyrillic, greek",
+        "good_for": "semi-geometric UI, reads well at label sizes"
+      },
+      {
+        "family": "Figtree",
+        "variable": true,
+        "scripts": "latin",
+        "good_for": "friendly consumer apps"
+      },
+      {
+        "family": "Work Sans",
+        "variable": true,
+        "scripts": "latin",
+        "good_for": "a grotesque with warmth, good from label to headline"
+      },
+      {
+        "family": "Archivo",
+        "variable": true,
+        "axes": "weight and width",
+        "scripts": "latin, cyrillic, greek",
+        "good_for": "dense UI where a width axis solves a long-label problem"
+      },
+      {
+        "family": "Instrument Sans",
+        "variable": true,
+        "scripts": "latin",
+        "good_for": "neutral with an edge, holds up in both UI and headline roles"
+      },
+      {
+        "family": "Space Grotesk",
+        "variable": true,
+        "scripts": "latin",
+        "good_for": "a technical voice",
+        "caution": "distinctive enough that it tires at body length"
+      }
+    ],
+    "reading_and_display": [
+      {
+        "family": "Literata",
+        "variable": true,
+        "kind": "serif",
+        "good_for": "long reading on a screen, which is what it was drawn for"
+      },
+      {
+        "family": "Source Serif 4",
+        "variable": true,
+        "kind": "serif",
+        "good_for": "body serif that pairs with Source Sans"
+      },
+      {
+        "family": "Newsreader",
+        "variable": true,
+        "kind": "serif",
+        "good_for": "editorial body and headline in one family"
+      },
+      {
+        "family": "Lora",
+        "variable": true,
+        "kind": "serif",
+        "good_for": "warm body serif for reading-heavy screens"
+      },
+      {
+        "family": "Fraunces",
+        "variable": true,
+        "kind": "serif display",
+        "axes": "weight, optical size, softness, wonk",
+        "good_for": "display with a real point of view",
+        "caution": "display sizes only"
+      },
+      {
+        "family": "Playfair Display",
+        "variable": true,
+        "kind": "serif display",
+        "good_for": "high contrast headlines",
+        "caution": "the thin strokes disappear at small sizes and in sunlight"
+      },
+      {
+        "family": "Instrument Serif",
+        "variable": false,
+        "kind": "serif display",
+        "good_for": "a single large moment per screen"
+      },
+      {
+        "family": "Bricolage Grotesque",
+        "variable": true,
+        "kind": "display",
+        "good_for": "an opinionated headline face that still has a usable weight range"
+      }
+    ],
+    "mono": [
+      {
+        "family": "JetBrains Mono",
+        "variable": true,
+        "good_for": "code, with a tall x-height that survives small sizes"
+      },
+      {
+        "family": "IBM Plex Mono",
+        "variable": false,
+        "good_for": "code and data next to Plex Sans"
+      },
+      {
+        "family": "Roboto Mono",
+        "variable": true,
+        "good_for": "code and tabular data in an Android-native product"
+      },
+      {
+        "family": "Space Mono",
+        "variable": false,
+        "good_for": "short technical labels",
+        "caution": "not a reading face"
+      }
+    ]
+  }
+}

package/src/skills/references/icon-and-image-assets.md

@@ -0,0 +1,103 @@
+# Icon and image assets, per stack
+
+Lookup only. The rules live in `heuristics/icons-and-imagery.md`. Open this file for one size, one axis or one API name, not as background reading.
+
+## Symbol sets
+
+| Set | Axes and variants | What it gives for free |
+|---|---|---|
+| SF Symbols (iOS) | 9 weights, ultralight to black, each mapped to a San Francisco font weight; 3 scales (small, medium, large) defined against the cap height; outline, fill, slash and enclosed variants | Baseline information on every symbol, Dynamic Type scaling when configured with a text style, and per-script variants that follow the device language |
+| Material Symbols (Android, web) | One variable font in Outlined, Rounded and Sharp. `opsz` 20 to 48, default 24. `wght` 100 to 700, default 400. `GRAD` -50 to 200, default 0. `FILL` 0 to 1, default 0 | One file for every weight and fill; `FILL` is animatable for selection |
+
+Axis meanings: `wght` is the stroke weight and moves the overall size a little. `GRAD` changes thickness more finely with almost no size change; -50 is the value for light artwork on a dark ground. `opsz` retunes the stroke so the glyph looks the same at a different size. `FILL` is for state.
+
+Only the 20 px and 24 px Material Symbols are drawn on a perfect pixel grid.
+
+Flutter's bundled `Icons` is the older Material Icons set, while its `Icon` widget already takes `fill`, `weight`, `grade` and `opticalSize`. A project that wants current Material Symbols imports the font or the SVGs itself.
+
+`IconThemeData.fallback()` in Flutter: size 24.0, fill 0.0, weight 400.0, grade 0.0, opticalSize 48.0. Note the mismatch: the default optical size is 48 while the default size is 24. `applyTextScaling` resolves to false unless set on the widget or the `IconTheme`.
+
+Compose `Icon` is 24.dp when the painter has no intrinsic size, and is tinted with `LocalContentColor.current`. The `material-icons` and `material-icons-extended` artifacts are no longer recommended by Google.
+
+## Raster variants, by stack
+
+| Stack | How a variant is named | Notes |
+|---|---|---|
+| iOS asset catalog | `@2x` and `@3x` filename suffixes | iOS ships at 2x and 3x. `scale` and `nativeScale` can differ |
+| Android resources | `res/drawable-<bucket>/` | A vector drawable goes in the default `res/drawable/` with no per-density copy |
+| Flutter | `2.0x/name.png` beside `name.png` | Nominal densities 1.5x, 2.0x, 3.0x, 4.0x. List only the main asset or its folder in `pubspec.yaml` |
+| React Native | `name@2x.png` sibling files, one `require` | The closest density is picked when the exact one is missing. A `uri` source carries no dimensions |
+
+## Android density buckets
+
+| Bucket | Approx dpi | Scale | A 48 px mdpi bitmap becomes |
+|---|---|---|---|
+| ldpi | 120 | 0.75x | 36 px |
+| mdpi | 160 (baseline) | 1x | 48 px |
+| hdpi | 240 | 1.5x | 72 px |
+| xhdpi | 320 | 2x | 96 px |
+| xxhdpi | 480 | 3x | 144 px |
+| xxxhdpi | 640 | 4x | 192 px |
+
+Ratio 3:4:6:8:12:16. `px = dp * (dpi / 160)`, converted with `TypedValue.applyDimension()` rather than hardcoded. `nodpi` is never scaled. `sp` matches `dp` until the user changes the text size, and is never used for layout.
+
+## Vector drawables
+
+Android has no native SVG. Convert with Vector Asset Studio (`res` > New > Vector Asset). Keep one at 200 by 200 dp or under, past which it takes too long to draw. Author a tintable icon in solid black (`android:fillColor="#FF000000"`). `VectorDrawable` and `AnimatedVectorDrawable` land in API 21, with `VectorDrawableCompat` and `AnimatedVectorDrawableCompat` below it.
+
+## Formats
+
+Flat artwork that scales: PDF or SVG. Bitmap work: de-interlaced PNG, or an 8-bit palette where 24-bit colour is not needed. Photographs: JPEG or HEIC. Design at the lowest resolution and scale up, keeping control points on whole values so the shape stays on the raster grid at 2x and 3x.
+
+## Fill and fit
+
+| Stack | Fill the frame and crop | Fit inside the frame |
+|---|---|---|
+| SwiftUI | `.scaledToFill()` with `.clipped()` | `.scaledToFit()` |
+| UIKit | `.scaleAspectFill` | `.scaleAspectFit` |
+| Compose | `ContentScale.Crop` | `ContentScale.Fit` |
+| Flutter | `BoxFit.cover` | `BoxFit.contain` |
+| React Native | `resizeMode="cover"` | `resizeMode="contain"` |
+| Mobile web | `object-fit: cover` | `object-fit: contain` |
+
+## Dark variants
+
+iOS: a second appearance inside the asset catalog entry, resolved by the system. Android: `res/drawable-night/` beside `res/drawable/`. Flutter and React Native resolve the file themselves from the platform brightness.
+
+## App icon
+
+| Platform | Canvas | Structure |
+|---|---|---|
+| iOS | 1024 by 1024 px, square, no transparency, no rounded corners | Layered: one background plus one or more foreground layers, assembled in Icon Composer. Prefer SVG or PDF layers; PNG only for mesh gradients and raster art. Ship layers unmasked |
+| Android adaptive | 108 by 108 dp layers | `<adaptive-icon>` in `res/mipmap-anydpi-v26/ic_launcher.xml` with `<background>`, `<foreground>` and `<monochrome>`. Referenced from the manifest as `android:icon`, with `android:roundIcon` alongside it for the launchers that ask for a round variant |
+| Play listing | 512 by 512 px, 32-bit PNG with alpha, 1024 KB maximum | Feature graphic 1024 by 500 px, JPEG or 24-bit PNG, no alpha |
+
+Adaptive icon geometry: a 72 dp masked viewport out of the 108 dp canvas, with the outer 18 dp on each side reserved for masking and for parallax or pulse effects. Keep the mark inside the 66 dp safe box and at least 48 dp across. Layers carry no mask and no outline shadow, and vectors are preferred over bitmaps.
+
+Themed icons need the `<monochrome>` layer. User theming arrives in Android 13 (API 33). From Android 16 QPR 2 the system themes icons for apps that supply no monochrome layer.
+
+iOS appearances: default, dark, clear light, clear dark, tinted light, tinted dark. The system generates any variant not supplied, and each alternate app icon needs its own set. Colour spaces: sRGB, Gray Gamma 2.2, Display P3.
+
+Let the system draw the specular highlight, the shadow between layers, the bevel, the blur and the glow. Avoid soft or feathered edges on foreground shapes, extremely thin strokes and sharp corners.
+
+Licensing: system symbols may not be used in an app icon, a logo or any other trademarked use, and platform hardware may not be reproduced.
+
+Expo keys: `icon`; `ios.icon` taking either a path to a `.icon` directory (SDK 54 and later) or an object of `light`, `dark` and `tinted` PNGs; `android.icon`; `android.adaptiveIcon.foregroundImage`, `.backgroundColor`, `.backgroundImage` and `.monochromeImage`.
+
+## Generating the icon set
+
+Every stack has a generator that takes one master image and writes every density, catalog entry and adaptive layer. Five things about them cost an afternoon each, and none of them surfaces as an error.
+
+**The dedicated config file wins over the manifest block.** Where a generator reads configuration from two places, a file of its own at the project root and a block inside the dependency manifest, the file is tried first and the manifest block is only the fallback. `flutter_launcher_icons` loads `flutter_launcher_icons.yaml` and drops to the `pubspec.yaml` block only when that returns nothing, with no message either way. A project forked from another app carries that file with the *other app's* artwork paths, so the generator runs, reports success, and produces the wrong app's icon. Look for the dedicated file before writing any configuration, and when finished leave one of the two, not both.
+
+**The generator applies its own inset, so the safe zone gets applied twice.** It wraps the foreground in an `<inset>` inside the adaptive icon XML, expressed as a percentage: `flutter_launcher_icons` writes `android:inset="16%"` unless `adaptive_icon_foreground_inset` says otherwise, which already accounts for most of the 108/72/66 dp geometry. Artwork pre-shrunk to the 66 dp safe box before handing it over comes out visibly small inside the mask. Either hand over full-bleed artwork and let the inset do the work, or raise the artwork's radius so that radius times the remaining fraction lands inside the safe box. The inset is configurable; editing the generated XML by hand is not, because the next run overwrites it.
+
+**Measure the output, do not infer it.** Open the generated foreground, measure the bounding box of the non-transparent pixels, and compare its radius against the safe box. This is the only check that catches the double inset, and it takes one command.
+
+**Rasterisers drop what the design tool shows.** Blend modes, filters and effects are commonly ignored when an SVG is converted to PNG, so the raster differs from the artboard. Open the generated file and look at it. When judging a transparent foreground, composite it over the real background colour first: white artwork on the viewer's white backdrop reads as an empty file, and the natural conclusion, that the conversion lost the shape, is wrong.
+
+**Generators overwrite what they still produce and orphan the rest.** Switching an adaptive background from image to colour leaves the old background bitmap in every density bucket; dropping a platform leaves its whole directory. Nothing reports it, the files ship inside the binary, and the stale artwork resurfaces later. After changing artwork or configuration, delete the generated directories and regenerate, rather than generating over the top, then scan the output for the old palette to prove nothing survived.
+
+## Loading APIs
+
+Android decodes at the size drawn: `BitmapFactory.Options.inJustDecodeBounds` reads `outWidth` and `outHeight` without allocating, then `inSampleSize` decodes down. In practice a library does this: Glide, Coil (`AsyncImage`), Picasso or Fresco. Compose loads bundled assets with `painterResource`, which handles PNG, JPEG, WEBP, vector drawables and animated vector drawables. SwiftUI has `AsyncImage` for network images and `Image(decorative:)` for an unlabelled one.

package/src/skills/references/input-fields.md

@@ -0,0 +1,82 @@
+# Input fields
+
+Lookup only. The rules live in `heuristics/forms.md`. Open this file for one field's keyboard or autofill name, not as background reading.
+
+Two settings per field, and they are separate: the keyboard decides what the user can type, the content type decides what the platform can fill in for them. Setting one does not set the other.
+
+## Keyboard type
+
+| Field | SwiftUI `.keyboardType` | Compose `KeyboardType` | Flutter `TextInputType` | React Native `keyboardType` | Web `inputmode` |
+|---|---|---|---|---|---|
+| email | `.emailAddress` | `Email` | `.emailAddress` | `email-address` | `email` |
+| telephone | `.phonePad` | `Phone` | `.phone` | `phone-pad` | `tel` |
+| whole number | `.numberPad` | `Number` | `.number` | `number-pad` | `numeric` |
+| money or measure | `.decimalPad` | `Decimal` | `.numberWithOptions(decimal: true)` | `decimal-pad` | `decimal` |
+| URL | `.URL` | `Uri` | `.url` | `url` | `url` |
+| search | `.webSearch` | `Text` | `.text` | `web-search` | `search` |
+| password | `.default` | `Password` | `.visiblePassword` where shown | `default` | `text` |
+| multi-line note | `.default` | `Text` | `.multiline` | `default` | `text` |
+
+Card numbers and one time codes are numeric keyboards over a text field, never a number field. A number field brings steppers, drops leading zeros, and on the web turns a mistyped digit into a scroll event.
+
+## Return key
+
+| Meaning | SwiftUI | Compose | Flutter | React Native | Web |
+|---|---|---|---|---|---|
+| next field | `.submitLabel(.next)` | `ImeAction.Next` | `TextInputAction.next` | `returnKeyType="next"` | `enterkeyhint="next"` |
+| last field | `.submitLabel(.done)` | `ImeAction.Done` | `TextInputAction.done` | `"done"` | `"done"` |
+| submit now | `.submitLabel(.go)` | `ImeAction.Go` | `TextInputAction.go` | `"go"` | `"go"` |
+| search | `.submitLabel(.search)` | `ImeAction.Search` | `TextInputAction.search` | `"search"` | `"search"` |
+
+## Autofill content type
+
+| Value | SwiftUI `.textContentType` | Compose `ContentType` | Flutter `AutofillHints` | React Native `autoComplete` | Web `autocomplete` |
+|---|---|---|---|---|---|
+| email | `.emailAddress` | `EmailAddress` | `.email` | `email` | `email` |
+| username | `.username` | `Username` | `.username` | `username` | `username` |
+| existing password | `.password` | `Password` | `.password` | `current-password` | `current-password` |
+| new password | `.newPassword` | `NewPassword` | `.newPassword` | `new-password` | `new-password` |
+| one time code | `.oneTimeCode` | `SmsOtpCode` | `.oneTimeCode` | `sms-otp` | `one-time-code` |
+| full name | `.name` | `PersonFullName` | `.name` | `name` | `name` |
+| given name | `.givenName` | `PersonFirstName` | `.givenName` | `given-name` | `given-name` |
+| family name | `.familyName` | `PersonLastName` | `.familyName` | `family-name` | `family-name` |
+| telephone | `.telephoneNumber` | `PhoneNumber` | `.telephoneNumber` | `tel` | `tel` |
+| street | `.streetAddressLine1` | `AddressStreet` | `.streetAddressLine1` | `street-address` | `street-address` |
+| city | `.addressCity` | `AddressLocality` | `.addressCity` | `postal-address-locality` | `address-level2` |
+| postal code | `.postalCode` | `PostalCode` | `.postalCode` | `postal-code` | `postal-code` |
+| country | `.countryName` | `AddressCountry` | `.countryName` | `country` | `country-name` |
+| card number | `.creditCardNumber` | `CreditCardNumber` | `.creditCardNumber` | `cc-number` | `cc-number` |
+| card expiry | `.creditCardExpiration` | `CreditCardExpirationDate` | `.creditCardExpirationDate` | `cc-exp` | `cc-exp` |
+| security code | `.creditCardSecurityCode` | `CreditCardSecurityCode` | `.creditCardSecurityCode` | `cc-csc` | `cc-csc` |
+
+On iOS, the same attribute is `textContentType` on `UITextField` and a prop of the same name in React Native, which is the one that drives fill on that platform.
+
+On Android, the Compose semantics property landed in Compose 1.8; view layouts use `android:autofillHints` with the `AUTOFILL_HINT_*` string of the same meaning.
+
+## Grouping and saving
+
+A credential is filled and saved as a set, so the fields have to be declared as one.
+
+- SwiftUI: fields in the same form are grouped by the system; submit ends the session.
+- Compose: read `LocalAutofillManager` and call `commit()` when the form is submitted, or nothing is offered for saving.
+- Flutter: wrap the fields in `AutofillGroup`, then call `TextInput.finishAutofillContext()` on submit.
+- React Native: `importantForAutofill` on the container, plus the props above per field.
+- Web: one `<form>` element around the fields, and a real submit.
+
+## One time codes
+
+One field, numeric keyboard, the one time code content type. The platform reads the message and offers the digits above the keyboard.
+
+- iOS fills from Messages with no extra work once `.oneTimeCode` is set.
+- Android reads the SMS through the SMS Retriever API, or the User Consent API where the message is not formatted for retrieval.
+- Mobile web can additionally use the WebOTP API through `navigator.credentials.get()` with an `otp` request.
+
+## Capitalisation and correction
+
+| Field | Capitalisation | Autocorrect |
+|---|---|---|
+| email, username, password, code, URL | none | off |
+| person or street name | words | off |
+| free text, note, message | sentences | on |
+
+The names of these settings: `.textInputAutocapitalization()` and `.autocorrectionDisabled()` in SwiftUI, `KeyboardOptions(capitalization =, autoCorrectEnabled =)` in Compose, `textCapitalization` and `autocorrect` in Flutter, `autoCapitalize` and `autoCorrect` in React Native, `autocapitalize` and `autocorrect` in HTML.

package/src/skills/references/launch-surface.md

@@ -0,0 +1,94 @@
+# Launch surface configuration, per stack
+
+Lookup only. The rules live in `heuristics/splashscreen.md`. Open this file for one key, one attribute or one dismissal API, not as background reading.
+
+Nothing here is a design decision. The decision is in the heuristic; this is where the name of the knob lives.
+
+## iOS: the two supported routes
+
+Pick one. Both satisfy the same requirement.
+
+| Route | Key | What it holds |
+|---|---|---|
+| Property list | `UILaunchScreen` dictionary in `Info.plist` | `UIColorName` (background color), `UIImageName`, `UIImageRespectsSafeAreaInsets`, plus `UINavigationBar`, `UITabBar`, `UIToolbar` to draw empty bars |
+| Interface file | `UILaunchStoryboardName` pointing at `LaunchScreen.storyboard` | UIKit views only |
+| Per URL scheme | `UILaunchScreens` | one launch screen per scheme |
+| Legacy | `UILaunchImages` | deprecated, do not add it |
+
+The storyboard route is deliberately inert: one root `UIView` or `UIViewController`, UIKit classes only, no outlets, no actions, no custom classes, no user defined runtime attributes. Nothing in it executes.
+
+The launch screen is required on iOS and iPadOS. No size, resolution or file weight limit is published for it, because the property list route takes a color and the storyboard route is constraint based.
+
+A launch that never draws its first frame is killed by the system watchdog. The crash carries termination reason `SPRINGBOARD`, code `0x8badf00d`, and a `scene-create` watchdog event.
+
+## Android: theme attributes
+
+Two sets with the same job. The compat set has no `android:` prefix and is the one to use, because it produces the same surface back to older releases.
+
+| Purpose | Platform (Android 12+) | Compat (`androidx.core:core-splashscreen`) |
+|---|---|---|
+| Window background, one opaque color | `android:windowSplashScreenBackground` | `windowSplashScreenBackground` |
+| Centre icon | `android:windowSplashScreenAnimatedIcon` | `windowSplashScreenAnimatedIcon` |
+| Icon animation duration | `android:windowSplashScreenAnimationDuration` | `windowSplashScreenAnimationDuration` |
+| Circle behind the icon | `android:windowSplashScreenIconBackgroundColor` | `windowSplashScreenIconBackgroundColor` |
+| Theme applied once the surface goes | (the activity theme) | `postSplashScreenTheme`, required |
+| Icon size | (fixed) | `splashScreenIconSize` |
+| Branding image at the bottom | `android:windowSplashScreenBrandingImage` | not present |
+| Always show the icon | `android:windowSplashScreenBehavior`, value `icon_preferred` | not present |
+
+Compat themes: `Theme.SplashScreen` as the parent, `Theme.SplashScreen.IconBackground` when the icon sits on a circle. Some Android documentation writes the icon background attribute without the `Color` suffix; the library only declares `windowSplashScreenIconBackgroundColor`.
+
+Setting `android:windowBackground` in a launch theme is the pre Android 12 pattern. From Android 12 the system discards that custom splash and shows its own default one instead, so the configured background never appears. A dedicated splash Activity is the separate case, and it produces two surfaces rather than one wrong one. Do not pin a `core-splashscreen` version from prose; read the current one from the dependency catalogue.
+
+## Android: holding and dismissing
+
+| Need | API |
+|---|---|
+| Install the surface | `installSplashScreen(activity)`, called before `super.onCreate()` |
+| Hold it | `setKeepOnScreenCondition { }`, returning `true` to hold. Compat only |
+| Hold it without the library | `ViewTreeObserver.OnPreDrawListener` on `android.R.id.content`, returning `false` to suspend |
+| Own the exit | `setOnExitAnimationListener { }`, then `SplashScreenViewProvider.remove()` |
+| Remaining icon time | `iconAnimationStartMillis`, `iconAnimationDurationMillis` |
+
+The framework interface `android.window.SplashScreen` carries only `setOnExitAnimationListener`, `clearOnExitAnimationListener` and `setSplashScreenTheme`. There is no keep on screen condition outside the compat library.
+
+## Asset geometry, Android
+
+| Asset | Size | Visible area |
+|---|---|---|
+| Icon with an icon background | 240x240 dp | fits a 160 dp circle |
+| Icon without an icon background | 288x288 dp | fits a 192 dp circle |
+| Animated vector icon | 432 dp icon area | 288 dp inner area |
+| Branding image | 200x80 dp | leave it empty |
+
+One third of the icon foreground is masked. Anything drawn in the outer third does not survive.
+
+## Flutter
+
+| Platform | Where |
+|---|---|
+| iOS | `ios/Runner/Base.lproj/LaunchScreen.storyboard`, assets in the `LaunchImage` set inside `Runner/Assets.xcassets` |
+| Android | `LaunchTheme` in `android/app/src/main/res/values/styles.xml`, with a `values-night` copy for dark |
+| Android handoff | manifest `meta-data` on the Flutter activity, `io.flutter.embedding.android.NormalTheme` pointing at `@style/NormalTheme` |
+
+The Flutter template still teaches `android:windowBackground` on `LaunchTheme`. On Android 12 and up, put the `windowSplashScreen*` attributes there instead, or add the compat library. Keep `NormalTheme` on the same background color as the first Flutter frame.
+
+## Expo
+
+| Need | Where |
+|---|---|
+| Configure | the `expo-splash-screen` config plugin, under `expo.plugins` in the app config |
+| Properties | `backgroundColor`, `image`, `imageWidth`, `resizeMode` (`contain`, `cover`, `native`), `dark` with its own `backgroundColor` and `image`, plus per platform `android` and `ios` blocks |
+| Hold it | `SplashScreen.preventAutoHideAsync()`, called in module scope rather than inside a component |
+| Dismiss it | `SplashScreen.hide()` or `SplashScreen.hideAsync()` |
+| Exit options | `SplashScreen.setOptions({ duration, fade })`, `fade` iOS only |
+
+The icon must be a PNG. Any other format fails the production build. A 1024x1024 source with a transparent background is the recommended input.
+
+## Bare React Native
+
+No core API exists. The surface is the platform's own, `UILaunchScreen` or the storyboard on iOS and `Theme.SplashScreen` on Android, reached either directly or through a package recorded in `STACK.md`.
+
+## Mobile web
+
+There is no OS drawn launch surface for a page. An installed web app gets one from the manifest: `background_color`, `theme_color`, `name` and the icon set. A first paint that arrives quickly is the only equivalent a browser tab has.