Update README and app_features to reflect current feature set

README: expanded from the original terse list into categorized sections
covering the six conjugation practice modes, textbook reader, AI chat
and stories, listening/pronunciation, cloze, lyrics, vocab SRS, offline
dictionary, grammar notes/exercises, and CloudKit sync. Architecture
section now documents the dual local/cloud SwiftData stores with the
App Group ID, the widget-schema-must-match requirement, and the
Scripts/textbook extraction pipeline.

app_features.md: added a full Conjuga section (practice modes, verb
reference, grammar, dictionary, sync, widgets, data counts) alongside
the existing ConjuGato and Conjuu ES analyses; added Conjuga as a
first column in the comparison table with rows for the new capability
axes (AI, textbook, speech, offline dictionary, lyrics, CloudKit,
widgets); added a "Conjuga excels at" strengths section.

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

README.md

@@ -1,32 +1,57 @@
 # Conjuga
 
-A Spanish verb conjugation learning app for iOS. Practice all 20 tenses with spaced repetition, handwriting recognition, and vocabulary courses.
+A Spanish-learning iOS app that combines verb conjugation practice, a full textbook reader, an AI conversation partner, offline dictionary lookups, grammar exercises, and more. Runs entirely on-device where possible (Foundation Models, Speech framework, Vision OCR).
 
 ## Features
 
-- **Conjugation Practice** — Flashcards, typing, multiple choice, handwriting, sentence building, and full table modes
-- **Spaced Repetition** — SM-2 algorithm tracks what you know and surfaces what you don't
-- **1,750 Verbs** — From basic to expert, with irregular form highlighting
-- **20 Tenses** — Every indicative, subjunctive, conditional, and imperative tense
-- **Grammar Guide** — 20 tense guides with conjugation tables + 20 grammar topic notes (Ser vs Estar, Por vs Para, etc.)
-- **Vocabulary Courses** — Weekly decks with example sentences
-- **Progress Tracking** — Streaks, daily goals, accuracy stats, and achievement badges
-- **CloudKit Sync** — Review progress syncs across devices
-- **Widgets** — Daily progress, word of the day, and weekly stats
-- **Text-to-Speech** — Hear any verb pronounced in Spanish
+### Verb practice
+- **Six conjugation modes** — flashcards, typing, multiple choice, handwriting (Apple Pencil / finger), sentence builder, and full-table (conjugate all persons at once)
+- **Focus modes** — weak verbs (SM-2 spaced repetition), irregularity drills (spelling / stem / unique), common tenses
+- **1,750 verbs** across 5 levels (Basic → Expert) with 209 K pre-conjugated forms and 23 K irregular-span annotations
+- **20 tenses** — every indicative, subjunctive, conditional, and imperative tense, each with character-level irregular highlighting
+- **Irregularity filter** — search the verb list by Any Irregular / Spelling Change / Stem Change / Unique Irregular, combinable with level filter
+- **Text-to-speech** on any form
+
+### Content & study
+- **Textbook reader** — 30 chapters of *Complete Spanish Step-by-Step* with 251 interactive exercises (keyboard + Apple Pencil), 931 OCR'd vocab tables rendered as Spanish→English grids (~3 100 paired cards extracted via bounding-box OCR)
+- **Course decks** — weekly vocab decks with example sentences, week tests, and cumulative checkpoint exams
+- **Stem-change toggle** on Week 4 flashcard decks (E-IE, E-I, O-UE, U-UE) showing inline present-tense conjugations
+- **Grammar guide** — 20 tense guides with usage rules and examples + 20+ grammar topic notes (ser/estar, por/para, preterite/imperfect, etc.), each with 100+ practice exercises
+- **Grammar exercises** — interactive quizzes for 5 core topics (ser/estar, por/para, preterite/imperfect, subjunctive, personal *a*)
+
+### AI & speech
+- **Conversational practice** — on-device AI chat partner (Apple Foundation Models) with 10 scenario types; chat bubbles have tappable words that open dictionary / on-demand AI lookup
+- **AI short stories** — generated stories with tappable words and comprehension quizzes
+- **Listening practice** — listen-and-type + pronunciation scoring via the Speech framework
+- **Pronunciation check** — word-by-word match scoring
+
+### Vocabulary & tools
+- **Offline dictionary** — reverse index of 175 K verb forms + 200 common words, cached to disk for instant lookups
+- **Vocab SRS review** — spaced repetition over course vocabulary with Again / Hard / Good / Easy rating
+- **Cloze practice** — fill-in-the-blank sentences with distractor generation
+- **Lyrics practice** — search, translate, and read Spanish song lyrics
+
+### Tracking & sync
+- **Progress** — streaks, daily goals, accuracy stats, achievement badges, study-time tracking per day
+- **CloudKit sync** — review progress, test results, saved stories, conversations, and textbook attempts sync across devices
+- **Widgets** — combined dashboard + word-of-the-day, refreshed daily and on backgrounding
 
 ## Architecture
 
 - **SwiftUI** + **SwiftData** with a dual-store configuration:
-  - **Local store** — Reference data (verbs, forms, guides) seeded from JSON on first launch
-  - **Cloud store** — User data (review cards, progress, streaks) synced via CloudKit
-- **SharedModels** package shared between the app and widget extension
+  - **Local store** (App Group `group.com.conjuga.app`) — reference data: verbs, forms, irregular spans, tense guides, course decks, vocab cards, textbook chapters. Seeded from bundled JSON on first launch. Self-healing re-seeds trigger on version bumps *or* if rows are missing on disk.
+  - **Cloud store** (CloudKit `iCloud.com.conjuga.app`, private database) — user data: review cards, course reviews, user progress, test results, daily logs, saved songs, stories, conversations, textbook exercise attempts.
+- **SharedModels** Swift Package shared between the app and widget extension. Widget schema must include every local-store entity or SwiftData destructively migrates the shared store.
+- **Foundation Models** for on-device AI generation (`@Generable` structs for typed output).
+- **Vision** framework for OCR of textbook pages and vocabulary images.
+- **Speech** framework for recognition and pronunciation scoring.
+- **Textbook extraction pipeline** (`Conjuga/Scripts/textbook/`) — XHTML and answer-key parsers, macOS Vision image OCR + PDF page OCR, bounding-box vocab pair extractor, NSSpellChecker-based validator, and language-aware auto-fixer.
 
 ## Requirements
 
-- iOS 18+
+- iOS 18+ (iOS 26 for Foundation Models features)
 - Xcode 16+
 
 ## Building
 
-Open `Conjuga/Conjuga.xcodeproj` in Xcode and run on a simulator or device. Data seeds automatically on first launch.
+Open `Conjuga/Conjuga.xcodeproj` in Xcode and run on a simulator or device. Reference data seeds automatically on first launch. To regenerate textbook content, run `Conjuga/Scripts/textbook/run_pipeline.sh` locally — the generated `textbook_data.json` / `textbook_vocab.json` are committed so fresh clones build without the pipeline.

app_features.md

@@ -1,6 +1,85 @@
 # Spanish Conjugation Apps — Feature Comparison
 
-Side-by-side feature analysis of **ConjuGato** and **Conjuu ES**, based on App Store screenshots and extracted app data.
+Side-by-side feature analysis of **Conjuga** (this project), **ConjuGato**, and **Conjuu ES**, based on App Store screenshots, extracted app data, and this repository's source.
+
+---
+
+## Conjuga (this project)
+
+**Platform:** iOS 18+ (iOS 26 required for Foundation Models features)
+**Monetization:** —
+**Tech stack:** SwiftUI + SwiftData (dual local / CloudKit stores), SharedModels Swift Package, Foundation Models, Vision, Speech, WidgetKit
+
+### Practice Modes
+
+- **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
+- **Listening practice** — listen-and-type + pronunciation scoring via Speech framework, word-by-word match
+- **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
+
+### Verb Reference
+
+- **1,750 verbs**, 5 levels (Basic / Elementary / Intermediate / Advanced / Expert), 209 K pre-conjugated forms
+- **20 tenses** with character-level irregular-span highlighting (spelling / stem / unique)
+- **Irregularity filter** — All / Any Irregular / Spelling Change / Stem Change / Unique Irregular — combinable with level
+- **Per-verb detail** with per-form English translations and tense-grouped table
+- **Text-to-speech** on any conjugated form
+
+### Grammar & Content
+
+- **20 tense guides** with usage rules and examples
+- **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
+- **Grammar exercises** — interactive quizzes for 5 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
+- **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 extraction pipeline** — XHTML + answer-key parsers, macOS Vision image OCR, PDF page OCR, bounding-box vocab pair extractor, NSSpellChecker validator, language-aware auto-fixer
+
+### Offline Dictionary
+
+- **Reverse index of 175 K verb forms + 200 common words**, cached to disk
+- **Tappable-word lookup** in chat bubbles and stories; falls back to Foundation Models `@Generable ChatWordInfo` when a word isn't in the dictionary
+
+### Progress & Sync
+
+- **SM-2 spaced repetition** for verb review
+- **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
+- **Background app refresh** for widget data
+
+### Widgets
+
+- **Combined dashboard** (word of day + stats)
+- **Word-of-day** standalone
+- Both refresh daily and on app backgrounding
+
+### Settings & Filters
+
+- **Selectable verb level** and **enabled tenses**
+- **Include vosotros** toggle
+- **Auto-fill verb stem** toggle for Full Table practice
+- **Feature reference** page in Settings documenting every feature and which settings affect it
+
+### Data (in repo)
+
+| Asset | Count |
+|-------|-------|
+| Verbs | 1,750 |
+| Verb forms (pre-conjugated) | 209,014 |
+| Irregular span annotations | 23,795 |
+| Tenses | 20 |
+| Tense guides | 20 |
+| Grammar notes | 20+ (each with 100+ exercises) |
+| Textbook chapters | 30 |
+| Textbook exercises | 251 |
+| Textbook vocab pairs | ~3,118 |
+| Offline dictionary forms | 175,425 |
 
 ---
 
@@ -184,30 +263,44 @@ Side-by-side feature analysis of **ConjuGato** and **Conjuu ES**, based on App S
 
 ## Feature Comparison
 
-| Feature | ConjuGato | Conjuu ES |
-|---------|-----------|-----------|
-| **Verb count** | 1,750 | 621 |
-| **Tenses** | 27 | 20 |
-| **Practice style** | Flashcard (tap to reveal) | Typing (fill in forms) |
-| **Input method** | Self-rate (no typing) | Type conjugation |
-| **Daily goals** | Numeric counter (25/100) | 4 presets (Casual→Committed) |
-| **Spaced repetition** | Yes (star + heart ratings) | Session-based review |
-| **Rhyming mnemonics** | Yes (dedicated tab) | Not visible |
-| **Grammar breakdown** | Color-coded span highlighting | Ending table + usage rules |
-| **Irregularity detail** | 3-level (spelling/stem/unique) with character spans | 4-label (ordinary/irregular/regular/orto) |
-| **Tense explanations** | In-app guides with mnemonics | Modal popups with usage categories |
-| **Example sentences** | Per-tense with audio | Per-tense in guide popups |
-| **Audio** | Tap any conjugation + auto-pronounce | Not prominent |
-| **Difficulty levels** | Filter by irregularity type | 8 graded word lists |
-| **Custom lists** | No | Yes (My Lists + Pinboard) |
-| **Verb filters** | Ending type + irregularity + tense | Tense checkboxes + level |
-| **Translations** | 8 languages | 4 languages |
-| **Platform** | iOS (Catalyst) | macOS + iOS |
-| **Monetization** | One-time purchase | Free tier + paid |
-| **vosotros toggle** | Yes | Not visible |
+| Feature | Conjuga | ConjuGato | Conjuu ES |
+|---------|---------|-----------|-----------|
+| **Verb count** | 1,750 | 1,750 | 621 |
+| **Tenses** | 20 | 27 | 20 |
+| **Practice style** | Flashcards, typing, MC, handwriting, sentence builder, full table | Flashcard (tap to reveal) | Typing (fill in forms) |
+| **Input method** | All four (type / tap / write / speak) | Self-rate (no typing) | Type conjugation |
+| **Daily goals** | Numeric counter + streaks + study-time | Numeric counter (25/100) | 4 presets (Casual→Committed) |
+| **Spaced repetition** | SM-2 (verb forms + vocab cards) | Yes (star + heart ratings) | Session-based review |
+| **Grammar breakdown** | Character-level irregular span highlighting | Color-coded span highlighting | Ending table + usage rules |
+| **Irregularity detail** | 3-level (spelling/stem/unique) + per-verb badges + filter | 3-level with character spans | 4-label (ordinary/irregular/regular/orto) |
+| **Tense explanations** | 20 guides + 20 grammar notes with 100+ exercises each | In-app guides with mnemonics | Modal popups with usage categories |
+| **Example sentences** | Per-tense + per-card + per-story + in textbook | Per-tense with audio | Per-tense in guide popups |
+| **Audio** | TTS on any form + pronunciation scoring | Tap any conjugation + auto-pronounce | Not prominent |
+| **Difficulty levels** | 5 levels + irregularity filter (combinable) | Filter by irregularity type | 8 graded word lists |
+| **Custom lists** | — | No | Yes (My Lists + Pinboard) |
+| **Verb filters** | Level + irregularity category + tense selection + search | Ending type + irregularity + tense | Tense checkboxes + level |
+| **AI features** | On-device chat, stories, word lookups (Foundation Models) | — | — |
+| **Textbook** | 30 chapters, 251 exercises, ~3,100 vocab pairs (OCR pipeline) | — | — |
+| **Listening / speech** | Listen-and-type + pronunciation scoring | — | — |
+| **Offline dictionary** | 175 K forms | — | — |
+| **Lyrics** | Search + translate | — | — |
+| **CloudKit sync** | Yes (private database) | — | — |
+| **Widgets** | Combined + word-of-day | — | — |
+| **Platform** | iOS 18+ (iOS 26 for AI) | iOS (Catalyst) | macOS + iOS |
+| **Monetization** | — | One-time purchase | Free tier + paid |
+| **vosotros toggle** | Yes | Yes | Not visible |
 
 ## Unique Strengths
 
+### Conjuga excels at:
+- **Breadth of modes** — six conjugation practice styles plus cloze, listening, lyrics, chat, stories, textbook, and vocab review in one app
+- **AI integration** — on-device Foundation Models power the chat partner, story generator, and dictionary fallback lookup with no cloud round-trips
+- **Textbook reader** — full *Complete Spanish Step-by-Step* textbook with 251 interactive exercises and 3,100 OCR-paired vocab cards, built via an in-repo extraction pipeline
+- **Combinable filters** — Level × Irregularity × search on the verb list, with per-row category badges
+- **Multi-input practice** — type, tap, Apple Pencil handwriting, and voice (pronunciation scoring)
+- **Offline dictionary** — 175 K verb-form reverse index makes word lookups instant and network-free
+- **CloudKit sync** — progress, tests, saved content, and conversations travel between devices
+
 ### ConjuGato excels at:
 - **Breadth** — nearly 3× the verbs
 - **Irregularity teaching** — character-level color-coded highlighting showing exactly *why* each form is irregular