uni/AGENTS.md

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.

# 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

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