uni/AGENTS.md

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

# 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