DOCUMENTATION

Get the most out of Ultimate Clarity.

Quick-start guides, feature documentation, and troubleshooting for Ultimate Clarity on macOS. New here? Start with the 5-minute first scan walkthrough below.

Quick start

Got the app installed and want to see what it does? Five minutes start to finish.

  1. 1

    Grant access to your Photos library

    First launch asks for Photos permission. Click Allow in the macOS system dialog. Clarity reads metadata only — actual photos stay where Apple put them. Without this, Person Search and Face Recognition cannot work.

  2. 2

    Run the first scan

    Click Scan All on the Dashboard. Clarity reads your library, runs Apple's Vision face detection, computes perceptual hashes for duplicate detection, and indexes metadata. For 10,000 photos: ~3 minutes on M2. For 100,000+: ~25–40 minutes — set it running and walk away.

  3. 3

    Try Person Search

    Open the Person Search tab in the sidebar. Type a name, or click an unnamed face cluster to label it. The first time you tag someone you'll see every file (photos, PDFs, documents) where their face, name, email, phone, or ID appears.

  4. 4

    Set up the Vault

    Sidebar → Vault. Click Set up vault. You'll create a password, register Touch ID/Face ID for unlock, and write down the 12-word BIP39 recovery phrase. Write it on paper — losing both password and recovery phrase = vault is permanently inaccessible.

  5. 5

    Explore Smart Duplicates

    Sidebar → Smart Duplicates. Clarity finds exact and near-duplicate photos using three perceptual hash algorithms. Review groups, pick keepers, delete the rest. Typical reclaim: 4–12 GB on a 50,000-photo library.

Feature documentation

Face Recognition

Apple Vision detects and clusters faces across your library. Tag a face once and it's named everywhere it appears — photos, scanned documents, PDFs.

Find it: Sidebar → People

Person Deep Search

Find every file mentioning a specific person — not just by face, but by name (OCR + filename), email, phone, ID, or GPS. Built for GDPR / DSAR compliance.

Find it: Sidebar → Person Search

Smart Duplicates

Three perceptual hash algorithms (pHash, dHash, aHash) find exact AND near-duplicates. Burst photos, slightly cropped versions, different exports — all clustered.

Find it: Sidebar → Smart Duplicates

Universal Vault

AES-256-GCM encrypted storage for any file type. Touch ID / Face ID / Optic ID unlock. BIP39 recovery phrase. Intruder Capture if wrong code is entered.

Find it: Sidebar → Vault

Privacy Cleaner

Strips EXIF, GPS, timestamps, camera info from photos and PDFs. 10 metadata risk categories — keep what you need, remove what's risky.

Find it: Sidebar → Privacy Cleaner

Auto-Redact PII

Detects ID numbers, faces, emails, phones across 21 countries. Redacts before sharing. 36+ document types supported.

Find it: Tools → Auto-Redact

Life Happens Exports

12 templates: Wedding, New Baby, Memorial, Pet Memorial, Family History, Separation, Moving, GDPR Request, DSAR, Employment Transition, Asset Documentation, Legal Package.

Find it: Sidebar → Life Happens

Rules Engine

22 conditions × 11 actions. Automate organization, tagging, vault-moves, exports. Run on schedule or on-demand.

Find it: Tools → Rules

Scheduled Tasks

8 task types running daily/weekly/monthly: Person Search, Face Detection, Duplicates, Privacy Audit, PII Scan, Content Safety, OCR, Metadata Cleanup.

Find it: Settings → Scheduled Tasks

Troubleshooting

Photos library access not working

macOS → System Settings → Privacy & Security → Photos. Make sure Ultimate Clarity is enabled. If it's not in the list, quit Clarity, relaunch, and grant permission when the system dialog appears. If the dialog never appears, reset TCC: open Terminal and run tccutil reset Photos com.clarityapp.ClarityNew, then relaunch Clarity.

Scan is stuck or very slow

First scan on a 50,000+ library takes 25–40 minutes on M2. Check Activity Monitor — Clarity should be using GPU and CPU. If it's been hours with no progress, force-quit and relaunch — the scan resumes from the last checkpoint. Heat throttling on M1 / Intel can slow processing significantly.

Vault unlock fails with correct password

After 5 failed attempts the vault locks for 60 seconds. After 10 failed attempts it locks for 5 minutes — and Intruder Capture takes a webcam photo. If your password is correct but unlock keeps failing, try restarting your Mac (occasionally Keychain caches stale state). If still failing, use your 12-word BIP39 recovery phrase: Vault → Forgot password → Use recovery phrase.

Person Search returns no results

Person Search needs both face indexing AND text indexing complete. Settings → Index Status shows progress for each. If face index is 0%, make sure scan completed without errors. If text/OCR index is 0%, wait — OCR takes longer than face detection on first scan.

App crashes on launch

Most launch crashes are caused by corrupted preferences. Quit Clarity, then in Terminal run: defaults delete com.clarityapp.ClarityNew followed by killall cfprefsd, then relaunch. If crash persists, send the crash log: Console.app → Crash Reports → search "Clarity" → email the most recent log to hello@ultimateclarity.app.

Drag-and-drop into vault not working

macOS sandbox sometimes blocks NSItemProvider drops from Photos.app or Preview. Workaround: drag the file to Desktop first, then drag from Desktop into the vault. We're working on a structural fix — track progress in Release Notes.

Still stuck?

Email a description, what you tried, and macOS version. One person reads every message.

hello@ultimateclarity.app