docs(cocoa): Update SDK skill guidance

skills/sentry-cocoa-sdk/references/error-monitoring.md

@@ -1,7 +1,7 @@
 # Error Monitoring — Sentry Cocoa SDK
 
-> Minimum SDK: `sentry-cocoa` v7.0.0+  
-> Swift Error improvements: v8.7.0+  
+> Minimum SDK: `sentry-cocoa` v7.0.0+
+> Swift Error improvements: v8.7.0+
 > HTTP client error capture: v8.0.0+
 
 ## Configuration
@@ -11,10 +11,11 @@
 | `enableCrashHandler` | `Bool` | `true` | Master switch for crash reporting (signal handlers, Mach exceptions, C++) |
 | `sampleRate` | `Float` (0.0–1.0) | `1.0` | Percentage of error events sent |
 | `attachStacktrace` | `Bool` | `true` | Attach stack traces to all captured messages |
+| `attachAllThreads` | `Bool` | `false` | Attach full stack traces for all threads (SDK 9.9+) |
 | `maxBreadcrumbs` | `Int` | `100` | Max breadcrumbs per event |
 | `enableAppHangTracking` | `Bool` | `true` | Detect main thread unresponsiveness |
 | `appHangTimeoutInterval` | `Double` | `2.0` | Seconds before a hang is reported |
-| `enableAppHangTrackingV2` | `Bool` | `true` (v9+) | Differentiates fully/non-fully-blocking hangs |
+| `enableReportNonFullyBlockingAppHangs` | `Bool` | `true` | Include non-fully-blocking hangs where V2 is supported |
 | `enableWatchdogTerminationTracking` | `Bool` | `true` | Track OS watchdog kills via heuristics |
 | `enableCaptureFailedRequests` | `Bool` | `true` | Auto-capture HTTP client errors as Sentry events |
 | `failedRequestStatusCodes` | `[HttpStatusCodeRange]` | `[500–599]` | Status code ranges that trigger error capture |
@@ -119,8 +120,8 @@ SentrySDK.start { options in
     options.enableAppHangTracking = true
     options.appHangTimeoutInterval = 2.0    // default; avoid values < 0.1
 
-    // V2: differentiates fully vs non-fully blocking hangs (default in v9+)
-    options.enableAppHangTrackingV2 = true
+    // V2 is the default in v9+ where supported; this option controls whether
+    // less-actionable non-fully-blocking hangs are reported.
     options.enableReportNonFullyBlockingAppHangs = true
 }
 
@@ -235,10 +236,9 @@ SentrySDK.start { options in
             return nil
         }
         // Suppress app hang events
-        // Note: V1 (enableAppHangTracking) uses exception type "App Hanging"
-        //       V2 (enableAppHangTrackingV2, default in 9.0+) may use a different
-        //       type — inspect event.exceptions?.first?.type in beforeSend to confirm
-        if event.exceptions?.first?.type == "App Hanging" {
+        // V1/macOS may use "App Hanging"; V2 uses the more specific values
+        // listed above. Inspect event.exceptions?.first?.type in beforeSend.
+        if event.exceptions?.first?.type?.contains("App Hang") == true {
             return nil
         }
         // Scrub sensitive data
@@ -325,7 +325,7 @@ When `enableCrashHandler = true` (default), the SDK installs:
 - **C++ exception handlers** — `std::terminate` interception
 - **Objective-C uncaught exception handler** — `NSSetUncaughtExceptionHandler`
 
-> ⚠️ Always test crash reporting **without a debugger attached**. The debugger intercepts signals and prevents the SDK from capturing crashes.
+> Warning: Always test crash reporting **without a debugger attached**. The debugger intercepts signals and prevents the SDK from capturing crashes.
 
 ### macOS — uncaught NSException reporting
 

skills/sentry-cocoa-sdk/references/logging.md

@@ -1,6 +1,6 @@
 # Logging — Sentry Cocoa SDK
 
-> Minimum SDK (experimental): `sentry-cocoa` v8.55.0+  
+> Minimum SDK (experimental): `sentry-cocoa` v8.55.0+
 > Minimum SDK (stable): `sentry-cocoa` v9.0.0+
 
 ## Configuration
@@ -59,7 +59,7 @@ logger.error("Payment failed",            attributes: ["amount": 99.99])
 logger.fatal("Connection pool exhausted", attributes: ["activeConnections": 100])
 ```
 
-Supported attribute value types: `String`, `Int`, `Double`, `Bool`.
+Supported Swift attribute value types include `String`, `Bool`, `Int`, `Double`, `Float`, arrays, and sets; other values are converted to strings.
 
 ### Log levels (severity order)
 
@@ -103,19 +103,19 @@ SentrySDK.start { options in
         if log.level == .debug && options.environment == "production" { return nil }
 
         // Enrich all logs with app version
-        var mutableLog = log
-        mutableLog.attributes["app.version"] =
-            Bundle.main.object(forInfoDictionaryKey: "CFBundleShortVersionString") as? String
-        return mutableLog
+        if let version = Bundle.main.object(forInfoDictionaryKey: "CFBundleShortVersionString") as? String {
+            log.attributes["app.version"] = SentryAttribute(string: version)
+        }
+        return log
     }
 }
 ```
 
 Available on `SentryLog`:
-- `log.level` — `SentryLevel` (`.trace`, `.debug`, `.info`, `.warning`, `.error`, `.fatal`)
-- `log.message` — `String`
+- `log.level` — `SentryLog.Level` (`.trace`, `.debug`, `.info`, `.warn`, `.error`, `.fatal`)
+- `log.body` — `String`
 - `log.timestamp` — `Date`
-- `log.attributes` — `[String: Any]`
+- `log.attributes` — `[String: SentryAttribute]`
 
 ### Automatic default attributes
 
@@ -188,7 +188,7 @@ SentrySDK.logger.info("User signed in",
 | Logs not appearing in Sentry | Verify `options.enableLogs = true` (v9+) or `options.experimental.enableLogs = true` (v8.55+) |
 | Logs only partially appearing | Logs may be lost during crashes; this is a known SDK limitation |
 | `SentrySDK.logger` not found | Requires v8.55.0+; check SPM/CocoaPods version |
-| Attributes not queryable | Only `String`, `Int`, `Double`, and `Bool` are supported attribute value types |
+| Attributes not queryable | Prefer `String`, `Bool`, `Int`, `Double`, `Float`, arrays, or sets; convert complex objects to stable strings |
 | `beforeSendLog` not called | Ensure you set it before `SentrySDK.start` completes and `enableLogs = true` |
 | Too many logs overwhelming Sentry | Use `beforeSendLog` to filter by level; set minimum level for production |
 | Logs missing user context | Call `SentrySDK.setUser(...)` before logging to attach user identity automatically |

skills/sentry-cocoa-sdk/references/metrics.md

@@ -0,0 +1,122 @@
+# Metrics — Sentry Cocoa SDK
+
+> Minimum SDK: experimental in v9.4.0+, generally available in v9.12.0+
+> Swift only; Objective-C metrics API is not currently available.
+> Metrics are enabled by default in v9.12.0+.
+
+Use metrics for aggregate counters, gauges, and distributions that should not create Sentry issues. Do not duplicate automatic tracing, app hangs, MetricKit diagnostics, or error events.
+
+## Configuration
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `enableMetrics` | `Bool` | `true` | Enable or disable metrics |
+| `beforeSendMetric` | `((SentryMetric) -> SentryMetric?)?` | `nil` | Filter or mutate metrics before send; return `nil` to drop |
+
+For SDK 9.4.0-9.11.x, metrics used `options.experimental.enableMetrics` and `options.experimental.beforeSendMetric`. Those experimental options were removed in 9.12.0; use the top-level options above.
+
+## Code Examples
+
+### Basic setup
+
+```swift
+import Sentry
+
+SentrySDK.start { options in
+    options.dsn = "___PUBLIC_DSN___"
+    options.enableMetrics = true  // default in SDK 9.12+
+}
+```
+
+### Counter
+
+Counters track discrete occurrences. `count` does not accept a unit.
+
+```swift
+SentrySDK.metrics.count(key: "button.click")
+
+SentrySDK.metrics.count(
+    key: "link.created",
+    value: 1,
+    attributes: [
+        "source": "share_extension",
+        "is_favorite": false
+    ]
+)
+```
+
+### Gauge
+
+Gauges track current state.
+
+```swift
+SentrySDK.metrics.gauge(
+    key: "queue.depth",
+    value: 42,
+    attributes: ["queue": "sync"]
+)
+```
+
+### Distribution
+
+Distributions track measured values where percentiles are useful.
+
+```swift
+SentrySDK.metrics.distribution(
+    key: "qr.render.duration",
+    value: 187.5,
+    unit: .millisecond,
+    attributes: [
+        "cache_hit": true,
+        "image_size": "1024"
+    ]
+)
+```
+
+### beforeSendMetric
+
+```swift
+SentrySDK.start { options in
+    options.dsn = "___PUBLIC_DSN___"
+    options.beforeSendMetric = { metric in
+        var metric = metric
+
+        if case let .boolean(drop)? = metric.attributes["drop_me"], drop {
+            return nil
+        }
+
+        metric.attributes["processed"] = .boolean(true)
+        metric.attributes["app_area"] = .string("links")
+        return metric
+    }
+}
+```
+
+## Attribute Types
+
+Metric attributes use `SentryAttributeValue` at the capture API and `SentryAttributeContent` inside `beforeSendMetric`.
+
+Supported capture values:
+- Scalar: `String`, `Bool`, `Int`, `Double`, `Float`
+- Arrays: `[String]`, `[Bool]`, `[Int]`, `[Double]`, `[Float]`
+- Sets: `Set<String>`, `Set<Bool>`, `Set<Int>`, `Set<Double>`, `Set<Float>` (SDK 9.13+)
+
+Use stable, low-cardinality attributes. Avoid URLs, IDs, user-entered names, or unbounded strings unless they are intentionally scrubbed and useful for grouping.
+
+## Best Practices
+
+- Use metrics for aggregate product and app-health signals, not exceptions or stack traces.
+- Keep metric names lowercase and dot-delimited, such as `link.created` or `network.reachability.changed`.
+- Prefer distributions for durations and sizes, gauges for current state, and counters for occurrences.
+- Avoid metrics that duplicate automatic spans, failed request events, app hangs, watchdog terminations, or MetricKit diagnostics.
+- Keep `enableMetrics = true` unless the app has a policy or volume reason to disable metrics.
+
+## Troubleshooting
+
+| Issue | Solution |
+|-------|----------|
+| `enableMetrics` compile error | Requires SDK 9.12+; on 9.4-9.11 use `experimental.enableMetrics` or upgrade |
+| Metric not sent | Verify `SentrySDK.start` ran and `enableMetrics` is true |
+| Count with `unit` fails | `count` has no `unit` parameter; use `gauge` or `distribution` if units are needed |
+| Objective-C compile issue | Metrics are Swift-only |
+| Too many unique series | Reduce high-cardinality attributes and metric names |

skills/sentry-cocoa-sdk/references/profiling.md

@@ -1,15 +1,16 @@
 # Profiling — Sentry Cocoa SDK
 
-> Minimum SDK for UI Profiling (`configureProfiling`): `sentry-cocoa` v8.49.0+  
-> Minimum SDK for stable `configureProfiling` API: v9.0.0+  
+> Minimum SDK for UI Profiling (`configureProfiling`): `sentry-cocoa` v8.49.0+
+> Minimum SDK for stable `configureProfiling` API: v9.0.0+
+> Supported platforms: iOS and macOS. Not supported on tvOS, watchOS, or visionOS.
 > **All legacy profiling APIs (`profilesSampleRate`, `enableAppLaunchProfiling`, continuous beta) were removed in v9.0.0.**
 
 ## Configuration
 
 | Option | Type | Default | Description |
 |--------|------|---------|-------------|
 | `configureProfiling` | `((SentryProfileOptions) -> Void)?` | `nil` | Closure to configure UI Profiling (v8.49.0+) |
-| `sessionSampleRate` | `Double` (0.0–1.0) | `0` | Fraction of user sessions to profile; evaluated once per session |
+| `sessionSampleRate` | `Float` (0.0–1.0) | `0` | Fraction of user sessions to profile; evaluated once per session |
 | `lifecycle` | `SentryProfileLifecycle` | `.manual` | `.trace` (auto) or `.manual` (explicit start/stop) |
 | `profileAppStarts` | `Bool` | `false` | Profile from the earliest possible lifecycle stage on next launch |
 
@@ -149,15 +150,15 @@ For CI/CD, set `SENTRY_AUTH_TOKEN` as an environment variable.
 // BEFORE (removed in v9.0.0)
 SentrySDK.start { options in
     options.tracesSampleRate = 1.0
-    options.profilesSampleRate = 1.0   // ❌ no longer exists
+    options.profilesSampleRate = 1.0   // Removed: no longer exists
 }
 
 // AFTER (v9.0.0+)
 SentrySDK.start { options in
     options.tracesSampleRate = 1.0
     options.configureProfiling = {
         $0.sessionSampleRate = 1.0
-        $0.lifecycle = .trace          // ✅ equivalent behaviour
+        $0.lifecycle = .trace          // Equivalent behavior
     }
 }
 ```
@@ -174,9 +175,9 @@ MetricKit delivers hang diagnostic payloads on iOS 15+ and macOS 12+. Starting w
 |----------|----------------------|
 | iOS | 15+ |
 | macOS | 12+ |
-| tvOS | ❌ |
-| watchOS | ❌ |
-| visionOS | ❌ |
+| tvOS | No |
+| watchOS | No |
+| visionOS | No |
 
 ## Best Practices