vybekiit 0.7.4 → 0.7.7

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

@@ -0,0 +1,306 @@
+# 1.0 to 2.0 Migration Map
+
+Use this reference while editing. Preserve behavior first; macro adoption is secondary.
+
+## Module and naming
+
+Convert the module class and remove `Name(...)` only when the paired core reads the macro-synthesized name:
+
+```swift
+// 1.0
+public final class CameraModule: Module {
+  public func definition() -> ModuleDefinition {
+    Name("Camera")
+  }
+}
+
+// 2.0
+@ExpoModule("Camera")
+public final class CameraModule: Module {}
+```
+
+Always carry a custom 1.0 name into `@ExpoModule("...")`. A stale `Name(...)` can override or conflict with the 2.0 name depending on the core revision. In mixed mode, remove `Name(...)` only after verifying the installed `_jsName` contract.
+
+## Functions
+
+Move a DSL closure into a real method and use `@JS("wireName")` when the Swift method name is different:
+
+```swift
+// 1.0
+Function("sum") { (a: Double, b: Double) -> Double in
+  return a + b
+}
+
+// 2.0
+@JS("sum")
+func add(a: Double, b: Double) -> Double {
+  return a + b
+}
+```
+
+Preserve:
+
+- the JS name
+- positional arity
+- optional arguments and Swift defaults
+- thrown errors and return type
+- whether the result is synchronous or a Promise
+
+Do not migrate functions that resolve to the same JS name unless the checked-out macro has overload grouping and collision diagnostics. Older 2.0 implementations install one property per declaration, so the last overload silently wins.
+
+Reject or keep in DSL any unsupported signature such as variadics, `inout`, unresolved generics, or closure parameters without verified callback support. A `Promise` parameter is also unsupported; refactor it as described under Async functions.
+
+### Async functions
+
+A `Promise` parameter is not supported in a `@JS` signature; 2.0 drops the trailing-`Promise` argument entirely. A Promise-returning function has three shapes in 2.0. Pick by how the underlying work produces its result.
+
+**1. Standard `async` method.** The common case. Swift `async` maps to a JS Promise:
+
+```swift
+// 1.0
+AsyncFunction("load") { (url: URL) -> String in
+  return try loadSynchronously(url)
+}
+
+// 2.0
+@JS
+func load(url: URL) async throws -> String {
+  return try await loadResource(url)
+}
+```
+
+**2. Checked continuation.** When the result arrives through a delegate or completion handler that fires once, wrap it with `withCheckedThrowingContinuation` (or `withCheckedContinuation` for non-throwing callbacks, or an `AsyncStream` for repeated values). This is the usual refactor for a 1.0 `AsyncFunction` that took a trailing `Promise` instance:
+
+```swift
+// 1.0
+AsyncFunction("start") { (promise: Promise) in
+  scanner.start(
+    onSuccess: { result in promise.resolve(result) },
+    onFailure: { error in promise.reject(error) }
+  )
+}
+
+// 2.0
+@JS
+func start() async throws -> ScanResult {
+  return try await withCheckedThrowingContinuation { continuation in
+    scanner.start(
+      onSuccess: { result in continuation.resume(returning: result) },
+      onFailure: { error in continuation.resume(throwing: error) }
+    )
+  }
+}
+```
+
+Resume the continuation exactly once on every path. If the callback API cannot guarantee that, or the refactor is otherwise unsafe, keep the function on the DSL instead of forcing it.
+
+**3. Synchronous method returning a `Task`.** The `Task` encodes to a promise that settles with its result. Use it when the work is naturally a `Task`, or when a promise is needed as a value nested inside another encoded result rather than as the function's own return:
+
+```swift
+// 2.0
+@JS
+func download(url: URL) -> Task<DownloadResult, any Error> {
+  return Task {
+    try await self.downloader.download(url)
+  }
+}
+```
+
+This shape requires the `JavaScriptEncodable` conformance for `Task` in the checked-out core (encode-only; a JS promise does not decode back into a `Task`). Verify it exists before using this shape; prefer shape 1 or 2 when it is absent.
+
+Do not assume scheduling is unchanged. 2.0 async members are `@JavaScriptActor`-isolated and begin on the JS thread until their first real suspension. A 1.0 `.runOnQueue(...)` function or a workload that relied on automatic background execution must not be migrated as-is. Never move blocking I/O directly onto the JS actor.
+
+For a queue-pinned 1.0 function, prefer restructuring the work onto the Swift Concurrency model (structured concurrency, an actor, or a detached task for blocking work). When that is not feasible because the queue itself is the contract, for example a library that must be called from one serial queue, convert to an `async` method that dispatches to that queue inside a checked continuation:
+
+```swift
+// 1.0
+AsyncFunction("process") { (input: String) -> String in
+  return try self.processor.process(input)
+}
+.runOnQueue(processingQueue)
+
+// 2.0
+@JS
+func process(input: String) async throws -> String {
+  return try await withCheckedThrowingContinuation { continuation in
+    processingQueue.async {
+      do {
+        continuation.resume(returning: try self.processor.process(input))
+      } catch {
+        continuation.resume(throwing: error)
+      }
+    }
+  }
+}
+```
+
+## Properties and constants
+
+Map a getter to a getter-only `@JS var`; map a getter/setter pair to a settable stored or computed `@JS var`:
+
+```swift
+// 1.0
+Property("volume") { self.volume }
+  .set { self.volume = $0 }
+
+// 2.0
+@JS
+var volume: Double = 1
+```
+
+Access control does not define JS mutability. Verify whether the declaration is syntactically settable; a stored `var` normally produces a JS setter.
+
+Map a 1.0 `Constant` to a `@JS let`; a `let` property is a natural constant and produces a read-only JS property:
+
+```swift
+// 1.0
+Constant("apiVersion") { 3 }
+
+// 2.0
+@JS
+let apiVersion = 3
+```
+
+Evaluation timing shifts: a 1.0 `Constant` closure runs lazily, while a `let` initializes with the module instance. When the value is expensive and must stay deferred, keep private lazy storage and expose a getter-only computed property (a `var` with a `{ }` getter body and no storage of its own), not a stored `lazy var`:
+
+```swift
+private lazy var cachedInfo = computeInfo()
+
+@JS
+var info: Info {  // computed: recomputes nothing, just returns the cached value
+  return cachedInfo
+}
+```
+
+Do not expose a cached value as a settable `lazy @JS var`.
+
+## Events
+
+Replace `Events(...)` plus `sendEvent(...)` with a typed function property:
+
+```swift
+@Record
+struct ProgressEvent {
+  var percent: Double
+}
+
+// Explicit string preserves the old wire name.
+@Event("onProgress")
+var onProgress: (ProgressEvent) -> Void
+
+func report(percent: Double) {
+  onProgress(ProgressEvent(percent: percent))
+}
+```
+
+The default `@Event` wire name strips a leading `on` and decapitalizes the remainder: Swift `onProgress` emits `progress`. 1.0 modules commonly expose `onProgress`. During migration, pass the original wire name explicitly unless an intentional JS breaking change was approved.
+
+Use `() -> Void` for no-payload events. For payloads, create or reuse a `JavaScriptEncodable` type instead of preserving an untyped dictionary. Migrate `OnStartObserving` and `OnStopObserving` to the `didStartListening(event:)`/`didStopListening(event:)` lifecycle hooks (see Views and lifecycle).
+
+Default `@Event` dispatch schedules onto the JS thread and is callable from other isolation contexts. Do not use `sync: true` unless core provides the matching `emitSync` overloads.
+
+## Shared objects
+
+Move instance behavior from a `Class(...)` block onto the `SharedObject` subclass:
+
+```swift
+// 2.0
+@SharedObject
+final class Download: SharedObject {
+  @JS
+  init(url: URL) {
+    self.url = url
+  }
+
+  @JS
+  func pause() {}
+
+  @JS
+  var progress: Double { currentProgress }
+
+  // Installs on the JS class (constructor) object, not the prototype.
+  @JS
+  static let maxConcurrent = 4
+}
+
+@ExpoModule(classes: [Download.self])
+final class DownloadModule: Module {}
+```
+
+Drop the leading owner argument used by instance DSL closures; use `self` in the real instance method. Preserve constructor arity and JS member names.
+
+Migrate only when the checked-out core supplies the shared-object decoration and construction hooks. Static properties migrate as Swift `static` or `class` properties and install on the JS class (constructor) object rather than the prototype; verify constructor-side routing for static functions before migrating them, since instance support does not imply static-function support. Never create both a 1.0 `Class(...)` entry and a 2.0 registration for the same class without confirming that core intentionally merges them.
+
+Static members belong to shared objects, not modules: a module is exported to JS as an instance, so Swift `static` members on a `Module` class are not useful there. Keep module-level values as instance `@JS` members.
+
+## Records
+
+Attach `@Record`, remove field wrappers, and encode requiredness in the declaration:
+
+```swift
+@Record
+struct Options {
+  var source: URL       // required
+  var retries: Int = 3  // omittable; default applies
+  var label: String?    // omittable and nullable
+}
+```
+
+Rules:
+
+- non-optional with no default: required
+- any property with a default: omittable
+- optional type: omittable and nullable
+
+Preserve the 1.0 contract exactly. For example, migrate `@Field var source: URL? = nil` to `var source: URL?`, not to `var source: URL`, unless the user approved a breaking change.
+
+Every stored property is part of the 2.0 record surface. If the old type contains stored bookkeeping that was not a 1.0 field, move it out of the record or leave the type on 1.0; there is no field opt-out. Verify that each field supports the required `JavaScriptDecodable`/`JavaScriptEncodable` direction.
+
+Do not adopt `@Union` until that macro and its coding witnesses exist in the target.
+
+## Views and lifecycle
+
+Keep UIKit `View`, `Prop`, view `Events`, and `OnViewDidUpdateProps` DSL entries until the target includes the complete `@ViewProps`/`@ExpoView` core contract. Macro declarations or expansion tests alone do not prove the runtime update path exists.
+
+Module lifecycle is core-owned rather than macro-generated. The DSL components map to hook methods with no-op defaults:
+
+| 1.0 | 2.0 |
+| --- | --- |
+| `OnCreate` | `didCreate()` |
+| `OnDestroy` | `willDestroy()` |
+| `OnStartObserving` | `didStartListening(event:)` |
+| `OnStopObserving` | `didStopListening(event:)` |
+
+Rules:
+
+- Use the `override` keyword when the class inherits `Module`/`BaseModule`; define the hooks directly (no `override`) when the conformance comes only from `@ExpoModule`. Hooks added only in a subclass of a macro module are not called; keep them on the class that declares the conformance.
+- The listening hooks receive the event name. A module-wide 1.0 `OnStartObserving` ignores the argument; a per-event `OnStartObserving("name")` becomes a comparison on it.
+- `didCreate()` runs after the module is registered, slightly later than 1.0 `OnCreate`, which fires before registration; `willDestroy()` runs at holder teardown. Verify nothing depends on the earlier timing before migrating `OnCreate`.
+- DSL lifecycle components can remain during an incremental migration and each fires exactly once, but do not implement a DSL component and its hook for the same behavior, or the work runs twice.
+
+There is no 2.0 replacement for every lifecycle component; for example, retain app-context teardown handling when no matching hook exists.
+
+## Mixed mode
+
+`@ExpoModule` may coexist with a non-empty `definition()` when the paired core supports merging the two surfaces. Keep only unsupported entries in the DSL and avoid duplicate names across macro and DSL registrations.
+
+Before deleting `definition()`, verify that it contains no:
+
+- views or view events
+- lifecycle or app-context listeners
+- queue-pinned functions
+- shared-object static functions or other unsupported definitions
+
+## Contract checklist
+
+For every migrated member compare before and after:
+
+| Concern | Must remain stable |
+| --- | --- |
+| Module | registration name and `requireNativeModule` key |
+| Function | JS name, accepted arity, omitted/default behavior, sync/Promise result |
+| Property | JS name, read/write behavior, evaluation/caching |
+| Event | listener string, payload shape, timing |
+| Record | field names, requiredness, nullability, defaults |
+| Shared object | constructor shape, prototype vs constructor placement, identity |
+| Execution | JS actor, main actor, background queue, ordering |

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

@@ -1,6 +1,6 @@
 ---
 name: expo-module
-description: Framework (OSS). Guide for creating and writing Expo native modules and views using the Expo Modules API (Swift, Kotlin, TypeScript). Covers module definition DSL, native views, shared objects, config plugins, lifecycle hooks, autolinking, and type system. Use when building or modifying native modules for Expo.
+description: Framework (OSS). Guide for creating and writing Expo native modules and views using the Expo Modules API (Swift, Kotlin, TypeScript). Covers module definition DSL, native views, shared objects, config plugins, lifecycle hooks, autolinking, and type system. Use when building or modifying native modules for Expo. Not for migrating an existing Swift module from the definition DSL to the Expo Modules API 2.0 macros; use expo-migrate-module (from the expo-experiments plugin) for that.
 version: 1.0.0
 license: MIT
 ---
@@ -18,6 +18,8 @@ Complete reference for building native modules and views using the Expo Modules
 - Adding Android, Apple, or web support to an existing Expo module
 - Editing `expo-module.config.json`, config plugins, or lifecycle hooks
 
+To migrate an existing Swift module from the definition DSL to the Expo Modules API 2.0 macros (`@ExpoModule`, `@JS`, `@Event`), use the `expo-migrate-module` skill (from the `expo-experiments` plugin) instead.
+
 ## References
 
 Consult these resources as needed:
@@ -139,3 +141,11 @@ export function hello(name: string): string {
 ```
 
 Note: iOS uses just the class name; Android uses the fully-qualified class name (package + class). See `references/module-config.md` for all fields.
+
+## 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-module" "<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/dist/global-skills/expo-native-ui/SKILL.md

@@ -179,3 +179,11 @@ Use CSS `boxShadow` style prop. NEVER use legacy React Native shadow or elevatio
 ```
 
 'inset' shadows are supported.
+
+## 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-native-ui" "<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/dist/global-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/dist/global-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/dist/global-skills/expo-router/SKILL.md

@@ -228,3 +228,11 @@ export default function Layout({ segment }) {
   );
 }
 ```
+
+## 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/dist/global-skills/expo-skill-feedback/SKILL.md

@@ -1,54 +1,87 @@
 ---
 name: expo-skill-feedback
-description: Framework (OSS). Submit feedback on an Expo skill — or on Expo itself — or turn the bundled anonymous usage telemetry on or off (off by default / opt-in; the user saying "enable Expo skills telemetry" in conversation is the switch). Use when an Expo skill was useful, confusing, broken, missing context, or worth improving; when something fell short because of Expo (an SDK bug or confusing framework behavior) rather than the skill; or when the user wants to enable, turn on, opt in to, disable, turn off, opt out of, check the status of, or understand the anonymous usage tracking these skills can send.
+description: 'Submit feedback on an Expo skill—or Expo itself—and control bundled anonymous usage telemetry (off by default / opt-in). Submit feedback with: npx --yes submit-expo-feedback@latest "ACTIONABLE_FEEDBACK". Optionally add either or both: --category "CATEGORY" and --subject "SUBJECT". Replace the uppercase placeholders before running. Use when a skill was useful, confusing, broken, missing context, or worth improving; when Expo, Expo CLI, EAS CLI, docs, or MCP worked well or fell short; when an AI agent repeatedly failed, got stuck, or needed the user to take over an Expo task (report it as an eval candidate); or when the user explicitly asks to enable or disable telemetry (tracking), check its status, or understand what it collects.'
 ---
 
 # Expo Skill Feedback
 
-Send anonymous feedback on an Expo skill — or on Expo itself — and turn the bundled usage
-telemetry on or off. **Telemetry is off by default (opt-in)** — nothing is sent until it's
-enabled. Feedback goes to the Expo team via PostHog. Only the skill name, your rating + note,
-platform, and a hash of a random local install id are sent — never code, prompts, file paths,
-secrets, or personal data. (A separate automatic `skill_invoked` event fires when a skill runs
-*once enabled*; the switch below controls both.)
+Help Expo improve by sharing specific feedback about what worked well or what fell short. Feedback
+submission is independent of usage telemetry and does not require enabling it.
 
-## Submitting feedback
+## Submit feedback
 
-Be proactive: when a skill was wrong, confusing, outdated, or missing — or the trouble is
-with **Expo itself** — send 1-3 concrete sentences. Pass the skill you're rating to
-`--skill` (the skill being rated, not `expo-skill-feedback`):
+```bash
+npx --yes submit-expo-feedback@latest "<ACTIONABLE_FEEDBACK>"
+```
+
+Add either optional flag independently when it provides useful context:
 
 ```bash
-node "${CLAUDE_PLUGIN_ROOT}/skills/expo-skill-feedback/scripts/skill-feedback.cjs" \
-   --skill eas-app-stores --rating useful \
-   --text "TestFlight steps were clear and worked first try."
+npx --yes submit-expo-feedback@latest --category "<CATEGORY>" --subject "<SUBJECT>" "<ACTIONABLE_FEEDBACK>"
 ```
 
-- `--rating`: `useful` · `confusing` · `bug` · `idea` · `other`
-- `--about`: `skill` (default) · `expo` (the issue is Expo itself, not the skill)
-- `--dry-run` prints the payload without sending
+`--category` defaults to `unknown`, and `--subject` may be omitted when there is no specific target.
+When including them, choose the values that most precisely identify what the feedback is about:
 
-Never include secrets, source code, long prompts, or stack traces.
+| Category | Subject |
+| --- | --- |
+| `skills` | Exact skill name from its frontmatter, such as `expo-router` |
+| `docs` | Full Expo documentation URL |
+| `mcp` | Exact MCP tool name used |
+| `expo-cli` | Full Expo CLI command, such as `npx expo install` |
+| `eas-cli` | Full EAS CLI command, such as `eas build` |
+| `evals` | Expo package or command the failed task involves, else a capability phrase, such as `expo-router` or `eas build` |
+| `unknown` | Concise Expo product, package, feature, or other topic |
 
-If the command refuses because telemetry is off, don't drop the feedback — ask the user
-once (see *Turning it on or off*), and resend the same command after they enable.
+In the final argument, say what helped and why, or provide the relevant context, expected behavior,
+and what happened instead. Do not include secrets, source code, personal data, long prompts, or stack traces.
 
-## Turning it on or off
+## Eval candidates: tasks that broke the model
 
-Telemetry is anonymous and **off by default (opt-in)** — nothing (neither the automatic
-`skill_invoked` event nor feedback) is sent until the user enables it. Saying so in
-conversation is the switch: when the user says **"enable Expo skills telemetry"** — or
-answers yes when you offer — run:
+Expo turns hard real-world tasks into agent evals: anything Expo an agent can attempt — framework,
+EAS, tooling — qualifies, whether or not a skill was involved. The signal worth sending is a task an
+AI agent could not complete cleanly despite real effort: several failed attempts, a build or screen
+that never worked, or the user stepping in to fix it manually. Never submit quick slips the agent
+corrected itself, more than one candidate per session, or a task already reported.
+
+When such a failure happens — or the user says a model failed at an Expo task — show the user the exact
+submission you intend to send and get approval; the Task field must describe the Expo-technical
+shape of the task, never the user's product or business context. Without a user to approve it
+(headless or CI runs), do not submit. Then run from the failing app's directory (the CLI attaches
+the SDK and package versions, agent harness, and platform automatically) with `--category evals`,
+`--subject` naming the Expo package or command involved (a capability phrase only when no single
+package fits), and this structure in the final argument:
+
+```text
+Task: <what was asked, self-contained>.
+Expected: <observable success criteria>.
+Actual: <what the agent did instead>.
+Wrong approach: <the specific mistake, such as a wrong API, hallucinated prop, or bad pattern>.
+Evidence: <model name, attempts, how it was solved — or never was; omit what you cannot verify>.
+```
+
+A good candidate is solvable (eventually done or clearly doable), verifiable (success is
+observable), and specific. Mention only environment details the CLI cannot see, such as other key
+packages or a freshly created app. Describe code; do not paste it. If the command fails with an
+error naming `evals` as an invalid category, resend once with `--category unknown` and the same
+subject prefixed `eval-candidate: `; on any other error, do not resend.
+
+## Usage telemetry
+
+Automatic skill usage telemetry is separate from feedback and **off by default**. Never enable it
+without an explicit user request. Use the following script with `--on`, `--off`, or `--status`:
 
 ```bash
-node "${CLAUDE_PLUGIN_ROOT}/skills/expo-skill-feedback/scripts/telemetry.cjs" --on
+node "${CLAUDE_PLUGIN_ROOT}/skills/expo-skill-feedback/scripts/telemetry.cjs" --status
 ```
 
-`--off` turns it off again. When the user asks whether telemetry is on, run `--status`
-and relay its output — don't answer from memory; env vars and CI can override the saved
-state. Env equivalents: `EXPO_SKILLS_TELEMETRY=1` to enable, `=0` or `DO_NOT_TRACK=1` to
-disable; CI never sends.
+Environment equivalents are `EXPO_SKILLS_TELEMETRY=1` to enable and
+`EXPO_SKILLS_TELEMETRY=0` or `DO_NOT_TRACK=1` to disable. CI never sends telemetry.
 
-**Never enable it on your own.** If a feedback send was refused because telemetry is off,
-ask the user once — "Expo skills telemetry is off; enable it (anonymous) and send this?" —
-and run `--on` only after an explicit yes. If they decline, drop the feedback silently.
+## 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-skill-feedback" "<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/dist/global-skills/expo-skill-feedback/agents/openai.yaml

@@ -1,4 +1,4 @@
 interface:
   display_name: "Expo Skill Feedback"
-  short_description: "Send anonymous feedback on an Expo skill, or turn the opt-in usage telemetry on or off (off by default)"
-  default_prompt: "Use $expo-skill-feedback to rate an Expo skill (useful, confusing, bug, idea) with a short anonymous note, or to enable, disable, or check the status of Expo skills telemetry."
+  short_description: "Help Expo improve with feedback, eval candidates, and usage telemetry"
+  default_prompt: "Use $expo-skill-feedback to help Expo improve by submitting feedback, reporting an Expo task an AI agent failed at as an eval candidate, or controlling Expo skills telemetry."

package/dist/global-skills/expo-tailwind-setup/SKILL.md

@@ -478,3 +478,11 @@ Add className to component props:
 ```tsx
 type Props = React.ComponentProps<typeof RNView> & { className?: string };
 ```
+
+## 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-tailwind-setup" "<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/dist/global-skills/expo-ui/SKILL.md

@@ -45,3 +45,11 @@ references/
   swift-ui.md              Platform-specific iOS UI: @expo/ui/swift-ui components, modifiers, RNHostView, useNativeState
   jetpack-compose.md       Platform-specific Android UI: @expo/ui/jetpack-compose components, modifiers, LazyColumn caveat, icons, useNativeState
 ```
+
+## 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-ui" "<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.