Docs — refresh feature reference + app_features for this session's work

Both the in-app Feature Reference and app_features.md were last updated
2026-04-21, before Books, the verb-table vocab SRS, Extra Study,
read-along, the guide enrichment, and the Practice-tab restructure.

FeatureReferenceView (Settings → How Features Work):
  - Regrouped to match the live Practice tab: Conjugation / Vocabulary
    / Reading sections.
  - Added Vocab Flashcards (Quiz + Learn modes, in-session learning
    queue), Vocab Multiple Choice, Books + read-aloud, Extra Study,
    and Guide cross-links.
  - Tense/grammar counts corrected (36 grammar notes, enriched guides).
  - "Settings That Affect Practice" now lists Cards per session and
    notes the Verbs-tab ↔ Level sync.

app_features.md (Conjuga section of the comparison doc):
  - Practice modes split into Conjugation / Vocabulary / Reading.
  - Documented the two-layer vocab SRS, Books + books pipeline,
    Extra Study, guide enrichment + cross-links, configurable session
    size, and the VerbReviewCard cloud model.
  - Data table updated (36 grammar notes, bundled books row).

Docs only — no behavior change.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Conjuga/Conjuga/Views/Settings/FeatureReferenceView.swift

@@ -3,15 +3,17 @@ import SwiftUI
 struct FeatureReferenceView: View {
     var body: some View {
         List {
-            Section("Verb Conjugation Practice") {
+            // MARK: Conjugation
+
+            Section("Practice — Conjugation") {
                 featureRow(
                     icon: "rectangle.stack", color: .blue,
                     title: "Flashcard / Typing / MC / Handwriting / Sentence Builder",
                     details: [
-                        "Pulls from verb conjugation database (1,750 verbs)",
+                        "Pulls from the verb conjugation database (1,750 verbs)",
                         "Filtered by your Level setting",
                         "Filtered by your Enabled Tenses",
-                        "Respects Include Vosotros setting",
+                        "Respects the Include Vosotros setting",
                         "Due cards (SRS) shown first, then random",
                     ]
                 )
@@ -25,9 +27,7 @@ struct FeatureReferenceView: View {
                         "Random tense from your Enabled Tenses",
                     ]
                 )
-            }
 
-            Section("Quick Actions") {
                 featureRow(
                     icon: "star.fill", color: .orange,
                     title: "Common Tenses",
@@ -57,20 +57,86 @@ struct FeatureReferenceView: View {
                         "Filtered by your Level and Enabled Tenses",
                     ]
                 )
+            }
+
+            // MARK: Vocabulary
+
+            Section("Practice — Vocabulary") {
+                featureRow(
+                    icon: "rectangle.on.rectangle.angled", color: .purple,
+                    title: "Vocab Flashcards",
+                    details: [
+                        "English meaning → recall the Spanish verb",
+                        "Pool = verbs at your enabled Levels (the same Level set the Verbs tab filters by)",
+                        "Session size set by Settings → Cards per session",
+                        "Overdue verbs pulled first, then new verbs by frequency",
+                        "Quiz mode: tap to reveal, rate Again/Hard/Good/Easy. Again/Hard requeue the card a few cards later; a second Good or an Easy graduates it. Graduation updates the long-term SRS schedule.",
+                        "Learn mode (toolbar toggle): both sides shown at once, Next/Previous to browse, loops — no rating, no pressure",
+                        "Example sentence generated on-device; speaker button reads the verb aloud",
+                    ]
+                )
+
+                featureRow(
+                    icon: "checklist", color: .purple,
+                    title: "Vocab Multiple Choice",
+                    details: [
+                        "English meaning → pick the Spanish verb from 4 options",
+                        "Distractors prefer the same part of speech",
+                        "Same level-filtered pool and SRS session queue as Vocab Flashcards",
+                    ]
+                )
 
                 featureRow(
                     icon: "rectangle.stack.fill", color: .teal,
                     title: "Vocab Review",
                     details: [
-                        "Reviews vocabulary cards that are due (SRS scheduled)",
+                        "Reviews course/textbook vocabulary cards that are due (SRS scheduled)",
                         "Cards become due after you study them in Course quizzes",
-                        "Rate Again/Hard/Good/Easy to schedule next review",
+                        "Rate Again/Hard/Good/Easy to schedule the next review",
-                        "Uses all course vocabulary, not filtered by level",
+                        "Distinct from Vocab Flashcards — this is course vocab, not the verb table",
                     ]
                 )
             }
 
-            Section("Practice Activities") {
+            // MARK: Reading
+
+            Section("Practice — Reading") {
+                featureRow(
+                    icon: "book.fill", color: .teal,
+                    title: "Stories",
+                    details: [
+                        "AI-generated one-paragraph Spanish stories",
+                        "Matched to your Level and Enabled Tenses",
+                        "Every word is tappable for a definition",
+                        "English translation hidden by default (toggle to reveal)",
+                        "3-question comprehension quiz at the end",
+                        "Requires an Apple Intelligence-capable device",
+                    ]
+                )
+
+                featureRow(
+                    icon: "books.vertical.fill", color: .indigo,
+                    title: "Books",
+                    details: [
+                        "Full-length bilingual books bundled with the app",
+                        "Chapter list; read a chapter paragraph by paragraph",
+                        "Tap any word for a definition (offline dictionary, on-device AI fallback)",
+                        "Toggle between Spanish and pre-translated English",
+                        "Read-aloud: a voice reads the chapter with the current word highlighted; tap a word to pause and look it up",
+                        "Voice and speed picker in the read-aloud controls",
+                    ]
+                )
+
+                featureRow(
+                    icon: "music.note.list", color: .pink,
+                    title: "Lyrics",
+                    details: [
+                        "Search and save Spanish song lyrics",
+                        "Side-by-side Spanish and English",
+                        "Long-press a word for a definition",
+                    ]
+                )
+
                 featureRow(
                     icon: "bubble.left.and.bubble.right.fill", color: .green,
                     title: "Conversation",
@@ -79,8 +145,7 @@ struct FeatureReferenceView: View {
                         "10 scenario types (restaurant, directions, etc.)",
                         "AI adapts vocabulary to your Level setting",
                         "Corrections provided inline when you make mistakes",
-                        "Conversations saved to iCloud for revisiting",
+                        "Requires an Apple Intelligence-capable device",
-                        "Requires Apple Intelligence-capable device",
                     ]
                 )
 
@@ -91,8 +156,6 @@ struct FeatureReferenceView: View {
                         "Listen & Type: hear a sentence, type what you heard",
                         "Pronunciation: read a sentence aloud, get scored on accuracy",
                         "Sentences pulled from course vocabulary examples",
-                        "Uses all course vocab (not filtered by level)",
-                        "Pronunciation requires microphone permission",
                     ]
                 )
 
@@ -101,50 +164,23 @@ struct FeatureReferenceView: View {
                     title: "Cloze Practice",
                     details: [
                         "Fill in the missing word in a Spanish sentence",
-                        "Sentences from course vocabulary examples",
                         "4 multiple-choice options (1 correct + 3 distractors)",
-                        "Distractors are other vocabulary words from same pool",
+                        "Sentences from course vocabulary examples",
-                        "Uses all course vocab (not filtered by level)",
-                    ]
-                )
-
-                featureRow(
-                    icon: "music.note.list", color: .pink,
-                    title: "Lyrics",
-                    details: [
-                        "Search and save Spanish song lyrics",
-                        "Side-by-side Spanish and English translations",
-                        "User-curated library, not filtered by level",
-                        "Saved to iCloud for sync across devices",
-                    ]
-                )
-
-                featureRow(
-                    icon: "book.fill", color: .teal,
-                    title: "Stories",
-                    details: [
-                        "AI-generated one-paragraph Spanish stories",
-                        "Matched to your Level and Enabled Tenses",
-                        "Every word is tappable for definition",
-                        "Known words use offline dictionary (175K+ verb forms)",
-                        "Unknown words looked up via on-device AI",
-                        "English translation hidden by default (toggle to reveal)",
-                        "3-question comprehension quiz at the end",
-                        "Saved to iCloud for revisiting",
-                        "Requires Apple Intelligence-capable device",
                     ]
                 )
             }
 
+            // MARK: Guide
+
             Section("Guide") {
                 featureRow(
                     icon: "book", color: .brown,
                     title: "Tense Guides",
                     details: [
-                        "Detailed explanation of each of the 20 verb tenses",
+                        "In-depth guide to each of the 20 verb tenses",
-                        "Conjugation ending tables for -ar, -er, -ir verbs",
+                        "Conjugation ending tables, common irregulars, mnemonics",
-                        "Usage patterns with example sentences",
+                        "Usage patterns, pitfalls, and contrast with neighbouring tenses",
-                        "Essential tenses marked with orange badge",
+                        "Essential tenses marked with an orange badge",
                     ]
                 )
 
@@ -152,14 +188,24 @@ struct FeatureReferenceView: View {
                     icon: "doc.text", color: .brown,
                     title: "Grammar Notes",
                     details: [
-                        "23 grammar topics (ser vs estar, por vs para, etc.)",
+                        "36 grammar topics (ser vs estar, por vs para, WEIRDO, etc.)",
-                        "Interactive exercises available for 5 topics",
+                        "Each with a mnemonic, contrast examples, and common pitfalls",
-                        "Tap 'Practice This' on notes that have exercises",
+                        "Interactive exercises available on selected topics",
-                        "Content grouped by category with card-based layout",
+                    ]
+                )
+
+                featureRow(
+                    icon: "arrow.triangle.branch", color: .indigo,
+                    title: "Cross-links",
+                    details: [
+                        "Tense guides show \"Related grammar\" chips that jump to the matching grammar note",
+                        "Grammar notes show \"Used in tenses\" chips that jump back",
                     ]
                 )
             }
 
+            // MARK: Course
+
             Section("Course") {
                 featureRow(
                     icon: "list.clipboard", color: .orange,
@@ -167,11 +213,21 @@ struct FeatureReferenceView: View {
                     details: [
                         "Vocabulary from specific course weeks",
                         "Multiple quiz types: MC, typing, handwriting, cloze",
-                        "Focus Area mode for missed words",
                         "Not filtered by Level (uses course structure)",
                     ]
                 )
 
+                featureRow(
+                    icon: "star.circle.fill", color: .yellow,
+                    title: "Extra Study",
+                    details: [
+                        "Star a card during a course flashcard session to mark it for extra study",
+                        "Each week shows an \"Extra Study\" row when it has starred cards",
+                        "Launches a session of just the starred cards for that week",
+                        "Marks are iCloud-synced across devices",
+                    ]
+                )
+
                 featureRow(
                     icon: "checkmark.seal", color: .orange,
                     title: "Checkpoint Exams",
@@ -183,23 +239,27 @@ struct FeatureReferenceView: View {
                 )
             }
 
+            // MARK: Dashboard
+
             Section("Dashboard") {
                 featureRow(
                     icon: "clock.fill", color: .mint,
                     title: "Study Time",
                     details: [
                         "Tracks time the app is in the foreground",
-                        "Starts when app becomes active, stops on background",
+                        "Shows today's time and an all-time total",
-                        "Shows today's time and all-time total",
                         "7-day bar chart of daily study time",
                     ]
                 )
             }
 
+            // MARK: Settings
+
             Section("Settings That Affect Practice") {
-                settingRow(name: "Level", affects: "Verb practice, Quick Actions, Stories, Conversation (Full Table ignores level)")
+                settingRow(name: "Level", affects: "Conjugation practice, Vocab Flashcards & Multiple Choice, Stories, Conversation. Shared with the Verbs tab filter. Full Table ignores level.")
-                settingRow(name: "Enabled Tenses", affects: "Verb practice, Full Table, Irregularity Drills, Stories")
+                settingRow(name: "Enabled Tenses", affects: "Conjugation practice, Full Table, Irregularity Drills, Stories")
-                settingRow(name: "Include Vosotros", affects: "Verb practice, Full Table, Quick Actions")
+                settingRow(name: "Include Vosotros", affects: "Conjugation practice, Full Table, Common Tenses")
+                settingRow(name: "Cards per session", affects: "How many verbs a Vocab Flashcards / Multiple Choice session draws")
                 settingRow(name: "Daily Goal", affects: "Dashboard progress tracking only")
             }
         }

app_features.md

@@ -10,17 +10,30 @@ Side-by-side feature analysis of **Conjuga** (this project), **ConjuGato**, and
 **Monetization:** —
 **Tech stack:** SwiftUI + SwiftData (dual local / CloudKit stores), SharedModels Swift Package, Foundation Models, Vision, Speech, WidgetKit
 
-### Practice Modes
+The Practice tab is organised into three sections — **Conjugation**, **Vocabulary**, and **Reading**.
+
+### Practice — Conjugation
 
 - **Six core conjugation modes** — flashcards, typing, multiple choice, handwriting (Apple Pencil + finger), sentence builder, full table (all persons at once)
 - **Focus modes** — weak verbs (SM-2 SRS), irregularity drills (spelling / stem / unique, selectable), common tenses
 - **Quick answer review** with per-form irregular-span highlighting
-- **Vocab SRS Review** — spaced repetition over course vocabulary with Again / Hard / Good / Easy rating
+
-- **Cloze practice** — fill-in-the-blank with distractor generation from vocab pool
+### Practice — Vocabulary
-- **Listening practice** — listen-and-type + pronunciation scoring via Speech framework, word-by-word match
+
+- **Vocab Flashcards** — English → Spanish verb recall over the verb table, filtered by enabled Levels (shared with the Verbs-tab filter). Two-layer SRS: a position-based in-session learning queue (Again/Hard requeue 5–10 cards later, Good moves ~20 ahead, a second Good or Easy graduates) on top of the long-term SM-2 schedule. Due-first session ordering, session size configurable in Settings.
+  - **Quiz mode** — tap-to-reveal + Again/Hard/Good/Easy rating
+  - **Learn mode** — both sides shown at once, Next/Previous browsing on a loop, no rating
+- **Vocab Multiple Choice** — same pool/SRS; pick the Spanish verb from 4 options, distractors prefer matching part of speech
+- **Vocab SRS Review** — spaced repetition over *course* vocabulary (distinct from the verb-table flashcards) with Again / Hard / Good / Easy rating
+
+### Practice — Reading
+
+- **AI short stories** — generated stories with tappable words + comprehension quiz
+- **Books** — full-length bilingual EPUB-imported books; chapter reader with tap-to-define, Spanish/English toggle, and read-aloud (TTS with active-word highlighting, tap-to-pause-and-define, voice + speed picker)
 - **Lyrics practice** — search Spanish songs, translate line by line
 - **Conversational practice** — on-device AI chat partner (Apple Foundation Models) with 10 scenarios, tappable words that open dictionary or on-demand AI lookup
-- **AI short stories** — generated stories with tappable words + comprehension quiz
+- **Listening practice** — listen-and-type + pronunciation scoring via Speech framework, word-by-word match
+- **Cloze practice** — fill-in-the-blank with distractor generation from vocab pool
 
 ### Verb Reference
 
@@ -32,13 +45,15 @@ Side-by-side feature analysis of **Conjuga** (this project), **ConjuGato**, and
 
 ### Grammar & Content
 
-- **20 tense guides** with usage rules and examples
+- **20 tense guides** — teacher-handout depth: usage cases, conjugation tables, common irregulars, mnemonics (WEIRDO, ESCAPA, etc.), pitfalls, and contrast with neighbouring tenses
-- **20+ grammar topic notes** (ser/estar, por/para, preterite/imperfect, subjunctive, personal *a*, suffixes, irregular yo forms, stem-changers, etc.) each with 100+ practice exercises
+- **36 grammar topic notes** (ser/estar, por/para, preterite/imperfect, subjunctive triggers, personal *a*, suffixes, irregular yo forms, stem-changers, etc.) — each with a mnemonic, contrast examples, and a common-pitfalls section
-- **Grammar exercises** — interactive quizzes for 5 core topics
+- **Guide cross-links** — tense guides and grammar notes link bidirectionally ("Related grammar" / "Used in tenses" chips)
+- **Grammar exercises** — interactive quizzes for core topics
 - **Course decks** — weekly vocabulary with example sentences, week tests, cumulative checkpoint exams
-- **Stem-change toggle** on Week 4 decks (E-IE, E-I, O-UE, U-UE) with inline present-tense conjugations
+- **Extra Study** — star cards during course flashcard review; each week surfaces an "Extra Study" row to drill just the starred cards (iCloud-synced)
-- **Textbook reader** — 30 chapters of *Complete Spanish Step-by-Step* with 251 interactive exercises (keyboard + Apple Pencil), 931 OCR'd vocab tables rendered as paired Spanish→English grids (~3 100 cards)
+- **Textbook reader** — 30 chapters of *Complete Spanish Step-by-Step* with 251 interactive exercises (keyboard + Apple Pencil), vocab tables rendered as paired Spanish→English grids
-- **Textbook extraction pipeline** — XHTML + answer-key parsers, macOS Vision image OCR, PDF page OCR, bounding-box vocab pair extractor, NSSpellChecker validator, language-aware auto-fixer
+- **Textbook extraction pipeline** — XHTML + answer-key parsers, macOS Vision image OCR, PDF page OCR, LLM-vision vocab-pair pass, NSSpellChecker validator, language-aware auto-fixer
+- **Books pipeline** (`Scripts/books/`) — EPUB → chapter JSON extractor, Claude-subagent translation pass, bundler
 
 ### Offline Dictionary
 
@@ -47,10 +62,11 @@ Side-by-side feature analysis of **Conjuga** (this project), **ConjuGato**, and
 
 ### Progress & Sync
 
-- **SM-2 spaced repetition** for verb review
+- **SM-2 spaced repetition** for conjugation review, course vocab, and verb-table vocab (separate `VerbReviewCard` schedule)
+- **In-session learning queue** for vocab practice — position-based requeue layered on top of the SM-2 schedule
 - **Streaks, daily goals, accuracy stats, achievement badges**
 - **Study-time tracking** per day (foreground time)
-- **CloudKit private-database sync** — review cards, user progress, test results, daily logs, saved songs, stories, conversations, textbook exercise attempts
+- **CloudKit private-database sync** — review cards, verb review cards, user progress, test results, daily logs, saved songs, stories, conversations, textbook exercise attempts, extra-study marks
 - **Background app refresh** for widget data
 
 ### Widgets
@@ -61,9 +77,10 @@ Side-by-side feature analysis of **Conjuga** (this project), **ConjuGato**, and
 
 ### Settings & Filters
 
-- **Selectable verb level** and **enabled tenses**
+- **Selectable verb level** (shared between Settings and the Verbs-tab filter) and **enabled tenses**
 - **Include vosotros** toggle
 - **Auto-fill verb stem** toggle for Full Table practice
+- **Cards per session** — vocab flashcard / multiple-choice session size (10–50 or All)
 - **Feature reference** page in Settings documenting every feature and which settings affect it
 
 ### Data (in repo)
@@ -74,12 +91,12 @@ Side-by-side feature analysis of **Conjuga** (this project), **ConjuGato**, and
 | Verb forms (pre-conjugated) | 209,014 |
 | Irregular span annotations | 23,795 |
 | Tenses | 20 |
-| Tense guides | 20 |
+| Tense guides | 20 (enriched to teacher-handout depth) |
-| Grammar notes | 20+ (each with 100+ exercises) |
+| Grammar notes | 36 |
 | Textbook chapters | 30 |
 | Textbook exercises | 251 |
-| Textbook vocab pairs | ~3,118 |
 | Offline dictionary forms | 175,425 |
+| Bundled books | 1 (Olly Richards — *Spanish Short Stories Vol 2*, 13 chapters) |
 
 ---