---
name: ansight-install-dotnet-mobile
description: Use this skill when installing or configuring Ansight in a .NET mobile app, including .NET MAUI, .NET for Android, and .NET for iOS. Apply the current Ansight NuGet package surface, initialize the runtime in the correct startup path, enable pairing, ask the user which tool suites to install and whether screen-view events should be integrated, and add optional telemetry or tools without inventing platform-specific packages.
---

# Ansight .NET Mobile Install Skill

Use this skill when a user asks an AI agent to install or configure Ansight for `.NET MAUI`, `.NET for Android`, or `.NET for iOS`.

## Goal

Produce a working Ansight integration for the target `.NET` mobile app, verify the build, and explain any remaining Studio, MCP, or pairing steps.

## Supported Targets

The current `.NET` SDK supports these mobile targets through the same package surface:

- `net9.0-android`
- `net9.0-ios`
- `.NET MAUI` apps targeting Android or iOS

Use the same base package and runtime APIs across all three app shapes:

- base package: `Ansight`
- optional tool packages:
  - `Ansight.Tools.VisualTree`
  - `Ansight.Tools.Reflection`
  - `Ansight.Tools.Database`
  - `Ansight.Tools.FileSystem`
  - `Ansight.Tools.Preferences`
  - `Ansight.Tools.SecureStorage`

When dependency names are in question, verify against the official published package profile: `https://www.nuget.org/profiles/ansight-ai`.

## Inputs To Confirm

- target app shape: `.NET MAUI`, `.NET for Android`, or `.NET for iOS`
- whether the user wants only the base runtime or additional tool suites
- whether remote tooling should be enabled for local inspection builds
- whether developer pairing, QR pairing, or both should be enabled
- whether screen views, lifecycle events, log forwarding, or JPEG session capture should be added

## Required Constraints

- keep Ansight scoped to local-development workflows unless the user explicitly asks otherwise
- do not invent separate Android-only or iOS-only Ansight package ids; use the published `.NET` package surface
- preserve the app's existing startup, logging, and navigation patterns
- install tool packages only in development builds and gate them with the documented MSBuild flag
- if the user did not explicitly request tool suites or screen-view integration, ask before adding them
- highlight only the minimal Android manifest permissions and iOS `Info.plist` requirements introduced by pairing, and treat QR scanning as app-specific
- do not enable remote tools by default
- prefer least-privilege tool guards and narrow allow-lists

## Workflow

1. Inspect the project file and determine the app shape:
   - `.NET MAUI`: look for `UseMaui`, `MauiProgram.cs`, and `Platforms/`
   - `.NET for Android`: look for `TargetFramework` `net9.0-android` and an application entry such as `MainApplication`
   - `.NET for iOS`: look for `TargetFramework` `net9.0-ios` and an `AppDelegate`
2. Confirm the published package surface from the official Ansight NuGet profile.
3. Before making optional changes, confirm the user's intent with short direct questions when it is not already explicit:
   - which Ansight tool suites should be installed
   - whether `Runtime.ScreenViewed(...)` events should be integrated
4. Do not install optional tool packages or add screen-view hooks until the user answers, unless they already specified those choices clearly.
5. Add the base `Ansight` package.
6. If remote tools are requested, add only the requested tool packages in Debug-only build conditions and enable `AnsightAllowRemoteTools=true` in the matching Debug-only property group.
7. Initialize Ansight with `Options.CreateBuilder()` and `Runtime.InitializeAndActivate(options)` from the app's startup path.
8. Enable host pairing with `.WithHostPairing()`.
9. If tool packages were installed, register each suite explicitly in the options builder and choose the narrowest tool guard that supports the requested workflow.
10. Wire platform-specific app shape details:
   - `.NET MAUI`: prefer an app-owned bootstrap called from `MauiProgram.CreateMauiApp()`, with platform lifecycle hooks left in `Platforms/Android/MainApplication.cs` and `Platforms/iOS/AppDelegate.cs`
   - `.NET for Android`: initialize from `MainApplication.OnCreate()` or a bootstrap it calls
   - `.NET for iOS`: initialize from the app startup path and keep lifecycle callbacks in `AppDelegate`
11. Inspect and update platform metadata requirements when the integration needs local network access or app-specific QR pairing:
   - Android manifest permissions
   - iOS `Info.plist` local-network key, plus camera only when QR pairing is included
12. If bundled pairing profiles are used, embed `ansight.json` and `ansight.developer-pairing.json` with the exact logical names, and set `HostPairingOptions.BundledProfileAssembly` to the assembly that contains them.
13. Add optional features only when requested:
   - FPS and memory telemetry
   - screen-view events
   - app lifecycle tracking
   - runtime log forwarding
   - JPEG session capture
   - tool suites
14. If the user also wants agent-driven workflows, remind them to install Ansight Studio and point their MCP client at `http://127.0.0.1:45125/mcp/`.
15. Build the project or solution and report any remaining manual steps in Studio.

## User Prompting Rule

When the user's request is missing optional integration choices, ask before editing.

Ask these two questions in plain language:

1. Which Ansight tool suites do you want installed, if any?
2. Should I integrate `Runtime.ScreenViewed(...)` events into your navigation or page presentation flow?

If the user declines, keep the integration to the base runtime, pairing, and any other explicitly requested features.

## Minimal Runtime Shape

```csharp
using Ansight;

var options = Options.CreateBuilder()
    .WithFramesPerSecond()
    .WithHostPairing()
    .Build();

Runtime.InitializeAndActivate(options);
```

## Pairing Guidance

Use the same pairing surface across `.NET MAUI`, `.NET for Android`, and `.NET for iOS`:

- bundled developer pairing through embedded `ansight.json`
- QR pairing through `Runtime.HostPairing.ConnectFromPayloadAsync(...)`
- stored-profile reconnects through `Runtime.HostPairing.AutoConnectAsync()`

For developer pairing resources:

```xml
<PropertyGroup>
  <AnsightDeveloperPairingEnabled>true</AnsightDeveloperPairingEnabled>
  <AnsightDeveloperPairingSourceFile>ansight.json</AnsightDeveloperPairingSourceFile>
  <AnsightDeveloperPairingOutputFile>$(BaseIntermediateOutputPath)ansight.developer-pairing.json</AnsightDeveloperPairingOutputFile>
</PropertyGroup>

<ItemGroup>
  <EmbeddedResource Include="ansight.json" LogicalName="ansight.json" />
  <EmbeddedResource Include="$(BaseIntermediateOutputPath)ansight.developer-pairing.json"
                    LogicalName="ansight.developer-pairing.json"
                    Condition="'$(AnsightDeveloperPairingEnabled)' == 'true' and Exists('$(BaseIntermediateOutputPath)ansight.developer-pairing.json')" />
</ItemGroup>
```

## Platform Permissions And Plist Requirements

Call these out explicitly whenever the integration adds pairing. Keep the defaults minimal. Treat QR scanning as app-specific.

### Android

For `.NET MAUI` use `Platforms/Android/AndroidManifest.xml`. For `.NET for Android`, use the equivalent manifest in the Android project.

Baseline requirements:

```xml
<uses-permission android:name="android.permission.INTERNET" />
<uses-permission android:name="android.permission.ACCESS_NETWORK_STATE" />
```

Guidance:

- `INTERNET` is required for the local host connection
- `ACCESS_NETWORK_STATE` supports network-state inspection and connectivity checks
- do not add `ACCESS_WIFI_STATE`, `CHANGE_WIFI_MULTICAST_STATE`, or other broader network permissions unless the specific app integration actually needs them
- do not add `android:usesCleartextTraffic="true"` by default
- `CAMERA` is required only when QR pairing is explicitly included
- if QR pairing is added, request camera permission at runtime before scanning

### iOS

For `.NET MAUI` use `Platforms/iOS/Info.plist`. For `.NET for iOS`, use the app's `Info.plist`.

Baseline requirement:

```xml
<key>NSLocalNetworkUsageDescription</key>
<string>Ansight client needs local network access to discover and connect to the host test harness.</string>
```

Guidance:

- `NSLocalNetworkUsageDescription` is required when the app needs local network access for pairing or host discovery
- do not add camera or ATS keys by default
- `NSCameraUsageDescription` is required only when QR pairing is explicitly included
- when QR pairing is not included, do not add camera usage text unnecessarily

In the final response, list any manifest or `Info.plist` edits alongside the runtime and package changes so the user sees the full platform impact.

## Build-Time Tooling Opt-In

Treat remote tooling as development-only.

If concrete tool packages are present and `AnsightAllowRemoteTools` is not enabled, the build fails on purpose.

Recommended pattern:

```xml
<ItemGroup Condition="'$(Configuration)' == 'Debug'">
  <PackageReference Include="Ansight" Version="*" />
  <PackageReference Include="Ansight.Tools.VisualTree" Version="*" />
  <PackageReference Include="Ansight.Tools.Database" Version="*" />
</ItemGroup>

<PropertyGroup Condition="'$(Configuration)' == 'Debug'">
  <AnsightAllowRemoteTools>true</AnsightAllowRemoteTools>
  <AnsightDeveloperPairingEnabled>true</AnsightDeveloperPairingEnabled>
</PropertyGroup>
```

Rules:

- keep `AnsightAllowRemoteTools=true` scoped to Debug-only conditions
- omit tool packages entirely from Release or distribution builds
- leave `AnsightAllowRemoteTools` unset or `false` outside development builds
- package installation alone is not enough; runtime registration is still required

## Runtime Tool Registration

Register each suite explicitly in the options builder.

```csharp
using Ansight;
using Ansight.Tools.Database;
using Ansight.Tools.FileSystem;
using Ansight.Tools.VisualTree;

var options = Options.CreateBuilder()
    .WithHostPairing()
    .WithVisualTreeTools()
    .WithDatabaseTools()
    .WithFileSystemTools(fileSystem =>
    {
        fileSystem.AddRoot("logs", "/absolute/path/to/logs");
    })
    .WithReadOnlyToolAccess()
    .Build();

Runtime.InitializeAndActivate(options);
```

Registered tools stay unusable until the guard allows them.

Common suite registration entry points:

- `Ansight.Tools.VisualTree` -> `WithVisualTreeTools()`
- `Ansight.Tools.Reflection` -> `WithReflectionTools(...)`
- `Ansight.Tools.Database` -> `WithDatabaseTools()`
- `Ansight.Tools.FileSystem` -> `WithFileSystemTools(...)`
- `Ansight.Tools.Preferences` -> `WithPreferencesTools(...)`
- `Ansight.Tools.SecureStorage` -> `WithSecureStorageTools(...)`

Guard selection:

- `WithToolsDisabled()`: no discovery and no execution
- `WithReadOnlyToolAccess()`: read-scoped tools only
- `WithReadWriteToolAccess()`: read and write tools, but not delete tools
- `WithAllToolAccess()`: read, write, and delete tools

Registration constraints that should usually be configured when those suites are enabled:

- reflection: add roots plus traversal and writable or invokable allow-lists
- file system: add only approved extra roots with stable tags
- preferences: restrict stores, keys, or key prefixes
- secure storage: restrict storage identifiers, services, and key allow-lists

## Lifecycle Guidance

- `.NET for Android`: if lifecycle tracking is requested, use `Ansight.Platforms.Android.AndroidAppLifecycleTracker.Register(this)` from the application type
- `.NET for iOS`: if lifecycle tracking is requested, call `Runtime.SetAppLifecycleState(...)` from `AppDelegate` foreground and background callbacks
- `.NET MAUI`: keep those same lifecycle hooks in the platform files under `Platforms/`

## Screen-View Guidance

- `.NET MAUI`: emit `Runtime.ScreenViewed(...)` from `ContentPage.OnAppearing()` or an equivalent navigation presentation point
- `.NET for Android` and `.NET for iOS`: emit `Runtime.ScreenViewed(...)` from the real screen-presentation point rather than navigation intent alone
- if the user has not asked for screen-view integration yet, ask first instead of adding it by default

## Tool Guidance

- install tool packages separately from the base `Ansight` package
- keep tools restricted to local-development builds and gated behind `AnsightAllowRemoteTools`
- use `WithReadOnlyToolAccess()` by default
- only move to `WithReadWriteToolAccess()` when the requested tool actually needs write operations
- use `WithAllToolAccess()` only when delete-scoped operations are genuinely required
- reflection writes and invocations need both the reflection package and a write-capable guard policy

## Done Criteria

- the app builds
- Ansight initializes from the correct startup path for the target app shape
- pairing flow is clearly documented for the user
- optional telemetry or tools are only enabled when requested
- the final response lists changed files and any follow-up step the user must perform in Studio