README

ai-study

Personal workspace for analysing articles & papers, producing structured syntheses, and maintaining a referenced knowledge base. Designed for cross-platform use: capture on iOS, analyse on Mac.

Layout

ai-study/
├── synthesis/                  # per-article syntheses (one file per source)
├── inbox/                      # repo intake — Jina-fetched markdown from the iOS Shortcut
├── sources/                    # archived source PDFs by year (optional)
├── kb/
│   ├── topics/                 # rolling thematic dossiers
│   └── entities/               # short reference notes for orgs / people
├── index.md                    # map of everything (Quartz homepage)
├── .github/workflows/          # capture workflow (Jina Reader → inbox/)
└── .claude/commands/           # slash commands (/synthesise, /dossier, /inbox-clear)

Capture: getting articles in

Anti-bot protection blocks Claude’s WebFetch on a growing share of sites. The workspace has two intake paths so capture is one tap from anywhere:

• Repo inbox/ — primary intake for URLs. The “Send to ai-study” iOS Shortcut POSTs the URL to a GitHub Action that fetches it via Jina Reader and commits clean markdown to inbox/. Kills the PDF dance for the ~80% of pages Jina can read.
• Drive ai-study-inbox/source-files/ — fallback intake for pages Jina can’t read (paywalls, anti-bot, dynamic content). Drop a PDF (or .url file) here from iOS or Mac.

Both intakes are permanent archives — captured items stay forever. Processing state is tracked in synthesis frontmatter (source_inbox_file: or source_drive_file:), not folder location. /synthesise discovery mode scans both and filters out anything already synthesised.

iOS Shortcuts (one-off install)

Three signed .shortcut files live in tools/shortcuts/. AirDrop each to your iPhone and tap Add Shortcut. No “Allow Untrusted Shortcuts” toggle needed.

Shortcut	Use when
Send to ai-study	Default. POSTs URL to GitHub → Jina Reader → inbox/. Works on ~80% of articles.
Send to ai-study (Archive)	Paywalled / Jina-blocked sites (NYT, FT, WSJ, AFR, The Australian). Opens archive.ph/?run=1&url=… in Safari — pass the Cloudflare check interactively, wait for the snapshot.
Save to ai-study (PDF)	Pairs with (Archive): re-share the archive.ph page once it loads → this shortcut PDFs it and saves to Drive ai-study-inbox/source-files/. Also works on any Safari page when both other paths fail.

One-offs you still need to do once:

1. GitHub PAT. Generate a fine-grained personal access token at https://github.com/settings/tokens?type=beta, scoped to this repo only, with Contents: read & write. The Send to ai-study shortcut prompts for it during install (Shortcuts uses WFWorkflowImportQuestions — one tap to paste).
2. (Optional) Jina API key. The free tier handles personal volume fine; for higher limits add JINA_API_KEY as a repo Action secret (Settings → Secrets and variables → Actions → New repository secret). The workflow uses it automatically if present.
3. Drive folder. Create ai-study-inbox/source-files/ at the root of your Google Drive (used by the (PDF) shortcut and visible to this Mac Claude via the Drive MCP connector).

Rebuilding the shortcuts (after editing action structures in tools/shortcuts/src/build.py):

python3 tools/shortcuts/src/build.py

That regenerates the signed .shortcut files in place.

Verify: Share any article from Safari → tap Send to ai-study. Within ~30 s the Action runs (visible at https://github.com/Hark0q/ai-study/actions) and a new file appears under inbox/. Then on Mac, run /synthesise (no args) and the new inbox item shows up in the discovery list.

Mac URL capture

• URL works in WebFetch: just paste it. /synthesise <url> walks the fallback chain.
• URL blocked: Claude will try Wayback, Google Cache, /amp variants, and RSS before giving up. If everything fails, fall back to the PDF route above.

Anti-bot fallback chain

For URL inputs handed to /synthesise directly (not via the iOS Shortcut, which already used Jina), it tries in order:

1. Direct WebFetch
2. Jina Reader (https://r.jina.ai/<url>) — different engine, often beats anti-bot
3. Subagent retry (different cache state sometimes wins)
4. https://web.archive.org/web/<url> Wayback snapshot
5. Google Cache
6. Probe /amp, /print, /lite variants and the site RSS feed
7. Stop and ask for a PDF capture to Drive

If a fallback returned partial content (Wayback snapshots can miss dynamic blocks), the synthesis says so in its retrieval: field and at the top of the body.

Synthesis

Each article produces one file in synthesis/, named YYYY-MM-DD-slug.md where the date is the source’s publication date (so files sort by topic-relevance, not by when you got around to reading them).

Structure (see synthesis/2026-05-08-apra-ai-governance.md for the canonical example):

• YAML frontmatter (source, authors, retrieval method, tags, linked topics/entities)
• Headline message (1 paragraph)
• Key takeouts (3–6 bullets)
• Wider context
• Section-by-section breakdown
• Action implications / open questions
• Wikilinks footer to topic dossiers and entities

Knowledge base — rolling topic dossiers

kb/topics/<slug>.md is the long-running “what we know now” view for a topic. After each synthesis, Claude updates the relevant dossier:

• Refreshes the “Current state” paragraph if the new source materially shifts it
• Appends claims with [[wikilink]] to the source synthesis
• Proposes a refactor when claims start to repeat

Every factual claim cites at least one synthesis. No orphan claims. [[wikilinks]] use Obsidian syntax — works in Obsidian/Bear if you want a graph view; renders as plain text on GitHub but the linked filename is still visible.

kb/entities/<slug>.md is a short stub for an org/person/instrument referenced across multiple syntheses.

Slash commands

• /synthesise — no args: list unprocessed items across both intakes (repo inbox/ and Drive source-files/) and pick one. With args (<url-or-file>): full pipeline (fetch → synthesise → update dossier → commit).
• /dossier <topic> — open, refactor, or create a topic dossier
• /inbox-clear — audit both intakes against synthesis frontmatter; backfill any missing source_inbox_file: / source_drive_file:

Commit / push policy

One commit per synthesis (covering the synthesis file, dossier updates, entity updates, index.md update). Pushed to origin/main. The repo on GitHub gives you a mobile-readable view via Safari on iOS — useful for browsing the KB without needing the Claude app.

sources/ does not commit large PDFs — Drive is the source of truth for raw captures. If you want a local PDF archive, drop it in sources/<year>/.

What’s not in scope yet

• Auto-poll the inboxes on a schedule (could add via /loop or a routine later)
• Auto-categorising into topic dossiers
• Weekly digest of new syntheses

Disclaimer

Syntheses are prepared for personal study. Quoted material belongs to the original publishers. Not legal, financial or professional advice.