Axiom Apple Docs

Apple Documentation Router

Apple bundles for-LLM markdown documentation inside Xcode. These are authoritative, up-to-date guides and diagnostics written by Apple engineers. Read them directly with Claude Code's native `Read` tool — no MCP server or special tool required.

When to Use

• You need the exact API signature or behavior from Apple
• An Axiom skill references an Apple framework and you want the official source
• A Swift compiler diagnostic needs explanation
• The user asks about a specific Apple framework feature

Priority: Axiom skills provide opinionated guidance (decision trees, anti-patterns, pressure scenarios). Apple docs provide authoritative API details. Use both together.

How to Read These Docs

The session-start hook resolves Xcode's location and echoes the literal base directories into session context (look for "Apple for-LLM Documentation: Xcode detected at <path>"). Use the `Read` tool with <that base>/<filename>.

Default Xcode location (/Applications/Xcode.app) base directories:

Example invocation Claude should produce:

Read /Applications/Xcode.app/Contents/PlugIns/IDEIntelligenceChat.framework/Versions/A/Resources/AdditionalDocumentation/SwiftUI-Implementing-Liquid-Glass-Design.md

Xcode-beta users: the session-start hook respects AXIOM_XCODE_PATH and reports the resolved path in session context — use that path, not the default above.

Guide Files (AdditionalDocumentation)

20 files. Read with the path pattern {guides base}/{filename}.

UI & Design

Data & Persistence

Concurrency & Performance

Apple Intelligence

System Integration

Accessibility

Computer Vision

Swift Compiler Diagnostics

46 files in the diagnostics directory. Read with the path pattern {diagnostics base}/{filename}.

Concurrency Diagnostics

Type System Diagnostics

Build & Migration Diagnostics

Swift Language Diagnostics

Index

If a diagnostic you need isn't listed above, list the diagnostics directory first:

ls $AXIOM_XCODE_PATH/Contents/Developer/Toolchains/XcodeDefault.xctoolchain/usr/share/doc/swift/diagnostics/

Filenames follow the diagnostic's short name (lowercase, hyphenated).

Routing Decision Tree

User question about Apple API/framework?
├── Specific compiler error/warning → Read {diagnostics base}/<diagnostic-name>.md
├── Liquid Glass implementation     → Read {guides base}/<Framework>-Implementing-Liquid-Glass-Design.md
├── Swift concurrency patterns      → Read {guides base}/Swift-Concurrency-Updates.md
├── Foundation Models / on-device AI → Read {guides base}/FoundationModels-Using-on-device-LLM-in-your-app.md
├── SwiftData features              → Read {guides base}/SwiftData-Class-Inheritance.md
├── StoreKit / IAP                  → Read {guides base}/StoreKit-Updates.md
├── App Intents / Siri              → Read {guides base}/AppIntents-Updates.md
├── Charts / visualization          → Read {guides base}/Swift-Charts-3D-Visualization.md
├── Text editing / AttributedString → Read {guides base}/SwiftUI-Styled-Text-Editing.md or Foundation-AttributedString-Updates.md
├── WebKit in SwiftUI               → Read {guides base}/SwiftUI-WebKit-Integration.md
├── Toolbar features                → Read {guides base}/SwiftUI-New-Toolbar-Features.md
└── Other                           → ls the base directory to see what's available

Fallback When Xcode Is Unavailable

If AXIOM_XCODE_PATH is unset, or the path doesn't exist, or the IDEIntelligenceChat.framework directory is missing (older Xcode), fall back to:

1. sosumi.ai (markdown mirror of developer.apple.com — see axiom-tools/apple-docs-research.md) 2. WebFetch of the equivalent developer.apple.com URL 3. Suggest installing the latest Xcode for full Apple docs coverage

Do not silently fail — tell the user when Xcode docs aren't available locally and which fallback you used.

MCP Convenience Path

Clients using axiom-mcp can also invoke axiom_read_skill with the legacy ID (e.g., apple-guide-swiftui-implementing-liquid-glass-design). The MCP server reads the same Xcode files and returns the same content. Both paths are supported — the file-Read path works everywhere; the MCP path is a convenience for catalog/search workflows.

Research Methodology

For WWDC transcript capture (Chrome auto-capture), sosumi.ai documentation access, and multi-session research workflows, see skills/apple-docs-research.md.

Resources

Skills: axiom-swiftui, axiom-concurrency, axiom-data, axiom-ai, axiom-integration

Apple Documentation Research

When to Use This Skill

✅ Use this skill when:

• Researching Apple frameworks or APIs (WidgetKit, SwiftUI, etc.)
• Need full WWDC session transcripts with code samples
• Looking for Apple Developer documentation
• Want to extract code examples from WWDC presentations
• Building comprehensive skills based on Apple technologies

❌ Do NOT use this skill for:

• Third-party framework documentation
• General web research
• Questions already answered in existing skills
• Basic Swift language questions (use Swift documentation)

Related Skills

• Use superpowers-chrome:browsing for interactive browser control
• Use writing-skills when creating new skills from Apple documentation
• Use reviewing-reference-skills to validate Apple documentation skills

Core Philosophy

Apple Developer video pages contain full verbatim transcripts with timestamps and complete code samples. Chrome's auto-capture feature makes this content instantly accessible without manual copying.

Key insight: Don't manually transcribe or copy code from WWDC videos. The transcripts are already on the page, fully timestamped and formatted.

WWDC Session Transcripts via Chrome

The Technique

Apple Developer video pages (developer.apple.com/videos/play/wwdc20XX/XXXXX/) contain complete transcripts that Chrome auto-captures.

Step-by-Step Process

1. Navigate using Chrome browser MCP tool:

   {
     "action": "navigate",
     "payload": "https://developer.apple.com/videos/play/wwdc2025/278/"
   }

Tool name: mcp__plugin_superpowers-chrome_chrome__use_browser

Complete invocation:

   Use the mcp__plugin_superpowers-chrome_chrome__use_browser tool with:
   - action: "navigate"
   - payload: "https://developer.apple.com/videos/play/wwdc2025/278/"

2. Locate the auto-captured file:

• Chrome saves to: ~/.../superpowers/browser/YYYY-MM-DD/session-TIMESTAMP/
• Session directory uses Unix timestamp in milliseconds (e.g., session-1765217804099)
• Filename pattern: NNN-navigate.md (e.g., 001-navigate.md)

Finding the latest session:

   # List sessions sorted by modification time (newest first)
   ls -lt ~/Library/Caches/superpowers/browser/*/session-* | head -5

3. Read the captured transcript:

• Full spoken content with timestamps (e.g., [0:07], [1:23])
• Descriptions of code and API usage (spoken, not formatted)
• Chapter markers and resource links

What You Get

✅ WWDC transcripts contain:

• Full spoken content with timestamps (e.g., [0:07], [1:23])
• API names mentioned by speakers (e.g., widgetRenderingMode, supportedMountingStyles)
• Descriptions of what code does ("I'll add the widgetRenderingMode environment variable")
• Step-by-step explanations of implementations
• Chapter markers and resource links

❌ WWDC transcripts do NOT contain:

• Formatted Swift code blocks ready to copy-paste
• Complete implementations
• Structured code examples

Critical Understanding: Transcripts are spoken word, not code. You'll read sentences like "I'll add the widgetRenderingMode environment variable to my widget view" and need to reconstruct the code yourself from these descriptions.

When Code Isn't Clear from Transcript

If the transcript's code descriptions aren't detailed enough, follow this fallback workflow:

1. Check Resources Tab

• Navigate back to the WWDC session page
• Click "Resources" tab
• Look for "Download Sample Code" or "View on GitHub"
• Download Xcode project with complete working implementation

2. Use sosumi.ai for API Details

• Look up specific APIs mentioned in transcript
• Example: Transcript says "widgetAccentedRenderingMode" → look up sosumi.ai/documentation/swiftui/widgetaccentedrenderingmode
• Get exact signature, parameters, usage

3. Jump to Timestamp in Video

• Use transcript timestamp to jump directly to code explanation in video
• Example: Transcript says code at [4:23] → watch that specific 30-second segment
• Faster than watching entire 45-minute session

4. Combine Sources

• Transcript = conceptual understanding + workflow
• Resources = complete code
• sosumi.ai = API details
• Result: Full picture without manually reconstructing everything

Example transcript structure:

# Session Title - WWDC## - Videos - Apple Developer

## Chapters
- 0:00 - Introduction
- 1:23 - Key Topic 1

## Transcript
0:00
Speaker: Welcome to this session...

[timestamp]
Now I'll add the widgetAccentedRenderingMode modifier...

Example Session

WWDC 2025-278 "What's new in widgets":

• Navigate: https://developer.apple.com/videos/play/wwdc2025/278/
• Captured: 001-navigate.md
• Contains: ~15 minutes of full transcript with API references and code concepts

Apple Documentation via sosumi.ai

Why sosumi.ai

Developer.apple.com documentation is HTML-heavy and difficult to parse. sosumi.ai provides the same content in clean markdown format.

URL Pattern

Instead of:

https://developer.apple.com/documentation/widgetkit

Use:

https://sosumi.ai/documentation/widgetkit

URL Pattern Rules

Format: https://sosumi.ai/documentation/[framework]

Rules for framework name: 1. Lowercase - Use lowercase even if framework is capitalized (SwiftUI → swiftui) 2. No spaces - Remove all spaces (Core Data → coredata) 3. No hyphens - Remove all hyphens (App Intents → appintents, NOT app-intents) 4. Case-insensitive - Both SwiftUI and swiftui work, but lowercase is recommended

Common mistakes:

• ❌ app-intents → ✅ appintents
• ❌ axiom-data (skills/core-data.md) → ✅ coredata
• ❌ AVFoundation → ✅ avfoundation

Examples:

Using with WebFetch or Read Tools

WebFetch:
  url: https://sosumi.ai/documentation/widgetkit/widget
  prompt: "Extract information about Widget protocol"

Result: Clean markdown with API signatures, descriptions, examples

Framework Examples

Common Research Workflows

Workflow 1: New iOS Feature Research

Goal: Create a comprehensive skill for a new iOS 26 feature.

1. Find WWDC sessions — Search "WWDC 2025 [feature name]" 2. Get transcripts — Navigate with Chrome to each session 3. Read transcripts — Extract key concepts, code patterns, gotchas 4. Get API docs — Use sosumi.ai for framework reference 5. Cross-reference — Verify code samples match documentation 6. Create skill — Combine transcript insights + API reference

Time saved: 3-4 hours vs. watching videos and manual transcription

Workflow 2: API Deep Dive

Goal: Understand a specific API or protocol.

1. sosumi.ai docs — Get protocol/class definition 2. WWDC sessions — Search for sessions mentioning the API 3. Code samples — Extract from transcript code blocks 4. Verify patterns — Ensure examples match latest API

Workflow 3: Multiple Sessions Research

Goal: Comprehensive coverage across multiple years (e.g., widgets evolution).

1. Parallel navigation — Use Chrome to visit 3-6 sessions 2. Read all transcripts — Compare how APIs evolved 3. Extract timeline — iOS 14 → 17 → 18 → 26 changes 4. Consolidate — Create unified skill with version annotations

Example: Extensions & Widgets skill used 6 WWDC sessions (2023-2025)

Anti-Patterns

❌ DON'T: Manual Video Watching

BAD:
1. Play WWDC video
2. Pause and take notes
3. Rewind to capture code
4. Type out examples manually

Result: 45 minutes per session

✅ DO: Chrome Auto-Capture

GOOD:
1. Navigate with Chrome
2. Read captured .md file
3. Copy code blocks directly
4. Reference timestamps for context

Result: 5 minutes per session

❌ DON'T: Scrape developer.apple.com HTML

BAD:
Use WebFetch on developer.apple.com/documentation
Result: Complex HTML parsing required

✅ DO: Use sosumi.ai

GOOD:
Use WebFetch on sosumi.ai/documentation
Result: Clean markdown, instant access

Troubleshooting

superpowers-chrome MCP not available

Symptom: mcp__plugin_superpowers-chrome_chrome__use_browser isn't loaded in this session.

Solution: Fall back to the agent-browser CLI (/opt/homebrew/bin/agent-browser) to fetch the page, then read its output. Don't give up on the content or kill the user's Chrome — launch a separate profile instead if a live browser is required.

Chrome Session Directory Not Found

Symptom: Can't locate 001-navigate.md file

Solution: 1. Check Chrome actually navigated (look for URL confirmation) 2. Find latest session: ls -lt ~/Library/Caches/superpowers/browser/*/ 3. Session directory format: YYYY-MM-DD/session-TIMESTAMP/

Transcript Incomplete

Symptom: File exists but missing transcript

Solution: 1. Page may still be loading - wait 2-3 seconds 2. Try navigating again 3. Some sessions require scrolling to load full content

sosumi.ai Returns Error

Symptom: 404 or invalid URL

Solution: 1. Verify framework name spelling 2. Check sosumi.ai format: /documentation/[frameworkname] 3. Fallback: Use developer.apple.com but expect HTML

Verification Checklist

Before using captured content:

• ☐ Transcript includes timestamps
• ☐ Code samples are complete (not truncated)
• ☐ Speaker names and chapter markers present
• ☐ Multiple speakers properly attributed
• ☐ Code syntax highlighting preserved

Resources

Skills: superpowers-chrome:browsing, writing-skills, reviewing-reference-skills

Time Saved: Using this technique saves 30-40 minutes per WWDC session vs. manual video watching and transcription. For comprehensive research spanning multiple sessions, savings compound to 3-4 hours per skill.