docs(docs): correct and clarify the iOS integration guides [NT-3943]

[David Nalchevanidze (nalchevanidze)]

What

End-to-end accuracy and reader-experience pass over both iOS integration guides (NT-3943, sub-task of NT-3896).

knowledge:check and guides:check were already green before this branch, so none of these defects were mechanically detectable — they came out of a cold newcomer read plus claim-by-claim verification against the Swift source and the internal fact store.

Correctness

• Four snippets could not compile. OptimizedEntry argument order (both initializers declare dwellTimeMs before minVisibleRatio, and Swift enforces declaration order), the missing hasConsent(method:) label, and absent Combine / Contentful imports. The first two were inherited from prose shared with the Android guides, where both forms are legal Kotlin — Swift is the only target where they break.
• UIKit consent gap. The guide called StorageDefaults(consent: true) a "seed" and never stated that a configured value overrides a stored user choice on every launch. A reader carrying the quick-start config into an app that later collects consent got no warning. The SwiftUI guide already stated this correctly, so the two siblings disagreed.
• Seven contradicted behavioral claims corrected, including a false tree-wide tap opt-out (a descendant onTap re-enables tracking), background flush described as UIKit-only when the gate is canImport(UIKit), and a preview-panel claim that only holds for SwiftUI.
• Four facts the knowledge base already held but the guides omitted.

Reader path

• Both fetch sections described a CDA query in prose and contained no fetch code, despite that being their entire reader goal. They now carry real contentful.swift queries, verified member-by-member against the vendored checkout.
• Every entry example leads with Contentful.Entry; the still-supported dictionary overload keeps one sentence.
• The quick start named a clientId it never sourced — provenance is now inline where it is first needed.
• UIKit snippets are placeable in a real file (hosted #if DEBUG block, wrapped await, lock-example call site), the storyboard-rooted case has an injection path that does not crash, and the view-tracking example wires its disappear path.
• Missing Troubleshooting rows and undefined load-bearing terms added.

Validation

• pnpm guides:check — pass
• pnpm knowledge:check — pass (1417 pointers, 10 fact files)
• pnpm exec prettier --check — clean
• Guide headings are byte-identical to main, so every table-of-contents anchor and inbound deep link still resolves.

Swift snippets are symbol-verified against source, not compiler-verified — no Xcode run in this environment.

Open items (not in this PR)

• The from: "<version>" placeholder in both guides is unfixed, pending confirmation of the published optimization.swift tag naming and whether from: or exact: is correct for a prerelease.
• Whether import Contentful resolves in a consumer target declaring only ContentfulOptimization is unconfirmed; the new Troubleshooting row is worded to be correct either way.
• Raised for the core-analytics owners: shared/concepts.md says getFlag(name) tracks a flag-view exposure immediately, native/ios.md says only subscribing does. iOS getFlag bridges that same shared core, so one is wrong. If concepts.md governs, both guides advise a pattern that silently generates billable exposures — and the same advice propagates to every SDK guide bridging the core.
• Follow-up ticket candidates: OptimizationConfig.environment defaults to main while ContentfulHTTPPreviewClient.environment defaults to master; trackCurrentScreen is the guides' recommended screen API but is called by no reference implementation, so XCUITest cannot regress the documented path; and ViewTrackingController / TrackingMetadata accept only dictionaries, forcing UIKit apps to hand-encode a typed entry.

Deliberately unchanged: table-of-contents placement and Before you start ordering (archetype-wide, shared by all 10 integration guides), and credential links (that sentence is duplicated verbatim across 6 guides and is not a fragment, so it belongs to the parent ticket).

🤖 Generated with Claude Code