225 lines
7.8 KiB
Markdown
225 lines
7.8 KiB
Markdown
# 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
|