docs(docs): bootstrap iOS SDK guides through the docs pipeline#380
Merged
Conversation
Add native/ios.md, the verified fact base for the beta ContentfulOptimization Swift Package, feeding both iOS guides. The iOS SDK runs the shared CoreStateful runtime through a JavaScriptCore bridge, so behavioral facts anchor to the resolvable optimization-js-bridge/core-sdk/api-schemas keys and concept docs; Swift-only surface uses extern: pointers naming the exact Swift file+symbol, since knowledge:check cannot resolve Swift #symbol pointers (no package.json/src). Passes pnpm knowledge:check. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Two per-UI blueprints for the one iOS SDK. Both omit the personalization explainer's managed-fetch clause (iOS has no fetch-by-ID path) and prove "init + one accepted screen event" rather than an entry render, since an entry-render proof would force an app-specific Swift CDA fetch into the quick start. The UIKit blueprint splits the old four-feature tracking section into distinct sections and shows the SceneDelegate runtime root as a diff. Passes pnpm guides:check. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Review escalation: both iOS guides describe the preview panel's behavior when mounted without a PreviewContentfulClient, but the KB had no backing fact. Add the traced behavior (panel opens degraded: empty audience section, no set-override controls, override summaries fall back to raw ids), grounded in PreviewPanelContent.swift and the shared computePreviewModel bridge helper. Passes pnpm knowledge:check. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Rewrite both iOS integration guides to the current archetype from their new blueprints and the iOS knowledge base. Both gain the personalization explainer (managed-fetch clause omitted), two-milestone framing, and a prose "Before you start" replacing the old setup-inventory table. Quick starts now prove "init + one accepted screen event" (no app-specific fetch forced inline), with performable verification. UIKit additionally splits the old four-feature tracking section into distinct sections and shows the SceneDelegate root as a diff. Applies the three-role review: fixes the OptimizedEntry onTap baseline-vs-resolved mislabel, drops the untaught `page` from pre-consent blocked lists, corrects the `changes`/@published attribution, and makes the verify steps name a searchable log signature and a failure-branch diagnostic. Passes pnpm guides:check and knowledge:check. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Add the two iOS blueprints to the authoring index and note that the native iOS family is now covered (with the Swift extern:-pointer exception). Fold the durable rules the iOS review surfaced into the authoring checklist: native runtime roots (SceneDelegate/AppDelegate) shown as diffs, result-wrapper types glossed with ownership, published-vs-snapshot state attribution, no multi-####-feature mega-section, and verify steps that name a searchable log signature, wire a failure-branch diagnostic, and define the proof's load-bearing state word without implying server receipt. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Tim Beyer (TimBeyer)
requested review from
Lotfi Anwar L Arif (Lotfi-Arif),
Felipe Mamud (fmamud) and
Charles Hudson (phobetron)
as code owners
July 20, 2026 12:58
Charles Hudson (phobetron)
approved these changes
Jul 20, 2026
Charles Hudson (phobetron)
left a comment
Charles Hudson (phobetron)
left a comment
Collaborator
There was a problem hiding this comment.
Looks like a good direction here 😄
Tim Beyer (TimBeyer)
changed the title
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Rebuilds the iOS SwiftUI and UIKit integration guides through the current docs pipeline. They previously predated it — full guides with no knowledge base and no blueprints. This runs the bootstrap path end to end: comprehend source into the KB, author the editorial blueprints, reconcile the guide prose, then the three-role review with fixes funnelled back.
What's here (commit by commit)
feat(docs): bootstrap iOS SDK knowledge base— newnative/ios.md, the verified fact base for the betaContentfulOptimizationSwift Package, feeding both guides.feat(docs): add iOS SwiftUI and UIKit guide blueprints— one per-UI blueprint each (the two guides are two UI-layer integrations of the one SDK).fix(docs): record iOS preview-panel no-client degraded mode— a fact added from a review escalation so both guides' preview-panel claims are grounded in source.feat(docs): reconcile iOS SwiftUI and UIKit guides to the pipeline— both guides rewritten to the current archetype + review fixes.docs(docs): register iOS blueprints and funnel back review rules— authoring index + checklist updates.Key decisions (native SDK, different ecosystem)
knowledge:checkdiscovers SDK keys frompackages/**/package.json+ a siblingsrc/and resolves#symbolvia the TypeScript compiler. The iOS package is a Swift Package (nopackage.json/src), so there is noioskey and Swift symbols can't be machine-resolved. Swift-only facts useextern:pointers naming the exact file+symbol; behavior that actually runs in the shared JavaScriptCore bridge anchors to the resolvableoptimization-js-bridge/core-sdk/api-schemaskeys. This is the consciously-accepted native deferral.guides:check.## Required setupinventory tables with prose## Before you start; added the personalization explainer (managed-fetch clause omitted) and two-milestone framing; UIKit's four-feature mega-section split into distinct sections; theSceneDelegateruntime root is now shown as a diff.Review outcome (three roles, per guide)
OptimizedEntry.onTapreceives the baseline entry (not the resolved variant) — corrected the example; one behavioral gap escalated → KB fact added (commit 3).pagein pre-consent blocked lists, achanges/@Publishedattribution error, and made verify steps name a searchable log signature and a failure-branch diagnostic.####-feature mega-section, and verify-step rules (searchable log token, failure diagnostic, honestly-scoped proof adjective).Validation
pnpm knowledge:check✓ — 881 source pointers across 9 fact files, noESCALATEmarkers.pnpm guides:check✓ — 8 blueprints, 114 planned sections, links and section/category structure valid.Not done: Swift snippets are verified against the types and the reference implementation for shape, but not compiled/run through Xcode/XCUITest.
🤖 Generated with Claude Code