Lectio

A study environment for the AP Latin exam under the 2025–26 framework — Vergil's Aeneid and Pliny the Younger's Letters. Built for one student, one exam: Friday, 14 May 2027.

Deployed at lectio.norvodesigns.com.

Next.js (App Router) · TypeScript · Tailwind v4 · Zustand · Vercel AI SDK.

There is also a native iPhone and iPad app (SwiftUI, Liquid Glass), built from the same content and syncing the same progress. See ios/README.md. An Android app (Kotlin, Jetpack Compose, with a Wear OS watch app) does the same on Google Play. See android/README.md. If you edit anything under src/data, run npm run export:content so the apps' copy of the course stays current (CI checks).

---

What's in it

Section	What it does
Dashboard	Countdown, mastery by unit and skill category, recent scores, what to study next, streak
Reading Room	Every syllabus passage with click-any-word glossary, highlights in eight colours, sentence-part marks, notes, printable study sheets, bookmarks, line flagging, and a cold read that hides the glossary and all your own marks
Translate	Literal-translation drills in the exam's own 15-segment shape, with self- and AI-grading
Sight Reading	Timed unseen passages from the CED's recommended authors, plus an AI generator
Quiz Engine	Configurable MCQ sets filtered by author, passage, unit, skill or question type; review queue
Vocabulary	SM-2 spaced repetition over all 990 words of the official required list
Grammar & Syntax	The constructions AP tests, with examples from the real passages
Scansion Lab	Interactive dactylic hexameter with a rules tutorial
Literary Devices	Reference cards plus a spot-the-device drill
Context & Culture	Vergil, Augustan Rome, Pliny's world, Vesuvius, provincial administration
FRQ Workshop	All five free-response types, timed, with official rubrics and a Course Project mode
Practice Exam	52 MCQ / 65 min, then 5 FRQ / 115 min, with a scored breakdown
Study Plan	Phases measured backwards from exam day
Settings	Theme, data export/import, AI usage meter

Keyboard

⌘K / Ctrl+K opens the command palette. g then a letter jumps to a section (g r for Reading Room, g v for Vocabulary, and so on — each section's letter is shown on hover in the sidebar). In the Reading Room: m mark up, c cold read, t English, n your notes, b bookmark; with words selected, 1–8 pick a colour and Delete takes the mark off. In the Quiz Engine, 1–4 answer and ↵ advances. In Vocabulary, space reveals and 1–4 grade.

---

Running it locally

npm install
cp .env.example .env.local     # then paste your key in (see below)
npm run dev                    # http://localhost:3000

Other scripts:

npm run build       # production build
npm run typecheck   # tsc --noEmit
npm run lint        # eslint
npm run verify      # content integrity checks — see below
npm run export:content    # re-export src/data for the iOS app (ios/Content)
npm run export:fixtures   # regenerate the iOS app's sync/SM-2 parity fixtures

npm run verify is worth knowing about. It checks that every answer key resolves to a real option, that every translation segment appears contiguously in its passage, that every grammar or device example really occurs in the passage it cites, that scansion feet add up and reconstruct their line, and that FRQ rubrics total the points the exam actually awards. It caught fifteen real content errors the first time it ran. Run it after editing anything under src/data.

---

Getting a free Gemini API key

1. Go to Google AI Studio and sign in with a Google account.
2. Click Create API key. Pick an existing Google Cloud project or let it make one.
3. Copy the key. You will not be shown it again.

Then, for local development, paste it into .env.local:

GOOGLE_GENERATIVE_AI_API_KEY=your-key-here

Adding it to Vercel

1. Open your project in the Vercel dashboard.
2. Settings → Environment Variables.
3. Add GOOGLE_GENERATIVE_AI_API_KEY with your key as the value. Tick Production, Preview and Development.
4. Redeploy — environment variables are read at build and run time, so an existing deployment will not pick up a new variable until it is redeployed.

Never prefix these with NEXT_PUBLIC_. Anything with that prefix is inlined into the JavaScript bundle and served to every visitor. These keys are read only inside route handlers under src/app/api/, which run on the server. No client component references them, and src/lib/ai/provider.ts imports server-only so a stray client import fails the build rather than leaking the key.

A note on the free tier and your data

Google's free tier for the Gemini API is free because your prompts and responses may be used to improve their models. Paid tiers are not. Everything this app sends is Latin passages and your own translations and essays, so there is nothing sensitive in it — but it is worth knowing, and it is why nothing in this app sends anything you have not explicitly asked it to grade.

Free-tier model availability also changes without much notice: models get renamed, deprecated, or have their quotas moved. That is exactly why the provider is behind an abstraction.

---

Switching providers

Everything goes through src/lib/ai/provider.ts. To change the primary provider, edit one line:

const PRIMARY: ProviderName = 'google';   // change to 'groq'

Groq is already wired up as an automatic fallback. When Gemini returns a 429 (rate limit or quota exhausted) or a 404 (model retired or renamed), the request is retried on Groq transparently. Get a key at console.groq.com/keys and set:

This is the beginning of the README. Read the rest at the original. Read the full README ↗