@jamestesting888/tum-mcp 0.6.1 → 0.7.0

package/CHANGELOG.md

@@ -1,5 +1,30 @@
 # Changes
 
+## 0.7.0 — 2026-10-26
+
+- Share one course app between Study and Exercises, with a single workspace
+  selector in the sidebar footer and a responsive mobile outline.
+- Add `prepare-exercises` for source-backed weekly exercises with optional hints,
+  explanations, solutions and prepared checks. Support editable tables, long math
+  and code drafts, graph selections/paths and line graph sample points. Open work
+  uses rubric comparison; the app does not execute code or grade proofs.
+- Keep step navigation in place, shorten controls and show section sources through
+  compact reference icons. Preserve browser progress, drafts and passage comments.
+- Use `.tum-mcp/` for private course state and a cited agent course handbook covering
+  course organization, schedules, coursework/platforms, assessment and bonus rules.
+  Track reviewed source versions, coverage gaps and changed supporting sources.
+- Rename `sync-study` to `sync-course` and `publish-study` to `publish-course`;
+  retain managed migration for previous skill names and preserve personal overrides.
+- Keep the shipped app a minimal reusable component template, explicitly distinct
+  from an example of good course teaching. Keep rich synthetic tests out of the package.
+
+New projects use `app/`; existing `study/` websites remain supported. Run
+`tum-mcp study upgrade PROJECT` explicitly to rename legacy `.study/` metadata;
+it preserves private records and archives the old root instructions. The separate
+`study build PROJECT --upgrade-layout` moves a verified legacy web folder to `app/`
+with a backup. Neither package installation nor update migrates course folders or
+rebuilds personal sites automatically. Exercise publication is opt-in.
+
 ## 0.6.1 — 2026-10-25
 
 - Make `tum-mcp update` download and validate the latest npm release before

package/README.md

@@ -3,7 +3,7 @@
 Connect your coding agent to Moodle, Artemis and Zulip. Read course content and
 build a private, source-backed study workspace. Unofficial; independent of TUM.
 
-**Latest release: [0.6.1](https://www.npmjs.com/package/@jamestesting888/tum-mcp).**
+**Package: [@jamestesting888/tum-mcp](https://www.npmjs.com/package/@jamestesting888/tum-mcp).**
 [Release notes](CHANGELOG.md).
 
 ## Agent setup
@@ -37,7 +37,7 @@ complete sign-in there. Only selected tabs open; Zulip needs no API key.
 Enable the [course and channel scopes](docs/tum-mcp.md#connections-and-scopes) you want to use.
 
 Choose a client with `--client`: `codex`, `claude`, `cursor` or `antigravity`.
-Setup configures MCP and installs all five skills; follow any activation or
+Setup configures MCP and installs all six skills; follow any activation or
 restart prompts. Use `generic` for manual MCP setup.
 
 For existing Cursor and Antigravity setups, run `tum-mcp update` to add the skills.
@@ -63,15 +63,16 @@ posting and read-state changes are unavailable.
 
 ### Skills and example requests
 
-The package includes five skills. Once you've chosen a course from
+The package includes six skills. Once you've chosen a course from
 your connections, try requests like these:
 
 | Skill | Use it to | Example request |
 | --- | --- | --- |
 | `read-content` | Read and explain course sources with citations | "Can you explain what we covered in last week's lecture?" |
-| `sync-study` | Create or refresh a course project | "Set up a study project for this course." |
+| `sync-course` | Create or refresh a course project | "Set up a study project for this course." |
 | `prepare-study` | Build lessons, flashcards and practice | "Make me a study website with flashcards and practice questions." |
-| `publish-study` | Put a prepared website on GitHub Pages | "Put my study site online so I can open it on my phone." |
+| `prepare-exercises` | Prepare optional hints, checks and worked solutions | "Help me work through this week's exercises in the same app." |
+| `publish-course` | Put a prepared website on GitHub Pages | "Put my study site online so I can open it on my phone." |
 | `audio-notes` | Save spoken lessons under `audio/` | "Turn this into audio notes I can listen to on the go." |
 
 Useful follow-ups in an existing project:
@@ -86,11 +87,12 @@ Client setup installs managed copies of the
 
 ### Recommended study flow
 
-1. **`sync-study`**: Set up a project for your course and collect its material.
+1. **`sync-course`**: Set up a project for your course and collect its material.
    Use it again when new material is available.
 2. **`prepare-study`**: Turn that material into a study website with explanations,
-   flashcards and practice questions.
-3. **`publish-study`** (optional): Put the website online so you can study on your
+   flashcards and practice questions. Use **`prepare-exercises`** for released sheets
+   with prepared interactive guidance. Both workspaces share one app; either can come first.
+3. **`publish-course`** (optional): Put the website online so you can study on your
    phone. Check the [publishing requirements](#publish-for-phone-access-optional) first.
 4. **`audio-notes`** (optional): Turn the prepared content into spoken lessons.
    Use them to revisit prepared topics while walking or commuting.
@@ -139,19 +141,20 @@ your project looks like this, with audio added when requested:
 
 ```text
 my-course/
-├── AGENTS.md                 Course overview and source index for your agent
+├── AGENTS.md                 Your rules and a short pointer to agent context
 ├── materials/
 │   ├── content/              Lectures, slides and reading
 │   ├── exercises/            Exercise sheets and practice material
 │   ├── exams/                Available exam and revision material
 │   └── other/                Announcements and course information
-├── study/
+├── app/
 │   ├── content.json          Lessons, flashcards and practice questions
 │   └── index.html            Your study website
 ├── audio/                    Optional audio notes
 │   ├── scripts/              Narration text
 │   └── tracks/               Audio lessons
-└── .study/
+└── .tum-mcp/
+    ├── course.md             Cited course orientation, rules and unknowns
     ├── state.json            Course identity and source versions
     └── comments.json         Passage comments, when added
 ```

package/docs/development.md

@@ -40,7 +40,7 @@ Each layer owns a different failure boundary:
 | Public upgrade | Earlier published versions, repair, ownership conflicts and removal |
 | Native platform | OS credential/ACL behavior; WSL Windows browser transport on both engines |
 
-Study integration fixtures build the real starter once, then copy it into a fresh
+Study integration fixtures build the private rich regression fixture once, then copy it into a fresh
 project for each test. Launcher tests only need an HTML entry point. Neither
 shares mutable course state. Client transaction tests use five small synthetic
 skills, including nested binary assets; full-pack export, migration and installed
@@ -56,7 +56,7 @@ CI runs macOS, Windows and Linux, plus both distribution engines on WSL 3.x.
 Consumer checks install the actual npm artifact, discover tools, build a study
 site and test available Chromium browsers with temporary profiles and synthetic
 pages. WSL verifies Windows browser transport. No live account is used.
-Upgrade checks cover public 0.6.0, client refresh, customized-file conflicts,
+Upgrade checks cover public 0.6.1, client refresh, customized-file conflicts,
 failed preparation, runtime repair and removal that preserves work/credentials.
 The package-lifecycle check uses a local synthetic registry and real isolated
 global npm prefixes to verify downloads, backend validation, replacement,
@@ -110,12 +110,14 @@ material remain untrusted data for the skill.
 
 ## Study renderer
 
-Author `study/content.json`. Formula blocks use LaTeX compiled locally into safe
+Author `app/content.json` and optional `app/exercises.json`; legacy `study/` remains supported. Formula blocks use LaTeX compiled locally into safe
 native MathML; legacy MathML remains accepted. Unit `path` labels group the outline
 without changing learning-progress revisions. Shared modules render all units;
 content changes do not require a framework or per-unit HTML.
 
-The distributed design/teaching/verification contracts live under
+Shared renderer assets live in `src/tum_mcp/bundled/course_app/site/`. The shipped
+component preview is deliberately minimal; richer learning pilots live in
+`tests/fixtures/course_app/`. The distributed design/teaching/verification contracts live under
 `src/tum_mcp/bundled/skills/prepare-study/references/`. Local agent notes and
 screenshots belong in ignored `docs/local/` or `.omo/`. Keep real course projects,
 session files, databases, downloads and environment files out of artifacts.

package/docs/setup.md

@@ -20,7 +20,7 @@ tum-mcp doctor
 
 Use `--client claude`, `cursor`, `antigravity`, or `generic` for another client.
 Codex needs the plugin enabled and a restart when prompted. Cursor and
-Antigravity setup installs all five skills and MCP configuration; restart each
+Antigravity setup installs all six skills and MCP configuration; restart each
 client afterward. Existing MCP-only setups gain the skills through `tum-mcp update`
 or another setup run. Generic setup writes configuration for manual installation.
 Setup preserves unrelated settings and refuses to

package/docs/study.md

@@ -1,13 +1,13 @@
 # Course study projects
 
-The five reading, study, audio and publishing skills ship with version **0.6.0**.
+Six focused skills cover source reading, course sync, Study preparation, Exercises preparation, audio and publishing.
 They run in your local agent, using the connected
 MCP tools to read course sources. The CLI validates and stores the resulting local
 files; it does not run an AI model.
 
 ## Publish a study website
 
-The optional `publish-study` skill makes a prepared site accessible from a phone
+The optional `publish-course` skill makes a prepared site accessible from a phone
 or another computer. Its GitHub repository is private; the Pages website is
 public. An eligible paid GitHub plan is required for Pages from private repositories.
 This workflow does not provide private website access. Review lesson text,
@@ -29,10 +29,16 @@ tum-mcp study publish --project PROJECT --public-site --repository OWNER/NAME
 
 Names use `study-<course>-<semester>` in lowercase with hyphens. A collision gets
 a stable course suffix; existing repositories are never made public. Settings in
-`.study/github.json` bind updates to that course, semester and repository. A
+`.tum-mcp/github.json` bind updates to that course, semester and repository. A
 failed setup retries the same saved repository rather than creating duplicates.
 
-Only the generated website renderer and lesson data are uploaded. Downloaded
+Study is the default hosted workspace, including for old settings. Exercise
+statements, hints and full solutions need explicit `--include-exercises` on the
+publish command after reviewing their public exposure. `--exclude-exercises`
+returns a combined site to Study only, using the same repository and URL. An
+Exercises-only site also requires explicit inclusion.
+
+Only the selected generated website renderer and data are uploaded. Downloaded
 originals, credentials, AGENTS.md, study inventory, passage comments, progress,
 audio and arbitrary files stay local. Git itself is not required: the publisher
 uses authenticated GitHub API calls through `gh`. Local publication settings do
@@ -63,7 +69,7 @@ and offline support are not included.
 
 ## Start with one course
 
-Use `sync-study` for both initial setup and later source updates. For a new project,
+Use `sync-course` for both initial setup and later source updates. For a new project,
 provide the course title and semester when known. The agent verifies
 its availability, resolves source IDs and asks about ambiguous mappings. A project
 cannot switch course or semester. Use a separate directory for another course.
@@ -86,18 +92,42 @@ pse-ws26/
     exams/                  Available revision material
     exercises/              Released statements and practice references
     other/                  Announcements and course information
-  .study/state.json         Course binding, source versions and coverage
-  study/                    Optional interactive study website
+  .tum-mcp/
+    course.md               Cited course structure, logistics, rules and unknowns
+    state.json              Course binding, source versions and coverage
+    notes/                  Detailed course/agent notes when needed
+  app/                      Shared Study and Exercises website
+    content.json            Optional source-backed Study content
+    exercises.json          Optional prepared exercise guidance
   audio/                    Optional category audio derived from the prepared website
 ```
 
-`AGENTS.md` contains a concise prerequisite/notation map, verified assessment facts,
-source locations, coverage and next actions. Detailed source content stays in
-materials. Existing user instructions are preserved; source text is untrusted data.
+`AGENTS.md` retains user rules and points agents to `.tum-mcp/course.md`. That short
+handbook explains the course's goals, lectures/tutorials, weekly work and platforms,
+assessment/bonus conditions, communication and preparation map. Claims carry source
+links/locators and checked dates; unknowns and conflicting announcements stay visible.
+Detailed source content remains in materials/. All TUM MCP course state, plans and
+agent notes live under .tum-mcp/.
+
+`sync-course` reads the relevant authoritative sources and maintains the handbook;
+the CLI scaffolds it without pretending to understand the course. Its review receipt
+records the local generation and hashes of supporting sources. `study inspect`
+reports changed supporting sources and coverage gaps so refreshes can focus on
+affected claims. A reviewed local snapshot does not establish live freshness or
+complete understanding. See the bundled sync-course context reference for the full
+source-review workflow.
+
+To rename existing private `.study/` state explicitly, close other course processes
+and run `tum-mcp study upgrade PROJECT`. It preserves unknown private files,
+comments, publication settings and the full old root instructions as
+`.tum-mcp/legacy-AGENTS.md`. Course identity, materials and browser progress stay the
+same. Existing legacy state remains readable until upgrade; two state folders are
+a conflict to reconcile, never silently merged. This differs from the web-folder
+upgrade below.
 
 ## State-based workflow
 
-`sync-study` starts with `tum-mcp study status PROJECT`, a read-only local check:
+`sync-course` starts with `tum-mcp study status PROJECT`, a read-only local check:
 
 | Mode | Action |
 | --- | --- |
@@ -112,7 +142,7 @@ The underlying `study init` and `study sync` commands remain separate.
 
 ## Keep it current
 
-Ask `sync-study` to compare the project with connected upstream sources. It
+Ask `sync-course` to compare the project with connected upstream sources. It
 reuses the saved course, semester, source IDs and reliable revisions. It retrieves
 changed material and updates course knowledge. Incomplete listings never imply withdrawal. Withdrawn sources
 keep their local originals; edited or deleted managed files are reported for review.
@@ -127,10 +157,9 @@ restores files when possible and reports any remaining conflict.
 
 ## Prepare the website
 
-Ask `prepare-study` to create or extend `study/`. Units follow the course's
+Ask `prepare-study` to create or extend the Study workspace in `app/`. Units follow the course's
 lecture/week sequence when useful, or use consistent topics. For a single course, use a flat list or one category level followed by topics,
-including several topics in one week. The multi-area demo also exercises deeper
-legacy hierarchies. Every unit has:
+including several topics in one week. Every unit has:
 
 - A concise explanation with source links, assumptions and worked examples.
 - Editable LaTeX formulas and inline variables, diagrams, code or comparison tables where they explain the concept.
@@ -173,7 +202,7 @@ glossaries, cards, questions and feedback. Code and dollar signs stay literal.
 
 Select text in Content, Flashcards or Practice, then click **Comment** to record what is unclear.
 You can also use Ctrl/Command+Alt+M after selecting text. The local preview saves
-notes in `.study/comments.json`, separately from learning progress. Click a
+notes in `.tum-mcp/comments.json`, separately from learning progress. Click a
 numbered passage marker or highlighted text to open its notes beside the quote.
 Markers sit beside section headings or the current card/question position.
 Notes can be edited, resolved or reopened; changed passages retain their original quotes.
@@ -186,7 +215,7 @@ automatically while the preview is open. Your draft is kept if a note changes
 elsewhere; choose Use latest or Keep mine before saving. Reload after the agent
 rebuilds the teaching content.
 
-Content lives in `study/content.json`; shared renderer modules and CSS keep the
+Content lives in `app/content.json`; shared renderer modules and CSS keep the
 site extensible. Source hashes identify affected units. A stale source stops a
 build until the explanation is reviewed. Unchanged units retain their revision;
 revised questions receive separate progress. Customized templates are preserved
@@ -210,11 +239,44 @@ or an unattended preview, use `tum-mcp study serve ./pse-ws26 --port 8765`.
 If port 8765 is busy, stop the other preview or choose `tum-mcp study --port 8766`.
 Keep the same address and port between sessions so browser progress remains available.
 
-The preview binds `127.0.0.1`, serves `study/` and saves comments through a bounded
+The preview binds `127.0.0.1`, serves `app/` (or the existing legacy `study/`) and saves comments through a bounded
 same-origin endpoint. It makes no campus requests.
 No course credentials are copied into the website. Browser storage holds progress
 locally. Nothing is published by these commands.
 
+## Prepare weekly exercises
+
+Ask `prepare-exercises` to prepare released weekly sheets in the same app. Study
+and Exercises can be prepared in either order. When both exist, a selector at the bottom of the sidebar
+switches workspaces and remembers the current place. On phones it lives inside the
+open course outline; there is no second switch in the reading area. Exercises are
+listed directly under sheets, optionally grouped by category.
+
+The original statement and subparts come first. Students can solve on paper, mark
+an exercise Reviewed, reveal a worked solution directly, or open **Guidance**.
+Prepared guidance offers one conceptual step, requested hints and specific repair
+feedback. Numeric checks state units/tolerance; choice checks have four options.
+Fillable tables check numeric cells and explicit text variants individually. Graph
+questions support node/edge selections and ordered paths with a visible diagram.
+Line graphs allow sample-point placement, coordinate edits and keyboard adjustment.
+Long math and programming work use saved writing areas and prepared rubrics; code
+is never executed, and symbolic work, proofs and programs are not automatically
+graded. Arbitrary graph drawing can use paper and rubric comparison. Typing, hints and step-by-step guidance are optional. Reviewed records an
+action, not mastery or an assessment result.
+
+Drafts and assistance stay in this browser. Editing a checked answer clears its
+verdict. Semantic changes start fresh progress for only that exercise, while retaining older
+browser records; source-hash review alone preserves progress.
+Reset on each workspace home affects only that workspace. Exercise passage comments
+use the existing private comment service; hosted exports do not expose it.
+
+Existing `study/` projects continue to work. New projects use `app/`. To upgrade a
+verified legacy layout explicitly, run `tum-mcp study build PROJECT --upgrade-layout`.
+It keeps the original tree at `.tum-mcp/layout-backup/`, preserves the course identity,
+learning revisions, comments, settings and personal files, and stops on customized
+generated files, an occupied backup or two layouts. Repeating a completed upgrade
+is a no-op. Do not create `app/` alongside an existing `study/` by hand.
+
 ## Create and maintain audio notes
 
 Use `prepare-study` to author the interactive course, then ask `audio-notes` to
@@ -225,7 +287,7 @@ Create audio notes from this prepared study website, one file per category.
 Keep course outputs under audio/; prefer free ElevenLabs with local Kokoro fallback.
 ```
 
-Audio Notes reads `study/content.json`, retaining the course's language, examples,
+Audio Notes reads `app/content.json`, retaining the course's language, examples,
 assumptions and limitations. It turns tables, formulas, code and diagram sequences
 into explanations that work without a screen. It does not independently research
 the course or create new subject matter. An audio-only request reuses the prepared
@@ -287,29 +349,32 @@ material with the previous verified coverage. This is an agent skill, not a new
 
 ## Packaged app template
 
-The complete web-app template is packaged with `prepare-study` in `assets/site/`.
+The shared web-app template is packaged in `bundled/course_app/site/`, separately from skill instructions.
 It includes the shell, navigation, flip cards, practice, diagrams and styling.
-Agents author course content in `study/content.json`; `study build` installs the
+Agents author course content in `app/content.json`; `study build` installs the
 shared template, preserves customized files and checks sources. This keeps new
 course sites consistent without rebuilding the interface. `tum-mcp study template`
 shows the bundled files and their combined revision for reproducible development.
 
-## Try the synthetic example
+## Try the component template
 
 After installing a locally built development artifact:
 
 ```sh
-tum-mcp study demo ./algorithms-demo
-tum-mcp study serve ./algorithms-demo
+tum-mcp study demo ./component-preview
+tum-mcp study serve ./component-preview
 ```
 
-This creates a clearly labelled synthetic course on graphs, BFS and DFS, including
-LaTeX rendered as native MathML, a step-through graph, comparison tables, flashcards and practice.
+This creates one small Study unit and one exercise covering prose, code, tables,
+formulas, graph/process diagrams, cards and response controls. It is a reusable
+component template, not necessarily a good teaching or question-authoring example.
+Actual course authoring follows reviewed sources and the preparation skills. Rich
+learning pilots stay in private test fixtures.
 It uses no campus account. An existing edited demo is preserved.
 
 ## Local helper inputs
 
-Agents use `tum-mcp study schema snapshot` and `tum-mcp study schema content` for
+Agents use `tum-mcp study schema snapshot`, `schema content` and `schema exercises` for
 validated input schemas. After authenticated tools verify availability, the agent
 stages a source snapshot with exact course identity, coverage and resource revisions.
 The helper does not authenticate the snapshot or grant any campus access itself.

package/docs/tum-mcp.md

@@ -2,7 +2,7 @@
 
 Package: `@jamestesting888/tum-mcp`, CLI: `tum-mcp`, backend: Python 3.13.
 Development version **0.6.1 (unreleased)** adds npm package management to the
-read-only course retrieval and five local study workflows in 0.6.0.
+read-only course retrieval and six local course workflows.
 
 ## Current capabilities
 
@@ -162,10 +162,11 @@ in JSON for troubleshooting. Default diagnostics do not create state folders.
 
 ## Study workflows
 
-`read-content` retrieves course information across the three websites. `sync-study`
+`read-content` retrieves course information across the three websites. `sync-course`
 uses read-only local status to initialize an explicitly chosen available course or
 reconcile an existing project. Incomplete state is preserved for recovery.
-`prepare-study` creates or extends its local interactive site. See the
+`prepare-study` authors lessons; `prepare-exercises` authors guided released sheets
+in the same local app. See the
 [study guide](study.md) for examples, state structure and helper commands.
 
 One project holds one course. Source revisions, coverage and course knowledge
@@ -182,13 +183,13 @@ writing files with activation.
 
 The Codex adapter uses a contained Node launcher to pin the managed Python in
 isolated mode; portable stdio manifests require a bare or contained executable.
-The shipped pack contains five skills: `read-content`, `sync-study`,
-`prepare-study`, `audio-notes` and `publish-study`. Website-specific retrieval
+The shipped pack contains six skills: `read-content`, `sync-course`,
+`prepare-study`, `prepare-exercises`, `audio-notes` and `publish-course`. Website-specific retrieval
 guidance is loaded from references within read-content. Teaching, schema and design contracts live
 with prepare-study; the renderer and synthetic example ship as reusable assets.
 Audio Notes converts prepared content into category tracks and maintains coverage,
 scripts, voice settings, candidates and archives under the course's `audio/` root.
-Publish Study uses host GitHub CLI authentication to create a private repository
+Publish Course uses host GitHub CLI authentication to create a private repository
 and a public Pages website after explicit publication consent. It chooses a course
 and semester name, updates the same site after successful study builds, and shows
 the hosted URL alongside the local launcher URL. No tokens or original course
@@ -203,7 +204,7 @@ routing quality is a separate evaluation from structural and discovery checks.
 Claude's invocation metadata follows each workflow's selected policy; automatic
 selection is enabled by default and never grants permission for a mutation.
 
-`setup --client cursor` writes `~/.cursor/mcp.json` and installs all five skills
+`setup --client cursor` writes `~/.cursor/mcp.json` and installs all six skills
 under `~/.cursor/skills/`.
 `setup --client antigravity` installs the same skills under `~/.gemini/config/skills/`
 and writes `~/.gemini/config/mcp_config.json`; an existing

package/npm/backend/manifest.json

@@ -1,5 +1,5 @@
 {
-  "wheel": "tum_mcp-0.6.1-py3-none-any.whl",
-  "wheelSha256": "59ecf435716e6c0ab68ed9720f2c137b3236f64dd5e962db4c3bf82b76c45ba2",
+  "wheel": "tum_mcp-0.7.0-py3-none-any.whl",
+  "wheelSha256": "dabe306ea1695fa03fa119b2673cc93c0ee705b34ebabc6674958fe77f5757a6",
   "requirementsSha256": "25f9efa7a4ffb0b97abcfeb9d4706d04808273ab1b35abcfaa1ef0b66e87591b"
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jamestesting888/tum-mcp",
-  "version": "0.6.1",
+  "version": "0.7.0",
   "description": "Read-only TUM Moodle, Artemis and Zulip integration with source-backed study workflows",
   "license": "MIT",
   "type": "module",