Scan intake — design + build tracker

TL;DR — v1 pipeline live

Apple Notes is out as the document intake — gray-square attachments (Circle M lease) + TCC wall on scanned attachments (6/4 truck repair) proved the path. Replaced with iCloud Drive "Scan Inbox" folder. Option B picked + executed: iCloud Drive enabled on M4 directly, no MBA bridge. Native Files-app scanner → iCloud syncs to M4 → launchd job every 5 min runs process.mjs → OCR via tesseract → parks each doc in ~/scan-inbox/_review/ with ocr.txt + meta.json for Aria triage. End-to-end test passed 2026-06-08. Next: LLM classifier (Sonnet) to auto-route high-confidence docs straight into drawer memory, then NAS archive + brief integration. Tracked in OPS-112.

1 · The flow (live)

┌─────────────────────────┐   ┌──────────────────────────────────┐
│  iPhone (Topher/Jaime)  │   │  iCloud Drive (M4 directly        │
│                         │   │  signed in as of 2026-06-08)      │
│  Files → Scan Inbox →   │──>│    Scan Inbox/_inbox/             │
│  tap • • • → Scan Docs  │   │                                   │
│  → save                 │   │  (shared w/ Jaime — TODO step §5) │
└─────────────────────────┘   └─────────┬─────────────────────────┘
                                        │ native iCloud sync
                                        ▼
                              ┌──────────────────────────┐
                              │  M4 launchd (5 min):     │
                              │  com.aria.scan-intake    │
                              │                          │
                              │  process.mjs:            │
                              │  1. OCR via tesseract    │
                              │  2. Move src → ~/scan-   │
                              │     inbox/_review/       │
                              │     <date>-<slug>/      │
                              │  3. Write ocr.txt +      │
                              │     meta.json           │
                              │  (later: LLM classify    │
                              │   → auto-file → NAS)     │
                              └──────────┬───────────────┘
                                         │
                                         ▼
                              ┌──────────────────────────┐
                              │  Aria reviews in next    │
                              │  session, files into     │
                              │  the right drawer        │
                              │  (until classifier ships)│
                              └──────────────────────────┘

2 · What's live (v1 pipeline)

Inbox: ~/Library/Mobile Documents/com~apple~CloudDocs/Scan Inbox/_inbox/ (iCloud Drive)
Processing artifacts: ~/scan-inbox/_review/ _processed/ _logs/ on M4 (local, no iCloud churn)
skills/scan-intake/process.mjs — OCR pipeline:
- Images (JPG/PNG/TIFF/BMP) → tesseract
- HEIC → sips→JPG → tesseract
- PDF → pdftotext if it has a text layer, else pdftoppm → tesseract per page
- Each doc moves from iCloud inbox to _review/<date>-<slug>/ with ocr.txt + meta.json
- Skips .icloud placeholders (file not yet downloaded) and files < 10 s old (still syncing)
launchd: com.aria.scan-intake, every 5 min (StartInterval 300)
Daily log at ~/scan-inbox/_logs/YYYY-MM-DD.log
Not yet wired: LLM classifier, NAS archive, brief integration, dashboard tile, Jaime how-to page

2.5 · One-time setup gotcha (documented for posterity)

Even after enabling iCloud Drive on M4, the terminal hosting Claude Code couldn't read iCloud Drive contents — directory entries existed but ls, readdir, and brctl all returned silently with zero output. Cause: Full Disk Access TCC grant required on macOS 25+ for iCloud Drive contents, even though the directory metadata is readable. Fix: System Settings → Privacy & Security → Full Disk Access → add /Users/tophermacstudio/.local/bin/claude and /usr/libexec/sshd-keygen-wrapper, toggle ON, fully quit + relaunch the Claude session (TCC caches per-process). Done 2026-06-08.

3 · Sync substrate decision — RESOLVED: Option B

Topher picked Option B (iCloud Drive enabled on M4 directly) 2026-06-08. Pipeline now reads ~/Library/Mobile Documents/com~apple~CloudDocs/Scan Inbox/_inbox/ directly. No MBA bridge needed, no NAS onboarding, no Shortcut setup. Trade-off accepted: Topher's personal Apple ID is now signed into the M4. Mitigation: keep an eye on iCloud Drive disk usage; selectively unsync large folders if needed.

For posterity: alternatives considered were Option A (MBA-as-bridge launchd rsync — adds a moving part, depends on MBA being awake) and Option C (iOS Shortcut → NAS/R2 — more engineering, Jaime onboarding tax). Re-revisit only if iCloud Drive itself becomes a problem.

4 · Remaining design decisions (Aria proposes defaults)

Question	Aria's default	Override if…
Vegas in the loop?	No live watcher. Aria flags AD-relevant docs in morning brief; specialist chat opens with a brief if needed.	…you want Vegas/specialists actively reading the intake folder. Unusual fit, but possible.
Jaime-facing agent?	No new agent. Jaime drops, Aria files, you + Jaime get a daily digest of "what got filed."	…Jaime wants her own chat to discuss filing decisions.
Cadence	Every 5 min via launchd. Briefing surfaces results at morning/lunch/EOD.	…you want push notifications on every processed scan.
Auto-file threshold	Confident classify → file silently + brief report. Unsure → `_review/` + brief flag.	…you'd rather review every doc before filing for the first few weeks.
Original archive	NAS `Documents/<category>/YYYY-MM-DD-<slug>.pdf` after filing.	…you want originals to stay in iCloud too, or to also email yourself a copy.

5 · Build plan — remaining

Sync wire-up — Option B done. iCloud Drive reads working from M4.
launchd job — com.aria.scan-intake, every 5 min. Loaded 2026-06-08.
Folder sharing with Jaime — From Topher's MBA: Finder → iCloud Drive → right-click Scan Inbox → Share → invite Jaime by Apple ID, "Can make changes." On both phones: Files → Browse → iCloud Drive → long-press Scan Inbox → Add to Favorites for one-tap access.
LLM classifier — add a Sonnet pass to process.mjs reading ocr.txt and returning {drawer, confidence, suggested_filename}. Threshold for auto-file: ≥0.8 confidence. Below → stays in _review/.
Drawer routing rules — map classifier output to drawer memory paths (vehicles/, finance/, hoa/, family-health/, aspire-digital clients, etc.).
NAS archive — once filed, copy original to NAS under Documents/<category>/.
Brief integration — morning/lunch/EOD brief reads ~/scan-inbox/_review/ + filed summary from log.
Dashboard tile on CC homepage: last run, N files in _review/, last 5 filed.
How-to page at /info/scan-intake-howto — the 30-second explainer for Jaime: "open Files, tap Scan Inbox, tap the camera icon, scan, save."

6 · Why Notes is the wrong intake (documented for posterity)

TCC wall on attachments (6/4 truck repair). Even when a note shows the scan in the Notes UI, AppleScript can't extract the image, and terminal can't read the Notes container without Full Disk Access. Aria sees that a scan exists, can't read the content.
Shared-folder attachment sync is fragile (6/8 Circle M). Jaime's scan made the note placeholder character () replicate to every device, but the attachment object never uploaded to iCloud. Gray squares everywhere, including on Jaime's own re-pull. Not a download lag — a never-uploaded state. No amount of waiting fixes it.
Folder share invites are per-device. Each Mac that wants to see a shared Notes folder must accept the invite locally. M4 (headless) can't easily do this; adds friction.
Conclusion: Notes is fine for handwritten thoughts + quick lists. Documents-to-file go to a Files-app watched folder where the OS doesn't try to be clever about attachments.

7 · Linear tracker

Build progress tracked in OPS-112 — Scan intake system (OSB project: Aria System).