Add comprehensive codebase documentation

Generate structured documentation in .agents/summary/ with architecture,
components, interfaces, data models, workflows, and dependencies.
Update AGENTS.md with consolidated project context for AI assistants.

Author: nacho

.agents/summary/architecture.md

@@ -0,0 +1,143 @@
+# Architecture
+<!-- metadata: type=architecture, audience=ai-agents, scope=system-design -->
+
+## Overview
+
+Mecalin follows the standard GNOME application architecture using GTK4 with the Adwaita design system. It uses the GTK subclassing pattern where each UI component is a GObject subclass with a corresponding XML composite template.
+
+## High-Level Architecture
+
+```mermaid
+graph TB
+    subgraph Entry["Application Entry"]
+        main["main.rs"]
+        app["MecalinApplication"]
+    end
+
+    subgraph Navigation["Navigation Layer"]
+        window["MecalinWindow<br/>(NavigationView hub)"]
+    end
+
+    subgraph Views["Feature Views"]
+        lesson["LessonView<br/>(Structured lessons)"]
+        speed["SpeedTestView<br/>(Timed typing tests)"]
+        falling["FallingKeysGame<br/>(Falling keys game)"]
+        scrolling["ScrollingLanesGame<br/>(Scrolling lanes game)"]
+        prefs["PreferencesView"]
+        about["AboutView"]
+        completion["CourseCompletionView"]
+    end
+
+    subgraph Widgets["Reusable Widgets"]
+        typing["TypingRow<br/>(Text input)"]
+        keyboard["KeyboardWidget<br/>(Visual keyboard)"]
+        hand["HandWidget<br/>(Hand position guide)"]
+        stv["SpeedTestTextView<br/>(Rich text display)"]
+        results["SpeedTestResultsView"]
+    end
+
+    subgraph Data["Data & Utilities"]
+        course["Course / Lesson / LessonStep"]
+        textgen["text_generation<br/>(Random text)"]
+        textutil["text_utils<br/>(Validation, WPM)"]
+        testutil["typing_test_utils<br/>(Test config/summary)"]
+        utils["utils<br/>(Locale, decomposition)"]
+    end
+
+    subgraph Resources["Embedded Resources"]
+        ui["11 XML UI templates"]
+        css["style.css"]
+        lessons["7 lesson JSON files"]
+        layouts["7 keyboard layout JSONs"]
+        words["40+ word list files"]
+        icons["SVG icons"]
+    end
+
+    main --> app
+    app --> window
+    window --> lesson & speed & falling & scrolling & prefs & about
+    lesson --> typing & keyboard & hand & completion
+    lesson --> course
+    speed --> stv & results
+    falling --> keyboard
+    scrolling --> keyboard
+    stv --> textutil
+    speed --> testutil
+    textgen --> words
+    course --> lessons
+    keyboard --> layouts
+    typing --> textutil
+    utils --> course & keyboard & lesson
+```
+
+## Design Patterns
+
+### GTK4 Subclassing Pattern
+
+Every UI component follows this structure:
+
+```mermaid
+classDiagram
+    class Component {
+        +mod imp (private implementation)
+        +glib::wrapper! macro
+        +public API methods
+    }
+    class imp_Module {
+        +struct ComponentName (fields)
+        +ObjectSubclass impl
+        +ObjectImpl::constructed()
+        +WidgetImpl overrides
+        +CompositeTemplate derive
+    }
+    class XML_Template {
+        +Widget hierarchy
+        +template_child bindings
+        +Signal connections
+    }
+    Component --> imp_Module : contains
+    imp_Module --> XML_Template : loads via GResource
+```
+
+Each component:
+1. Defines a private `imp` module with the actual struct and trait implementations
+2. Uses `#[derive(gtk::CompositeTemplate)]` to bind to an XML UI template
+3. Exposes a public wrapper type via `glib::wrapper!`
+4. Initializes in `ObjectImpl::constructed()` — setting up signals, loading data, binding settings
+
+### Navigation Architecture
+
+`MecalinWindow` uses `adw::NavigationView` as a stack-based navigation hub. Each feature is an `adw::NavigationPage` pushed by tag:
+
+```mermaid
+graph LR
+    Home["Home Menu"] -->|"push by tag"| lessons["lessons"]
+    Home -->|"push by tag"| speed_test["speed_test"]
+    Home -->|"push by tag"| game["game (Falling Keys)"]
+    Home -->|"push by tag"| lanes_game["lanes_game"]
+    Home -->|"push by tag"| preferences["preferences"]
+    Home -->|"push by tag"| about["about"]
+```
+
+### State Management
+
+- **GSettings** (`io.github.nacho.mecalin`): Persists user preferences (current lesson/step, widget visibility, finger colors, test duration)
+- **Window state** (`io.github.nacho.mecalin.state.window`): Persists window size and maximized state
+- **In-memory state**: Component-local `Cell`/`RefCell` fields in `imp` structs
+
+### Resource Embedding
+
+All UI templates, CSS, and icons are compiled into the binary via GResource (`resources.gresource.xml`). Lesson data, keyboard layouts, and word lists are embedded via `include_str!` and `include_dir!` macros at compile time.
+
+### Build-Time Code Generation
+
+`build.rs` performs two tasks:
+1. **Config generation**: Processes `src/config.rs.in` template, replacing `@VARIABLE@` placeholders with environment variables (VERSION, APPLICATION_ID, GETTEXT_PACKAGE, DATADIR)
+2. **Resource compilation**: Compiles `resources.gresource.xml` into a binary resource bundle
+
+### Internationalization
+
+- UI strings: gettext via `gettext-rs` and `i18n-format` crates
+- Lesson content: Separate JSON files per language, selected by locale detection (`utils::language_from_locale()`)
+- Keyboard layouts: Separate JSON files per language
+- Word lists: Separate text files per language, embedded at compile time

.agents/summary/codebase_info.md

@@ -0,0 +1,50 @@
+# Codebase Information
+<!-- metadata: type=overview, audience=ai-agents, scope=project-wide -->
+
+## Project Identity
+
+- **Name**: Mecalin
+- **Application ID**: `io.github.nacho.mecalin`
+- **Version**: 1.0.2
+- **License**: GPL-3.0-or-later
+- **Category**: Education (Typing Tutor)
+- **Distribution**: [Flathub](https://flathub.org/apps/io.github.nacho.mecalin)
+- **Heritage**: Based on [Mecawin](https://archive.org/details/mecawin), a classic Windows typing tutor
+
+## Technology Stack
+
+| Layer | Technology | Version Requirement |
+|-------|-----------|-------------------|
+| Language | Rust | Edition 2024 |
+| UI Framework | GTK4 | ≥ 4.14 (Cargo), ≥ 4.10 (Meson) |
+| Design System | libadwaita | ≥ 1.5 |
+| Build (dev) | Cargo | stable toolchain |
+| Build (prod) | Meson | ≥ 0.59.0 |
+| Packaging | Flatpak | GNOME Platform 46 |
+| i18n | gettext | via `gettext-rs` crate |
+| CI | GitHub Actions | ubuntu-latest |
+
+## Language Breakdown
+
+| Language | Files | Purpose |
+|----------|-------|---------|
+| Rust | 20 `.rs` files | Application logic |
+| XML | 11 `.ui` files | GTK Builder UI templates |
+| JSON | 7 lesson + 7 keyboard layout files | Localized content |
+| Text | 40+ `.txt` files | Word lists for text generation |
+| CSS | 1 `style.css` | Custom styling |
+| XML | 1 `.gresource.xml` | Resource manifest |
+| XML | 1 `.gschema.xml` | GSettings schema |
+| YAML | 1 `ci.yml` + 1 Flatpak manifest | CI/CD and packaging |
+
+## Supported Languages (UI Translation)
+
+Spanish (es), French (fr), Galician (gl), Italian (it), Polish (pl), Portuguese (pt)
+
+## Supported Keyboard Layouts
+
+US, Spanish, French, Galician, Italian, Polish, Portuguese
+
+## Word Lists for Text Generation
+
+40+ languages including: Arabic, Bengali, Bulgarian, Catalan, Czech, Danish, Dutch, English, Estonian, Finnish, French, Galician, German, Greek, Hebrew, Hindi, Hungarian, Indonesian, Italian, Kabyle, Kinyarwanda, Korean, Nepali, Norwegian (Bokmål/Nynorsk), Occitan, Persian, Polish, Portuguese, Romanian, Russian, Slovak, Swahili, Swedish, Turkish, Ukrainian, Vietnamese

.agents/summary/components.md

@@ -0,0 +1,113 @@
+# Components
+<!-- metadata: type=components, audience=ai-agents, scope=all-modules -->
+
+## Application Core
+
+### MecalinApplication (`src/application.rs`)
+- **Parent**: `adw::Application`
+- **Role**: Application entry point. Registers GResource base path, loads CSS, sets keyboard shortcuts (`Ctrl+Q` quit, `Ctrl+W` close), creates the main window on activation.
+- **Key behavior**: `startup()` loads global CSS provider; `activate()` creates and presents `MecalinWindow`.
+
+### MecalinWindow (`src/window.rs`)
+- **Parent**: `adw::ApplicationWindow`
+- **Role**: Main window and navigation hub. Contains `adw::NavigationView` with `ActionRow` entries for each feature.
+- **Template children**: `header_bar`, `window_title`, `navigation_view`, plus rows for lessons, speed test, falling keys, scrolling lanes, preferences, about.
+- **Key behavior**: Each row's `activated` signal pushes the corresponding navigation page by tag. Persists window size/maximized state via GSettings.
+
+## Feature Views
+
+### LessonView (`src/lesson_view.rs`)
+- **Parent**: `adw::NavigationPage`
+- **Role**: Structured typing lessons with step-by-step progression. The most complex view.
+- **Contains**: `TypingRow`, `KeyboardWidget`, `HandWidget`
+- **Key behavior**: Loads a `Course` based on locale, tracks current lesson/step/repetition via GSettings, highlights relevant keys on the keyboard, shows hand position guidance, advances through steps on completion, shows `CourseCompletionView` when all lessons are done.
+- **Properties**: `current_lesson` (boxed), `current_step_index` (u32)
+
+### SpeedTestView (`src/speed_test_view.rs`)
+- **Parent**: `adw::NavigationPage`
+- **Role**: Timed typing speed tests with configurable duration.
+- **Contains**: `SpeedTestTextView`, `SpeedTestResultsView`
+- **Key behavior**: Generates random text via `text_generation`, starts a timer, tracks progress, shows results (WPM, accuracy, duration) on completion or timeout.
+
+### FallingKeysGame (`src/falling_keys_game.rs`)
+- **Parent**: `adw::NavigationPage`
+- **Role**: Gamified typing practice where keys fall from the top of the screen.
+- **Contains**: `FallingKeysWidget` (custom painted widget), `KeyboardWidget`
+- **Key behavior**: Game loop spawns falling key characters, player must type them before they reach the bottom. Tracks score and lives. Uses `glib::timeout_add_local` for the game loop.
+- **Inner types**: `FallingKey` (position, character, speed), `FallingKeysWidget` (custom snapshot rendering)
+
+### ScrollingLanesGame (`src/scrolling_lanes_game.rs`)
+- **Parent**: `adw::NavigationPage`
+- **Role**: Gamified typing practice with text scrolling across lanes.
+- **Contains**: `LaneWidget` (custom painted widget), `KeyboardWidget`
+- **Key behavior**: Multiple lanes with scrolling text that must be typed. Uses `glib::timeout_add_local` for animation. Tracks score and lives.
+- **Inner types**: `ScrollingText` (text, position, lane), `LaneWidget` (custom snapshot rendering)
+
+### PreferencesView (`src/preferences_view.rs`)
+- **Parent**: `adw::NavigationPage`
+- **Role**: User settings for hand widget visibility, keyboard widget visibility, finger colors, and lesson selection.
+- **Key behavior**: Binds `adw::SwitchRow` widgets directly to GSettings keys. Populates lesson combo from `Course` data.
+
+### AboutView (`src/about_view.rs`)
+- **Parent**: `adw::NavigationPage`
+- **Role**: Application information, credits, and links.
+
+### CourseCompletionView (`src/course_completion_view.rs`)
+- **Parent**: `adw::NavigationPage`
+- **Role**: Congratulatory view shown when all lessons in a course are completed.
+
+## Reusable Widgets
+
+### TypingRow (`src/typing_row.rs`)
+- **Parent**: `adw::PreferencesRow`
+- **Role**: Core text input widget used in `LessonView`. Shows target text, captures typed input, validates character-by-character.
+- **Signals**: `mistake-made(bool)`, `step-completed`, `next-char-changed(String)`, `dead-key-started`
+- **Key behavior**: Locks cursor to end position, validates each keystroke against target text, draws custom cursor overlay, detects dead key input (for accented characters).
+
+### KeyboardWidget (`src/keyboard_widget.rs`)
+- **Parent**: `gtk::Widget`
+- **Role**: Visual on-screen keyboard that highlights the current key to press and shows finger assignments.
+- **Key behavior**: Loads keyboard layout from JSON, custom `snapshot()` rendering of keys with color-coded fingers, supports dead key sequences (accent → base char), handles modifier keys (Shift, AltGr).
+- **Inner types**: `KeyboardLayout`, `KeyInfo`, `Finger`, `ModifierKey`
+
+### HandWidget (`src/hand_widget.rs`)
+- **Parent**: `gtk::Widget`
+- **Role**: Visual hand position guide showing which finger to use.
+- **Key behavior**: Custom `snapshot()` rendering of left/right hands with highlighted current finger. Caches theme colors and responds to dark/light mode changes.
+
+### SpeedTestTextView (`src/speed_test_text_view.rs`)
+- **Parent**: `adw::Bin` (composite template)
+- **Role**: Rich text display for speed tests with color-coded correct/incorrect characters, animated caret, and scrolling.
+- **Sub-modules**: `accessibility.rs`, `caret.rs`, `colors.rs`, `input.rs`, `scrolling.rs`
+- **Key behavior**: Manages original vs typed text comparison, renders colored text via GTK TextBuffer tags, animates caret position, handles IME input, auto-scrolls as user types.
+- **Signals**: `typed-text-changed`, `push-original-text`, `set-original-text`
+
+### SpeedTestResultsView (`src/speed_test_results_view.rs`)
+- **Parent**: `adw::NavigationPage`
+- **Role**: Displays speed test results (WPM, accuracy, duration).
+- **Signals**: `retry-clicked`
+
+## Data & Utility Modules
+
+### Course (`src/course.rs`)
+- **Role**: Data model for structured typing lessons. Loads lesson JSON files based on language.
+- **Types**: `Course`, `Lesson`, `LessonStep`, `LessonsData`
+- **Key behavior**: `new_with_language()` loads embedded JSON via `include_str!`. Falls back to US English for unknown languages.
+
+### text_generation (`src/text_generation.rs`)
+- **Role**: Generates random typing text from embedded word lists.
+- **Types**: `Language` (enum with 30+ variants), `Punctuation`
+- **Key behavior**: Loads word lists via `include_dir!`, generates text with configurable difficulty (simple/advanced), supports punctuation insertion, uppercase, and wrapping.
+
+### text_utils (`src/text_utils.rs`)
+- **Role**: Text validation, WPM calculation, and character comparison utilities.
+- **Types**: `GraphemeState` (Correct/Unfinished/Mistake)
+- **Key behavior**: Grapheme-level validation with Unicode support, handles character aliases (æ→ae, guillemets→quotes, non-breaking spaces), calculates WPM from correct graphemes.
+
+### typing_test_utils (`src/typing_test_utils.rs`)
+- **Role**: Speed test configuration and result summary types.
+- **Types**: `TestConfig`, `TestDuration`, `TestSummary`, `GeneratedTestDifficulty`
+
+### utils (`src/utils.rs`)
+- **Role**: Locale detection, Unicode decomposition, and key extraction utilities.
+- **Key functions**: `language_from_locale()` (maps LANG env var to language code), `decompose_with_spacing_accent()` (for dead key handling), `extract_keys()` (unique characters from text).