# AGENTS.md - Agent Guidelines for Uni Slides (HdM + DHBW)

This file contains comprehensive guidelines for agentic coding agents working on the Uni Slides project. For the short version, see `CLAUDE.md`.

## Project Overview

This project builds presentation decks for Marp, supporting multiple courses:

- **223015b** – Dateiformate, Schnittstellen, Speichermedien (HdM, 6 Kapitel + Klausur)
- **223015c** – Internettechnologien (HdM, 3 Kapitel + Klausur)
- **dhbw** – Technik I – Grundlagen IT (DHBW, 8 Kapitel)

## Development Workflow

### Build Commands

Unified per-course pattern: `make <target>-<course>`. Group targets without suffix run for all courses. Single dev server serves all courses.

```bash
# Dev (all courses, single port)
make dev                      # Live server (HMR), port 1312

# Per-course build/deploy (replace <c> with: 223015b, 223015c, dhbw)
make build-<c>                # Build HTML + PDF
make html-<c>                 # HTML only
make pdf-<c>                  # PDF only
make klausur-<c>              # Extract klausur slides (HdM only)
make deploy-<c>               # Build + deploy single course (ASK FIRST!)

# All courses
make build                    # Build everything
make html / pdf               # HTML / PDF only
make klausur                  # Extract klausur (HdM courses only)
make deploy                   # Deploy everything (ASK FIRST!)

# Utilities
make qr URL=...               # Generate QR code
make qr-slides COURSE=<c>     # QR for course URL
make optimize-images COURSE=<c>   # Resize images
make clean                    # Remove generated files
make install                  # npm install
```

**Adding a new course:** add id to `COURSES` in `Makefile` + define `<id>_NAME`, `<id>_KAPITEL`, `<id>_DEPLOY`, `<id>_KLAUSUR`. No new targets needed.

### Nix Flake

```bash
nix develop                   # Dev shell with all tools (node 22, npm, make)
```

### Testing

No formal test framework. To validate changes:
1. Start dev server: `make dev`
2. Open http://localhost:1312/223015b/, /223015c/, or /dhbw/
3. Verify slides render correctly
4. Run `make build` to ensure no build errors
5. Check generated files in `build/` directory

## Code Style Guidelines

### File Structure

```
slides/
├── 223015b/            # HdM: Dateiformate
├── 223015c/            # HdM: Internettechnik
└── dhbw/               # DHBW: Technik I
scripts/                # Shared scripts
themes/                 # Custom Marp themes
build/                  # Generated output (gitignored)
```

- Slides in `slides/<course>/` following `NN-topic.md` (HdM) or `NN_topic.md` (DHBW)
- Assets in `slides/<course>/assets/`
- Always reference images as `./assets/filename.png`
- Scripts in `scripts/`
- Themes in `themes/`
- Generated output in `build/` (gitignored)

### Naming Conventions

- Slide files: `NN-topic.md` (HdM, e.g. `01-grundlagen.md`) or `NN_topic.md` (DHBW, e.g. `01_web_eng.md`)
- Images: `snake_case.jpg` or `kebab-case.jpg`
- Klausur files: `klausurfolien.md` / `klausurfragen.md` (auto-generated, HdM only)
- Function/variable names in scripts: `snake_case`

### Markdown Style

- Use ATX-style headers (`# ## ###`)
- YAML frontmatter for slide metadata at top of each file
- Never include a final `---` (creates empty slide)
- Use `<!-- _class: klausur -->` for exam-relevant slides (HdM)
- Use relative paths for assets: `./assets/image.png`

### Script Style

- Use `#!/usr/bin/env bash` shebang
- Use `set -e` for error handling
- Use `2>/dev/null || true` for optional operations
- Define variables in UPPER_CASE at script top
- Use colors for terminal output: `\033[0;32m` etc.

### Git Workflow

- Commit messages: ALWAYS lowercase
- NEVER add co-authoring lines or generated footers
- Follow semantic naming: "add-...", "fix-...", "update-..."
- Commit changes to scripts, Makefile, documentation separately from slide content

## Agent Restrictions

### Security

- NEVER run commands outside `/home/libretech/Repos/uni`
- NEVER run build/deploy commands without explicit user request
- NEVER run deploy commands (`make deploy`, `scp`, etc.) without explicit permission
- NEVER run `git checkout --` or `git restore` on files with uncommitted work. To undo specific changes, use targeted Edit operations instead.

### File Protection

Slide files in `slides/*/*.md` are main content files:
- **ALLOWED**: Adding slides, adjusting content, fixing typos, enhancing sections
- **FORBIDDEN** (without permission): Deleting slides, removing sections, bulk deletions
- Before ANY deletion: ALWAYS ask user for confirmation

### Klausur Handling (HdM only)

- Klausur files (`klausurfolien.md`, `klausurfragen.md`) are auto-generated
- NEVER edit klausur files directly
- To update klausur: edit source slides with `<!-- _class: klausur -->` markers
- Run `make klausur` (or `make klausur-<c>`) to regenerate
- DHBW course has no klausur extraction (`dhbw_KLAUSUR =` is empty)

## Development Patterns

### Adding New Slides

1. Create new file following naming convention (`NN-topic.md` for HdM, `NN_topic.md` for DHBW)
2. Copy frontmatter from existing slides in the same course
3. Add stem to `<course>_KAPITEL` in `Makefile`
4. Test with `make dev`

### Modifying Existing Slides

1. Edit the appropriate markdown file in `slides/<course>/`
2. Maintain consistent styling with course theme
3. Preserve image paths as `./assets/...`
4. Test changes with dev server

### Working with Assets

1. Place images in `slides/<course>/assets/`
2. Use descriptive names: `diagram-network.jpg`, `example-code.png`
3. Optimize with `make optimize-images COURSE=<c>`
4. Reference as `./assets/filename.ext`

### Course-Specific Configuration

Each course has these per-course settings in `Makefile`:
- `<c>_NAME` – Display name
- `<c>_KAPITEL` – Ordered list of slide file stems (without `.md`)
- `<c>_DEPLOY` – Remote deploy path
- `<c>_KLAUSUR` – `1` to enable klausur extraction, empty to disable

## Common Tasks

### Debugging Build Issues

1. Check Makefile syntax: `make -n build-<c>`
2. Verify Marp CLI: `npx @marp-team/marp-cli --version`
3. Check file permissions: `ls -la slides/`
4. Validate markdown via dev server

### Updating Course Structure

1. Update `<c>_KAPITEL` in `Makefile`
2. Ensure slide files follow naming convention
3. Update course-specific themes if needed
4. Test both `make dev` and `make build-<c>`

### Working with Themes

- Custom theme in `themes/custom-theme.css`
- Course themes referenced in individual slide frontmatter
- Use consistent color schemes per course
- Test theme changes across all slides

## Deployment Process

Deployment to production server requires explicit permission:
1. Build: `make build` (HTML + PDF) or per-course `make build-<c>`
2. Index generation: handled by `scripts/generate-index.sh` (per course) and `scripts/generate-root-index.sh` (root)
3. Deploy: `scp` to `tengo@tuttle.uberspace.de` via `make deploy-<c>` or `make deploy`
4. Root index deployed by `make deploy-index` (or as part of `make deploy`)

**IMPORTANT**: Never run deployment commands without explicit user permission.

## Tools and Dependencies

### Core
- Marp CLI for slide rendering (via `npx @marp-team/marp-cli`)
- Bash scripts for automation (`scripts/`)
- Make for build orchestration
- Git for version control

### Optional
- `qrencode` for QR generation (via nix-shell)
- ImageMagick for image optimization (via nix-shell)

## Troubleshooting

### Common Issues
- **Port conflicts**: kill the dev-server process holding port 1312
- **Build failures**: check file permissions and Marp CLI availability via `npx`
- **Asset loading**: verify relative paths and file existence in `slides/<c>/assets/`
- **Deploy issues**: check SSH keys for `tengo@tuttle.uberspace.de` and remote permissions

### Getting Help
1. Check this `AGENTS.md` first
2. Review `Makefile` targets and `scripts/`
3. Test changes incrementally
4. Maintain backup of working configurations