New frameworks: usdkit, computegraph, foundationmodels, coreai, paperkit,
evaluations, proximityreader, sensorkit, fskit. Plus beta API additions across
realitykit, appintents, foundation, appkit, swift, metrickit, corespotlight,
swiftui and others. Net-new vs the existing corpus (URL-deduplicated); existing
pages untouched.
Paired with mihaelamj/cupertino#1093 which splits swift-org and
swift-book into independent fetchable sources.
Migration:
- cupertino-docs/swift-org/swift-book/ → cupertino-docs/swift-book/
- swift-book gets its own top-level corpus dir matching
defaultOutputDirKey = .swiftBook
- swift-org's metadata.json updated for the slimmer crawl
Content refresh:
- New cache snapshots from a forced fetch (8 minute crawl). All 43
topics now carry latest Apple content. Previously-orphan
summaryofthegrammar + revisionhistory have fresh cache snapshots.
swift-book.db consumers (cupertino save --source swift-book --clear)
read from cupertino-docs/swift-book/ now, not from swift-org/swift-book/.
The HIG crawler used to derive the `platforms: [...]` frontmatter +
`> **Platforms:** ...` body line from substring matching the whole
HTML for platform tokens. Every HIG page's nav/footer mentions all
5 platforms, so every page reported all 5 regardless of topic. The
`.md` files claimed `Designing for watchOS` is available on iOS /
macOS / tvOS / visionOS too — contradicting both the page's own
content and the post-#1073 schema fix.
The cupertino-side fix lands in mihaelamj/cupertino#1078: new
`HIGPlatformRules` foundation-tier table unifies crawler, indexer
strategy, and SQL backfill. This corpus commit rewrites the existing
.md files for the 10 platform-specific HIG topics:
- designing-for-watchos, watch-faces → watchOS only
- designing-for-tvos → tvOS only
- designing-for-visionos, spatial-layout → visionOS only
- designing-for-macos → macOS only
- mac-catalyst → iOS + macOS
- carplay, designing-for-ipados, designing-for-ios → iOS only
Cross-platform topics (the other 163 pages: buttons, alerts,
accessibility, etc.) are unchanged.
Apple's HIG site returned the same URL with two different <title>
shapes across consecutive fetches: one with the
" | Apple Developer Documentation" suffix the crawler stripped, one
with the dehyphenated "|AppleDeveloperDocumentation" variant it
didn't. The crawler used the (sanitized) title as the filename, so
every HIG topic landed twice: `buttons.md` plus
`buttons-appledeveloperdocumentation.md`.
The cupertino-side fix lands in mihaelamj/cupertino#1076: the
crawler now derives the filename from the URL's last path
component (Apple's canonical HIG slug), so the same URL always
maps to the same .md file regardless of title surface form. This
corpus commit removes the 173 stale duplicate files so the next
`cupertino save --source hig` reads exactly the 173 canonical
topics that should have been there all along.
Row count in hig.db drops 346 → 173 (one row per topic).
10 MB authoritative Apple SDK constraints table consumed by
cupertino's indexer at save time
(`Search.Index.applyAppleStaticConstraints` pass per #759
iter 3). Without this file the per-source-DB enrichment runs
iter 1+2 only (16% constraint coverage on doc_symbols rows);
with it the coverage rises to ~38%.
Source pipeline:
1. `cupertino-symbolgraphs-gen` runs
`xcrun swift symbolgraph-extract` over Apple frameworks ->
per-framework `.symbols.json` files (cupertino-symbolgraphs
v0.1.1, 406 slugs / 269 OK / 137 SKIP)
2. `cupertino-constraints-gen` filters those to
conformance + superclass constraint entries -> this
apple-constraints.json (61,040 entries)
3. `cupertino save` reads this file from `<base-dir>` if
present + applies the constraint pass per per-source DB
Regenerate when cupertino-symbolgraphs releases a new version
(per Swift / SDK bump, new framework, framework deprecation)
and commit the refreshed JSON here. The "always commit JSONs
with data to the GH repo" rule the user articulated 2026-05-27
applies here: this file IS data, not generated build artefact,
and should ride alongside the other corpus data in cupertino-docs.
The packages/ subtree is now a separate published repo:
https://github.com/mihaelamj/cupertino-packages
Initial content seeded from
cupertino-docs/packages@26fc51c92. cupertino-docs continues to
house apple-docs JSON, HIG, swift-evolution, swift-org,
swift-book, and archive corpora.
The split keeps per-source corpus repos independently versioned
and avoids the 1.5 GB packages bloat in cupertino-docs git
history. cupertino-sample-code (separate repo) and
cupertino-symbolgraphs (separate repo) already followed this
pattern.
Stage 2 archive download (codeload.github.com) of 137 seed
packages plus transitive dependencies discovered by walking
each Package.swift via raw.githubusercontent.com. Total 326 MB
written in 98 seconds after a 200-second resolver pass.
12 new top-level package owners since prior refresh:
- apple, awslabs, hummingbird-project, mattpolzin, mihaelamj,
ordo-one, orlandos-nl, realm, swiftlang, tuist, valkey-io, vapor
The 1290 deletions are mostly per-package availability.json
sidecars; they get regenerated by the optional
`--annotate-availability` pass, intentionally not included in
this stage.
Fetched via `cupertino fetch --source packages --skip-metadata`
(skipped stage 1 star-count popularity sort, which is throttled
to 60 req/h GitHub REST API unauthenticated). 1 package failed
to download (logged in
/tmp/cupertino-fetch-packages-archives-20260527-111255.log).
Updated:
- swift-org/package-manager.json
- metadata.json (crawl manifest)
Other 197 pages unchanged since prior crawl. The
`.cupertino-rejected-urls.jsonl` audit log is intentionally
untracked (crawl-time artefact, not corpus content). 198 pages
total in scope: 0 new, 1 updated, 197 skipped.
173 markdown pages across HIG components, foundations, patterns,
and inputs. Source: https://developer.apple.com/design/human-interface-guidelines/
Generated by `cupertino fetch --source hig` from Mac Studio
against the post-PR-#1067 release binary.
- Banner line updated from v0.9.0 (234,331 docs / 287 frameworks) to
v1.1.1 corpus tag (414,807 source files / 420 frameworks) with the
most recent published bundle (v1.1.0 zip: 285,735 indexed docs / 420
frameworks).
- Contents table expanded: now lists all six source folders that the
bundled search.db indexes (apple-docs, swift-evolution, swift-org,
hig, archive, packages + sample-code), with current per-source counts.
- Top Frameworks by Document Count table refreshed with v1.1.0 bundle
numbers (kernel 39,585 / matter 16,227 / foundation 10,372 / appkit
10,332 / uikit 9,078 / swift 9,026 / accelerate 7,863 / security
6,983 / coreservices 6,477 / swiftui 6,440).
The v0.9.0 numbers in the old README were from a half-year-old snapshot
that didn't include the v1.0.x → v1.1.0 corpus growth or the v1.1.1
Claw-merge contribution. Brings the public face of cupertino-docs in
line with what cupertino setup actually downloads.
Merge of Studio's v1.1.0 corpus (412,523 files) with Claw mini's
342,790-file crawl, per-file inspection across SHA-different + only-Claw
buckets:
498 overwrites from Claw (Claw's version had richer content; Apple
updated the page between the Studio crawl
in early May and the Claw crawl in mid-May)
2,285 new files from Claw (URLs Claw discovered that Studio missed,
mostly hash-suffixed Swift overload-
disambig pages)
153 dropped at boundary (Claw-only URLs whose content was poison —
JS-fallback / React 404 sub-view — filtered
out before commit)
Studio's existing 412,523 files plus 2,285 new from Claw = 414,807 files
total. Schema unchanged from v1.1.0. Post-merge 13-category poison audit
(414,807 files): 0 matches across all categories.
Companion writeup: blog draft '2026-05-14-merging-two-apple-doc-crawls.md'.
Source-corpus state at this commit is what cupertino-docs@v1.1.1 will tag.
- Remove 39 .md poison stubs containing Apple's React 404 sub-view body
("The page you're looking for can't be found"). These predated the
cupertino JSON crawler and snuck in via an old AppleDocs-tool import.
- Remove 21 .md files whose .json sibling already covered the same URL
with richer content. The .json wins on every duplicate.
- Convert the remaining 43 .md gap-fillers to canonical
StructuredDocumentationPage JSON (source: appleWebKit). These covered
Apple URLs not present as .json: Metal sync guides, CGImageRef,
CoreImage transitions, StoreKit views, audiotoolbox render blocks,
several scenekit / metalperformanceshaders / cloudkit entry points.
The original markdown body is preserved verbatim in the rawMarkdown
field for full-text search.
- Source corpus is now JSON-only (412,523 files); the .md format is
retired.
Companion to the crawler-side defense merged at cupertino 0fcd246
(PR #432, #284 follow-up). Tagged v1.0.3 as the baseline for the
v1.0.3 bundle build.
Major corpus refresh accompanying the cupertino #284 cleanup work:
docs/ (412,562 files / 2.4G total):
- Net change: 71,284 files (1,017,864 insertions / 4,503,415 deletions).
- Removed: 1,166 + 39 + 3 = 1,208 poison files Apple's CDN consistently
returns error templates for (JS-disabled fallback + Web Server Error
+ 502/403 titles).
- Added: 8,357 .json files recovered from cross-backup URL match
(May-09 jsonpass + private mirror + Apr-30 pre-recrawl).
- Added: 103 .md files from the November 2025 AppleDocs snapshot for
URIs not available as .json anywhere.
- Added: 580 synthesized stub .json files for URIs whose own page
Apple's CDN won't render but whose one-line description IS embedded
in the parent type's Topics section. Each stub carries the parent-
extracted description as 'abstract' and source: custom.
- Verified clean across 12 poison categories (no HTTP error titles,
no JS-disabled fallback, no Skip-Navigation broken bodies, no
openresty/CDN markers) by a full no-heuristics scan of all
412,458 .json + 103 .md files.
swift-evolution/ (912 files, +41 new):
- Refetched via 'cupertino fetch --type evolution' against
github.com/swiftlang/swift-evolution.
- 3 brand-new SE-XXXX proposals + 478 refreshed.
- Preserves the historical NNNN-descriptive-name files (429 of them)
that the cupertino-docs repo kept from the original swift-evolution
proposals/* directory layout — both naming conventions coexist.
swift-org/ (787 files, +2 from local sync).
archive/ (419 files, +12 from local sync).
packages/, hig/ unchanged.
Reference: #290 (re-publish v1.0.x bundle), #284 (poison rows, closed),
PR #289 + PR #291 (crawler + indexer defenses, merged into cupertino
main), #293 (URI collision design issue, filed).
No version bump on cupertino. The corpus tag below marks this state.
Bulk update of the public corpus from /Users/mmj/.cupertino-dev/, the
local source that built v1.0.0 / v1.0.1 release database bundles.
- docs/: 1,739 new pages, 403,381 modified (schema upgrade to the
structured-page format used by v1.0+: overview, rawMarkdown,
sections[].items[]). Total 404,568 page JSONs (2.4 GB).
- packages/: 1,587 packages (1.5 GB), previously empty in this repo.
Includes per-package source archives and READMEs for the curated
Swift package set. Some packages (notably swiftlang/swift-foundation-icu)
ship 50-100 MB ICU lookup tables — under GitHub's 100 MB limit.
No deletions: existing files not in .cupertino-dev are preserved
(e.g. swift-org/ has 81 historical pages this update doesn't touch).
Merges /Volumes/Code2/cupertino-backup-2026-04-30-pre-recrawl/ (the
in-progress JSON-only recrawl from Claw, 345k files / 2.2 GB) into
docs/ with the rule "keep the larger version per file". Adds 84,226
new pages and replaces 36,278 with larger versions; leaves 224,653
unchanged where the existing Mar 13 file was equal-or-larger.
Archives 9 frameworks that Apple has removed or renamed in the
~6 weeks since the Mar 13 baseline, into _archive/2026-03-13/:
Removed (now 404 on developer.apple.com):
availability, cocoa, objective-c, performance, sensitivecontent
Renamed/relocated (URL still resolves but under a different slug):
passkit_apple_pay_and_wallet → passkit
safariextensions → safariservices/safari_app_extensions
touchcontrols → touchcontroller
carekit → carekit-apple/CareKit (separate hierarchy)
Net effect: docs/ goes from 319,191 → 403,370 files (+26 %).
The 224,653 skipped files are notable — for those pages, the older
Mar 13 extractor produced richer content than the in-progress
JSON-only crawl. A WKWebView-only crawl (in flight on Claw) should
produce a fuller corpus and re-update docs/ when it completes.
The Quick Start section linked to cupertino-docs/releases which has no
releases. The pre-built databases are published on the main cupertino
repo. Also bumps the displayed version from v0.5.0 to v0.9.0.
Closes#1
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
Restores 188k docs accidentally deleted by rsync --delete, plus adds
new docs for 134 previously missing/incomplete frameworks.
Total: 319,190 doc files across 385+ frameworks.
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
Adds missing docs for 186 frameworks including Matter (25k+ pages),
CoreGraphics, CoreMedia, IOBluetooth, HIDDriverKit, and more.
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
Move the 84MB JSON file to LFS storage to comply with GitHub's
recommended file size limits.
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude <noreply@anthropic.com>
