@mmerterden/multi-agent-pipeline 20.6.0 → 20.8.0

package/pipeline/skills/shared/external/core-nfc/SKILL.md

@@ -1,486 +1,412 @@
 ---
 name: core-nfc
-description: "Read and write NFC tags using CoreNFC. Use when scanning NDEF tags, reading ISO7816/ISO15693/FeliCa/MIFARE tags, writing NDEF messages, handling NFC session lifecycle, configuring NFC entitlements, or implementing background tag reading in iOS apps."
+description: "Core NFC on iPhone: reading and writing NDEF tags, ISO7816, ISO15693, FeliCa and MIFARE access, reader session lifecycle, NFC entitlement and Info.plist setup, background tag reading. Use when adding or reviewing NFC tag scanning or writing."
 metadata:
-  source: "dpearson2699/swift-ios-skills (PolyForm Perimeter 1.0.0)"
+  source: multi-agent-pipeline
 ---
 
-# CoreNFC
-
-Read and write NFC tags on iPhone using the CoreNFC framework. Covers NDEF
-reader sessions, tag reader sessions, NDEF message construction, entitlements,
-and background tag reading. Targets Swift 6.3 / iOS 26+.
-
-## Contents
-
-- [Setup](#setup)
-- [NDEF Reader Session](#ndef-reader-session)
-- [Tag Reader Session](#tag-reader-session)
-- [Writing NDEF Messages](#writing-ndef-messages)
-- [NDEF Payload Types](#ndef-payload-types)
-- [Background Tag Reading](#background-tag-reading)
-- [Common Mistakes](#common-mistakes)
-- [Review Checklist](#review-checklist)
-- [References](#references)
-
-## Setup
-
-### Project Configuration
-
-1. Add the **Near Field Communication Tag Reading** capability in Xcode
-2. Add `NFCReaderUsageDescription` to Info.plist with a user-facing reason string
-3. Add the `com.apple.developer.nfc.readersession.formats` entitlement with the current `TAG` value; do not add legacy `NDEF`
-4. For ISO 7816 tags, add supported application identifiers to `com.apple.developer.nfc.readersession.iso7816.select-identifiers` in Info.plist
-5. For FeliCa tags, add supported system codes to `com.apple.developer.nfc.readersession.felica.systemcodes`; do not use wildcard system codes
-
-### Device Requirements
+# Core NFC
+
+Core NFC lets an iPhone app read tags, write NDEF data and talk to a tag in its
+own protocol. Everything happens inside a short-lived reader session that the
+system presents as a scan sheet. Code here assumes Swift 6.3 with an iOS 26
+deployment target, and only iPhone hardware reads tags.
+
+## Project setup
+
+1. In Signing & Capabilities, add **Near Field Communication Tag Reading**.
+2. Put a sentence the user will read into `NFCReaderUsageDescription` in Info.plist.
+   An empty value is a review problem.
+3. The capability writes the reader-session formats entitlement
+   (`...nfc.readersession.formats`) with the value `TAG`. Older samples add
+   `NDEF` as well; leave that out.
+4. For ISO 7816 cards, list every application identifier the app will select
+   in the Info.plist select-identifiers array (shown below).
+5. For FeliCa, list each system code in the Info.plist systemcodes array.
+   Wildcard codes are not accepted.
+
+```xml
+<key>NFCReaderUsageDescription</key>
+<string>Scanning lets you check in to the gym by tapping your member card.</string>
+<key>com.apple.developer.nfc.readersession.iso7816.select-identifiers</key>
+<array>
+    <string>F0010203040506</string>
+</array>
+<key>com.apple.developer.nfc.readersession.felica.systemcodes</key>
+<array>
+    <string>12FC</string>
+</array>
+```
 
-NFC reading requires iPhone 7 or later. Always check for reader session
-availability before creating NFC UI or sessions. Use the concrete reader
-session type you are about to create.
+### Hardware and availability
 
-```swift
-import CoreNFC
+Tag reading needs an iPhone 7 or newer. Before showing any NFC button or
+creating a session, ask the session class you intend to use, for example
+`NFCNDEFReaderSession.readingAvailable` or `NFCTagReaderSession.readingAvailable`.
+`false` means the device lacks the hardware or NFC is restricted, so hide or
+disable the feature instead of starting a session that will fail.
 
-guard NFCNDEFReaderSession.readingAvailable else {
-    // Device does not support NFC or feature is restricted
-    showUnsupportedMessage()
-    return
-}
-```
-
-### Key Types
+### Types you will meet
 
 | Type | Role |
-|---|---|
-| `NFCNDEFReaderSession` | Scans for NDEF-formatted tags |
-| `NFCTagReaderSession` | Scans for ISO7816, ISO15693, FeliCa, MIFARE tags |
-| `NFCNDEFMessage` | Collection of NDEF payload records |
-| `NFCNDEFPayload` | Single record within an NDEF message |
-| `NFCNDEFTag` | Protocol for interacting with an NDEF-capable tag |
+|------|------|
+| `NFCNDEFReaderSession` | Session that scans NDEF-formatted tags |
+| `NFCTagReaderSession` | Session with native access to ISO7816, ISO15693, FeliCa and MIFARE tags |
+| `NFCNDEFMessage` | An NDEF message: an ordered list of records |
+| `NFCNDEFPayload` | A single NDEF record |
+| `NFCNDEFTag` | Protocol adopted by tags that can hold NDEF data |
 
-## NDEF Reader Session
+## Reading NDEF data
 
-Use `NFCNDEFReaderSession` to read NDEF-formatted data from tags. This is the
-simplest path for reading standard tag content like URLs, text, and MIME data.
+The NDEF session is the shortest path when all you need is a URL, some text or
+a MIME blob.
 
 ```swift
 import CoreNFC
 
-final class NDEFReader: NSObject, NFCNDEFReaderSessionDelegate {
+final class BadgeReader: NSObject, NFCNDEFReaderSessionDelegate {
     private var session: NFCNDEFReaderSession?
 
-    func beginScanning() {
+    func scan() {
         guard NFCNDEFReaderSession.readingAvailable else { return }
-
         session = NFCNDEFReaderSession(
             delegate: self,
             queue: nil,
             invalidateAfterFirstRead: false
         )
-        session?.alertMessage = "Hold your iPhone near an NFC tag."
+        session?.alertMessage = "Hold the top of your iPhone near the badge."
         session?.begin()
     }
 
-    // MARK: - NFCNDEFReaderSessionDelegate
+    func readerSessionDidBecomeActive(_ session: NFCNDEFReaderSession) {}
 
-    func readerSessionDidBecomeActive(_ session: NFCNDEFReaderSession) {
-        // Session is scanning
-    }
-
-    func readerSession(
-        _ session: NFCNDEFReaderSession,
-        didDetectNDEFs messages: [NFCNDEFMessage]
-    ) {
-        for message in messages {
+    func readerSession(_ reader: NFCNDEFReaderSession, didDetectNDEFs found: [NFCNDEFMessage]) {
+        for message in found {
             for record in message.records {
-                processRecord(record)
+                handle(record)
             }
         }
     }
 
-    func readerSession(
-        _ session: NFCNDEFReaderSession,
-        didInvalidateWithError error: Error
-    ) {
-        let nfcError = error as? NFCReaderError
-        if nfcError?.code != .readerSessionInvalidationErrorFirstNDEFTagRead,
-           nfcError?.code != .readerSessionInvalidationErrorUserCanceled {
-            print("Session invalidated: \(error.localizedDescription)")
+    func readerSession(_ reader: NFCNDEFReaderSession, didInvalidateWithError error: any Error) {
+        if let nfcError = error as? NFCReaderError,
+           nfcError.code == .readerSessionInvalidationErrorFirstNDEFTagRead
+            || nfcError.code == .readerSessionInvalidationErrorUserCanceled {
+            // Normal end of a scan, not a failure.
+        } else {
+            report(error)
         }
         self.session = nil
     }
+
+    private func handle(_ record: NFCNDEFPayload) {}
+    private func report(_ error: Error) {}
 }
 ```
 
-### Reading with Tag Connection
+The first-read and user-cancel codes are ordinary endings. Only other codes
+deserve an alert, and the session reference is cleared in every case.
+
+### Connecting to the tag
 
-For read-write operations, use the tag-detection delegate method to connect
-to individual tags:
+To read and then write, or to inspect capacity, implement
+`readerSession(_:didDetect:)` with `[any NFCNDEFTag]`. When that method exists,
+the system calls it instead of `didDetectNDEFs`.
 
 ```swift
-func readerSession(
-    _ session: NFCNDEFReaderSession,
-    didDetect tags: [any NFCNDEFTag]
-) {
-    guard let tag = tags.first else {
-        session.restartPolling()
+func readerSession(_ reader: NFCNDEFReaderSession, didDetect found: [any NFCNDEFTag]) {
+    if found.count > 1 {
+        retryAfterMultipleTags(reader)
         return
     }
-
-    session.connect(to: tag) { error in
-        if let error {
-            session.invalidate(errorMessage: "Connection failed: \(error)")
-            return
-        }
-
-        tag.queryNDEFStatus { status, capacity, error in
-            guard error == nil else {
-                session.invalidate(errorMessage: "Query failed.")
-                return
-            }
-
+    guard let first = found.first else {
+        reader.restartPolling()
+        return
+    }
+    nonisolated(unsafe) let reader = reader
+    nonisolated(unsafe) let tag = first
+    Task {
+        do {
+            try await reader.connect(to: tag)
+            let (status, _) = try await tag.queryNDEFStatus()
             switch status {
             case .notSupported:
-                session.invalidate(errorMessage: "Tag is not NDEF compliant.")
-            case .readOnly:
-                tag.readNDEF { message, error in
-                    if let message {
-                        self.processMessage(message)
-                    }
-                    session.invalidate()
-                }
-            case .readWrite:
-                tag.readNDEF { message, error in
-                    if let message {
-                        self.processMessage(message)
-                    }
-                    session.alertMessage = "Tag read successfully."
-                    session.invalidate()
-                }
+                reader.invalidate(errorMessage: "No NDEF support on this tag.")
+            case .readOnly, .readWrite:
+                let badge = try await tag.readNDEF()
+                reader.alertMessage = "Badge read: \(badge.records.count) records."
+                reader.invalidate()
             @unknown default:
-                session.invalidate()
+                reader.invalidate(errorMessage: "Unexpected tag status.")
             }
+        } catch {
+            reader.invalidate(errorMessage: "Could not read the tag: \(error.localizedDescription)")
         }
     }
 }
 ```
 
-## Tag Reader Session
+Every tag call also has a completion-handler form. Those handlers are
+`@Sendable`, while sessions and tags are not `Sendable`, so capturing them there
+draws Swift 6 warnings. The `async` forms, awaited inside one `Task`, keep the
+steps in reading order, but the `Task` closure still captures the session and
+the tag. Swift 6 rejects that in its region-isolation pass ("passing closure as
+a 'sending' parameter risks causing data races"), so the callback hands them
+over as `nonisolated(unsafe)` copies. After starting the task the callback
+touches neither, which leaves the task as their only user.
+
+An empty array means nothing usable was found yet: `restartPolling()` keeps
+the sheet open and waits for the next tap.
+
+### More than one tag in the field
+
+Both session types can report several tags at once. Talking to one of them
+while another is in range is unreliable, so do not pick one at random. Tell the
+user to take the extra tags away, pause briefly so they can do it, then resume
+polling on the same session:
+
+```swift
+func retryAfterMultipleTags(_ session: NFCNDEFReaderSession) {
+    session.alertMessage = "More than one tag found. Remove the extras and try again."
+    nonisolated(unsafe) let session = session
+    Task {
+        try? await Task.sleep(for: .milliseconds(500))
+        session.restartPolling()
+    }
+}
+
+func retryAfterMultipleTags(_ session: NFCTagReaderSession) {
+    session.alertMessage = "More than one tag found. Remove the extras and try again."
+    nonisolated(unsafe) let session = session
+    Task {
+        try? await Task.sleep(for: .milliseconds(500))
+        session.restartPolling()
+    }
+}
+```
+
+`restartPolling()` is declared separately on each session class rather than on
+the shared base, hence the two overloads. A zero-length array gets the plain
+`restartPolling()` call without the message.
+
+## Native tag access
+
+`NFCTagReaderSession` exposes each tag family in its own protocol: ISO 7816,
+ISO 15693, FeliCa and MIFARE. Pick polling options to match the tags you expect:
 
-Use `NFCTagReaderSession` when you need direct access to the native tag
-protocol (ISO 7816, ISO 15693, FeliCa, or MIFARE).
+| Polling option | Finds |
+|----------------|-------|
+| `.iso14443` | ISO 7816 compatible cards and MIFARE |
+| `.iso15693` | ISO 15693 vicinity tags |
+| `.iso18092` | FeliCa |
 
-Polling options are protocol-specific: `.iso14443` detects ISO
-7816-compatible and MIFARE tags, `.iso15693` detects ISO 15693 tags, and
-`.iso18092` detects FeliCa tags. Do not use `NFCTagReaderSession` for
-payment-related AIDs; Apple documents `NFCPaymentTagReaderSession` for
-eligible EU payment use cases.
+Payment application identifiers are off limits for this session. For eligible
+payment use cases in the EU, Apple documents a separate
+`NFCPaymentTagReaderSession`.
 
 ```swift
-final class TagReader: NSObject, NFCTagReaderSessionDelegate {
+final class CardReader: NSObject, NFCTagReaderSessionDelegate {
     private var session: NFCTagReaderSession?
 
-    func beginScanning() {
+    func scan() {
         guard NFCTagReaderSession.readingAvailable else { return }
-
-        session = NFCTagReaderSession(
-            pollingOption: [.iso14443, .iso15693, .iso18092],
-            delegate: self,
-            queue: nil
-        )
-        session?.alertMessage = "Hold your iPhone near a tag."
+        session = NFCTagReaderSession(pollingOption: [.iso14443, .iso15693], delegate: self, queue: nil)
+        session?.alertMessage = "Hold your transit card near the phone."
         session?.begin()
     }
 
-    func tagReaderSessionDidBecomeActive(
-        _ session: NFCTagReaderSession
-    ) { }
-
-    func tagReaderSession(
-        _ session: NFCTagReaderSession,
-        didDetect tags: [NFCTag]
-    ) {
-        guard let tag = tags.first else { return }
-
-        session.connect(to: tag) { error in
-            guard error == nil else {
-                session.invalidate(
-                    errorMessage: "Connection failed."
-                )
+    func tagReaderSessionDidBecomeActive(_ session: NFCTagReaderSession) {}
+
+    func tagReaderSession(_ reader: NFCTagReaderSession, didDetect found: [NFCTag]) {
+        if found.count > 1 {
+            retryAfterMultipleTags(reader)
+            return
+        }
+        guard !found.isEmpty else {
+            reader.restartPolling()
+            return
+        }
+        nonisolated(unsafe) let reader = reader
+        nonisolated(unsafe) let tags = found
+        Task {
+            let tag = tags[0]
+            do {
+                try await reader.connect(to: tag)
+            } catch {
+                reader.invalidate(errorMessage: error.localizedDescription)
                 return
             }
-
             switch tag {
-            case .iso7816(let iso7816Tag):
-                self.readISO7816(tag: iso7816Tag, session: session)
-            case .miFare(let miFareTag):
-                self.readMiFare(tag: miFareTag, session: session)
-            case .iso15693(let iso15693Tag):
-                self.readISO15693(tag: iso15693Tag, session: session)
-            case .feliCa(let feliCaTag):
-                self.readFeliCa(tag: feliCaTag, session: session)
-            @unknown default:
-                session.invalidate(errorMessage: "Unsupported tag type.")
+            case .iso7816(let card): await select(card, in: reader)
+            case .miFare(let chip): await inspect(chip, in: reader)
+            case .iso15693(let label): await readBlocks(label, in: reader)
+            case .feliCa(let card): await readSystemCodes(card, in: reader)
+            @unknown default: reader.invalidate(errorMessage: "This tag type is not handled.")
             }
         }
     }
 
-    func tagReaderSession(
-        _ session: NFCTagReaderSession,
-        didInvalidateWithError error: Error
-    ) {
-        self.session = nil
+    func tagReaderSession(_ reader: NFCTagReaderSession, didInvalidateWithError error: any Error) {
+        session = nil
     }
 }
 ```
 
-## Writing NDEF Messages
+The task receives the whole `tags` array rather than a single `NFCTag`: with
+the enum value itself as the `nonisolated(unsafe)` copy, Swift 6.3 still
+rejects the capture. Always connect before sending any command. The `select`, `inspect`,
+`readBlocks` and `readSystemCodes` helpers stand for per-family code (APDUs,
+block reads, MIFARE and FeliCa calls), which is written out in the
+[patterns reference](references/nfc-patterns.md).
 
-Write NDEF data to a connected tag. Always check `readWrite` status first.
+## Writing NDEF
+
+Query the status first. Only `.readWrite` tags accept a write; anything else
+ends the session with a clear message.
 
 ```swift
-func writeToTag(
-    tag: any NFCNDEFTag,
-    session: NFCNDEFReaderSession,
-    url: URL
-) {
-    tag.queryNDEFStatus { status, capacity, error in
+func store(_ link: URL, on tag: any NFCNDEFTag, session: NFCNDEFReaderSession) async {
+    do {
+        let (status, _) = try await tag.queryNDEFStatus()
         guard status == .readWrite else {
-            session.invalidate(errorMessage: "Tag is read-only.")
+            session.invalidate(errorMessage: "This tag is read-only.")
             return
         }
-
-        guard let payload = NFCNDEFPayload.wellKnownTypeURIPayload(
-            url: url
-        ) else {
-            session.invalidate(errorMessage: "Invalid URL.")
+        guard let record = NFCNDEFPayload.wellKnownTypeURIPayload(url: link) else {
+            session.invalidate(errorMessage: "Could not encode the link.")
             return
         }
-
-        let message = NFCNDEFMessage(records: [payload])
-
-        tag.writeNDEF(message) { error in
-            if let error {
-                session.invalidate(
-                    errorMessage: "Write failed: \(error.localizedDescription)"
-                )
-            } else {
-                session.alertMessage = "Tag written successfully."
-                session.invalidate()
-            }
-        }
+        try await tag.writeNDEF(NFCNDEFMessage(records: [record]))
+        session.alertMessage = "Tag updated."
+        session.invalidate()
+    } catch {
+        session.invalidate(errorMessage: "Could not write: \(error.localizedDescription)")
     }
 }
 ```
 
-## NDEF Payload Types
-
-### Creating Common Payloads
+Check capacity against the message size before large writes; see the reference
+file for the comparison and for permanent locking.
 
-```swift
-// URL payload
-let urlPayload = NFCNDEFPayload.wellKnownTypeURIPayload(
-    url: URL(string: "https://example.com")!
-)
+## Building and parsing payloads
 
-// Text payload
-let textPayload = NFCNDEFPayload.wellKnownTypeTextPayload(
-    string: "Hello NFC",
-    locale: Locale(identifier: "en")
-)
+| Record | Factory |
+|--------|---------|
+| URI | `NFCNDEFPayload.wellKnownTypeURIPayload(url:)` (optional result) |
+| Text | `NFCNDEFPayload.wellKnownTypeTextPayload(string:locale:)` |
+| App data | `NFCNDEFPayload(format: .nfcExternal, type:identifier:payload:)` with a `domain:type` type string |
 
-// Custom payload
-let customPayload = NFCNDEFPayload(
+```swift
+let config = NFCNDEFPayload(
     format: .nfcExternal,
-    type: "com.example:mytype".data(using: .utf8)!,
+    type: Data("example.com:shelf".utf8),
     identifier: Data(),
-    payload: "custom-data".data(using: .utf8)!
+    payload: Data(#"{"aisle":7}"#.utf8)
 )
 ```
 
-### Parsing Payload Content
+When reading, branch on `typeNameFormat`:
 
 ```swift
-func processRecord(_ record: NFCNDEFPayload) {
+func describe(_ record: NFCNDEFPayload) -> String? {
     switch record.typeNameFormat {
     case .nfcWellKnown:
-        if let url = record.wellKnownTypeURIPayload() {
-            print("URL: \(url)")
-        } else if let (text, locale) = record.wellKnownTypeTextPayload() {
-            print("Text (\(locale)): \(text)")
-        }
+        if let url = record.wellKnownTypeURIPayload() { return url.absoluteString }
+        let (text, locale) = record.wellKnownTypeTextPayload()
+        return text.map { "\($0) [\(locale?.identifier ?? "?")]" }
     case .absoluteURI:
-        if let uri = String(data: record.payload, encoding: .utf8) {
-            print("Absolute URI: \(uri)")
-        }
+        return utf8(record.payload)
     case .media:
-        let mimeType = String(data: record.type, encoding: .utf8) ?? ""
-        print("MIME type: \(mimeType), size: \(record.payload.count)")
+        return "\(utf8(record.type) ?? "unknown"), \(record.payload.count) bytes"
     case .nfcExternal:
-        let type = String(data: record.type, encoding: .utf8) ?? ""
-        print("External type: \(type)")
+        return utf8(record.type)
     case .empty, .unknown, .unchanged:
-        break
+        return nil
     @unknown default:
-        break
-    }
-}
-```
-
-## Background Tag Reading
-
-On iPhone XS and later, iOS can read NFC tags in the background without
-opening your app. The NDEF message must contain a URI record
-(`typeNameFormat == .nfcWellKnown`, type `U`). If there are multiple URI
-records, the system uses the first one.
-
-For app-specific routing, write a universal link to the tag and configure the
-Associated Domains capability for that domain. Background tag reading also
-supports specific system URL schemes such as web, email, SMS, telephone,
-FaceTime, Maps, and HomeKit setup. It does not support custom URL schemes, and
-the system does not route by bundle ID or arbitrary NDEF content type.
-
-When a user taps a compatible tag, iOS displays a notification that opens
-your app. Handle the tag data via `NSUserActivity`:
-
-```swift
-func scene(
-    _ scene: UIScene,
-    continue userActivity: NSUserActivity
-) {
-    guard userActivity.activityType ==
-        NSUserActivityTypeBrowsingWeb else { return }
-
-    let message = userActivity.ndefMessagePayload
-    guard message.records.first?.typeNameFormat != .empty else { return }
-
-    for record in message.records {
-        processRecord(record)
+        return nil
     }
 }
-```
-
-## Common Mistakes
-
-### DON'T: Use stale or missing NFC entitlements
-
-Without the `com.apple.developer.nfc.readersession.formats` entitlement,
-reader sessions cannot access NFC hardware. Use the current `TAG` value for
-Core NFC reader sessions; do not copy older examples that add `NDEF`.
-
-### DON'T: Skip the readingAvailable check
-
-Creating an NFC session on an unsupported or restricted device fails before
-the scan UI can do useful work.
-
-Check `NFCNDEFReaderSession.readingAvailable` or
-`NFCTagReaderSession.readingAvailable` before creating the matching session.
-
-### DON'T: Ignore session invalidation errors
-
-The session invalidates for multiple reasons. Distinguishing user cancellation
-from real errors prevents false error alerts.
-
-```swift
-// WRONG -- shows error when user cancels
-func readerSession(
-    _ session: NFCNDEFReaderSession,
-    didInvalidateWithError error: Error
-) {
-    showAlert("NFC Error: \(error.localizedDescription)")
-}
 
-// CORRECT -- filter expected invalidation reasons
-func readerSession(
-    _ session: NFCNDEFReaderSession,
-    didInvalidateWithError error: Error
-) {
-    let nfcError = error as? NFCReaderError
-    switch nfcError?.code {
-    case .readerSessionInvalidationErrorUserCanceled,
-         .readerSessionInvalidationErrorFirstNDEFTagRead:
-        break  // Normal termination
-    default:
-        showAlert("NFC Error: \(error.localizedDescription)")
-    }
-    self.session = nil
-}
+func utf8(_ bytes: Data) -> String? { String(bytes: bytes, encoding: .utf8) }
 ```
 
-### DON'T: Hold a strong reference to a stale session
+## Background tag reading
 
-Once a session is invalidated, it cannot be restarted. Nil out your reference
-and create a new session for the next scan.
+iPhone XS and newer read tags without the app open. The rules:
 
-```swift
-// WRONG -- reusing invalidated session
-func scanAgain() {
-    session?.begin()  // Does nothing, session is dead
-}
-
-// CORRECT -- create a new session
-func scanAgain() {
-    session = NFCNDEFReaderSession(
-        delegate: self, queue: nil, invalidateAfterFirstRead: false
-    )
-    session?.begin()
-}
-```
+- One record has to be a well-known URI record: `typeNameFormat` equal to
+  `.nfcWellKnown` and a record type of `U`. If there are several URI records, the first one wins.
+- To route to your app, write a universal link and set up Associated Domains
+  for that domain.
+- System schemes also work: web, mail, SMS, phone, FaceTime, Maps and HomeKit
+  setup.
+- Custom URL schemes do nothing here. There is no routing by bundle identifier
+  or by arbitrary NDEF content type.
 
-### DON'T: Write without checking tag status
-
-Writing to a read-only tag silently fails or produces confusing errors.
+A matching tag posts a notification; tapping it launches the app with a
+browsing-web activity:
 
 ```swift
-// WRONG -- writes without checking status
-tag.writeNDEF(message) { error in
-    // May fail on read-only tags
-}
-
-// CORRECT -- check status first
-tag.queryNDEFStatus { status, capacity, error in
-    guard status == .readWrite else {
-        session.invalidate(errorMessage: "Tag is read-only.")
-        return
-    }
-    tag.writeNDEF(message) { error in
-        // Handle result
+func scene(_ scene: UIScene, continue activity: NSUserActivity) {
+    guard activity.activityType == NSUserActivityTypeBrowsingWeb else { return }
+    let message = activity.ndefMessagePayload
+    guard let first = message.records.first, first.typeNameFormat != .empty else { return }
+    for record in message.records {
+        route(record)
     }
 }
 ```
 
-## Review Checklist
-
-- [ ] NFC capability added in Signing & Capabilities
-- [ ] `NFCReaderUsageDescription` set in Info.plist
-- [ ] `com.apple.developer.nfc.readersession.formats` entitlement uses `TAG`, not legacy `NDEF`
-- [ ] `NFCNDEFReaderSession.readingAvailable` or `NFCTagReaderSession.readingAvailable` checked before creating sessions
-- [ ] Session delegate set before calling `begin()`
-- [ ] Session reference set to nil after invalidation
-- [ ] `didInvalidateWithError` distinguishes user cancellation from actual errors
-- [ ] NDEF status queried before write operations
-- [ ] Tag capacity checked before writing large messages
-- [ ] ISO 7816 application identifiers listed in Info.plist if using `NFCTagReaderSession`
-- [ ] FeliCa system codes listed in Info.plist when polling `.iso18092`
-- [ ] Background tag reading uses a URI NDEF record and universal links or supported system URL schemes
-- [ ] Custom URL schemes, bundle IDs, or arbitrary NDEF content types are not used for background routing
-- [ ] Payment-related AIDs are routed away from `NFCTagReaderSession`
-- [ ] Only one reader session active at a time
+## Mistakes that keep coming back
+
+- **Wrong or missing formats entitlement.** Without it the session cannot reach
+  the NFC hardware. Use `TAG`; drop copied `NDEF` values.
+- **No `readingAvailable` check.** Where NFC is missing or switched off by
+  policy, session creation fails before any scan sheet appears.
+- **Every invalidation treated as an error.** Cancel and first-read are normal;
+  alerting on them trains users to ignore alerts.
+- **Reusing a dead session.** An invalidated session cannot restart and
+  `begin()` on it does nothing. Clear the reference and create a new one.
+- **Writing blind.** Without a status query, writes to read-only tags fail in
+  confusing ways.
+- **Answering the first of several tags.** Ask the user to remove the extras
+  and restart polling.
+
+## Review checklist
+
+- [ ] NFC Tag Reading capability is on
+- [ ] `NFCReaderUsageDescription` has a real sentence
+- [ ] Formats entitlement is `TAG`, with no `NDEF`
+- [ ] `readingAvailable` is checked on the same session class that is created
+- [ ] Delegate is supplied before `begin()`
+- [ ] Session reference is cleared after invalidation
+- [ ] `didInvalidateWithError` separates cancel and first-read from real errors
+- [ ] Multiple detected tags lead to a remove-extras message and `restartPolling()`
+- [ ] NDEF status is queried before any write
+- [ ] Capacity is compared with message length before large writes
+- [ ] ISO 7816 AIDs are listed when `NFCTagReaderSession` selects applications
+- [ ] FeliCa system codes are listed when polling `.iso18092`
+- [ ] Background tags carry a URI record with a universal link or supported system scheme
+- [ ] No custom schemes, bundle IDs or content types relied on for background routing
+- [ ] Payment AIDs are kept away from `NFCTagReaderSession`
+- [ ] Only one reader session runs at a time
 
 ## References
 
-- Extended patterns (ISO 7816 commands, multi-tag scanning, NDEF locking): [references/nfc-patterns.md](references/nfc-patterns.md)
-- [Core NFC framework](https://sosumi.ai/documentation/corenfc)
-- [NFCNDEFReaderSession](https://sosumi.ai/documentation/corenfc/nfcndefreadersession)
-- [NFCTagReaderSession](https://sosumi.ai/documentation/corenfc/nfctagreadersession)
-- [NFCNDEFMessage](https://sosumi.ai/documentation/corenfc/nfcndefmessage)
-- [NFCNDEFPayload](https://sosumi.ai/documentation/corenfc/nfcndefpayload)
-- [NFCNDEFTag](https://sosumi.ai/documentation/corenfc/nfcndeftag)
-- [NFCNDEFReaderSessionDelegate](https://sosumi.ai/documentation/corenfc/nfcndefreadersessiondelegate)
-- [NFCTagReaderSessionDelegate](https://sosumi.ai/documentation/corenfc/nfctagreadersessiondelegate)
-- [Building an NFC Tag-Reader App](https://sosumi.ai/documentation/corenfc/building_an_nfc_tag-reader_app)
-- [Adding Support for Background Tag Reading](https://sosumi.ai/documentation/corenfc/adding-support-for-background-tag-reading)
-- [Near Field Communication Tag Reader Session Formats Entitlement](https://sosumi.ai/documentation/bundleresources/entitlements/com.apple.developer.nfc.readersession.formats)
-- [ISO7816 application identifiers for NFC Tag Reader Session](https://sosumi.ai/documentation/bundleresources/entitlements/com.apple.developer.nfc.readersession.iso7816.select-identifiers)
-- [ISO18092 system codes for NFC Tag Reader Session](https://sosumi.ai/documentation/bundleresources/entitlements/com.apple.developer.nfc.readersession.felica.systemcodes)
+- [NFC patterns](references/nfc-patterns.md): ISO 7816 APDUs, ISO 15693
+  blocks, MIFARE and FeliCa commands, multi-tag handling, multi-record messages
+  and capacity, tag locking, a SwiftUI scanner, error codes
+- Apple documentation, all under developer.apple.com/documentation:
+  - [framework overview](https://developer.apple.com/documentation/corenfc)
+  - session classes: [NDEF](https://developer.apple.com/documentation/corenfc/nfcndefreadersession),
+    [tag](https://developer.apple.com/documentation/corenfc/nfctagreadersession)
+  - delegates: [NDEF](https://developer.apple.com/documentation/corenfc/nfcndefreadersessiondelegate),
+    [tag](https://developer.apple.com/documentation/corenfc/nfctagreadersessiondelegate)
+  - data types: [message](https://developer.apple.com/documentation/corenfc/nfcndefmessage),
+    [payload](https://developer.apple.com/documentation/corenfc/nfcndefpayload),
+    [NDEF tag protocol](https://developer.apple.com/documentation/corenfc/nfcndeftag)
+  - articles: [tag-reader sample app](https://developer.apple.com/documentation/corenfc/building-an-nfc-tag-reader-app),
+    [background reading](https://developer.apple.com/documentation/corenfc/adding-support-for-background-tag-reading)
+  - keys: [formats entitlement](https://developer.apple.com/documentation/bundleresources/entitlements/com.apple.developer.nfc.readersession.formats),
+    [ISO 7816 AIDs](https://developer.apple.com/documentation/bundleresources/information-property-list/com.apple.developer.nfc.readersession.iso7816.select-identifiers),
+    [FeliCa system codes](https://developer.apple.com/documentation/bundleresources/information-property-list/com.apple.developer.nfc.readersession.felica.systemcodes)