A reference refresh should preserve provenance and separate catalog coverage from compiled examples. New documentation can change guidance without proving that an implementation works on the new SDK.

Upstream change → Source comparison → Guide update → Compile affected sample
  1. 1Upstream change
  2. 2Source comparison
  3. 3Guide update
  4. 4Compile affected sample

Work through the example

Track the source date and identify API claims that require the new toolchain. Keep old deployment targets in the verification matrix.

Start with a disposable branch and synthetic data. Write the expected outcome before changing the implementation, then keep the first failing result. This prevents a later repair from quietly redefining the task. The procedure below is grounded in the repository reference; its examples must still be checked against your project and installed toolchain.

Implementation reference

The following focused section is adapted from the maintained project guide. It preserves the source’s examples and limitations.

Pattern

Use a clone for offline work after installation. Search runs locally with Node and does not call an AI or make network requests:

node scripts/query-library.mjs search "Persistence" source
node scripts/query-library.mjs outline docs/frameworks/swiftdata.md
node scripts/query-library.mjs read samples/SkillPatterns/Sources/SkillPatterns/Persistence.swift 0 6000

search returns up to eight file paths, titles and sizes, without file bodies. outline returns headings with character offsets. read returns exact content, a content hash and nextOffset; continue from that offset until it is null when the complete source is needed. Offsets are JavaScript UTF-16 string indexes, not bytes. No excerpt is silently presented as a complete file.

The same library is bundled inside the knowledge MCP package:

  1. Call search_local_references with a feature/API query and kind: "source" for reusable code, or kind: "guide" for explanations.
  2. Use get_reference_outline to select a guide section.
  3. Call read_local_reference with its exact returned path and offset. The default body budget is 6,000 characters; the maximum is 16,000 per call. Follow nextOffset only if necessary.
  4. Read sibling package manifests, dependencies and tests before adapting a source file. Preserve error handling, actor isolation and availability requirements.
  5. Build and test the resulting app with the installed SDK. A source file being indexed does not prove it builds independently.

get_apple_technology now defaults to an overview with local guide/source routes. Request view: "full" only when the entire guide and topic map are needed. The repository's Markdown examples also contain explicitly labelled wrong patterns; retain their surrounding explanation and do not automatically extract every fenced block as production Swift.

Where the complete code lives

  • samples/SkillPatterns/: Swift package containing persistence, streams, routing, observation, composition and signal-processing implementations with tests.
  • samples/AppleRecipes/: original Apple API implementations with their own manifest, tests and build evidence. See its README for exact platform coverage.
  • templates/ios-app/: an app's screens, models, repositories and test starting points.
  • templates/common-patterns/: editable networking, persistence, authentication, design and navigation source; adaptation and app-level testing are required.
  • cli/src/: complete source of the app scaffolder.
  • mcp-server/src/: complete source of the analysis and local knowledge servers.

See docs/apple/local-library.md for the generated file inventory. The index contains metadata only. Content has one canonical source file; the MCP bundle stores identical content once by SHA-256. Plugin archives carry those same canonical files so they work without fetching individual guides.

Apple guidance and ownership

Original code in this repository is covered by the repository's MIT license, subject to any file-specific notices. Apple documentation links in the guides are attribution and freshness references. Apple SDK binaries, internal source and proprietary manuals are not relicensed as part of this project. Use the installed SDK and the linked official guidance for availability or behavior that changed after the snapshot.

Acceptance and failure review

Checkpoint What to inspect If it does not match
Upstream change Confirm the input and environment Preserve the failure and return to this step
Source comparison Inspect the intermediate artifact Preserve the failure and return to this step
Guide update Run the focused check Preserve the failure and return to this step
Compile affected sample Record the observed result Preserve the failure and return to this step

Ask the agent to explain the smallest change that resolves the observed mismatch. Keep unrelated refactors out of the repair. A change that makes a warning disappear is not enough if the behavior or ownership contract has changed. Re-run the same acceptance check so the before and after results are comparable.

Evidence and limits

A successful index refresh is not a GA compatibility test.

This is an educational guide. Its presence in the series does not certify a completed client-specific lab. The series evidence record separates executed checks from exercises and blocked environments.

Inspect the source used in this lesson.

What to do next

Next: Planning a safe Swift 6 and iOS 27 migration