### Install Debug Build for Sample App

Source: https://github.com/mibrahimdev/sharingan/blob/develop/README.md

Installs the debug version of the sample composeApp to the Android device.

```bash
./gradlew :sample:composeApp:installDebug
```

--------------------------------

### Install Ktor Plugin

Source: https://github.com/mibrahimdev/sharingan/blob/develop/site/index.html

Integrates Sharingan's HTTP logging capabilities into your Ktor application by installing the SharinganKtor plugin.

```kotlin
install(SharinganKtor)
```

--------------------------------

### Integrate Ktor HTTP Client Plugin

Source: https://github.com/mibrahimdev/sharingan/blob/develop/site/docs/getting-started.html

Install the SharinganKtor plugin to capture HTTP requests and responses. Secrets are masked and streams are not consumed.

```kotlin
val client = HttpClient {
    install(SharinganKtor) // that's it
}
```

--------------------------------

### Implement Platform-Specific Time Formatting

Source: https://github.com/mibrahimdev/sharingan/blob/develop/docs/ARCHITECTURE.md

Provides platform-specific implementations for formatting time. This example shows the common declaration and Android/iOS actual implementations.

```kotlin
currentTimeMillis()
```

```kotlin
System.currentTimeMillis()
```

```kotlin
NSDate().timeIntervalSince1970 * 1000
```

--------------------------------

### Install Sharingan Ktor Plugin

Source: https://github.com/mibrahimdev/sharingan/blob/develop/AGENTS.md

Integrate Sharingan's Ktor plugin for automatic HTTP traffic capture in debug builds. Customize capture settings like redacted headers and body logging.

```kotlin
HttpClient { install(SharinganKtor) }
HttpClient { install(SharinganKtor) {
    store = Sharingan.store          // SharinganStore, default shown
    redactedHeaders = setOf("Authorization", "Proxy-Authorization", "Cookie", "Set-Cookie") // default
    captureBodies = true             // textual content types only; SSE/binary never read
    maxBodyBytes = 65536             // longer bodies truncated with a marker
} }
```

--------------------------------

### Capture Dependency Resolution Before Cleanup

Source: https://github.com/mibrahimdev/sharingan/blob/develop/docs/superpowers/plans/2026-06-12-ios-readiness.md

Runs a Gradle task to list dependencies for a specific configuration and saves the output to a file for later comparison. It then counts occurrences of 'org.jetbrains.compose' to verify initial setup.

```bash
./gradlew :sharingan:dependencies --configuration iosSimulatorArm64CompileKlibraries -q > /tmp/deps-before.txt && grep -c "org.jetbrains.compose" /tmp/deps-before.txt
```

--------------------------------

### Implement Platform-Specific Back Navigation

Source: https://github.com/mibrahimdev/sharingan/blob/develop/docs/ARCHITECTURE.md

Provides platform-specific implementations for handling back navigation. This example shows the common declaration and Android/iOS actual implementations.

```kotlin
PlatformBackHandler(enabled, onBack)
```

```kotlin
androidx.activity.compose.BackHandler
```

--------------------------------

### Implement Platform-Specific Text Sharing

Source: https://github.com/mibrahimdev/sharingan/blob/develop/docs/ARCHITECTURE.md

Provides platform-specific implementations for sharing text. This example shows the common declaration and Android/iOS actual implementations.

```kotlin
shareText(String)
```

```kotlin
Intent.ACTION_SEND
```

```kotlin
UIActivityViewController
```

--------------------------------

### Implement Platform-Specific Clipboard Copy

Source: https://github.com/mibrahimdev/sharingan/blob/develop/docs/ARCHITECTURE.md

Provides platform-specific implementations for copying text to the clipboard. This example shows the common declaration and Android/iOS actual implementations.

```kotlin
copyToClipboard(String)
```

```kotlin
ClipboardManager.setPrimaryClip
```

```kotlin
UIPasteboard.generalPasteboard
```

--------------------------------

### Implement Platform-Specific Clock Time Formatting

Source: https://github.com/mibrahimdev/sharingan/blob/develop/docs/ARCHITECTURE.md

Provides platform-specific implementations for formatting clock time including milliseconds. This example shows the common declaration and Android/iOS actual implementations.

```kotlin
formatClockTime(Long)
```

```kotlin
SimpleDateFormat("HH:mm:ss.SSS", Locale.US)
```

```kotlin
NSDateFormatter
```

--------------------------------

### Example AI Agent Export Payload

Source: https://github.com/mibrahimdev/sharingan/blob/develop/site/docs/ai-exports.html

This is the structured Markdown content generated by Sharingan's 'Copy for AI agent' feature. It includes HTTP event details and a JSON response body.

```markdown
## HTTP 500 — GET /v1/streams/cam-12
host: api.iot-fleet.dev
duration: 10 214 ms (TTFB 10 180 · download 34)
request:
  Authorization: ••••
  Accept: application/json
response body:
```json
{ "error": "upstream_timeout",
  "stream": "cam-12", "retry_after": 30 }
```
```

--------------------------------

### Attach Session to Bug Report (Kotlin)

Source: https://github.com/mibrahimdev/sharingan/blob/develop/site/docs/ai-exports.html

Example of how to use SharinganExport to attach a network session to a bug report automatically. This requires the Sharingan library and a bug tracking integration.

```kotlin
val report = SharinganExport.agentMarkdown(Sharingan.events.value)
bugTracker.attach("network-session.md", report)
```

--------------------------------

### Assemble Release Build for Parity Proof

Source: https://github.com/mibrahimdev/sharingan/blob/develop/README.md

Assembles the release build of the sample composeApp with the 'sharingan.noop' property set for parity proofing.

```bash
./gradlew :sample:composeApp:assembleRelease -Psharingan.noop
```

--------------------------------

### Building Pure-Swift XCFrameworks

Source: https://github.com/mibrahimdev/sharingan/blob/develop/docs/superpowers/plans/2026-06-12-ios-readiness.md

Instructions for building the XCFrameworks for the pure-Swift consumer test. This involves building both XCFrameworks as per the README.

```bash
maestri ask "OpenCode #2" -- "build both XCFrameworks per README, create a fresh pure-Swift app (~/sharingan-swift-consumer-test, no Kotlin/Gradle), follow only the README "Pure Swift app" section: embed, configuration-dependent search path + embed phase, URLSession or manual Sharingan capture call per docs, present viewer, screenshot, build the Release configuration too and confirm it links the noop (viewer presents as an empty controller)."
```

--------------------------------

### iOS Entry Points

Source: https://github.com/mibrahimdev/sharingan/blob/develop/llms.txt

Exposes the Sharingan UIViewController and a method to present it, usable from Swift or Kotlin.

```APIDOC
## iOS Entry Points

### Description
Provides access to the Sharingan UI on iOS.

### Methods
- `SharinganViewController()`: Creates an instance of the Sharingan UIViewController.
- `presentSharingan(animated: Boolean = true)`: Presents the Sharingan UI over the topmost view controller.

### Parameters
- `animated` (Boolean, Optional): Determines if the presentation should be animated. Defaults to true.
```

--------------------------------

### Run JVM and Kotlin/Native Tests

Source: https://github.com/mibrahimdev/sharingan/blob/develop/docs/ARCHITECTURE.md

Commands to execute unit tests on the JVM and Kotlin/Native platforms for the Sharingan module.

```bash
./gradlew :sharingan:testDebugUnitTest
./gradlew :sharingan:iosSimulatorArm64Test
```

--------------------------------

### Build Sharingan Release XCFramework

Source: https://github.com/mibrahimdev/sharingan/blob/develop/README.md

Use these Gradle commands to build the release versions of the Sharingan and Sharingan-noop XCFrameworks. The output frameworks will have the same name for easy import.

```bash
./gradlew :sharingan:assembleSharinganReleaseXCFramework	# debug-tool build
```

```bash
./gradlew :sharingan-noop:assembleSharinganReleaseXCFramework	# inert twin
```

--------------------------------

### Android UI Entry Point

Source: https://github.com/mibrahimdev/sharingan/blob/develop/AGENTS.md

Shows how to display the Sharingan UI on Android. Requires POST_NOTIFICATIONS permission on API 33+.

```kotlin
Sharingan.show(context)                  // open browser directly
Sharingan.setNotificationEnabled(false)  // opt out
```

--------------------------------

### No-op SharinganKtor ClientPlugin

Source: https://github.com/mibrahimdev/sharingan/blob/develop/docs/ARCHITECTURE.md

This Kotlin code defines the no-operation `SharinganKtor` ClientPlugin. It installs cleanly and registers no hooks, ensuring zero runtime cost in release builds.

```kotlin
package dev.sharingan.noop.ktor

import io.ktor.client.plugins.*

object SharinganKtor : ClientPlugin<Unit> {
    override val key: AttributeKey<Unit> = AttributeKey("SharinganKtor")

    override val prepare: ((Unit) -> Unit)? = null
    override val install: ((client: HttpClient, scope: Unit) -> Unit) = { _, _ ->
        // No-op: installs cleanly but registers zero hooks.
    }
}
```

--------------------------------

### Example HTTP 500 Error Response Body

Source: https://github.com/mibrahimdev/sharingan/blob/develop/site/index.html

This JSON snippet represents a typical error response body for an HTTP 500 error, indicating an upstream timeout.

```json
{
  "error": "upstream_timeout",
  "stream": "cam-12", "retry_after": 30
}
```

--------------------------------

### Run Sample App Instrumented Tests

Source: https://github.com/mibrahimdev/sharingan/blob/develop/docs/ARCHITECTURE.md

Command to execute on-device UI tests for the sample app on Android.

```bash
./gradlew :sample:composeApp:connectedDebugAndroidTest
```

--------------------------------

### Build from Source: Publish to Maven Local

Source: https://github.com/mibrahimdev/sharingan/blob/develop/site/docs/getting-started.html

Clone the repository and publish Sharingan to your local Maven repository to build against local changes. This is useful for contributing or testing modifications.

```bash
git clone https://github.com/mibrahimdev/Sharingan && cd Sharingan
./gradlew publishToMavenLocal
```

--------------------------------

### Configure Sharingan XCFramework in Gradle

Source: https://github.com/mibrahimdev/sharingan/blob/develop/docs/superpowers/plans/2026-06-12-ios-readiness.md

Sets up the XCFramework for the main 'Sharingan' artifact, defining base name and adding iOS targets.

```kotlin
    // Same baseName in :sharingan and :sharingan-noop — pure-Swift consumers
    // swap debug/noop per build configuration by search path, so
    // `import Sharingan` must resolve identically in both.
    val sharinganXCFramework = XCFramework("Sharingan")
    iosArm64()
    iosSimulatorArm64 {
        testRuns.configureEach { deviceId = "iPhone 17 Pro" }
    }
    listOf(iosArm64(), iosSimulatorArm64()).forEach {
        target ->
        target.binaries.framework {
            baseName = "Sharingan"
            isStatic = true
            sharinganXCFramework.add(this)
        }
    }
```

--------------------------------

### iOS UI Entry Point

Source: https://github.com/mibrahimdev/sharingan/blob/develop/AGENTS.md

Presents the Sharingan UI modally on iOS from Swift or Kotlin. Can be called from any thread.

```kotlin
SharinganViewController(): UIViewController
presentSharingan(animated: Boolean = true)  // presents over topmost VC, any thread
```

--------------------------------

### Kotlin Multiplatform Dependencies (Shared Module)

Source: https://github.com/mibrahimdev/sharingan/blob/develop/site/docs/getting-started.html

Configure dependencies in your shared module's `build.gradle.kts` for Kotlin Multiplatform projects. This example conditionally includes the debug or noop artifact based on a Gradle property and ensures it's exported correctly for iOS.

```kotlin
kotlin {
    val sharinganArtifact = if (providers.gradleProperty("release").isPresent)
        "io.github.mibrahimdev:sharingan-noop:0.1.0" else "io.github.mibrahimdev:sharingan:0.1.0"

    listOf(iosArm64(), iosSimulatorArm64()).forEach {
        target ->
        target.binaries.framework {
            baseName = "shared"
            export(sharinganArtifact)   // surfaces Sharingan in shared.h
        }
    }

    sourceSets {
        commonMain.dependencies {
            implementation(sharinganArtifact)
        }
        iosMain.dependencies {
            api(sharinganArtifact)      // export() requires api at THIS source set
        }
    }
}
```

--------------------------------

### Theme Initialization Script

Source: https://github.com/mibrahimdev/sharingan/blob/develop/site/docs/ai-exports.html

This JavaScript code initializes the theme based on local storage or system preferences. It runs immediately upon script execution.

```javascript
(function(){try{var t=localStorage.getItem("sharingan-theme");if(t!=="light"&&t!=="dark")t=(window.matchMedia&&window.matchMedia("(prefers-color-scheme: light)").matches)?"light":"dark";document.documentElement.setAttribute("data-theme",t);}catch(e){}})();
```

--------------------------------

### Assemble Release XCFramework for Sharingan-Noop Module

Source: https://github.com/mibrahimdev/sharingan/blob/develop/docs/superpowers/specs/2026-06-12-ios-readiness-design.md

This command builds the release XCFramework for the `:sharingan-noop` module. This module provides inert implementations for debug/noop swaps.

```bash
./gradlew :sharingan-noop:assembleSharinganReleaseXCFramework
```

--------------------------------

### Ktor HTTP Client Integration (Zero-Config)

Source: https://github.com/mibrahimdev/sharingan/blob/develop/site/docs/integrations.html

Automatically capture HTTP traffic with the Ktor plugin. No initial configuration is needed for basic usage.

```kotlin
val client = HttpClient {
    install(SharinganKtor)
}
```

--------------------------------

### Configure Sharingan-Noop XCFramework in Gradle

Source: https://github.com/mibrahimdev/sharingan/blob/develop/docs/superpowers/plans/2026-06-12-ios-readiness.md

Sets up the XCFramework for the 'Sharingan-noop' artifact, ensuring it has the same base name for interchangeable use.

```kotlin
    val sharinganXCFramework = XCFramework("Sharingan")
    listOf(iosArm64(), iosSimulatorArm64()).forEach {
        target ->
        target.binaries.framework {
            baseName = "Sharingan"
            isStatic = true
            sharinganXCFramework.add(this)
        }
    }
```

--------------------------------

### Ktor HTTP Client Integration (Full Configuration)

Source: https://github.com/mibrahimdev/sharingan/blob/develop/site/docs/integrations.html

Customize Ktor HTTP capture settings, including body capture, maximum body size, and header redaction.

```kotlin
install(SharinganKtor) {
    captureBodies = true            // default
    maxBodyBytes = 64 * 1024        // default — longer bodies truncate with a marker
    redactedHeaders = setOf("Authorization", "X-Api-Key")  // additive to defaults
}
```

--------------------------------

### Build Release XCFrameworks

Source: https://github.com/mibrahimdev/sharingan/blob/develop/docs/superpowers/plans/2026-06-12-ios-readiness.md

Command to build the release XCFrameworks for both Sharingan and Sharingan-noop artifacts. Outputs are directed to standard error and the last 5 lines are shown.

```bash
./gradlew :sharingan:assembleSharinganReleaseXCFramework :sharingan-noop:assembleSharinganReleaseXCFramework 2>&1 | tail -5
```

--------------------------------

### Compose UI Entry Point

Source: https://github.com/mibrahimdev/sharingan/blob/develop/AGENTS.md

Displays the Sharingan UI screen within a Jetpack Compose application. This is a debug artifact.

```kotlin
@Composable SharinganScreen(modifier, darkTheme = isSystemInDarkTheme(), store = Sharingan.store)
```

--------------------------------

### Add and Commit iOS Onboarding Changes

Source: https://github.com/mibrahimdev/sharingan/blob/develop/docs/superpowers/plans/2026-06-12-ios-readiness.md

Stages changes for iOS onboarding documentation and commits them with a detailed message. This includes artifact acquisition, API requirements, build phase hazards, version pinning, and framework embedding.

```bash
git add README.md docs/RECIPES.md AGENTS.md llms.txt site/
git commit -m "Docs: iOS onboarding that actually compiles — mavenLocal, export(), Xcode wiring, XCFramework path

Every undocumented step the first-time-consumer field test hit is now
written down: artifact acquisition, iosMain api + export() requirement,
the -Prelease build-phase hazard, pinned version matrix, pure-Swift
XCFramework embedding, and the real SharinganUI Swift names.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>"
```

--------------------------------

### Export Events as Summary String

Source: https://github.com/mibrahimdev/sharingan/blob/develop/AGENTS.md

Generate a concise, one-line summary for each event, including timestamps.

```kotlin
summary(events): String             // one line per event, clock-stamped
```

--------------------------------

### MQTT Client Integration

Source: https://github.com/mibrahimdev/sharingan/blob/develop/docs/RECIPES.md

Integrate MQTT clients like KMQTT, HiveMQ, and Paho with Sharingan for subscribing, receiving, and publishing messages. Log payloads as JSON for better visualization.

```kotlin
client.subscribe(filter, qos) { /* granted */ Sharingan.mqtt.subscribed(filter, qos) }
client.onMessage { msg -> Sharingan.mqtt.received(msg.topic, msg.payload.decodeToString(), msg.qos) }
client.publish(topic, bytes, qos, retained).also {
    Sharingan.mqtt.publish(topic, bytes.decodeToString(), qos, retained)
}
```

--------------------------------

### Publishing KMP Library Locally

Source: https://github.com/mibrahimdev/sharingan/blob/develop/docs/superpowers/plans/2026-06-12-ios-readiness.md

Run this command in the library repository to publish the KMP library to your local Maven repository before integrating it into the iOS consumer project.

```bash
./gradlew publishToMavenLocal
```

--------------------------------

### Perform Full Build and Test After Cleanup

Source: https://github.com/mibrahimdev/sharingan/blob/develop/docs/superpowers/plans/2026-06-12-ios-readiness.md

Executes a full build and unit tests for the project after applying changes to the Gradle build script. This verifies that the modifications have not introduced any build or test failures.

```bash
./gradlew :sharingan:testDebugUnitTest :sharingan:compileKotlinIosSimulatorArm64 2>&1 | tail -3
```

--------------------------------

### Manual MQTT Logging

Source: https://github.com/mibrahimdev/sharingan/blob/develop/README.md

Log MQTT publish, receive, and subscribe events manually using Sharingan.mqtt. Payloads that parse as JSON will be pretty-printed.

```kotlin
// MQTT (any client)
Sharingan.mqtt.publish(topic, payloadAsText, qos = 1, retained = false)
Sharingan.mqtt.received(topic, payloadAsText, qos = 1)
Sharingan.mqtt.subscribed("devices/+/commands/#", qos = 1)
```

--------------------------------

### Assemble Release XCFramework for Sharingan Module

Source: https://github.com/mibrahimdev/sharingan/blob/develop/docs/superpowers/specs/2026-06-12-ios-readiness-design.md

This command builds the release XCFramework for the `:sharingan` module. It's part of the XCFramework distribution strategy for iOS.

```bash
./gradlew :sharingan:assembleSharinganReleaseXCFramework
```

--------------------------------

### Export Events as Human-Readable Summary

Source: https://github.com/mibrahimdev/sharingan/blob/develop/README.md

Generate a concise, human-digestible summary of events, with one line per event.

```kotlin
SharinganExport.summary(events)           // human digest, one line per event
```

--------------------------------

### Sharingan Data Flow Diagram

Source: https://github.com/mibrahimdev/sharingan/blob/develop/docs/ARCHITECTURE.md

Illustrates the data flow within the Sharingan system, from capture entry points through storage to various consumers like the UI and export functionalities.

```text
 capture entry points                store                      consumers
┌──────────────────────┐
│ SharinganKtor plugin │──┐
│ (ktor/SharinganKtor) │  │   ┌─────────────────────┐   ┌──────────────────────────┐
├──────────────────────┤  ├──▶│ SharinganStore       │──▶│ UI: SharinganScreen      │
│ Sharingan.http .log  │  │   │ ring buffer (300)    │   │  wrapper → stateless     │
│ Sharingan.mqtt .pub… │──┘   │ StateFlow<List<…>>   │   │  *Content composables    │
│ Sharingan.ble  .noti…│      │ + isRecording flag   │   ├──────────────────────────┤
└──────────────────────┘      └─────────────────────┘   │ CaptureNotification      │
  header redaction happens          ▲      │             │ (Android, observes flow) │
  BEFORE record() — secrets         │      │             ├──────────────────────────┤
  never enter the buffer     record()      └────────────▶│ SharinganExport          │
                                                         │ agentMarkdown/curl/json/ │
                                                         │ sessionJson/summary      │
                                                         └───────────┬──────────────┘
                                                                     ▼
                                                  copyToClipboard / shareText
                                                  (expect/actual per platform)

```

--------------------------------

### Manifest-Merged ContentProvider for Android Initialization

Source: https://github.com/mibrahimdev/sharingan/blob/develop/docs/ARCHITECTURE.md

This XML snippet shows the declaration of SharinganInitProvider in the library's AndroidManifest.xml. This allows for zero-setup initialization of Sharingan on Android before the Application.onCreate() method.

```xml
<provider
    android:name=".internal.SharinganAndroid.SharinganInitProvider"
    android:authorities="${applicationId}.sharingan-init"
    android:exported="false"
    android:initOrder="100" />
```

--------------------------------

### Tagging and Pushing for Release

Source: https://github.com/mibrahimdev/sharingan/blob/develop/docs/RELEASING.md

Commands to checkout the main branch, pull latest changes, create a Git tag matching the catalog version, and push the tag to origin. This action triggers the CI staging process.

```bash
git checkout main && git pull
git tag v0.1.0          # must equal the catalog version, with a leading "v"
git push origin v0.1.0
```

--------------------------------

### Run Android Instrumented Tests

Source: https://github.com/mibrahimdev/sharingan/blob/develop/docs/ARCHITECTURE.md

Command to execute on-device UI tests for the Sharingan module on Android.

```bash
./gradlew :sharingan:connectedDebugAndroidTest
```

--------------------------------

### MQTT Client Subscription Logging

Source: https://github.com/mibrahimdev/sharingan/blob/develop/site/docs/integrations.html

Log MQTT subscription events by calling Sharingan.mqtt.subscribed within your client's subscription callback.

```kotlin
client.subscribe(filter, qos) { /* granted */ Sharingan.mqtt.subscribed(filter, qos) }
```

--------------------------------

### Build Release XCFramework for Swift Apps

Source: https://github.com/mibrahimdev/sharingan/blob/develop/site/docs/getting-started.html

Generate the release XCFramework for Sharingan and its no-op twin using Gradle. These are used for pure Swift applications.

```bash
./gradlew :sharingan:assembleSharinganReleaseXCFramework        # debug-tool build
./gradlew :sharingan-noop:assembleSharinganReleaseXCFramework   # inert twin
```

--------------------------------

### Re-integrating iOS Consumer Project

Source: https://github.com/mibrahimdev/sharingan/blob/develop/docs/superpowers/plans/2026-06-12-ios-readiness.md

Instructions for the field agent to re-integrate the KMP library into the iOS consumer project, following the updated README instructions. This involves deleting old wrapper files and re-establishing the integration.

```bash
maestri ask "OpenCode #2" -- "(1) delete the hand-rolled wrapper shared/src/iosMain/.../SharinganIos.kt and the api-placement workarounds in ~/sharingan-ios-consumer-test; (2) re-integrate strictly per the updated README (it now has the export() recipe and SharinganUI names); (3) rebuild, run on the booted iPhone 17 Pro simulator, trigger traffic, present the viewer via SharinganUI.presentSharingan(animated: true); (4) screenshot every state to ~/sharingan-ios-consumer-test/screenshots-v2/ including a landscape rotation (xcrun simctl cannot rotate — ask it to use AppleScript System Events keystrokes on the Simulator app, Cmd+Right Arrow, or flag it for manual check); (5) list any step it needed that the docs don't state."
```

--------------------------------

### Configurable HTTP Logging with Ktor

Source: https://github.com/mibrahimdev/sharingan/blob/develop/README.md

Customize SharinganKtor logging by enabling body capture, setting max body size, and redacting sensitive headers. Body capture is on by default.

```kotlin
install(SharinganKtor) {
    captureBodies = true            // default — request/response bodies are recorded
    maxBodyBytes = 64 * 1024        // default
    redactedHeaders = setOf("Authorization", "X-Api-Key")
}
```

--------------------------------

### Present Sharingan Modally with Animation Option

Source: https://github.com/mibrahimdev/sharingan/blob/develop/docs/superpowers/specs/2026-06-12-ios-readiness-design.md

This function provides a convenient way to present the Sharingan viewer modally from the main queue. It resolves the topmost view controller and supports an optional animation parameter.

```kotlin
presentSharingan(animated: Boolean = true)
```

--------------------------------

### Run API Parity Check

Source: https://github.com/mibrahimdev/sharingan/blob/develop/docs/api-parity.md

Execute the Gradle task to verify API parity between the debug and no-op modules. This command should be run locally to catch discrepancies before pushing changes.

```bash
./gradlew checkApiParity

```

--------------------------------

### Sharingan UIViewController for iOS

Source: https://github.com/mibrahimdev/sharingan/blob/develop/docs/superpowers/plans/2026-06-12-ios-readiness.md

Creates a UIViewController for the Sharingan log browser using Compose. It includes a check for strict plist sanity to prevent crashes on certain iOS versions. Call `presentSharingan` to display it.

```kotlin
@file:OptIn(ExperimentalObjCName::class)
@file:ObjCName("SharinganUI")

package dev.sharingan

import androidx.compose.ui.window.ComposeUIViewController
import dev.sharingan.internal.topmostViewController
import dev.sharingan.ui.SharinganScreen
import kotlin.experimental.ExperimentalObjCName
import kotlin.native.ObjCName
import platform.UIKit.UIApplication
import platform.UIKit.UIViewController
import platform.UIKit.UIWindow
import platform.UIKit.UIWindowScene
import platform.darwin.dispatch_async
import platform.darwin.dispatch_get_main_queue

/**
 * The Sharingan log browser as a `UIViewController` — embed or present it
 * however your app likes (sheet, push, debug menu). For the common case, 
 * call [presentSharingan] instead.
 *
 * A host app whose Info.plist lacks `CADisableMinimumFrameDurationOnPhone` 
 * must never crash (Compose Multiplatform 1.11 aborts on a strict plist 
 * check otherwise); the key remains a host-side opt-in for ProMotion/120Hz.
 */
public fun SharinganViewController(): UIViewController = ComposeUIViewController(configure = {
    enforceStrictPlistSanityCheck = false
}) {
    SharinganScreen()
}

/**
 * Presents the log browser over the topmost view controller of the key
 * window. Safe to call from any thread; no-ops if no window is attached yet.
 *
 * ```swift
 * SharinganUI.presentSharingan(animated: true)
 * ```
 */
public fun presentSharingan(animated: Boolean = true) {
    dispatch_async(dispatch_get_main_queue()) {
        val root = UIApplication.sharedApplication.connectedScenes
            .filterIsInstance<UIWindowScene>()
            .flatMap { it.windows.filterIsInstance<UIWindow>() }
            .firstOrNull { it.keyWindow } 
            ?.rootViewController ?: return@dispatch_async
        topmostViewController(root)
            .presentViewController(SharinganViewController(), animated = animated, completion = null)
    }
}
```

--------------------------------

### Export Events as Agent Markdown

Source: https://github.com/mibrahimdev/sharingan/blob/develop/README.md

Use these functions to export single events or entire sessions as structured Markdown suitable for AI agents. The output includes method, path, status, host, request headers, and response body.

```kotlin
SharinganExport.agentMarkdown(event)      // one event as structured Markdown
SharinganExport.agentMarkdown(events)     // whole session, with counts header
```

--------------------------------

### Import XCFramework DSL in Gradle

Source: https://github.com/mibrahimdev/sharingan/blob/develop/docs/superpowers/plans/2026-06-12-ios-readiness.md

Imports the necessary XCFramework plugin for Kotlin Multiplatform projects.

```kotlin
import org.jetbrains.kotlin.gradle.plugin.mpp.apple.XCFramework
```

--------------------------------

### Log MQTT Publish

Source: https://github.com/mibrahimdev/sharingan/blob/develop/llms.txt

Log an MQTT publish event using Sharingan.mqtt.publish. You can specify the topic, payload, QoS, and retained status. Errors can also be logged.

```kotlin
Sharingan.mqtt.publish(topic, payload /*String?*/, qos = 0, retained = false, error = null)
```

--------------------------------

### Release Workflow Diagram

Source: https://github.com/mibrahimdev/sharingan/blob/develop/docs/RELEASING.md

Visual representation of the release process: tag push triggers CI staging, followed by manual verification and release in the Central Portal.

```text
push tag v<version>  ──▶  CI stages to Central Portal  ──▶  STOP (awaiting human)
                                                              │
                          maintainer verifies + clicks  ◀─────┘
                          "Publish" in the portal, then
                          cuts the GitHub Release
```

--------------------------------

### Present Sharingan UI in Swift

Source: https://github.com/mibrahimdev/sharingan/blob/develop/docs/superpowers/plans/2026-06-12-ios-readiness.md

Use this snippet to present the Sharingan UI directly from Swift. It can be called from any thread and is the simplest way to display the UI.

```swift
import SwiftUI
import shared // your shared framework

// One-call presentation (topmost view controller, any thread):
SharinganUI.presentSharingan(animated: true)

// Or embed/present the view controller yourself:
struct SharinganView: UIViewControllerRepresentable {
    func makeUIViewController(context: Context) -> UIViewController {
        SharinganUI.SharinganViewController()
    }
    func updateUIViewController(_ vc: UIViewController, context: Context) {}
}
.sheet(isPresented: $showLogs) { SharinganView() }
```

--------------------------------

### MQTT Client Publish Logging

Source: https://github.com/mibrahimdev/sharingan/blob/develop/site/docs/integrations.html

Log published MQTT messages by calling Sharingan.mqtt.publish after your client's publish operation.

```kotlin
client.publish(topic, bytes, qos, retained).also {
    Sharingan.mqtt.publish(topic, bytes.decodeToString(), qos, retained)
}
```

--------------------------------

### Opt-in ExperimentalObjCName in Gradle

Source: https://github.com/mibrahimdev/sharingan/blob/develop/docs/superpowers/plans/2026-06-12-ios-readiness.md

Adds the `kotlin.experimental.ExperimentalObjCName` opt-in to all source sets in the Gradle build scripts. This is a belt-and-braces approach alongside the file-level opt-in.

```gradle
all { languageSettings.optIn("kotlin.experimental.ExperimentalObjCName") }
```

--------------------------------

### Inspect Generated Headers

Source: https://github.com/mibrahimdev/sharingan/blob/develop/docs/superpowers/plans/2026-06-12-ios-readiness.md

Searches the generated XCFramework header file for specific Swift/Objective-C symbols to verify their names and structure.

```bash
grep -n "SharinganUI\|SharinganViewController\|presentSharingan" sharingan/build/XCFrameworks/release/Sharingan.xcframework/ios-arm64/Sharingan.framework/Headers/Sharingan.h | head -20
```

--------------------------------

### Gradle Dependencies for Sharingan Integration

Source: https://github.com/mibrahimdev/sharingan/blob/develop/site/index.html

Add these dependencies to your build.gradle.kts file to integrate Sharingan for debug builds and a no-op version for release builds.

```kotlin
dependencies {
    debugImplementation("io.github.mibrahimdev:sharingan:0.1.0")
    releaseImplementation("io.github.mibrahimdev:sharingan-noop:0.1.0")
}
```

--------------------------------

### Export Events as Markdown

Source: https://github.com/mibrahimdev/sharingan/blob/develop/AGENTS.md

Generate Markdown formatted output for a single HTTP event or a session summary.

```kotlin
agentMarkdown(event): String        // "## GET /path" + status/host lines + headers + ```json body
agentMarkdown(events): String       // "# Sharingan session export" + counts + per-event sections
```

--------------------------------

### Publish Sharingan Locally for iOS Integration

Source: https://github.com/mibrahimdev/sharingan/blob/develop/docs/superpowers/plans/2026-06-12-ios-readiness.md

Clones the Sharingan repository and publishes the artifacts to the local Maven repository. This is a prerequisite for adding Sharingan as a dependency in local iOS development.

```bash
git clone https://github.com/<org>/sharingan && cd sharingan
./gradlew publishToMavenLocal
```

--------------------------------

### No-op Sharingan UIViewController for Release Builds

Source: https://github.com/mibrahimdev/sharingan/blob/develop/docs/superpowers/plans/2026-06-12-ios-readiness.md

Provides a no-operation twin of the Sharingan UIViewController for release builds. This ensures Swift call sites compile and run without including the UI or Compose payload.

```kotlin
@file:OptIn(ExperimentalObjCName::class)
@file:ObjCName("SharinganUI")

package dev.sharingan

import kotlin.experimental.ExperimentalObjCName
import kotlin.native.ObjCName
import platform.UIKit.UIViewController

/**
 * No-op twin: returns an empty view controller so Swift call sites compile
 * and run against the release framework without UI or Compose payload.
 */
public fun SharinganViewController(): UIViewController = UIViewController(nibName = null, bundle = null)

/** No-op twin: release builds have no browser to present. */
public fun presentSharingan(animated: Boolean = true) {
}
```

--------------------------------

### Creating a GitHub Release

Source: https://github.com/mibrahimdev/sharingan/blob/develop/docs/RELEASING.md

Command to create a GitHub release manually after the Maven Central deployment has been published. It uses the 'gh' CLI to create a release with a title and automatically generate release notes.

```bash
gh release create v0.1.0 --title v0.1.0 --generate-notes
```

--------------------------------

### Manual HTTP Logging with Sharingan HttpLogger

Source: https://github.com/mibrahimdev/sharingan/blob/develop/site/docs/integrations.html

Log HTTP requests and responses manually using Sharingan's HttpLogger, suitable for OkHttp or NSURLSession.

```kotlin
Sharingan.http.log(
    method = "GET",
    url = "https://api.example.dev/v1/devices",
    statusCode = 200,
    durationMillis = 214,
    requestHeaders = listOf("Accept" to "application/json"),
    responseBody = bodyText,          // JSON renders pretty-printed
    timing = listOf(TimingPhase("TTFB", 180), TimingPhase("Download", 34)),
)
```

--------------------------------

### Enable Experimental Objective-C Name Annotation

Source: https://github.com/mibrahimdev/sharingan/blob/develop/docs/superpowers/specs/2026-06-12-ios-readiness-design.md

These lines enable the experimental Objective-C name annotation for file-level naming. This is required for stable, intention-revealing class names in the Swift surface.

```kotlin
@file:OptIn(ExperimentalObjCName::class)
```

```kotlin
languageSettings.optIn("kotlin.experimental.ExperimentalObjCName")
```

--------------------------------

### HTTP Capture (Ktor Plugin)

Source: https://github.com/mibrahimdev/sharingan/blob/develop/AGENTS.md

Automatic HTTP traffic capture for Ktor clients using the SharinganKtor plugin. Configuration options include custom store, redacted headers, body capture, and max body size.

```APIDOC
## HTTP Capture (Ktor Plugin)

### Description
Automatic HTTP traffic capture for Ktor clients using the SharinganKtor plugin. Configuration options include custom store, redacted headers, body capture, and max body size.

### Usage
```kotlin
HttpClient { install(SharinganKtor) }
HttpClient { install(SharinganKtor) {
    store = Sharingan.store          // SharinganStore, default shown
    redactedHeaders = setOf("Authorization", "Proxy-Authorization", "Cookie", "Set-Cookie") // default
    captureBodies = true             // textual content types only; SSE/binary never read
    maxBodyBytes = 65536             // longer bodies truncated with a marker
} }
```
```