# ClassicsLens User Guide

## Table of Contents

1. [Getting Started](#getting-started)
2. [Student Guide](#student-guide)
3. [Instructor Guide](#instructor-guide)
4. [Admin Guide](#admin-guide)
5. [Common Questions](#common-questions)
6. [Troubleshooting](#troubleshooting)

---

## Getting Started

### Creating an account

Go to [classicslens.com](https://classicslens.com) and click **Sign in with Google** or use an email address and password. If your instructor has already invited you by email, your account will automatically be linked to their class when you sign up — no extra steps needed.

### Navigating the app

The navigation bar has tabs that vary by account tier:

| Tab | Who sees it | What it's for |
|-----|-------------|--------------|
| **Today** | Everyone | Your daily passage plus any assigned readings |
| **Review** | Everyone | Flashcard review of words you've saved |
| **Analyze** | Everyone | Parse any Latin or Greek word |
| **Classes** | Instructor/Academic | Class and student management |
| **Settings** | Everyone | Language preferences, display options, account |

Two additional destinations are accessible via links at the bottom of the Today page:

- **View your progress** — reading heatmap, vocabulary growth, grammar weak spots
- **My Texts** — upload and read your own Latin/Greek texts (Pro, Instructor, and Academic only)

---

## Student Guide

### Reading a passage

Each day brings one new passage — Latin, Greek, or alternating depending on your settings. The passage appears on the **Today** tab.

**Clicking a word** opens a popup showing:
- The dictionary headword (e.g. *amor*, *λόγος*)
- Part of speech
- Short definition
- Morphological analysis (e.g. *pres. act. ind. 3sg*)
- Principal parts for verbs
- Frequency rank (how common the word is in Classical literature)
- Links to Logeion and Perseus for deeper lookup
- A one-tap button to save the word to your flashcard deck

Click anywhere outside the popup to close it.

**POS coloring** (togglable in Settings) highlights verbs in amber, nouns in blue, adjectives in green, and pronouns in violet. Useful for quickly spotting the structure of a sentence.

**The context card** (collapsible, below the passage header) gives AI-generated historical notes about the passage — author background, thematic tags, and what makes this excerpt significant. Helpful for orienting yourself before reading.

**Reveal translation** shows a public-domain English translation. It's hidden by default so you can attempt the passage first.

**Comprehension questions** appear below the translation (where available). They test your understanding of the passage content.

**Mark as done** records the passage as complete, advances your day counter, and maintains your streak. Your streak resets if you skip a day.

### Managing your vocabulary

**Saving words**: click any word in a passage and tap the blue "Review" button, or do the same from the Analyze tab. The word is added to your SRS deck with the inflected form, lemma, definition, and morphology.

**The Review tab** shows cards that are due based on spaced repetition. Each card shows the inflected form on the front and the lemma, definition, morphology, and the passage where you first saw the word on the back.

Grade each card:
- **Again** — you forgot it; the card comes back soon
- **Good** — you remembered it; interval extends moderately
- **Easy** — you knew it instantly; interval extends significantly

The **due-count badge** on the Review tab icon updates every minute. Try to clear it daily.

**Anki export**: go to Settings → Account → "Download Anki deck". Downloads a TSV file compatible with Anki's import format. Cards are tagged `ClassicsLens` and organized by language.

### My Texts (Pro, Instructor, Academic)

**My Texts** lets you upload your own Latin or Greek texts — handouts, textbook exercises, custom readings — and use all ClassicsLens tools on them: word parsing, SRS, and the Analyze tab.

**To access:** scroll to the bottom of the Today page and click **My Texts**.

**Uploading a text:**
1. Click **Upload a text**
2. Enter a title (required) and author (optional)
3. Select the language: Latin or Greek
4. Paste the text (up to 50,000 characters)
5. Check the box: *"I am uploading text I have the right to use for personal study"*
6. Click **Upload**

The text is private — only your account can access it.

**Reading:** click any text in your list to open it in the full reader. Everything works the same as a built-in passage: click words for parse popups, save to your SRS deck, use the Analyze tab.

**Quotas:**

| Tier | Max texts | Max length |
|------|-----------|------------|
| Pro | 20 | 50,000 chars each |
| Instructor | 100 | 50,000 chars each |
| Academic | 100 | 50,000 chars each |

**Deleting a text:** click the trash icon next to any text in your list. This is permanent and cannot be undone.

---

### Tracking progress

The **Progress** page (linked at the bottom of the Today tab) shows:
- A 52-week reading heatmap — darker squares are days you read more
- Vocabulary growth chart — words added to your deck over time
- Grammar weak spots — morphological patterns (e.g. "Greek aorist passive subjunctive") ranked by how often you grade them "Again"

### Language mix

In **Settings → Language Mix**, choose:
- **Latin only** — all passages are Latin
- **Greek only** — all passages are Classical Greek (Xenophon, Plato, Homer, etc.)
- **Alternating** — Classical Latin and Greek on alternate days
- **Mostly Latin / Mostly Greek** — weighted toward one language
- **Biblical Greek** — all passages are from the Greek Bible (Septuagint OT + Koine NT)
- **Alternate + Biblical (3-way)** — rotates Latin → Classical Greek → Biblical Greek day by day

**Biblical Greek** draws from the full Greek Bible — 7,000+ passages:

| Corpus | Books | Passages | Translation |
|--------|-------|----------|-------------|
| Septuagint (LXX) | 52 OT books | ~5,650 | Brenton (1851, public domain) |
| New Testament (SBLGNT) | 27 NT books | 1,395 | World English Bible (public domain) |

Every word is fully parsed and linked to the TFLSJ/Abbott-Smith lexicon and STEP Bible (LXX passages link to the LXX interlinear; NT passages link to the Textus Receptus interlinear).

Your language mix takes effect starting with the next day's passage.

### Assigned readings

If you're in an instructor's class, assigned passages appear above your daily reading at the top of the Today tab. Click **Read** to load the passage inline. The experience is identical to your daily reading — all words are clickable, the translation can be revealed, etc. Click **Mark as done** when finished; your instructor can see completion status.

Assignments from multiple classes all appear together, sorted by due date.

### Parse quota

Free accounts can parse **10 words per day** from the Analyze tab. Words you click in passages do not count against this quota — the quota only applies to manual queries in the Analyze tab. Students enrolled in an instructor's class get unlimited parses. Pro subscribers also get unlimited parses.

---

## Instructor Guide

### Setting up a class

1. Go to **Settings** and upgrade to the Instructor tier if you haven't already
2. The **Classes** tab appears in the nav bar
3. Click **New class** and give it a name
4. Click **Invite** and enter student email addresses one at a time

Students receive an invitation email. If they already have a ClassicsLens account, they're added immediately. If not, they'll be linked to your class automatically when they sign up — even if they sign up weeks later.

Students in your class get **Pro access** included: unlimited word parses and full SRS access.

### Inviting students

- Enter one email per invite
- Students who don't have accounts yet show as "Pending" until they sign up
- You can remove students at any time; they lose Pro access but keep their data
- **Student limit**: your account has a default cap of 30 active students across all classes. Contact the site admin if you need more.

### Assigning passages

From the **Classes** tab, open a class and click **Assign passage**. You can:

- Search the corpus by author, work, or keyword — browse 9,755 passages
- Assign with an optional due date and instructor instructions (shown to students below the passage header)
- Assign multiple passages; students see all pending assignments

Students see assignments sorted by due date. Completed assignments are marked with a checkmark and shown below pending ones.

### Uploading custom texts

If you want students to read a text not in the corpus (a handout, an unpublished papyrus, a textbook exercise), upload it via **My Texts** (link at the bottom of the Today page — see [My Texts](#my-texts-pro-instructor-academic) in the Student Guide above for the upload steps).

Once uploaded, a text appears in your My Texts list. To assign it to a class, open the class from the **Classes** tab and assign the text from there.

Custom texts work exactly like corpus passages: every word is clickable, word popups show full parse data, students can save words to their decks. The only difference is there's no pre-loaded translation — include a translation in your instructions if you want students to have one.

**Copyright note**: you are responsible for ensuring you have the right to share the text. Public-domain texts (anything published before 1928 in the US) are always safe. Your own compositions, or texts you hold the rights to, are also fine.

### Tracking student progress

The class **Dashboard** shows all assignments with a per-student completion grid: who has read what, and when. You can see:
- Total students enrolled vs. completed for each assignment
- Individual student timestamps
- Which assignments are overdue

The roster view shows overall stats per student: total passages read, SRS card count, streak.

### Previewing readings

Click the eye icon next to any assignment or text to see it exactly as a student would, in a standalone reader. An amber "Preview mode" banner confirms you're not in your own reading session.

---

## Admin Guide

The admin panel is accessible from **Settings** (visible only to `broadnax@gmail.com`). It has four tabs:

### Users

Shows all accounts with:
- Display name, email, auth provider (Google or email/password)
- Current tier (subscription tier + any tier override)
- Activity stats: day number, passages read, streak, card count, last active date

**Tier override**: buttons at the bottom of each user row let you force any tier (`free`, `pro`, `instructor`, `academic`) regardless of their Stripe subscription. Useful for beta access, comps, and the Playwright test account. Leave blank to rely on the Stripe subscription.

**Delete user**: permanently deletes the account and all data (cascades via FK constraints). Requires confirmation. Cannot delete your own account.

### Passages

Browse and search all 9,755 passages. Filter by language. Click any passage to see its full text and a "Preview as student" link.

### Promos

Create promo codes that grant recipients a free tier upgrade.

**Fields**:
- **Code** — the string users enter (auto-uppercased, e.g. `FRIEND2026`)
- **Tier** — `pro` or `academic`
- **Max uses** — how many times the code can be redeemed (default 1)
- **Expires** — optional expiry date

Codes can be deactivated at any time. Users who already redeemed keep their access.

To share: send the user to `classicslens.com` → Settings → Account → "Redeem promo code".

### Instructors

Shows all instructor and academic tier accounts with:
- Current student count vs. their limit
- Number of classes
- Visual usage bar (green → amber at 80% → red at limit)

**Editing a limit**: click "Edit limit" next to any instructor, type a new number, press Enter or Save. Takes effect immediately — the next invite attempt will check against the new limit.

The default limit for new instructor accounts is 30 active students. There's no limit on the number of classes, only on total active students across all classes.

---

## Common Questions

**Q: Why am I getting the same passage again?**
The passage schedule is based on your day counter, which advances when you click "Mark as done". If you haven't marked a passage done, you'll see it again the next day. Your day counter only moves forward — it won't skip passages.

**Q: Can I change today's passage?**
No. The passage is fixed per day per language. You can change your language mix in Settings, but the change takes effect starting the next day.

**Q: I clicked a word and nothing happened.**
Some punctuation tokens (periods, commas, brackets) aren't linked to lexicon entries. If a word-like token doesn't respond, it may be a numeral, proper noun, or form not in the database. Try the Analyze tab — it uses the Morpheus sidecar as a fallback and can handle more edge cases.

**Q: The parse result looks wrong.**
Classical parsers are imperfect. Morpheus was built for Classical Attic and Classical Latin — Medieval Latin, Koine Greek, and highly irregular forms may parse incorrectly or not at all. Use the Logeion or Perseus links in the popup for authoritative lookup.

**Q: My streak reset even though I read yesterday.**
Streaks are tracked by UTC date, not local time. If you're in a timezone significantly behind UTC, "yesterday" for you might be two days ago in UTC. This is a known limitation.

**Q: I'm an instructor — why can't I assign a passage?**
You must be on the Instructor tier (paid subscription or promo code). If you just subscribed via Stripe, wait a minute and refresh — the webhook can take 30–60 seconds to process. If it still doesn't work after 5 minutes, contact support.

**Q: A student says they can't see their assignment.**
Check:
1. Is the student in your class with status "Active" (not "Pending")?
2. Did they sign up with the exact email address you invited?
3. If they signed up with Google, their Google account email must match the invited address.

If the student signed up with a different email, you'll need to invite that email separately. Pending invites only auto-activate on sign-up, not retroactively.

**Q: Can students use ClassicsLens without being in a class?**
Yes. Free accounts can read daily passages, click words, and save 10 parses/day without any instructor involvement.

**Q: Where does the translation come from?**
All translations are public-domain English versions — Perseus Digital Library, Project Gutenberg, and similar sources. They're matched to passages by section reference. Not every translation is perfect; some are Victorian-era and stylistically dated, but they're accurate and freely redistributable.

**Q: How do I export my vocabulary to Anki?**
Go to **Settings → Account → Download Anki deck**. This downloads a `.txt` file. In Anki: File → Import, select the file, set the separator to Tab. Cards include: surface form, lemma, definition, morphology, and source passage.

**Q: Can I delete my account?**
Yes. **Settings → Account → Delete account**. This permanently deletes all your data including your SRS deck, progress, and settings. It cannot be undone.

---

## Troubleshooting

### "Parse quota exceeded"
You've hit the 10 parse/day limit on a free account. Quota resets at midnight UTC. Options:
- Wait until tomorrow
- Enroll in an instructor's class (grants unlimited parses)
- Upgrade to Pro

### Passage won't load
Usually a transient network error. Refresh the page. If it persists, check the browser console for a specific error. The most common cause is an expired session — try signing out and back in.

### Word popup shows "Not found in local lexicon"
The word isn't in the SQLite database. The popup shows fallback links to Logeion and Perseus. This happens most often with:
- Rare proper nouns (place names, personal names)
- Late Latin or Medieval forms
- Very rare inflected forms not in Morpheus
- Typos or OCR errors in the passage text

### Paradigm table shows "No paradigm data available"
The lemma isn't in the paradigms table. This affects:
- Indeclinable words (adverbs, prepositions, conjunctions)
- Very rare lemmas not in the seed data
- Some irregular forms

### Email password reset not arriving
Check your spam folder. Emails come from `noreply@classicslens.com` via Resend. If it's not there within 5 minutes, try again — reset tokens expire after 1 hour.

### Dark mode reverts after refresh
This should no longer happen — theme is stored server-side and synced on login. If it still reverts, sign out and back in once to force a sync.

### Instructor: student limit reached error
Your account has reached its student limit. Contact the site admin to increase your limit. In the meantime, you can remove inactive or dropped students to free up slots.