# AGENTS.md - Agent Guidelines for HdM Slides

This file contains comprehensive guidelines for agentic coding agents working on the HdM Slides project.

## Project Overview

This project builds presentation decks for Marp, supporting multiple courses:
- **223015b** - Dateiformate, Schnittstellen, Speichermedien (6 Kapitel)
- **223015c** - Internettechnologien (3 Kapitel)

## Development Workflow

### Build Commands
```bash
# Development
make dev              # Start single dev server on port 3000
npm run dev           # Alternative command for development server

# Build
make build            # Build all courses (HTML + PDF)
make build-b          # Build 223015b only
make build-c          # Build 223015c only
make html             # HTML only builds
make pdf              # PDF only builds

# Klausur Folien
make klausur          # Extract klausurfolien for all courses
make klausur-b        # Extract klausurfolien for 223015b
make klausur-c        # Extract klausurfolien for 223015c

# Deployment
make deploy            # Deploy all courses (requires explicit permission)
make deploy-b         # Deploy 223015b only
make deploy-c         # Deploy 223015c only

# Utilities
make qr URL=...       # Generate QR code
make optimize-images COURSE=223015b  # Resize images
make clean            # Remove generated files
```

### Testing
No specific test framework is used. To validate changes:
1. Start dev server: `make dev`
2. Open http://localhost:3000/223015b/ or /223015c/
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 in `slides/<course>/` following naming pattern `NN-topic.md`
- 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` (e.g., `01-grundlagen.md`, `02-bilder.md`)
- Images: `snake_case.jpg` or `kebab-case.jpg`
- Klausur files: `klausurfolien.md` (auto-generated)
- Function names in scripts: `snake_case`
- 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
- 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/mwc/Coding/hdm` folder
- NEVER run build/deploy commands without explicit user request
- NEVER run deploy commands (make deploy, scp, etc.) without explicit permission

### 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
- Klausur files (`klausurfolien.md`) are auto-generated
- NEVER edit klausurfolien.md files directly
- To update klausurfolien: edit source slides with `<!-- _class: klausur -->` markers
- Run `make klausur` to regenerate

## Development Patterns

### Adding New Slides
1. Create new file following `NN-topic.md` pattern
2. Copy frontmatter from existing slides in the same course
3. Update Makefile `_KAPITEL` variable if needed
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=223015b`
4. Reference as `./assets/filename.ext`

### Course-Specific Configuration
Each course has specific settings in Makefile:
- Course name and title
- Kapitel list (slide files)
- Deploy path
- Theme colors (in generate-index.sh)

## Common Tasks

### Debugging Build Issues
1. Check Makefile syntax: `make -n build`
2. Verify Marp CLI installation: `npx @marp-team/marp-cli --version`
3. Check file permissions: `ls -la slides/`
4. Validate markdown syntax with dev server

### Updating Course Structure
1. Update `_KAPITEL` variables in Makefile
2. Ensure slide files follow naming convention
3. Update course-specific themes if needed
4. Test both dev and build processes

### Working with Themes
- Custom theme in `themes/custom-theme.css`
- Course themes defined 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 process: `make build` (HTML + PDF)
2. Index generation: automatically handled
3. Deploy to remote server via SCP
4. Root index deployment

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

## Tools and Dependencies

### Core Dependencies
- Marp CLI for slide rendering
- Bash scripts for automation
- Make for build orchestration
- Git for version control

### Optional Tools
- qrencode for QR generation (via nix)
- ImageMagick for image optimization
- Python 3 for simple HTTP server (legacy)

## Testing Strategy

Since there's no formal test suite:
1. Manual testing with dev server
2. Build process validation
3. Slide rendering checks
4. Asset path verification
5. Cross-browser compatibility checks (important)

## Troubleshooting

### Common Issues
- **Port conflicts**: Use `make dev-kill` to clean up processes
- **Build failures**: Check file permissions and Marp CLI installation
- **Asset loading**: Verify relative paths and file existence
- **Deploy issues**: Check SSH keys and remote permissions

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