README

ai-study iOS Shortcuts

Three signed .shortcut files that handle every capture path the workspace needs. Built on macOS via tools/shortcuts/src/build.py and signed with shortcuts sign --mode anyone so they install on any iPhone — no “Allow Untrusted Shortcuts” toggle required.

Files

File	Share-sheet entry	Sends to	Use when
send-to-ai-study.shortcut	Send to ai-study	GitHub Action → Jina Reader → inbox/	Default. ~80% of articles.
send-to-ai-study-archive.shortcut	Send to ai-study (Archive)	Opens archive.ph/?run=1&url=… in Safari	Paywalled / Jina-blocked sites (NYT, FT, WSJ, AFR, The Australian). Pass Cloudflare interactively.
save-to-ai-study-pdf.shortcut	Save to ai-study (PDF)	Drive ai-study-inbox/source-files/	After Cloudflare bypass on archive.ph, or for any page Jina/Action can’t read. Also works as a one-tap PDF fallback from any Safari page.

Install (one-off)

On Mac:

# Build all three (recreates .shortcut files in this directory)
python3 tools/shortcuts/src/build.py

Then for each .shortcut file:

1. AirDrop to your iPhone (Finder right-click → Share → AirDrop), or drop them in iCloud Drive / Files and open from there.
2. iOS opens the import preview in Shortcuts.app. Tap Add Shortcut.
3. For send-to-ai-study.shortcut only, you’ll be prompted to paste your GitHub fine-grained PAT (Contents: read/write on Hark0q/ai-study). Generate one at https://github.com/settings/tokens?type=beta.
4. In Shortcuts → tap ⋯ on each → Details → enable “Use with Share Sheet” if not already on.

After install, the three shortcuts show up under Safari’s share sheet. Pick whichever path fits the article.

How the three paths fit together

                     ┌─────────────────────┐
                     │  Safari share sheet │
                     └──────────┬──────────┘
                                │
       ┌────────────────────────┼────────────────────────┐
       ▼                        ▼                        ▼
┌──────────────┐       ┌────────────────┐       ┌────────────────┐
│ Send to      │       │ Send to        │       │ Save to        │
│ ai-study     │       │ ai-study       │       │ ai-study (PDF) │
│ (Jina)       │       │ (Archive)      │       │                │
└──────┬───────┘       └────────┬───────┘       └────────┬───────┘
       │                        │                        │
       ▼                        ▼                        ▼
  GitHub Action            archive.ph                Drive
  → Jina Reader            (Safari opens,            ai-study-inbox/
  → inbox/                  user passes CF)          source-files/
                                │
                                │ user then re-shares
                                │ resulting page →
                                ▼
                         ┌────────────────┐
                         │ Save to        │
                         │ ai-study (PDF) │
                         └────────────────┘

Why three shortcuts instead of a menu

A single menu shortcut would mean every capture is two taps (share → pick menu option). The Cloudflare-on-archive.ph case already needs two share-sheet hops; making the common Jina case slower to compensate is the wrong trade.

Editing / rebuilding

Action structures live in src/build.py. After edits:

python3 tools/shortcuts/src/build.py

The script emits XML plists into src/_build/, runs plutil -convert binary1, and signs with shortcuts sign --mode anyone. The _build/ artifacts are gitignored — only the signed .shortcut files are committed.

Notes on the format

• iOS Shortcut files are binary plists with a signed wrapper. shortcuts sign --mode anyone produces a file anyone can import; without that, iOS would require the recipient to toggle “Allow Untrusted Shortcuts” in Settings → Shortcuts.
• Variable references inside action parameters use the WFTextTokenString serialization: the string contains U+FFFC (Object Replacement) characters at each variable position, and a parallel attachmentsByRange dict maps {location, length} keys to variable refs. The builder handles this automatically.
• Import-time substitution (the PAT prompt on send-to-ai-study) uses WFWorkflowImportQuestions to bind a prompt to a specific action’s parameter (ActionIndex + ParameterKey).