vybekiit 0.7.26 → 0.7.27

package/dist/global-skills/expo-design-system/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: expo-design-system
-description: Framework (OSS). Build and maintain a design system inside an Expo app - a reusable theme of design tokens (color, spacing, typography, radius, shadow, motion), reusable component structure with variant/size/state prop conventions, and rules for when to extract a repeated view into a shared component. Use when creating or organizing theme files and design tokens (theme.ts / theme/), extending an existing theme or styling library (NativeWind, Tamagui, Restyle, Unistyles) in its own idiom, standardizing styles so screens (including AI-generated ones) look consistent and polished, building an in-app component library, or auditing an app for design-system drift (hardcoded colors, spacing, fonts). For platform styling specifics (semantic colors, HIG rules, native controls) use expo-native-ui; for Tailwind/CSS setup use expo-tailwind-setup; for folder layout of a new app use expo-project-structure.
+description: Framework (OSS). Build and maintain a design system inside an Expo app - a reusable theme of design tokens (color, spacing, typography, radius, shadow, motion), reusable component structure with variant/size/state prop conventions, and rules for when to extract a repeated view into a shared component. Use when creating or organizing theme files and design tokens (theme.ts / theme/), extending an existing theme or styling library (NativeWind, Tamagui, Restyle, Unistyles) in its own idiom, standardizing styles so screens (including AI-generated ones) look consistent and polished, fixing an app that looks AI-generated or generic instead of native (the named native-slop tells), building an in-app component library, or auditing an app for design-system drift (hardcoded colors, spacing, fonts). For platform styling specifics (semantic colors, HIG rules, native controls) use expo-native-ui; for folder layout of a new app use expo-project-structure.
 version: 1.0.0
 license: MIT
 ---
@@ -12,25 +12,28 @@ Make every screen in an app draw from one visual source of truth: a token theme
 Sibling skills own the layers around this one:
 
 - `expo-native-ui` - platform styling rules (HIG, semantic colors, controls, shadows syntax). Follow it for **what values look native**; follow this skill for **where values live and how they're reused**.
-- `expo-tailwind-setup` - if the project uses Tailwind, tokens live in `global.css` as CSS variables instead of TypeScript. The scales and naming in this skill still apply; only the storage format changes.
 - `expo-project-structure` - folder skeleton for new apps.
 
+For Tailwind projects, keep tokens in `global.css` as CSS variables and follow the styling library's own setup guidance. The scales and naming in this skill still apply; only the storage format changes.
+
 ## References
 
 Consult these resources as needed:
 
 ```
 references/
-  audit.md      Audit an existing app for design-system drift: grep checks,
-                scoring rubric, incremental adoption plan, and templates for
-                documenting or extending components
+  audit.md        Audit an existing app for design-system drift: grep checks,
+                  scoring rubric, incremental adoption plan, and templates for
+                  documenting or extending components
+  native-slop.md  The 20 named anti-pattern tells of AI-generated apps (The Web
+                  Modal, Everything's a Card, ...) with grep checks for the greppable ones
 ```
 
 ## Adopt Before You Build
 
 In an app that already has screens, the first move is detection, not construction. Before writing any token file:
 
-1. **Look for a declared system.** Check `package.json` for a styling library - NativeWind/Tailwind (use `expo-tailwind-setup`), Tamagui, Restyle, Unistyles, styled-components. Then look for a token file: `theme.ts`, `src/theme/`, `constants/theme.ts`, or `constants/Colors.ts` (the create-expo-app default).
+1. **Look for a declared system.** Check `package.json` for a styling library - NativeWind/Tailwind, Tamagui, Restyle, Unistyles, styled-components. Then look for a token file: `theme.ts`, `src/theme/`, `constants/theme.ts`, or `constants/Colors.ts` (the create-expo-app default).
 2. **If one exists, it is the source of truth.** Extend it in its own idiom - its names, its scale, its storage format. Audit drift against that system, not against the examples below.
 3. **If only de facto values exist** - the same greys and paddings repeated across screens, no theme file - there is no system yet. Those values are the input to the scales, not the authority: derive tokens from the most frequent ones, snapped to the 4-point grid (`references/audit.md` §5).
 4. **Never introduce a second system beside an existing one.** A fresh `src/theme/` next to a Tamagui config is design-system drift, not adoption.
@@ -189,6 +192,8 @@ export function ThemedText({
 
 Screen titles still come from the navigation stack header (`expo-native-ui` rule), so `largeTitle` is mostly for non-stack contexts.
 
+**Dynamic Type.** Text scales with the user's system text-size setting (`allowFontScaling` is on by default). Use padding or `minHeight` around text so rows can grow, and check large accessibility text sizes. Let labels wrap or reflow before considering a per-element `maxFontSizeMultiplier` for constrained chrome; dense rows alone are not a reason to cap readable text. Never disable scaling app-wide with `allowFontScaling={false}`.
+
 ### Radius
 
 ```tsx
@@ -243,6 +248,7 @@ Every design-system primitive defines, explicitly:
 - **Sizes** - `sm`, `md`, `lg`. Default `md`. Sizes map to spacing/typography tokens, never to fresh numbers.
 - **States** - default, **pressed** (not hover - this is touch), disabled, loading. Handle pressed with a `Pressable` style function; never leave a tappable element without pressed feedback.
 - **Style override** - accept a `style` prop and merge it **last**, so callers can adjust layout (margins, flex) without forking the component. Callers may override layout, not identity - a caller changing a button's colors is a signal the variant set is missing something.
+- **Accessibility** - custom interactive primitives expose their role and disabled/busy/selected state as applicable. Text children can supply the label; icon-only controls and buttons that replace text with a spinner need an explicit label that remains available while loading. Verify labels on native controls too.
 
 ```tsx
 // components/button.tsx
@@ -280,6 +286,8 @@ export function Button({
   return (
     <Pressable
       accessibilityRole="button"
+      accessibilityLabel={title}
+      accessibilityState={{ disabled: !!(disabled || loading), busy: !!loading }}
       disabled={disabled || loading}
       onPress={onPress}
       style={({ pressed }) => [
@@ -341,7 +349,19 @@ After building or changing a screen, screenshot it and check it against these pr
 - **Repetition / unity** - do all corners, shadows, and accents match? If not, a value escaped the theme - move it in.
 - **Alignment** - do edges share axes? Fix with consistent screen edge padding.
 
-The pass is complete only when all four checks pass, or every failing value has moved into the theme or a component. If a screen fails the same check twice, the fix belongs in the theme or a component - not in the screen.
+Recheck the rendered result after fixing a value; moving it into the theme does not itself fix the layout. If the same defect recurs across screens, fix the shared token or component. Also run the primary-task and content checks in `expo-native-ui`'s Behavior section; screenshots alone cannot verify interaction.
+
+## Named Failures: Native Slop
+
+Use these names to recognize common mistakes when building and reviewing:
+
+- **The Web Modal** - a custom centered dialog used for composing or picking. Prefer a native sheet (`formSheet`, `@expo/ui` BottomSheet) or menu; native confirmation alerts remain appropriate for consequential actions.
+- **Everything's a Card** - every row and section in its own white rounded shadowed box. Use grouped lists; group with background and hairlines, not borders.
+- **Emoji Iconography** - 🔥 ⚙️ ✨ as tab or button icons. SF Symbols on iOS, Material icons on Android.
+- **The Purple-Gradient Hero** - a decorative gradient intro pushing the task below the fold. Lead task screens with useful content; retain a hero when it serves the requested experience.
+- **The Spinner Blink** - a full-screen spinner between every state, or "No items yet" flashing during the first load. Every screen has four states (see `expo-data-fetching`).
+
+Treat visual tells as review prompts, not blanket bans on cards, fonts, or branding. Fix the observable problem and respect the user's brief and existing design system. The full list of 20 and candidate grep checks are in `./references/native-slop.md`; use them to explain the problem and replacement when reviewing a screen.
 
 ## Auditing an Existing App
 

package/dist/global-skills/expo-design-system/references/audit.md

@@ -49,9 +49,14 @@ grep -rEn 'shadow(Color|Offset|Opacity|Radius)|elevation:' $SRC --include='*.tsx
 
 # Multiple theme entry points (there must be exactly one)
 ls src/theme.ts src/theme/index.ts theme.ts theme/index.ts constants/theme.ts 2>/dev/null
+
+# Candidate files with custom tappables but no explicit accessibility role/label (inspect each control; text or forwarded props may supply labels)
+grep -rln '<Pressable' $SRC --include='*.tsx' | xargs grep -LE 'accessibility(Role|Label)'
 ```
 
-For a Tailwind project (`expo-tailwind-setup`), also check for values that bypass `global.css` variables: arbitrary-value classes like `p-[13px]` or `text-[#5B21B6]`.
+Then run the candidate checks in `native-slop.md`. Inspect the rendered result: token checks alone cannot establish readable dark mode, spacing hierarchy, or appropriate shadows.
+
+For a Tailwind project, also check for values that bypass `global.css` variables: arbitrary-value classes like `p-[13px]` or `text-[#5B21B6]`.
 
 ```bash
 grep -rEn 'className="[^"]*\[[^"]*\]' $SRC --include='*.tsx'
@@ -87,7 +92,7 @@ For each component in the shared components directory (`src/components/`, or `co
 | Pressed state | Tappable components give pressed feedback via a `Pressable` style function |
 | Disabled / loading | Handled, and disabled blocks `onPress` |
 | Style override | Accepts `style`, merged last |
-| Accessibility | `accessibilityRole` set; touch target ≥ 44pt |
+| Accessibility | Role and applicable disabled/busy/selected state exposed; label survives loading and identifies icon-only controls; touch target ≥ 44pt (48dp Android) |
 | Tokens only | No literals that duplicate a theme value |
 
 ## 4. Report format

package/dist/global-skills/expo-design-system/references/native-slop.md

@@ -0,0 +1,74 @@
+# Native Slop: Named Anti-Pattern Tells
+
+Recurring mistakes in generated React Native apps, with names, observable tells, and preferred replacements. Use these as review prompts: explain what harms the task, readability, or platform behavior. A card, font, gradient, or onboarding flow is not a defect by itself; respect the user's brief and existing design system. Interaction failures such as obscured inputs or false-empty states still need fixing.
+
+## The 20 tells
+
+| # | Name | The tell (observable) | Native instead |
+|---|---|---|---|
+| 1 | **The Web Modal** | A custom centered dialog for picking or composing that ignores keyboard space and platform dismissal | Native sheet (`presentation: 'formSheet'`, `@expo/ui` BottomSheet) or anchored menu; use native alerts for consequential confirmations |
+| 2 | **The X-Button Sheet** | A sheet closed only by an "X" in the top corner - no grab handle, no swipe-to-dismiss | Native sheet with detents; drag down to dismiss; Cancel/Done in the header where the platform puts them |
+| 3 | **Emoji Iconography** | 🔥 ⚙️ ✨ ❤️ as tab icons, buttons, or empty-state art | SF Symbols on iOS, Material icons on Android - one icon family per platform (see `expo-native-ui`) |
+| 4 | **The Purple-Gradient Hero** | A decorative gradient intro pushes useful content and the primary task below the fold | Lead task screens with useful content under a navigation title; keep a hero when it serves the requested experience |
+| 5 | **The Floating Pill Tab Bar** | A custom rounded, inset, drop-shadowed tab bar hovering above the home indicator | The platform tab bar (`NativeTabs`) with system-managed placement, materials, and behaviors |
+| 6 | **Inter Everywhere** | An arbitrary downloaded font replaces the app's typography, with missing weights or poor readability | System type (SF / Roboto) by default; preserve brand typography when requested and verify weights, readability, and scaling |
+| 7 | **Everything's a Card** | Every list row and section wrapped in its own white rounded shadowed card; cards nested inside cards | Grouped lists (`@expo/ui` List, iOS inset-grouped, Material sections); grouping via background + hairlines, not boxes |
+| 8 | **Shadowboxing** | Heavy drop shadows (opacity ≥ 0.15, radius ≥ 10) doing hierarchy's job on white-on-white surfaces | 2-3 tokened elevation levels; hierarchy from the type ramp and grouping. iOS is a low-shadow platform |
+| 9 | **Wireframe Borders** | A 1px gray `borderWidth` outlining every container - usually Tailwind's `#E5E7EB` from web muscle memory | Spacing and surface contrast; hairlines only as list separators (`StyleSheet.hairlineWidth`, semantic separator color) |
+| 10 | **alert() Confirmation** | Alerts interrupt routine undoable actions, report success, or replace field validation | Native confirmation alert for uncommon irreversible actions; undo for routine reversible ones. Field errors stay inline; success updates the UI |
+| 11 | **The Hand-Rolled Header** | `headerShown: false` plus a `<Text>` title and custom back button - losing large-title collapse, back-swipe, and scroll-to-top | Stack header options. The navigation bar is configured, never rebuilt |
+| 12 | **16-Everything** | The same 16px padding on every axis at every level; section gaps equal row gaps, so proximity carries no meaning | The spacing scale with distinct steps: row gap < group gap < section gap |
+| 13 | **The Squish Reflex** | `scale: 0.96` press feedback on *every* touchable - including full-width list rows - or `TouchableOpacity`'s washed-out flash | Rows highlight (background change); buttons scale slightly or dim; `Pressable` with per-role feedback. Never `TouchableOpacity` |
+| 14 | **The Grand Entrance** | Staggered `FadeInDown.delay(i * 100)` on every list and screen, replaying on every visit | Entrance animation only for rare/first-time moments (`expo-animation`'s frequency gate); routine screens just appear |
+| 15 | **The Onboarding Carousel** | Generic promotional slides delay the first useful screen without collecting required setup or teaching necessary concepts | Start with useful content and contextual guidance; retain onboarding that serves required setup or the user's brief |
+| 16 | **Cross-Platform Costume** | One platform wearing the other's uniform: a FAB or ripple in an iOS-idiom app; iOS back-chevrons, large titles, or iOS-styled switches on Android | Each platform gets its own HIG's idiom - or a deliberate, documented platform-neutral treatment |
+| 17 | **Safe-Area Collision** | Content under the notch/Dynamic Island or home indicator - or hand-patched with `marginTop: 50` | Headers/tab bars handle it; otherwise `contentInsetAdjustmentBehavior="automatic"` or safe-area-context insets |
+| 18 | **Dark-Mode Amnesia** | Hardcoded `#fff` / `#000` / gray hexes; the app breaks - or half-breaks - the moment the OS theme flips | Semantic colors (`Color.ios.*` / `Color.android.dynamic.*`) through the theme; brand colors as declared light/dark pairs |
+| 19 | **The Spinner Blink** | A full-screen centered `ActivityIndicator` between every state, or "No items yet" flashing while the first fetch resolves | Four-state screens (see `expo-data-fetching`): loading ≠ empty, keep stale content while revalidating, `RefreshControl`, skeletons for slow initial loads with a known layout |
+| 20 | **Keyboard Blindness** | The focused input or the submit button disappears behind the keyboard; buttons above a keyboard need two taps | `react-native-keyboard-controller` tracks the real keyboard frame (`expo-animation` keyboard recipe); `keyboardShouldPersistTaps="handled"` for forms/search, `"always"` when unhandled taps must also keep the keyboard open |
+
+For confirmation choices, follow [Apple’s alert guidance](https://developer.apple.com/design/human-interface-guidelines/alerts): uncommon irreversible actions warrant confirmation; routine undoable actions generally do not.
+
+## Grep the greppable tells
+
+Same shell-variable convention as `audit.md` (set `$SRC` and `$THEME` first, run from the repo root). These searches find candidates, not verified defects. Two hit classes:
+
+- **review-each** - legitimate uses exist; check each hit against the tell's description.
+- **advisory** - hits only suggest the tell; confirm on a screenshot.
+
+```bash
+# --- review-each ---
+# Touchable* anywhere → #13 The Squish Reflex (Pressable only)
+grep -rn 'TouchableOpacity\|TouchableHighlight\|TouchableWithoutFeedback' $SRC --include='*.tsx'
+
+# fontFamily outside the theme → #6 Inter Everywhere (may reference a valid brand token)
+grep -rn 'fontFamily:' $SRC --include='*.tsx' | grep -v "^$THEME/"
+
+# RN <Modal> for picking/composing → #1 The Web Modal
+grep -rn '<Modal' $SRC --include='*.tsx'
+
+# Alert.alert → #10 alert() Confirmation
+grep -rn 'Alert\.alert' $SRC --include='*.tsx'
+
+# Gradient blocks in screens → #4 The Purple-Gradient Hero
+grep -rn 'LinearGradient\|experimental_backgroundImage' $SRC --include='*.tsx'
+
+# Rebuilt navigation chrome → #11 The Hand-Rolled Header
+grep -rn 'headerShown:\s*false' $SRC --include='*.tsx'
+
+# Custom tab bar chrome → #5 The Floating Pill Tab Bar
+grep -rn 'tabBarStyle' $SRC --include='*.tsx'
+
+# --- advisory ---
+# Emoji as UI glyphs → #3 Emoji Iconography (content strings may contain emoji; glyph-as-icon is the tell)
+# \x{FE0F} catches text-default emoji rendered emoji-style (⚙️ ❤️), which Emoji_Presentation alone misses
+rg -n '[\p{Emoji_Presentation}\x{FE0F}]' $SRC -g '*.tsx'
+```
+
+`audit.md` §1 finds related token candidates for #18 Dark-Mode Amnesia, #12 16-Everything, and #8 Shadowboxing. Token compliance does not prove readable dark mode, useful spacing hierarchy, or restrained shadows; inspect the rendered screen too.
+
+Screenshot-only tells (no grep precise enough to trust): #2 X-Button Sheet, #7 Everything's a Card, #9 Wireframe Borders, #15 Onboarding Carousel, #16 Cross-Platform Costume, #17 Safe-Area Collision. Three more need a running app: #14 The Grand Entrance (re-enter a screen), #19 The Spinner Blink (watch the first load and a refetch), #20 Keyboard Blindness (keyboard open). Check them per `SKILL.md`'s Self-Critique Pass, #16 on both platforms.
+
+## Growing the list
+
+A new tell earns its place only after the same failure appears repeatedly across generations - one model's one-off quirk stays out until it repeats. Keep the list near 20 entries: recognition degrades with length.

package/dist/global-skills/expo-examples/SKILL.md

@@ -87,7 +87,6 @@ When the user already has an app, **add only what the example introduces; never
 
 ## Related skills
 
-- Tailwind / NativeWind styling → `expo-tailwind-setup`
 - Native UI components (@expo/ui package) → `expo-ui`
 - Styling and native-feeling screens → `expo-native-ui`
 - Navigation and routing → `expo-router`

package/dist/global-skills/expo-examples/references/catalog.md

@@ -46,7 +46,7 @@ Most are single-screen integrations; a few differ:
 - `with-react-router` — React Router (web)
 
 ## Styling & UI
-- `with-tailwindcss` — Tailwind / NativeWind (see also `expo-tailwind-setup` skill)
+- `with-tailwindcss` — Tailwind / NativeWind
 - `with-styled-components` — styled-components
 - `with-shadcn` — shadcn-style components
 - `with-moti` — Moti animations

package/dist/global-skills/expo-migrate-module/SKILL.md

@@ -11,28 +11,34 @@ Migrate the Swift side of an existing Expo module without changing its observabl
 
 ## Prerequisite
 
-The Expo Modules API 2.0 macros require `expo` `57.0.7` or newer. Before editing, check the target's installed version (`expo` in `package.json`/lockfile, or `npm ls expo`). If it is older, stop and tell the user to upgrade first; do not attempt the migration against an unsupported version. This is a floor, not a guarantee: the exact macro and core surface still varies within `57.x`, so step 2 must still verify the checked-out source.
+Use `expo` `57.0.21` or newer. Earlier `57.x` versions can compile the macros but lack many of the 2.0 features and performance optimizations, so do not target them. Before editing, check the target's installed version (`expo` in `package.json`/lockfile, or `npm ls expo`). If it is older, stop and tell the user to upgrade first.
+
+Check the example app's own `package.json` too, not only the module root. The example app is the integration surface you build and launch in step 4, so it needs the same floor.
+
+This is a floor, not a guarantee: the exact macro and core surface still varies within `57.x`, so step 2 must still verify the checked-out source.
+
+SDK 57 ships the macros as **experimental and undocumented**, with the official beta in SDK 58. The API can still change under you. Say this to the user before a large migration, and prefer incremental mixed mode over converting a module wholesale.
 
 ## References
 
 - Read `references/migration-map.md` before changing source. It contains the 1.0-to-2.0 mappings, semantic traps, and mixed-mode rules.
 - Read `references/example.md` for a full before/after walkthrough of one module through mixed mode to a complete migration. Consult it when you need to see how the per-member rules compose.
-- Read `references/compatibility.md` when the checked-out `expo-modules-core` version or branch is not known to support every requested macro. It explains how to verify the actual compile-time and runtime surface instead of guessing from an SDK number.
+- Read `references/compatibility.md` when the checked-out `expo-modules-core` version or branch is not known to support every requested macro. It explains how to verify the actual compile-time and runtime surface instead of guessing from a version number, and lists what the macros plugin gained through `0.10.0`.
 
 ## Workflow
 
 ### 1. Establish the contract
 
-Inspect repository instructions and the worktree before editing. Locate the Swift module classes, records, shared objects, native views, JS/TS bindings, tests, example app, podspec, and installed or checked-out `expo-modules-core`.
+Inspect repository instructions and the worktree before editing. Locate the Swift module classes, records, shared objects, native views, JS/TS bindings, tests, example app, podspec, `expo-module.config.json`, and installed or checked-out `expo-modules-core`.
 
 Inventory every exported item before rewriting it:
 
 - module and shared-object JS names
-- function names, arity, labels, defaults, nullability, sync/async behavior, errors, and queue semantics
+- function names, arity, labels, defaults, nullability, sync/async behavior, errors, and queue/thread semantics (note which `AsyncFunction` bodies do blocking or long-running work, and any `.runOnQueue(...)`)
 - property names, mutability, and constant caching behavior
 - event wire names and payload shapes
 - record field names, defaults, requiredness, and nullability
-- shared-object constructors and instance/static placement
+- shared-object constructors and instance/static placement (`Function` vs `StaticFunction`/`StaticAsyncFunction`)
 - lifecycle hooks and views
 
 Use the TypeScript declarations and JS call sites to resolve ambiguity. Do not silently "improve" requiredness, rename an event, or change sync behavior during a syntax migration.
@@ -58,9 +64,11 @@ Follow these invariants:
 - Preserve every existing JS-visible name explicitly when Swift naming rules or macro defaults differ.
 - Keep original optional/default behavior. An optional 1.0 record field must not become required merely because 2.0 can express required fields.
 - Do not migrate same-JS-name overloads unless the checked-out macro groups and dispatches them.
-- Do not migrate queue-pinned DSL functions as-is; restructure onto Swift Concurrency or dispatch to the original queue via a continuation, per the async-function rules in `references/migration-map.md`.
-- Do not migrate views, unions, synchronous events, or shared-object static functions without verified support.
+- Preserve async threading behavior. A 1.0 `AsyncFunction` body ran off the JS thread; a 2.0 `async` `@JS` member starts on it and leaves only at the first `await`. A body that never awaits therefore blocks the JS thread, with no change to the JS signature. Audit what runs before the first `await`, and never leave blocking I/O on the JS actor. Fix with `@JS(.concurrent)`, or restructure onto Swift Concurrency or a continuation. Queue-pinned functions get the same treatment. See the threading section in `references/migration-map.md`.
+- Verify core support before migrating views, unions, synchronous events, shared-object static members, or free-form `Any` arguments. The macros plugin has shipped ahead of core on every one of these, so check the checked-out core rather than a plugin version, and leave unsupported members on the 1.0 DSL. `references/compatibility.md` has the per-capability checks.
+- Keep `expo-module.config.json` listing every module class under `apple.modules`. The entries are bare Swift class names, so renaming a class during migration detaches the module silently: it builds, then is absent at runtime. A migrated class must also stay `public` or `open`. SDK 58's auto-discovery is what retires these entries.
 - Do not change Kotlin, JS wrappers, or public `.d.ts` files unless the user requested an API change.
+- Never write macro-generated symbols into the module's source. The macro emits them; hand-writing or overriding them is not part of a migration.
 
 After each group, search for old DSL entries and call sites that should have moved. Avoid broad formatting or unrelated cleanup.
 
@@ -90,13 +98,16 @@ Run the narrowest available checks first, then the real integration surface:
 1. Build or type-check the Apple module against the target `expo-modules-core`.
 2. Run native unit tests and JS/TS tests.
 3. Build and launch the example app when the repository provides one.
-4. Compare the final exported surface with the inventory from step 1.
-5. Search for stale `Name`, migrated `Function`/`Property`/`Constant`/`Events` entries, old `sendEvent` calls, `@Field`, and duplicate registrations.
+4. Confirm `expo-module.config.json` still names every module class under `apple.modules`, matching the Swift class names as they now stand. A stale entry builds clean and fails only at runtime, so the example app must actually resolve the module, not merely compile.
+5. Compare the final exported surface with the inventory from step 1.
+6. Search for stale `Name`, migrated `Function`/`AsyncFunction`/`StaticFunction`/`StaticAsyncFunction`/`Property`/`Constant`/`Events` entries, old `sendEvent` calls, `@Field`, and duplicate registrations. Search the source you wrote, not macro expansion output.
 
-Expansion tests alone are insufficient: generated macro code can look correct while failing against mismatched core symbols. If dependencies changed or macro plugin flags are missing, reinstall JS dependencies as appropriate, run the repository's CocoaPods installation workflow, and restart Xcode before diagnosing plugin communication failures.
+Expansion tests alone are insufficient: generated macro code can look correct while failing to link or run against a mismatched core. If dependencies changed or macro plugin flags are missing, reinstall JS dependencies as appropriate, run the repository's CocoaPods installation workflow, and restart Xcode before diagnosing plugin communication failures.
 
 ## Handoff
 
+Never print macro-generated or core-internal symbol names to the user. `references/compatibility.md` cites them so you can grep for them, but they are implementation details that change between plugin revisions, and they are noise in a report. Name a capability by its macro (`@JS static`, `@Event(sync:)`) and by observable JS behavior. Say "the installed core does not support decoding free-form dictionary arguments yet", not the name of the missing method. The exception is a tracking issue on `expo/expo`, where the specific missing hook is the point.
+
 Report:
 
 - which members moved to 2.0

package/dist/global-skills/expo-migrate-module/references/compatibility.md

@@ -16,49 +16,106 @@ Inspect the declarations that the user's source can import:
 grep -nE 'public macro (ExpoModule|JS|Event|SharedObject|Record|Union|ViewProps|ExpoView)' <path-to-ExpoModulesMacros.swift>
 ```
 
-A declaration proves only that Swift recognizes the attribute. Also inspect the corresponding macro implementation and core runtime hooks.
+A declaration proves only that Swift recognizes the attribute, not that the code the macro generates will compile and run against the installed core.
 
 ## Check paired core support
 
-Search the actual core source for the feature being migrated:
+The macros plugin and core can drift independently, so a successful macro expansion does not prove the generated code links or is called at runtime.
+
+> The symbol names in this section are macro internals, for your own verification only. Never print them in the conversation, name them in your report, or write them into the migrated module's source. Report a capability by its macro (`@JS static`, `@Event(sync:)`) and by observable JS behavior. See the reporting rule in `SKILL.md`.
+
+**Fast pre-check.** Search core for the hooks the generated code calls, to rule out an unsupported capability before you write any Swift:
 
 ```bash
-grep -rnE '_decorateModule|_decorateSharedObject|_constructSharedObject|_jsName|EventEmitter|emitSync|StaticProperty|AnyViewProps|PropsDiff|_updateViewProps|didCreate|__expo_onStartListeningToEvent' <expo-modules-core>
+grep -rnE '_decorateModule|_decorateSharedObject|_constructSharedObject|_jsName|EventEmitter|emitSync|StaticProperty|AnyViewProps|PropsDiff|_updateViewProps|didCreate|__expo_onStartListeningToEvent|decodeAnyDictionary|decodeAnyArray|JSOptions|UnionCaseMismatch' <expo-modules-core>
 ```
 
-Use compile errors and symbol call sites to confirm signatures. The macros plugin and core can drift independently; a successful macro expansion does not prove the generated code compiles or is called at runtime.
+An absent hook is strong evidence the capability is unavailable. A present one is weaker: it proves the symbol exists, not that its signature matches what the plugin generates or that core ever calls it.
 
-## Capability gates
+**Confirm by compiling.** Write the smallest `@JS` member that uses the capability, build the module target against the checked-out core, and read the diagnostics:
 
-Treat these as independent capabilities:
+- The build succeeds: the capability is supported end to end.
+- The macro reports an error or warning: the plugin itself rejects the construct. The diagnostic names the supported alternative.
+- Expansion succeeds but linking fails on an undefined symbol: the plugin is ahead of core. Keep the member in the 1.0 DSL.
 
-| Capability | Evidence required before migration |
-| --- | --- |
-| Module functions/properties | `@ExpoModule`/`@JS`, generated `_decorateModule`, and the core call site |
-| Module name | generated `_jsName` and core registration/name lookup that reads it |
-| Records | `@Record`, coding conformance/assertions, and field decode/encode support |
-| Async events | `@Event`, `EventEmitter`, and `BaseModule`/`SharedObject` conformance |
-| Shared-object instances | `_decorateSharedObject`, construction hook, and core invocation |
-| Shared-object static functions | constructor object passed to decoration and static function routing |
-| Synchronous events | `@Event(sync:)` plus core `emitSync` overloads |
-| Task-returning functions | `JavaScriptEncodable` conformance for `Task` in core (encode-only) |
-| Views | `@ViewProps`/`@ExpoView` plus the complete typed props update and event runtime |
-| Module lifecycle methods | `AnyModule` requirements/base implementations and holder call sites |
+Then exercise the member from the example app or a test, because a binding can link and still never be invoked.
 
-If any required evidence is absent, keep that item in the 1.0 DSL.
+## Capability gates
 
-## Known migration hazards in the July 2026 plan
+Treat these as independent capabilities. Confirm each by compiling a minimal member that uses it, then calling it from JS:
+
+| Capability | Macro surface | Core hook to grep (internal) | Confirm by |
+| --- | --- | --- | --- |
+| Module functions/properties | `@ExpoModule`, `@JS` | `_decorateModule` and its call site | calling the function and reading the property from JS |
+| Module name | `@ExpoModule("Name")` | `_jsName` and the name lookup that reads it | resolving the module under its expected JS name |
+| Records | `@Record` | coding conformances and field decode/encode | round-tripping a record argument and a record return value |
+| Async events | `@Event` | `EventEmitter` on modules and shared objects | receiving an emitted event through the module's JS listener |
+| Shared-object instances | `@SharedObject`, `@JS` | `_decorateSharedObject(prototype:)`, construction hook | constructing one from JS and calling an instance member |
+| Shared-object static members | `@JS static` | `_decorateSharedObject(constructor:)`, distinct from the `prototype:` overload | calling the member on the JS class itself, not an instance |
+| Synchronous events | `@Event(sync:)` | `emitSync` overloads | observing the listener run before the emit call returns |
+| Task-returning functions | `@JS` returning `Task` | `JavaScriptEncodable` for `Task` (encode-only) | awaiting the returned promise in JS |
+| Views | `@ViewProps`, `@ExpoView` | `AnyViewProps`, `PropsDiff`, `_updateViewProps` | rendering the view and updating every prop from JS |
+| Module lifecycle methods | lifecycle members on the module class | `AnyModule` requirements and holder call sites | observing each hook fire |
+| Free-form `Any` arguments | `@JS` with `Any`, `[Any]`, `[String: Any]` | `decodeAny`, `decodeAnyArray`, `decodeAnyDictionary` | building it, then passing a JS object through |
+| Off-JS-thread async start | `@JS(.concurrent)` | `JSOptions` and the options-taking `@JS` overload (plugin `0.10.0`) | the `@JS` declaration accepting an options argument |
+| Typed N-case unions | `@Union` | `Union` macro declaration and `UnionCaseMismatch` (plugin `0.10.0`) | round-tripping each case through the JS boundary |
+| Autolinked `@ExpoModule` discovery | none, it is a build-time step | none, `scan-modules` plus the autolinking consumer | the module loading without an `expo-module.config.json` entry |
+
+If a capability cannot be confirmed, keep that item in the 1.0 DSL.
+
+## Known migration hazards
 
 Use this only as a warning list; checked-out source wins.
 
+- Async threading changed architecturally, not just syntactically: a 2.0 `async` member starts on the JS thread and leaves it at the first suspension point, where a 1.0 `AsyncFunction` never ran there. A verbatim migration can move blocking work onto the JS thread with no signature change. `@JS(.concurrent)` (plugin `0.10.0`) restores the 1.0 behavior, but needs a paired `JSOptions` type and a second `@JS` overload in core. See the threading table in `references/migration-map.md`.
 - Same-JS-name `@JS` overload grouping/dispatch was designed but not built; duplicate bindings could silently overwrite each other.
-- `@Union` was not built.
+- `@Union` landed in plugin `0.10.0`, but needs the paired `Union` macro declaration and `UnionCaseMismatch` exception in core. Decoding is first-match in case-declaration order, so preserving a 1.0 `Either`'s type order is part of the contract. See the unions section in `references/migration-map.md`.
 - Decode errors lacked the 1.0 argument-index wrapper. This affects diagnostics rather than call semantics, but tests asserting exact messages may fail.
 - `@ViewProps` had only an initial pure-macro slice; the UIKit typed props runtime and `@ExpoView` contract were still gated on core.
-- Shared-object instance functions, properties, setters, construction, and static properties were implemented; verify constructor-side routing before migrating static functions.
 - `@Event(sync: true)` macro generation existed, but core `emitSync` was still required.
 - Default asynchronous `@Event` was supported after core added `EventEmitter` to modules and shared objects.
-- `@JS` functions/properties, range-based arity, default/optional-aware calls, `@Record` field synthesis, async `@JavaScriptActor`, and instance shared-object decoration had landed in the macros work.
+- `@JS` functions/properties, range-based arity, default/optional-aware calls, `@Record` field synthesis, async `@JavaScriptActor`, and shared-object decoration had landed in the macros work.
+- Shared-object `@JS static`/`class` members bind onto the constructor object through a `constructor:`-labeled decoration hook, separate from the `prototype:` one used for instance members. The plugin has emitted this binding since `v0.7.0`, but core shipped the `prototype:` overload well ahead of it, so a static member can expand and then fail to link. Instance support does not imply static support. Keep `StaticFunction`/`StaticAsyncFunction` entries in the 1.0 `Class(...)` block until the `constructor:` overload is present.
+- Async `@JS` bindings are two-phase: arguments decode synchronously before the asynchronous boundary, and return values encode on the JS thread. A 1.0 async function whose argument decoding had side effects ordered after the hop can therefore observe a different order.
+
+## Landed in the macros plugin since 0.8.0
+
+Free-form `Any` arguments and `scan-modules` shipped in `0.9.0`, both covered below. `@JS(.concurrent)` (see the threading section in `references/migration-map.md`) and `@Union` (see the unions section) shipped in `0.10.0`.
+
+All four are macro-side only. The plugin generates the code, but each needs a paired declaration or runtime hook in `expo-modules-core`, and core has been the lagging half throughout. A plugin version number therefore tells you nothing about whether a feature is usable. Check the checked-out core, per the capability gates above.
+
+### Free-form `Any` arguments in `@JS` (plugin `0.9.0`)
+
+`Any`, `[Any]`, and `[String: Any]` are accepted as **argument** types and decode through dedicated entry points instead of the type's own `.decode`:
+
+Free-form is decode-only, so the position where the type appears decides whether it is allowed:
+
+- **argument** (function, constructor, setter): compiles, with a warning steering you to `[String: JavaScriptValue]`
+- **return type**: compile error
+- **property**: compile error, because its getter always encodes
+
+Optional (`[String: Any]?`) and nested (`[String: [String: Any]]`) spellings are unsupported.
+
+These bindings decode through `JavaScriptValue.decodeAny`, `decodeAnyArray`, and `decodeAnyDictionary`. Core shipped the macro side first, so where those methods are absent the member expands and then fails to link. Confirm by building one minimal free-form argument against the checked-out core before migrating any others.
+
+Prefer `[String: JavaScriptValue]` when you can change the Swift signature without changing the JS contract. A 1.0 DSL function taking a loosely typed dictionary is often expressible that way, and it is the alternative the macro's own warning points to.
+
+### `scan-modules` for autolinked module discovery (plugin `0.9.0`)
+
+The scanner CLI merged into the shipped `ExpoModulesMacros-tool` binary, so one executable serves both the compiler plugin protocol (no arguments) and a CLI:
+
+```bash
+ExpoModulesMacros-tool scan-modules --platform iOS --define DEBUG ios/
+```
+
+Its JSON output is versioned and reports each detected module's access level. It evaluates `#if` conditions against `--platform` and repeatable `--define`, answers `canImport` for a curated set of Apple SDK frameworks, and prunes `node_modules` along with test and example directories (`Tests`, `UITests`, `__tests__`, `__mocks__`, `example`, `examples`, `e2e`).
+
+The intent is that `expo-modules-autolinking` detects `@ExpoModule` classes automatically, replacing the `expo-module.config.json` module list. **The scanner shipped ahead of that consumer**, so until autolinking actually calls it, discovery is not active. Consequences for a migration:
+
+- Keep the module's existing `expo-module.config.json` declarations, and verify they are correct before you finish. Listing every module class under `apple.modules` is a 1.0 requirement that still applies on SDK 57; 2.0 does not lift it. The entries are bare Swift class names with no compile-time link to the class, so a rename during migration silently detaches the module: it builds, and then is absent at runtime. SDK 58 adds auto-discovery, at which point these entries can be removed.
+- A migrated `@ExpoModule` class must be `public` or `open` to be linkable from the app target. The scanner reports each class's access level so inaccessible ones can be skipped with a diagnostic.
+- Product sources kept under a pruned directory name are invisible to the scanner. A package in that layout stays on `expo-module.config.json`, which opts it out of scanning.
+- You can run `scan-modules` yourself as a migration check: it lists which classes the macro attribute is actually detected on, which catches an `@ExpoModule` that landed in a conditional block or a non-public class.
 
 ## Integration verification