Running it yourself

There are two ways to have this on your own machine. Install the website as an app, which takes one click and needs nothing else. Or run the whole thing from a terminal, which gets you a folder of readings in one go, search across all of them, and your own published copy.

Installing the app

The website can install itself. You get an icon with your other programmes, its own window with no address bar, and it opens without a connection once you've used it once. There's no download and nothing to approve.

Chrome, Edge	Open the reader and click the install icon at the right-hand end of the address bar, or use the "install this as an app" link at the bottom of the page.
Safari	File, then Add to Dock.
Firefox	No install on desktop. Bookmark it and carry on as normal, the site works exactly the same.

Your courses live in the browser either way, so anything you saved before installing is still there afterwards. To remove it, uninstall it like any other programme, or from the app's own menu.

This is still the website, so it reads PDFs the way the website does. For the terminal version and what it adds, carry on below.

What you need

Python 3.11 or newer, and git.

Setting it up

git clone https://github.com/tobyn-smith/reader
cd reader
python -m venv .venv
.venv/Scripts/activate
pip install -e ".[dev]"

On macOS or Linux, activate with source .venv/bin/activate instead. If you plan to send changes back, run git config core.hooksPath .githooks as well.

The commands

`vault syllabus syllabus.pdf`	Reads a syllabus and shows you what it found. Nothing is saved until you say so.
`vault ingest readings/`	Takes in a folder of reading PDFs and matches them to the schedule. Safe to run again.
`vault status`	This week: what you have, what's missing, what's due.
`vault search "commitment problem"`	Full text, across every reading you've taken in.
`vault build --public --pdf`	Builds the site the way GitHub Pages serves it.
`vault serve`	Opens the private build, with everything in it.

Where your files go

Your database, PDFs and caches sit in ~/.seminar-vault/, outside the repository. Coursework can't end up in a commit by accident.

Optional extras

`ocrmypdf`	Scanned PDFs with no text layer.
`pagefind`	Search on the built site.
`weasyprint`	Print PDFs locally. CI builds them anyway.

One feature each. Everything else works without them.

Publishing your own

Fork it, then Settings, Pages, source: GitHub Actions.
Run vault syllabus your-syllabus.pdf for each course and check the parse.
Run vault ingest your-readings/ as term goes on.
Run vault export --public, read what it kept and dropped, then commit data/public.json. Pushing publishes.

Only what's on the allowlist reaches the public site, and the tests fail if anything new turns up there. Schedules, citations, deadlines and bibliographies go out. Reading text, notes and your instructor's contact details stay on your machine.

Tests

pytest -q

Offline, no keys. The test files are syllabi I made up in the same layouts real ones use. They check the exact number of readings in each week, so a parser that drops one gets caught.

Browser vs terminal

Both run the same Python. The terminal sees the ruled lines a table is drawn with, so it pulls more rows off a page; the browser is choosier, and a larger share of what it keeps resolves into a proper citation. Neither is simply better, they miss different things. The figures on the front page are the browser's.

Measure it yourself against your own syllabi:

python scripts/measure.py ~/your-syllabi --web

Drop --web for the terminal's numbers. ARCHITECTURE.md in the repository has the rest, including what the parser gets wrong.

Back to the reader