axiom-core-spotlight-ref

# Core Spotlight & NSUserActivity Reference

## Overview

Comprehensive guide to Core Spotlight framework and NSUserActivity for making app content discoverable in Spotlight search, enabling Siri predictions, and supporting Handoff. Core Spotlight directly indexes app content while NSUserActivity captures user engagement for prediction.

**Key distinction** Core Spotlight = indexing all app content; NSUserActivity = marking current user activity for prediction/handoff.

---

## When to Use This Skill

Use this skill when:
- Indexing app content (documents, notes, orders, messages) for Spotlight
- Using NSUserActivity for Handoff or Siri predictions
- Choosing between CSSearchableItem, IndexedEntity, and NSUserActivity
- Implementing activity continuation from Spotlight results
- Batch indexing for performance
- Deleting indexed content
- Debugging Spotlight search not finding app content
- Integrating NSUserActivity with App Intents (appEntityIdentifier)

Do NOT use this skill for:
- App Shortcuts implementation (use app-shortcuts-ref)
- App Intents basics (use app-intents-ref)
- Overall discoverability strategy (use app-discoverability)

---

## Related Skills

- **app-intents-ref** — App Intents framework including IndexedEntity
- **app-discoverability** — Strategic guide for making apps discoverable
- **app-shortcuts-ref** — App Shortcuts for instant availability

---

## When to Use Each API

| Use Case | Approach | Example |
|----------|----------|---------|
| User viewing specific screen | `NSUserActivity` | User opened order details |
| Index all app content | `CSSearchableItem` | All 500 orders searchable |
| App Intents entity search | `IndexedEntity` | "Find orders where..." |
| Handoff between devices | `NSUserActivity` | Continue editing note on Mac |
| Background content indexing | `CSSearchableItem` batch | Index documents on launch |

**Apple guidance** Use NSUserActivity for user-initiated activities (screens currently visible), not as a general inde