@mmerterden/multi-agent-pipeline 20.7.0 → 20.8.0

package/pipeline/skills/shared/external/ios-networking/SKILL.md

@@ -1,490 +1,414 @@
 ---
 name: ios-networking
-description: "Build, review, or improve networking code in iOS/macOS apps using URLSession with async/await, structured concurrency, and modern Swift patterns. Use when working with REST APIs, downloading files, uploading data, WebSocket connections, pagination, retry logic, request middleware, caching, background transfers, or network reachability monitoring. Also use when handling HTTP requests, API clients, network error handling, or data fetching in Swift apps."
+description: "URLSession with async/await and structured concurrency on iOS and macOS: HTTP requests, REST API clients, response validation, error handling, retry with backoff, middleware and token refresh, pagination, caching, downloads, uploads, background transfers, WebSockets, NWPathMonitor reachability, Network.framework, ATS. Use when building or reviewing networking code, API clients or data fetching. Not for pinning (swift-security) or Keychain internals."
 metadata:
-  source: "dpearson2699/swift-ios-skills (PolyForm Perimeter 1.0.0)"
+  source: multi-agent-pipeline
 ---
 
 # iOS Networking
 
-Modern networking patterns for iOS 26+ using URLSession with async/await and
-structured concurrency. All examples target Swift 6.3. No third-party
-dependencies required -- URLSession covers the vast majority of networking
-needs.
-
-## Contents
-
-- [Core URLSession async/await](#core-urlsession-asyncawait)
-- [API Client Architecture](#api-client-architecture)
-- [Error Handling](#error-handling)
-- [Pagination](#pagination)
-- [Network Reachability](#network-reachability)
-- [Configuring URLSession](#configuring-urlsession)
-- [App Transport Security (ATS)](#app-transport-security-ats)
-- [Common Mistakes](#common-mistakes)
-- [Review Checklist](#review-checklist)
-- [References](#references)
+URLSession handles nearly every networking job an app has, and it needs no
+third-party package to do it well. Baseline for this skill: iOS 26, Swift 6.3.
 
 ## Core URLSession async/await
 
-URLSession gained native async/await overloads in iOS 15. Prefer these for
-foreground data, upload, download, and streaming work. Background URLSession
-transfers are the main exception: they still use task/delegate APIs so the
-system can deliver events after suspension or relaunch.
+The async overloads (iOS 15 and later) are the default for foreground work:
+data, upload, download and streaming. The one exception is a background
+session. The system delivers its events after the app was suspended or even
+relaunched, so it keeps the task-plus-delegate API.
 
-### Data Requests
+### Data requests
 
 ```swift
-// Basic GET
-let (data, response) = try await URLSession.shared.data(from: url)
-
-// With a configured URLRequest
-var request = URLRequest(url: url)
-request.httpMethod = "POST"
-request.setValue("application/json", forHTTPHeaderField: "Content-Type")
-request.httpBody = try JSONEncoder().encode(payload)
-request.timeoutInterval = 30
-request.cachePolicy = .reloadIgnoringLocalCacheData
-
-let (data, response) = try await URLSession.shared.data(for: request)
+let (forecast, _) = try await URLSession.shared.data(from: forecastURL)
+
+var order = URLRequest(url: ordersURL)
+order.httpMethod = "POST"
+order.addValue("application/json", forHTTPHeaderField: "Content-Type")
+order.httpBody = try JSONEncoder().encode(newOrder)
+order.timeoutInterval = 30
+order.cachePolicy = .reloadIgnoringLocalCacheData
+let (confirmation, reply) = try await session.data(for: order)
 ```
 
-### Response Validation
+### Response validation
 
-Always validate the HTTP status code before decoding. URLSession does not
-throw for 4xx/5xx responses -- it only throws for transport-level failures.
+A 404 or a 503 is not a thrown error. URLSession throws only when the
+transport fails (no route, TLS failure, cancellation), so check the status
+yourself before touching the body:
 
 ```swift
-guard let httpResponse = response as? HTTPURLResponse else {
+guard let status = (response as? HTTPURLResponse)?.statusCode else {
     throw NetworkError.invalidResponse
 }
-
-guard (200..<300).contains(httpResponse.statusCode) else {
-    throw NetworkError.httpError(
-        statusCode: httpResponse.statusCode,
-        data: data
-    )
+if !(200...299).contains(status) {
+    throw NetworkError.httpStatus(code: status, body: data, message: nil)
 }
 ```
 
-### JSON Decoding with Codable
+### Decoding with Codable
 
 ```swift
-func fetch<T: Decodable>(_ type: T.Type, from url: URL) async throws -> T {
-    let (data, response) = try await URLSession.shared.data(from: url)
-
-    guard let httpResponse = response as? HTTPURLResponse,
-          (200..<300).contains(httpResponse.statusCode) else {
-        throw NetworkError.invalidResponse
-    }
-
+func load<Model: Decodable>(_ kind: Model.Type, at address: URL) async throws -> Model {
+    let (bytes, reply) = try await session.data(from: address)
+    try validate(reply, body: bytes)
     let decoder = JSONDecoder()
     decoder.dateDecodingStrategy = .iso8601
     decoder.keyDecodingStrategy = .convertFromSnakeCase
-    return try decoder.decode(T.self, from: data)
+    return try decoder.decode(kind, from: bytes)
 }
 ```
 
-### Downloads and Uploads
+### Downloads and uploads
 
-Use `download(for:)` for large files -- it streams to disk instead of
-loading the entire payload into memory.
+`download(for:)` streams the body to a file instead of memory, so use it for
+anything large. The returned file is temporary: move or copy it right away.
 
 ```swift
-// Download to a temporary file
-let (localURL, response) = try await URLSession.shared.download(for: request)
+let (tempFile, _) = try await session.download(for: manualRequest)
+let target = URL.documentsDirectory.appending(path: "manual.pdf")
+try FileManager.default.moveItem(at: tempFile, to: target)
 
-// Move or copy the returned temporary file promptly.
-let destination = documentsDirectory.appendingPathComponent("file.zip")
-try FileManager.default.moveItem(at: localURL, to: destination)
+let (ack, _) = try await session.upload(for: syncRequest, from: jsonData)
+let (receipt, _) = try await session.upload(for: videoRequest, fromFile: videoURL)
 ```
 
-For delegate-based `URLSessionDownloadDelegate`, move or open the temporary
-file before `urlSession(_:downloadTask:didFinishDownloadingTo:)` returns.
-
-Background sessions are delegate-driven transfer queues. Use task creation
-APIs such as `downloadTask(with:)` and file-backed `uploadTask(with:fromFile:)`,
-then handle `URLSessionDelegate` / task delegate callbacks. Do not use async
-convenience APIs such as `data(for:)`, `download(for:)`, or `upload(for:)` as
-the durable background-session pattern.
-
-```swift
-// Upload data
-let (data, response) = try await URLSession.shared.upload(for: request, from: bodyData)
+A `URLSessionDownloadDelegate` gets the same kind of temporary file and has
+to relocate or open it before `urlSession(_:downloadTask:didFinishDownloadingTo:)` returns.
 
-// Upload from file
-let (data, response) = try await URLSession.shared.upload(for: request, fromFile: fileURL)
-```
+A background session is a delegate-driven transfer queue. Its work is
+`downloadTask(with:)` plus `uploadTask(with:fromFile:)` for uploads from disk,
+reported through session and task delegate callbacks. The async conveniences
+`data(for:)`, `download(for:)` and `upload(for:)` are not a durable
+background pattern. See [background and WebSocket guide](references/background-websocket.md).
 
 ### Streaming with AsyncBytes
 
-Use `bytes(for:)` for streaming responses, progress tracking, or
-line-delimited data (e.g., server-sent events).
+`bytes(for:)` hands you the body as it arrives: useful for progress, for
+newline-delimited JSON and for server-sent events.
 
 ```swift
-let (bytes, response) = try await URLSession.shared.bytes(for: request)
-
-for try await line in bytes.lines {
-    // Process each line as it arrives (e.g., SSE stream)
-    handleEvent(line)
+let (stream, _) = try await session.bytes(for: request)
+for try await line in stream.lines {
+    handle(line)
 }
 ```
 
-## API Client Architecture
+## API client architecture
 
-### Protocol-Based Client
+### Protocol-based client
 
-Define a protocol for testability. This lets you swap implementations in
-tests without mocking URLSession directly.
+Put the client behind a protocol. Tests then substitute a double instead of
+mocking URLSession.
 
 ```swift
 protocol APIClientProtocol: Sendable {
-    func fetch<T: Decodable & Sendable>(
-        _ type: T.Type,
-        endpoint: Endpoint
-    ) async throws -> T
-
-    func send<T: Decodable & Sendable>(
-        _ type: T.Type,
-        endpoint: Endpoint,
-        body: some Encodable & Sendable
-    ) async throws -> T
+    func fetch<Reply: Decodable & Sendable>(_ endpoint: Endpoint, as kind: Reply.Type) async throws -> Reply
+    func send<Reply: Decodable & Sendable>(_ endpoint: Endpoint, json payload: some Encodable & Sendable,
+                                           as kind: Reply.Type) async throws -> Reply
+    func perform(_ endpoint: Endpoint) async throws
+    func upload<Reply: Decodable & Sendable>(_ endpoint: Endpoint, bytes: Data,
+                                             as kind: Reply.Type) async throws -> Reply
 }
-```
 
-```swift
 struct Endpoint: Sendable {
-    let path: String
-    var method: String = "GET"
+    enum HTTPMethod: String, Sendable { case get, post, put, patch, delete }
+
+    var path: String
+    var method: HTTPMethod = .get
     var queryItems: [URLQueryItem] = []
     var headers: [String: String] = [:]
-
-    func url(relativeTo baseURL: URL) -> URL {
-        guard let components = URLComponents(
-            url: baseURL.appendingPathComponent(path),
-            resolvingAgainstBaseURL: true
-        ) else {
-            preconditionFailure("Invalid URL components for path: \(path)")
-        }
-        var mutableComponents = components
-        if !queryItems.isEmpty {
-            mutableComponents.queryItems = queryItems
+    var body: Data? = nil
+    var cachePolicy: URLRequest.CachePolicy = .useProtocolCachePolicy
+    var timeoutInterval: TimeInterval = 30
+
+    func urlRequest(relativeTo baseURL: URL) throws -> URLRequest {
+        guard var parts = URLComponents(url: baseURL.appending(path: path),
+                                        resolvingAgainstBaseURL: true) else {
+            throw NetworkError.invalidURL
         }
-        guard let url = mutableComponents.url else {
-            preconditionFailure("Failed to construct URL from components")
-        }
-        return url
+        if !queryItems.isEmpty { parts.queryItems = queryItems }
+        guard let url = parts.url else { throw NetworkError.invalidURL }
+        var request = URLRequest(url: url, cachePolicy: cachePolicy, timeoutInterval: timeoutInterval)
+        request.httpMethod = method.rawValue.uppercased()
+        request.httpBody = body
+        request.allHTTPHeaderFields = headers
+        return request
     }
 }
 ```
 
-The client accepts a `baseURL`, optional custom `URLSession`, `JSONDecoder`,
-and an array of `RequestMiddleware` interceptors. Each method builds a
-`URLRequest` from the endpoint, applies middleware, executes the request,
-validates the status code, and decodes the result. See
-[references/urlsession-patterns.md](references/urlsession-patterns.md) for the complete `APIClient` implementation
-with convenience methods, request builder, and test setup.
+A bad URL is a thrown `NetworkError.invalidURL`, never a crash; nothing in
+this skill force-unwraps.
 
-Production clients should receive an injected, configured `URLSession` instead
-of calling `URLSession.shared` internally. Configure `URLSessionConfiguration`
-with request/resource timeouts, cache policy or `URLCache`,
-`waitsForConnectivity`, data-cost policy, and delegates when authentication
-challenges, redirects, metrics, pinning, or background transfer handling matter.
+The concrete `APIClient` is built from a base URL, an injected `URLSession`
+and an ordered list of `RequestMiddleware`; it owns a snake_case, ISO 8601
+`JSONDecoder` and `JSONEncoder`. Every method runs
+the same pipeline: build the request, apply middleware, execute, validate,
+decode. The full implementation, a fluent request builder and tests are in
+[URLSession patterns](references/urlsession-patterns.md).
 
-### Lightweight Closure-Based Client
+Inject a configured session into production clients rather than reaching for
+`URLSession.shared` inside them. The configuration is where request and
+resource timeouts, cache policy or a `URLCache`, `waitsForConnectivity`,
+cellular and Low Data Mode policy live, plus a delegate when you need auth
+challenges, redirect control, metrics, pinning or background transfers.
 
-For apps using the MV pattern, use closure-based clients for testability
-and SwiftUI preview support. See [references/lightweight-clients.md](references/lightweight-clients.md) for
-the full pattern (struct of async closures, injected via init).
+### Lightweight closure-based client
 
-### Request Middleware / Interceptors
+MV-style SwiftUI apps often do better with a struct of async closures passed
+in through `init`: trivial to stub in previews and tests. See
+[lightweight clients](references/lightweight-clients.md).
 
-Middleware transforms requests before they are sent. Use this for
-authentication, logging, analytics headers, and similar cross-cutting
-concerns.
+### Request middleware
+
+Middleware rewrites a request before it goes out. Authentication, logging,
+tracing and analytics headers all fit here.
 
 ```swift
 protocol RequestMiddleware: Sendable {
-    func prepare(_ request: URLRequest) async throws -> URLRequest
+    func adapt(_ request: inout URLRequest) async throws
 }
-```
 
-```swift
-struct AuthMiddleware: RequestMiddleware {
-    let tokenProvider: @Sendable () async throws -> String
+struct BearerTokenMiddleware: RequestMiddleware {
+    let currentToken: @Sendable () async throws -> String
 
-    func prepare(_ request: URLRequest) async throws -> URLRequest {
-        var request = request
-        let token = try await tokenProvider()
-        request.setValue("Bearer \(token)", forHTTPHeaderField: "Authorization")
-        return request
+    func adapt(_ request: inout URLRequest) async throws {
+        let token = try await currentToken()
+        request.addValue("Bearer " + token, forHTTPHeaderField: "Authorization")
     }
 }
 ```
 
-### Token Refresh Flow
+### Token refresh
 
-Handle 401 responses by refreshing the token and retrying once.
+On a 401, refresh once and repeat the call once. A second 401 is a real
+failure, not a loop.
 
 ```swift
-func fetchWithTokenRefresh<T: Decodable & Sendable>(
-    _ type: T.Type,
-    endpoint: Endpoint,
-    tokenStore: TokenStore
-) async throws -> T {
+func fetchRefreshingOnce<Reply: Decodable & Sendable>(_ endpoint: Endpoint, as kind: Reply.Type) async throws -> Reply {
     do {
-        return try await fetch(type, endpoint: endpoint)
-    } catch NetworkError.httpError(statusCode: 401, _) {
-        try await tokenStore.refreshToken()
-        return try await fetch(type, endpoint: endpoint)
+        return try await client.fetch(endpoint, as: kind)
+    } catch NetworkError.httpStatus(code: 401, _, _) {
+        try await credentials.refresh()
+        return try await client.fetch(endpoint, as: kind)
     }
 }
 ```
 
-## Error Handling
+## Error handling
 
-### Structured Error Types
+### Structured error type
+
+One error enum is shared by this file and every reference:
 
 ```swift
-enum NetworkError: Error, Sendable {
+enum NetworkError: Error, LocalizedError {
+    case invalidURL
     case invalidResponse
-    case httpError(statusCode: Int, data: Data)
-    case decodingFailed(Error)
+    case httpStatus(code: Int, body: Data, message: String?)
+    case decodingFailed(any Error)
     case noConnection
     case timedOut
     case cancelled
-
-    /// Map a URLError to a typed NetworkError
-    static func from(_ urlError: URLError) -> NetworkError {
-        switch urlError.code {
-        case .notConnectedToInternet, .networkConnectionLost:
-            return .noConnection
-        case .timedOut:
-            return .timedOut
-        case .cancelled:
-            return .cancelled
-        default:
-            return .httpError(statusCode: -1, data: Data())
+    case transport(URLError)
+
+    static func from(_ error: URLError) -> NetworkError {
+        switch error.code {
+        case .notConnectedToInternet, .networkConnectionLost: .noConnection
+        case .timedOut: .timedOut
+        case .cancelled: .cancelled
+        default: .transport(error)
         }
     }
 }
 ```
 
-### Key URLError Cases
+`Error` already refines `Sendable`, so the enum is Sendable without saying
+so. Unknown transport failures keep their `URLError` in `.transport` instead
+of posing as a fake HTTP status. `errorDescription` returns `nil` for
+`.cancelled` so cancellation never surfaces as a message; the full
+implementation is in [URLSession patterns](references/urlsession-patterns.md#error-types).
 
-| URLError Code | Meaning | Action |
+### URLError codes worth handling
+
+| Code | What happened | Response |
 |---|---|---|
-| `.notConnectedToInternet` | Device offline | Show offline UI, queue for retry |
-| `.networkConnectionLost` | Connection dropped mid-request | Retry with backoff |
-| `.timedOut` | Server did not respond in time | Retry once, then show error |
-| `.cancelled` | Task was cancelled | No action needed; do not show error |
-| `.cannotFindHost` | DNS failure | Check URL, show error |
-| `.secureConnectionFailed` | TLS handshake failed | Check cert pinning, ATS config |
-| `.userAuthenticationRequired` | Authentication required to access a resource | Trigger auth flow |
+| `.notConnectedToInternet` | Device is offline | Offline UI, queue for later |
+| `.networkConnectionLost` | The connection broke partway through | Back off, then try again |
+| `.timedOut` | Server too slow | Retry once, then report |
+| `.cancelled` | Task was cancelled | Do nothing, show nothing |
+| `.cannotFindHost` | DNS lookup failed | Check the host, report |
+| `.secureConnectionFailed` | TLS handshake failed | Check ATS and pinning setup |
+| `.userAuthenticationRequired` | Resource needs credentials | Start sign-in |
+
+### Server error bodies
 
-### Decoding Server Error Bodies
+Many APIs return a JSON body with the failure. The client decodes it into
+`message` when it can; a caller can also decode it on demand:
 
 ```swift
-struct APIErrorResponse: Decodable, Sendable {
-    let code: String
-    let message: String
-}
+struct APIErrorBody: Decodable, Sendable {
+    let code: String?
+    let message: String?
 
-func decodeAPIError(from data: Data) -> APIErrorResponse? {
-    try? JSONDecoder().decode(APIErrorResponse.self, from: data)
+    static func decode(from data: Data) -> APIErrorBody? {
+        try? JSONDecoder().decode(APIErrorBody.self, from: data)
+    }
 }
 
-// Usage in catch block
-catch NetworkError.httpError(let statusCode, let data) {
-    if let apiError = decodeAPIError(from: data) {
-        showError("Server error: \(apiError.message)")
-    } else {
-        showError("HTTP \(statusCode)")
-    }
+do { try await client.perform(archiveEndpoint) }
+catch NetworkError.httpStatus(let status, let body, let message) {
+    banner = message ?? APIErrorBody.decode(from: body)?.message ?? "Request failed (\(status))"
 }
 ```
 
-### Retry with Exponential Backoff
+### Retry with exponential backoff
 
-Use structured concurrency for retries. Respect task cancellation between
-attempts. Skip retries for cancellation and 4xx client errors (except 429).
+Retry inside structured concurrency so cancellation stops the loop. Never
+retry cancellation or a 4xx, with 429 as the exception; 5xx and transient
+transport errors are fair game.
 
 ```swift
 func withRetry<T: Sendable>(
     maxAttempts: Int = 3,
     initialDelay: Duration = .seconds(1),
+    maxDelay: Duration = .seconds(30),
+    shouldRetry: @Sendable (any Error) -> Bool = isTransient,
     operation: @Sendable () async throws -> T
 ) async throws -> T {
-    var lastError: Error?
+    precondition(maxAttempts > 0, "maxAttempts must be at least 1")
     for attempt in 0..<maxAttempts {
+        try Task.checkCancellation()
         do {
             return try await operation()
         } catch {
-            lastError = error
-            if error is CancellationError { throw error }
-            if case NetworkError.httpError(let code, _) = error,
-               (400..<500).contains(code), code != 429 { throw error }
-            if attempt < maxAttempts - 1 {
-                try await Task.sleep(for: initialDelay * Int(pow(2.0, Double(attempt))))
-            }
+            guard attempt < maxAttempts - 1, shouldRetry(error) else { throw error }
+            let capped = min(initialDelay * (1 << attempt), maxDelay)
+            try await Task.sleep(for: capped + capped * Double.random(in: 0...0.1))
         }
     }
-    throw lastError!
+    preconditionFailure("the last attempt always returns or throws")
 }
 ```
 
+There is no sleep after the last attempt: its error is rethrown at once. The
+`isTransient` predicate is in
+[URLSession patterns](references/urlsession-patterns.md#retries-that-back-off-exponentially).
+
 ## Pagination
 
-Build cursor-based or offset-based pagination with `AsyncSequence`.
-Always check `Task.isCancelled` between pages. See
-[references/urlsession-patterns.md](references/urlsession-patterns.md) for complete `CursorPaginator` and
-offset-based implementations.
+Model paging as an `AsyncSequence` of pages, cursor-based or offset-based,
+and call `try Task.checkCancellation()` (or test `Task.isCancelled`) before
+every page request. Both paginators are written out in
+[URLSession patterns](references/urlsession-patterns.md#paging-by-cursor).
 
-## Network Reachability
+## Network reachability
 
-Use `NWPathMonitor` from the Network framework -- not third-party
-Reachability libraries. On current OS targets it conforms to `AsyncSequence`;
-wrap `pathUpdateHandler` only for compatibility or custom projections.
+Use `NWPathMonitor`, not a third-party Reachability port. On current SDKs the
+monitor is itself an `AsyncSequence`; wrapping `pathUpdateHandler` in your own
+stream is only for older targets or for a custom projection.
 
 ```swift
-import Network
-
-func observeNetworkStatus() async {
-    let monitor = NWPathMonitor()
-
-    for await path in monitor {
-        handle(path.status)
-    }
+for await path in NWPathMonitor() {
+    isOnline = path.status == .satisfied
+    useLowBandwidth = path.isConstrained || path.isExpensive
 }
 ```
 
-Check `path.isExpensive` (cellular) and `path.isConstrained` (Low Data
-Mode) to adapt behavior (reduce image quality, skip prefetching).
+`isExpensive` means cellular or a hotspot; `isConstrained` means Low Data
+Mode. Use them to lower image quality or skip prefetching.
 
-Use Network.framework for low-level TCP, UDP, listeners, Bonjour, path
-monitoring, or WebSocket protocol work -- not ordinary REST APIs. For iOS 26
-`NetworkConnection<QUIC>`, `openStream(...)` and `inboundStreams(...)` are
-async throwing APIs; see [references/network-framework.md#quic-multiplexed-streams](references/network-framework.md#quic-multiplexed-streams).
+Network.framework is for TCP and UDP, listeners, Bonjour, path monitoring and
+WebSocket protocol work. It is not the tool for an ordinary REST API. On
+iOS 26 `NetworkConnection<QUIC>` adds multiplexed streams, and both
+`openStream(...)` and `inboundStreams(...)` are async and throwing. See
+[Network framework guide](references/network-framework.md) and its
+[QUIC stream notes](references/network-framework.md#quic-multiplexed-streams).
 
 ## Configuring URLSession
 
-Create a configured session for production code. `URLSession.shared` is
-acceptable only for simple, one-off requests.
+`URLSession.shared` suits a quick one-off call. Anything that ships deserves a
+configured session:
 
 ```swift
-let configuration = URLSessionConfiguration.default
-configuration.timeoutIntervalForRequest = 30
-configuration.timeoutIntervalForResource = 300
-configuration.waitsForConnectivity = true
-configuration.requestCachePolicy = .returnCacheDataElseLoad
-configuration.httpAdditionalHeaders = [
+let config = URLSessionConfiguration.default
+config.timeoutIntervalForRequest = 30
+config.timeoutIntervalForResource = 300
+config.waitsForConnectivity = true
+config.requestCachePolicy = .returnCacheDataElseLoad
+config.httpAdditionalHeaders = [
     "Accept": "application/json",
-    "Accept-Language": Locale.preferredLanguages.first ?? "en"
+    "Accept-Language": Locale.preferredLanguages.prefix(3).joined(separator: ", "),
 ]
-
-let session = URLSession(configuration: configuration)
+let session = URLSession(configuration: config)
 ```
 
-`waitsForConnectivity = true` is valuable -- it makes the session wait for
-a network path instead of failing immediately when offline. Combine with
-`urlSession(_:taskIsWaitingForConnectivity:)` delegate callback for UI
-feedback.
+With `waitsForConnectivity`, a request made while offline waits for a usable
+path instead of failing immediately. Implement
+`urlSession(_:taskIsWaitingForConnectivity:)` on the delegate to tell the user.
 
 ## App Transport Security (ATS)
 
-ATS enforces HTTPS for all connections by default. Do not disable it.
-ATS is URL Loading System policy, so it covers `URLSession` rather than making
-lower-level `Network.framework` connections secure automatically. When using
-Network.framework, configure secure TLS parameters and trust handling correctly
-for that protocol stack.
-
-Use domain-specific ATS exceptions only as a last resort.
-
-**Rules:**
-- Never set `NSAllowsArbitraryLoads` to `true` in production unless there is no narrower option.
-- ATS exceptions require justification and may trigger additional App Store review.
-- Use exception domains only for third-party servers you cannot upgrade to HTTPS.
-- `NSAllowsLocalNetworking` is acceptable for local device communication (Bonjour, IoT).
-- Prefer ATS `NSPinnedDomains` for declarative pinning when possible. Raw bytes
-  from `SecKeyCopyExternalRepresentation` are not sufficient for SPKI pinning;
-  correct SPKI pinning hashes Subject Public Key Info and belongs in `swift-security`.
-
-## Common Mistakes
-
-**DON'T:** Use `URLSession.shared` with custom configuration needs.
-**DO:** Create a configured `URLSession` with appropriate timeouts, caching,
-and delegate for production code.
-
-**DON'T:** Force-unwrap `URL(string:)` with dynamic input.
-**DO:** Use `URL(string:)` with proper error handling. Force-unwrap is
-acceptable only for compile-time-constant strings.
-
-**DON'T:** Decode JSON on the main thread for large payloads.
-**DO:** Keep decoding on the calling context of the URLSession call, which
-is off-main by default. Only hop to `@MainActor` to update UI state.
-
-**DON'T:** Ignore cancellation in long-running network tasks.
-**DO:** Check `Task.isCancelled` or call `try Task.checkCancellation()` in
-loops (pagination, streaming, retry). Use `.task` in SwiftUI for automatic
-cancellation.
-
-**DON'T:** Use Alamofire or Moya when URLSession async/await handles the
-need.
-**DO:** Use URLSession directly. With async/await, the ergonomic gap that
-justified third-party libraries no longer exists. Reserve third-party
-libraries for genuinely missing features (e.g., image caching).
-
-**DON'T:** Mock URLSession directly in tests.
-**DO:** Use `URLProtocol` subclass for transport-level mocking, or use
-protocol-based clients that accept a test double.
-
-**DON'T:** Use `data(for:)` for large file downloads.
-**DO:** Use `download(for:)` which streams to disk and avoids memory spikes.
-
-**DON'T:** Fire network requests from `body` or view initializers.
-**DO:** Use `.task` or `.task(id:)` to trigger network calls.
-
-**DON'T:** Hardcode authentication tokens in requests.
-**DO:** Inject tokens via middleware so they are centralized and refreshable.
-
-**DON'T:** Ignore HTTP status codes and decode blindly.
-**DO:** Validate status codes before decoding. A 200 with invalid JSON and
-a 500 with an error body require different handling.
-
-## Review Checklist
-
-- [ ] Foreground transfers use async/await; background sessions use delegate/task APIs
-- [ ] Error handling covers URLError cases (.notConnectedToInternet, .timedOut, .cancelled)
-- [ ] Requests are cancellable (respect Task cancellation via `.task` modifier or stored Task references)
-- [ ] Authentication tokens injected via middleware, not hardcoded
-- [ ] Response HTTP status codes validated before decoding
-- [ ] Large downloads use `download(for:)` not `data(for:)`
-- [ ] Network calls happen off `@MainActor` (only UI updates on main)
-- [ ] URLSession configured with appropriate timeouts and caching
-- [ ] Production clients inject configured sessions instead of using `URLSession.shared`
-- [ ] Background transfers use task/delegate APIs, not async convenience APIs
-- [ ] Retry logic excludes cancellation and 4xx client errors
-- [ ] Pagination checks `Task.isCancelled` between pages
-- [ ] Sensitive tokens stored in Keychain (not UserDefaults or plain files)
-- [ ] No force-unwrapped URLs from dynamic input
-- [ ] Server error responses decoded and surfaced to users
-- [ ] Network.framework code configures TLS/trust explicitly and keeps deep pinning work in `swift-security`
-- [ ] `NetworkConnection<QUIC>` stream APIs are treated as async throwing
-- [ ] Ensure network response model types conform to Sendable; use @MainActor for UI-updating completion paths
+- ATS requires HTTPS by default. Leave it on.
+- ATS is policy of the URL Loading System. It governs URLSession, not
+  Network.framework connections; with Network.framework you configure TLS
+  and trust evaluation yourself.
+- A per-domain exception is the last resort, only for a third-party host
+  that cannot move to HTTPS. Exceptions need a written justification and
+  can draw extra App Review scrutiny.
+- `NSAllowsArbitraryLoads = true` does not belong in a production build
+  unless nothing narrower exists.
+- `NSAllowsLocalNetworking` is fine for talking to local devices (Bonjour,
+  IoT accessories).
+- Prefer declarative pinning with `NSPinnedDomains`. Hashing the raw bytes
+  from `SecKeyCopyExternalRepresentation` is not SPKI pinning; a correct pin
+  hashes the Subject Public Key Info. Trust code belongs to `swift-security`.
+
+## Common mistakes
+
+1. `URLSession.shared` where configuration matters. Build a session with
+   timeouts, caching and a delegate.
+2. Force-unwrapping `URL(string:)`. Handle `nil`, whether the string is
+   dynamic or a literal; a thrown `invalidURL` costs one line.
+3. Decoding big payloads on the main actor. The awaited call and the decode
+   stay off the main actor; hop to `@MainActor` only to publish UI state.
+4. Ignoring cancellation in paging, streaming and retry loops. Test
+   `Task.isCancelled` or use `try Task.checkCancellation()`, and start work
+   from SwiftUI `.task` so it is cancelled with the view.
+5. Adding Alamofire or Moya for what async URLSession already does. Keep
+   libraries for features the SDK lacks, such as image caching.
+6. Mocking URLSession in tests. Stub the transport with a `URLProtocol`
+   subclass or swap the client protocol for a double.
+7. `data(for:)` for large files. `download(for:)` avoids the memory spike.
+8. Starting requests in a view's `body` or `init`. Use `.task` or
+   `.task(id:)`.
+9. Pasting tokens into individual requests. Middleware centralises them and
+   makes refresh possible.
+10. Decoding before checking the status. A 200 with malformed JSON and a 500
+    with an error body need different handling.
+
+## Review checklist
+
+- [ ] Foreground work uses async/await; background sessions use tasks and delegates, not async conveniences
+- [ ] `.notConnectedToInternet`, `.timedOut` and `.cancelled` are handled
+- [ ] Requests are cancellable through `.task` or a stored `Task`
+- [ ] Auth headers come from middleware; tokens live in the Keychain, never UserDefaults or plain files
+- [ ] Status code checked before decoding; server error bodies decoded and shown
+- [ ] Large downloads use `download(for:)`
+- [ ] Networking and decoding run off `@MainActor`; only UI updates hop to main
+- [ ] Session has deliberate timeouts and caching and is injected, not `URLSession.shared`
+- [ ] Retry skips cancellation and 4xx other than 429
+- [ ] Paginators check cancellation between pages
+- [ ] No force-unwrapped URLs or casts
+- [ ] Network.framework code sets TLS and trust explicitly; pinning detail deferred to `swift-security`
+- [ ] `NetworkConnection<QUIC>` stream calls are awaited and can throw
+- [ ] Response models are `Sendable`; code that updates UI is `@MainActor`
 
 ## References
 
-- See [references/urlsession-patterns.md](references/urlsession-patterns.md) for complete API client
-  implementation, multipart uploads, download progress, URLProtocol
-  mocking, retry/backoff, certificate pinning, request logging, and
-  pagination implementations.
-- See [references/background-websocket.md](references/background-websocket.md) for background URLSession
-  configuration, background downloads/uploads, WebSocket patterns with
-  structured concurrency, and reconnection strategies.
-- See [references/lightweight-clients.md](references/lightweight-clients.md) for the lightweight closure-based
-  client pattern (struct of async closures, injected via init for testability
-  and preview support).
-- See [references/network-framework.md](references/network-framework.md) for Network.framework (NWConnection,
-  NWListener, NWBrowser, NWPathMonitor) and low-level TCP/UDP/WebSocket patterns.
-- See [references/file-storage-patterns.md](references/file-storage-patterns.md) for file system directory
-  selection, FileProtectionType, backup exclusion, and storage pressure handling.
+- [URLSession patterns](references/urlsession-patterns.md): full API client, request builder, multipart upload, download progress, cursor and offset pagination, URLProtocol mocking, retry with jitter, pinning guidance, request logging, caching, SSE, session factory.
+- [background and WebSocket guide](references/background-websocket.md): background session setup, background downloads and uploads, app delegate event handling, WebSocket with structured concurrency, reconnection, typed messages, auth.
+- [lightweight clients](references/lightweight-clients.md): struct-of-closures client injected through `init` for tests and previews.
+- [Network framework guide](references/network-framework.md): `NWConnection`, `NWListener`, `NWBrowser`, `NWPathMonitor`, raw TCP, UDP and WebSocket, iOS 26 `NetworkConnection`.
+- [file storage patterns](references/file-storage-patterns.md): directory choice, `FileProtectionType`, backup exclusion, low-storage handling.