---

name: cockpit description: Use only when the user explicitly asks to use Cockpit, invokes a Cockpit command or skill, or asks to install, configure, develop, debug, inspect, or verify Cockpit itself; do not activate for generic app, Flutter, UI, or E2E work.

Cockpit

Activation Boundary

Cockpit is opt-in. Activate this Skill only after an explicit user request to use Cockpit or to work on Cockpit itself. A generic request about app development, Flutter, UI, debugging, screenshots, mobile, desktop, browser, or E2E does not activate it. Before activation, do not invoke Cockpit commands, inspect sessions or targets, start or stop a daemon or app, load Cockpit MCP resources, or suggest a Cockpit workflow. Do not carry Cockpit into an unrelated later task unless the user explicitly activates it again.

cockpit dev owns Flutter discovery, processes, ports, and Supervisor state. Development handles are short lowercase base-36 values (1 through 9, then a, b, ...). Copy other generated IDs exactly; never replace them with paths. Use the globally installed cockpit executable everywhere. Live capabilities are authoritative.

Flutter Preflight

Before running any cockpit dev command in a Flutter source checkout, first confirm that its Cockpit bridge entrypoint is integrated. A normal Flutter app does not expose a Cockpit bridge by itself, so dev start rejects it during bridge-shell preflight before launching Flutter.

Cockpit accepts two layouts:

• Direct entrypoint (recommended): cockpit/main.dart and its bootstrap are ordinary Dart files in the application's existing Flutter package. Put flutter_cockpit in that package's dev_dependencies, run flutter pub get at the application root, and keep the production lib/ entrypoint unchanged. This preserves the real Android/iOS/macOS host, identifiers, entitlements, permissions, flavors, and deep links.
• Separate module: cockpit/pubspec.yaml plus cockpit/main.dart form a non-published Flutter package that depends on the real application locally. Use this only when package and native-host isolation is intentional; it has a separate Dart package name and, with platform folders, a separate native app identity that must be configured deliberately.

In either layout, the entrypoint must resolve flutter_cockpit, wrap the real application root in FlutterCockpitApp, and install the Cockpit navigator observer for every Navigator the app owns. Run flutter pub get in the package resolution root after changing dependencies. If any part is absent or does not match the app's actual public bootstrap/router API, read and complete flutter.md before cockpit dev start.

Only an already integrated checkout takes the fast path below. cockpit/main.dart is the default development entrypoint; pass another entrypoint only when the checkout intentionally uses one.

Select The Device Explicitly

Device choice is a deliberate input, not a host heuristic. Never infer a device from row order, the last Flutter target, a platform name, the host platform, or a remembered session. A connected macOS host must not win over an iOS/Android simulator or physical device. Before the first launch in a project, and whenever the target is ambiguous, discover the current devices:

cockpit target discover

This returns a bounded targets list with the exact id, name, platform, emulator, and sdk. Use the exact id in the next command. If the user did not provide a device and more than one compatible target is listed, stop and ask which exact row to use; never choose the first, last, host, or an emulator implicitly. If exactly one compatible target exists, state its id, name, and platform before using that exact id. Never silently switch between a simulator and a physical device.

The copy-ready selection flow is always:

cockpit target discover
# choose one row by its exact id; do not guess from the name alone
cockpit dev start --device <chosenId>
cockpit session show <handle>

If dev start reports deviceAmbiguous, use the listed candidates and rerun with one exact --device; if it reports deviceNotFound, reconnect or boot that same intended device and rediscover it. Do not fall through to another device or start a second app. For a fresh project with multiple active sessions, inspect cockpit session list and select the intended handle before reusing it.

cockpit target discover
cockpit dev start --device <deviceId>
cockpit session list
cockpit session show <handle>
cockpit dev status --session <handle>

For a registered black-box target, select the exact target after discovery and prove its live capabilities before any mutation:

cockpit target list
cockpit target get --target-id <targetId>
cockpit target inspect --target-id <targetId> --profile evidence

Physical-device work requires an online, unlocked, trusted device and its native control path (Android ADB; iOS WDA/devicectl where native control is needed). A connected row alone is not proof of E2E readiness: after the app is registered, target inspect --profile evidence must advertise the required tree, input, capture, lifecycle, and (for integration tests) VM capabilities. Probe with a read-only inspect, a system-first screenshot, and dev wait before running a real flow. Keep the same selected device id and session handle for Flutter launches, tests, reloads, screenshots, network reads, and recovery.

For a wired physical iOS Flutter development session, Cockpit automatically owns the Flutter SDK's iproxy forwarder for the selected device and remote bridge port. Do not start iproxy manually, guess a host port, or launch a second app. If forwarding is unavailable, repair the same Flutter SDK/device connection (for example with flutter precache --ios and devicectl), then rerun the same dev start --device <id>; Cockpit keeps the existing handle. The app still needs a valid development signature, trusted computer, Developer Mode, and an unlocked device. Wireless sessions use the device network path instead and require local-network access.

These are external iOS prerequisites, not Cockpit settings. Before reporting a launch or VM timeout, verify them once on the selected device:

• macOS must have the intended Xcode selected, first-launch components and iOS platform runtime installed. flutter doctor -v, xcode-select -p, and xcodebuild -checkFirstLaunchStatus are the read-only checks.
• A physical device must be paired and trusted, unlocked, and have Developer Mode enabled. The app's development team/signing profile must be valid; a successful Xcode build alone does not prove installation or VM reachability.
• The host app running Flutter (Terminal, IDE, or Codex) must be allowed to control Xcode in macOS System Settings > Privacy & Security > Automation. When this grant is missing, Xcode can finish building while install/launch waits and the Dart VM Service never appears. Grant only the requested Xcode automation access, then rerun the same command and device.
• For a wired device, keep the USB connection alive and use the Cockpit-owned iproxy; for a wireless device, allow the app's iOS Local Network prompt and publish the VM port with flutter drive --publish-port. Current Flutter flutter test integration_test/... cannot publish that port wirelessly, so use USB for it. Do not switch transport or device mid-run.
• ReplayKit consent is required only for native screen recording. Native WDA control additionally needs a reachable, signed WDA endpoint; neither is required for Flutter-tree-only integration actions.

Integration tests follow the same explicit selection; always pass the exact discovered id even when Flutter currently reports a single default:

flutter test integration_test/<test>.dart -d <deviceId>
flutter drive --profile --no-dds --driver=integration_test/driver.dart \
  --target=integration_test/<test>.dart -d <deviceId>

Use flutter test for ordinary integration tests and flutter drive --profile --no-dds for VM-backed performance evidence. iOS Simulator supports debug integration only; Flutter rejects iOS Simulator profile/AOT builds because profile is physical-device-only. Before a physical run, verify the exact device again; after it starts, require a live status, a current screen/anchor, and no disqualifying runtime or native-driver error. For a source-owned test, flutter_cockpit_test still uses Flutter's official runner; it does not select a device for you. If the device disappears, repair that device and rediscover it; do not fall through to another target or create a second session.

A wirelessly connected iOS device is a distinct case. Current Flutter flutter test integration_test/... cannot publish its VM service port and may fail with Cannot start app on wirelessly tethered iOS device. Use a USB connection for that command, or run the same integration target through flutter drive --publish-port (plus --profile --no-dds when profiling). On Xcode 26+ physical profile runs, add --ios-profile-debugger to use Flutter's direct LLDB path and avoid the Xcode fallback that can wait for CONFIGURATION_BUILD_DIR. Keep the chosen device unlocked, accept Xcode Automation and local-network access when required, and treat a launch that stalls before the app process is visible as blocked rather than switching devices.

Choose The Command

Choose One AI Control Surface

CLI and MCP are two transports over the same authenticated Supervisor API; they do not provide separate runtime state or extra capabilities. Install the Cockpit runtime once because it supplies both cockpit and cockpit_mcp, but choose one surface as the primary interface for a task. CLI + Skill is the default because it is portable, compact, scriptable, and does not inject a large tool catalog into every turn:

• Use the CLI with this Skill for normal development, CI, batch actions, and hosts that can execute shell commands.
• Choose MCP only when the host cannot reliably run shell commands or when typed tool/resource discovery is materially useful. Keep its profile limited to the domains needed by the task (core, flutter, or e2e) and do not shell out to the CLI for the same operation.
• A native plugin may bundle Skill + MCP; that is one logical integration. Do not add a second standalone Skill copy or MCP server on top of it.

The Skill is guidance, not a third control plane. When both surfaces are installed, one Supervisor, one selected session, and one request path remain the source of truth. Never execute the same mutation through CLI and MCP, and never load the full MCP catalog when a narrow profile or one CLI command proves the next state.

Use the highest-level command that owns the task:

| Need | Command | | --- | --- | | Install or refresh the current AI host integration | cockpit skill | | Check for a newer CLI release without changing anything | cockpit update --check | | Update the installed CLI and running Supervisor | cockpit update | | Start, inspect, control, debug, resize, capture, or reload Flutter | cockpit dev | | Validate or run reusable Flutter/black-box tests | cockpit case / cockpit suite | | Read a durable run, event stream, report, or artifact | cockpit run / cockpit artifact | | Confirm session identity, checkout, entrypoint, or reachability | cockpit session | | Discover one generic live capability | cockpit op list --kind KIND | | Learn an operation schema and its safer task command | cockpit explain KIND | | Execute an advertised operation without a task command | cockpit op run KIND |

Use dev for normal Flutter work; it resolves the required project resources. case runs one journey, suite runs a durable campaign, and op executes an advertised operation that has no task command.

Flutter Fast Path

Start