german-learning-context/README.md

# German Learning — Co-learning Context Repo

This repo tracks what I've actually covered across German-learning materials
(course books, workbooks, audio transcripts, and answer keys), lesson by
lesson, so that Claude (or any LLM) has exact context on my vocabulary and
grammar level when we study together. *Menschen A1.1* is the first source;
later books can be added alongside it.

## How to use this with Claude

At the start of a study session, point Claude at the relevant lesson file(s)
(e.g. `A1.1/lektion-05.md`), or the whole `A1.1/INDEX.md` for a running
summary. Ask Claude to only use vocabulary/grammar that appears in those
files (or earlier lessons) when creating exercises, example sentences, or
corrections — this keeps practice within what I've actually learned.

## Structure

```
A1.1/
  lektion-XX.md   ← everything for one lesson: vocab, grammar, communication
                     patterns, course book + workbook exercise summaries,
                     official audio transcripts, answer key highlights
  _template.md    ← template used to build each lektion-XX.md
  INDEX.md        ← one-line summary of every lesson so far
A1.2/             ← added once I move on to the next book
  ...
Ergaenzung/       ← supplementary practice books (see below)
  wortschatz-grammatik-a1/
  hoeren-sprechen-a1/
  lesen-schreiben-a1/
  _template.md
  INDEX.md
scripts/
  transcribe.py   ← local ASR fallback (faster-whisper) for audio with no
                     official transcript
```

Each lesson is one combined file rather than separate course-book/workbook
files, because *Menschen*'s workbook exercises constantly reference course
book sections (e.g. "KB 2b") and share the same grammar — splitting them
apart would just duplicate content.

## Adding a new lesson

1. Get the course book pages, workbook pages, and (if available) the
   official Hueber Transkriptionen PDF pages for that lesson — as PDFs,
   photos, or a folder path.
2. Claude extracts/summarizes content into `lektion-XX.md` using
   `_template.md`: vocabulary (from the workbook's Lernwortschatz page),
   grammar boxes, communication patterns, a brief summary of what each
   exercise practices (not full exercise text), audio transcripts, and
   answer key highlights.
3. Review and correct anything Claude got wrong or over-summarized.
4. Update `INDEX.md` with a one-line entry for the lesson.
5. Commit.

## Audio (listening exercises)

Hueber releases official **Transkriptionen** PDFs for both the Kursbuch
(course book) and Arbeitsbuch (workbook) — these are the primary source for
audio content, not the *Lösungsschlüssel* (answer key — a different
document). Raw audio files are **not** stored in this repo (see
`.gitignore`); only transcripts (text) are, since that's what gives Claude
context.

Primary workflow — official transcripts:
1. Get the Kursbuch and Arbeitsbuch Transkriptionen PDFs for the relevant
   book (A1.1, A1.2, ...).
2. Extract the per-track dialogue text into that lesson's `.md` file under
   "Audio / Listening", marked as official-sourced.
3. No review needed for accuracy — these are publisher-official text, not ASR.

Fallback workflow — local ASR (only if no official transcript exists for a
given track, e.g. supplementary listening material):
1. Get the audio files locally (publisher CD/app/download), any folder
   outside git.
2. Run `scripts/transcribe.py` (uses `faster-whisper` on GPU) to transcribe
   them:
   ```bash
   pip install faster-whisper
   python scripts/transcribe.py "<path-to-lesson-audio>" "A1.1/transcripts/lektion-XX"
   ```
3. Skim the `.txt` output for ASR mistakes (names, numbers, fast speech) and
   fix them.
4. Reference/paste the transcript into the lesson's `.md` file under "Audio
   / Listening", flagged as ASR-generated — transcripts are small text
   files so committing them is fine.

## Adding a new book (e.g. A1.2)

Copy the `A1.1/` folder structure (minus content) into a new `A1.2/` folder
and repeat the process.

## Supplementary practice books (`Ergaenzung/`)

Alongside *Menschen*, I also use three Hueber *Deutsch üben* practice
books: **Wortschatz & Grammatik A1**, **Hören & Sprechen A1**, and **Lesen
& Schreiben A1**. Unlike *Menschen*, these aren't organized lesson-by-lesson
against a shared story/curriculum — each is structured around its own
topics/units (grammar points for Wortschatz & Grammatik, skill-practice
units for the other two). Forcing them into the `A1.1/lektion-XX.md`
structure would misrepresent that, so they get their own space instead:

```
Ergaenzung/
  wortschatz-grammatik-a1/abschnitt-X.md
  hoeren-sprechen-a1/abschnitt-X.md
  lesen-schreiben-a1/abschnitt-X.md
  _template.md   ← template for these files
  INDEX.md       ← per-book tables mapping each section to Menschen Lektion(en)
```

Each `abschnitt-X.md` covers one lettered section as defined by that book's
own table of contents (e.g. Wortschatz & Grammatik A1's "A Person, Familie
und Freunde", which itself bundles ~17 small sub-exercises) — not one file
per tiny sub-exercise, since those are often half a page each. It's scoped
like a lesson file (vocab/grammar covered, exercise summary, audio
transcript if applicable, answer key highlights, notes) but adds a
**"Relates to Menschen Lektion(en)"** field so a tutor session can tell
whether content is reinforcing what's already been covered in *Menschen*
or introducing something new/out-of-scope. These books also ship their own
built-in Lösungen (answer key), so no separate answer-key source is needed.

Workflow for adding a section: same as adding a *Menschen* lesson (get the
pages as PDF/photo, Claude summarizes into `abschnitt-X.md` using
`Ergaenzung/_template.md`, review, update `Ergaenzung/INDEX.md`, commit).