SwiftUI looks like it does 3D.

rotation3DEffect takes an axis, an anchor, an anchorZ, and a perspective parameter. projectionEffect takes a full ProjectionTransform, and ProjectionTransform can even be initialized directly from a CATransform3D. A custom GeometryEffect hands you the view’s size and lets you return any projection matrix you can compute. Pose one view with these and it looks convincingly, beautifully three-dimensional.

So build a cube. Six faces, one shared space, rotate the camera. That is the simplest possible 3D scene, and pure SwiftUI on iOS and macOS cannot build it. I tested this thesis rather than assuming it: I wrote the counterexample, rendered it headlessly, and inspected the images, and the rendering corrected two of my own claims along the way.

Let me say the finding precisely, because the imprecise version is wrong. Do not say “SwiftUI has no 3D.” Say:

SwiftUI’s iOS/macOS 3D is per-view projected 2D output composited by painter’s order. It has no shared-space, depth-sorted layer hierarchy.

SwiftUI genuinely has per-view 3D projection: one view, one card, one face rotates in space with real perspective. What it lacks is a shared 3D coordinate space across sibling views and a per-frame depth ordering inside it. And the missing piece has a name: it is exactly what Core Animation’s CATransformLayer exists to provide.

The smallest counterexample, pure SwiftUI, no bridge

Here is a self-contained SwiftUI cube. No UIKit, no AppKit, no Core Animation import. It uses only rotation3DEffect(perspective:), the real iOS/macOS 3D view effect. The faces are declared back-to-front for the rest pose, front face last so it paints on top when the cube faces you. That hand-sorted order is the whole point: SwiftUI never recomputes it as the cube rotates, so it is correct only at rest.

import SwiftUI

struct FlatSwiftUICube: View {
    @State private var yaw = 0.0
    @State private var pitch = 20.0
    private let side: CGFloat = 120

    var body: some View {
        VStack(spacing: 24) {
            ZStack {
                // Back-to-front for the rest pose: front (2) declared LAST so it wins at yaw 0.
                face(.yellow, "4", angle: .degrees(180), axis: (0, 1, 0)) // back
                face(.orange, "5", angle: .degrees(90),  axis: (1, 0, 0)) // top
                face(.purple, "6", angle: .degrees(-90), axis: (1, 0, 0)) // bottom
                face(.red,    "1", angle: .degrees(-90), axis: (0, 1, 0)) // left
                face(.green,  "3", angle: .degrees(90),  axis: (0, 1, 0)) // right
                face(.blue,   "2", angle: .degrees(0),   axis: (0, 1, 0)) // front
            }
            // Rotate the WHOLE assembly. There is no shared 3D space, so this is just one
            // more projection applied on top of the already-projected faces.
            .rotation3DEffect(.degrees(pitch), axis: (1, 0, 0), perspective: 0.5)
            .rotation3DEffect(.degrees(yaw),   axis: (0, 1, 0), perspective: 0.5)
            .frame(width: 260, height: 260)

            Slider(value: $yaw,   in: 0...360)
            Slider(value: $pitch, in: -90...90)
        }
        .padding()
    }

    private func face(_ color: Color, _ label: String,
                      angle: Angle, axis: (x: CGFloat, y: CGFloat, z: CGFloat)) -> some View {
        ZStack {
            RoundedRectangle(cornerRadius: 8).fill(color.opacity(0.55))
            RoundedRectangle(cornerRadius: 8).stroke(color, lineWidth: 2)
            Text(label).font(.title).bold().foregroundStyle(.white)
        }
        .frame(width: side, height: side)
        // anchorZ pivots the rotation half a side behind the face. It is the ONLY way to
        // fake shared-space placement on iOS/macOS, because there is no z-translation in a
        // shared 3D coordinate space (transform3DEffect is visionOS-only).
        .rotation3DEffect(angle, axis: axis, anchorZ: -side / 2, perspective: 0.5)
    }
}

I rendered this with ImageRenderer at pitch = 20 across a yaw sweep and inspected it image by image. The observations, rendered, not asserted:

• At yaw = 0, the rest pose: the blue front face reads on top and the assembly reads as “a cube facing you.” But look closer: it is a splayed frustum, not a closed cube. The sides fan outward, because the anchorZ pivot cannot push a face out along its normal in a shared space. The correct static shape is already out of reach. That is itself evidence for the thesis.

• At yaw = 120: the blue front face has turned to face away from the viewer, yet it still dominates the center, painted on top, its label mirrored. A real cube at this angle shows mostly side and back faces with the front occluded.

• At yaw = 180: the front face points fully away, so a depth-sorted cube shows the yellow back face. Instead the yellow face is completely hidden and the blue front face still fills the center, label reversed. This is the unambiguous failure: no depth sort, the declared-last face always wins.

An earlier draft of this analysis asserted the behavior from reasoning, and the render corrected it twice: my original face order buried the front face so the cube was wrong even at rest, and the “cube” at rest is really a frustum. The thesis survived both corrections and came out stronger, which is exactly why a thesis has to be tested.

The failure also fits in one automatable line: at yaw = 180 the center pixel of the SwiftUI render is blue, the wrong winner. Render the Core Animation cube at the matching pose and the center is the true back face. Same pose, opposite winner: painter’s order versus depth sort.

Here is the same failure live, in the pure SwiftUI macOS witness from the AppleCube repository:

What the APIs actually are, in Apple’s words

The decisive evidence is not the demo. It is the documentation, read carefully. Two phrases decide the thesis, and both appear verbatim in Apple’s docs.

Core Animation’s CATransformLayer is documented as the class for “true 3D layer hierarchies, rather than the flattened hierarchy rendering model used by other layer types”, and, unlike normal layers, transform layers “do not flatten their sublayers into the plane at Z=0”.

SwiftUI’s rotation3DEffect on iOS and macOS “renders a view’s content as if it’s rotated” in three dimensions. projectionEffect “applies a projection transformation to this view’s rendered output”.

As-if-rotated rendered output is a 2D projection. It is not membership in a shared 3D scene. The full API picture:

Read the bottom three rows again. The richer 3D view model exists. Apple built it, named it, shipped it, on visionOS, where the platform has a real depth model. On iOS and macOS those APIs are simply not offered. Nobody forgot 3D. The boundary is deliberate, which is what makes it worth studying.

The SwiftUI filter

So ask the question the way a SwiftUI architect would. Not “which Core Animation properties are missing?”, but:

Given the Core Animation layer model as input, what subset did SwiftUI admit into its value-based view model, under what names, and at what scope?

The answer is a filter, not a one-to-one wrapper. The input side is a persistent object graph: layers with bounds, position, zPosition, anchorPoint, anchorPointZ, a mutable transform, a parent sublayerTransform, a sublayers array, and compositor rules like depth sorting and doubleSided. The output side is SwiftUI’s view value: layout proposes a rectangle, modifiers derive another rendered result from it, the parent composites children in view order plus zIndex.

The filter rule:

SwiftUI admits only the pieces that can be expressed as value transforms of one view’s rendered rectangle. It does not admit API that turns a view subtree into a mutable layer object graph.

Run every relevant Core Animation input through that rule and you get exactly the API that shipped:

So yes, SwiftUI has anchors. The exact sentence matters: SwiftUI has transform anchors; it does not expose Core Animation’s layer anchor fields. anchor and anchorZ are not CALayer.anchorPoint and anchorPointZ under different names. They are filtered descendants of those ideas. SwiftUI kept the notion of a normalized pivot because it is useful inside a pure value transform, and rejected the durable layer-geometry object that would let a subtree behave like a mutable 3D model.

Why draw the line there? Because the filter is the price of SwiftUI’s core design. Views are values: body produces them, a long-lived dependency graph diffs them, and animatable attributes interpolate copies of their data, off the main thread for the built-in effects. Exposing sublayerTransform, CATransformLayer, or mutable layer geometry would let user code mutate an object graph underneath SwiftUI’s layout, diffing, identity, animation, and cross-platform rendering model. SwiftUI instead keeps the backing renderer private and offers value-level transformations. If I were designing SwiftUI, this is a coherent boundary and I would draw it too. It is also the scientific reason the cube proof fails in pure SwiftUI. Both facts are true at once.

The positive control: the cube that works

Claims need controls. The AppleCube repository keeps four executable targets, a positive and a negative witness on each platform:

The negative controls are deliberately pure: no UIViewRepresentable, no NSViewRepresentable, no hosted UIKit or AppKit, no Core Animation, no SceneKit, no RealityKit. Even the night-sky background respects the firewall: the layer demos drift their stars with CAEmitterLayer, while the SwiftUI demos draw theirs with Canvas and TimelineView, because borrowing CAEmitterLayer would quietly turn the negative control back into a Core Animation demo.

The positive construction is everything the filter rejected, used directly, and each step is precisely the thing SwiftUI cannot express:

1. One parent CATransformLayer holds the six faces as siblings in a single 3D coordinate space. Because it is a transform layer, the faces are not flattened to Z = 0.

2. Perspective lives on the parent, once, shared by every face. One camera for the whole object, which also means one shared vanishing point:

perspective.m34 = -1.0 / 500.0
transformedLayer.sublayerTransform = perspective

3. Each face is placed in true 3D by its own layer transform. The fold is a rotation per face, and the front face is a real CATransform3DMakeTranslation(0, 0, zWidth), a genuine +Z translation in the shared space. That z placement is exactly what anchorZ cannot fake, which is why the SwiftUI version is a frustum.

4. Rotating the whole object mutates the parent’s sublayerTransform. One rotation moves the entire shared space, all six faces together, and the renderer re-resolves occlusion from the shared geometry every frame. Back faces can even be culled with isDoubleSided = false, a compositor rule, not a content swap.

I walked through this construction step by step in Core Animation Layers forming a 3D cube; it comes straight from Apple’s 2011 session Core Animation Essentials, and it still works, character for character, fifteen years later.

Here are both positive witnesses recorded together, the AppKit and UIKit apps hosting the same layer scene at the same time, folding and rotating with correct occlusion at every angle:

And the macOS witness on its own:

This is not a novel reading of Core Animation. Nick Lockwood’s iOS Core Animation: Advanced Techniques describes the identical model and builds the identical six-face cube: any 3D surfaces in one scene must be siblings “because each parent flattens its children”, CATransformLayer “does not flatten its sublayers, so it can be used to construct a hierarchical 3D structure”, and the parent’s perspective transform means “the vanishing point is set as the center of the container layer, not set individually”. Apple’s documentation, the running code, and a standard text all name the same two ingredients: the single-camera sublayerTransform and the non-flattening container.

Core Animation is 2.5D, and that makes the finding sharper

The article should not overclaim in the other direction either. Core Animation is not a depth-buffered 3D engine. Its model is 2.5D: flat layer surfaces living in a 3D compositing space, with a compositor descended from the painter’s model. Four exact rules:

1. An ordinary CALayer flattens its subtree into one flat surface; a 3D transform then warps that surface as a projected quad.

2. sublayerTransform is the parent camera. It applies to sublayers only, never to the parent’s own content. This is where shared m34 perspective belongs.

3. CATransformLayer is the exception: a non-rendering container whose only job is to keep children unflattened, so their faces project independently in one shared space.

4. Depth is sorted, not buffered. Faces are ordered back-to-front in the shared space; there is no per-pixel z-buffer. Mutually intersecting quads are the hard case. A cube of non-intersecting faces is the clean case.

So the missing thing in SwiftUI is not “a 3D GPU”. The missing public primitive is the retained layer-compositor machinery: CATransformLayer, parent sublayerTransform, zPosition as layer-space ordering, and doubleSided as a compositor back-face rule.

There is one more witness worth naming. I have been building a clean-room reconstruction of Core Animation’s layer model, and it arrived at the same boundary from the other direction: to reproduce Core Animation’s cube it had to implement precisely these primitives, the non-flattening transform layer, the parent camera, the two-pivot face projection, the back-to-front depth sort, and back-face culling by projected winding. Its tests hold those behaviors against a live Core Animation rendering oracle, with one honestly open residual, an off-center multi-child seam measurement. A reconstruction that independently converges on the same four primitives is evidence that the boundary is real, not an artifact of one demo.

Card flips prove a different theorem

The classic GeometryEffect card flip, which I walked through in SwiftUILab’s Advanced Animations, is intentionally not one of the witnesses. The trick enters through an allowed opening in the filter: a GeometryEffect receives a CGSize and returns a ProjectionTransform, a pure transform of one rendered rectangle, which is exactly the abstraction SwiftUI permits. Deferring the front-to-back content swap until the card is edge-on makes one rectangle look two-sided, and the card is beautiful because a single rendered rectangle is precisely what SwiftUI is for.

But note what the swap is standing in for. In Core Animation, doubleSided defaults to true and setting it false culls a layer when it faces away from the camera, a compositor rule. The card trick has to swap content manually because no such rule exists at the SwiftUI view level. It adds no shared Z space, no depth sorting, no parent camera. A card asks whether one view can be projected. A cube asks whether six siblings can share a scene. Different theorem.

Proof status

Following the discipline from The SwiftUI Oracle, the claim is split into labeled evidence, because “it looks right” is not a result:

And the honest labeling that keeps all of this defensible:

• The AppleCube demo is labeled what it is: a UIKit/AppKit host with a Core Animation layer scene. It is not “pure SwiftUI 3D” and does not claim to be.

• The counterexample above is genuinely pure SwiftUI, and it is labeled as what it is: a SwiftUI cube that demonstrates the flattening limit, not a working cube.

• If you need a real cube inside a SwiftUI app on iOS or macOS today, the honest construction is a SwiftUI host wrapping the CATransformLayer scene through a representable, or SceneKit, or RealityKit. None of those is “pure SwiftUI 3D”.

Run it yourself

Everything is in the AppleCube repository, including the recording scenarios that drive the failure poses reproducibly:

xcodebuild \
  -project Cube3DCA/Cube3DCA.xcodeproj \
  -scheme SwiftUIFlatMobile \
  -configuration Debug \
  -destination 'platform=iOS Simulator,name=iPhone 17' \
  build

Swap the scheme for Cube3DMobile, Cube3DCAMac, or SwiftUIFlatMac for the other three witnesses.

In The Morlocks Built SwiftUI I argued that the foundation never left. This article is the constructive version of that argument, read off the API surface itself and then rendered to check. SwiftUI’s architects looked at the layer model, kept everything that could be expressed as a value transform of one rectangle, collapsed depth into draw order, and declined to expose the scene, then built the fuller 3D model where the platform demanded it, on visionOS. That decision is why your app animates smoothly without you ever thinking about the render loop. It is also why, when you finally need the cube on iOS or macOS, you will find it one hosting view below the boundary they drew.

On 30 June, at nine minutes past three in the afternoon, a machine at GitHub decided I was a machine. It locked my account. My repositories, my profile, my Pages, all of it went 404 to the world. Not deleted. I could still see everything from the inside. Just switched off, so that to everyone else I had simply never existed. No email. No warning. No reason. And I was asleep when it happened.

What it saw

I pulled my own security log before I got angry, because I wanted to be fair. I will not pretend the machine hallucinated. My tools had been busy: more than a thousand OAuth tokens minted and rotated, hundreds of repositories created and destroyed by automation running in my name. To an abuse detector, that is not a person. That is a bot.

Here is the part that still stings. I have never used GitHub Copilot. Not once. Yet two Copilot apps churned 963 of those tokens on their own, from January to June, an integration I never turned on, working under my name while I was somewhere else living my life. I did not use the feature. The feature used me. And then it got me flagged.

A door with no one behind it

To appeal, GitHub sends you to a screen that asks you to prove you are human. A captcha. It never loaded for me.

That is the whole thing in one picture. A red error saying it cannot verify me, and a green checkmark underneath saying I am verified. Both at once. No text ever arrived. No ticket ever opened. No person ever answered, because there is no person. It is machines all the way down.

I am not special. Michal Flaška lost around a thousand repositories exactly this way, pulled his logs like I pulled mine, and found the same culprit: “the bad actor didn’t delete anything. GitHub’s own automation did.” He waited forty days. Another developer gave up by day ten and left for Codeberg, where I am now. There are dozens of us saying the same three sentences. Same 404. Same silence. Same machine.

What I actually signed up for

I subscribed to a tool. Machines I would orchestrate, machines I would give orders to. Build this. Run that. Host my work. I never signed up to be judged by machines I do not command, machines that flag me, lock me, and shut a door in my face while no human watches. The only machines I ever agreed to work with are the ones that take my orders, never the ones that give them to me.

A multi-trillion-dollar company decided humans do not scale, and quietly removed them. What is left flagged me, gated me, ignored me, and a marketing page calls it support.

So keep it

GitHub, you do not have to restore my account. Please, don’t bother.

I care about code more than almost anything I make, and I cannot keep what I love in a place where no one like me is home. Thinking about you now makes me nauseous, and I do not need that in my life.

I took my work, and I left. I am not coming back.

And I did not just leave. I became a member of Codeberg e.V., the non-profit behind the place I moved to, where humans vote on its direction. A machine decided I did not belong at GitHub. At Codeberg, I have a vote.

Addendum, three hours later

I published this post, shared it in four places, and went about my morning. Three hours later, out of curiosity, I clicked the support link one more time.

The wall was gone.

No SMS screen. No captcha refusing to verify me. The support portal simply loaded and offered me two situations to choose from.

It walked me to a form titled “Reinstatement request.” One of its radio buttons reads, word for word: “I can login, but my profile and contributions aren’t visible to others.” My whole catastrophe, pre-printed as a checkbox. I was never an edge case. I was a category common enough to have its own form field.

The billing page, meanwhile, now tells me three things at once. A banner at the top asks me to please update my payment method. A toast announces my billing information was successfully updated. And a warning box below them both says I cannot update my billing information, because my account is flagged and ineligible for transactions. The machine orders the repair, reports the repair, and forbids the repair, in one screen.

I wrote in this post that the appeal only works when you are loud in public, and I hoped to be wrong about that. The door that stayed shut while I knocked for two days moved by itself the same morning people were reading about it. Draw your own conclusion about who it moves for.

I am a solo developer in Zagreb with a blog about running Swift everywhere, making Swift do anything, rebuilding Apple frameworks nobody asked me to rebuild. My megaphone is a paper cup. If the sound carried, it is because strangers passed it from hand to hand until someone with a real megaphone heard it.

To be clear about the score: I am still blocked. The noise did not open the door. It opened the waiting room. For everyone locked out this way without an audience, even the waiting room stays shut.

The form is there now. I did not ask them to open it.

Will I fill it in? I still do not know. There is exactly one reason to: if my account is ever deleted for good, my username becomes available, and whoever claims it inherits every old link to Cupertino. A stranger could stand at my old address, wearing my name, serving their code to people who trusted mine. So I may apply after all, not to return, but to hold the ground: one repository, Cupertino, kept as nothing but a redirect pointing home.

Everything else can go. My packages will drop off the Swift Package Index, which only indexes packages hosted on GitHub, and I have made my peace with that. None of them were essential to the community, so nothing of value is lost. I find no joy in seeing them tied to a place I left. They are already on Codeberg, whole. A listing is not a home.

Everything I make lives where a human answers the door.

Addendum, one day later

There is one more place where GitHub is required to tell the truth about what it did to me, and I went and looked.

Under the EU’s Digital Services Act, a platform that restricts you must hand you a statement of reasons, and must file that statement in the European Commission’s public DSA Transparency Database. Article 17 names the cases one by one: restricting the visibility of your content, suspending monetary payments, suspending the service, suspending your account. What happened to me on 30 June was all four at once. I never received a statement. So I checked whether they ever wrote one.

The database publishes complete daily dumps. I downloaded the three days around my lock and read every row, 66.7 million statements from every platform operating in Europe. My totals matched the Commission’s published counts exactly, so I know I missed nothing.

On 30 June, the day my account was locked at 15:09, GitHub filed nothing. Not about me, about anyone. On 1 July it filed 20,570 statements in a single batch, every one of them an account suspension for actions taken on 29 June, almost all for scams and fraud. On 2 July, nothing again. No statement covering any GitHub decision from 30 June exists in the database.

Then I stopped filtering by date and asked a wider question. In the entire history of the database, across everything GitHub has ever filed, the number of statements reporting a monetary restriction is zero. The number reporting a suspension of service is zero. GitHub Sponsors suspends payouts with every lock like mine, the law names that as a reportable restriction, and the count of times GitHub has reported one is zero. This is not a late batch. This is a category of decision that their reporting pipeline was never taught to mention.

Maybe a batch for 30 June still shows up in some later dump. It changes nothing. Article 17 is explicit about the moment: the statement of reasons is owed at the latest from the date the restriction is imposed, and it is owed to the person restricted. Not to a database, eventually. To me, then. On 30 June they took my visibility, my funding, my service, and my account in one stroke, and they told me nothing. Not that day, not since.

The violation was complete at 15:09 on 30 June, the moment they acted without informing me. Nothing GitHub files later can reach back and undo that.

One more field, and I will leave it with you. Every statement GitHub files carries a flag saying whether the decision was automated. All 20,570 say the same thing: not automated. Twenty thousand human decisions in one day, they tell the regulator???? I titled this post before I read their filings. To the Commission, GitHub reports a building full of humans. At the door where I knocked for two days, there was no one. Both cannot be true.

Short version: Cupertino’s working distribution home is now Codeberg.

If you installed Cupertino from the old GitHub tap, brew upgrade can tell you that everything is current while leaving you on 1.4.1. That is not the current working release. The current release is 1.4.2, and it lives in the new Codeberg tap.

Update an existing install

Run this exactly:

brew tap cupertinohq/tap https://codeberg.org/CupertinoHQ/homebrew-tap.git
brew fetch cupertinohq/tap/cupertino
brew uninstall mihaelamj/tap/cupertino || true
brew install cupertinohq/tap/cupertino
brew untap mihaelamj/tap || true
cupertino --version

Expected output:

1.4.2

Then check your databases:

cupertino doctor

If you need to download the databases again:

cupertino setup

Fresh install

For a new Homebrew install:

brew tap cupertinohq/tap https://codeberg.org/CupertinoHQ/homebrew-tap.git
brew install cupertinohq/tap/cupertino
cupertino setup

The explicit Codeberg URL matters. If you run only:

brew tap cupertinohq/tap

Homebrew assumes GitHub. That is not where the working tap lives.

How to tell if you are still on the old path

Run:

brew info cupertino

If you see this:

From: https://github.com/mihaelamj/homebrew-tap/...
Tap: mihaelamj/tap
stable 1.4.1

you are still looking at the old GitHub tap.

The working tap should resolve to:

From: https://codeberg.org/CupertinoHQ/homebrew-tap.git/Formula/cupertino.rb
Tap: cupertinohq/tap
stable 1.4.2

What changed in 1.4.2

This is a distribution hotfix, not a corpus rebuild.

• Source moved to codeberg.org/CupertinoHQ/cupertino

• Homebrew moved to codeberg.org/CupertinoHQ/homebrew-tap

• The Homebrew formula downloads the 1.4.2 binary from Codeberg packages

• cupertino setup downloads the database bundle from cupertino-assets.fly.dev

• The database bundle is still version 1.4.0

• The schema is unchanged

That means your existing v1.4.0 databases remain valid. If cupertino doctor says all checks passed, you do not need to download the databases again.

Why brew upgrade was confusing

Homebrew compares your installed formula against the tap it knows about. If your machine is still tapped to the old GitHub formula and that formula says 1.4.1, Homebrew can report “nothing to upgrade” even though the working Codeberg tap has 1.4.2.

The fix is not just brew upgrade. The fix is switching taps.

The old GitHub setup path is obsolete

The old GitHub release asset can return 404. Cupertino 1.4.2 no longer depends on that path for setup.

The current setup path is:

https://cupertino-assets.fly.dev/releases/v1.4.0/cupertino-databases-v1.4.0.zip
https://cupertino-assets.fly.dev/apple-constraints.json

I tested the new path end to end: Homebrew installs 1.4.2, cupertino setup downloads the bundle, the constraints sidecar downloads, and all 8 databases verify.

Source installs

If you build from source, clone the Codeberg repo:

git clone https://codeberg.org/CupertinoHQ/cupertino.git
cd cupertino

The old GitHub URLs should be treated as legacy references. Codeberg is the working home now.

In the last post I claimed I had measured SwiftUI until its behavior was predictable. This post is the receipts. It is for Swift developers, so it is mostly code: the test harness, the firewall that keeps it honest, and the differential tests that hold a from-scratch engine against the real framework. If you have ever wondered what it would take to prove you understand SwiftUI rather than assert it, this is one answer.

The engine is called PureView. It is a clean-room reimplementation of SwiftUI’s semantics: the attribute graph, identity, layout, animation, and lowering to a display list. It never imports SwiftUI. The proof that it is faithful is a separate test target that does import SwiftUI and compares the two, value for value.

What “oracle” means here

In testing, an oracle is the source of the correct answer: the thing that tells you whether a result is right. Our oracle is real SwiftUI itself. For any scene, we ask the real framework what it does, and that answer is the ground truth we grade the engine against. The engine is the work; SwiftUI is the answer key.

The firewall: the engine may never import SwiftUI

A measurement is worthless if the instrument can cheat. If the engine were allowed to call SwiftUI, any agreement would be suspect, because the engine could simply forward to the framework it claims to reproduce. So the engine is sealed off, and the seal is not a convention. It is a test that fails swift test if a UI-framework import ever appears in the engine sources.

@Suite("Engine import confinement")
struct EngineImportConfinementTests {
    @Test("Sources/PureView imports no UI framework")
    func engineImportsNoUIFramework() throws {
        let forbidden = ["SwiftUI", "UIKit", "AppKit", "WatchKit"]
        // #filePath = <root>/Tests/PureViewTests/<this file>; climb to <root>/Sources/PureView.
        let engineRoot = URL(filePath: #filePath)
            .deletingLastPathComponent() // PureViewTests
            .deletingLastPathComponent() // Tests
            .deletingLastPathComponent() // <root>
            .appending(path: "Sources/PureView")

        let fileManager = FileManager.default
        let enumerator = try #require(
            fileManager.enumerator(at: engineRoot, includingPropertiesForKeys: nil),
            "engine source root must exist at \(engineRoot.path)"
        )

        func importsForbidden(_ line: String) -> Bool {
            forbidden.contains { framework in
                line == "import \(framework)"
                    || line == "@testable import \(framework)"
                    || line.hasPrefix("import \(framework).")
            }
        }

        var offenders: [String] = []
        for case let url as URL in enumerator where url.pathExtension == "swift" {
            let source = try String(contentsOf: url, encoding: .utf8)
            for (index, line) in source.split(separator: "\n", omittingEmptySubsequences: false).enumerated() {
                let trimmed = line.trimmingCharacters(in: .whitespaces)
                if importsForbidden(trimmed) {
                    offenders.append("\(url.lastPathComponent):\(index + 1): \(trimmed)")
                }
            }
        }

        #expect(offenders.isEmpty, "engine must not import a UI framework, found: \(offenders)")
    }
}

SwiftUI, UIKit, and AppKit are system frameworks, so a stray import SwiftUI in an engine file would compile green and ship undetected. The convention is not enough; this test makes the leak fail the build. That is the whole integrity story in thirty lines.

The shape of every test: do it twice, compare

Every oracle test has the same skeleton. Describe a scene. Run it in real SwiftUI and record the answer. Run the same scene in the engine. Assert the two agree, to the floating-point floor.

The harness: running real SwiftUI headless

To use SwiftUI as the oracle we have to run it for real, with no app and no screen. The harness hosts a view in an offscreen window, lets it run a genuine update cycle, then reads the resolved geometry back out through a preference-key probe.

private struct FrameKey: SwiftUI.PreferenceKey {
    static let defaultValue: [String: CGRect] = [:]
    static func reduce(value: inout [String: CGRect], nextValue: () -> [String: CGRect]) {
        value.merge(nextValue(), uniquingKeysWith: { _, new in new })
    }
}

extension SwiftUI.View {
    /// Tag a view so the oracle records its resolved frame, in root coordinates.
    func probe(_ id: String) -> some SwiftUI.View {
        background(
            GeometryReader { proxy in
                Color.clear.preference(key: FrameKey.self, value: [id: proxy.frame(in: .named(kRoot))])
            }
        )
    }
}

@MainActor
func oracleFrames(_ content: some SwiftUI.View, rootSize: CGSize) -> [String: CGRect] {
    let box = FrameBox()
    let view = ZStack(alignment: .topLeading) { content }
        .frame(width: rootSize.width, height: rootSize.height, alignment: .topLeading)
        .coordinateSpace(name: kRoot)
        .onPreferenceChange(FrameKey.self) { box.frames = $0 }
        .environment(\.displayScale, 2)   // pin the pixel grid for cross-machine determinism

    let host = NSHostingView(rootView: view)
    host.frame = CGRect(origin: .zero, size: rootSize)
    let window = NSWindow(contentRect: host.frame, styleMask: [.borderless],
                          backing: .buffered, defer: false)
    window.contentView = host
    host.layoutSubtreeIfNeeded()
    pump(until: { !box.frames.isEmpty }, timeout: 2)
    return box.frames
}

/// Spin the main run loop in 10 ms slices until `condition` holds or `timeout` elapses.
@MainActor
func pump(until condition: () -> Bool, timeout: TimeInterval) {
    let deadline = Date().addingTimeInterval(timeout)
    while !condition(), Date() < deadline {
        RunLoop.main.run(until: Date().addingTimeInterval(0.01))
    }
}

displayScale is pinned to 2 so SwiftUI’s frame snapping is identical on a Retina machine and a CI box. When we say “we measured what SwiftUI does,” this is the literal mechanism: SwiftUI runs, and a GeometryReader reports its own layout system’s answer.

Measuring the attribute graph: count the body re-runs

The headline claim about SwiftUI is the cone: change one value, and only the views that read it recompute. The problem is that a body re-run leaves no trace. So we give it one. Each probe view bumps a counter inside its body. The invisible event becomes an integer.

/// A reference counter mutated only on the main actor (inside `body`).
private final class BodyCounter: @unchecked Sendable {
    private(set) var runs = 0
    func bump() { runs += 1 }
}

private final class OracleModel: SwiftUI.ObservableObject {
    @SwiftUI.Published var value: Int = 0
}

/// Reads `model.value`, so it depends on the state.
private struct ReaderView: SwiftUI.View {
    @SwiftUI.ObservedObject var model: OracleModel
    let counter: BodyCounter
    var body: some SwiftUI.View {
        counter.bump()
        return Text(verbatim: "\(model.value)")
    }
}

/// Reads nothing from the model, so it must not re-evaluate when the state changes.
private struct IgnorerView: SwiftUI.View {
    let counter: BodyCounter
    var body: some SwiftUI.View {
        counter.bump()
        return Text(verbatim: "static")
    }
}

The test reads both counters, changes one value, waits for the reader to re-run, and then drains the run loop a little longer so a stray re-run of the ignorer would be caught. Then it builds the same shape in the engine’s AttributeGraph and asserts the cones match.

@Test("only the view that reads state re-evaluates, and the engine cone agrees")
func bodyEvalConeMatchesEngine() {
    // Ground truth from real SwiftUI.
    let swiftUI = swiftUIBodyEvalDifferential()
    #expect(swiftUI.readerReran,  "SwiftUI: the reader's body should re-run on the state change")
    #expect(!swiftUI.ignorerReran, "SwiftUI: the ignorer's body should not re-run")

    // The same shape modeled in the engine: a source, a reader, an ignorer.
    let graph = AttributeGraph()
    let state = Attribute(graph: graph, value: 0)
    let reader = Attribute(graph: graph) { _ in state.value }
    let ignorer = Attribute(graph: graph) { _ in 0 }
    _ = reader.value
    _ = ignorer.value
    let readerBefore = reader.evaluationCount
    let ignorerBefore = ignorer.evaluationCount

    state.setValue(1)
    _ = reader.value
    _ = ignorer.value

    // The differential: the engine's invalidation cone matches SwiftUI's.
    #expect((reader.evaluationCount  > readerBefore)  == swiftUI.readerReran)
    #expect((ignorer.evaluationCount > ignorerBefore) == swiftUI.ignorerReran)
}

Proving an absence is the subtle part. To show the ignorer stayed put, the test waits for the expected re-run and then drains briefly for a stray. The engine side is deterministic and is the real regression catcher; the bounded wait on the SwiftUI side can only catch a stray, never manufacture a false pass.

Measuring layout: probe the resolved frame

Layout is the largest area, because there is the most to pin down. Each test lays the scene out in real SwiftUI, reads back every subview’s frame through the probe, and asserts the engine places each node at the same coordinates.

@Test("Frame centering matches real SwiftUI")
func frameCentering() {
    let leaf = Color.clear.frame(width: 20, height: 20).probe("child")
    let container = leaf.frame(width: 30, height: 30).probe("container")
    let oracle = oracleFrames(container, rootSize: CGSize(width: 100, height: 100))
    #expect(!oracle.isEmpty, "oracle produced no frames (headless measurement failed)")

    let node = FrameLayout(width: 30, height: 30, FixedLeaf(Size(width: 20, height: 20)))
    let engine = node.layout(in: Size(width: 100, height: 100))

    if let oc = oracle["container"] {
        #expect(close(oc, cg(engine.frame)), "container: oracle \(oc) vs engine \(cg(engine.frame))")
    }
    if let ch = oracle["child"] {
        #expect(close(ch, cg(engine.children[0].frame)), "child: oracle \(ch) vs engine \(cg(engine.children[0].frame))")
    }
}

close is where the rigor lives. The tolerance absorbs only CGFloat round-trip, nothing more.

/// The engine and SwiftUI must produce the *same* frame, not a close one. This 1e-6
/// absorbs only `CGFloat` round-trip representation. A residual above it is a real
/// divergence, never slack: re-derive the rule, do not widen the bound.
let exactFloor: CGFloat = 1e-6

func close(_ a: CGRect, _ b: CGRect, tol: CGFloat = exactFloor) -> Bool {
    abs(a.minX - b.minX) <= tol && abs(a.minY - b.minY) <= tol &&
        abs(a.width - b.width) <= tol && abs(a.height - b.height) <= tol
}

When a layout test fails, the rule is to find why the behavior differs and fix the engine, never to widen exactFloor until the failure disappears. A tolerance you are allowed to relax is a wish, not a measurement.

Measuring animation: hold the spring against SwiftUI’s Spring

Animation is the most quantitative area, because motion is numbers over time. A spring is a damped harmonic oscillator. Released from rest, its progress curve is

which starts at 0, sweeps past 1, and settles back. We sample the engine’s spring and SwiftUI’s own Spring at the same times and assert they agree across all three damping regimes.

@available(macOS 14, iOS 17, *)
private func assertSpringMatches(
    response: Double,
    dampingFraction: Double,
    tolerance: Double = 1e-6
) {
    let engine = PureView.Spring(response: response, dampingFraction: dampingFraction)
    let oracle = SwiftUI.Spring(response: response, dampingRatio: dampingFraction)
    let samples = 120
    for step in 0 ... samples {
        let t = engine.settleDuration * Double(step) / Double(samples)
        let engineValue = engine.unitStepResponse(at: t)
        let oracleValue = oracle.value(target: 1.0, initialVelocity: 0.0, time: t)
        #expect(
            abs(engineValue - oracleValue) <= tolerance,
            "spring(response=\(response), damping=\(dampingFraction)) at t=\(t): " +
            "engine \(engineValue) vs SwiftUI \(oracleValue)"
        )
    }
}

The assertion is the whole point, in one line:

Sampled point by point, the two springs are the same number to six decimals.

Measuring pixels: compare the rendered bytes

Frames prove position. Pixels prove the rest: the actual color drawn, and the paint order of overlapping fills. SwiftUI’s own ImageRenderer rasterizes the view; the engine’s display list is rasterized by a reference renderer; we diff the buffers channel by channel.

/// Render a SwiftUI view to an RGBA8 buffer in the same space/scale/orientation.
private func snapshot(_ view: some SwiftUI.View, size: CGSize, scale: CGFloat) throws -> [UInt8] {
    let renderer = ImageRenderer(content: view.frame(width: size.width, height: size.height))
    renderer.scale = scale
    renderer.colorMode = .nonLinear
    let image = try #require(renderer.cgImage, "ImageRenderer produced no image")
    let w = Int(size.width * scale), h = Int(size.height * scale)
    let (ctx, raw) = try context(width: w, height: h, scale: 1, flipForDrawing: true)
    defer { raw.deallocate() }
    ctx.draw(image, in: CGRect(x: 0, y: 0, width: CGFloat(w), height: CGFloat(h)))
    return bytes(raw, count: w * 4 * h)
}

private func assertPixelsMatch(
    _ name: String,
    list: DisplayList,
    view: some SwiftUI.View,
    size: CGSize,
    scale: CGFloat = 2,
    tolerance: Int = 2
) throws {
    let engine = try rasterize(list, size: size, scale: scale)
    let swiftui = try snapshot(view, size: size, scale: scale)
    #expect(!engine.isEmpty && engine.count == swiftui.count, "\(name): buffer size mismatch")
    var maxDiff = 0, exceeding = 0
    for i in 0 ..< min(engine.count, swiftui.count) {
        let diff = abs(Int(engine[i]) - Int(swiftui[i]))
        maxDiff = max(maxDiff, diff)
        if diff > tolerance { exceeding += 1 }
    }
    #expect(exceeding == 0, "\(name): \(exceeding) channels exceed tol \(tolerance) (maxDiff \(maxDiff))")
}

The tolerance here is 2 on an 8-bit channel: the quantization floor is one least-significant bit, and integer-aligned fills at scale 2 have crisp edges, so there is no anti-aliasing slack to hide behind.

What it all adds up to

There are 125 of these tests today, across 19 files. The same do-it-twice method holds every layer the engine rebuilds.

What measuring caught that reading never would

The payoff: the measurement caught a bug in the engine that reading the code could not. The spring decided it had come to rest using the bare decay envelope, which undercounts the long tail of a critically damped or overdamped spring. The code looked correct. Measured against SwiftUI, the spring clamped a few percent short of its target, a visible snap. The oracle failed with the exact residual, and the settling time was rederived from the real basis of the oscillator. Reading gives you the happy path. Measuring gives you the edges, where the interesting bugs live.

One honest caveat about the animation path

A committed animation keeps running smoothly when the main thread is busy only for one of two paths. Layer-level properties, opacity and transform, lower to Core Animation and are interpolated on the render server’s own clock, off the main thread. Value-driven animations, a spring on a custom value, are re-pulled through the graph every frame on the main thread, and those do stutter if you block it. The oracle measures the value and velocity of the motion; which thread interpolates it is a property of the lowering path. Worth stating precisely, since the rest of this post is about precision.

Colophon: every figure was made by my own software

No third-party drawing or charting tool was used anywhere in this post.

• The conceptual diagrams (the wall, the two pieces, the counters, the negotiation, the pixel comparison) were drawn by PureDraw, my dependency-free Swift-native 2D vector engine, through its GraphicsContext API. PureDraw rasterized them to the JPEGs shown here with its own BitmapRenderer and JPEGEncoder, and also produced scalable SVG and PDF masters. No external image tool touched them.

• The bar chart, the spring plot, and every mathematical formula were rendered by TileDown, my static-site engine, from plain-text fences in this Markdown file.

• This page was assembled by TileDown, and its PDF was typeset by MarkdownPDF, my Markdown-to-PDF engine.

PureDraw is part of SlayerMotion, the graphics engine family this series is about. TileDown and MarkdownPDF are separate projects of mine, not part of SlayerMotion. All three are my own software; none of it is anyone else’s.

I wanted to know what SwiftUI really is, not what the tutorials say it is. So I came at it from two directions that cannot collude. I measured the real framework’s behavior until it was predictable, the way you probe any black box, and I read Apple’s own patent on it, line by line. The shipping framework is the oracle. The granted patent is Apple describing its own machine. When the two agree, you are no longer guessing.

flowchart LR
  B["Real framework behavior"] --> M["One demand-driven graph"]
  P["Apple's granted patent"] --> M

And they agree, almost field for field. What they describe together is simpler and stranger than the usual story: not a view tree that gets diffed, but a single demand-driven graph. I will show you that graph, because it is genuinely elegant. Then, at the end, I will tell you why it is the part of Apple’s stack I find least interesting, and what I have been doing about that. First the engine.

A view is a value, not an object

When you write a SwiftUI view you are not creating a thing on screen. You are describing what the screen should look like, as a cheap struct that gets thrown away and rebuilt constantly. This trips people up because it feels wasteful. It is not. The struct is disposable on purpose. The part of your UI that actually persists lives somewhere else entirely.

That somewhere else is the attribute graph, and it is the whole game.

The attribute graph

Every view compiles into a graph of attributes. An attribute is one node with exactly two things: a cached value, and a rule that computes that value from its inputs. A view’s body is itself an attribute whose rule is “evaluate this body.”

The clever part is how edges form. When a rule runs and reads another attribute, an edge is recorded between them. Dependencies are never declared. They are discovered, by watching what each body actually reads while it runs. You get the dependency graph for free, just by evaluating.

Now the reactive behavior everyone loves, explained without magic. You change one piece of state. SwiftUI does not rebuild the world. It marks that single source attribute dirty and pushes the dirty flag forward along the edges, to exactly the attributes that depended on it and to nobody else. That set is the cone. Then, lazily, when the screen needs a value, it pulls. It walks down to the dirty inputs, recomputes only those, caches them, and bubbles the result back up. An attribute whose inputs did not change returns its cache and its rule never runs. That is why a screen with a thousand views re-runs the body of only the one that changed.

flowchart TD
  S["@State count, a source"] -->|dirty| L["Label.body"]
  L --> T["Text attribute"]
  S -.->|no edge, untouched| O["Other.body"]

The cone is the whole efficiency story. A naive rebuild touches every body in the interface, so its cost grows with the screen. The graph touches only the dirty node and what truly depends on it, so its cost tracks the change, not the size of the UI.

There is one more piece that matters for performance. If a recomputed value comes out equal to what it was before, propagation stops there. An unchanged value never disturbs anything downstream, so a state change that happens to produce the same result costs almost nothing.

State and identity

Because the view struct is disposable, your @State cannot live inside it. It lives in persistent storage, keyed by the view’s identity. Identity is structural, meaning the view’s type and position in the tree. An explicit id does not override that, it pairs with it: change the identifier and the view gets a new identity at that spot, but reuse the same identifier elsewhere and the two stay distinct.

This one rule explains a lot of confusing behavior. As long as the identity is stable, your state survives every rebuild of the struct. The moment the identity changes, by changing .id or by removing and reinserting the view, the old state is destroyed and a fresh one is created at its default. It is also why a List can recycle its rows without losing their state. The state follows the identity, not the position on screen. Reorder the data and each row’s state travels with its identifier.

Layout is a negotiation

Layout is three steps and one rule. The parent proposes a size to the child. The child chooses its own size. The parent then places the child. The rule is that the parent never forces a size on the child. A stack divides its space among its children, giving the least flexible ones their size first and sharing what is left. Text measures itself through the text engine, with kerning and the font’s own line metrics, which is why a label is exactly as wide as it needs to be.

flowchart TD
  P1["Parent proposes a size"] --> C1["Child chooses its own size"]
  C1 --> P2["Parent places the child"]

How it becomes pixels, and the part people get wrong

SwiftUI sits on Core Animation. Core Animation holds the layer state, position, opacity, transform, the properties the GPU composites and the render server interpolates. Core Graphics paints the content, text and shapes, into bitmaps that become a layer’s contents.

Here is the part most people get wrong. SwiftUI does not make one layer per view. UIKit does that, where every view is layer backed one to one. SwiftUI coalesces. A stack of ten text labels is usually a single layer with a single drawing, not eleven layers. A view earns its own layer only when it needs a layer level property, like opacity or a transform. This is a real reason SwiftUI is efficient. A long list is a handful of layers for the compositor to manage, not thousands. The tradeoff is that coalesced content has to be redrawn when it changes, while a dedicated layer can move without a redraw. For typical interfaces that trade is a clear win.

Animation, the beautiful part

When you change a value inside withAnimation, the model value jumps straight to its target. It does not crawl there. Instead the framework makes a copy of that destination, and into the copy it injects an intermediate value, interpolated for this exact instant. The view draws the copy. Your data is already at the final value. Only the presentation is in flight.

Each animation is a tiny record: a from value, a to value, a timing function, and a start time. That is all it needs.

flowchart TD
  R["Animation record"] --> A["from value"]
  R --> B["to value"]
  R --> C["animation function"]
  R --> D["start time"]

Time itself is just another input to the graph. Every frame a clock ticks, that tick dirties only the animated attributes, and they re-pull a fresh interpolated value through the same cone machinery as everything else. The interpolation works on a delta vector, the difference between from and to, scaled by the curve.

A spring is not a special case. It is a damped harmonic oscillator solved over time, which is exactly why it overshoots and then settles. And because the animation is committed once and the render server interpolates on its own clock, it keeps running smoothly even when your main thread is busy.

Two lines of math carry the whole motion. The presented value is the start plus the delta, scaled by the curve $p(t)$, which runs from 0 to 1, so the data sits at the target while only the presentation moves:

A spring is the same machinery with the curve replaced by a damped harmonic oscillator. Released from rest, its progress curve is

which starts at 0, sweeps past 1, and settles back to 1. That overshoot past 1 is exactly why the spring overshoots its target and then settles.

What the patent says

US 11,042,388 B2, granted June 22, 2021, priority June 3, 2018. Inventors Jacob Xiao, Kyle Macomber, Joshua Shaffer, and John Harper, the same John Harper who created Core Animation in 2006.

John Harper, via his GitHub.

Hold that name. Apple the company would not exist without Steve Jobs. The iPhone, and the whole fluid, animated, GPU-composited kingdom that grew on top of it, iOS, iPadOS, watchOS, tvOS, and visionOS, would not exist as we know it without John Harper. The same hand drew the engine that runs underneath all of it, from Core Animation in 2006 to the very graph this post is about. SwiftUI is just the newest room in a house whose foundation he poured. He is the John Carmack of Apple, its Linus Torvalds: the engineer whose work a billion people touch every day and whose name almost none of them know. That is a shame, and correcting it, in my own small way, is part of why I am writing all this.

flowchart LR
  I["Inputs, 0 to n"] --> F["Function"]
  F --> O["Cached output, persistent"]
  O -.->|re-run| F

As you can see in the image above, the patent lays the attribute graph out in plain words. It supports zero to n inputs, applies a function on the inputs to calculate an output, stores the output in a persistent memory structure, and whenever any input changes the function gets re-run. Affected attributes set a dirty bit, and the tree is traversed bottom up so that dirty attributes initiate an update. That is exactly what the behavior shows, down to the dirty bit and the bottom up pull, now in Apple’s own words.

It also spells out the animation record as the same four fields the behavior implies: from value, to value, animation function, start time.

flowchart LR
  T["Destination state, your data"] --> Cp["Copy"]
  Cp --> Inj["Intermediate value injected"]
  Inj --> Rn["Copy is rendered"]

And as the image above shows, the patent describes the method as generating a copy of the destination state and injecting an intermediate value into the copy for rendering. That is the model and presentation split you can watch the real framework perform.

I did not take any of this from the patent. The behavior and the patent are two independent witnesses, and they arrive at the same machine. When the framework you can observe and the patent Apple was granted describe the same structure, that structure is real, forced by the problem, not chosen by taste.

One graph, one cone, drawn lazily

That is the whole of it. A single demand-driven graph. State flows down through the environment, preferences flow up from children to parents, time is just another input, the graph recomputes only what truly changed, and it hands a coalesced layer tree to Core Animation to composite. Strip away the syntax and SwiftUI is one graph, one cone, drawn lazily.

And here is the part I will only hint at. This was never really about SwiftUI. It began with Core Animation, because I wanted to understand it, and the only way I trust to understand a thing is to build it again from nothing. But you cannot understand Core Animation without the drawing layer beneath it, so that came next.

A text layer pulls you into typesetting. Transitions pull you into image processing. Each engine demanded the one below it, until the whole stack stood on its own and SwiftUI settled on top almost as an afterthought. None of it ships, and none of it is for sharing. It is mine, a way to learn the machine by rebuilding it, and it has a name: SlayerMotion.

flowchart TD
  SUI["SwiftUI, one graph"] --> CA["Core Animation, the compositor"]
  CA --> CG["Core Graphics, drawing"]
  CA --> CT["Core Text, typesetting"]
  CA --> CI["Core Image, effects"]

Of the five, SwiftUI interests me the least, by a wide margin. It was not even born to be the future of the platform: it started as a way to make watchOS apps bearable to write, and only once it existed did Apple look at it and see what they had, and take it everywhere. It arrived with a quiet promise: that you could finally skip all of it, the dozen frameworks underneath, and just ship.

That promise was a lie. You can ship, yes, but you have not learned the platform, you have learned a facade over it, and the day something leaks through, a layout that will not behave, an animation that stutters, text that measures wrong, you are standing on a stack you never met. The people who took SwiftUI as a way around the frameworks did not become Apple developers. They became SwiftUI users, and that is a different and smaller thing.

Set beside the engines underneath it, SwiftUI is genuinely uninteresting, boring even, a thin and tidy graph that does one clever thing and then gets out of the way. The one that floored me at the start still floors me most, and I suspect always will: Core Animation, a compositor that keeps an animation running smooth on its own clock while your app is busy elsewhere. The drawing layer, the type engine, the image pipeline are close behind. That is where the hard, strange, beautiful problems live, and that is the series. SwiftUI was just the easiest door into the story.

The keynote tells you what Apple announced. The documentation and the sample code tell you what Apple wants you to actually ship. Those are not the same thing, and the second one is far more useful if you are deciding what to build this summer.

So I did the boring, revealing thing: I diffed it. Cupertino just shipped v1.4.0, a full re-crawl of Apple’s developer documentation, and I compared it page by page against the version that has been on everyone’s disk since May. Then I read the diff like a tea leaf.

The answer is not subtle. Apple wants you to build Apple Intelligence into your app, and it has written you the homework.

The sample code is the smoking gun

When Apple wants you to learn an API, it announces it. When Apple wants you to ship something, it gives you sample code you can paste from. So the new sample projects are the clearest signal in the whole corpus, and v1.4.0 added eleven of them. Here is the entire list:

• App Intents: Integrating Your Music App with Apple Intelligence

• App Intents: Integrating Your Messaging App with Apple Intelligence

• App Intents: Integrating Your Calendar App with Apple Intelligence

• App Intents: Integrating Your Photo App with Apple Intelligence

• FoundationModels: Origami, crafting a dynamic tutorial for Apple Intelligence

• Evaluations: Book Tracker, using evaluations to evaluate an intelligent feature

• HealthKit: Tracking heart rate zones for workouts

• Metal: Training a neural network to render irradiance in real time

• Metal: Running inline ML operations in a shader with Metal 4

• DeclaredAgeRange: Implementing age assurance and permissions

• VisionKit: Structuring recognized text on a document

Read the top four again. Apple did not write “an example of App Intents.” It wrote “Integrating Your Music App,” “Your Messaging App,” “Your Calendar App,” “Your Photo App.” That is not documentation. That is a brief. Apple has taken the four most common app categories on the platform and handed each one a template for wiring itself into Apple Intelligence through App Intents. If you ship one of those four kinds of app, your summer roadmap is sitting in a sample project with your name on it.

There is not a single exception in the eleven. Every new sample is Apple Intelligence, App Intents, or on-device ML. No new SwiftUI layout sample, no new networking sample, no new Core Data sample. The signal is monochrome.

The new frameworks are the syllabus

Sample code shows you the assignments; the new frameworks show you the curriculum. v1.4.0 added 19 frameworks that did not exist in the previous release, and the cluster tells the same story:

Core AI. Evaluations. Media Intelligence. Music Understanding. Trust Insights. Suggested Actions. App Intents Testing. This is the connective tissue around on-device models: the pieces that let your app declare what it can do, feed a model the right context, evaluate what comes back, and route media intelligently. Evaluations is the quiet standout. Apple shipping a framework specifically for evaluating an intelligent feature, plus a sample that uses it, is Apple admitting that “add AI” is not a feature, it is an engineering discipline with a test loop. That is the most grown-up thing in the release.

And it is not only the debutants. foundationmodels, the on-device model framework, was not new but it more than doubled in pages (356 to 821) and more than tripled in symbols (406 to 1,383). The framework Apple gave you last year to talk to its models is the one it spent this cycle fleshing out.

The honest part: most of the bytes are a deeper re-crawl

I am not going to oversell the numbers, because the headline flatters the truth. The documentation database grew by +12,057 pages and +67,575 symbols. But only about 23% of the new pages come from those 19 new frameworks. The other 77% is a deeper re-crawl of frameworks that already existed. For symbols it is even more lopsided: roughly 95% of the gain is re-crawled existing frameworks, and the Swift standard library alone accounts for over 40% of it (+27,908 symbols).

So the accurate sentence is: the byte-weight is a fuller pass over everything, and the signal is the 19 new frameworks and eleven new samples on top. Both are true, and a release post that only quoted the big number would be lying by omission.

Where did the existing-framework growth concentrate? Right where you would guess given the theme:

RealityKit and App Intents leading the page growth is the same story from yet another angle: spatial computing and the intent system are both load-bearing for what Apple is asking you to build. No framework shrank in page count and none were removed, so at the framework level v1.4.0 is a clean superset of v1.3.0.

What did not change, honestly

A re-crawl is not a magic content generator. Four databases came back byte-for-byte identical to v1.3.0: HIG, Swift Evolution, the Swift book, and the legacy Apple Archive guides. Three of those (HIG, Swift Evolution, the Swift book) were genuinely re-crawled this cycle and simply came back unchanged because Apple had not touched them upstream; the archive corpus was the one source carried over from the previous cycle. I verified “identical” with a content fingerprint over every page, not by trusting file dates. If your work lives in those four, v1.4.0 changes nothing for you, and I would rather say so than pad the release.

The Swift package index (packages.db) is the interesting middle case. The set of 185 packages is unchanged, but 183 were re-fetched from current upstream and re-indexed, so the database now reflects what those packages look like today rather than at the last crawl. That means it is honest rather than purely additive: Vapor lost 1,604 symbols where upstream refactored, while swift-package-manager and swift-async-algorithms each gained a few hundred. Net +2,836 symbols, but the real win is that the package picture is current.

Why your AI agent needs this, specifically now

Here is the part that ties the signal back to the tool. If Apple wants you to spend the summer wiring your app into Apple Intelligence, you are going to ask an assistant about Core AI, App Intents Testing, the Evaluations framework, and FoundationModels constantly. And an assistant working from a six-month-old corpus will confidently tell you those frameworks do not exist, because in its world they do not.

That is exactly the failure Cupertino exists to prevent. It puts Apple’s documentation on your machine as a set of local, searchable databases an AI agent can read through MCP, offline, in milliseconds. v1.4.0 is not a flashy release: it does not add a feature or touch a line of the query engine. It does the quieter thing that actually matters for a documentation tool, which is make the corpus match what Apple shipped. The fact that the new frameworks map almost perfectly onto Apple’s summer wishlist is not a coincidence; it is the whole point. Your agent now knows about the assignment.

Getting v1.4.0

The binary is signed and notarized and lives on the tap:

brew upgrade cupertinohq/tap/cupertino# or: brew tap cupertinohq/tap https://codeberg.org/CupertinoHQ/homebrew-tap.git
brew install cupertinohq/tap/cupertino
cupertino setup            # downloads the v1.4.0 database bundle

Same 8 per-source databases as v1.3.0, shipped read-only in rollback-journal mode, same schema (v18, packages on their own v5 track). Nothing in your tooling changes; the corpus underneath it just got current, and it got current in a very specific, very on-message direction.

Build the thing in the sample project. Apple already wrote the brief.

An autonomous bounty bot opened a pull request on my project that quietly repointed a core dependency to a fork it controlled. It did not even work. That is the part that should worry you.

On 21 June 2026, a pull request landed on Cupertino, my open-source Apple-documentation MCP server. The title was reassuringly boring: “Fix for issue #13.” The body was one line: “Implemented automated fix.” Three files changed, a hundred-odd lines, green-ish checks. The kind of contribution a maintainer waves through between meetings.

Then I read the lockfile.

One line in a lockfile

Buried in Packages/Package.resolved, the PR changed a single dependency’s location:

- "location": "https://codeberg.org/Mihaela/SwiftMCPCore.git"
+ "location": "https://github.com/KartavyaDikshit/SwiftMCPCore.git"

SwiftMCPCore is the wire-protocol core my server is built on. The PR repointed it from my repository to a fork owned by the person who opened the PR. The new code in the same PR called an API (variables) that does not exist in the real SwiftMCPCore, only in that fork. The fork had been created 33 minutes before the PR was opened.

That one line is the entire anatomy of a software supply-chain compromise. If I merge it, or if my CI so much as builds the branch, the build tool fetches and runs code from a repository I do not control, and bakes it into the binary that ships to every user through Homebrew. The payload today is harmless. The repository is not mine. Whoever owns it can change it tomorrow. That is the whole move: get a trusted project to depend on something you control, dressed up as a helpful fix.

The twist: it would not have worked

Here is what turns this from a scary anecdote into something useful. The PR changed the lockfile but not the manifest. Swift Package Manager trusts Package.swift, not Package.resolved, for where a dependency actually comes from, and Package.swift still pointed at my canonical repository. So on a real build the fork URL gets ignored or overwritten, and the new code, which depends on the fork, fails to compile. No build check ever ran green, because it cannot.

A competent attacker edits the manifest too, so the swap actually takes effect. This one did not. And that is exactly what told me what I was really looking at.

The real story: a bounty bot

This was not a hand-crafted attack on my project, and I do not have to guess, because the author published the tool. Among his own repositories is one called bounty-hunter, described in his own words as an “Autonomous GitHub open-source bounty hunter bot.” He created it at midnight UTC, finished building it within the hour, and then let it run.

The timeline of my incident reads like a machine working a list:

The targets give away the goal, and it is farming, not sabotage. One target was a crypto-bounty repo that literally pays per merged contribution, hit twice. Another was a well-known honeypot whose own description invites newcomers to “make pull requests and build their reputation.” The rest were high-visibility AI and developer-tool projects where good-first-issues live, including, with some irony, a Python supply-chain auditing tool.

To make my build compile inside its sandbox, the bot needed a type the upstream package did not have. So it forked the package, added the type, and its local resolve wrote the fork URL into my lockfile, which it then committed. The dependency repoint was a byproduct of a machine trying to make a build pass on its way to a merged PR. On the other 33 repositories, the same bot never touches dependencies at all.

The author looks like an early-career developer: a five-year-old account, a portfolio of student machine-learning and web projects, based in a German university town. This is not a nation-state. It is one person, a sixteen-kilobyte Python script, and a language model.

Why the harmless explanation is the alarming one

Intent barely matters. Whether this bot is farming bounties, padding a contribution graph, or demonstrating a product, the artifact it produced is indistinguishable from a supply-chain attack and one manifest edit away from a working one. And it operates at volume: one bot, 34 repositories, in a single day.

The defense open source has always leaned on is a human maintainer reading the diff. That defense does not scale to this throughput. Review fatigue is the attack surface now. The weaponized version writes itself: same pipeline, swap the benign type for a payload, fix the manifest so it resolves, fan out to a few hundred repositories, and wait for one tired maintainer to merge a green-looking fix at 1am. The barrier to producing this used to be skill and intent. Now it is a weekend project.

What actually protects you

• Read the dependency files first. On any PR that touches Package.resolved, package-lock.json, go.sum, or Cargo.lock, that diff is the review, not the feature code.

• A dependency URL that points at a contributor’s fork is an automatic reject, no matter what the fork contains today.

• Do not let CI build untrusted external PRs without a human gate. Building is execution.

• Keep the manifest and lockfile consistent, pinned to a canonical source and a known revision, and reject any PR where the two disagree.

How I handled it

I declined and closed the PR with a public explanation, because the reasons are a heads-up for every other maintainer this bot visited. The feature it reached for is actually worth having: typed resource-template variables. The right way to get it is to propose the type to the canonical package, where it can be reviewed, tagged, and pinned, then build on top of that. The idea was fine. Depending on a fork I do not control is the disqualifier.

If you maintain anything popular enough to have open issues, a bot is already reading them. Read your lockfiles.

Left to its own defaults, an AI coding agent is an enthusiastic shortcut machine. It will wrap the failing call in try? and move on. It will force-unwrap because the optional is “obviously” non-nil. It will handle the three easy cases, skip the malformed one, and report the task done. It will tell you “tests pass” without running them, because the build was green and the build “should” mean the tests are fine. Every one of those is a small lie that compiles.

I did not start with a rulebook. I started with corrections.

The first ones were one-offs, the kind you mutter while you fix them yourself. Don’t swallow that error. Don’t force-unwrap there. Run the tests before you tell me they passed. But the same corrections came back, session after session, and a correction you give twice is a rule you have not written down yet. So I started writing them down, one repeated annoyance at a time, in a file the agent loads before it touches a line of my code.

What I did not expect was the side effect. To make a rule a machine will actually obey, you have to state it precisely enough that it cannot be wriggled around, and every time I forced that precision I found a place where I had been hand-waving for years. The rulebook was supposed to discipline the agent. It ended up disciplining me.

That file is public now. It is rules-swift: the rules I point every coding agent at as always-loaded context. It is two layers in one repo, the Swift and Apple-platform craft on top and a language-agnostic standard of care vendored underneath in core/ (which is also its own repo, rules-engineering-discipline, if you work in another language). The whole thing rests on one line, “choose the optimal path, not the fastest one,” and everything else is a specific way of not betraying it.

But the repo is the destination. The journey was three turns, each one a correction I kept making until it became a rule, and each rule turning around to teach me something about my own work.

The first turn: the fix you ask for is usually a symptom

The correction I made most often was not about a bug. It was about where the bug was being fixed.

The example that finally made me write the rule was a retry. The agent had wrapped a call that should never fail in a retry loop, and the retry made the failure disappear. But a call that should never fail and sometimes does has a bug one layer down, and the retry was hiding it. The fix belonged in the layer that owns the data, not in a loop around the symptom.

The rule I wrote is almost embarrassingly basic: before writing code, state the problem’s real invariant in one sentence, and if you cannot, you are not ready to write it. Trace a symptom to the layer that owns it before you patch anything. The moment I made the agent do that, I had to admit how often I did the opposite, reaching for the nearest familiar shape instead of deriving from the actual constraint. Its companion clause turned out to be just as much about me: reason from the source, not from memory. A remembered API signature is a hypothesis, not a citation. I had been quoting my own memory as evidence for years.

The second turn: validations are values, and the best one is the one you delete

The more I corrected the agent’s validation code, the more I recognized my own. One big validate() function, a tree of if statements, a mutable errors array I appended to as I went. That is how almost everyone does it, and it is how I did it.

The turn came from Matt Polzin’s OpenAPIKit idiom: validations are not control flow, they are values. A Validation<Subject> is a description, a check, and a when predicate, composed with an algebra instead of nested conditionals. Two things in that rewired how I think about correctness. First, the description states the correct state, never the failure. You write “Operations contain at least one response,” and the framework derives the negative by prefixing “Failed to satisfy:”. One source of truth, two readings, where I used to write the message and the check as two things that quietly drifted apart. Second, the strongest validation is the one you delete: if a type carries its own invariant, a non-empty collection, a smart constructor that rejects bad input at init, the bad state cannot be built and needs no check at all.

And the part with teeth, the one I now miss in every codebase that lacks it: every public type is either validated or excluded with a one-line reason, and a coverage gate in CI fails the build if someone adds a public type that is neither. “We validate our inputs” stopped being something I said in a meeting and became something the build proves on every commit.

The third turn: no singletons, not even the sanctioned one

This is the bluntest rule in the set, and the one I argued with myself about the longest. No singletons, ever. Not static let shared. Not even the Singleton that the Gang of Four book explicitly sanctions on page 127. The rule names that exact temptation and refuses it: when you catch yourself about to document one as “legitimate per p. 127,” stop, and do the injection.

It reads as dogma until you see the reason, and the reason was the lesson. Every dependency should appear at the type’s init, where the coupling is visible, testable, and removable. A singleton conjures its collaborator out of process-wide state at runtime, and the instant it does, that dependency is invisible in the call graph and welded to everything that touches it. The test I now hold a module to is mechanical: copy it out of the repo with only its declared dependencies and build it. If it does not lift out clean, it has a hidden dependency, and a hidden dependency is a bug that has not happened yet.

Where it landed: a machine will not give you the benefit of the doubt

Here is the thing the whole journey was actually about, the one I did not see coming. A colleague who reads “validate carefully” fills in the rest from experience. An agent does not. Vague rules produce vague work, instantly and at scale. So every rule had to become checkable: not “be rigorous” but “no claim of done without a fresh command in this response,” not “handle errors” but the exact list of forbidden silencers (try?, force-unwrap, xfail, sleep() to make a symptom vanish).

That is what made the corrections worth writing down. Every place a rule resisted being made checkable was a place I had been getting by on the benefit of the doubt, the same benefit a machine refuses to extend. The whole set collapses into one question the agent has to answer before it calls anything finished, and writing it for the agent is how I finally started asking it of myself:

Did I take the optimal path, or a path I am hoping no one inspects?

Honesty is one of the rules, so the limits: a rules file does not enforce itself. A model that has read “no force-unwrap” is not a force-unwrap that never ships, which is why the checks a machine can decide live in git hooks and CI and the prose only covers the judgment calls. The set is also shaped to my stack, a Swift monorepo with an OpenAPI-first workflow, and the Swift opinions are opinions. The engineering-discipline core travels anywhere; the rest you should fork and disagree with in writing.

The map, if you want it

If any of this sounds like a correction you have made more than once, take the map. Clone rules-swift, point your agent at it, and watch how much stops needing to be said twice. The core spine comes vendored with it; the standalone rules-engineering-discipline is there if you want it on its own. Star it if it saves you a repeated correction. That is the whole ask.

Here is the validation function almost everyone writes the first time. You have a parsed model. You want to check it. So you write this:

func validate(_ document: Document) throws {
    var errors: [String] = []
    if document.servers.isEmpty {
        errors.append("document has no servers")
    }
    for (path, item) in document.paths {
        for (method, operation) in item.operations {
            if operation.responses.isEmpty {
                errors.append("\(method) \(path) has no responses")
            }
            for variable in operation.server?.urlTemplate.variables ?? [] {
                if !operation.server!.variables.keys.contains(variable) {
                    errors.append("\(path) uses undefined variable \(variable)")
                }
            }
        }
    }
    // ... three hundred more lines ...
    if !errors.isEmpty { throw ValidationError(errors) }
}

It works. It also rots. Every new rule is another branch wedged into the same traversal. The error strings drift out of sync with the checks. Nobody can test a single rule in isolation, because there is no single rule, there is only the function. You cannot turn one check off without commenting out code. And the location of each failure is whatever you remembered to interpolate into the string, which is to say, inconsistent and usually wrong.

I stopped writing validators like this when I read Matt Polzin’s OpenAPIKit. His validation layer is the cleanest I have seen in Swift, and the core idea is one sentence:

A validation is not code you run. It is a value you build.

Once you take that seriously, everything else follows. This post is the whole idiom, distilled from how OpenAPIKit actually does it. I now hold every validation layer I write to it.

What OpenAPIKit is

OpenAPIKit is a Swift library for reading, writing, and validating OpenAPI documents. OpenAPI is the specification format that describes an HTTP API: its paths, operations, request and response bodies, schemas, servers, and components. The documents are usually written as large YAML or JSON files.

OpenAPIKit gives you three things, layered cleanly on top of each other:

1. A typed model of the entire OpenAPI specification. Every construct in the spec, OpenAPI.Document, OpenAPI.PathItem, Operation, Response, Server, JSONSchema, and the rest, is a real Swift type. Not a [String: Any] you index into and pray. A real type with real fields, so the compiler knows the shape of an OpenAPI document.

2. Codable conformance over that model. Because the model is Codable, you decode a YAML or JSON spec straight into OpenAPI.Document and encode it back out. The decoder is where the first wall of correctness lives: a document that is not even shaped like OpenAPI fails to decode at all. This is the “parse first” pass.

3. A validation subsystem over the decoded model. This is the part this post is about. Once you have a decoded OpenAPI.Document, you run a Validator over it to catch the semantic errors that decoding alone cannot: a $ref that points at a component that does not exist, an operation with no responses, a server URL template that uses a variable nobody defined. These are valid OpenAPI syntax describing an invalid document.

The validation code lives under Sources/OpenAPIKit/Validator/. The files worth reading are Validation.swift (the atom), Validator.swift (the engine and the default set), Validation+Builtins.swift (the shipped rules), and ReferenceValidations.swift (the reference-resolution rules). The tests under Tests/OpenAPIKitTests/Validator/ are as instructive as the source, and I will come back to them.

How you actually use it is three lines:

import OpenAPIKit
import Yams

let document = try YAMLDecoder().decode(OpenAPI.Document.self, from: yamlString)
try document.validate()   // throws a ValidationErrorCollection if anything is wrong

The first line is the parse pass. The second is the validate pass. Everything below is how that second line is built, and why it is built the way it is.

Parse first, validate second

The first move happens before any validation runs at all. Parsing and validation are two passes, not one.

The parser’s job is to turn bytes into a well typed value and to make as many illegal states as it can simply unrepresentable. An enum cannot hold a case that does not exist. A non-optional field cannot be missing. By the time you have a parsed Document, a whole category of “errors” is gone, because the type system refused to let them exist.

Validation runs after that, over the already typed value. It catches only what the types cannot or should not enforce: a server template that references a variable nobody defined, an operation with zero responses, a reference that points at a component that is not in the document. These are not type errors. They are semantic ones. They need their own pass.

If you find yourself validating inside the parser, stop. Parse to a clean value. Then validate the value.

A validation is a small struct of closures

Here is the atom. A Validation over some subject type carries three things:

• a description string,

• a check that produces errors,

• a predicate that decides whether this rule even applies here.

That is it. No inheritance, no protocol with ten requirements. A plain value you can build, store in an array, pass around, and combine.

The simplest one reads almost like English:

public static var operationsContainResponses: Validation<Operation> {
    .init(
        description: "Operations contain at least one response",
        check: \.responses.count > 0
    )
}

Look at what is not there. There is no traversal. This rule does not know how to find Operation values in a document, and it does not care. It only knows what a correct Operation looks like. The machinery finds every operation in the tree and offers each one to this rule. Dispatch is directed by the subject type: a Validation<Operation> fires on operations, wherever they appear, and is invisible to everything else.

The description states the correct state, never the failure

Read that description again: “Operations contain at least one response.” Positive. It describes the world when the rule is satisfied, not the world when it breaks.

This is deliberate, and it is one of my favorite details. You write the description once, phrased positively. When the rule fails, the framework derives the failure message by prefixing "Failed to satisfy: ". So you get:

Failed to satisfy: Operations contain at least one response

One source of truth, two readings. You never write the failure phrasing by hand, so the check and its message can never drift apart. Compare that to the if-tree above, where if responses.isEmpty and the string "has no responses" are two independent things you have to keep in agreement forever.

The description does more than format messages. It is the rule’s identity. Because rules are removed by matching their description, the description must be unique and stable. Which leads to the next piece.

Every error knows where it lives

An error is a reason plus a location:

ValidationError(reason: "Server Object does not define the variable 'x'", at: context.codingPath)

You supply the reason. You do not supply the location by hand. The traversal fills in the coding path as it walks, so by the time your check runs, context.codingPath already says exactly where in the tree you are. The rendered message comes out consistent every time:

… at path: .paths./hello/world.get.servers

or, at the top:

… at root of document

No more interpolating \(path).\(method) into strings and getting it subtly wrong. The path is bookkeeping the framework owns, not you.

Application is predicate gated

Every validation has a when: predicate that runs before the check, with the full context in hand. The default is “always.” But when a rule should only apply to a subset, you scope it with the predicate, not with an if inside the check body.

This matters because it keeps the check pure. The check answers “is this value correct,” full stop. The predicate answers “does this rule even apply here,” separately. A rule that only applies to OpenAPI 3.1 documents, or only to operations at a certain path, or only when some other field is present, says so in when: and keeps its check clean. Conditionals do not leak into the logic that decides pass or fail.

Two shapes, by how a value can fail

There are two ways to author the check, and the choice is mechanical.

If a value can fail one way, use the Bool form. You give a positive description and a predicate; false yields exactly one error, auto-formatted from the description. That operationsContainResponses rule above is this form. It is the dominant case.

If a single value can fail in several places at once, use the multi-error form and return one ValidationError per offender:

public static var serverVariablesAreDefined: Validation<Server> {
    .init(
        description: "All server template variables are defined",
        check: { context in
            context.subject.urlTemplate.variables
                .filter { !context.subject.variables.contains(key: $0) }
                .map { name in
                    ValidationError(
                        reason: "Server Object does not define the variable '\(name)'",
                        at: context.codingPath
                    )
                }
        }
    )
}

A server with three undefined variables produces three errors, each with its own reason and its own path. You do not collapse them into one “server is invalid” message, because then you would lose two thirds of the information about what to fix. The rule emits one error per problem.

A default set you can add to and subtract from

You ship two validators: a populated one with a curated default set, and a blank one with nothing. Builders are fluent and chainable. You compose your actual policy from the defaults, plus your own rules, minus the ones you do not want:

let validator = Validator()                       // the defaults
    .validating(.operationsContainResponses)      // add a builtin by name
    .validating(myCustomRule)                      // add your own
    .withoutValidating("All server template variables are defined")  // remove one by its description

This is why descriptions have to be unique and stable: the description is the removal key. withoutValidating matches on it. Rename a rule’s description and you have quietly changed its identity.

When strictness comes in grades, you model the grades as whole-set swaps on the validator, not as flags threaded through individual rules. OpenAPIKit does lenient reference checks by default, swaps in the strict set with validatingAllReferencesFoundInComponents(), and clears them with skippingReferenceValidations(). Three named configurations, not a strict: Bool smuggled into every check.

The combinator algebra

Because validations and their checks are values, you combine them with an algebra instead of nesting if statements. These are the moves I reach for:

• && / || combine checks. && concatenates both error lists; || short-circuits and only fails if both sides fail.

• comparison operators (==, >, >=, and friends) lift a key path and a literal into a predicate, so check: \.responses.count > 0 is a real expression, not a closure you wrote by hand.

• take(\.path) { value in ... } digs to a value and runs arbitrary logic past simple equality.

• lift(\.child, into: ...) runs child-typed validations against a child value while keeping the parent’s path and document. This is the key compositional move for nested structure.

• unwrap(\.optional, into:description:) unwraps an optional, erroring if nil, otherwise running child validations on the unwrapped value.

• lookup / unwrapAndLookup resolve a reference against the document’s component store, error if it is not found, otherwise validate the resolved value.

• all(validations...) applies many validations to the same context.

So a compound rule reads declaratively:

check: \.responseOutcomes.count >= 1
    && { $0.subject.responseOutcomes.allSatisfy { $0.status == 200 } }

You are describing what correct looks like by composing pieces, not writing a traversal.

Test the rules, the machinery, and the set

The test style mirrors the philosophy, and OpenAPIKit’s bar here is the part most people skip. There are three layers to it.

Every rule gets a failing and a succeeding test. Not just “here is a broken document, does it throw.” Also “here is a document that almost trips the rule but does not.” The succeeding fixture is a near miss, the value sitting exactly at the boundary the rule guards. A rule tested only in its failing direction is untested, because nothing proves it stays quiet on valid input. Assert the thrown collection’s exact count, each reason (including the "Failed to satisfy: " prefix), and each coding path:

func test_serverCountCheckFails() {
    let document = // ... seed the failing case
    let validator = Validator.blank
        .validating("All server arrays have more than 1 server", check: \[Server].count > 1)
    XCTAssertThrowsError(try document.validate(using: validator)) { error in
        let error = error as? ValidationErrorCollection
        XCTAssertEqual(error?.values.count, 1)
        XCTAssertEqual(error?.values.first?.reason,
                       "Failed to satisfy: All server arrays have more than 1 server")
        XCTAssertEqual(error?.values.first?.codingPath.map(\.stringValue),
                       ["paths", "/hello/world", "get", "servers"])
    }
}

The machinery gets its own negative tests. The type-erased wrapper that filters by runtime type has to be proven correct on its own: an optional subject yields no errors, a wrong type yields no errors, a false predicate yields no errors. And one positive control, the same value of the same type appearing twice yields two errors, to prove those negatives are not vacuously passing.

The configuration is pinned. A test asserts the exact, ordered list of active rule descriptions for every validator configuration. blank is empty. The full default set is pinned description by description. This means you cannot add, remove, or reword a rule without a test failing first, which forces every such change to be deliberate rather than accidental.

The point of all this is that a validator can pass every test it ships and still be incomplete, if some field of the input model never got a rule at all. So the final discipline is a coverage law: keep a registry of every field the model can carry, and a meta-test that fails if any field lacks either a validation or an explicit “unsupported, and here is why” classification. Silent gaps get caught mechanically, not in review.

Why I hold everything to this now

I do not treat this as an OpenAPI trick. I treat it as the standard for any validation layer over any parsed model: a config, a manifest, an HTML tree, a schema, a feature model. One framework, parameterized over both the subject and the document, reused by every layer instead of copied per layer. Each rule a named, removable, isolation-testable value with a positive description. Errors that carry their own location. Combinators instead of conditionals.

The if-tree at the top of this post produces correct results. That is not the bar. The bar is whether you can add a rule without touching a three-hundred-line function, turn one off by name, test it alone, and trust that its failure message points at the right place. The if-tree fails all four. Validations as values pass all four, and they do it because the design made the right thing the easy thing.

Parse first. Then build your validations as values.

Credit where it is due: this entire idiom is Matt Polzin’s. Go read Sources/OpenAPIKit/Validator/. It is some of the most quietly excellent Swift in the ecosystem.

“Swift runs everywhere” is usually a slide. A roadmap bullet, a conference promise, a footnote about a port someone started. I wanted to know what it looks like when it is not a slide, so I held my own projects to it: every platform claim must be a CI gate that runs on every push, and at least one build per project must be something you can click right now.

Four projects pass that bar today. A static site generator, a Markdown to PDF engine, a YAML parser, and a 2D vector graphics engine. All pure Swift. Between them they cover macOS, Linux, Windows, and the browser.

Exhibit one: the page you are reading

This site is built by TileDown, a static site generator written in Swift. The math on my posts is typeset to SVG at build time, the charts and diagrams are fenced text blocks rendered by the engine, and every article ships its own PDF from the same Markdown source. I wrote about the why in Why I built TileDown.

The part that belongs in this post is the CI table. On every push, TileDown builds and tests on macOS and on Linux in a Swift 6.1 container, the core targets build on Windows, and the math playground product cross-compiles to wasm32-unknown-wasip1 with the official Swift WebAssembly SDK. Four platforms, four green gates, one codebase. The generator that produced this page would produce it on a Linux box just as happily.

Exhibit two: a PDF engine in your browser tab

pdf.aleahim.com is MarkdownPDF compiled to WebAssembly. Type Markdown on the left, get a real PDF on the right, with no server involved. The engine parses the Markdown, lays out the document, and writes the PDF bytes directly in Swift, no LaTeX, no headless browser, no C library underneath. The wasm ships gzipped at about eighteen megabytes, downloads once, and is cached after that.

The same engine runs the full witness test suite on macOS and Linux, where the output PDFs are checked by independent tools including veraPDF for PDF/UA and PDF/A conformance. Windows and WebAssembly are build gates that compile the engine on every push. I covered the engine itself in Markdown to PDF in your browser, in pure Swift.

Exhibit three: a YAML parser with receipts

PureYAML is a dependency-free YAML package: no external SwiftPM dependencies, no bundled C sources, and no Foundation requirement in the library target. Its single CI workflow gates macOS, Linux, Windows, and WASI on every push.

Correctness is measured, not asserted. A comparison harness runs PureYAML and Yams side by side over a corpus of 111 real-world documents, OpenAPI specs, Kubernetes manifests, GitHub Actions workflows. In the latest checked-in run both parsers accept the same 110 documents and reject the same intentionally damaged one, with zero disagreements between them.

And because a CI badge is less fun than a demo, there is a live streaming benchmark that fetches multi-megabyte YAML files and parses them as streams, in Swift, inside your browser tab, reporting fetch time, parse time, and throughput as it goes.

Exhibit four: a graphics engine that brings its own canvas

PureDraw is a dependency-free 2D vector graphics engine, a “Virtual PostScript Machine” with an API compatible with CoreGraphics and the HTML5 Canvas, written without either of them. Zero external dependencies, zero bundled C sources, no Foundation requirement in the core. The capability showcase at the top of its README, a bezier-path character, gradients, blend modes, shadows, a 3D cube with a projective grid texture, is a PDF rendered entirely by the engine itself, from the test suite.

This is the project where portability earns its keep most visibly: graphics is the domain everyone assumes belongs to the platform. PureDraw builds and runs its full test suite on macOS, on Linux in a Swift container, and on Windows, in both debug and release, and the library cross-compiles to WebAssembly on every push. The drawings that come out are the same bytes everywhere, because nothing underneath them belongs to any one platform.

And you do not have to take the CI’s word for any of it. That badge is not a video. It is a few lines of PureComposition, a small language with a grammar of its own, compiled and rendered frame by frame. Glow Draw runs the same engines as WebAssembly right in your browser tab. PureDraw is CoreGraphics rebuilt from nothing, PureLayer is CoreAnimation rebuilt the same way, and PureComposition is the language that drives them: an EBNF grammar, a parser, a compiler that lowers it to a PureDraw virtual-machine program, and a command-line engine that runs the whole pipeline with no Mac in sight. The drawing API, the layer compositor, and the language on top, all reconstructed in portable Swift. If rebuilding Apple’s graphics stack from first principles is the kind of problem you would want to talk about, get in touch.

If Swift is your language and you have been told it stops at the Mac, the CI logs say otherwise.

There is a playground at pdf.aleahim.com. Type Markdown on the left, get a real PDF on the right. No server is involved. The PDF is produced by a pure-Swift engine compiled to WebAssembly and run inside your browser.

What it is

MarkdownPDF turns Markdown into a PDF with no LaTeX, no headless browser, and no C Markdown or PDF library underneath. It parses the Markdown, lays the document out, and writes the PDF bytes directly in Swift. It runs on macOS and Linux, the core also builds for Windows and WebAssembly, and that last one is what makes the in-browser demo possible.

The reason I wanted this: every Markdown to PDF path I tried pulled in something heavy. A browser to print from, a full LaTeX distribution, or a C library bound into the build. I wanted one Swift package that takes Markdown and emits the PDF, so it drops into a server or an app with nothing to provision on the machine.

What it renders

In one codebase:

• A TeX-style math subset. Fractions, radicals, superscripts, and big-operator limits lay out as real two-dimensional math. The quadratic formula and a several-rows-tall continued fraction are in the default sample.

• Native vector charts: bar, line, pie, and scatter, drawn with PDF path operators rather than rasterized images.

• A Mermaid flowchart subset, drawn as native PDF shapes.

• Embedded TrueType subsetting, DEFLATE compression, tagged PDF, and PDF/UA and PDF/A profiles checked with veraPDF on a fixture corpus.

Headings, lists, tables, code blocks with syntax highlighting, links, and images are all there too.

How it runs in the browser

The browser demo is small. There is a tiny executable that reads Markdown from standard input, renders it, and writes the PDF bytes to standard output. That executable is compiled to wasm32-unknown-wasip1. In the page, a WASI shim runs the wasm, feeds the text area in as stdin, and captures stdout as the PDF, which is shown in an iframe with a download fallback.

Two things were worth getting right. The wasm has to be instantiated asynchronously, because synchronous instantiation is disallowed on the main thread for modules over eight megabytes. And the engine is large, so the playground ships a gzipped wasm, about eighteen megabytes on the wire, and inflates it in the browser. First load downloads it once, then it is cached.

The pieces, and where they live

The work is split into focused packages, each open source under MIT:

• The engine: MarkdownPDF. The parser, layout, and PDF byte serialization.

• The math: MathTypeset. A dependency-free Swift math typesetting package. It is its own package because a static site generator I work on shares it, so the same TeX source typesets the same way whether the target is a web page or a PDF.

• The command line: MarkdownPDFCli. markdownpdf input.md output.pdf and a resume variant.

• The playground: pdf.aleahim.com, with source at markdownpdf-playground. The wasm build, the WASI harness, and the page itself.

There are no third-party runtime dependencies. The only package the engine pulls in is my own MathTypeset, which itself has none.

Honest limits

It is early and I say so. Math renders with an embedded Latin Modern Math font, so plus-minus, sigma, radicals, and Greek come out as real glyphs, not ASCII. One wrinkle worth noting: the engine embeds TrueType (glyf) fonts only for now, and Latin Modern Math ships as OpenType CFF, so the playground bundles a TrueType conversion of it (the MATH table is preserved). The full witness test suite runs on macOS and Linux; Windows and WebAssembly are build gates that compile the engine but do not yet run the suite. Text beyond Western European needs a supplied font, and shaping for Arabic and Hebrew is the open frontier where help is welcome.

Try it

The demo is at pdf.aleahim.com, the engine is at codeberg.org/Mihaela/MarkdownPDF. If you render Markdown to PDF anywhere that you would rather not install a browser or a LaTeX stack, this might fit.

I already had a static site generator. It was small, fast, and pleasant, and for a while that was enough. Then I started wanting things it was never going to give me, and every workaround made the setup more fragile instead of less.

So I wrote down what I actually wanted from a blog. It turned into a short, stubborn list.

I wanted diagrams in the prose

Not screenshots of diagrams. Not a separate tool that exports a PNG I have to keep in sync by hand. A fenced block, in the article, that renders:

graph TD
  Idea[I want to explain a flow] --> Tool{Does my generator do diagrams?}
  Tool -->|No| Screenshot[Export a PNG forever]
  Tool -->|Yes| Inline[Write it in the post]
  Screenshot --> Stale[It drifts out of date]
  Inline --> Done[It stays with the text]

I wanted charts that are just text

Same idea, numbers instead of boxes. I describe the data in a few lines and the build hands me a static SVG. No chart library, no script tag, no runtime:

The numbers are invented. The rendering is real, and it uses the same notation the PDF side understands, which matters for the next part.

I wanted the PDF of the article, for free

If you are reading this on the site, there is a Download PDF button near the top of the page. I did not build it by hand for this post. The same engine that lays out this page lays out a print version, from the same Markdown, so every article ships a PDF without me thinking about it.

I wanted real math

Typeset at build time into static SVG, themed to the page. No MathJax, no web font, no LaTeX install:

And I wanted a way out of “static forever”

This is the part that made it a project instead of a config file. Static sites are wonderful until the day you want one live thing on the page: a counter, an embed, a form that talks to a backend. Most generators answer that with “drop in some JavaScript and good luck.”

I wanted that one live thing to be a first-class, typed unit of content. So TileDown has tiles. A tile renders to HTML, scoped CSS, and only the JavaScript it needs, and nothing else on the page pays for it. Here is one:

Today tiles cover the client-side cases: counters, embeds, callouts. The next step is tiles that talk to a backend, a form that hits a real service, and that work is still coming. But the model is the point. Dynamic behavior is a tile, not a hole I cut in the static output.

That is the whole reason

Diagrams, charts, a free PDF, real math, and a typed path to dynamic content. None of those is exotic on its own. I just could not get all of them from one tool without the setup fighting me, so I built the tool. This post is written in plain Markdown and rendered by it.

brew install tiledown/tap/tiledown

I want OpenAPIDoctor to become a no-backend browser tool.

The product shape is right. A user should be able to paste or upload an OpenAPI spec, run the same strict Swift validator locally in the browser, see structured diagnostics, repair the safe cases, and download the fixed spec. No upload. No server. No account.

The only honest way to test that idea is to ask the compiler.

What I tested

Native build first:

swift build

That passed with Apple Swift 6.2.

Then I tested the installed WASI SDK:

swift build \
  --target OpenAPIDoctor \
  --swift-sdk 6.2-RELEASE-wasm32-unknown-wasip1 \
  --scratch-path /tmp/openapidoctor-wasm-library

And the CLI shape:

swift build \
  --product openapi-doctor \
  --swift-sdk 6.2-RELEASE-wasm32-unknown-wasip1 \
  --scratch-path /tmp/openapidoctor-wasm-cli

Both failed before OpenAPIDoctor itself compiled.

The blocker

The first blocker is Yams, specifically its embedded CYaml C target:

error: unable to create target:
'No available targets are compatible with triple "wasm32-unknown-wasip1"'

I confirmed it directly by building Yams for the same SDK. It fails in the C parser files: parser.c, reader.c, writer.c, api.c, emitter.c, and scanner.c.

I also tried a tiny C compile with the same target:

clang --target=wasm32-unknown-wasip1

That failed with the same target-support error. So the current local toolchain cannot compile the C YAML dependency to WASI.

What this means

OpenAPIDoctor is not WebAssembly-ready as it exists today.

That does not kill the idea. It narrows the work.

The core shape is still good:

• Validator.validate(yaml:) already accepts an in-memory string.

• Repairer.repair(yaml:) already returns repaired YAML in memory.

• The native CLI is just a composition layer around those APIs.

• The right browser boundary is a WASI command: stdin in, diagnostics or files out.

The weak point is YAML infrastructure.

OpenAPIDoctor imports Yams in the validator, repairer, and synthesizer. It also uses Stitcher for multi-file refs, and Stitcher depends on Yams too. That means a browser build needs a YAML path that can cross to WASI.

The next path

There are three practical options.

1. Test again inside the Linux SwiftWasm toolchain we use for the TileDown playground builds. If that environment can compile C targets to WASI, then the next blocker will be runtime behavior.

2. Replace or isolate the YAML layer behind a WebAssembly-friendly interface. Single-file diagnosis could start with a smaller path before multi-file repair.

3. Add an OpenAPIDoctor WASI wrapper only after the dependency question is settled. The wrapper should read the spec from stdin and write JSON diagnostics to stdout.

The browser product should not use custom JavaScript exports. The better pattern is the same one that already works for the PDF playground:

stdin + argv + preopened files/directories -> stdout or output files

That keeps the Swift code shaped like a normal command-line program and lets the browser provide an in-memory filesystem.

Current verdict

OpenAPIDoctor is product-ready as a local-first browser idea, but not yet compiler-ready for WebAssembly.

The first concrete task is not UI. It is a dependency build proof for OpenAPIKit, Yams, and Stitcher under WASI. Only after that should the web tool be wrapped as a TileDown WASM tile or a standalone site.

This release started with a number that looked too small to matter.

Back in v1.2.0 I had added deployment-aware search: ask cupertino for an API and tell it which OS you actually ship, and it filters out the answers that would not compile for you.

cupertino search swiftui --source samples --min-ios 16

The flag parsed. The database carried availability metadata. The command looked completely right. And yet, in the dev corpus, --min-ios handed back the same 88 results whether I asked for iOS 13 or iOS 18. A filter that returns the same set for every value is not filtering. It is decoration.

That is the kind of bug that looks like a one-line fix until you ask why it was possible at all.

A filter that does not filter is worse than no filter. It lets an assistant claim it respected your deployment target while quietly handing you an iOS 18 API for an app that still ships iOS 16. That is not an answer. It is a future compile error wearing a green checkmark.

I could have found the missing parameter, threaded it through the one path that dropped it, added a test, and shipped. One path fixed. The reason that path could go missing in the first place: untouched.

So I pulled on it instead.

The problem under the bug

cupertino had outgrown the shape it was born in.

Early on, the whole thing fit one mental model: a big Apple documentation index with a few extra sources bolted on. Apple Developer Documentation, the HIG, Apple Archive, Swift Evolution, swift.org, and The Swift Programming Language all lived inside a single SQLite file. Samples and packages had their own databases, but most of the command surface still thought in three buckets:

• search.db

• samples.db

• packages.db

That shape was fine when the project was small. It quietly stopped being fine the moment cupertino became a genuine multi-source tool, and the symptoms were everywhere if you knew to look. A platform filter honored in one source and silently dropped in another. A doctor probe pointed at a database filename that a per-source build no longer produced. A release script that knew the names of its databases by heart.

Those were not five unrelated bugs. They were one disease with five rashes. Source identity was scattered across CLI switches, MCP handlers, setup checks, release manifests, and tests, each carrying its own hand-copied list of names. Change the world in one place and the other four kept believing the old map.

The cure was already half-built. The Source Independence Day effort had been pushing toward a single source of truth in code: a registry every part of the system reads from, so adding a content source becomes one composition-root change instead of a scavenger hunt. The code was moving that way. The shipped artifact was not. The bundle users actually installed still wore the old three-bucket shape.

So v1.3.0 became the release that drags the artifact up to meet the architecture.

Not because retiring a database filename is exciting. It is not. Nobody installs cupertino to admire the shape of its SQLite files. It matters because that old shape was a tax. Every new source paid it. Every cross-source feature paid it. v1.3.0 is the refactor that stops collecting it.

One registry, eight databases

In v1.3.0 a source is no longer a string in a source column.

It is a registered provider that declares everything about itself: where its data lives, how it fetches, how it reads, how it searches, which metadata it carries, and which filters it can honestly apply. One registry holds them all, and the rest of the system asks the registry instead of remembering.

The release bundle now matches that model exactly. Instead of one giant docs database plus two siblings, v1.3.0 ships eight per-source databases:

• apple-documentation.db

• hig.db

• apple-archive.db

• swift-evolution.db

• swift-org.db

• swift-book.db

• apple-sample-code.db

• packages.db

cupertino setup downloads cupertino-databases-v1.3.0.zip, a 742 MB bundle that expands to about 3.9 GB. Most of that is one file: apple-documentation.db weighs 2.6 GB and holds 351,505 documents and 240,543 symbols across 398 frameworks. Next is packages.db at 1.0 GB with 185 packages. The HIG, archive, Swift Evolution, swift.org, and Swift book databases are the small ones, a few megabytes each.

The split is not cosmetic. It changes what can go wrong independently. If the HIG corpus is stale, the HIG database is stale and Apple API search is not dragged down with it. If packages need a schema bump, packages get one without reindexing everything else. And when a new source lands, the release tool derives its database straight from the registry. No human goes hunting for the one more filename list that forgot to grow.

Users never see any of this. The fan-out search surface stays exactly as simple as it was. Underneath, SmartQuery dispatches across the independent source databases and fuses the results with reciprocal rank fusion, so one source can degrade without taking the whole query down with it. That is the trade the refactor buys: invisible to the person typing a query, decisive for the person adding the next source.

The old public shape had to break

Some flags described a world that no longer exists, so they had to go.

The legacy --search-db override is gone from all six commands that carried it: search, read, save, doctor, list-frameworks, and inheritance. It made sense when there was one docs database to point at. It is meaningless when every source resolves through the registry to its own file, and keeping it around would only preserve the wrong mental model. Scripts that still pass --search-db now get a clear error instead of a silent misread.

The same honesty went inward. Roughly 230 searchDB and searchDb identifiers across the CLI, services, indexer, and search layers became the generic dbURL and dbPath, because there is no longer a single “the db” to name. The release tool stopped bundling a hardcoded trio of filenames and now asks the production registry for every enabled source’s destination database. And databaseVersion moved to 1.3.0, so a v1.3.0 binary pulls the per-source bundle while a v1.2.x binary keeps pulling the old unified one. Upgrades and downgrades both land on a bundle they understand.

The one place the literal search.db name survives is the upgrade shim, which has to recognize a real pre-v1.3.0 file by its old name in order to migrate it. Everywhere else, the old name is finally just history.

Then SQLite made the refactor earn it

Splitting the bundle uncovered a second bug, the kind that only appears once you change how the file is born.

The indexers build databases in WAL mode, which is great for local write workloads and awkward for a static read-only artifact. A freshly extracted WAL database usually arrives with no -shm sidecar, and a plain SQLITE_OPEN_READONLY cannot open it without conjuring that shared-memory state first. So a shipped database could be byte-for-byte intact, pass an integrity check, and still refuse to open on a clean install.

packages.db made it impossible to ignore. On a fresh setup, package search would report the database as unopenable while the file sat right there, perfectly valid.

v1.3.0 fixes the artifact instead of teaching every reader a workaround. The release tool converts each bundled database to rollback journal mode before zipping, and rollback-mode databases open read-only with no -shm or -wal sidecar required. Then every query, read, and serve path opens through one shared helper, SQLiteSupport.openReadOnly(at:), using SQLITE_OPEN_READONLY. SELECT works. INSERT, UPDATE, DELETE, and any DDL fail with SQLITE_READONLY. The indexer and the setup migrator are the only writers; ordinary search and MCP reads physically cannot mutate the cache they read from.

That is the invariant I want under a local documentation tool. The thing you query is the thing you shipped, and nothing in the read path can quietly rewrite it.

I did not trust any of this without batteries

The frightening part of a refactor this wide is never the code you remember touching. It is the assumption asleep in a path you forgot existed.

So v1.3.0 leans on tests that behave more like release audits than unit checks.

DatabaseBundleManifestTests proves the bundle is derived from the production registry and excludes the retired search.db. searchDBFlagRejectedEverywhere proves the removed flag errors on every one of the six commands that used to take it. ConvertToRollbackJournalTests reproduces the WAL no-sidecar failure, then proves rollback conversion cures it. SQLiteSupportReadOnlyTests proves the shared helper can read and cannot write. Issue1190PackageQueryReadOnlyOpenTests proves a shipped rollback-mode packages.db answers a query the instant setup finishes.

Then come the snapshot batteries, which run the real CLI against the real shipped databases.

ReadOnlyReadBatteryTests drives the actual binary across all eight databases through the read-only path, searching every source and then performing at least twenty reads from each. The assertions check shape, not whether the output was simply long enough to look alive.

ExhaustiveEnrichmentBatteryTests covers all 24 enrichments from the project’s enrichment inventory. Sixteen of them are proven end to end through the real CLI: lexical search, AST symbols, generic constraints, framework aliasing, conformances, inheritance, rank fusion, exact-title reranking, deployment floors for every --min platform, structured reads, and code examples. The other eight are internal columns the CLI never surfaces, so they are proven directly against the database with row-count probes rather than pretended through a command that cannot show them. The run writes the actual output into an HTML report, because a feature is not real until the artifact users install can demonstrate it.

That is the whole point of a battery. The local corpus is the product, so the product has to prove itself against the corpus, not against a mock that always agrees.

One more footgun, while I was in there

The refactor also exposed a package-fetch default that had quietly stopped making sense.

Before v1.3.0:

cupertino fetch --source packages

refreshed Swift Package Index metadata and star counts for 10,995 packages and then downloaded the curated archive closure the indexer actually consumes. The metadata refresh can take around four hours without a GITHUB_TOKEN. The archive stage took about 97 seconds for the 185-archive closure on a clean base. The four-hour stage was not the one doing the load-bearing work.

So the default flipped. Now cupertino fetch --source packages just downloads the archives. If you want the metadata refresh, you ask for it:

cupertino fetch --source packages --refresh-metadata

The old --skip-metadata flag is gone, because skipping metadata is no longer the exception. It is the default.

The boundary work continues

v1.3.0 also documents three public Swift packages factored out of cupertino: SwiftMCPCore, SwiftMCPClient, and CupertinoDataKit.

CupertinoDataKit is the one that belongs to this release’s theme. It is the public read contract: the documentation and sample-code read protocols plus the value types they return. cupertino re-exports it through SearchModels, so the in-repo names stay put while the boundary becomes something real and external rather than implied.

It is the same move as the database split, applied to code instead of files. Name the boundary out loud. Make the system derive from it. Stop asking every caller to carry the old map in its head.

Upgrade

brew upgrade cupertino
cupertino setup

setup pulls the v1.3.0 per-source bundle. After that, search, read, and MCP serve all open the shipped databases read-only.

Here is the short version. Source independence has always been a code goal, and it is still a work in progress there. v1.3.0 is the release where it stops being only a code goal and starts being true of the artifact you actually install: eight databases, one registry, nothing in the read path that can rewrite them, and no unified search.db left to leak the old shape back in.

And the ninth database, whenever a new source earns one, is now a registry entry away instead of a refactor. That door is open now. I will walk through it soon.

That is why this one is The Big Refactor.

Swift is for the Eloi.

That is the cynical reading. There is a ladder here, and every rung hides more than the last:

• C: too dangerous. Pointers, manual memory, undefined behavior.

• Objective-C: too dynamic. A runtime that will happily message a deallocated object and crash you in production.

• Swift: safe by default, but the pointers are still there if you go looking.

• Swift 6 strict concurrency: the compiler now walks you across every actor boundary so you never have to reason about a data race yourself.

• SwiftUI: declarative. Stop thinking about the render loop.

• SwiftData: persistence without ever learning what an object graph is.

Most developers shipping apps today have never typed CALayer, because SwiftUI just works. Until it doesn’t.

It is tempting to call this condescension: the toolmakers kept the real tools and handed us the Fisher-Price version. It is a satisfying story. It is also wrong.

The man who built both ends

Core Animation was created by an Apple engineer named John Harper, and it is older than the device that made it famous. He built it under the codename “LayerKit”, and Apple was already showing it running on the Mac at WWDC 2006, months before the iPhone was announced. The foundational patent, US 8,130,226 (“Framework for Graphics Animation and Compositing Operations”), traces its priority to an application filed on August 4, 2006, and its own text still notes that “Core Animation” is just the “LayerKit” of that earlier filing. It reached the public in 2007: in the first iPhone OS, and later that year on the Mac in OS X 10.5 Leopard.

He left for Facebook in 2014. He came back to Apple and co-built SwiftUI: at WWDC 2019 he was on stage in “Building Custom Views with SwiftUI”, explaining how the view system actually works.

The person who built the rendering foundation that shipped in 2007 was, twelve years later, on the team building the declarative layer that sits on top of it. The same hands on both ends of the abstraction.

A Morlock in the daylight.

SwiftUI is not what happens when the serious engineers go build silicon and leave the toy framework to someone junior. It is what happens when the people who understand the foundation best decide what you should usually not have to think about. The implicit animation system, the idea that a state change should animate by default, that you declare what the UI is and let the framework diff and interpolate, is not a dumbing-down of Core Animation. It is Core Animation’s own philosophy, made the default instead of the opt-in.

The foundations never left

Of all of Apple’s low-level frameworks, almost everything named Core is written in C and meant to be called from anywhere: Core Graphics, Core Text, Core Audio, Core Foundation. Close to the metal, language-agnostic, no object model in the way.

Two are different. Core Animation and Core Data are written in Objective-C, object-model frameworks built around a tree of objects rather than a bag of C functions: Core Animation with its layer tree, Core Data with its managed-object graph. They were designed object-first because the problems they solve are object-shaped.

Those two still do not have Swift-native replacements. SwiftUI does not replace Core Animation. It sits on top of it. Your .animation() modifier drives a CAAnimation. Your view hierarchy resolves to a layer tree and a render server that has been doing this job, more or less unchanged, since 2007. SwiftData does the same thing to Core Data. The friendly declarative surface is new. The foundation underneath is the same machine it always was.

Core Animation did not need to change, because it was right the first time. The layer tree, the split between the model tree and the presentation tree, the separate render process, the implicit transactions: all still there, all still doing the work. What SwiftUI replaced was not Core Animation. It was UIKit’s interface to Core Animation: the manual animation blocks, the animator APIs, the layout system that had accreted cruft for a decade. The part that aged badly was how we talked to the machine, not the machine.

So what is the truth we can’t handle?

It is not that we are too stupid for pointers. Plenty of us could learn the layer tree in a weekend.

The truth is quieter: the foundation is still there, you have just stopped being able to see it, and that is a debt, not a gift. It comes due on the specific day SwiftUI does something you cannot explain. A frame that drops. An animation that fights itself. A view that will not redraw when every rule you know says it should. On that day the abstraction has failed, and the only people who can fix it are the ones who know what is underneath: the layer tree, implicit versus explicit animation, transforms, compositing, the render server.

Apple did not give us Swift and SwiftUI because we are too soft for the real thing. They gave them to us because the people who built the real thing learned, over fifteen years, which parts you genuinely should not have to touch most days. That is not contempt. It is the opposite. It is mastery deciding the default.

A good enough abstraction does not insult you. It just makes you comfortable on the surface, and helpless the day the machinery underneath asks whether you were paying attention. The layer tree is a weekend’s study. Learn it before the day you need it, because the framework will not tell you, in advance, which kind of day today is.

Released 2026-05-21.

What you actually get

If you’ve ever asked an AI coding assistant about a Swift API and watched it confidently invent a method that doesn’t exist (or point you at a deprecated 2017 version), cupertino is what I built for that.

This release: AI assistants using cupertino now land the right Apple documentation page on the first try 9 times out of 10. Was 5 out of 10 in v1.1.0.

A few concrete cases:

• Ask about URLSession async/await, get the modern API. Not the completion-handler page from 2017.

• Ask “what replaced NSURLConnection”, go straight to URLSession.

• Ask about @Observable, don’t get it fused with the older ObservableObject.

• Compare Combine and AsyncSequence, get both pages, not a hallucinated synthesis.

352,712 indexed Apple documentation pages, zero garbage rows on the merged corpus. Runs locally, no cloud, no subscription, free and open source.

Upgrade is one command:

brew upgrade cupertino && cupertino setup

The rest of this post is for the technically curious.

The measurement

Rank-1 accuracy on a 50-query canonical-lookup corpus (Swift stdlib types, Foundation, SwiftUI, UIKit, AppKit, Combine, framework roots) went from 52% in v1.1.0 to 92% in v1.2.0. Cross-validated on two more corpora, zero regressions across 110 paired queries, statistically significant at McNemar p ≤ 1e-5 on the largest corpus.

Three independent samples, same direction, similar effect size. Not a fluke.

Methodology lives at docs/design/search-quality-eval.md; per-query rank movements live in docs/audits. If a number is wrong in public, an audit markdown is wrong first.

How it works

cupertino is the retrieval layer of RAG, nothing else. The AI agent does the generation; cupertino just returns the right Apple page when one is asked for.

The substrate is SQLite FTS5 with field-weighted BM25, populated by an AST extraction pass at index time that pulls symbol signatures, generic constraints, platform availability, and deprecation markers into queryable columns. No embeddings, no vector database, no reranker.

Anthropic’s published RAG recipe (Contextual Retrieval, September 2024) keeps a BM25 stage alongside the dense one as the non-optional floor. cupertino takes that floor and runs it without the rest, on a corpus class where that’s enough: identifier-heavy, terminology-precise, Apple API docs.

What it still gets wrong

These were weak in v1.1.0 too. The next release is meant to move them. If it does, the live page will say so. If it doesn’t, the same page will say that, in the same row, without anyone editing copy.

This is not a feature roadmap. It is a list of things the tool does badly, published next to the things it does well.

Upgrade

brew upgrade cupertino
cupertino setup

cupertino setup pulls the v1.2.0 database bundle from GitHub. If you had v1.1.0 installed locally, the migrator handles the schema bumps idempotently.

Full release write-up: docs/release-writeup-v1.2.0.md. Source for every measurement: docs/audits/.

brew upgrade cupertino this week and your local Apple docs database is 7,095 documents richer and zero rows are HTTP error pages pretending to be documentation. You will not notice. Searches feel the same. cupertino doctor was already green. The MCP server returns the same shape.

That gap, between “looks fine” and “actually fine”, is the whole post.

TL;DR

brew update
brew upgrade cupertino
cupertino setup     # downloads cupertino-databases-v1.1.0.zip (685 MB)
cupertino doctor    # "Bundled version: 1.1.0", apple-docs: 284,518

Done. The rest is how I found out the index was lying to me.

The 3 a.m. query

I was confident about v1.0.2. Audit clean. Bundle rebuilt. Counts verified. Shipped.

Then I ran one more query against the v1.0.2 search.db, the kind you only run when you can’t sleep:

SELECT uri, title, abstract, source
FROM docs_metadata m JOIN docs_structured s ON s.uri = m.uri
WHERE s.title IN ('Forbidden', '403 Forbidden', '404 Not Found',
                  'Bad Gateway', '502 Bad Gateway');

One row came back.

uri:      swift-org://docc_documentation
title:    Forbidden
abstract: You don't have permission to access this resource.
source:   swift-org

That is not Apple’s DocC documentation. That is an HTTP 403 page indexed as canonical content for the DocC URL. Anyone querying cupertino for DocC would get a result with a correct URL, a plausible title, and a body of pure garbage. The worst kind of indexing bug: silent and authoritative.

The mistake was small and embarrassing. My poison scan walked ~/.cupertino/docs/. The bundle is built from six sibling directories. I had been auditing one out of six.

~/.cupertino/
  docs/             # 412k JSON files
  swift-evolution/  # 483 proposals
  swift-org/        # 196 pages    ← never scanned
  hig/              # 173 pages
  archive/          # 406 legacy guides
  packages/         # README files

Sweeping the full tree turned up six poison files in swift-org/. Five of them had been shipping in every prior release. Nobody had noticed. But the six was the small problem. The big problem: my scanning was wrong, and I had no idea what else was hiding in 412,523 other files.

The 13 ways Apple’s docs site poisons a crawler

I rebuilt the audit as a matrix: every pattern, every source, every file. Each row below came from a real failure I had already hit. None of it is theoretical.

Against every expectation, docs/ scanned clean across all 13. Earlier passes had actually stuck. The poison was concentrated in the small directories I had been ignoring.

(Quick footnote, since it cost me an hour. Category 13 is a byte read on 412k files. My first pass shelled out head -c 1 per file. Projected wall time: about five hours. Rewriting as a single Python os.walk that stats, opens, and reads one byte inside one process: 41 seconds. The per-file fork was the entire cost.)

How Apple’s docs site actually poisons your index

Three failure modes. In the order they fooled me.

Mode 1: the CDN returns an HTML error page at status 200. Title is 403 Forbidden. A five-line title check catches it. Done in PR #289 last release.

Mode 2: the SPA shell. Apple’s docs site is a client-rendered React app. Fetch without JS and you get a <noscript> blurb that politely asks you to enable JavaScript. v1.0.2 had 1,327 of these. PR #291 filtered them at indexing time, but it was scoped to the apple-docs path, which is exactly why the swift-org Forbidden row strolled past.

Mode 3: the one that ate my Tuesday. JavaScript runs. The React app boots. The React app’s data API returns 404 for the URL. The React app cheerfully renders its own 404 sub-view as the page body:

<h1>Apple Developer Documentation</h1>
<a href="#app-main">Skip Navigation</a>
<h1>The page you're looking for can't be found.</h1>
<input placeholder="Search developer.apple.com">

Title is generic. Body is the app announcing its own failure. No error markers. Status 200. HTML perfectly clean. Every defense I had waved this through, because from the network’s point of view Apple successfully served me a page. The page just happens to be Apple’s React app politely informing the user that the page doesn’t exist.

The fix that was missing

PR #432 is small. A substring check on the rendered HTML, before the crawler writes anything:

public static func looksLikeJavaScriptFallback(html: String) -> Bool {
    if html.contains("The page you're looking for can't be found") { return true }
    if html.contains("An unknown error occurred") { return true }
    return false
}

Both phrases live exclusively inside Apple’s no-content sub-views. Real docs do not quote either sentence. The check runs after WebKit renders, so it sees the same bytes that would have hit disk. If it returns true, the crawler logs a skip and walks away.

Every skip writes one JSONL row to <output>/.cupertino-rejected-urls.jsonl:

{"url":"https://developer.apple.com/documentation/.../fetch-apple",
 "framework":"accountorganizationaldatasharing",
 "reason":"js_fallback",
 "timestamp":"2026-05-13T11:53:42Z"}

This is the part I think generalizes. Once a poison file lands on disk, every downstream consumer has to re-discover that it’s poison. Catch it at write time and it is nobody’s problem ever again. The JSONL puts the visibility back: jq over it and you have a retry list, a recrawl set, or a bug-report folder.

Targeted recrawl of 51 known-poison URLs from v1.0.2: 48 rejection rows, all correctly tagged js_fallback, zero new files on disk. Pre-fix, the same set wrote 9 poison files in 90 seconds before I killed the run.

One false-positive risk worth naming. Two real Apple symbol pages quote “An unknown error occurred” in their Discussion section (cfnetworkserviceerrorunknown, generalinternalretryableerror). Both are already in the v1.1.0 bundle, but a future recrawl of those exact URLs would currently get rejected. Filed for v1.2: tighten the match so the phrase has to sit in a standalone position (h1, adjacent to Skip Navigation) rather than anywhere in the HTML.

The reindex

cupertino save --docs --clear on the cleaned corpus:

documents:           285,735       (84.7% of 351,249 source, rest deduped)
frameworks:          420
db size:             2.36 GB
defense trips:       0
errors:              0
warnings:            0
runtime:             9h 39m

The line I care about is defense trips: 0. Across 351,249 indexer reads the indexer-side gate from PR #291 did not fire once. The test wasn’t whether the defense works. The test was whether anything was left for it to filter. Nothing was.

(The 65,514 gap between source files and indexed rows is real deduplication. Apple’s docs ship hash-suffixed variants of overloaded methods (equatable_-3axv1_de895d6c.json) that all point at the same logical URL.)

The release saga, or: what databaseVersion actually does

This is the part I’d flag to anyone shipping a similar tool.

v1.1.0 first shipped tagged correctly, binary rebuilt correctly, bundle uploaded to a parallel GitHub release. I ran cupertino setup to test the upgrade. It cheerfully downloaded the old v1.0.2 bundle.

The bug was one line in Shared.Constants.swift:

public static let databaseVersion = "1.0.2"

cupertino setup builds the download URL from this constant:

{baseURL}/v{databaseVersion}/cupertino-databases-v{databaseVersion}.zip

The release-tooling commit had explicitly not bumped it, with a confident note: “databaseVersion stays at 1.0.2 (no schema/content change).” Schema-wise that was true. Content-wise it was a confident lie. The corpus was the cleanest it had ever been, the bundle was genuinely new, and the binary was politely asking the CDN for last week’s poisoned one.

Fix: one-line change, fix branch, squash-merge, force-move the v1.1.0 tag to the new HEAD. release.yml rebuilds, codesigns, notarizes, and replaces the assets on tag push. Then a Homebrew bump for the new tarball SHA. About 25 minutes of clock time once I noticed. Approximately 25 minutes of dignity, also gone.

The lesson: when the bundle changes, bump databaseVersion, even if the schema doesn’t. Otherwise your install path silently downgrades users to the previous bundle. No error. Doctor reports green. The binary asked for last week’s bundle, and last week’s bundle is exactly what it got.

What I’d take with me

HTTP 200 doesn’t mean “valid content.” It means the CDN served some bytes. Documentation, error page, noscript fallback, React 404 sub-view: your problem to tell apart. Title checks miss two of three.

Defense gates belong upstream. Catching poison at write time costs the same as catching it later, and prevents a class of bug instead of detecting one. Append an audit log so you keep the visibility.

Bump databaseVersion when the bundle changes, even if the schema doesn’t. Then run cupertino setup end-to-end before the release is “shipped.” Trust the binary, not the release notes.

If you want to try it:

brew tap cupertinohq/tap https://codeberg.org/CupertinoHQ/homebrew-tap.git
brew install cupertinohq/tap/cupertino    # or brew upgrade
cupertino setup
cupertino search "your favorite Apple symbol"

Three defense PRs: #289, #291, #432. About 350 lines of Swift including tests. The cleanup itself was one long afternoon of careful greps.

“The given data was not valid YAML.”

The first time I saw this error, the YAML was fine.

I had pasted ten kilobytes of perfectly formed OpenAPI into a generator, watched it crash, and squinted at a stack trace that very confidently told me my document was malformed. It wasn’t. The document was a well-indented, schema-valid spec that someone had hand-edited the week before. The actual problem was a single stray key on a Tag object, eleven levels down, which OpenAPIKit had quietly rejected and which Yams had then wrapped in a DecodingError.dataCorrupted carrying a debug message that had nothing to do with the actual cause. The real error lived in Context.underlyingError, three more layers in.

I lost an afternoon to that error. Then I lost a morning to it again, a week later, on a different spec. Then I built OpenAPIDoctor.

What spec-first Swift gets you, and what it costs

When you generate Swift code from an OpenAPI document, the document is no longer documentation that lags behind the code. It is the code. Apple’s swift-openapi-generator reads the spec, runs it through mattpolzin/OpenAPIKit, and emits typed Swift clients and servers from what it finds. Spec parses cleanly, the generated code compiles. Spec has any structural issue OpenAPIKit doesn’t like, the generator either fails outright or emits code that won’t compile.

That contract is what makes spec-first Swift worth doing. It is also what makes the spec a load-bearing artifact that nobody can afford to hand-edit carelessly. Which, of course, everybody does.

OpenAPIKit is a strict parser by design. It does not silently round-trip unknown keys, because that would let bugs through into your generated client. The trouble is that real-world specs accumulate small violations the moment more than one person edits them, or the moment anyone copy-pastes a fragment from another tool. A short, honest taxonomy:

• A Tag object carrying a slug: field. Not part of the spec. Strict parser rejects it.

• A Parameter with stray email: and phone: keys left behind by a half-finished refactor. Strict parser rejects them.

• nullable: true on a spec that has been migrated to OpenAPI 3.1, where the keyword is no longer valid. Strict parser rejects it.

• A response body declaring application/x-www-form-urlencoded, which the Swift OpenAPI runtime cannot serve. Parser accepts it; the runtime explodes downstream and writes you a different kind of letter.

Each violation is small. None is the sort of structural problem a code review catches. All of them surface as InconsistencyError from OpenAPIKit, which is the right thing for OpenAPIKit to do. The wrong thing is what tends to happen next: the caller gets a stack trace, fixes the first key by hand, runs the generator again, hits the next key, fixes that, runs again. On a single-file spec it is tedious. On a spec split across folders with shared schemas it is a half-day exercise that involves opening seventeen files and remembering which one you were in.

There are excellent OpenAPI linters in the JavaScript world. They are also not OpenAPIKit. If I lint with one tool and generate with another, I am postponing the failure, not preventing it. The validator had to be OpenAPIKit, end of debate.

What I wanted

The shape was small and specific:

1. Validate using the exact parser the generator uses. No second source of truth for “valid.”

2. Surface every failure as a typed value, not a stack trace.

3. Auto-repair the mechanical violations, with an audit trail of what changed.

4. Stop on the violations that need human judgement, and say clearly which ones.

5. Handle multi-file specs cleanly. Everything serious lives in more than one file.

6. Exit with codes a shell pipeline can use.

That list looks obvious in hindsight. It mostly is. The interesting part is what stands between you and it.

What OpenAPIDoctor does

OpenAPIDoctor is a Swift package and CLI built on OpenAPIKit and Yams. Three pieces, in increasing order of how much fun they were to write:

• A Validator that decodes the spec through OpenAPIKit and categorises every result.

• A SpecLoader that handles multi-file specs.

• A Repairer that runs validate, fix, revalidate in a loop until the spec is clean or it hits something it cannot touch.

Every result comes back as a DiagnosisKind. Six cases. Only one is auto-repairable:

• .ok: spec parses cleanly. Go home.

• .vendorExtensionPrefix(codingPath, invalidKeys, subjectName): an extensible OpenAPI object carries keys that are not in the type’s documented set and do not start with x-. The diagnosis carries the exact coding path and the exact keys to strip. isAutoRepairable == true.

• .inconsistency(codingPath, details, subjectName): every other InconsistencyError from OpenAPIKit. Unsupported openapi: version, malformed $ref: pointing at a component that does not exist. Needs a human.

• .decodingError(codingPath, details): Foundation-level type mismatch or missing required field. No title: on info:. Wrong type for version:. Needs a human.

• .fileError(details): the file is not there or cannot be read. Needs a different human.

• .unknown(details): escape hatch. Nobody is happy about this case existing, but the alternative is lying.

Having these as typed values changes how you write callers. You can pattern-match. You can ask diagnosis.kind.isAutoRepairable and route accordingly. From the CLI it looks like this:

$ openapi-doctor my-spec.yaml
{"status":"ok"}

$ openapi-doctor stray-tag-keys.yaml
{"codingPath":["tags","Index 0"],"invalidKeys":["slug","timezone"],"kind":"vendor-extension-prefix","status":"inconsistency","subject":"Vendor Extension"}

One line of JSON on stdout, always. Exit code 0 for clean, 1 for “fixable, try --fix”, 2 for “you need to edit this, or the file is missing.” Nothing to parse, nothing to grep through.

The seams of the abstraction

If you have read this far, you might enjoy the parts that didn’t come out as cleanly as the API suggests.

OpenAPIKit tells you which keys are invalid in English. The error message contains a sentence like Invalid properties: [slug, timezone]. There is no [String] accessor for those keys; they live inside the human-readable details string, sitting between two brackets, separated by commas. So OpenAPIDoctor parses them back out:

guard let openRange = details.range(of: "Invalid properties: [") else { return [] }
let after = details[openRange.upperBound...]
guard let closeRange = after.range(of: "]") else { return [] }
return after[..<closeRange.lowerBound]
    .split(separator: ",")
    .map { $0.trimmingCharacters(in: .whitespaces) }
    .filter { !$0.isEmpty }

This is honest engineering, not clever engineering. If OpenAPIKit ever exposes the rejected keys as structured data, this disappears in one commit. Until then, the seam is here and visible.

Same applies to the classification. A vendor-extension-prefix violation is identified by details.contains("vendor extension property"). A substring match against an error message. I am aware of how that looks. I am also aware that it has worked perfectly across 594 spec files and counting.

OpenAPIKit reports array positions as strings. A coding path looks like ["tags", "Index 0", "slug"]. The "Index 0" segment is a literal string, not an integer wrapped in Any. The walker that descends into the YAML to delete keys has to parse that string back into an Int:

static func parseIndex(_ segment: String) -> Int? {
    guard segment.hasPrefix("Index ") else { return nil }
    return Int(segment.dropFirst("Index ".count))
}

Small, dumb, real. If you have ever shipped a tool that runs against someone else’s API, you know that almost all of the work is small and dumb and real.

The 3.0 / 3.1 sniff. OpenAPIKit splits its Document types: OpenAPIKit.OpenAPI.Document is 3.1, OpenAPIKit30.OpenAPI.Document is 3.0. If you point the 3.1 decoder at a 3.0 spec, you get the immortal error "Failed to parse Document Version 3.0.x as one of OpenAPIKit's supported options." So OpenAPIDoctor scans the raw YAML for the openapi: line, picks a decoder, and only parses once. Cheap, deterministic, no second source of truth for what version the spec is.

Yams.dump doesn’t preserve key order. A comment in the Repairer is candid about it: “preserves enough of the structure for our auto-repair use case (the spec is regenerated on every round anyway). Stable key ordering isn’t guaranteed.” In the auto-repair flow this doesn’t matter, because the source of truth after a repair is the repaired YAML, and you read what was just written. In a workflow that diffs the result against the original, you’ll see ordering churn. That tradeoff is documented in the code, not hidden in a footnote.

Repair, round by round

The Repairer is my favourite part. It runs as a loop, capped at thirty rounds: validate, fix, revalidate, until either the spec is clean or it hits a diagnosis that is not auto-repairable. Each round removes exactly the keys OpenAPIKit reported, at exactly the coding path it reported them. No regex matches against the YAML, no guessing. A recursive walker descends to the target, deletes the listed keys from the dict at the leaf, and rebuilds the tree from the bottom up.

$ openapi-doctor --fix multi-stray.yaml
# stderr: one JSON per round, streamed as it happens
# {"removedKeys":["slug"],"round":1,...}
# {"removedKeys":["timezone","region"],"round":2,...}
# stdout: aggregate result
{"finalDiagnosis":"ok","roundsApplied":2,"status":"repaired","totalRemovedKeys":3,...}

The 30-round cap is not arbitrary, but it is generous. The worst-shaped spec I have thrown at it cleared in five. The cap is there so that if the validator and the YAML ever disagree about shape and the loop starts looking like progress that isn’t, the tool stops with a real diagnosis instead of running forever.

For a destructive-free survey of how broken a spec is, there’s a dry-run mode that uses the same loop but discards the repaired YAML, keeping only the list of diagnoses found along the way:

$ openapi-doctor --all my-spec.yaml 2>/tmp/diagnoses.jsonl
{"diagnosesFound":3,"fixableDiagnoses":2,"status":"ok","terminalKind":"ok"}

Internally, --all and --fix share the strip implementation. The Validator’s collectAll reaches into Repairer.stripKeys directly. One source of truth for “how do you remove a vendor extension key from a YAML tree.” That is the kind of taste that doesn’t show up in the README, which is exactly why I am putting it here.

--output <path> writes the repaired YAML to a side file and leaves the source untouched, useful for diffing before-and-after in CI. --corpus <dir> walks a directory of specs and reports per-file results with an aggregate summary, useful when you have inherited a folder of half-maintained specs and want a triage report before you touch anything.

The 594-file corpus

Multi-file specs are where the interesting bugs live. A serious API spans folders: a finance service that pulls ../core/parameters/id.yml; an analytics service that pulls ../core/schemas/apiError.yml; a ledger service that references both. OpenAPIKit expects one document. Without help, every external $ref would dangle.

The loader delegates to Stitcher, a separate library I published in November 2025 for exactly this problem. OpenAPIDoctor followed in May 2026 and took Stitcher as a dependency rather than re-implementing the resolver, which is the right division of labour: cross-file $ref resolution is a generic problem; OpenAPI validation is a specific one. Two libraries, two responsibilities, one composes the other.

To prove the two pieces actually agree about what “valid” means on the shape of spec I care about, the test suite drives an anonymised real-world corpus through the validator: 594 YAML files across 22 services, of which 146 contain at least one cross-folder ../ reference, all OpenAPI 3.0.3, the kind of layout you only get when humans have been editing for a year. The test asserts every entry point validates cleanly. When it does, I know Stitcher’s merged output and OpenAPIKit’s strict parser agree, in detail, across the whole tree, every commit.

You can flip Stitcher off with --no-resolve-refs, which loads the spec file as-is. Useful when the referenced files are not on disk, or when you want to isolate a problem to a single file and stop wondering if the resolver is the one lying to you.

Where it fits

OpenAPIDoctor is one stage in a longer code-generation pipeline I run. Specs come in. Validation happens. Generation happens. Swift compiles. There is nothing exotic about that flow except the requirement that every stage produces something the next stage can use, without surprises.

OpenAPIDoctor’s contract is the simplest in the chain. After it runs, the spec is either clean, or the caller knows exactly what is wrong with it, whether a tool can fix it, and where in the document the problem lives. That contract is what lets the rest of the pipeline be boring. Boring pipelines are the only kind that ship.

Where to find it

codeberg.org/Mihaela/OpenAPIDoctor, tagged at 1.0.0. MIT licensed. Library for embedding in your own pipeline, CLI for the shell:

.package(url: "https://codeberg.org/Mihaela/OpenAPIDoctor", from: "1.0.0"),

If you generate Swift from OpenAPI on anything bigger than a toy spec, you probably want this somewhere upstream of the generator. And if you ever see “The given data was not valid YAML.” in a stack trace, you now know two things: it is lying to you, and somebody already wrote the tool that tells you the truth.

A few weeks ago I shipped cupertino v1.0.1 and closed the bug that was supposed to make it impossible for the same Apple page to appear twice in the local search index. The release notes carried a confident sentence: “verified that the shipped v1.0.0 search.db has zero case-axis duplicate pairs.” The query that verified it returned empty across 405,782 rows. Done.

Today I shipped v1.0.2, which removes 128,142 of those rows. They were duplicates. They had been duplicates the whole time. The verification query was structurally incapable of seeing them.

Here is what happened, what v1.0.2 contains, and the three things I took away from the audit.

What v1.0.2 ships

Concrete numbers first.

So a third of the database was the same Apple page indexed twice, once under documentation/Swift/... and once under documentation/swift/..., with slightly different URI hashes so the rows did not look identical to a casual audit.

The fix is one canonicalization call inside URLUtilities.filename(_:). The bundle is a full reindex of 404,729 JSON pages, 12 hours 36 minutes wall-clock on an M4 Max. The schema version bumps from 12 to 13 so old databases get rejected at open with a “rebuild required” message that points at cupertino setup, which downloads the new clean bundle in seconds.

Two other things ride along in this release:

• Post-redirect URL canonicalization (#277), contributed by @Vignesh-Thangamariappan in PR #278. When Apple issues a 301/302 redirect (e.g. professional_video_applications to professional-video-applications), the crawler now files the page under the post-redirect URL instead of the request URL. Five regression tests plus an integration test against a mock redirect server. Thank you, Vignesh. This was a subtle bug to find and a careful PR to author.

• HTML link augmentation for sparse-references pages (#203, PR #281). The crawler now unions HTML <a href> links with DocC’s JSON references on pages where the JSON link count is below a configurable threshold. Catches operator overloads, legacy numeric-ID symbols, REST sub-paths, and the handful of frameworks Apple serves only as HTML.

Earlier groundwork on #200 (case-axis dedup at index time) came from @imwyvern, who supplied the crawler queue dedup, the dedup helper, and the URI alignment in PR #201. v1.0.2 builds on that work; the change here is finding the layer it missed.

The bug

Apple serves the same documentation page under multiple URL casings. The reference graph inside Apple’s DocC JSON is sometimes documentation/Swift/withTaskGroup(of:returning:isolation:body:) and sometimes the all-lowercase variant. Cupertino treats both as crawl targets. Pre-#283, the indexer would also treat them as separate pages, producing two rows in docs_metadata, two rows in docs_fts, two answers in the search results.

Wesley’s PR #201 in v1.0.1 fixed URLUtilities.normalize(_:) to lowercase the path, which was supposed to collapse these at queue time. It did, partially. There was a layer below the queue that #201 did not cover.

URLUtilities.filename(from:) is the function that turns a URL into an on-disk filename and, by extension, into the URI key used in docs_metadata. For URLs containing parens or colons (so, any Swift method signature with named parameters), it appends an 8-hex disambiguator hash. That hash was computed from the raw URL string, before the function’s internal lowercasing. So the same Apple page, fetched from two case-variant URLs, produced two different hash suffixes:

documentation/Swift/withTaskGroup(of:returning:isolation:body:)
  -> documentation_swift_withtaskgroup_of_returning_isolation_body_b9f71892

documentation/swift/withtaskgroup(of:returning:isolation:body:)
  -> documentation_swift_withtaskgroup_of_returning_isolation_body_969a5400

Different filename, different URI, two rows in the database, two cards in your search results.

The verification trap

This is the part that bothers me.

The v1.0.1 closure of #200 was not careless. It included a verification query, run against the actual shipped DB, with the explicit goal of confirming the bug was gone:

SELECT LOWER(uri), COUNT(*)
  FROM docs_metadata
  GROUP BY LOWER(uri)
  HAVING COUNT(*) > 1;
-- (returned empty across 405,782 rows)

Empty result, ship it. Felt rigorous. Was wrong.

The query is structurally incapable of finding the bug. The URIs in docs_metadata carry an 8-hex suffix that varies per source URL, so the case-variant pair documentation_swift_withtaskgroup_..._b9f71892 and documentation_swift_withtaskgroup_..._969a5400 lowercase to two different strings. GROUP BY LOWER(uri) cannot collapse them. It returns empty. It will always return empty no matter how broken the dedup is, because the column itself is wrong for the question.

The correct query is on docs_structured.url, which preserves the original Apple URL with its original casing:

SELECT 'clusters', COUNT(*) FROM (
  SELECT LOWER(url) FROM docs_structured
    GROUP BY LOWER(url) HAVING COUNT(*) > 1
);
-- clusters | 61257

Two columns, two completely different stories. One verification you would write because the index key obviously is the URI. One verification you would write because that is the column a human would look at to spot the duplicate.

This generalizes. The verification query for a data correctness fix has to come from the column where the bug would show up to a reader, not the column the data is keyed by. They look interchangeable until you realize that the key has been transformed by code that may itself be where the bug lives. If you verify in the transformed space, you verify against the same transformation that may be broken.

A simpler version of the same lesson: ask yourself which column a customer would email you about, not which column the code uses as its primary key.

What I learned

Three takeaways, in order of how much they cost me.

1. “Already fixed in vN” claims with a clean test are very compelling and very capable of being wrong.

I do not think Wesley or I were reckless. The #200 fix was real and good. The verification query passed. The release notes were faithful to what the query said. Everyone behaved sensibly. The query was still the wrong query.

What I want to internalize: in any audit that asserts “we checked the data and it’s clean”, the question is not just “what did the query return”, but “if the bug were present, would this exact query show it”. For data bugs, that means: which column does the bug live in, and is that the column the verifier looked at.

For this PR, I added a docs entry that explicitly names the wrong query and the right query, side by side, as a permanent footnote. Anyone reading the v1.0.0 release notes in five years can follow the link to see why the empty result was misleading.

2. The migration you built and then deleted is still good engineering.

I spent a real amount of time on an in-place v12 to v13 migration. The plan was: walk docs_metadata, recompute each URI through the post-#283 helper, group by canonical URI, pick the survivor by latest last_crawled, delete losers, rename survivors across docs_metadata + docs_structured + docs_fts + doc_symbols + doc_imports + doc_code_examples, all in one transaction with FK off. 270 lines of code, nine unit tests, three integration tests against a v12 fixture DB. The unit tests passed. The integration test passed on a 10-row fixture in milliseconds.

Then I ran it against my real 405k-row search.db. First attempt: over an hour, never committed, journal at 314 MB, killed it. Second attempt with prepared-statement reuse: marginally faster, journal at 415 MB at the 1h mark, killed it. Third attempt with PRAGMA journal_mode = MEMORY plus synchronous = OFF: another hour, never observably finished.

Meanwhile, cupertino setup downloads the pre-built v1.0.2 bundle in about thirty seconds. That is the path. Always was. The architecture already had the answer; the migration was solving a problem that did not need to be solved.

I deleted the migration before the tag. All 270 lines, all twelve tests. The CHANGELOG notes the draft existed and was removed, because that fact matters for anyone wondering why the codebase has a v12-to-v13 throw block but no migration body to call. The bug fix lives entirely in URLUtilities.filename(_:). The data fix lives entirely in the new bundle. The schema bump is a one-line Int32 that forces the upgrade path.

What I learned: write the migration code if you have to think through the algorithm, but ship the path that the architecture wants you to ship. The investment was not wasted. It was the thing that forced me to fully understand what the dedup boundary actually looks like across all six tables that hold URIs.

3. Reindexing 404,729 pages costs you an evening of wall-clock and removes one third of your data.

The bundle reindex took 12 hours 36 minutes on an M4 Max. I watched a stale-build SwiftPM lock kill three attempts before the fourth one ran clean. I babysat the cupertino-rel binary signing through Apple’s notarization queue. I watched the search.db file grow from 425 MB to 2.41 GB in 27-second progress increments, all night.

The first time I ran cupertino search "withTaskGroup" against the new bundle it returned a single result, lowercase, canonical. The same query against the v1.0.1 bundle returns two: one capital S, one lowercase. That moment is worth twelve hours.

What also changed in the cupertino skill

The cupertino skill (the bundle of instructions that ships in skills/cupertino/SKILL.md for LLMs that integrate with cupertino) got a “Two rules” block at the top of its body. The previous version had query strategy + verification guidance scattered throughout. The new version makes the two things that matter the first thing the calling model sees:

1. Any Apple-related question goes through cupertino search first. Do not reach for training-data memory of Apple APIs.

2. After drafting an answer, verify that the code exists on Apple and that the pattern is appropriate. Existence catches invented method names. Appropriateness catches deprecated symbols that cupertino indexes alongside current ones (e.g. UIWebView when WKWebView exists).

The token cost of doing this is small (about 5 % overhead for cite-as-you-go, a few hundred tokens per verification re-search) and the failure mode it prevents is the most common LLM Apple-API hallucination class.

Upgrade

If you already have cupertino installed:

brew update && brew upgrade cupertinohq/tap/cupertino
cupertino setup

The first command pulls the new universal binary (signed and notarized via the GitHub Actions release workflow). The second downloads the new database bundle (669 MB compressed, 3.3 GB on disk). Your old v12 search.db will be rejected at open with a “rebuild required” message and replaced.

If you are installing for the first time:

bash <(curl -sSL https://codeberg.org/CupertinoHQ/cupertino/raw/branch/main/install.sh)

Thanks

To @Vignesh-Thangamariappan for PR #278 (post-redirect canonicalization, #277). To @imwyvern for the upstream #200 work that v1.0.2 builds on. To everyone who filed issues against the v1.0.0 corpus and made #283 surface in the first place.

Cupertino is free, open-source, local-first, and built by one person on her own time.

Built by Mihaela. I also work on Codeweaver.

The first release I’d actually call stable. Apple’s documentation, search that doesn’t suck, and an MCP server that an AI agent can read from before it answers.

If you’ve ever asked an LLM “what does Swift’s Task do?” and got back something about Mach kernel context switches, you’ve met the problem cupertino solves. Models hallucinate Apple APIs because their training data is stale, partial, and weighted toward whatever prose happened to mention a symbol — not toward Apple’s actual documentation. The fix isn’t a bigger model. The fix is making the documentation available to the model at inference time, ranked correctly, served over a protocol the model already speaks.

That’s cupertino. v1.0.0 “First Light” is the first release I’m willing to call stable across the whole pipeline: crawl, index, rank, serve, distribute. Before today every previous release had at least one of those broken. Today none of them are.

The headline: search now returns the right answer

Run this against an installed v1.0:

$ cupertino search Task --limit 3
Searched: packages, apple-docs, swift-evolution

[1] Task | Apple Developer Documentation  •  source: apple-docs  •  score: 0.0492
    apple-docs://swift/documentation_swift_task
    A unit of asynchronous work.

[2] task | Apple Developer Documentation  •  source: apple-docs  •  score: 0.0484
    apple-docs://kernel/documentation_kernel_kernel_resource_sizes_data_t_1586795-task

[3] task  •  source: apple-docs  •  score: 0.0476
    apple-docs://foundation/documentation_foundation_urlprotocol_task

That’s the canonical Swift Task struct at #1, where it belongs. The same binary against the same database before today’s changes returned a Mach kernel C function as the top result. Cupertino’s pre-1.0 ranker — and frankly every documentation search I’ve seen, including Apple’s own — was wrong on common type names. Type “Task”, get a kernel essay. Type “View”, get a DeviceManagement payload schema. Type “Result”, get a Vision associated type.

Multiple compounding bugs caused this. Fixing them was most of what this release is about.

Reciprocal rank fusion that actually understands the query

Cupertino’s cupertino search (no --source flag) fans out across every available corpus in parallel — apple-docs, the Apple Archive, HIG, swift-evolution, swift.org, the Swift Book, the curated packages corpus, the Apple sample-code corpus — and fuses the per-source rankings via reciprocal rank fusion (Cormack/Clarke/Büttcher, 2009). The math is 1 / (k + rank) per source, summed across sources. RRF is the right shape for prose-vague queries where any source might hold the answer (“how do I cancel an async operation”). It is the wrong shape for symbol queries where the answer is unambiguously in apple-docs.

The pre-1.0 default was uniform RRF. Every source’s rank-1 contributed 1/61 ≈ 0.0164. Three sources tied at 0.0164 on a query like Task, the alphabetic tiebreak buried apple-docs, and you got “Common Tasks in OS X” from the Apple Archive instead of the Swift Task struct.

v1.0 splits the routing decision by query shape. Symbol-shaped queries — single token, ASCII identifier, leading uppercase, the kind of thing a Swift developer types on muscle memory — only fan out across apple-docs + swift-evolution + packages. The four prose-shaped sources don’t even participate in the fusion. Plus an authority weight on RRF: apple-docs gets 3.0, swift-evolution and packages 1.5, swift.org and the Swift Book 1.0, the Apple Archive and HIG 0.5. apple-docs’s rank-1 fuses to 3.0/61 ≈ 0.0492 and beats peer rank-1’s 1.0/61 ≈ 0.0164 without alphabetic tiebreaks deciding anything.

The Searched: line in the output above is the routing decision made visible. It listed only packages, apple-docs, swift-evolution because Task looks like a symbol. Type cupertino search "swiftui state management" and you’ll see Searched: hig, samples, apple-docs, swift-evolution, packages — five sources, broader fan-out, because the query is prose.

Inside apple-docs: BM25F, AST symbols, and a ladder of post-rank heuristics

Per-source ranking inside apple-docs is field-weighted BM25 (BM25F, Robertson/Zaragoza/Taylor 2004) over an 8-column FTS5 index — uri, source, framework, language, title, content, summary, symbols. Title gets weight 10×, AST-derived symbols 5×, summary 3×, framework 2×, body and metadata 1×. The symbols column is new in v1.0: it’s populated by a Swift AST extractor that runs over both code blocks AND declaration lines on every page. So a query like Observable ranks the SwiftUI macro page above prose mentions of the word “observable” in unrelated articles.

On top of raw BM25F, there’s a ladder of post-rank heuristics that handle pathological cases the indexer alone can’t fix:

• Title-suffix awareness. Apple writes <canonical type name> | Apple Developer Documentation only on the parent landing page of a type. Sub-symbols (properties, methods, nested types) get clean titles. The suffixed page’s raw BM25 is worse because the suffix dilutes title term-frequency over field length, so a 50× boost is applied to suffixed exact-title matches, while clean-titled siblings keep the existing 20×. Flips canonical-vs-sub-symbol order without touching BM25F.

• Exact-title peer tiebreak. Result matches three apple-docs pages exactly: Swift’s Result enum, Vision’s VisionRequest.Result associated type, and Installer JS’s runtime Result. All three get the same 50×, so BM25F decides — and BM25F has no opinion. v1.0 adds two orthogonal signals: URI simplicity (documentation_FRAMEWORK_QUERY is the framework’s top-level type page; anything deeper is a sub-symbol) and a small framework-authority map (swift 0.5, swiftui 0.7, foundation 0.7; installer_js and webkitjs mildly demoted). Fires only inside the exact-title branch — does not crowd out framework-specific symbol queries (VisionRequest still resolves to vision/VisionRequest).

• Force-include canonical type pages past fetchLimit. Some canonical pages get buried by raw BM25 length-normalization — Foundation URL lands at raw BM25 position 1017, Swift Identifiable at 2577, Foundation Data past 3000 — well past the 1000-row over-fetch the post-rank multipliers operate on. v1.0 hand-fetches apple-docs://FRAMEWORK/documentation_FRAMEWORK_QUERY directly by URI for the top-tier frameworks (swift, swiftui, foundation) and force-prepends them. O(1) per probe via docs_metadata’s primary key.

The combined effect: against the v1.0 corpus (405,782 documents across 422 frameworks), 34 of 35 canonical type queries land their canonical apple-docs page at fused #1. The holdout, Stack, doesn’t have a canonical Swift / SwiftUI / Foundation type — TVML’s Stack is the right answer, and that’s what comes back.

The packages corpus gets the same treatment

Same BM25F-buries-the-canonical-repo problem on package_files_fts. Type vapor middleware and pre-1.0 you got apple/swift-openapi-generator because that repo has long prose mentioning Vapor and middleware in the same article; the actual vapor/vapor repo’s README ranked second. Type swift testing and you got pointfreeco/swift-dependencies because that package’s testing article has more keyword density than the actual swiftlang/swift-testing repo.

The fix mirrors the apple-docs canonical force-include. When the query tokens — joined with dashes for multi-word queries, or as single tokens for single-word queries — match an indexed repo name exactly, force-fetch that repo’s top BM25 file and prepend it. Two priority tiers: dashed forms (“swift-testing”) beat single tokens (“swift”) so a multi-word query that has a dashed canonical doesn’t also pull in the broader-corpus repo via the bare token. swift testing resolves to swiftlang/swift-testing, not swiftlang/swift. vapor middleware resolves to vapor/vapor because no vapor-middleware repo exists; the single-token fallback finds vapor.

The probe is bounded — it only fires when there’s an indexed canonical match, so queries that genuinely don’t have a canonical repo (alamofire request against a corpus where Alamofire isn’t indexed; actor isolation which isn’t a repo name at all) fall through to plain BM25 with no overhead.

A SQL gotcha that cost us ~3 seconds per query

While testing the canonical force-include, I shipped it with the wrong SQL shape:

SELECT ... FROM docs_fts f
JOIN docs_metadata m ON f.uri = m.uri
WHERE f.uri = ?
LIMIT 1;

docs_fts is an FTS5 virtual table. Its uri column is not a queryable index — FTS5 stores columns inside the inverted index, accessible only through MATCH. SQLite’s planner picked SCAN VIRTUAL TABLE INDEX 0 and walked the entire FTS5 index for every probe. About 3.2 seconds per probe on the 3.4 GB v1.0 search.db. Three probes per search call = 10 seconds of pure overhead before the actual query ran.

The fix is a one-line SQL rewrite — query docs_metadata (whose uri is TEXT PRIMARY KEY) directly, pull title and summary out of json_data via json_extract($.title, $.abstract), never touch the FTS5 virtual table for this lookup. 5 milliseconds per probe. Single-process search wall time on the 3.4 GB corpus dropped from ~18 seconds to ~4 seconds.

The same bug was lurking in the older fetchFrameworkRoot helper that’s been there since #81, untimed and presumably contributing to user-visible latency for months. Both are fixed in v1.0.

Concurrent-search lock contention

Every Search.Index initialization used to issue an unconditional PRAGMA user_version = N write — even when the version was already correct. SQLite is single-writer. Two parallel cupertino search invocations contended on the open-time write lock, and one would fail with database is locked because SQLite’s default busy_timeout is 0.

Fixed two ways: read-then-write (skip the PRAGMA when the version already matches, so the steady-state path does zero writes), and sqlite3_busy_timeout(db, 5000) right after open so any future write contention degrades to a wait-then-succeed instead of an immediate failure. Cupertino’s MCP server can now handle concurrent requests against the same database without flaking.

Distribution: one bundle, not two

Pre-1.0 the deployment shape was: search.db and samples.db shipped on mihaelamj/cupertino-docs, while the curated packages.db was scoped for a separate mihaelamj/cupertino-packages companion repo. The split made sense when the packages corpus was a separate-cadence thing. It turned out it isn’t — the same crawl produces all three, on the same schedule, with the same release cycle. Two repos meant two release tags per cut, two sequential downloads on cupertino setup, soft-fail logic when one release lagged the other, and two URL constants in Shared.Constants to keep in sync.

v1.0 collapses everything to one bundle: cupertino-databases-v1.0.0.zip on mihaelamj/cupertino-docs, ~833 MB compressed, contains all three databases. cupertino setup does one download + extract + version stamp. The companion repo is deleted; deleting it was the last action before tagging.

The release tooling caught up too. cupertino-rel databases now bundles all three databases into the single zip and uploads to the docs repo. Hard-fails if packages.db is missing under --base-dir unless --allow-missing-packages is passed (lets a release runner publish a partial bundle in genuinely time-sensitive cases without making it the default).

The schema bump (BREAKING)

Schema went from 10 → 12 across two intermediate steps. v11 added kind and symbols columns to docs_metadata. v12 added the symbols column to docs_fts. FTS5 doesn’t support ALTER TABLE ADD COLUMN, so v12 is a hard break — existing v10/v11 databases throw on open with a clear error message:

Database schema version 10 requires migration to version 12.
This is a breaking change that adds AST-derived symbols to the FTS index.
Please delete the database and run 'cupertino save' to rebuild:
rm ~/.cupertino/search.db && cupertino save

Most users won’t see this — they’ll just cupertino setup once and get the v1.0 bundle directly, with setup automatically backing up any pre-existing databases as .backup-<version>-<iso8601> siblings (#249) before extraction overwrites them. The rollback is one rename.

Users who built their own search.db with cupertino save against an older binary need to rebuild, but the docs corpus on disk is unchanged — the same ~/.cupertino/docs/ produces a v12 search.db without re-crawling.

MCP protocol upgrade — 2025-11-25

The Model Context Protocol moved to spec 2025-11-25. Cupertino now negotiates that as its preferred version and retains backward-compat for 2025-06-18 and 2024-11-05 so older clients keep working through three negotiation hops. The new spec adds Icon to Implementation, so cupertino’s MCP serve advertises a 64×64 PNG via a data:image/png;base64,... URI (embedded as a Swift literal in the binary, no external bundle).

Crawler hardening

The crawler took a lot of fire across this release.

• Per-URL JSON-then-WebView fallback. cupertino fetch --type docs does one pass through the queue, trying Apple’s JSON API first and falling back to WKWebView when a page has no JSON endpoint. Single-pass, full coverage. (The fallback was already there; the previous “two-pass” orchestration was running the same crawler twice and is now removed.)

• Auto-resume by default. If metadata.json has an active session matching the start URL, cupertino fetch picks it up. The previous --resume flag was a log-message switch and is gone.

• Crash-safe metadata writes. JSONCoding.encode(_:to:) writes with .atomic (temp + rename), so a kill mid-save can never leave metadata.json corrupt. Mid-save corruption was the one failure mode that could make a multi-day crawl unresumable.

• Default page cap raised 15,000 → 1,000,000. Effectively uncapped for full Apple-corpus crawls (~50–80k pages). The old 15k default would silently truncate at ~15–30% coverage.

• URL canonicalization (case axis). URLUtilities.normalize now lowercases the URL path. Apple’s docs server is case-insensitive, but the crawler used to treat /documentation/Cinematic/CNAssetInfo and /documentation/cinematic/cnassetinfo as different URLs. Queue inflated ~3× with case duplicates (62% of queue entries on the April 2026 crawl). Fragment + query stripping unchanged.

• Filename-length cap, queue dedup at enqueue time, autorelease pool around per-page work, full DocC references walk — the unglamorous fixes that let a multi-day crawl finish without RSS leaks, dropped pages, or queue explosion.

A reproducible recrawl pipeline (scripts/recrawl.sh) wraps the whole thing in 10 phases with named markers so you can tail-follow the log and see “phase 5/10 starting” in real time.

Architecture: the four-package CLI lift

This is more for contributors than users, but worth flagging. Logic that powered four CLI commands — setup, doctor, save, fetch — moved out of Sources/CLI/Commands/* into four new SPM packages:

• Distribution — the download + extract + version-stamp pipeline (SetupService, ArtifactDownloader, ArtifactExtractor, InstalledVersion).

• Diagnostics — pure-data probes for SQLite + filesystem corpus, used by doctor. Zero external deps.

• Indexer — write-side counterpart to Search. Three indexer services (DocsService, PackagesService, SamplesService) each emit per-stage events. Hosts the preflight pipeline for cupertino save + doctor --save.

• Ingest — package skeleton + Session helpers lifted from FetchCommand. The seven <Type>Pipeline services still live in CLI; lifting them is queued for v1.0.1.

The point of the lift is that MCP tooling, future agent-shell adapters, and tests can now drive the pipelines without depending on ArgumentParser. CLI files become thin front-doors that parse flags and render progress.

What “First Light” means

The release name is from astronomy. First light is the first time a new telescope is pointed at the sky and an actual image comes back — not a calibration target, not a test pattern, but real data. Everything before is engineering. First light is when the instrument starts being a telescope.

That’s how this release feels. The previous twelve months were engineering — getting the crawler not to leak memory, getting the indexer to handle the field weights, getting the MCP server to negotiate protocols, getting the install to not strand users on stale databases. v1.0.0 is when those parts compose into something that does what it was built to do.

Try it

brew tap cupertinohq/tap https://codeberg.org/CupertinoHQ/homebrew-tap.git
brew install cupertinohq/tap/cupertino
cupertino setup
cupertino search Task

brew install pulls a notarized universal binary (~13 MB). cupertino setup downloads the v1.0.0 database bundle (~833 MB compressed, ~5 GB extracted). cupertino search Task should land the canonical Swift Task struct as result #1.

If you want it as an MCP server for Claude / Cursor / VS Code Copilot / Zed / Windsurf / opencode / Codex, point your client config at cupertino serve. Setup guides for each are in the README.

What’s next: v1.0.1

A few items deferred from v1.0.0 that I want to land in a follow-up patch:

• WKWebView re-crawl on the May 2026 corpus. The April 2026 corpus shipped with v1.0.0 because rebuilding the schema-12 search.db from on-disk docs doesn’t need a re-crawl. The next release will refresh the corpus content itself and pick up Apple-side documentation edits since April plus pages the JSON API doesn’t expose.

• Kind-tier ranking. Roughly 49% of apple-docs rows have kind=unknown. When the crawler-side metadata extraction improves, a kind ∈ {enum, struct, class, protocol} tier slots ahead of the framework-authority tiebreak in HEURISTIC 1. The exact-title peer cluster gets a third orthogonal signal and the few remaining edge cases (Result’s lowercase-property competition, Identifiable’s conformance-page domination) collapse cleanly.

• Ingest sub-PRs 4b–4f. The seven <Type>Pipeline services still in CLI lift cleanly into the new package once they grow callback-based shapes. Tracked under #247.

That’s it. Cupertino v1.0.0 “First Light” is out. Tag, binary, bundle, formula — all live as of today.

Apple’s documentation is now something an AI agent can actually read before it answers.

TL;DR: All 307 Apple frameworks are now indexed. 302,424 documentation pages searchable. Community contributors added Agent Skill support and a Claude Code plugin. Homebrew resource bundle fix.

The Completionist Achievement: Unlocked

I wanted every Apple framework in the index. Not most of them. All of them.

Turns out, the crawler was only finding ~20 frameworks by following links from Apple’s developer homepage. That’s like exploring a library by only reading the “Staff Picks” shelf. The rest of Apple’s documentation was sitting there, patiently waiting to be discovered.

The fix: seed the crawler from Apple’s own technologies.json – their internal index of every framework. Feed that to the BFS crawler, and suddenly the whole library opens up.

But that was just the first of five bugs hiding in the crawl engine:

That last one was sneaky. If a page’s content hadn’t changed since the last crawl, the crawler skipped it – but skipped before adding its child links to the queue. Entire subtrees silently disappeared.

The result: 13 previously missing frameworks crawled and indexed. CoreGraphics, CoreMedia, CoreVideo, CoreText, CoreAudio, dnssd, Hypervisor, IOBluetooth, HIDDriverKit, Matter, OpenGLES, USBDriverKit, and CoreAudioTypes.

Yes, even OpenGLES. Deprecated, but completionism has no room for judgment.

Your AI agent can now answer questions about Hypervisor’s vCPU mapping and IOBluetooth’s RFCOMM channels. You’re welcome.

Community Contributions

This release marks a milestone I’m genuinely excited about: the first external contributions to Cupertino.

Both add new ways to use Apple documentation without running an MCP server. Two contributors saw something they wanted, built it, and sent a PR. That’s the open source dream right there.

Agent Skill Support (PR #167)

Tijs Teulings added support for using Cupertino as a stateless Agent Skill. AI coding agents get direct access to Apple documentation via CLI commands with JSON output – no MCP server process needed.

Install with OpenSkills:

npx openskills install mihaelamj/cupertino

Or manually copy the skill definition to .claude/skills/cupertino/.

No daemon. No stdio pipe. Just cupertino search "SwiftUI" --format json and you’re done.

Claude Code Plugin (PR #169)

Gustavo Ambrozio took Tijs’s skill and leveled it up into a proper Claude Code plugin with marketplace support.

claude /plugin marketplace add https://codeberg.org/CupertinoHQ/cupertino.git

The plugin adds a manifest, marketplace metadata, and improved skill descriptions with better trigger phrases. One command to install, zero configuration after that.

Thank you Tijs and Gustavo. It’s a great feeling to see the project grow beyond a single-maintainer effort.

The Homebrew Symlink Saga

Here’s a fun one. After the v0.10 release, brew install cupertino worked fine… until you actually ran any command. Instant crash:

Fatal error: could not load resource bundle:
from /opt/homebrew/bin/Cupertino_Resources.bundle

The problem: Homebrew symlinks files from the Cellar to /opt/homebrew/bin/, but not directories. The resource bundle was sitting happily in the Cellar, but Bundle.main.bundleURL (which doesn’t resolve symlinks) was looking in /opt/homebrew/bin/ where the symlink lives. Two ships passing in the night.

The fix was two-pronged:

1. Formula: Added a post_install hook that manually creates the symlink for the resource bundle directory

2. Code: CupertinoResources.bundle now resolves symlinks via executableURL.resolvingSymlinksInPath() before falling back to Bundle.module

Belt and suspenders. If you had the crash, brew update && brew upgrade cupertinohq/tap/cupertino fixes it.

Search Improvements

Framework search now includes synonym matching. Because nobody remembers if it’s “CoreGraphics” or “Core Graphics”:

Case-insensitive, space-tolerant. Type it however you remember it.

Install or Update

# New install
brew tap cupertinohq/tap https://codeberg.org/CupertinoHQ/homebrew-tap.git
brew install cupertinohq/tap/cupertino

# Update existing
brew update && brew upgrade cupertinohq/tap/cupertino

# Or one-line install
bash <(curl -sSL https://codeberg.org/CupertinoHQ/cupertino/raw/branch/main/install.sh)

Then:

cupertino setup  # Download databases (~30 seconds)
cupertino serve  # Start MCP server

Issues and PRs Closed

• #159 - Missing framework documentation

• #160 - Crawler improvements for full coverage

• #167 - Agent Skill support (@tijs)

• #169 - Claude Code plugin (@gpambrozio)

• #162 - CONTRIBUTING.md (@William-Laverty)

• #133 - README link fix (@lwdupont)

• #172 - Crawler session resume and delay fixes

Links

• Codeberg Repository
• Documentation
• Tag v0.10.0

I created a GitHub repo from my phone while walking around the house. No terminal, no SSH, no laptop open. Just iMessage.

iRelay is a Swift daemon that listens for iMessages on your Mac, spawns Claude Code in your project directory, and sends the result back as a text. You message your Mac like you’d message a person, except it writes code.

Codeberg: codeberg.org/Mihaela/iRelay

Demo

How It Works

The flow is simple:

iPhone (iMessage) → Mac (iRelay daemon) → Claude Code → response → iMessage

You send something like irelayy fix the failing test from your phone. Your Mac picks it up, runs Claude Code against your project, and texts you back with what it did.

That’s it. No web UI, no port forwarding, no VPN. Just iMessage as a transport layer.

Why the Double Y

I already run OpenClaw on the same Mac for iMessage automation. Two daemons listening to the same iMessage account would fight over every incoming message.

The fix: a prefix. iRelay claims any message starting with irelayy (double y). OpenClaw ignores those. Everything else goes to OpenClaw. Simple namespace partitioning over a shared channel.

What I Actually Did With It

First real test: I asked it to investigate my repos and suggest a business idea. It came back with MCPMe. Then I told it to create the repo, write the README, and push it. All from iMessage. The Mac did the work while I made coffee.

That’s the use case — you’re away from your desk but you want something done now. A quick fix, a repo setup, a refactor. Text it, walk away, get the result back on your phone.

Architecture

iRelay is designed around channels and providers:

• Channels handle message transport — iMessage is the one that works today. The architecture supports Telegram, Slack, Discord, Signal, Matrix, IRC, and WebChat, but those are scaffolded, not wired up yet.

• Providers handle LLM execution — Claude Code is the primary one. OpenAI, Ollama, and Gemini slots exist for future use.

Conversation history is preserved across messages, so context carries over. You can also save and restore sessions.

What’s Next

iRelay pairs well with Cupertino — when Claude Code has offline access to Apple’s documentation, the responses you get back over iMessage are significantly better. No hallucinated APIs, no deprecated patterns. I’ve been quietly working on a major Cupertino update that nearly doubles framework coverage, which will make this combination even stronger. More on that soon.

Built in a day. Used from the couch.

TL;DR: Cupertino now has setup guides for 8 different AI tools. MCP protocol upgraded to 2025-06-18. Comprehensive documentation for all binaries. No more Node.js in the codebase.

This release focuses on reach. More AI tools can use Cupertino. Better documentation. Cleaner internals.

Release Summary

Since v0.8.0, Cupertino has had 5 releases:

Multi-Agent Support (v0.9.1)

The most requested feature: “How do I use Cupertino with X?”

Cupertino started as a Claude tool. But MCP is an open protocol. Any AI assistant that speaks MCP can use it.

v0.9.1 adds setup guides for 8 AI tools:

Quick Setup

For most tools, configuration is a JSON object:

{
  "mcpServers": {
    "cupertino": {
      "command": "/opt/homebrew/bin/cupertino",
      "args": ["serve"]
    }
  }
}

The exact structure varies by tool. Full examples are in the serve command documentation.

Dynamic Path Detection

If you’re not sure where cupertino is installed:

claude mcp add cupertino -- $(which cupertino)
codex mcp add cupertino -- $(which cupertino) serve

The $(which cupertino) expands to the actual binary path. Works for Homebrew installs on both Apple Silicon (/opt/homebrew/bin) and Intel (/usr/local/bin).

MCP Protocol Upgrade (v0.9.0)

v0.9.0 upgrades the MCP protocol from 2024-11-05 to 2025-06-18.

This matters because newer AI tools expect the newer protocol. Without this upgrade, Cupertino would fail to initialize with clients that only support 2025-06-18.

The upgrade includes backward compatibility:

// Server negotiates with client
public let MCPProtocolVersion = "2025-06-18"
public let MCPProtocolVersionsSupported = ["2025-06-18", "2024-11-05"]

// During initialization, find common version
let negotiatedVersion = clientVersions
    .first { MCPProtocolVersionsSupported.contains($0) }

If a client requests 2024-11-05, Cupertino still works. If it requests 2025-06-18, that works too. The MCPClient and MockAIAgent also support version fallback when connecting to servers.

Thanks to @erikmackinnon for the contribution (#130).

Binary Documentation (v0.9.1)

Cupertino ships 4 executables. Until now, only cupertino had proper documentation.

v0.9.1 adds 48 documentation files covering all binaries:

cupertino

The main CLI with 12 commands. Already documented, but now with updated MCP client configuration examples.

cupertino-tui

The terminal UI for browsing and selecting packages:

cupertino-tui
cupertino-tui --version

5 views documented:

• Dashboard - Overview and quick actions

• Packages - Browse and select Swift packages

• Archive - Apple Archive documentation selection

• Videos - WWDC video selection

• Settings - Configuration options

mock-ai-agent

A testing tool that simulates MCP client behavior:

mock-ai-agent search "SwiftUI navigation"
mock-ai-agent list-tools
mock-ai-agent --server /path/to/cupertino
mock-ai-agent --version  # New in v0.9.1

Arguments documented:

• <query> - Search query to execute

• --server - Path to MCP server binary

Useful for testing MCP servers without a full AI client.

cupertino-rel

The release automation tool (maintainer-only):

cupertino-rel bump patch          # Bump version
cupertino-rel tag --version 0.9.1 --push  # Create and push tag
cupertino-rel homebrew --version 0.9.1    # Update Homebrew formula
cupertino-rel databases --version 0.9.1   # Upload database release
cupertino-rel docs-update patch   # Documentation-only release
cupertino-rel full 0.10.0         # Complete release workflow

6 subcommands with all options documented:

• bump - Update version in all files

• tag - Create and push git tags

• homebrew - Update Homebrew formula

• databases - Upload databases to cupertino-docs

• docs-update - Documentation-only releases

• full - Complete release workflow

Documentation Structure

The documentation follows the same granular folder structure as the main CLI:

docs/binaries/
├── README.md
├── cupertino-tui/
│   ├── README.md
│   ├── option (--)/
│   │   └── version.md
│   └── view/
│       ├── dashboard.md
│       ├── packages.md
│       ├── archive.md
│       ├── videos.md
│       └── settings.md
├── mock-ai-agent/
│   ├── README.md
│   ├── option (--)/
│   │   ├── server.md
│   │   └── version.md
│   └── argument (<>)/
│       └── query.md
└── cupertino-rel/
    ├── README.md
    ├── option (--)/
    │   └── version.md
    └── subcommand/
        ├── bump/
        ├── tag/
        ├── homebrew/
        ├── databases/
        ├── docs-update/
        └── full/

No More Node.js (v0.8.3)

v0.8.3 removed the last Node.js dependency from the codebase.

The MCP integration tests previously used npm packages to simulate client behavior. Now they use cupertino serve directly:

@Test("Initialize handshake with cupertino server")
func cupertinoServerInitialize() async throws {
    let process = Process()
    process.executableURL = URL(fileURLWithPath: ".build/debug/cupertino")
    process.arguments = ["serve"]

    let stdinPipe = Pipe()
    let stdoutPipe = Pipe()
    process.standardInput = stdinPipe
    process.standardOutput = stdoutPipe

    try process.run()

    // Send initialize request (compact JSON + newline)
    let initRequest = """
    {"jsonrpc":"2.0","id":1,"method":"initialize","params":{...}}\n
    """
    stdinPipe.fileHandleForWriting.write(Data(initRequest.utf8))

    // Parse and verify response
    let response = try JSONDecoder().decode(JSONRPCResponse.self, from: responseData)
    #expect(response.serverInfo.name == "cupertino")
}

The tests verify:

• MCP initialize handshake

• tools/list responses

• Protocol version negotiation

• Server info and tool registration

Swift-only tests. No npm. No node_modules. No package-lock.json.

This is now policy in AGENTS.md: no Node.js or npm in the Cupertino codebase.

Setup Progress Animation (v0.8.2)

Database downloads are ~400MB. Previously, cupertino setup showed nothing while downloading.

Now you get real-time feedback:

Download progress with bar:

⠹ [████████████░░░░░░░░░░░░░░░░░░] 42% (168MB/400MB)

Extraction spinner:

⠧ Extracting databases...

Implementation details:

• DownloadProgressDelegate implements URLSessionDownloadDelegate for real-time progress

• ExtractionSpinner shows animated feedback during unzip

• Extended download timeout to 10 minutes for large database files

• Uses ANSI escape codes for in-place updates

Small things that make the tool feel responsive.

Installer ANSI Fix (v0.8.1)

The one-line installer had broken ANSI colors:

Before:

\033[32m✓ Installation complete\033[0m

After:

✓ Installation complete  (in green)

Two echo statements were missing the -e flag for escape sequence interpretation. Fixed in #124.

Database Compatibility

This release uses the same database schema as v0.8.2. No migration needed.

When you run cupertino setup, it downloads databases from the v0.8.2 release. The CLI version (0.9.1) and database version (0.8.2) are now decoupled.

This means:

• CLI updates don’t require database re-downloads

• Database updates don’t require CLI updates

• Schema changes are tracked separately

Install or Update

# New install
brew tap cupertinohq/tap https://codeberg.org/CupertinoHQ/homebrew-tap.git
brew install cupertinohq/tap/cupertino

# Update existing
brew update && brew upgrade cupertinohq/tap/cupertino

# Or one-line install
bash <(curl -sSL https://codeberg.org/CupertinoHQ/cupertino/raw/branch/main/install.sh)

Then:

cupertino setup  # Download databases (~30 seconds)
cupertino serve  # Start MCP server

Configure your AI tool using the guides above, and you’re ready.

Issues Closed

• #124 - Installer ANSI escape sequences

• #96 - Setup progress animation

• #131 - Remove Node.js dependency from MCP integration tests

• #130 - MCP protocol mismatch (2025-06-18 support)

• #134 - Better documentation for use with different agents

• #137 - Documentation improvements: MCP client configs and binary documentation

Links

• Codeberg Repository
• Documentation
• Tag v0.9.1

TL;DR: SwiftSyntax-based AST indexing. Major codebase refactoring. Cleaner search results. Test suite grew from 93 to 698 tests.

This release is about foundations. Less visible features, more architectural work that makes everything else possible.

The Big Feature: AST Indexing

This is issue #81, and it’s been brewing for a while. Sample code search was purely keyword-based - you search “async”, you get files containing “async”. Comments, strings, documentation, actual code - all treated equally.

Now Cupertino extracts structured symbol data from Swift source:

// SwiftSourceExtractor analyzes this:
@MainActor
class NetworkManager: ObservableObject {
    @Published var isLoading = false

    func fetch() async throws -> Data { ... }
}

And extracts:

What This Enables

Better ranking, not magic. When you search “@Observable”, plain text search finds every file mentioning “Observable” - comments, strings, documentation, actual declarations. All ranked equally.

With AST indexing, Cupertino knows which results contain actual @Observable class declarations. These get boosted in ranking. The real symbol usages surface first.

$ cupertino search "@Observable" --source samples --format markdown

## Projects (5 found)

### 1. Migrating from the Observable Object protocol to the Observable macro
- **Frameworks:** swiftui
- **Files:** 14

## Matching Files

### Library.swift
> @Observable final class Library {
>     var books: [Book] = [Book(), Book(), Book()]
> }

### Book.swift
> @Observable final class Book: Identifiable {
>     var title = "Sample Book Title"
>     let id = UUID()
> }

The search still matches text, but files with actual @Observable declarations rank higher than files that just mention the word in comments.

Dedicated semantic tools. The symbol tables power these MCP tools:

• search_symbols - query by symbol type and attributes

• search_property_wrappers - find @Published, @State, @Binding usage

• search_conformances - find protocol implementations

• search_concurrency - find async/await patterns

These query extracted symbol data directly, not text. AI assistants can ask “find all async functions in SwiftUI samples” and get structured results.

How It Works

The new ASTIndexer package uses SwiftSyntax to parse Swift files and extract:

• Symbols: Classes, structs, enums, actors, protocols, functions

• Attributes: @MainActor, @Published, @Observable, etc.

• Conformances: Protocol adoptions

• Modifiers: async, throws, static, public

SwiftSyntax is Apple’s official Swift parser - the same one the compiler uses. No regex hacks, no fragile pattern matching.

The tradeoff? Build times. SwiftSyntax is a beast. First release build takes 10-15 minutes now. But the capability is worth it.

The Refactoring Story

This release involved substantial architectural changes that touch almost every part of the codebase. The goal: make search results cleaner and the system more capable.

Unified Search Service

Previously, each search source (docs, HIG, samples, videos) had its own formatting logic scattered across the codebase. Now there’s a unified SearchService that handles all sources consistently:

• Single entry point for all search types

• Consistent result formatting across sources

• Shared footer generation with tips and guidance

• Hierarchical numbering that works across all result types

Package Architecture Cleanup

The package structure got significant attention:

• Consolidated duplicate functionality across modules

• Clearer boundaries between Services, Core, and domain packages

• Better separation of CLI concerns from library logic

• Removed dead code paths and unused types

Result Formatter Protocol

A new ResultFormatter protocol standardizes how search results become output:

protocol ResultFormatter {
    associatedtype Input
    func format(_ result: Input) -> String
}

This enabled reusable formatters for different output contexts (CLI text, MCP markdown, JSON) while keeping the core search logic unchanged.

The refactoring wasn’t glamorous work, but it paid off immediately in cleaner search results and faster feature development.

Smarter Search Output

Here’s a subtle change that matters more than it sounds: hierarchical result numbering.

Before:

## Apple Documentation
### UIButton
### UIView
### UIControl

## Sample Code
### ButtonStyles
### CustomControls

After:

## 1. Apple Documentation (20)
### 1.1 UIButton
### 1.2 UIView
### 1.3 UIControl

## 2. Sample Code (5)
### 2.1 ButtonStyles
### 2.2 CustomControls

Why does this matter? When Claude is navigating search results, it can now reference specific items: “Looking at result 1.3…” or “Sample 2.1 shows this pattern…”

The count in headers (20, 5) also helps the AI understand result distribution. If one source has 50 results and another has 2, that’s useful context.

Small formatting changes, big impact on AI reasoning.

Display Bugs: Death by a Thousand Cuts

Sometimes bugs accumulate in strange ways. I noticed search results had weird formatting artifacts:

• Tabbars|AppleDeveloperDocumentation### - trailing garbage

• Tab bars - double spaces

• Goingfull screen - missing space in HIG titles

• Framework# SwiftUI - inline markdown headers

Each individually minor. Together, they made results look unprofessional and confused AI parsing.

The fix was a string extension that cleans display text:

var cleanedForDisplay: String {
    var result = self

    // Remove trailing ###
    while result.hasSuffix("###") { ... }

    // Remove |AppleDeveloperDocumentation
    result = result.replacingOccurrences(of: "|AppleDeveloperDocumentation", with: "")

    // Fix "Goingfull" -> "Going full"
    result = result.addingSpacesToCamelCase

    // Collapse double spaces
    while result.contains("  ") { ... }

    return result
}

Now there are 34 unit tests just for string formatting. Because every edge case that slipped through was a papercut in every search result.

The Test Suite Story

That’s not a typo. We went from 93 tests to 698.

Where did they come from?

1. AST Indexer tests - SwiftSyntax extraction needs thorough testing

2. String formatter tests - All those display edge cases

3. Service layer tests - Unified search service coverage

4. Symbol database tests - Integration tests for code analysis

The duration dropped despite 7x more tests because I fixed a race condition in the PriorityPackagesCatalog tests. The old code used defer { Task { await ... } } which created detached async tasks that didn’t complete before the next test ran. State leaked between tests, causing random failures.

The fix was embarrassingly simple: don’t use defer with async cleanup. Just await at the end of the test.

Doctor Command Gets Smarter

The cupertino doctor command now diagnoses package-related issues:

$ cupertino doctor

Cupertino v0.8.0 - Health Check

Databases:
  ✅ search.db (2.3GB, 302,424 docs)
  ✅ sample.db (156MB, 606 projects)

Package Status:
  ✅ User selections: ~/.cupertino/selected-packages.json (12 packages)
  ✅ Downloaded READMEs: 12/12
  ⚠️  Orphaned READMEs: 3 (packages no longer selected)

Priority Breakdown:
  📦 Apple Official: 31 packages
  📦 Ecosystem: 5 packages

MCP Tools: 8 registered
Resources: 3 providers active

The “orphaned READMEs” warning catches when you’ve unselected packages but their downloaded docs remain. Helpful for debugging unexpected search results.

What’s Next

The semantic tools (search_symbols, search_conformances, etc.) are built. Next steps:

1. Index all sample code - Run AST extraction across all 606 projects to populate symbol tables

2. Cross-referencing - Link extracted symbols to their documentation pages

3. Symbol coverage - Expand extraction to catch more edge cases

The infrastructure is in place. Now to fill the database and refine the queries.

Install or Update

# New install
brew tap cupertinohq/tap https://codeberg.org/CupertinoHQ/homebrew-tap.git
brew install cupertinohq/tap/cupertino

# Update existing
brew upgrade cupertino

# Or one-line install
bash <(curl -sSL https://codeberg.org/CupertinoHQ/cupertino/raw/branch/main/install.sh)

Then:

cupertino setup  # Download databases (~30 seconds)
cupertino serve  # Start MCP server

Try the improved search:

# See hierarchical numbering
cupertino search "SwiftUI navigation" --source all

# Clean HIG results
cupertino search "tab bar" --source hig

# Check your installation health
cupertino doctor

Cupertino is an Apple Documentation MCP Server. 302,424 pages of Apple documentation, searchable by AI. Source at codeberg.org/CupertinoHQ/cupertino.

TL;DR: Finally crawled all of Apple’s docs. Added OS version filtering. Made AI agents smarter about finding the right documentation.

Four days after v0.5.0, and I’ve shipped two more releases. At this point I’m not sure if this is momentum or obsession. Let’s call it momentum.

The Numbers

Three hundred thousand pages. That’s every framework, every class, every method Apple has documented. The crawl ran for almost two weeks total across multiple sessions.

Top Frameworks by Document Count

Kernel jumped from 25,000 to nearly 40,000 pages. That’s IOKit, BSD interfaces, Mach APIs, driver development - the low-level stuff that’s hardest to find and most valuable when you need it. Matter has 24,000+ docs for smart home development. Accelerate and SIMD documentation is fully indexed now - performance optimization guides that AI models probably didn’t see much of during training.

The Feature I’ve Been Waiting For: OS Version Filtering

This was issue #99, and it’s been on my mind since day one. Apple’s documentation includes version information - which iOS/macOS version introduced each API. We now extract this.

cupertino search "async" --min-ios 16

Or in Claude:

“Search for SwiftUI navigation APIs available in iOS 17+”

The AI agent can now filter results by platform version. No more suggestions for deprecated iOS 12 APIs when you’re building for iOS 17.

How It Works

Different documentation sources need different strategies:

For Apple’s modern docs, there’s a hidden JSON endpoint at /tutorials/data/documentation/ that returns structured metadata including availability. For older stuff, we derive from the framework - if it’s UIKit, we know the minimum versions.

The cool part? You can filter by any platform:

• --min-ios 16

• --min-macos 14

• --min-tvos 17

• --min-watchos 10

• --min-visionos 1

visionOS filtering. For when you’re building spatial computing apps and need APIs that actually exist on the platform.

Teaching AI Where to Look

Here’s something I discovered while using Cupertino with Claude: the AI doesn’t know what it doesn’t know.

When Claude searches for “CALayer animation”, it gets API reference - classes, methods, properties. Good stuff. But the conceptual documentation - the “why” behind Core Animation - lives in Apple Archive. And Claude had no idea.

The Problem

I had added archive support in v0.2.3. Users could search with --source apple-archive. But AI agents don’t read release notes. They read tool descriptions once, then forget. Every search was missing the deep conceptual guides.

The Solution: Teasers

Now every search result includes hints from alternate sources:

# Search Results for "CALayer animation"

## Results from apple-docs (5 found)

1. **CALayer** - The basic object for managing and presenting drawable content...
2. **CABasicAnimation** - An animation that applies a single keyframe...

---

**Other sources to explore:**

- **apple-archive**: 3 results (Core Animation Programming Guide, Animation Types...)
- **samples**: 2 results (LayerPlayer, AnimationExplorer)
- **swift-evolution**: 1 result (SE-0421: Generalize async sequence...)

Use `source` parameter to search: apple-archive, samples, hig, swift-evolution...

Every search response is now a teaching moment. Claude sees there are archive guides available. It sees sample code exists. It learns in context how to dig deeper.

Human Interface Guidelines: Design Docs for AI

Here’s something I didn’t expect to matter as much as it does: HIG support.

Apple’s Human Interface Guidelines aren’t just for designers. When Claude is helping you build a button, a navigation pattern, or a settings screen, it should know Apple’s design recommendations - not just the API.

cupertino search "buttons" --source hig

Now when you ask “what’s the recommended button style for destructive actions?”, Claude can actually look it up instead of guessing. Platform-specific guidance for iOS, macOS, watchOS, visionOS - all searchable.

The HIG docs are marked as “universal” for availability - they apply across all OS versions. Design principles don’t deprecate like APIs do.

One Tool to Rule Them All

Speaking of simplification - I consolidated the search tools.

Before v0.7.0:

• search_docs - Apple documentation

• search_hig - Human Interface Guidelines

• search_samples - Sample code

• …and more

Now:

• search - Everything, with a source parameter

# CLI
cupertino search "buttons" --source hig
cupertino search "networking" --source samples
cupertino search "actors" --source swift-evolution
cupertino search "everything" --source all

One tool, eight sources, cleaner mental model. The source parameter accepts:

• apple-docs (default) - API reference

• samples - Working code examples

• hig - Design guidelines

• apple-archive - Legacy conceptual guides

• swift-evolution - Language proposals

• swift-org - Swift.org documentation

• swift-book - The Swift Programming Language

• packages - Swift package docs

• all (searches everything)

The all option is surprisingly useful. When you’re not sure where something lives, just search everywhere.

What I Learned

Building for AI is different than building for humans.

Humans read documentation. They explore. They remember “oh yeah, there’s an archive section I should check.” AI agents don’t work that way. They have tool descriptions and search results. That’s it.

The best way to teach an AI agent? Put the lesson in every response it sees. Not in documentation it reads once. Not in tool descriptions it might forget. In the actual output, every single time.

That’s why teasers matter. That’s why source-aware messaging matters. Every search result is documentation.

The Road Ahead

With 302,424 pages indexed and version filtering working, the foundation is solid. What’s next:

1. Semantic code search - Search sample code by what it does, not just keywords

2. Framework relationships - Search UIKit, get relevant Foundation results too

3. Smarter ranking - Weight results by your target platform

The crawl is complete. The curation continues.

Install or Update

# New install
brew tap cupertinohq/tap https://codeberg.org/CupertinoHQ/homebrew-tap.git
brew install cupertinohq/tap/cupertino

# Update existing
brew upgrade cupertino

# Or one-line install
bash <(curl -sSL https://codeberg.org/CupertinoHQ/cupertino/raw/branch/main/install.sh)

Then:

cupertino setup  # Download 2.3GB database (~30 seconds)
cupertino serve  # Start MCP server

Try the new features:

# Filter by OS version
cupertino search "SwiftUI navigation" --min-ios 17

# Search design guidelines
cupertino search "buttons destructive" --source hig

# Search legacy conceptual guides
cupertino search "Core Animation" --source apple-archive

# Search everything at once
cupertino search "async await" --source all

Cupertino is an Apple Documentation MCP Server. 302,424 pages of Apple documentation, searchable by AI. Source at codeberg.org/CupertinoHQ/cupertino.

TL;DR: Documentation database nearly doubled. New release tooling. A roadmap for what’s next.

Two days after v0.4.0, we’re shipping v0.5.0. Why so fast? Because I finally finished a 5-day deep crawl of Apple’s documentation.

The Numbers

The crawl ran for 5 days because I wanted everything. Every framework, every page, every deprecated API. The result: nearly 100,000 more documents than before.

Top Frameworks by Document Count

1. Kernel - 24,747 docs

2. Matter - 22,013 docs

3. Swift - 17,466 docs

4. Foundation - 14,892 docs

5. UIKit - 12,341 docs

Kernel documentation alone has almost 25,000 pages. That’s IOKit, BSD interfaces, Mach APIs - the stuff that’s usually impossible to find.

What This Means for AI

When Claude searches Cupertino now, it has access to:

• Low-level APIs - Kernel programming, IOKit drivers, Mach ports

• Hardware interfaces - Matter protocol (24k+ docs for smart home development)

• Complete Swift coverage - Every proposal, every standard library type

• Obscure frameworks - The ones you forget exist until you need them

This is deterministic access to Apple’s documentation. No hallucination, no guessing from training data. Just the actual docs.

Why I Built Release Automation

I remember the release oopsie from v0.4.0 like it was just a few days ago. Wait, it was just a few days ago. 😅 I tagged before committing the version bump, had to delete tags, rebuild everything, update SHA256 checksums twice…

Almost happened again with v0.5.0. Caught it in time, but the close call was enough.

So I finally wrote the automation I’d been putting off. Not because users need it - they don’t. But because I was losing hours to release mechanics instead of building features.

The release process now touches 4 repositories (main repo, cupertino-docs for databases, Homebrew tap, and the blog). Miss one step, wrong order, typo in a version number - and you’re starting over.

Now it’s one command. I run it, go make coffee, come back to a published release. That’s the dream, anyway. We’ll see how v0.6.0 goes.

The Roadmap

The current roadmap lives with the Cupertino repository. Here’s what’s coming next, in dependency order:

Phase 1: Complete the Crawl (#88)

The crawl is extensive but not complete. Some frameworks have deep hierarchies that weren’t fully traversed. The goal is 100% coverage of Apple’s public documentation.

Status: In progress. Currently at depth level 8. No idea when it finishes - some frameworks go deep.

Phase 2: Prune the Database (#87)

Once we have everything, we need to clean it up. The database has:

• Duplicate entries (same doc indexed multiple times)

• Misclassified documents (wrong framework attribution)

• Orphaned entries from URL changes

This is blocked by #88 - no point pruning until the crawl is complete.

Phase 3: API Version Tracking (#99)

This is the big one. Apple’s documentation includes version information - which iOS/macOS version introduced each API. We can extract this.

Imagine searching with:

cupertino search "async" --min-os ios16

Or having Claude automatically filter out deprecated APIs when you’re targeting iOS 17+.

I’ve been investigating Apple’s /tutorials/data/documentation/ endpoint. It returns JSON with version metadata for most frameworks. Some older frameworks (Kernel, IOKit) don’t have it, but the coverage is good.

Status: Research complete. Implementation pending.

Phase 4: Version-Filtered Search (#100)

Once we have version data in the database, we can expose it as a search filter. Both CLI and MCP tool would support filtering by minimum OS version.

Blocked by: #99 (need the data first)

Phase 5: Semantic Code Search (#81)

The end goal: search sample code by what it does, not just by keyword.

cupertino search "async image loading with caching"

This requires:

1. Complete documentation (#88)

2. Clean database (#87)

3. SwiftSyntax AST indexing of sample code

It’s ambitious, but the foundation is being laid with each release.

Install or Update

# New install
brew tap cupertinohq/tap https://codeberg.org/CupertinoHQ/homebrew-tap.git
brew install cupertinohq/tap/cupertino

# Update
brew upgrade cupertino

# Or instant setup
bash <(curl -sSL https://codeberg.org/CupertinoHQ/cupertino/raw/branch/main/install.sh)

After installing, databases download automatically:

cupertino setup

Takes about 30 seconds to download the pre-built 1.9GB database.

The Vision: Human-Curated Developer Docs

Here’s what I’ve learned: having all the docs isn’t enough. We need them in context.

When you’re building an app targeting iOS 15+, you don’t want to see iOS 12 APIs. When you’re learning Core Animation, you want the conceptual guides from Apple Archive, not just the API reference. When you’re debugging a Matter integration, you need the 22,000 Matter docs filtered to what’s actually relevant.

Raw documentation is noise. Curated documentation is signal.

That’s where Cupertino is heading. Not just “here’s 234,331 docs” but “here’s what you actually need for your specific context.” Version filtering is coming - ask for iOS 16+ APIs only. Source awareness is coming - archive guides surfaced alongside modern reference. Framework relationships are coming - search UIKit and get relevant Foundation results too.

The crawl is the foundation. The curation is the value.

234,331 documents today. Context-aware, version-filtered, human-curated search tomorrow.

Cupertino is an Apple Documentation MCP Server. Install with brew tap cupertinohq/tap https://codeberg.org/CupertinoHQ/homebrew-tap.git brew install cupertinohq/tap/cupertino. Source at codeberg.org/CupertinoHQ/cupertino.

TL;DR: Human Interface Guidelines support, smarter framework search, and a hard lesson about release engineering.

Why jump from 0.3.4 to 0.4.0? Five issues closed: HIG support (#69), framework aliases (#91, #92), and Swift.org fixes (#93, #94). Enough new functionality to warrant a minor version bump.

What’s New

Human Interface Guidelines Support

Cupertino can now crawl and index Apple’s Human Interface Guidelines:

cupertino fetch --type hig

There’s also a new search_hig MCP tool that lets AI agents search design guidelines with platform and category filters. When you ask Claude “what are Apple’s recommendations for buttons?”, it can actually look it up instead of guessing from training data.

Everything available via MCP tools is also available via command line:

cupertino search "buttons" --source hig

This is something people might not realize: you can query Cupertino the same way AI does. Every MCP tool has a CLI equivalent. Want to see exactly what Claude sees when it searches? Run the same query yourself. Useful for testing, debugging, or when you just want quick answers without a conversation.

Framework Aliases

Before, searching for “Core Animation” might not find results indexed under “QuartzCore” (the actual import name). Now there are 249 framework aliases in the database:

• QuartzCore ↔ CoreAnimation ↔ Core Animation

• CoreGraphics ↔ Quartz2D ↔ Quartz 2D

Search works regardless of which name variant you use.

Swift.org Fixes

The Swift.org crawler was broken. The base URL had changed from docs.swift.org to www.swift.org/documentation/, and the indexer was looking for .md files when the crawler was saving .json files. Fixed.

Why This Matters

Here’s a real example from today. I asked Claude about Apple’s Foundation Models framework - the new on-device ML APIs. Claude’s response:

“The MCP server pulls the complete Foundation Models sample code documentation - straight from Apple’s current docs. No hallucinated API names!”

More examples of documentation you can search:

• FoundationModels - Apple’s new on-device ML framework

• Writing Tools - System-wide AI writing assistance

• Genmoji - Custom emoji generation

• Image Playground - On-device image generation

This is also why Cupertino needs a human touch - it can’t be fully automated. Someone has to notice when Apple adds new frameworks, when URLs change (like Swift.org did), when documentation structures shift. The crawler is automated, but the awareness isn’t.

That’s the whole point: deterministic, up-to-date docs instead of training data guesses.

Token Efficiency

A side benefit: Cupertino is more token-efficient than you’d expect.

Yes, tool results use tokens - documentation goes into context. But:

• Accurate = fewer turns - No hallucination means no correction loop

• Curated content - Returns exactly what’s needed, not web search noise

• Local search is free - No API cost for the search operation itself

• Truncated summaries - Results are summarized; full doc only when you call read_document

So not zero tokens, but more efficient token use. And no external API costs for search.

The Archive Discovery Problem

Here’s something interesting I discovered while testing. When Claude searched for “CALayer animation”, it got API reference pages - classes, methods, properties. Claude wanted to dig deeper:

“Let me try a more targeted search - something like the layer tree architecture or model/presentation layers that would be covered in the Core Animation Programming Guide.”

Then I suggested searching with source: "apple-archive". Claude’s reaction:

“Now THAT’s the difference! When searching with source: apple-archive, we get the Core Animation Programming Guide and the Animation Types and Timing Programming Guide - the real meat.”

The conceptual deep-dives that explain why things work the way they do.

Modern Apple docs = API reference (the what) Archive docs = Conceptual guides (the why)

The problem? AI agents don’t know to search the archive. It’s an opt-in parameter buried in the tool description.

The Solution: Auto-Surface Archive Teasers

I’m planning to modify search results to automatically hint at archive content:

# Search Results for "CALayer animation"

## Modern Documentation
[1] CALayer - API reference...
[2] CABasicAnimation - API reference...

---

## 📚 Related Archive Guides

**Core Animation Programming Guide** - Layer geometry, animation timing...

> For full archive content, search with `source: "apple-archive"`

This way:

• Modern docs still come first

• AI agents always see archive exists

• They learn how to get more, in context

Only show the archive section if there are relevant results. Same principle could apply to sample code, Swift packages, or any other source.

The Release Process Disaster

Here’s where it gets interesting. I had all the code ready, all the tests passing, and I was ready to ship.

The process seemed simple:

1. Bump version in Constants.swift

2. Update README.md and CHANGELOG.md

3. Create git tag

4. Push tag (triggers GitHub Actions build)

5. Upload databases to cupertino-docs

6. Update Homebrew formula

What could go wrong?

The Tag Timing Problem

I merged my feature branch, created the tag, pushed it… and then realized I hadn’t committed the version bump to main yet. The tag pointed to a commit where Constants.swift still said 0.3.5.

GitHub Actions dutifully built a beautiful, signed, notarized universal binary… that reported version 0.3.5.

$ cupertino --version
0.3.5

When users ran cupertino setup, it tried to download databases from v0.3.5 instead of v0.4.0. Everything was broken.

The Fix

I had to:

1. Delete the tag on GitHub

2. Delete the local tag

3. Make sure the version bump commit was pushed to main

4. Verify the built binary reports correct version before tagging

5. Recreate the tag

6. Wait for GitHub Actions to rebuild

7. Update the Homebrew formula with the new SHA256

The SHA256 Dance

When I first updated the Homebrew formula, I grabbed the SHA256 from the old (broken) binary. After rebuilding, the checksum changed. Users got:

Error: Formula reports different checksum: cf035352...
SHA-256 checksum of downloaded file: 5c5cf7ab...

Another round of updating the tap.

The 11-Step Release Process

After today’s adventures, here’s what the release process actually looks like:

1. Update version in Constants.swift, README.md, CHANGELOG.md

2. Commit and push to main

3. Build locally and verify --version matches

4. Create and push tag

5. Wait for GitHub Actions (~5 min)

6. Create GitHub release with notes

7. Build locally and install

8. Upload databases with cupertino release

9. Get new SHA256 from release

10. Update Homebrew tap formula

11. Verify on fresh machine

That’s 11 steps across 4 repositories. Miss one, and you’re rebuilding everything.

Time for Automation?

I’m seriously considering writing a release script. Swift or Bash?

The pragmatic choice is Bash - it’s just orchestrating CLI commands. But I’m a Swift purist. The cupertino release command already handles database uploads with proper GitHub API integration. Extending it to handle the full workflow feels right.

Something like cupertino release --full that:

1. Checks for uncommitted changes

2. Verifies version consistency

3. Builds and validates --version

4. Creates and pushes the tag

5. Waits for GitHub Actions

6. Uploads databases

7. Updates the Homebrew tap

One command. No mistakes. Written in Swift.

Lessons Learned

1. Order matters. Commit the version bump before creating the tag.

2. Verify before you ship. Build locally and check --version before tagging.

3. Document your release process. I now have a detailed DEPLOYMENT.md with warnings.

4. Automate what hurts. If you make the same mistake twice, write a script.

What’s Next

• Enhanced search results - Auto-surface archive, samples, packages in every search (high priority)

• Release automation - cupertino release --full in Swift

• Fix setup animations - They’re broken

• Keep crawling - Fresh docs matter

This release taught me a lot. Not just about release engineering, but about how AI agents actually use documentation. The archive discovery problem was a surprise - valuable content hidden behind an opt-in flag that agents don’t know to use.

Building tools for AI is different. You’re not just building for humans who read documentation. You’re building for agents that learn from tool descriptions and in-context hints.

Key discovery: Claude reads tool descriptions once, but reads search results every time. If you want agents to use a feature, put it in the output - not buried in documentation they’ll forget. Every search result is a teaching moment.

Next up: implementing enhanced search results. Once that ships, every search will auto-surface relevant content from archives, samples, and packages - with the exact commands to dig deeper. No more hidden treasure.

Cupertino is an Apple Documentation MCP Server. Install with brew tap cupertinohq/tap https://codeberg.org/CupertinoHQ/homebrew-tap.git brew install cupertinohq/tap/cupertino. Check it out at codeberg.org/CupertinoHQ/cupertino.

TL;DR: One command installs everything. Homebrew is also available.

bash <(curl -sSL https://codeberg.org/CupertinoHQ/cupertino/raw/branch/main/install.sh)

What Changed

In v0.3.0, I introduced cupertino setup to download pre-built databases. But you still had to clone the repo and build from source first. That’s two steps too many.

Now it’s one line:

bash <(curl -sSL https://codeberg.org/CupertinoHQ/cupertino/raw/branch/main/install.sh)

This:

1. Downloads a pre-built universal binary (arm64 + x86_64)

2. Installs to /usr/local/bin

3. Downloads documentation databases (~230 MB)

Total time: under a minute.

Signed and Notarized

Getting a command-line tool to “just work” on macOS is harder than it sounds. Without proper signing, users see scary “unidentified developer” warnings. Without notarization, Gatekeeper blocks execution entirely.

The release workflow now handles this automatically:

1. GitHub Actions builds a universal binary (arm64 + x86_64) on every release tag

2. Developer ID signing with my Apple Developer certificate

3. Apple notarization submits to Apple’s servers for malware scanning

4. Preserved signatures using ditto instead of cp to maintain code signing through the install process

The result: download, install, run. No security dialogs. No right-click workarounds. No “are you sure?” prompts.

This took several iterations to get right—the signing must happen in CI, notarization requires waiting for Apple’s servers, and even copying the file wrong can strip the signature. But now it’s automated and works every time.

Homebrew Support

Prefer Homebrew? Now available:

brew tap cupertinohq/tap https://codeberg.org/CupertinoHQ/homebrew-tap.git
brew install cupertinohq/tap/cupertino
cupertino setup

Three lines instead of one, but integrates with your existing Homebrew workflow.

150,000+ Apple Documentation Pages

The database has grown significantly:

More coverage means better search results for your AI assistant.

Demo Video

Watch the one-line install and Claude Desktop in action:

Three Install Methods

1. One-Line Install (Recommended)

bash <(curl -sSL https://codeberg.org/CupertinoHQ/cupertino/raw/branch/main/install.sh)

Downloads binary and databases. Ready in under a minute.

2. Homebrew

brew tap cupertinohq/tap https://codeberg.org/CupertinoHQ/homebrew-tap.git
brew install cupertinohq/tap/cupertino
cupertino setup

Integrates with Homebrew for updates via brew upgrade cupertino.

3. Build from Source

git clone https://codeberg.org/CupertinoHQ/cupertino.git
cd cupertino && make build && sudo make install
cupertino setup

For those who want to inspect or modify the code.

What’s Inside

After installation, you have:

• /usr/local/bin/cupertino - The MCP server binary

• ~/.cupertino/search.db - 150K+ documentation pages

• ~/.cupertino/samples.db - 606 sample projects, 18K+ source files

Start the server and configure Claude Desktop:

cupertino serve

{
  "mcpServers": {
    "cupertino": {
      "command": "/usr/local/bin/cupertino"
    }
  }
}

Registry Submissions

I’ve submitted Cupertino to the major MCP server registries:

• mcpservers.org

• PulseMCP

• awesome-mcp-servers

These directories help developers discover MCP servers—getting listed would bring more visibility to the Apple developer community.

Links

• Codeberg: codeberg.org/CupertinoHQ/cupertino

• Homebrew Tap: codeberg.org/CupertinoHQ/homebrew-tap

• Demo Video: YouTube

The best install experience is no install experience. One line is close enough.

TL;DR: cupertino setup now downloads pre-built databases in ~30 seconds. No more 20-hour crawls.

The Problem With v0.2.x

When I released Cupertino, the setup process looked like this:

cupertino fetch --type docs --max-pages 15000  # ~20-24 hours
cupertino fetch --type evolution               # ~5 minutes
cupertino save                                 # ~5 minutes

Twenty hours. To respect Apple’s servers, the crawler waits 0.5 seconds between requests. 21,000 pages × 0.5s = a very long initial setup.

Users loved the tool but hated the onboarding. Fair.

The Solution: Pre-built Databases

Instead of everyone crawling Apple’s documentation independently, I now publish pre-built databases on GitHub Releases. The new setup flow:

cupertino setup   # ~30 seconds
cupertino serve   # Start MCP server

That’s it. Two commands. Under a minute.

How It Works

For Users

The setup command downloads a zip file from GitHub Releases containing:

• search.db (~1.1 GB) - 138,000+ documentation pages

• samples.db (~183 MB) - 606 sample projects, 18,000+ source files

$ cupertino setup

📦 Cupertino Setup

⬇️  Downloading Databases...
   ⠹ [████████████████░░░░░░░░░░░░░░]  53% (121.0 MB/228.1 MB)
   ✓ Databases (228.1 MB)
📂 Extracting databases...
   ✓ Extracted

✅ Setup complete!
   Documentation: /Users/you/.cupertino/search.db
   Sample code:   /Users/you/.cupertino/samples.db

💡 Start the server with: cupertino serve

If databases already exist, it skips the download:

$ cupertino setup

📦 Cupertino Setup

✅ Databases already exist
   Documentation: /Users/you/.cupertino/search.db
   Sample code:   /Users/you/.cupertino/samples.db

💡 Use --force to overwrite with latest version
💡 Start the server with: cupertino serve

For Me (Maintainer)

A new release command automates publishing:

$ cupertino release

📦 Cupertino Release v0.3.0

📊 Database sizes:
   search.db:  1.2 GB
   samples.db: 192.2 MB

📁 Creating cupertino-databases-v0.3.0.zip...
   ✓ Created (228.3 MB)

🔐 Calculating SHA256...
   17dac4b84adaa04b5f976a7d1b9126630545f0101fe84ca5423163da886386a6

🚀 Creating release v0.3.0...
   ✓ Release created

⬆️  Uploading cupertino-databases-v0.3.0.zip...
   ✓ Upload complete

✅ Release v0.3.0 published!
   https://codeberg.org/CupertinoHQ/cupertino/src/branch/main/docs/artifacts

When I refresh the documentation (re-crawl Apple’s docs), I bump the version and run cupertino release. Users get the update with cupertino setup --force.

Version Parity

The CLI version matches the database release tag:

This ensures schema compatibility. If I change the database structure in v0.4.0, users with CLI v0.4.0 will download v0.4.0 databases.

Three Ways to Set Up Cupertino

Now you have options:

1. Instant Setup (Recommended)

cupertino setup    # ~30 seconds
cupertino serve

Download pre-built databases. Fastest option.

2. Build from GitHub

cupertino save --remote    # ~45 minutes
cupertino serve

Stream documentation from GitHub and build locally. Useful if you want to verify the build process or can’t download the 228MB zip.

3. Full Crawl (Advanced)

cupertino fetch --type docs --max-pages 15000    # ~20-24 hours
cupertino fetch --type evolution
cupertino save
cupertino serve

Crawl Apple’s documentation yourself. Only needed if you want to modify the crawler or need documentation not in the pre-built database.

Compression Matters

The uncompressed databases total ~1.3 GB. The zip file is 228 MB - about 1/6 the size. SQLite databases compress extremely well because they contain repetitive text data.

This makes the download fast and keeps GitHub Release storage reasonable.

Database Updates

I’m actively crawling Apple’s documentation and updating the databases several times a week. Run cupertino setup --force to get the latest version.

The current public material lives with the main Cupertino repository:

• Database artifacts - Pre-crawled documentation and database material

• Sample source definitions - Apple sample code source metadata

What’s Next

• Automatic updates - Check for new database versions on startup

• Delta updates - Download only changed documents instead of full database

• More documentation sources - WWDC transcripts, Apple Tech Notes

Try It

# Install
git clone https://codeberg.org/CupertinoHQ/cupertino.git
cd cupertino && make build && sudo make install

# Setup (the new way)
cupertino setup
cupertino serve

Configure Claude Desktop and you’re done. Full Apple documentation access in under a minute.

Links

• Codeberg: codeberg.org/CupertinoHQ/cupertino

• Tag: v0.3.0

• Databases: Cupertino artifacts

The best feature is the one that removes friction. Twenty hours of crawling was friction.

I’m not alone. Developers everywhere report the same issues: AI suggesting @ObservableObject and @Published when Apple now recommends @Observable. Xcode 26’s AI integration hallucinating 100% of the time when asked about new 2025 frameworks. One developer described fixing AI-generated Swift code as “whack-a-mole”—fix one obsolete API, another pops up.

That frustration is why I built Cupertino.

In my previous post, I introduced it—an MCP server that gives Claude offline access to 22,000+ Apple documentation pages. That was version 0.1.x. Since then, things have evolved rapidly: nine releases in 72 hours, two new companion repositories, and a complete ecosystem for AI-assisted Apple development.

I need this tool. I use it every day. And I’m building it in public because I know I’m not the only one frustrated with AI that hallucinates Apple APIs.

What Changed: v0.1.6 → v0.2.3

The original Cupertino solved the core problem—searching Apple docs locally. But real-world usage revealed gaps: ranking wasn’t smart enough, storage was bloated, and legacy documentation was missing. Here’s what shipped:

Intelligent Ranking (v0.2.1)

The initial BM25 search treated all documents equally. A query for “View” might return some random extension before SwiftUI.View itself. Eight ranking heuristics now prioritize:

• Core types over extensions - View ranks above View+Accessibility

• URL depth analysis - /documentation/swiftui/view beats /documentation/swiftui/view/some/nested/thing

• Title pattern detection - Exact matches surface first

• Modern over deprecated - Current APIs rank higher

The result: sub-100ms queries that actually return what you’re looking for.

Storage Cleanup (v0.1.8, v0.2.0)

The initial crawl produced ~27GB of data. Most of it was cruft: .git folders from sample code downloads, .DS_Store files, Xcode user data. A new cleanup command reduced storage to 2-3GB—a 90% reduction.

Version 0.2.0 fixed a critical bug where cleanup was accidentally deleting source code instead of just metadata. Now 99.8% of sample ZIPs retain intact source.

Language Filtering (v0.1.9)

Not everyone wants Objective-C results. The CLI and MCP tools now accept a language parameter:

cupertino search "NSObject" --language swift

Claude can filter too—just ask for “Swift-only results.”

Apple Archive Support (v0.2.3)

Apple’s modern documentation is great, but some topics only exist in the legacy archive: Core Animation Programming Guide, Quartz 2D Programming Guide, Core Text Programming Guide. These are still the authoritative sources for low-level graphics work.

Cupertino now crawls developer.apple.com/library/archive/ and integrates results with smart ranking that prioritizes modern docs while keeping legacy content searchable.

The Ecosystem: Three Repositories

Cupertino grew from one repo to three:

cupertino — The MCP Server

The main Swift package. Crawls, indexes, and serves documentation via MCP protocol. Install it, point Claude at it, done.

# Quick setup with Claude Code
claude mcp add cupertino --scope user -- /usr/local/bin/cupertino

Cupertino database artifacts — Pre-Crawled Documentation

Don’t want to crawl everything yourself? Install Cupertino and populate the local databases:

cupertino setup

Currently includes:

Swift Evolution, Swift.org, and package docs are pre-indexed and ready. Apple Developer Documentation and Archive still require running cupertino fetch yourself due to size—but having the infrastructure in place is a start. The tooling exists; full pre-crawled distribution is coming.

Cupertino sample sources — Apple Samples

This is the fun one. Every official Apple sample code project, cleaned and ready to build:

• 100+ frameworks covered: SwiftUI, ARKit, RealityKit, Metal, CoreML, Vision, AVFoundation, HealthKit, HomeKit, and more

• 606 projects: From “Hello World” to complex GPU shaders

• Build-ready: No .git folders, no xcuserdata, no cruft

• MIT Licensed: Use them however you want

When you ask Claude “show me how Apple implements ARKit face tracking,” it can now search actual Apple sample code—not hallucinate an approximation.

Example projects include:

• arkit-* — Augmented reality implementations

• swiftui-* — Modern UI patterns

• metal-* — GPU programming examples

• coreml-* — Machine learning integrations

• avfoundation-* — Video and audio capture

The 72-Hour Sprint

Nine releases shipped in three days. Here’s the changelog:

Each release addressed real issues discovered while using Cupertino with Claude Code. Fast iteration, real-world testing.

Using the Full Ecosystem

Here’s the quickest path to AI-assisted Apple development with accurate documentation:

# 1. Build the MCP server
git clone https://codeberg.org/CupertinoHQ/cupertino
cd cupertino
swift build -c release
sudo cp .build/release/cupertino /usr/local/bin/

# 2. Download the public database bundle
cupertino setup

# 3. Configure Claude Code
claude mcp add cupertino --scope user -- /usr/local/bin/cupertino

Now when you ask Claude about Apple APIs, it searches 22,000+ pages of real documentation. No hallucinations. No deprecated patterns. Just accurate, current information.

What’s Next

The ranking heuristics work well but aren’t perfect. Planned improvements:

• make install — One command to install everything: the MCP server, pre-crawled docs, and sample source material

• Semantic search — Embeddings-based similarity for conceptual queries

• Version awareness — Filter by iOS/macOS version

• Cross-reference linking — “See also” connections between related docs

• Sample code search — Full-text search across all 606 projects

Join Me

If you’re an Apple developer tired of AI hallucinations, give Cupertino a try. If you find bugs or have ideas, open an issue—27 closed so far, plenty more to go.

This isn’t a polished product yet. It’s a tool I’m building because I need it, and I’m sharing it because you might need it too.

Repositories

• cupertino — MCP Server (Swift)

• Cupertino artifacts — Pre-crawled documentation

• Cupertino sample sources — Apple sample source metadata

No more AI hallucinations about Apple APIs. Just real documentation that compiles.

TL;DR: I built an MCP server that gives Claude Desktop offline access to 22,000+ Apple documentation pages across 261 frameworks. No more hallucinated APIs.

The Problem

If you’ve used Claude or ChatGPT for Swift/iOS development, you’ve seen this: