# AGENTS.md - Guidelines for JuliaKurs23

This is a **Quarto-based Julia programming course book**. The book teaches scientific computing with Julia using interactive Jupyter notebooks rendered with Quarto.

**Translation Note:** The book was originally written in German and translated to English. The English needs improvement—focus on making the prose professional, concise, and suitable for mathematicians.

## Project Overview

- **Type**: Educational book (HTML website + PDF) generated from Quarto (.qmd) files
- **Language**: English (all content)
- **Build System**: Quarto with Julia Jupyter kernel
- **Julia Version**: 1.10
- **License**: CC BY-NC-SA 4.0

---

## Current Task: English Translation Improvement

The English text in this book was translated from German and needs refinement for quality.

### Workflow (one change at a time)

For each chapter file in `chapters/`:

1. I read the file and identify English improvements
2. I present ONE improvement at a time showing:
   - The current text
   - The proposed improvement
   - Explanation of why the change is needed
3. You reply **yes** or **no**
4. If yes, I apply the change; if no, I skip it
5. Repeat until all improvements for that file are done
6. Move to the next chapter file

### What to improve:
- English prose, grammar, word choice
- Clarity and flow for mathematical audience
- Professional tone suitable for mathematicians/scientists

### What NOT to change:
- Julia code
- LaTeX equations
- Markdown formatting
- Quarto cell options (`#| eval:`, etc.)

---

## Build Commands

```bash
# Build HTML website
quarto render

# Build only HTML
quarto render --to julia-color-html

# Build only PDF
quarto render --to julia-color-pdf

# Preview locally
quarto preview

# Render a specific chapter
quarto render chapters/first_contact.qmd

# Run in daemon mode (faster rebuilds)
quarto render --execute-daemon 3600
```

### Deployment

```bash
./deploy.sh
```

---

## Code Style Guidelines

### Quarto Structure (.qmd files)

- All `.qmd` files start with YAML front matter: `engine: julia`
- Code blocks use triple backticks with `julia` identifier
- Cell options in comments: `#| option: value`

### Julia Code Conventions

**Imports:**
```julia
using Statistics, LinearAlgebra, Plots  # many exports
import Base: convert, show               # specific exports
```

**Naming:**
- Variables/functions: lowercase with underscores (`my_variable`)
- Types: CamelCase (`MyType`, `AbstractMatrix`)
- Constants: ALL_UPPERCASE (`MAX_ITER`)
- Modules: PascalCase (`Statistics`)

**Formatting:**
- 4 spaces indentation
- ~92 character line limit
- Spaces around operators: `a + b`
- No spaces before commas: `f(a, b)`

**Types:**
- Explicit types for performance/clarity
- Parameterize: `Vector{Float64}`, `Dict{Symbol, Int}`
- Concrete types for struct fields

**Error Handling:**
```julia
try
    parse(Int, user_input)
catch e
    println("Invalid input: $e")
end

@assert x >= 0 "x must be non-negative"
```

---

## File Organization

```
/
├── _quarto.yml          # Quarto configuration
├── Project.toml         # Julia dependencies
├── index.qmd            # Book index
├── chapters/            # Chapter .qmd files
├── notebooks/           # Jupyter notebooks (.ipynb)
├── css/                 # Custom styles
├── images/              # Images and logos
├── fonts/               # Custom fonts
└── _book/               # Built output (generated)
```

---

## Important Notes

1. **All content is in English** — professional, concise, suitable for mathematicians
2. **Code, LaTeX, formatting preserved** — only improve English prose
3. **Code execution cached** — use `#| eval: true` to execute cells
4. **Freeze mode** — set to `auto` in _quarto.yml; use `freeze: false` to re-run all code
5. **Keep intermediates** — `keep-ipynb`, `keep-tex`, `keep-md` are all true