FOR_SMLFLG.md

# StudyAgent — FOR_SMLFLG

## Was ist das?
ADHS-freundlicher Study Buddy: Hilft Studenten mit ADHS durch ihr Semester.
Keine starren Plaene — Micro-Steps, Buddy-Ton, Dopamin beim Start statt beim Abschluss.

## Warum
Samuel IS die Zielgruppe. 569 ChatGPT + 232 Claude Sessions dokumentieren das Problem.
Kern-Insight: Dopamin kommt beim Task-BEGINN, nicht beim Complete. Jeder Step = frischer Start.

## Pain Points die das System loest
1. Lernplaene die nie halten — elastischer Plan, kein Guilt
2. WIP explodiert — max 2 Faecher gleichzeitig (hard enforcement in API)
3. Zeitdruck als Feature — Panik-Modus bei <48h
4. Routinedokumentation unmoeglich — Micro-Steps (je 5 Min)
5. Session-Memory — nie wieder bei Null anfangen

## Architektur & Tech-Stack

```
StudyAgent/
├── main.py          # FastAPI app, alle Routes, htmx-Partials (~516 LOC)
├── agent.py         # MiniMax M2.5 API-Call, Fallback-Steps ohne Key
├── models.py        # SQLAlchemy Models (Subject, Deadline, MicroStep, StudySession)
├── database.py      # SQLite Setup, Session-Maker
├── requirements.txt
├── static/style.css # Warm palette, ADHS-friendly Design
├── templates/
│   ├── base.html
│   ├── index.html
│   └── partials/    # subject_card, deadline_item, micro_step_card,
│                    # elastic_plan, progress_journey, session_banner
└── study_agent.db   # auto-created
```

**Tech:** Python + FastAPI (async, lifespan) + SQLAlchemy + SQLite + htmx + Jinja2 + MiniMax M2.5 API

## Starten / Nutzen

```bash
cd ~/Projekte/StudyAgent

# Erste Einrichtung
pip install -r requirements.txt
export MINIMAX_API_KEY=your-key-here   # optional — ohne Key laufen Fallback-Steps

# Starten
.venv/bin/uvicorn main:app --reload   # oder: uvicorn main:app --reload
# open http://localhost:8000
```

## Was funktioniert (implementiert)

- **Dashboard** (`GET /`) — aktive Faecher, naechste Deadlines, naechster Step, Session-Banner, Panik-Indikatoren
- **Faecher CRUD** (`POST/DELETE /subjects`) — WIP-Limit 2 wird server-seitig enforced
- **Deadlines anlegen** (`POST /deadlines`) — auto-generiert sofort Micro-Steps via MiniMax M2.5
- **Steps abschliessen/ueberspringen** (`POST /steps/{id}/complete|skip`) — naechster Step wird inline geladen
- **Elastischer Plan** (`GET /deadlines/{id}/plan`) — auto-komprimiert wenn Steps die verbleibende Zeit uebersteigen
- **Replan** (`POST /deadlines/{id}/replan`) — loescht pending+skipped, generiert neu
- **Session-Tracking** — Sessions werden auto-gestartet, after 30 Min Inaktivitaet auto-geschlossen
- **Panik-Modus** (`is_panic_mode()`) — greift bei <48h, reduziert auf 3-4 wesentliche Steps
- **AI-Fallback** — ohne `MINIMAX_API_KEY` kommen sinnvolle Dummy-Steps (kein Absturz)

## Was fehlt / bekannte Issues

- `.env` vorhanden (`MINIMAX_API_KEY`), in `.gitignore` geschuetzt. `.env.example` als Vorlage vorhanden.
- Browser-Test-Flow (Subject anlegen → Dashboard → Steps) noch nicht durchgespielt
- `fi_date`-aehnlicher Edge-Case: wenn `due_date` bereits vergangen ist, liefert `is_panic_mode()` `False` statt sinnvollen Zustand
- Kein Deployment-Setup (Fly.io geplant)
- Kein Auth (MVP-bewusste Entscheidung)

## Entscheidungen & Lessons Learned

- **htmx statt React** — kein Build-Step, Partials direkt vom Server, funktioniert ohne JS-Framework
- **Buddy-Ton in Code** — "Kein Stress, machen wir anders." direkt in Responses, kein separates i18n
- **Dummy-Steps als Fallback** — API-Fehler oder fehlender Key darf nie das Feature brechen
- **WIP-Limit server-seitig** — nicht nur UI-Warnung, sondern echter `HTTPException`-Block im `POST /subjects`
- **Auto-compress elastisch** — 20% Buffer-Formel: wenn `pending * 5min > hours_left * 0.8 * 60` → Replan

## Next Steps (priorisiert)

1. `MINIMAX_API_KEY` in `.env`-File konfigurieren und testen
2. Browser-End-to-End-Test: Subject → Deadline → Steps → Complete/Skip
3. Edge-Case fixen: vergangene Deadlines richtig behandeln
4. Sprint 3: Panik-Modus visuell sichtbar machen (Banner, roten Rahmen)
5. Fly.io Deployment vorbereiten