vybekiit 0.7.29 → 0.7.33

package/dist/global-skills/aws-serverless/references/orchestration.md

@@ -7,6 +7,7 @@ Step Functions and EventBridge decision matrices, error semantics, and limits. A
 - [Standard vs Express](#standard-vs-express)
 - [State machine limits and patterns](#state-machine-limits-and-patterns)
 - [Error handling](#error-handling)
+- [Which EventBridge capability](#which-eventbridge-capability)
 - [EventBridge rules, pipes, and patterns](#eventbridge-rules-pipes-and-patterns)
 - [Step Functions vs Lambda durable functions](#step-functions-vs-lambda-durable-functions)
 
@@ -90,6 +91,23 @@ Rules and best practices:
 
 ---
 
+## Which EventBridge capability
+
+Decided in `SKILL.md` Step 4; this is the full table.
+
+| Need | Use | Continue with |
+|---|---|---|
+| Time-based triggers (cron, rate, one-time), replacing VM cron or always-on workers for infrequent jobs, millions of tenant schedules, retries + maximum event age + DLQ, auditable scheduled runs | **EventBridge Scheduler** | Scheduler invokes AWS APIs directly (Lambda, Step Functions, SQS, ECS RunTask, …); surface failures with the DLQ plus CloudWatch alarms on `TargetErrorCount` and on DLQ depth |
+| AWS service state-change events on the default bus, or an existing classic single-account integration that routes events to up to 5 targets per rule by pattern matching | **EventBridge rules** on the default bus | [Event patterns](#eventbridge-rules-pipes-and-patterns) below |
+| Any new workload that publishes its own application events, including a single-account workload; many independent consumers; cross-team or cross-account sharing; central governance; ordered delivery per event group; schema integration; per-subscriber transformation; deduplication; retention and replay | **New EventBridge custom event bus** (`eventsv2`) | **amazon-eventbridge-event-bus** skill. Classic EventBridge operations still use the `events` API; migration from classic to the new bus is covered by that skill's migration reference |
+| One poll-based source (SQS, Kinesis, DynamoDB Streams, Kafka/MSK, Amazon MQ) feeding one target with optional filtering, enrichment, or transformation | **EventBridge Pipes** | [Source-to-target choices](#source-to-target-choices) below. If the only target is one Lambda function and no Pipe-only enrichment is needed, use the Event Function's native event source mapping directly |
+
+"Decouple these steps" for a single application with fan-out → new custom event bus for newly published application events, or existing classic rules when preserving an established integration. When steps must run in order with checkpointed progress, retries, or compensation, that is orchestration rather than eventing: decide Durable Functions vs Step Functions below.
+
+For an existing classic custom bus that needs retention, replay, ordering, or subscribers, plan an incremental migration through **amazon-eventbridge-event-bus**. Bridge classic and new buses so publishers and consumers can move independently; do not require a big-bang rewrite. Stay on classic for a feature the new bus does not support, such as Global Endpoints.
+
+---
+
 ## EventBridge rules, pipes, and patterns
 
 ### Event patterns
@@ -98,34 +116,42 @@ All specified fields must match (AND); values within an array are OR'd. Operator
 
 ### Best practices
 
-1. **Dedicated event bus per application domain** — default bus for AWS service events only.
+1. Use the default bus for AWS service state-change events. For a new workload publishing its own events, evaluate the new custom event bus first.
 2. **Be precise with patterns** — broad patterns risk infinite loops.
-3. **One target per rule** — simplifies debugging and IAM.
-4. **DLQs on all targets.**
-5. Use the EventBridge Sandbox to test patterns before deploying.
-6. For a **new** event-driven workload, evaluate the enhanced custom event bus first — see the **amazon-eventbridge-event-bus** skill (see SKILL.md routing). The practices above apply to the classic bus, whose rules and targets do not exist on the enhanced bus.
+3. With classic rules, prefer one target per rule to simplify debugging and IAM.
+4. Configure DLQs on deliveries that support them.
+5. Use the EventBridge Sandbox to test classic event patterns before deploying.
+6. The new custom bus uses subscribers rather than rules and targets; continue with **amazon-eventbridge-event-bus** for its payload shapes, filtering, transformations, retention, replay, ordering, migration, and delivery contract.
 
-### Pipes vs Rules
+### Source-to-target choices
 
-| Dimension | Pipes | Rules |
+| Mechanism | Topology | Choose it when |
 |---|---|---|
-| Topology | Point-to-point (1→1) | Fan-out (1→N) |
-| Flow | Source → Filter → Enrichment → Transform → Target | Event routing on a bus |
-| Sources | SQS, Kinesis, DynamoDB Streams, MSK, MQ | Any event on a bus |
-| Enrichment | Built-in (Lambda, API GW, API Destinations, Sync Express SFN) | Not built-in |
-| Use case | **Replace Lambda glue** for source→target | Event routing and distribution |
+| Native Lambda event source mapping | Poll-based source → one Lambda function | The source is SQS, Kinesis, DynamoDB Streams, Kafka/MSK, or Amazon MQ; Lambda is the only target; native batching/filtering/retry controls are sufficient |
+| EventBridge Pipes | Poll-based source → one target | Filtering, enrichment, or input transformation is needed in transit; the target is not Lambda; or a managed connector should replace glue code |
+| Pipe → new custom event bus | Poll-based source → many independent consumers | One Pipe performs source-side filtering/enrichment and publishes to the bus; each consumer owns a subscriber. Do not create one Pipe per consumer merely to simulate fan-out |
+| New custom event bus (`eventsv2`) | Application publishers → independent subscribers | The application publishes its own events and needs fan-out, retention/replay, ordering, deduplication, schemas, or independent consumer operations—even within one account |
+| Classic rules | Event on a classic/default bus → up to 5 targets per rule | Routing AWS service state-change events or preserving an existing classic EventBridge integration |
 
-Pipes filtering happens **at the source** — you pay only for matched events — with built-in retry + DLQ.
+Pipes filtering happens **at the source**—you pay only for matched events—with built-in retry and DLQ. A Pipe has one target; fan-out occurs after the Pipe through a bus and its subscribers.
 
 ---
 
 ## Step Functions vs Lambda durable functions
 
-Lambda durable functions let you write reliable multi-step workflows as **plain code** (TS/Python/Java) with automatic checkpointing — the SDK persists each step and replays from the checkpoint on interruption, enabling executions up to 1 year with zero compute during waits. **For full guidance use the aws-lambda-durable-functions skill** (see SKILL.md routing).
+The choice is made in `SKILL.md` (Step 3 — orchestration). Treat compute and orchestration as separate dimensions:
 
-| Question | Lambda durable functions | Step Functions |
-|---|---|---|
-| Programming model | Standard code (TS/Python/Java) | Amazon States Language / visual designer |
-| AWS service integrations | Primarily Lambda | 200+ native integrations |
-| Who reads the workflow | Developers | Non-technical stakeholders too |
-| Best for | Distributed transactions, stateful logic, AI agent loops | Business process automation, multi-service orchestration |
+- **Durable Functions** fits code-first orchestration written with the application, including all-Lambda workflows and replacement of hand-built checkpoint state.
+- **Step Functions** fits an explicitly visual or ASL-authored workflow, a shared cross-team state-machine contract, Distributed Map, or broad coordination of AWS services and non-Lambda compute through native integrations.
+- When the implementation model is not stated and either fits, name both with the one-line tradeoff rather than inferring that an external API/database call makes a workflow heterogeneous.
+
+| Use this skill | When the workload involves |
+|---|---|
+| **aws-step-functions** | Orchestration whose primary work is coordinating AWS services directly; coordinating ECS/Fargate, Glue, SageMaker, or Batch through native managed integrations; a visual, auditable workflow definition required for compliance or operations; a shared contract between teams that do not share a codebase; a runtime Durable Functions does not support; Distributed Map fan-out to thousands of parallel executions; authoring or editing Amazon States Language (ASL), JSONata, Retry/Catch, `.sync`/`waitForTaskToken`, TestState, or JSONPath-to-JSONata migration |
+| **aws-lambda-durable-functions** | Code-first orchestration when building on Lambda (`context.step`/`context.wait`/`context.invoke`, `withDurableExecution`); workflows written as plain sequential code in a supported runtime; waits on timers, callbacks, or conditions; checkpointed retries and execution history; replacing hand-rolled checkpointing in DynamoDB/Redis; saga and compensation logic; many fine-grained steps where Step Functions Standard transition cost may be significant |
+
+Limits that decide ties: a Durable Functions step is bounded by the Lambda timeout of the capacity provider it runs on (15 min on On-Demand and for synchronous invocations on Managed Instances; 90 min on Managed Instances for async or ESM invocations), and a durable execution can run up to 1 year on async invocations. Step Functions Standard executions run up to 1 year and Express up to 5 minutes (see [Standard vs Express](#standard-vs-express)).
+
+A Durable Function is an orchestration layer implemented by an Event Function. Few steps and a short wait may only need an idempotent handler plus a DLQ rather than either orchestrator.
+
+**For implementation guidance use the aws-lambda-durable-functions or aws-step-functions skill** — this file covers only the choice, Step Functions execution semantics, and EventBridge details above.

package/dist/global-skills/aws-serverless/references/production.md

@@ -68,7 +68,7 @@ Pre-deployment checklist, architecture trade-offs, and operational patterns. Con
 
 ### Lambdalith vs micro-Lambda
 
-Prefer **micro-Lambda** (function per route) for greenfield: per-function least-privilege IAM, independent scaling + reserved concurrency, granular observability, smaller/faster cold starts. Use a **Lambdalith** when migrating an existing Express/FastAPI app or when a small team values deployment simplicity over granularity.
+Prefer **micro-Lambda** (function per route) for greenfield: per-function least-privilege IAM, independent scaling + reserved concurrency, granular observability, smaller/faster cold starts. Use a **Lambdalith** when migrating an existing FastAPI app or when a small team values deployment simplicity over granularity. For Node.js apps, Lambda Web Functions runs the HTTP server directly without an adapter — route to the **aws-lambda-web-functions** skill; the Lambdalith adapter pattern applies to Python/FastAPI.
 
 ### Reserved vs Provisioned Concurrency
 

package/dist/global-skills/better-auth-best-practices/SKILL.md

@@ -1,6 +1,7 @@
 ---
 name: better-auth-best-practices
 description: Configure Better Auth server and client, set up database adapters, manage sessions, add plugins, and handle environment variables. Use when users mention Better Auth, betterauth, auth.ts, or need to set up TypeScript authentication with email/password, OAuth, or plugin configuration.
+disable-model-invocation: true
 ---
 
 # Better Auth Integration Guide

package/dist/global-skills/better-auth-security-best-practices/SKILL.md

@@ -1,6 +1,7 @@
 ---
 name: better-auth-security-best-practices
 description: Configure rate limiting, manage auth secrets, set up CSRF protection, define trusted origins, secure sessions and cookies, encrypt OAuth tokens, track IP addresses, and implement audit logging for Better Auth. Use when users need to secure their auth setup, prevent brute force attacks, or harden a Better Auth deployment.
+disable-model-invocation: true
 ---
 
 ## Secret Management

package/dist/global-skills/building-native-ui/SKILL.md

@@ -3,6 +3,7 @@ name: building-native-ui
 description: Complete guide for building beautiful apps with Expo Router. Covers fundamentals, styling, components, navigation, animations, patterns, and native tabs.
 version: 1.0.1
 license: MIT
+disable-model-invocation: true
 ---
 
 # Expo UI Guidelines

package/dist/global-skills/buy-domain/SKILL.md

@@ -29,13 +29,10 @@ it.
 ## Steps
 
 <!-- vybekiit:page-recipe-install -->
-0. **Install the launch checklist recipe first (catalog SSOT — Option C).**
-   Copy `apps/componentLibrary/src/pageRecipes/LaunchChecklistPage.tsx` export `LaunchChecklistPage` into the buyer app at route `/dashboard/launch`
-   (reuse if `go-live` already installed it).
-   Recipe id: `launch-checklist`. Preset: job_runs when deploy jobs are tracked.
-   Keep every `TODO:` in the recipe and wire domain checklist items after the route renders.
-   Also reference `packages/agentKit` `getPageRecipeInstall('buy-domain')` / page-recipe-manifest.json.
-   **Verify:** `/dashboard/launch` builds with practice checklist UI.
+0. **Add the launch checklist page first.** Run `vybekiit add page-recipe launch-checklist` (skip it
+   if `go-live` already added it). It adds the page at `/launch`. Keep every `TODO:` in the page and
+   fill in the domain items as you go.
+   **Verify:** `/launch` opens and shows the practice checklist.
 
 1. **Help them choose a name.** Talk through a web address they'd like. Check it's available and
    guide registration **one step at a time** — they pay for it (it's their address).

package/dist/global-skills/check-safety/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: check-safety
-description: "confirm the app is protected end-to-end before ship — abuse, database safety, and every. Use when the vibe coder says something like: am i ready to ship; is my app safe; did we cover security."
+description: "confirm the app is protected end-to-end before ship — abuse, database safety, and every API route classified correctly. Use when the vibe coder says something like: am i ready to ship; is my app safe; did we cover security."
 metadata:
   vybekiit-generated: buyer-skill-stub
 ---
@@ -23,13 +23,10 @@ API route classified correctly. Output a plain pass/fail summary for the builder
 ## Steps
 
 <!-- vybekiit:page-recipe-install -->
-0. **Install the page recipe first (catalog SSOT — Option C).**
-   Copy `apps/componentLibrary/src/pageRecipes/SafetyPage.tsx` export `SafetyPage` into the buyer app at route `/dashboard/safety`.
-   Recipe id: `safety`. Presets: none.
-   Keep every `TODO:` in the recipe and wire each one after the route renders.
-   Also reference `packages/agentKit` `getPageRecipeInstall('check-safety')` / page-recipe-manifest.json.
-   **Verify:** route builds and shows practice UI before provider wiring.
-
+0. **Add the ready-made page first.** Run `vybekiit add page-recipe safety`. It adds the page
+   at `/safety` and lists any data setup to run next. Keep every `TODO:` in the page and fill
+   each one in as you connect the real service.
+   **Verify:** `/safety` opens and shows practice content.
 
 1. **Abuse / DDoS layer.** Confirm `SECURITY_RATE_LIMIT` and `SECURITY_ORIGIN_LOCK` are `on` in
    `.env`. Confirm `middleware.ts` passes the request path for tiered limits. Confirm `/api/webhook`

package/dist/global-skills/claimable-postgres/SKILL.md

@@ -11,6 +11,7 @@ description: >-
 metadata:
   parent: neon
   source: https://github.com/neondatabase/agent-skills/tree/main/skills/claimable-postgres
+disable-model-invocation: true
 ---
 
 **FIRST**: Use the parent `neon` skill for a Neon overview, getting started with Neon, Neon development best practices, and more.

package/dist/global-skills/configure-capabilities/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: configure-capabilities
-description: "the app has **only the permissions it needs** — the builder never thinks about Info.plist, Android manifest, or Expo plugins. Use when the vibe coder says something like: camera; location permission; notifications permission."
+description: "the app has only the permissions it needs — the builder never thinks about Info.plist, Android manifest, or Expo plugins. Use when the vibe coder says something like: camera; location permission; notifications permission."
 metadata:
   vybekiit-generated: buyer-skill-stub
 ---

package/dist/global-skills/connect-account/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: connect-account
-description: "people can create accounts and sign in **inside the app**. Use when the vibe coder says something like: sign in; log in; create accounts; add users; forgot password; reset password."
+description: "people can create accounts and sign in inside the app. Use when the vibe coder says something like: sign in; log in; create accounts; add users; forgot password; reset password."
 metadata:
   vybekiit-generated: buyer-skill-stub
 ---

package/dist/global-skills/create-auth-skill/SKILL.md

@@ -1,6 +1,7 @@
 ---
 name: create-auth-skill
 description: Scaffold and implement authentication in TypeScript/JavaScript apps using Better Auth. Detect frameworks, configure database adapters, set up route handlers, add OAuth providers, and create auth UI pages. Use when users want to add login, sign-up, or authentication to a new or existing project with Better Auth.
+disable-model-invocation: true
 ---
 
 # Create Auth Skill

package/dist/global-skills/doctor/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: doctor
-description: "find out why something isn't working and fix it — without making the builder debug. Use when the vibe coder says something like: it's broken; nothing works; get an error; check my app."
+description: "find out why something isn't working and fix it — without making the builder debug anything. Use when the vibe coder says something like: it's broken; nothing works; get an error; check my app."
 metadata:
   vybekiit-generated: buyer-skill-stub
 ---

package/dist/global-skills/eas-app-stores/SKILL.md

@@ -1,8 +1,9 @@
 ---
 name: eas-app-stores
-description: EAS service (paid). Build and submit iOS and Android apps with EAS to TestFlight, the App Store, or Google Play. Supports Expo and other React Native projects, plus existing native apps. Use for eas.json setup, release pipelines, signing, app versions and build numbers, store submissions, and listing metadata. For Expo websites and API routes, use eas-hosting; for adding React Native screens to a native app, use expo-brownfield.
+description: Build and submit iOS and Android apps with EAS to TestFlight, the App Store, or Google Play. Supports Expo and other React Native projects, plus existing native apps. Use for eas.json setup, release pipelines, signing, app versions and build numbers, store submissions, and listing metadata. For Expo websites and API routes, use eas-hosting; for adding React Native screens to a native app, use expo-brownfield.
 version: 1.1.0
 license: MIT
+disable-model-invocation: true
 ---
 
 # App Store Deployment

package/dist/global-skills/eas-app-stores/agents/openai.yaml

@@ -1,4 +1,4 @@
 interface:
   display_name: "EAS App Stores"
-  short_description: "Paid EAS service. Build and submit iOS and Android apps."
+  short_description: "Build and submit iOS and Android apps."
   default_prompt: "Use $eas-app-stores to set up or verify EAS builds, TestFlight and store submissions, signing, versioning, and store metadata for iOS and Android apps: Expo and other React Native projects, plus existing native apps."

package/dist/global-skills/eas-hosting/SKILL.md

@@ -1,8 +1,9 @@
 ---
 name: eas-hosting
-description: EAS service (paid). Deploy Expo websites and Expo Router API routes to EAS Hosting - export the web bundle, run eas deploy for production and PR preview URLs, manage environment secrets and custom domains, and work within the Cloudflare Workers runtime. Also covers authoring API routes (+api.ts handlers, HTTP methods, request handling, CORS). Use when deploying an Expo web app or API routes, setting up EAS Hosting, or configuring hosting environments and domains. Not for native builds or store releases - use the eas-app-stores skill for those.
+description: Deploy Expo websites and Expo Router API routes to EAS Hosting - export the web bundle, run eas deploy for production and PR preview URLs, manage environment secrets and custom domains, and work within the Cloudflare Workers runtime. Also covers authoring API routes (+api.ts handlers, HTTP methods, request handling, CORS). Use when deploying an Expo web app or API routes, setting up EAS Hosting, or configuring hosting environments and domains. Not for native builds or store releases - use the eas-app-stores skill for those.
 version: 1.0.0
 license: MIT
+disable-model-invocation: true
 ---
 
 # EAS Hosting

package/dist/global-skills/eas-hosting/agents/openai.yaml

@@ -1,4 +1,4 @@
 interface:
   display_name: "EAS Hosting"
-  short_description: "Paid EAS service. Deploy Expo websites and Expo Router API routes to EAS Hosting, with environment secrets, custom domains, and the Cloudflare Workers runtime"
+  short_description: "Deploy Expo websites and Expo Router API routes to EAS Hosting, with environment secrets, custom domains, and the Cloudflare Workers runtime"
   default_prompt: "Use $eas-hosting to deploy an Expo web app or Expo Router API routes to EAS Hosting, author +api.ts route handlers, manage hosting environment secrets and custom domains, and work within the Cloudflare Workers runtime."

package/dist/global-skills/eas-observe/SKILL.md

@@ -1,8 +1,9 @@
 ---
 name: eas-observe
-description: EAS service (paid). Use for anything related to EAS Observe - adding `expo-observe` to an Expo project (AppMetricsRoot/ObserveRoot HOC, markInteractive and ObserveInteractiveMarker, the useObserve hook, the Expo Router / React Navigation integrations for per-route metrics, user-defined events via `Observe.logEvent`, error reporting via ObserveErrorBoundary and `Observe.reportError`, and runtime config such as sampleRate and dispatchInDebug), querying via the EAS CLI (`eas observe:metrics-summary`, `observe:metrics`, `observe:routes`, `observe:events`, `observe:session`, `observe:versions`), interpreting the resulting metrics (cold/warm launch, TTR, TTI, navigation cold/warm TTR, update download, and the TTI frameRate/device/network params for triaging slow startups), or shipping an Observe integration inside a third-party package.
+description: Use for anything related to EAS Observe - adding `expo-observe` to an Expo project (AppMetricsRoot/ObserveRoot HOC, markInteractive and ObserveInteractiveMarker, the useObserve hook, the Expo Router / React Navigation integrations for per-route metrics, user-defined events via `Observe.logEvent`, error reporting via ObserveErrorBoundary and `Observe.reportError`, and runtime config such as sampleRate and dispatchInDebug), querying via the EAS CLI (`eas observe:metrics-summary`, `observe:metrics`, `observe:routes`, `observe:events`, `observe:session`, `observe:versions`), interpreting the resulting metrics (cold/warm launch, TTR, TTI, navigation cold/warm TTR, update download, and the TTI frameRate/device/network params for triaging slow startups), or shipping an Observe integration inside a third-party package.
 version: 1.1.0
 license: MIT
+disable-model-invocation: true
 ---
 
 # EAS Observe

package/dist/global-skills/eas-observe/agents/openai.yaml

@@ -1,4 +1,4 @@
 interface:
   display_name: "EAS Observe"
-  short_description: "Paid EAS service. Set up expo-observe app metrics and query launch, route, event, and version performance with the EAS CLI"
+  short_description: "Set up expo-observe app metrics and query launch, route, event, and version performance with the EAS CLI"
   default_prompt: "Use $eas-observe to add expo-observe instrumentation (AppMetricsRoot/ObserveRoot, useObserve, ObserveInteractiveMarker, the router integrations, error reporting), query metrics with eas observe:* commands, and interpret cold/warm launch, TTR, and TTI results."

package/dist/global-skills/eas-simulator/SKILL.md

@@ -1,14 +1,15 @@
 ---
 name: eas-simulator
-description: "EAS service (paid). Run and control a user's app on a remote iOS/Android simulator hosted on EAS cloud. Read before running any `eas simulator:*` commands - it has the current syntax for this experimental API. Use whenever the user needs a simulator they can't run locally - 'run my app on a cloud simulator', 'use eas simulator to run/install/screenshot my app', 'I'm on Linux/Cursor and need an iOS device', 'no sim on this box / headless CI', 'let an agent click through my app and screenshot it', 'test my dev build on a remote sim with live reload', 'stream a sim to my browser' - even when they don't say 'EAS Simulator' or 'cloud'. On a host WITHOUT a local simulator (Linux, CI, cloud sandbox) it's the default; on macOS, do NOT auto-trigger for a plain 'run on the simulator' - use it only for a cloud/remote/shareable sim, an iOS version they lack, or an agent-driven session. NOT for local sims (expo run:ios, Xcode, Android Studio), EAS Build/Update, web preview, or physical devices."
+description: "Run and control a user's app on a remote iOS/Android simulator hosted on EAS cloud. Read before running any `eas simulator:*` commands - it has the current syntax for this experimental API. Use whenever the user needs a simulator they can't run locally - 'run my app on a cloud simulator', 'use eas simulator to run/install/screenshot my app', 'I'm on Linux/Cursor and need an iOS device', 'no sim on this box / headless CI', 'let an agent click through my app and screenshot it', 'test my dev build on a remote sim with live reload', 'stream a sim to my browser' - even when they don't say 'EAS Simulator' or 'cloud'. On a host WITHOUT a local simulator (Linux, CI, cloud sandbox) it's the default; on macOS, do NOT auto-trigger for a plain 'run on the simulator' - use it only for a cloud/remote/shareable sim, an iOS version they lack, or an agent-driven session. NOT for local sims (expo run:ios, Xcode, Android Studio), EAS Build/Update, web preview, or physical devices."
 version: 1.0.0
 license: MIT
 allowed-tools: "Bash(npx *eas-cli@*), Bash(npx *agent-device@*), Bash(npx expo *), Bash(eas *), Bash(expo *), Bash(xcodebuild*), Bash(pod*), Bash(argent *), Bash(ffmpeg*)"
+disable-model-invocation: true
 ---
 
 # EAS Simulator
 
-> **EAS service - costs apply.** EAS Simulator is a hosted EAS service. Session usage is subject to your account's pricing and limits. See https://expo.dev/pricing for current terms.
+> **EAS service - costs apply.** Sessions count toward your account's pricing and limits and stop at their maximum duration. Stop a session with `eas simulator:stop` when the task is done. See https://expo.dev/pricing for current terms.
 
 EAS Simulator runs a remote iOS simulator or Android emulator on EAS infrastructure that you drive from your machine — from the CLI, from an AI agent (via `agent-device`), and from a browser preview. It's the unlock for **environments that can't run a simulator locally** (Linux boxes, cloud/background agents like Cursor Cloud), and for letting an agent *verify* a change on a real device instead of only reasoning about code.
 
@@ -24,9 +25,9 @@ The frontmatter `description` carries the trigger phrases. In short: use this to
 - **Generic simulator request:** use a suitable local simulator when available. If the host cannot run the requested simulator (for example, iOS on Linux or a cloud sandbox), use EAS Simulator after checking access. A non-macOS host may still support a local Android emulator.
 - Honor an explicit local choice; hand off to `expo run:ios` / Xcode / Android Studio as appropriate. Clarify only when the requested environment remains ambiguous and affects the task.
 
-When the user requests EAS Simulator or a cloud simulator, proceed within that request and
-any stated budget. Explain applicable usage once and carry existing authorization through
-the session. Ask before exceeding a stated budget or expanding beyond the requested work.
+When the user asks for EAS Simulator or a cloud simulator, start the session and do the
+requested work without asking again. Stop the session when the work is done. Only check in
+if the user set a limit you would go past, or if the work grows beyond what they asked for.
 
 ## Prerequisites
 
@@ -39,9 +40,9 @@ the session. Ask before exceeding a stated budget or expanding beyond the reques
 
 ## Session lifetime
 
-- `--max-duration-minutes N` is the hard automatic-stop deadline. Customize it when supported by the account; otherwise use the service's default session limit.
+- `--max-duration-minutes N` is the hard automatic-stop deadline. Any plan can set it, up to the plan limit (40 minutes on Free, 115 on paid plans). The timer starts when the session is ready.
 - `--max-idle-time-minutes N` stops a session after that many inactive minutes. Omitted means **no idle timeout**: the session runs until its maximum duration or an explicit stop.
-- **Only activity reported through `agent-device` and `argent` resets the idle timer.** Appium commands and browser-preview activity do not reset it. For Appium or a user-driven browser preview, rely on the maximum duration—not idle time—to bound the session; customize it with `--max-duration-minutes` when supported by the account.
+- **Controller activity resets the idle timer** (`agent-device`, `argent`, and Appium commands, which are recorded as session events with producer `appium`). **Browser-preview activity does not reset it.** For a user-driven browser preview, rely on the maximum duration, not idle time, to bound the session.
 
 ## Check availability first
 
@@ -78,7 +79,7 @@ npx --yes eas-cli@latest simulator:start --platform ios --type agent-device --no
 #    agent-device runs on demand via npx — nothing installed globally.
 npx --yes eas-cli@latest simulator:exec npx agent-device@latest open <app-or-url> --platform ios
 npx --yes eas-cli@latest simulator:exec npx agent-device@latest snapshot -i          # interactive UI tree → @e1, @e2 refs
-npx --yes eas-cli@latest simulator:exec npx agent-device@latest press @e2            # tap a ref (NOTE: 'press', not 'tap')
+npx --yes eas-cli@latest simulator:exec npx agent-device@latest press @e2            # tap a ref (use 'press' or 'click')
 npx --yes eas-cli@latest simulator:exec npx agent-device@latest screenshot ./shot.png
 
 # 3. Stop the session and reset the dotenv. Omit --id to target the dotenv session.
@@ -86,11 +87,11 @@ npx --yes eas-cli@latest simulator:stop
 printf '# managed by eas-cli\n' > .env.eas-simulator
 ```
 
-To **watch** it live, hand the user the `webPreviewUrl` that `start` prints. All current session types include a browser preview; `agent-device`, `appium`, and `argent` also provide automation, while `web-preview-only` provides no automation interface. **This URL is for the *user's* browser — you cannot open it for them, and it must never touch the sim:**
+To **watch** it live, hand the user the `webPreviewUrl` that `start` prints (in `--json`, `remoteConfig.webPreviewUrl`; for `web-preview-only` sessions, `remoteConfig.previewUrl`). All current session types include a browser preview, on iOS and Android; `agent-device`, `appium`, and `argent` also provide automation, while `web-preview-only` provides no automation interface. On Android, the expo.dev session page does not show the preview inline yet: **Open preview** opens it in a new tab. Android support is in development, so some iOS features may not work there. **This URL is for the *user's* browser — you cannot open it for them, and it must never touch the sim:**
 - **"Open it here" (Cursor/VS Code)** → print the URL on its own line and tell the user to open Simple Browser (`Cmd/Ctrl+Shift+P` → "Simple Browser: Show") and paste it. Then **stop**: do not shell out to a system browser or a Cursor/VS Code URL handler, and do not ask "did a tab appear?" — you can't confirm it, the handoff is done.
 - **Never `open` the `webPreviewUrl` on the sim.** It's a browser preview, not a deep link and not an `agent-device open` argument; routing it to the device renders a browser-in-a-browser (a real past failure).
 - **Headless agent** (no display) → just return the URL as the deliverable.
-- **Keeping it alive for the user to drive** → use `--max-duration-minutes N` when supported, otherwise use the service's default limit. Browser-preview activity does not reset `--max-idle-time-minutes`, so idle timeout is not a reliable lifetime bound for this case. Tell the user when the session expires, using the CLI's reported duration or expiry. Keep it running for the requested preview; stop sessions created for one-shot tasks when the task finishes.
+- **Keeping it alive for the user to drive** → use `--max-duration-minutes N` (up to the plan limit). Browser-preview activity does not reset `--max-idle-time-minutes`, so idle timeout is not a reliable lifetime bound for this case. Tell the user when the session expires, using the CLI's reported duration or expiry. Keep it running for the requested preview; stop sessions created for one-shot tasks when the task finishes.
 
 `start` also prints a job-run URL.
 
@@ -134,7 +135,7 @@ copy of the CLI surface. Keep non-obvious behavioral guidance from this skill—
 | Command | Purpose |
 |---|---|
 | `npx --yes eas-cli@latest simulator:availability [--json] [--non-interactive]` | Check access without creating a session. |
-| `npx --yes eas-cli@latest simulator:start --platform ios\|android --name "<description>" [flags]` | Create a session; boot the sim + selected interface; write `.env.eas-simulator` by default; print the preview + job-run URLs. **Always pass `--name`**. `--json` does not suppress the dotenv; use `--out-config-type env` when no file should be written. |
+| `npx --yes eas-cli@latest simulator:start --platform ios\|android --name "<description>" [flags]` | Create a session; boot the sim + selected interface; write `.env.eas-simulator` by default; print the preview + job-run URLs. **Always pass `--name`**. `--json` does not suppress the dotenv; use `--out-config-type env` when no file should be written (it prints only the controller `export` lines, without `EAS_SIMULATOR_SESSION_ID`, so pass `--id` to `get`/`stop`/`events`). |
 | `npx --yes eas-cli@latest simulator:exec <cmd> [args…]` | Load `.env.eas-simulator`, then run `<cmd>` with that env. The bridge to the controller. |
 | `npx --yes eas-cli@latest simulator:get [--id <id>] [--json] [--non-interactive]` | Session status + connection details, including the session name. **Use this to confirm readiness** (see *Operating principles*). |
 | `npx --yes eas-cli@latest simulator:list [filters] [--limit N] [--after <cursor>] [--json]` | List and paginate project sessions; filter by status, type, platform, name prefix, and tags. |
@@ -177,19 +178,25 @@ If a controller fails to download a recording, retrieve it from [EAS session art
 | `install-from-source <url> --platform ios` | Install from a URL — the VM downloads it (use for EAS artifacts) |
 | `open <appId\|deep-link> --platform ios` | Launch an app (bundle id) or follow an app **deep link** (`exp+slug://…`). A first-time deep link raises a system **"Open in '<app>'?"** dialog — expect it (don't burn a snapshot discovering it) and `press 'label="Open"'` to hand off; it can be slow, so bound it with agent-device's own `--timeout` (e.g. `press 'label="Open"' --timeout 120000`) — **not** a shell `timeout` wrapper (macOS has no `timeout` binary). (Mode C sidesteps this dialog for the Metro-connect link via "Enter URL manually" — see run-your-app.md.) **Not** for the `webPreviewUrl` — that's a browser preview for the user, never the device. |
 | `snapshot -i` | Interactive accessibility tree → `@e1`-style refs |
-| `press <ref\|selector>` | Tap (e.g. `press @e2` or `press 'label="Open"'`) — **the tap verb is `press`, not `tap`** |
+| `press <ref\|selector>` | Tap (e.g. `press @e2` or `press 'label="Open"'`). `click <target>` also works. Use `press` or `click`: `tap` is a hidden alias that older versions reject |
 | `fill <ref> "text"` | Type into a field |
-| `screenshot <path>` | Capture the screen to a local PNG (downloaded from the daemon) — requires an app to be open (`open` first) |
-| `record start` / `record stop <path>` | Record the screen to a video — use this for **motion** (animations, gestures, transitions, timing), which a single screenshot can't capture |
+| `screenshot <path>` | Capture the screen to a local PNG (downloaded from the daemon) — requires an app to be open (`open` first). On iOS the default is 1x logical points (402x874 on iPhone 17); add `--pixel-density 3` for full resolution |
+| `record start [path]` / `record stop` | Record the screen to a video at the `record start` path (`record stop` takes no path) — use this for **motion** (animations, gestures, transitions, timing), which a single screenshot can't capture |
 | `metro prepare` / `metro reload` | Point a dev client at Metro / reload (Mode C) |
 
 **Screenshots vs. video.** Default to `screenshot` for static state, but for anything that *moves* — an animation, a transition, a gesture, a timing/jank question — **record a video and inspect the frames** instead; a still can't prove motion. Both controllers record (agent-device `record start`/`stop`, argent `screen-recording-start`/`stop`). Recordings sample at ~30fps — enough to see visible jank, not to prove sub-frame 60/120Hz hitches. For **timing** specifically, argent drops static frames by default (turn `trimStatic` off) — that plus other per-controller gotchas are in [references/controllers.md](./references/controllers.md).
 
 For the full verb set and the `argent` controller alternative, see [references/controllers.md](./references/controllers.md).
 
+## When the app crashes: device logs and crash reports (iOS)
+
+When the app crashes or closes on launch, read the iOS session's crash reports and device log before guessing from screenshots. Read them from the preview API URL in `simulator:get --json`. That URL carries the session token, so never print it.
+
+**Hold the device log before you reproduce the crash.** Without the hold, the crash gets a report but an empty log tail. Commands, fields, and fallbacks are in [references/logs-and-crashes.md](./references/logs-and-crashes.md).
+
 ## Operating principles
 
-The non-obvious mental model worth internalizing. Specific error→fix lookups (hung verbs, `tap`→`press`, `--platform`, `--json`, `pod install` locale, orphaned sessions, boot variability) live in [references/troubleshooting.md](./references/troubleshooting.md).
+The non-obvious mental model worth internalizing. Specific error→fix lookups (hung verbs, `tap` rejected, `--platform`, `--json`, `pod install` locale, orphaned sessions, boot variability) live in [references/troubleshooting.md](./references/troubleshooting.md).
 
 1. **Establish ground truth, then reset — don't patch-loop.** Never assume an existing session or Metro is yours or healthy. Before driving, confirm:
    - **cwd** — you're in the intended Expo project dir (a misdirected `start`/`exec` sessions the *wrong app* + drops a stray `.env.eas-simulator`; `pwd` / check `app.json`).
@@ -217,9 +224,10 @@ printf '# managed by eas-cli\n' > .env.eas-simulator   # clear the stale session
 
 - [references/run-your-app.md](./references/run-your-app.md) — full command sequences for modes A, B, and C (read before running a mode).
 - [references/controllers.md](./references/controllers.md) — agent-device verb reference and the `argent` alternative.
+- [references/logs-and-crashes.md](./references/logs-and-crashes.md) — device logs and crash reports from an iOS session (read when the app crashes or misbehaves).
 - [references/troubleshooting.md](./references/troubleshooting.md) — concrete errors and fixes.
 
-Source of truth: Expo docs and the `eas` / `agent-device` CLIs (`npx --yes eas-cli@latest simulator:* --help`, `agent-device --help`). This skill teaches how to apply them; it doesn't replace them.
+Source of truth: Expo docs and the `eas` / `agent-device` CLIs (`npx --yes eas-cli@latest simulator:* --help`, `npx --yes eas-cli@latest simulator:exec npx agent-device@latest help [topic]`; `--help` after `simulator:exec` shows the EAS CLI help instead). This skill teaches how to apply them; it doesn't replace them.
 
 ## Submitting Feedback
 If you encounter errors, misleading or outdated information in this skill, report it so Expo can improve:

package/dist/global-skills/eas-simulator/agents/openai.yaml

@@ -1,4 +1,4 @@
 interface:
   display_name: "EAS Simulator"
-  short_description: "Paid EAS service. Run and drive your app on a remote iOS/Android simulator on EAS cloud, from the CLI or an agent, with a live browser preview"
+  short_description: "Run and drive your app on a remote iOS/Android simulator on EAS cloud, from the CLI or an agent, with a live browser preview"
   default_prompt: "Use $eas-simulator to run, install, screenshot, and drive an app on a remote EAS cloud simulator - especially when no local simulator is available (Linux, CI, cloud agents) or a shareable browser preview is needed."

package/dist/global-skills/eas-simulator/references/controllers.md

@@ -7,7 +7,7 @@
 - `argent` (Software Mansion) — a capable alternative controller; check its license for your use.
 - `web-preview-only` — browser preview with no programmatic control.
 
-All four types include a web preview. Before setting `--max-idle-time-minutes`, follow [Session lifetime](../SKILL.md#session-lifetime); activity does not reset the timer for every interface.
+All four types include a web preview. Before setting `--max-idle-time-minutes`, follow [Session lifetime](../SKILL.md#session-lifetime); browser-preview activity does not reset the timer.
 
 ## Appium
 
@@ -19,7 +19,7 @@ npx --yes eas-cli@latest simulator:start --platform ios --type appium --non-inte
 npx --yes eas-cli@latest simulator:exec <appium-client> [args...]
 ```
 
-Use the maximum duration as the lifetime bound; Appium commands do not reset the idle timer.
+The start flags `--build-id`, `--build-fingerprint`, `--application-archive-url`, or `--expo-go` (with `--launch-arg` and `--open-url`) install and launch the app in an Appium session too. Appium commands are recorded as session events with producer `appium`: they appear in `simulator:events` and reset the idle timer.
 
 ## agent-device verbs (run via `npx --yes eas-cli@latest simulator:exec npx agent-device@latest <verb>`)
 
@@ -28,16 +28,20 @@ agent-device is a thin **client** talking to a **daemon** (the daemon runs on th
 The CLI help is written for agents and is the source of truth — run these for the full verb set and agentic loop guidance:
 
 ```bash
-npx --yes eas-cli@latest simulator:exec npx agent-device@latest --help
+npx --yes eas-cli@latest simulator:exec npx agent-device@latest help
 npx --yes eas-cli@latest simulator:exec npx agent-device@latest help workflow
 ```
 
+Use `help [topic]`, not `--help`: oclif catches `--help` after `simulator:exec` and prints the EAS CLI help.
+
 EAS-specific notes:
 
-- **`press`, not `tap`.** The tap verb is `press` — `tap` is not a verb.
+- **Tap with `press` or `click`.** `tap` is a hidden alias of `press` (not in `help commands`), and older agent-device versions reject it.
 - **`snapshot -i` is slow on iOS** — tens of seconds is normal; wait for it.
 - **`install` uploads** a local binary to the daemon; **`install-from-source`** has the VM download from a URL (use for EAS artifacts — avoids a large upload).
-- **Exercised against a live session:** `apps`, `install`, `install-from-source`, `open`, `snapshot -i`, `press`, `fill`, `screenshot`, `scroll`, `gesture` (needs a preset, e.g. `gesture swipe left`), `logs`, `record` (`start`/`stop <path>`), `network`, `perf`. `metro` (`prepare`/`reload`) is the Mode C dev-client bridge. Pass `--platform ios`; run `<verb>` with no args to see its required subcommand/args.
+- **Exercised against a live session:** `apps`, `install`, `install-from-source`, `open`, `snapshot -i`, `press`, `fill`, `screenshot`, `scroll`, `gesture` (needs a preset, e.g. `gesture swipe left`), `logs`, `record` (`start [path]`/`stop`), `network`, `perf`.
+- **Recording:** `record start ./clip.mp4`, then `record stop` (no path). The file goes to the `record start` path, with a `.gesture-telemetry.json` next to it, and the clip also uploads as a session artifact. If `record stop` times out while the remote device exports, run it again; add `--platform ios` if it cannot find the recording. Separately, EAS uploads a whole-session screen recording after the session stops (iOS and Android).
+- **Remote proof:** `open` prints `Session state: /Users/expo/...` (iOS) or `/home/expo/...` (Android) on the remote device. `session state-dir` prints the local path, so it does not prove remote use. `metro` (`prepare`/`reload`) is the Mode C dev-client bridge. Pass `--platform ios`; run `<verb>` with no args to see its required subcommand/args.
 
 ## Recording download recovery
 
@@ -49,7 +53,7 @@ npx --yes eas-cli@latest simulator:get --id <session-id> --json
 curl --fail --location --max-time 600 --output ./capture.mp4 '<downloadUrl>'
 ```
 
-Use the URL returned by EAS, not a path on the simulator or a controller artifact id. If the recording has not appeared yet, poll the same session with a bounded wait for upload completion. Already-uploaded artifacts can be retrieved after the session stops using its explicit id. If a download URL expires, query the session again for a fresh one. Give the download command more than 10 minutes in the outer runner, increase `--max-time` for larger files, and verify the downloaded video before reporting success.
+Use the URL returned by EAS, not a path on the simulator or a controller artifact id. If the recording has not appeared yet, poll the same session with a bounded wait for upload completion. Already-uploaded artifacts can be retrieved after the session stops using its explicit id; they stay until the session is deleted. The `downloadUrl` is stable and needs no auth: each request redirects to a new signed URL that is valid for 1 hour, so if a download fails, request the same `downloadUrl` again. Give the download command more than 10 minutes in the outer runner, increase `--max-time` for larger files, and verify the downloaded video before reporting success.
 
 Source: EAS CLI [simulator:get](https://github.com/expo/eas-cli/blob/main/packages/eas-cli/src/commands/simulator/get.ts) exposes `artifacts[].{id,name,filename,metadata,downloadUrl}`.
 
@@ -95,7 +99,7 @@ Where argent is weaker than agent-device Mode C — so it's **capable, not as fa
 
 **Screenshot resolution and token cost.** Screenshots cost context tokens once the agent reads them, so resolution is a real tradeoff. **argent's `screenshot` has two independent levers.** `scale` sets the image resolution and defaults **low** (too coarse to judge layout), so pass a larger scale when you need to **read** the UI. `includeImageInContext:false` keeps an image **out of the agent's context entirely** (zero token cost) — use that for a baseline you'll only **diff** later, and keep *that* one at full resolution so the pixel diff stays accurate. So: scale down images you actually read; drop unread ones with `includeImageInContext`, don't just shrink them. Exact flags and the current default: argent's help.
 
-**agent-device** screenshots default to full resolution — a crisp PNG you read from disk, token-heavier for its size, so match the capture to the question. From **v0.20.6** it gains the same lever argent has and drops the old one: `screenshot --scale <0.01–1>` proportionally resizes both dimensions (`1` = full resolution), with a token-conscious default via `AGENT_DEVICE_SCREENSHOT_SCALE` (or `screenshotScale` in config) that an explicit `--scale` overrides — keep it unset or `1` for pixel-diff baselines; the former `--max-size` is removed (older calls refused with migration guidance). Verify the version with `agent-device --version`. One caveat for remote sessions: the resize runs on the daemon, so a newer client against an older EAS session daemon can have `--scale` silently ignored and get full-res back.
+**agent-device** screenshots on iOS simulators default to 1x logical points (402x874 on iPhone 17); pass `--pixel-density 3` for full resolution when you need fine detail or a pixel-diff baseline, so match the capture to the question. From **v0.20.6** it gains the same lever argent has and drops the old one: `screenshot --scale <0.01–1>` proportionally resizes both dimensions (`1` = full resolution), with a token-conscious default via `AGENT_DEVICE_SCREENSHOT_SCALE` (or `screenshotScale` in config) that an explicit `--scale` overrides — keep it unset or `1` for pixel-diff baselines; the former `--max-size` is removed (older calls refused with migration guidance). Verify the version with `agent-device --version`. One caveat for remote sessions: the resize runs on the daemon, so a newer client against an older EAS session daemon can have `--scale` silently ignored and get full-res back.
 
 **Connecting via MCP (Cursor, Claude Code, Codex, and others).** Install the CLI globally first — the package is `@swmansion/argent`, not `argent`: