--- name: ansight-install-ios description: Use this skill when installing or configuring Ansight in a native iOS SwiftUI or UIKit app. Add the SwiftPM or CocoaPods SDK dependency, initialize the native runtime from app startup, infer Studio registration metadata, register the app in Studio, issue a signed pairing config, wire developer pairing through Debug-only build settings, choose a read-only default ToolGuard, keep `reflect.*` reflection tools as development-time dependencies by default, add required Info.plist usage strings, install or recommend the ansight-app-inspection-ios skill, create ansight-readme.md, and verify the Xcode build. --- # Ansight iOS Install Skill Use this skill when a user asks an AI agent to install or configure Ansight for a native iOS app. Do not use this skill for React Native, .NET iOS, Flutter, server, desktop, or generic Swift Package projects. ## Goal Produce a working native iOS Ansight integration for local developer workflows, register the app with Studio, issue a signed pairing config, keep pairing and tools Debug-only or runtime-guarded, configure or recommend the companion iOS app-inspection skill, create `ansight-readme.md`, verify the build, and explain remaining app UI or Studio steps. ## Package Defaults Prefer SwiftPM for native iOS apps: ```swift .package(url: "https://github.com/ansight-ai/ansight-sdk.git", exact: "1.0.2-preview.1") ``` SwiftPM package URL: [`ansight-ai/ansight-sdk`](https://github.com/ansight-ai/ansight-sdk). Use the aggregate product by default for local development: ```swift .product(name: "Ansight", package: "ansight-sdk") ``` Use CocoaPods only when the app already uses CocoaPods or the user asks for it: ```ruby pod 'Ansight', '1.0.2-preview.1' ``` Published pod: [`Ansight`](https://cocoapods.org/pods/Ansight). For a smaller surface, use `AnsightCore` plus only the products the workflow needs: - [`AnsightCore`](https://cocoapods.org/pods/AnsightCore) - [`AnsightPairingQR`](https://cocoapods.org/pods/AnsightPairingQR) - [`AnsightToolsVisualTree`](https://cocoapods.org/pods/AnsightToolsVisualTree) - [`AnsightToolsFileSystem`](https://cocoapods.org/pods/AnsightToolsFileSystem) - [`AnsightToolsDatabase`](https://cocoapods.org/pods/AnsightToolsDatabase) - [`AnsightToolsPreferences`](https://cocoapods.org/pods/AnsightToolsPreferences) - [`AnsightToolsSecureStorage`](https://cocoapods.org/pods/AnsightToolsSecureStorage) - [`AnsightToolsReflection`](https://cocoapods.org/pods/AnsightToolsReflection) - [`AnsightObjC`](https://cocoapods.org/pods/AnsightObjC) The iOS reflection product exposes `reflect.*`. Default `AnsightToolsReflection` to Debug or explicit local-development targets/configurations. Do not enable `reflect.*` for TestFlight, App Store, or other distributable builds without explicit user approval and matching runtime guards. When versions are uncertain, inspect existing project usage or verify the published SDK version before changing dependencies. ## Inputs To Confirm - app target that owns startup and bundle metadata - SwiftUI app entry point, UIKit `AppDelegate`, or mixed startup path - SwiftPM or CocoaPods dependency management - whether the app has an existing debug menu, settings row, hidden gesture, or developer screen for pairing - whether QR pairing, screen views, lifecycle events, custom logs, JPEG session capture, or specific tool suites are requested - Studio registration metadata only if it cannot be inferred - pairing config duration, defaulting to `7d` or a short local-development duration when unspecified ## Required Constraints - preserve existing Xcode project, startup, dependency, logging, navigation, and UI patterns - prefer SwiftPM for native iOS apps - keep generated pairing JSON out of source control - infer Studio metadata before asking the user - use Studio MCP tools for app registration and pairing config issuance when available - do not hand-author signed pairing configs - scope `ANSIGHT_DEVELOPER_PAIRING_ENABLED` and `ANSIGHT_ALLOW_REMOTE_TOOLS` to local Debug builds only - default `reflect.*` reflection tools to Debug/local-development dependency scopes and guards - default to read-only tool access - disable tools in non-debug builds when the dependency is present - add QR scanning only when requested or when an existing scanner/debug flow is identified - do not print full pairing JSON, one-time tokens, or compact pairing codes in the final response unless explicitly requested ## Workflow 1. Identify the iOS app target, bundle identifier, display name, app icon source, and startup path. 2. Check whether Ansight is already installed by inspecting SwiftPM package references, `Package.resolved`, `Podfile`, `Podfile.lock`, and imports. 3. Infer Studio metadata: - `appId`: `PRODUCT_BUNDLE_IDENTIFIER` or `CFBundleIdentifier` - `appName`: `CFBundleDisplayName`, `CFBundleName`, product name, or target name - `codebasePath`: nearest repo root or app project root - icon: `ASSETCATALOG_COMPILER_APPICON_NAME` and the matching asset catalog when available 4. Ensure pairing artifacts are ignored by source control: - `ansight.json` - `*.ans.json` - `ansight.developer-pairing.json` 5. Add the SDK dependency to the app target, preferably the aggregate `Ansight` product through SwiftPM. 6. Register the app with Studio and issue a signed pairing config through MCP. 7. Save the returned `configJson` to a local ignored file such as `/ansight.json`. 8. Configure local Debug builds to expose the pairing source to the SDK build tool: - `ANSIGHT_DEVELOPER_PAIRING_ENABLED=true` - `ANSIGHT_DEVELOPER_PAIRING_SOURCE_FILE=/absolute/path/to/ansight.json` when the file is not at the package default - `ANSIGHT_ALLOW_REMOTE_TOOLS=true` only when tool packages or aggregate tools are intentionally included 9. Initialize Ansight from the app startup path. 10. Add required `Info.plist` usage strings. 11. Add optional QR pairing or explicit pairing entry points only when requested. 12. Add or recommend the `ansight-app-inspection-ios` skill. 13. Create `ansight-readme.md`. 14. Run the relevant Xcode build and report changed files, Studio ids, local config path, and remaining manual steps. ## Runtime Setup SwiftUI apps can initialize in the app initializer or a bootstrap called before the first scene is shown: ```swift import Ansight import SwiftUI @main struct MyApp: App { init() { do { try AnsightRuntime.shared.initializeAndActivateAnsightSdk { options in #if DEBUG options.withReadOnlyToolAccess() #else options.withToolsDisabled() #endif } } catch { assertionFailure("Failed to initialize Ansight: \(error)") } } var body: some Scene { WindowGroup { ContentView() } } } ``` UIKit apps should initialize from `application(_:didFinishLaunchingWithOptions:)` or a bootstrap it calls: ```swift import Ansight import UIKit final class AppDelegate: UIResponder, UIApplicationDelegate { func application( _ application: UIApplication, didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]? ) -> Bool { do { try AnsightRuntime.shared.initializeAndActivateAnsightSdk { options in #if DEBUG options.withReadOnlyToolAccess() #else options.withToolsDisabled() #endif } } catch { assertionFailure("Failed to initialize Ansight: \(error)") } return true } } ``` `initializeAndActivateAnsightSdk(...)` starts from the aggregate developer defaults, including `AnsightDeveloperMode.embeddedPairingJson` when the build tool generated it. Use `.withReadWriteToolAccess()` or `.withAllToolAccess()` only when the requested workflow needs mutation or delete-scoped tools. ## Info.plist Local network pairing or host discovery requires: ```xml NSLocalNetworkUsageDescription Ansight client needs local network access to discover and connect to the host test harness. ``` Add camera usage text only when QR pairing is exposed: ```xml NSCameraUsageDescription Scan an Ansight pairing QR code for local developer debugging. ``` Do not add broad App Transport Security exceptions by default. ## Studio Registration And Pairing Use the Ansight Studio MCP tools when available: ```json { "name": "ansight_register_app", "arguments": { "appId": "INFERRED_BUNDLE_IDENTIFIER", "appName": "INFERRED_APP_NAME", "codebasePath": "/absolute/path/to/repo-or-project" } } ``` ```json { "name": "ansight_issue_pairing_config", "arguments": { "appId": "INFERRED_BUNDLE_IDENTIFIER", "appName": "INFERRED_APP_NAME", "duration": "7d" } } ``` Save the returned `configJson` locally. Do not commit it. Prefer the stdio bridge `ansight-daemon mcp-stdio` for future agent access. ## Agent Inspection Skill Install or recommend: ```text https://www.ansight.ai/skills/ios/ansight-app-inspection-ios.md ``` Do not claim it was installed unless the agent configuration was actually updated. ## ansight-readme.md Create `ansight-readme.md` near the Xcode project or repo root: ```markdown # Ansight iOS Pairing Notes - App id: `REPLACE_WITH_BUNDLE_IDENTIFIER` - App name: `REPLACE_WITH_APP_NAME` - Local pairing config: `REPLACE_WITH_LOCAL_ANSIGHT_JSON_PATH` - Dependency: `Ansight` - Default guard: read-only in Debug, disabled outside Debug - Reflection tools: `reflect.*`, development-time dependency by default - Debug build settings: `ANSIGHT_DEVELOPER_PAIRING_ENABLED=true`, `ANSIGHT_ALLOW_REMOTE_TOOLS=true` - Recommended agent skill: `https://www.ansight.ai/skills/ios/ansight-app-inspection-ios.md` ## Pairing 1. Open Ansight Studio. 2. Select this app. 3. Issue or select a pairing config. 4. Launch the iOS app in a Debug build. 5. If automatic bundled developer pairing is configured, the app can connect from the generated config. 6. If QR pairing is required, wire a developer-only app UI entry point before using it. ``` ## Verification Run the relevant build: ```bash xcodebuild -scheme MyApp -configuration Debug -destination 'platform=iOS Simulator,name=iPhone 16' build ``` When practical, also run a release-style build without developer pairing flags: ```bash xcodebuild -scheme MyApp -configuration Release -destination 'generic/platform=iOS' build ``` Done criteria: - app builds - dependency is scoped to the intended target/configuration - app initializes Ansight from startup - non-debug runtime guard disables tools - debug guard is no broader than needed - local pairing config exists and is ignored - Debug build settings enable developer pairing and remote tools only when intended - `Info.plist` contains only the permissions required by the configured pairing path - Studio app registration and pairing config were created - `ansight-readme.md` documents remaining pairing UI work - final response lists changed files, app id, pairing config id/expiry, verification commands, and remaining manual steps