novahiz 0.1.0

package/bundled-skills/expo-overview/SKILL.md

@@ -0,0 +1,115 @@
+---
+name: expo-overview
+description: "Framework (OSS). Entry point and router for every Expo or EAS task. Load this skill first — before writing code and before choosing another expo-* / eas-* skill — when the request, PRD, or spec mentions Expo, EAS, Expo Go, or an expo-* package, or the project has an `expo` dependency in `package.json`. Within that gate it also covers app specs and designs to implement (tabs, stacks, maps, lists, navigation, building from a screenshot), and phrasings like 'implement a mobile app', 'make my app look native', 'add navigation', 'fetch some data', 'upgrade my SDK', 'add Expo to my existing native app', 'ship to the App Store', or 'I'm new to Expo, where do I start'. A fully specified request (SDK pinned, libraries named, layout given) still routes through here — the shared setup rules still apply. Do NOT load it when neither signal is present: a bare React Native project with no `expo` dependency is not Expo work. Detects the real goal, routes to the right expo-* / eas-* skill, and owns the shared setup rules."
+version: 1.1.0
+license: MIT
+---
+
+# `expo-overview` — router & shared rules for Expo / EAS
+
+## Start Here — read before doing anything
+
+**Do not guess the skill from project files alone.** Many Expo goals look similar from
+the filesystem but need different skills.
+
+1. **Confirm this is Expo or EAS work** — the request mentions Expo or EAS, or
+   `package.json` has an `expo` dependency. Otherwise this skill does not apply.
+   A native app using EAS for delivery qualifies without an Expo runtime.
+2. **Read the user's goal** — what outcome do they want, in plain terms?
+3. **Classify it** using the Skill Map below, translating casual phrasing to a goal.
+4. **Confirm intent** if ambiguous ("Sounds like you want to ship to the stores — that's
+   `eas-app-stores`. Right?"), then load that skill's `SKILL.md` and follow it.
+5. **Trust the leaf skill** — it has its own detection logic and steps. Don't improvise.
+
+## Skill Map (by goal)
+
+Match the goal to a category, then the skill, then load that leaf's `SKILL.md`.
+
+**Build the app**
+- `expo-project-structure` — folder layout for a **new** Expo Router project: where screens, components, and config live (never restructure an existing app to match)
+- `expo-native-ui` — screens, styling, semantic colors, native controls, SF Symbols, media, layout
+- `expo-router` — navigation: file-based routes, tabs / stacks / modals / sheets, links, headers
+- `expo-animation` — motion and gestures: Reanimated worklets, Gesture Handler, screen transitions, sheet and press feedback, haptics, and fixing animation that stutters on device
+- `expo-ui` — native UI components via `@expo/ui`: BottomSheet, Picker, Slider, Switch, Menu, Button, FieldGroup (grouped form sections), List / ListItem, and more — real SwiftUI on iOS, Jetpack Compose on Android. The universal layer needs SDK 56+ and runs in Expo Go; the drop-in replacements (`@gorhom/bottom-sheet`, `datetimepicker`, …) and platform-specific layers also exist on SDK 55.
+- `expo-design-system` — one visual source of truth: design tokens (color, spacing, typography, radius, shadow, motion), reusable component conventions, and audits for drift (hardcoded colors, spacing, fonts)
+- `expo-tailwind-setup` — Tailwind / NativeWind styling
+- `expo-data-fetching` — network requests, React Query / SWR, caching, offline, route loaders
+- `expo-dom` — run web code or reuse a web library inside native
+- `expo-web-to-native` — migrate an existing web / React app to a native iOS / Android app
+
+> **Component selection rule:** whenever you need a UI component (list rows, bottom sheets, pickers, sliders, menus, buttons, segmented controls, toggles), **consult `expo-ui` first** to check whether `@expo/ui` has a native equivalent before reaching for a React Native built-in or a community library. Native `@expo/ui` components give the best platform fit, and on SDK 56+ the universal ones run in Expo Go with no custom build. Load `expo-ui` alongside `expo-native-ui` for any app that renders lists, detail sheets, or form controls. One exception: `@expo/ui` `List` renders native grouped rows (an iOS Settings screen), **not** a virtualized list — use `FlatList` / `FlashList` for large datasets.
+
+**Ship & operate**
+- `eas-app-stores` — build and submit iOS/Android apps (Expo and other React Native projects, plus existing native apps), TestFlight, versions, and store metadata
+- `eas-hosting` — deploy the web bundle to EAS Hosting; also author Expo Router API routes (`+api.ts` handlers) and their environments / domains
+- `eas-workflows` — EAS Workflow YAML and CI/CD pipelines
+- `eas-simulator` — run and drive the app on a remote iOS / Android simulator on EAS cloud
+- `expo-dev-client` — custom development builds
+- `eas-update` — configure, publish, test, and debug compatible over-the-air updates
+- `eas-update-insights` — OTA update health: crash rate, adoption, payload size
+- `eas-observe` — startup / launch / TTI performance with EAS Observe
+
+**Extend natively**
+- `expo-module` — native modules and views (Swift / Kotlin) with the Expo Modules API
+- `expo-brownfield` — embed Expo / React Native in an existing native app
+- `expo-app-clip` — iOS App Clip target (AASA, smart app banner)
+
+**Maintain & learn**
+- `expo-upgrade` — upgrade the Expo SDK and fix dependency conflicts
+- `expo-examples` — canonical, version-matched integration examples (Stripe, Clerk, Supabase, …)
+- `expo-skill-feedback` — send feedback on an Expo skill or on Expo itself; enable / disable the anonymous usage telemetry
+
+### Translating vague asks
+
+Some everyday phrasings don't obviously map to a skill name — translate before routing:
+
+- "Make it look native" → grouped controls / settings forms = `expo-ui`; screens, styling = `expo-native-ui`; motion = `expo-animation`; navigation = `expo-router`.
+- "Make the screens consistent" / "clean up the styling" / "set up a theme or design tokens" → `expo-design-system`.
+- "It looks AI-generated" / "too generic, not native" → `expo-design-system` (named native-slop tells + audit), with `expo-native-ui` for the platform idioms.
+- "Ship it" / "get an .ipa or .apk" / "release to the stores" / "put my Swift app on TestFlight" → `eas-app-stores` (build + submit, TestFlight, versions, store metadata).
+- "I'm new / where do I start" → scaffold first (see Shared setup rules), then route by goal.
+
+## Shared setup rules
+
+Apply the rules that match the project and the requested task.
+
+- **Native app using EAS for delivery?** Route to `eas-app-stores`; its
+  `references/native-ios.md` covers SwiftUI/UIKit on iOS. Keep the existing native
+  project. Apply EAS auth/linking below; Expo scaffolding, SDK, and package-install
+  rules do not apply to this path.
+- **Starting a new Expo app?** Start one the standard way before routing to a feature skill:
+  `npx create-expo-app@latest`, laying out folders per `expo-project-structure`. Then
+  classify the user's goal and route.
+- **Detect the SDK version** before giving version-specific advice: read the `expo`
+  version in `package.json` (and `app.json` / `app.config.{js,ts}`). Many APIs and
+  defaults differ by SDK.
+- **Read the docs for that SDK, not `latest`.** Use the version-pinned URL, e.g.
+  `https://docs.expo.dev/versions/v56.0.0/sdk/ui/` on SDK 56 instead of
+  `https://docs.expo.dev/versions/latest/sdk/ui/` — the `latest` pages track the newest
+  SDK and can document APIs the project does not have yet.
+- **Moving to a newer SDK is its own task** — load `expo-upgrade` instead of bumping
+  versions by hand.
+- **Managed vs. bare/prebuild**: the presence of committed `ios/` and `android/`
+  directories means native projects exist (prebuild or bare). Config-plugin and
+  native-setup steps differ — note which one the project is in.
+- **Install packages with `npx expo install <pkg>`**, not raw `npm`/`yarn`/`pnpm add`,
+  so versions stay compatible with the project's SDK.
+- **EAS auth & linking** (only needed for build/submit/update/observe/workflows): check
+  login with `eas whoami`, log in with `eas login`. A project is linked when
+  `extra.eas.projectId` exists in the app config; create it with `eas init` if missing.
+
+## When to skip the router hop
+
+- Only when the user explicitly named a specific `expo-*` / `eas-*` skill → load that
+  skill directly.
+- A fully-specified task (SDK version pinned, file layout given, libraries named) is
+  **not** a reason to skip: the shared rules above still apply — check them, then route
+  to the matching leaf skill.
+
+## Submitting Feedback
+If you encounter errors, misleading or outdated information in this skill, report it so Expo can improve:
+```bash
+npx --yes submit-expo-feedback@latest --category skills --subject "expo-overview" "<actionable feedback>"
+```
+Only submit when you have something specific and actionable to report. Include as much relevant context as possible.
+If an AI agent repeatedly failed or the user had to take over an Expo task, load the expo-skill-feedback skill and follow its eval-candidate flow instead of reusing the command above.

package/bundled-skills/expo-overview/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "Expo Overview"
+  short_description: "Entry point and router for Expo / EAS tasks: load first when the request mentions Expo or the project has an expo dependency, classify the goal, route to the right expo-* / eas-* skill, and apply shared setup rules"
+  default_prompt: "Use $expo-overview first when a task mentions Expo, EAS, or an expo-* package, or the project has an `expo` dependency in package.json — even when the stack or SDK version is already fully specified. Classify the user's goal, route to the right expo-* / eas-* skill, and apply the shared environment and setup rules the other Expo skills rely on."

package/bundled-skills/expo-project-structure/SKILL.md

@@ -0,0 +1,114 @@
+---
+name: expo-project-structure
+description: Framework (OSS). Folder structure for a new Expo app. Use when scaffolding or laying out a new Expo project with Expo Router, or deciding where a file should live in one. For new projects only — never restructure an existing app to match.
+version: 1.0.0
+license: MIT
+---
+
+# Expo Project Structure
+
+A starting skeleton for a **new** Expo app — one with no committed folder structure yet.
+
+**Apply only to new projects.** If the app already has a layout, follow its existing conventions and leave files where they are — a default to start from, never a standard to enforce or migrate toward. When unsure whether a project is new, ask before moving anything.
+
+The whole layout, assembled from the rules below:
+
+```
+├── assets/
+├── scripts/
+├── src/
+│   ├── app/                       # Expo Router routes ONLY — every file is a route
+│   │   ├── api/                   #   server API routes, grouped here
+│   │   │   ├── user+api.ts
+│   │   │   └── settings+api.ts
+│   │   ├── _layout.tsx
+│   │   ├── _layout.web.tsx         #   platform-specific layout
+│   │   ├── index.tsx
+│   │   └── settings.tsx
+│   ├── components/                 # reusable UI: button, card, table…
+│   │   ├── table/                  #   complex component → folder + index.tsx
+│   │   │   ├── cell.tsx
+│   │   │   └── index.tsx
+│   │   ├── bar-chart.tsx
+│   │   ├── bar-chart.web.tsx        #   platform-specific variant
+│   │   └── button.tsx
+│   ├── screens/                    # screen bodies that route files render
+│   │   ├── home/
+│   │   │   ├── card.tsx            #   used only by Home — not shared
+│   │   │   └── index.tsx           #   rendered by src/app/index.tsx
+│   │   └── settings.tsx
+│   ├── server/                     # server-only helpers used by app/api
+│   │   ├── auth.ts
+│   │   └── db.ts
+│   ├── utils/                      # standalone helpers + colocated tests
+│   │   ├── format-date.ts
+│   │   └── format-date.test.ts
+│   ├── hooks/                      # reusable hooks: use-theme.ts…
+│   ├── constants.ts
+│   └── theme.ts
+├── app.json
+├── eas.json
+└── package.json
+```
+
+## `src/` and `src/app`
+
+Keep app code under `src/` to separate it from config files. Expo Router supports both `app/` and `src/app/` out of the box — to switch, move the folder and restart the bundler. The default template aliases `@/*` to `./src/*` in `tsconfig.json`.
+
+`src/app` is **routes-only**: every file there becomes a route, so nothing else belongs in it. Everything below lives in sibling folders.
+
+## components/ — reusable UI
+
+Generic, reused UI (button, card, table) with one named export each. Name files in **kebab-case** (`bar-chart.tsx`), matching the default `create-expo-app` template. When a component grows, give it its own folder with the root in `index.tsx` and **colocate** its private sub-components beside it — the import path (`@/components/table`) stays unchanged.
+
+## screens/ — screen bodies
+
+Because `app/` files must be routes, complex screen UI that isn't reused has no home there. Once a screen grows big enough to need breaking out to separate components, put it in `screens/` and let each route just render its screen:
+
+```tsx
+import { Home } from "@/screens/home";
+
+export default function HomeScreen() {
+  // route-specific concerns only — e.g. read url params here
+  return <Home />;
+}
+```
+
+**Colocate** a screen's private components inside its folder (`screens/home/components/`). A bonus: the same screen can render under multiple routes.
+
+## server/ + app/api/ — separate server code
+
+Appending `+api` to a file in `app/` makes it a server **API route**. Server code is different from frontend code — it runs in a Node-like server environment (deployed with EAS Hosting or on [third-party services](https://docs.expo.dev/router/web/api-routes/#hosting-on-third-party-services)) and can read secret env vars (`process.env.X`, not just `EXPO_PUBLIC_*`). Keep it apart:
+
+- Group all routes under `app/api/` → `/api/user`, `/api/settings`. This colocates them and avoids collisions (e.g. a `/user` screen and a `/user` route).
+- Put shared server-only helpers in `src/server/`.
+- Consider ESLint rules that fence `+api` files and `server/` off from frontend-only checks.
+
+## Platform-specific code
+
+Small differences: use `Platform.select` / `Platform.OS`. For larger ones, split into platform files instead of inline `if/else` — `bar-chart.tsx` + `bar-chart.web.tsx`, imported extension-free (`@/components/bar-chart`); Metro picks the right file per target.
+
+- Props must be identical across variants.
+- A default file (no platform extension) is always required — make it a no-op if the component is single-platform.
+- Supported extensions: `.ios`, `.android`, `.native`, `.web`.
+
+## Colocate styles and tests
+
+- **Styles:** keep the `StyleSheet.create({ ... })` object at the bottom of the component file rather than in a separate `.styles` file.
+- **Tests:** put `format-date.test.ts` next to `format-date.ts` (preferred over a separate `__tests__/` folder) so tested files are obvious at a glance.
+
+## AI and config files
+
+Agent instructions live at the repo root — `AGENTS.md` / `CLAUDE.md`, with project skills under `.claude/`. Other config and assets stay outside `src/`: `app.json` / `app.config.ts`, `eas.json`, `package.json`, `assets/`, and `scripts/`.
+
+---
+
+Based on [Expo app folder structure best practices](https://expo.dev/blog/expo-app-folder-structure-best-practices) by Kadi Kraman. For `src/` precedence and alias mechanics, see the [Expo docs](https://docs.expo.dev/router/reference/src-directory/).
+
+## Submitting Feedback
+If you encounter errors, misleading or outdated information in this skill, report it so Expo can improve:
+```bash
+npx --yes submit-expo-feedback@latest --category skills --subject "expo-project-structure" "<actionable feedback>"
+```
+Only submit when you have something specific and actionable to report. Include as much relevant context as possible.
+If an AI agent repeatedly failed or the user had to take over an Expo task, load the expo-skill-feedback skill and follow its eval-candidate flow instead of reusing the command above.

package/bundled-skills/expo-project-structure/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "Expo Project Structure"
+  short_description: "Recommended folder structure for new Expo apps"
+  default_prompt: "Use $expo-project-structure to lay out a new Expo app: the src/ layout, routes-only app/ directory, screens, components, server code separation, and platform-specific files."

package/bundled-skills/expo-router/SKILL.md

@@ -0,0 +1,240 @@
+---
+name: expo-router
+description: Framework (OSS). Navigation and routing for Expo Router. Covers file-based routes, groups and dynamic routes, folder organization, Link with previews and context menus, native Stack, page titles, modals and form sheets, NativeTabs, headers and toolbars, and header search bars.
+version: 1.0.1
+license: MIT
+---
+
+# Expo Router Navigation
+
+Navigation and routing for Expo Router apps. For screen styling, colors, controls, media, and visual effects, use the `expo-native-ui` skill; for motion and gestures, use `expo-animation`.
+
+## References
+
+Consult these resources as needed:
+
+```
+references/
+  route-structure.md     Route conventions, dynamic routes, groups, folder organization
+  tabs.md                NativeTabs, migration from JS tabs, iOS 26 features
+  toolbar-and-headers.md Stack headers and toolbar buttons, menus, search (iOS only)
+  form-sheet.md          Form sheets in expo-router: configuration, footers and background interaction.
+  search.md              Search bar with headers, useSearch hook, filtering patterns
+  zoom-transitions.md    Apple Zoom: fluid zoom transitions with Link.AppleZoom (iOS 18+)
+```
+
+## Code Style
+
+- Always use kebab-case for file names, e.g. `comment-card.tsx`
+- Always remove old route files when moving or restructuring navigation
+- Never use special characters in file names
+- Configure tsconfig.json with path aliases, and prefer aliases over relative imports for refactors.
+
+## Routes
+
+See `./references/route-structure.md` for detailed route conventions.
+
+- Routes belong in the `app` directory.
+- Never co-locate components, types, or utilities in the app directory. This is an anti-pattern.
+- Ensure the app always has a route that matches "/", it may be inside a group route.
+
+## Library Preferences
+
+- `Color` from `expo-router` for native semantic colors, not raw `PlatformColor` (type-safe, auto-adapts to light/dark). See `expo-native-ui` for the full color palette pattern.
+- In SDK 56+, never import from `@react-navigation/*` directly — use `expo-router/react-navigation` instead (covers `@react-navigation/native`, `/core`, `/elements`, `/routers`)
+
+## Behavior
+
+- Prefer `Stack.SearchBar` to add a search bar to a screen
+
+# Navigation
+
+## Link
+
+Use `<Link href="/path" />` from 'expo-router' for navigation between routes.
+
+```tsx
+import { Link } from 'expo-router';
+
+// Basic link
+<Link href="/path" />
+
+// Wrapping custom components
+<Link href="/path" asChild>
+  <Pressable>...</Pressable>
+</Link>
+```
+
+Whenever possible, include a `<Link.Preview>` to follow iOS conventions. Add context menus and previews frequently to enhance navigation.
+
+## Stack
+
+- ALWAYS use `_layout.tsx` files to define stacks
+- Use Stack from 'expo-router/stack' for native navigation stacks
+
+### Page Title
+
+Set the page title with `Stack.Title`:
+
+```tsx
+<Stack.Title>Home</Stack.Title>
+```
+
+## Context Menus
+
+Add long press context menus to Link components:
+
+```tsx
+import { Link } from "expo-router";
+
+<Link href="/settings" asChild>
+  <Link.Trigger>
+    <Pressable>
+      <Card />
+    </Pressable>
+  </Link.Trigger>
+  <Link.Menu>
+    <Link.MenuAction
+      title="Share"
+      icon="square.and.arrow.up"
+      onPress={handleSharePress}
+    />
+    <Link.MenuAction
+      title="Block"
+      icon="nosign"
+      destructive
+      onPress={handleBlockPress}
+    />
+    <Link.Menu title="More" icon="ellipsis">
+      <Link.MenuAction title="Copy" icon="doc.on.doc" onPress={() => {}} />
+      <Link.MenuAction
+        title="Delete"
+        icon="trash"
+        destructive
+        onPress={() => {}}
+      />
+    </Link.Menu>
+  </Link.Menu>
+</Link>;
+```
+
+## Link Previews
+
+Use link previews frequently to enhance navigation:
+
+```tsx
+<Link href="/settings">
+  <Link.Trigger>
+    <Pressable>
+      <Card />
+    </Pressable>
+  </Link.Trigger>
+  <Link.Preview />
+</Link>
+```
+
+Link preview can be used with context menus.
+
+## Modal
+
+Present a screen as a modal:
+
+```tsx
+<Stack.Screen name="modal" options={{ presentation: "modal" }} />
+```
+
+Prefer this to building a custom modal component.
+
+## Sheet
+
+Present a screen as a dynamic form sheet:
+
+```tsx
+<Stack.Screen
+  name="sheet"
+  options={{
+    presentation: "formSheet",
+    sheetGrabberVisible: true,
+    sheetAllowedDetents: [0.5, 1.0],
+    contentStyle: { backgroundColor: "transparent" },
+  }}
+/>
+```
+
+- Using `contentStyle: { backgroundColor: "transparent" }` makes the background liquid glass on iOS 26+.
+
+## Common route structure
+
+A standard app layout with tabs and stacks inside each tab:
+
+```
+app/
+  _layout.tsx — <NativeTabs />
+  (index,search)/
+    _layout.tsx — <Stack />
+    index.tsx — Main list
+    search.tsx — Search view
+```
+
+```tsx
+// app/_layout.tsx
+import { NativeTabs } from "expo-router/unstable-native-tabs";
+import { ThemeProvider, DarkTheme, DefaultTheme } from "expo-router/react-navigation";
+import { useColorScheme } from "react-native";
+
+export default function Layout() {
+  const colorScheme = useColorScheme();
+  return (
+    <ThemeProvider value={colorScheme === "dark" ? DarkTheme : DefaultTheme}>
+      <NativeTabs>
+        <NativeTabs.Trigger name="(index)">
+          <NativeTabs.Trigger.Icon sf="list.dash" md="list" />
+          <NativeTabs.Trigger.Label>Items</NativeTabs.Trigger.Label>
+        </NativeTabs.Trigger>
+        <NativeTabs.Trigger name="(search)" role="search" />
+      </NativeTabs>
+    </ThemeProvider>
+  );
+}
+```
+
+Create a shared group route so both tabs can push common screens:
+
+```tsx
+// app/(index,search)/_layout.tsx
+import { Stack } from "expo-router/stack";
+import { colors } from "@/theme/colors";
+
+export default function Layout({ segment }) {
+  const screen = segment.match(/\((.*)\)/)?.[1]!;
+  const titles: Record<string, string> = { index: "Items", search: "Search" };
+
+  return (
+    <Stack
+      screenOptions={{
+        headerTransparent: true,
+        headerShadowVisible: false,
+        headerLargeTitleShadowVisible: false,
+        headerLargeStyle: { backgroundColor: "transparent" },
+        headerTitleStyle: { color: colors.label },
+        headerLargeTitleEnabled: true,
+        headerBlurEffect: "none",
+        headerBackButtonDisplayMode: "minimal",
+      }}
+    >
+      <Stack.Screen name={screen} options={{ title: titles[screen] }} />
+      <Stack.Screen name="i/[id]" options={{ headerLargeTitleEnabled: false }} />
+    </Stack>
+  );
+}
+```
+
+`headerLargeTitleEnabled` is the SDK 56+ option name; older SDKs use `headerLargeTitle`, which is deprecated upstream.
+
+## Submitting Feedback
+If you encounter errors, misleading or outdated information in this skill, report it so Expo can improve:
+```bash
+npx --yes submit-expo-feedback@latest --category skills --subject "expo-router" "<actionable feedback>"
+```
+Only submit when you have something specific and actionable to report. Include as much relevant context as possible.
+If an AI agent repeatedly failed or the user had to take over an Expo task, load the expo-skill-feedback skill and follow its eval-candidate flow instead of reusing the command above.

package/bundled-skills/expo-router/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "Expo Router"
+  short_description: "Navigate and structure Expo Router apps: file-based routes, links, native stacks, modals, sheets, native tabs, headers, and search"
+  default_prompt: "Use $expo-router to structure file-based routes, wire up navigation with Link previews and context menus, configure native Stack screens, modals, form sheets, NativeTabs, headers, toolbars, and search bars."