@imstudium/cli 0.1.1

package/mcp.json

@@ -0,0 +1,11 @@
+{
+  "mcpServers": {
+    "imstudium": {
+      "command": "npx",
+      "args": ["-y", "@imstudium/mcp"],
+      "env": {
+        "IMSTUDIUM_WORKSPACE": "~/Studium"
+      }
+    }
+  }
+}

package/package.json

@@ -0,0 +1,60 @@
+{
+  "name": "@imstudium/cli",
+  "version": "0.1.1",
+  "description": "ImStudium CLI — study workspace from Stud.IP",
+  "license": "MIT",
+  "type": "module",
+  "author": "Patrick Schröppel",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/paddy-shrp/imstudium.git",
+    "directory": "packages/cli"
+  },
+  "homepage": "https://github.com/paddy-shrp/imstudium#readme",
+  "bugs": {
+    "url": "https://github.com/paddy-shrp/imstudium/issues"
+  },
+  "keywords": [
+    "imstudium",
+    "studip",
+    "studium",
+    "mcp",
+    "cursor",
+    "claude",
+    "codex",
+    "windsurf",
+    "opencode"
+  ],
+  "bin": {
+    "imstudium": "./dist/cli.js"
+  },
+  "files": [
+    "dist",
+    "skills",
+    "mcp.json"
+  ],
+  "scripts": {
+    "build": "tsup",
+    "typecheck": "tsc --noEmit",
+    "clean": "rm -rf dist",
+    "prepublishOnly": "bun run build && bun run typecheck"
+  },
+  "dependencies": {
+    "@imstudium/sdk": "workspace:*",
+    "commander": "^13.1.0",
+    "playwright": "^1.52.0"
+  },
+  "devDependencies": {
+    "@types/node": "^22.15.21",
+    "tsup": "^8.5.0",
+    "tsx": "^4.19.4",
+    "typescript": "^5.8.3"
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  }
+}

package/skills/imstudium-cli/SKILL.md

@@ -0,0 +1,65 @@
+---
+name: imstudium-cli
+description: |
+  ImStudium CLI — sync Stud.IP course files, build ~/Studium workspace, plan Klausuren.
+  Use when the user mentions ImStudium, Studium, Stud.IP, course materials, Klausur dates, or exam prep from university LMS.
+allowed-tools:
+  - Bash(imstudium *)
+  - Bash(npx @imstudium/cli *)
+  - Bash(npx -y @imstudium/cli@latest *)
+---
+
+# imstudium cli
+
+Command-line interface for ImStudium / Stud.IP. Sync materials, build agent workspace, plan exams.
+
+## When to use
+
+- User wants course files offline from ImStudium
+- User asks about Klausuren / exam timeline
+- User needs `studium.json` for study planning
+- Prefer **local workspace** after sync — no API calls until refresh
+
+## One-shot setup
+
+```bash
+npx -y @imstudium/cli onboard --agents-only -y -o ~/Studium
+imstudium login
+imstudium init -o ~/Studium
+```
+
+## Updates
+
+```bash
+imstudium update --json   # upgrade + refresh harness; use --json for agents
+```
+
+## Quick commands
+
+```bash
+imstudium status --json
+imstudium --json studium
+imstudium --json klausuren
+imstudium sync --quiet --extract
+imstudium extract --course "Analysis"
+imstudium doctor --json
+imstudium files tree --course "Analysis"
+```
+
+## Reading slides
+
+After `extract`, each file has `extracted/<file>/content.md` and `pages/*.png`. Read the PNGs for diagrams and formulas (see `imstudium-visual` skill).
+
+## Auth
+
+```bash
+imstudium login   # local helper fallback until OAuth is registered
+```
+
+## Escalation
+
+1. `imstudium status --json` — auth + cliVersion
+2. `imstudium update --json` — upgrade + refresh harness
+3. `imstudium --json studium` — local overview
+4. `imstudium sync` — refresh from API
+5. MCP tools — see `@imstudium/mcp` skill

package/skills/imstudium-klausuren/SKILL.md

@@ -0,0 +1,33 @@
+---
+name: imstudium-klausuren
+description: |
+  Klausur and exam timeline with days-remaining. Use when user asks about exams, Prüfungen, deadlines, "when is my Klausur".
+---
+
+# imstudium klausuren
+
+Exam planning from `klausuren.md` / `studium.json`.
+
+## Read timeline
+
+```bash
+imstudium --json klausuren
+```
+
+Or MCP: `studium_klausuren`
+
+## Confirmed vs unconfirmed
+
+| Source | Trust |
+|--------|-------|
+| `event` (course calendar) | **Confirmed** — schedule around these |
+| `achievement`, `miscellaneous` | **Unconfirmed** — ask student to verify |
+
+## Planning output
+
+For each exam in the next 14 days:
+
+1. Date + `daysRemaining`
+2. Course title
+3. Location if known
+4. Top materials via `studium_find_materials`

package/skills/imstudium-mcp/SKILL.md

@@ -0,0 +1,59 @@
+---
+name: imstudium-mcp
+description: |
+  ImStudium MCP tools for all agent harnesses — studium overview, klausuren, course brief, find materials, sync.
+  Use when working inside an MCP-enabled agent instead of terminal.
+---
+
+# imstudium mcp
+
+MCP server: `@imstudium/mcp`
+
+## Install
+
+```bash
+imstudium setup mcp
+```
+
+## Tool selection
+
+| Intent | Tool |
+|--------|------|
+| Course map + search guidance | `studium_overview` (read `searchGuidance`) |
+| Exams | `studium_klausuren` |
+| One course | `studium_course_brief` |
+| Find PDFs by filename | `studium_find_materials` |
+| **Read/see slide content** | `studium_read_material` |
+| Refresh | `imstudium_sync` |
+| Auth check | `imstudium_whoami` |
+
+## Finding content (use YOUR search tools)
+
+**No custom search MCP tool.** Cursor/Codex/Claude already grep and semantic-search — the harness only prepares the index.
+
+After `studium_overview`, use `searchGuidance`:
+
+```
+rg -i "backprop" ~/Studium/SS2026/*/search/corpus.jsonl
+```
+
+Each JSONL line has `ref`, `text`, `pageImage`, `extractSlug`. Cite with `ref`, then read:
+
+- `extracted/<extractSlug>/content.md` (## Page N)
+- `extracted/<extractSlug>/pages/page-NNN.png` for slides
+
+Or semantic-search `corpus.jsonl` / `content.md` with your harness indexer.
+
+## Workflow
+
+```
+imstudium_whoami → studium_overview → studium_klausuren
+  → grep corpus.jsonl OR studium_find_materials
+  → studium_read_material → read pageImages
+```
+
+Prefer local tools before `imstudium_sync` (network + auth).
+
+## Visual comprehension (important)
+
+`studium_read_material` returns `content` (text) and `pageImages` (PNG paths). Slides carry diagrams, plots, and formulas that text misses — **read the `pageImages` files** with your image-reading tool before explaining slide content. Use the `page` argument to target one slide.

package/skills/imstudium-studium/SKILL.md

@@ -0,0 +1,33 @@
+---
+name: imstudium-studium
+description: |
+  Read the Studium workspace — courses, file counts, schedule context from studium.json.
+  Use after sync or when user asks "what courses am I in", "semester overview", "my Studium".
+---
+
+# imstudium studium
+
+Local semester map at `~/Studium/studium.json` (or `IMSTUDIUM_WORKSPACE`).
+
+**Default:** current calendar semester only (e.g. `SS2026/`), not all past enrollments.
+
+## Read first (no network)
+
+```bash
+imstudium --json studium
+```
+
+Or MCP: `studium_overview`
+
+## Output includes
+
+- Course list with slugs and file counts (current semester by default)
+- `semesters`, `semesterSlug` — active Stud.IP semester
+- `nextDeadlines` — upcoming exams
+- Schedule entries per course
+
+## Refresh only when stale
+
+```bash
+imstudium sync --quiet
+```

package/skills/imstudium-sync/SKILL.md

@@ -0,0 +1,45 @@
+---
+name: imstudium-sync
+description: |
+  Sync course files, wiki, news, and calendar from Stud.IP via ImStudium. Use when materials are missing, stale, or user says "refresh Studium", "download course files".
+---
+
+# imstudium sync
+
+Incremental sync from Stud.IP JSON:API to local workspace.
+
+**Default:** syncs courses active in the **current calendar semester** into `~/Studium/SS2026/` (not all 50+ past enrollments).
+
+```bash
+imstudium semesters              # show current + recent semesters
+imstudium courses list           # current semester courses only
+imstudium sync --semester WS2025-26   # pick a specific semester
+imstudium sync --all-semesters   # legacy: every enrollment
+```
+
+## Full refresh
+
+```bash
+imstudium sync -o ~/Studium
+imstudium sync --extract        # also extract text + slide images
+```
+
+Includes wiki, news, `calendar.ics`, rebuilds `studium.json`. With `--extract`, new/changed files get `extracted/<file>/content.md` + `pages/*.png`.
+
+## Preview (dry run)
+
+```bash
+imstudium sync --dry-run --json
+```
+
+Or MCP: `imstudium_sync_dry_run`
+
+## Cron
+
+```cron
+0 8 * * * imstudium sync --quiet --extract -o ~/Studium
+```
+
+## After sync
+
+Always re-read: `imstudium --json studium`

package/skills/imstudium-visual/SKILL.md

@@ -0,0 +1,63 @@
+---
+name: imstudium-visual
+description: |
+  MANDATORY when explaining slides, PDFs, diagrams, or formulas from ImStudium materials.
+  Text extraction is incomplete — you MUST read page PNGs or open viewer.html in Playwright/browser before answering.
+  Use after studium_read_material, imstudium view, or when user asks about slide content.
+allowed-tools:
+  - Bash(imstudium view *)
+  - Bash(imstudium extract *)
+  - Bash(npx playwright *)
+---
+
+# imstudium visual comprehension
+
+Slides are **visual**. `content.md` text misses diagrams, plots, formulas, tables, and layout.
+
+## Rule (all agents)
+
+**Never summarize slide content from text alone.** Before answering:
+
+1. Read **every** path in `pageImages`, OR
+2. Open `viewerFileUrl` (`file://.../viewer.html`) in Playwright / browser MCP and inspect each slide
+
+## Fast paths by harness
+
+| Harness | What to do |
+|---------|------------|
+| **Cursor / Claude / Codex / Windsurf / OpenCode with Read/vision** | `Read` each `pageImages` file |
+| **Playwright CLI** | `imstudium view --course "Analysis" --file "vorlesung 3"` → open printed `viewerFileUrl` |
+| **Browser MCP** (cursor-ide-browser) | `browser_navigate` to `viewerFileUrl`, `browser_take_screenshot` per slide |
+| **MCP only** | `studium_read_material` → follow `requiredAction` + `methods` in JSON response |
+| **Terminal** | `imstudium view --dir ~/Studium/.../extracted/foo-pdf` |
+
+## MCP response fields
+
+```json
+{
+  "requiredAction": "MANDATORY: Visually inspect all pageImages...",
+  "pageImages": ["/abs/path/pages/page-1.png", "..."],
+  "viewerHtml": "/abs/path/viewer.html",
+  "viewerFileUrl": "file:///abs/path/viewer.html",
+  "methods": [{ "id": "read_image", "action": "..." }, { "id": "playwright", "action": "..." }]
+}
+```
+
+Follow `requiredAction` literally.
+
+## Speed
+
+- `studium_read_material` reuses cached extraction (manifest mtime) — fast on repeat
+- `imstudium view` only writes `viewer.html` (~instant) — no re-render unless file changed
+- Bulk `imstudium extract` does NOT auto-open browser — agents opt in per file
+
+## Playwright one-liner
+
+```bash
+imstudium view --course "Analysis" --file "folien" --json
+# → open viewerFileUrl in Playwright, screenshot each .slide img
+```
+
+## When pageImages is empty
+
+Tell user: `imstudium doctor` then `imstudium extract --course "..."`. Poppler renders PDF slides; LibreOffice renders PPTX.

package/skills/workflows/klausur-prep/SKILL.md

@@ -0,0 +1,31 @@
+---
+name: imstudium-klausur-prep
+description: |
+  Workflow — produce a Klausur prep brief for one course: exam date, days remaining, priority files, 60-min study block.
+  Use when user says "help me study for", "Klausur prep", "exam plan for [course]".
+---
+
+# Workflow: Klausur prep
+
+## Inputs
+
+- Course name (substring match)
+- Optional: days until exam
+
+## Steps
+
+1. `studium_klausuren` — confirm exam date (confirmed vs unconfirmed)
+2. `studium_course_brief` — course context + `COURSE.md`
+3. `studium_find_materials` with queries: `klausur`, `übung`, `script`, `folien`
+4. `studium_read_material` on the top files — read the `pageImages` PNGs to actually see diagrams and formulas, then summarize key concepts per slide
+5. If no files: `imstudium_sync_dry_run` then `imstudium_sync`
+
+## Deliverable
+
+```markdown
+## [Course] — Klausur prep
+- **Exam:** [date] ([N] days)
+- **Status:** confirmed / verify manually
+- **Priority files:** (top 3 paths)
+- **60-min block:** [single focused task with done state]
+```

package/skills/workflows/semester-refresh/SKILL.md

@@ -0,0 +1,29 @@
+---
+name: imstudium-semester-refresh
+description: |
+  Workflow — morning semester refresh: sync, overview, next 3 exams, flag stale courses.
+  Use for daily briefing, "what's due", "update my Studium".
+---
+
+# Workflow: Semester refresh
+
+## Steps
+
+0. `imstudium update` — upgrade CLI + refresh harness
+1. `imstudium_whoami` — auth OK?
+2. `imstudium_sync` or CLI `imstudium sync --quiet`
+3. `studium_overview` — course list
+4. `studium_klausuren` — `nextDeadlines` top 3
+
+## Deliverable
+
+```markdown
+## Studium refresh — [date]
+- **Courses:** N active
+- **Next exams:** (top 3 with days remaining)
+- **Action:** [one course needing attention — fewest files or nearest exam]
+```
+
+## Cron alignment
+
+Matches `0 8 * * * imstudium sync --quiet` — run this workflow after sync in daily briefing.