@jamestesting888/tum-mcp 0.6.0 → 0.7.0

package/CHANGELOG.md

@@ -1,5 +1,43 @@
 # 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
+  replacing the invoked installation and refreshing configured clients.
+  Preserve newer installed versions; `--local` refreshes without contacting npm.
+- Make `tum-mcp uninstall` remove managed client setup and the npm package in
+  one command. Keep saved data by default; stop package removal on conflicts.
+  Client-only removal retains npm, and `--keep-package` supports managed cleanup.
+- Run npm through Node on all platforms, serialize package operations, and use
+  an external worker while Windows replaces package files.
+- Test actual global installations against a private synthetic registry, including
+  failed downloads/preparation/replacement, customized files, and data preservation.
+
 ## 0.6.0 — 2026-10-25
 
 - Merge course setup and updates into `sync-study`, with recovery for incomplete
@@ -20,8 +58,8 @@
   Reuse isolated test fixtures,
   retain native/platform coverage and expose slow tests and failures in CI.
 - Preserve Windows CRLF study instructions through repeated synchronization.
-- Group Artemis and Zulip implementation by provider, retaining read-only campus
-  tools and Moodle compatibility. Fix OCR with aliased macOS temporary paths.
+- Group Artemis and Zulip implementation by provider, retaining read-only
+  course tools. Fix OCR with aliased macOS temporary paths.
 
 Upgrading does not rebuild personal study sites automatically. Ask your agent to
 update the prepared website; customized renderer files are preserved for review.

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.0](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
@@ -36,13 +36,9 @@ Select services with **Space**, then **Enter**. Choose an installed browser and
 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.
 
-| Client | Setup |
-| --- | --- |
-| Codex | `--client codex` · plugin and skills; enable/restart when prompted |
-| Claude Code | `--client claude` · MCP registration and skills |
-| Cursor | `--client cursor` · MCP registration and all five skills; restart |
-| Google Antigravity | `--client antigravity` · MCP registration and all five skills; restart |
-| Other MCP clients | `--client generic` · configuration for manual installation |
+Choose a client with `--client`: `codex`, `claude`, `cursor` or `antigravity`.
+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.
 Updates and uninstall preserve customized files and report them for review.
@@ -51,7 +47,7 @@ Supports macOS, Windows, glibc Linux x86_64/ARM64 and WSL 3.x. In WSL, sign-in
 opens a Windows browser. Add `--host windows` to setup for a Windows client that
 uses the WSL backend. [Browser and WSL setup](docs/setup.md#wsl).
 
-Setup supplies a private Python runtime. New connections use encrypted local
+Setup supplies a private Python runtime. Connections use encrypted local
 files and need no native keyring, Git or Docker.
 
 ## Read and study
@@ -67,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:
@@ -90,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.
@@ -143,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
 ```
@@ -167,11 +166,13 @@ stay local. Study progress is saved in your browser.
 ## Update
 
 ```sh
-npm install --global @jamestesting888/tum-mcp@latest
 tum-mcp update
 ```
 
-`update` prepares the invoked package's runtime and refreshes configured clients.
+`update` downloads the latest release, validates its backend, installs it in the
+same npm location and refreshes configured clients. It never downgrades a newer
+installation. Use `tum-mcp update --local` to refresh the installed version without checking npm.
+From 0.6.0 or earlier, upgrade the npm package once to obtain this command.
 Sessions, scopes and downloads carry forward. User-edited entries and skills are
 preserved and reported for review. Reload the client; refresh its cached plugin
 if needed. Study sites are updated separately through the study workflows.
@@ -179,14 +180,14 @@ if needed. Study sites are updated separately through the study workflows.
 ## Remove
 
 ```sh
-tum-mcp uninstall --all
-npm uninstall --global @jamestesting888/tum-mcp
+tum-mcp uninstall
 ```
 
-Managed registrations and unchanged skills are removed. Settings, sessions,
+The npm package, managed registrations and unchanged skills are removed. Settings, sessions,
 downloads and study projects are preserved. After closing clients, add
 `--purge-runtime` to remove generated runtimes or `--forget-credentials` to
-remove saved local sessions and historical Git tokens. [Removal details](docs/setup.md#update-and-remove).
+remove saved local credentials. [Removal details](docs/setup.md#update-and-remove).
+Use `--client NAME` to remove just one client, or `--keep-package` to retain npm.
 
 [Guide](docs/tum-mcp.md) · [Setup](docs/setup.md) · [Study workflows](docs/study.md) · [Development](docs/development.md)
 

package/docs/development.md

@@ -2,8 +2,6 @@
 
 The npm package is the distribution. Its wheel contains one Python package,
 `src/tum_mcp/`, with peer `moodle/`, `artemis/` and `zulip/` provider packages.
-The retired standalone Moodle plugin and its checkout installer are no longer
-maintained.
 Client adapters still generate the configuration each host needs.
 
 ## Checks
@@ -19,6 +17,7 @@ npm test
 npm pack --ignore-scripts --pack-destination dist
 npm run test:consumer
 npm run test:upgrade
+npm run test:package-lifecycle
 ```
 
 Python 3.13 is the managed runtime. Install Tesseract for OCR tests. Default tests
@@ -41,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
@@ -57,8 +56,11 @@ 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.4.1/0.5.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,
+failure ordering and one-command removal. It does not publish a test release.
 All five jobs must pass on the exact pushed commit before completion is claimed.
 
 Live Moodle checks are opt-in: `TUM_MOODLE_LIVE=1 uv run pytest tests/live -q`.
@@ -97,14 +99,7 @@ tag and artifact integrity before pushing the release documentation.
 
 Client setup installs managed copies of the repository's skills; those copies are
 outputs, not another source tree. Use `skills customize` for a personal override.
-The Codex adapter generates a small host plugin because that client uses it to
-load skills and MCP together; it is separate from the removed top-level Moodle
-plugin distribution.
-
-Keep Moodle's existing native-store service/account identity, session paths and
-download locations stable during migrations. Environment variable names and the
-`tum-moodle` CLI alias remain compatible; its implementation now resides inside
-`tum_mcp.moodle`. No automatic native-store secret extraction occurs.
+The Codex adapter generates a small host plugin to load skills and MCP together.
 
 Extraction uses bounded subprocesses. POSIX enforces CPU/process-group limits;
 Windows terminates the worker and observed children. Study imports and preview
@@ -115,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
@@ -35,11 +35,10 @@ Run **`tum-mcp connect`**, with no arguments, in an interactive terminal:
 3. Complete TUM sign-in/MFA in the opened window. Only selected service tabs open.
 4. Return to the terminal for the saved-connection result.
 
-Moodle uses exactly the same selector and storage flow as Artemis and Zulip.
-No API key or Keychain prompt is needed. A temporary browser profile keeps the
-connection separate from your everyday browser. Ctrl+C closes it and preserves
+All three services use the same sign-in and encrypted session storage flow.
+No API key or native credential-store prompt is needed. A temporary browser
+profile keeps the connection separate from your everyday browser. Ctrl+C closes it and preserves
 connections that already completed. A dumb terminal uses numbered prompts.
-Old service arguments and `--service`/`--auth` flags are no longer accepted.
 
 Chrome, Edge, Brave, Chromium, Vivaldi and Opera are detected in their standard
 locations. Selected preview channels and Opera GX are detected where installed.
@@ -113,19 +112,25 @@ browser discovery still requires functioning interop.
 Sessions are encrypted with owner-restricted local key files. This avoids native
 credential-store prompts, but anyone obtaining both key and ciphertext can
 decrypt them. [Storage locations and recovery](tum-mcp.md#connections-and-scopes)
-explain migration and backup. Existing Moodle data and downloads are preserved.
+explain where sessions are saved and how to back them up.
 
 ## Update and remove
 
 ```sh
-npm install --global @jamestesting888/tum-mcp@latest
 tum-mcp update
 ```
 
-`update` activates the backend bundled in the invoked npm package and refreshes
-previously configured clients. It does not fetch a newer npm version itself,
-connect services, change scopes or register additional clients. `setup --client
-NAME` explicitly registers one client and can also refresh that client's managed
+From 0.6.1, `update` retrieves the latest npm release, validates its backend in a
+temporary installation, replaces the invoked package and refreshes previously
+configured clients. It preserves the installation prefix and global/local mode.
+It does not connect services, change scopes or register additional clients.
+It never downgrades a newer installation. `update --local` skips npm and repairs
+or refreshes the installed version. Source/pinned builds use this local mode;
+temporary npx and linked source installations are not replaced automatically.
+Automatic replacement also stops if the package directory contains configured
+sessions, downloads or course work; move that data outside the package first.
+For 0.6.0 and earlier, first install the newer npm package once.
+`setup --client NAME` explicitly registers one client and can also refresh that client's managed
 files. WSL Windows registrations keep their distribution/user/data paths.
 
 Ownership receipts track the entries and files installed by TUM MCP. Unchanged
@@ -138,57 +143,40 @@ not selected, and a damaged runtime is repaired into a fresh generation. A newer
 managed client is not silently downgraded by an older package; intentional
 rollback starts by unregistering that client, then registering the reviewed version.
 
-0.4.1/0.5.0 installations without receipts are adopted only after matching their
-retained runtime's canonical client output. The seven former workflow skills and the three website skills are replaced by
-`read-content`, `sync-study` and `prepare-study`; `audio-notes` adds
-spoken lessons derived from the prepared website. Personal overrides
-under retired names remain in the config `skills/` directory; review and merge
-retrieval guidance into `read-content` before exporting a replacement pack.
 Reload MCP servers in Cursor/Antigravity, restart Claude as appropriate, and
 update/reinstall TUM MCP from the personal source in Codex Plugins if its cached
 copy still shows the older skills. Writing source files does not activate a host.
 
 Remove a single client with `tum-mcp uninstall --client cursor` (replace the
 client as needed; add `--host windows` from WSL for a Windows client). To remove
-all managed registrations before uninstalling npm:
+the npm package and all managed registrations:
 
 ```sh
-tum-mcp uninstall --all
-npm uninstall --global @jamestesting888/tum-mcp
+tum-mcp uninstall
 ```
 
 Custom edits and user-added files are preserved. Codex's local source/catalog
 entry can be removed, but its cached/active plugin must also be removed or
-disabled through Codex Plugins. No npm uninstall hook deletes user data.
+disabled through Codex Plugins. Package removal runs only after successful
+client cleanup; conflicts preserve npm so you can review and retry. `--all`
+is accepted explicitly, and `--keep-package` removes client setup without npm.
+No npm lifecycle hook performs cleanup or reads credentials.
 
 For explicit cleanup, **close coding clients first**, then run:
 
 ```sh
-tum-mcp uninstall --all --purge-runtime --forget-credentials
-npm uninstall --global @jamestesting888/tum-mcp
+tum-mcp uninstall --purge-runtime --forget-credentials
 ```
 
 `--purge-runtime` deletes verified managed runtime generations after the Python
 helper exits, and removes unchanged managed bootstrap/browser-driver caches.
 Active tracked backends or unrecognized runtime files stop automatic removal.
 Paths overlapping configured assignment work, downloads or Moodle data are
-protected. `--forget-credentials` removes local encrypted service sessions, keys
-and participation Git tokens; it does not revoke remote credentials. Native
-Keychain/Credential Manager/Secret Service records and legacy Moodle sessions
-stay intact. Settings, custom skills, course cache, downloads and assignment
-work are retained by these commands. No command recursively deletes the campus
+protected. `--forget-credentials` removes saved local credentials and session
+keys; it does not revoke remote credentials. Settings, custom skills, course
+cache, downloads and assignment work are retained by these commands.
+No command recursively deletes the campus
 data root. Course audio and optional shared speech models/runtimes also remain.
 Remove a shared speech cache only when explicitly requested and no other course
 needs it; its host paths are documented in the audio skill. If removal is
-interrupted, run npm `setup` to recover before reuse.
-
-## Existing Moodle-only installations
-
-The older `tum-moodle` commands and sixteen `moodle_*` tools remain compatible.
-The separate source/plugin installer retains its original native credential
-store: macOS Keychain, Windows Credential Manager, or Linux Secret Service.
-Its native-store identity, existing session paths and downloads remain intact.
-The combined `tum-mcp serve` uses local-file storage and directs all login
-requests to `tum-mcp connect`. Reconnect once through that selector to create the
-new session; no automatic extraction of older native-store secrets occurs.
-Disable the older plugin when activating TUM MCP to avoid duplicate tools.
+interrupted, run `tum-mcp setup --client NAME` to recover before reuse.

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

@@ -1,19 +1,19 @@
 # TUM MCP guide
 
 Package: `@jamestesting888/tum-mcp`, CLI: `tum-mcp`, backend: Python 3.13.
-Version **0.6.0** provides read-only course retrieval and five local study workflows.
+Development version **0.6.1 (unreleased)** adds npm package management to the
+read-only course retrieval and six local course workflows.
 
 ## Current capabilities
 
-All sixteen `moodle_*` compatibility tools remain available, including materials,
-announcements, forums and explicitly scoped private-record reads. Artemis adds
+The sixteen `moodle_*` tools provide materials, announcements, forums and
+explicitly scoped private-record reads. Artemis adds
 available-course metadata, lectures and learning units, student PDF attachments,
 released non-quiz statements and permitted exact-commit feedback. Zulip provides
 scoped channel/topic search and cited discussion reads.
 
 Website access is read-only. There are no public exercise workspace, test-run,
-submission, start, deployment, rebuild or push workflows. The retained internal
-remote gate rejects every action even if an old verification flag is enabled.
+submission, start, deployment, rebuild or push workflows.
 Local downloads, source inventories, study-site builds and checkpoint storage
 are local operations; they do not post, submit or mark campus content as read.
 
@@ -67,22 +67,19 @@ and Python 3.13.15; an existing matching uv, including the verified cached downl
 is reused. Source checkouts and system
 Python are unnecessary for consumers. Supported bootstrap targets are macOS
 arm64/x64, Windows arm64/x64, and glibc Linux arm64/x64; hands-on verification is
-recorded separately. New campus sessions use permission-restricted local keys and need no Secret Service.
-Clean consumer bootstrap, idempotent setup, diagnostics, and skill validation
-passed on macOS ARM64 and in Linux ARM64 and x86_64 containers. The x86_64 check
-ran through Docker amd64 emulation on an ARM64 Mac; packaged MCP protocol checks
-and an encrypted credential round trip through a real GNOME Secret Service in an
-isolated D-Bus session also passed. Real Linux desktop browser sign-in, macOS x64,
-and Windows hands-on checks remain open. New storage and terminal behavior need
-the current checkout’s test evidence; earlier native-store results do not certify them. The installer targets glibc Linux
-x86_64/amd64 and aarch64/ARM64.
-
-`update` prepares the backend bundled in the invoked package, refreshes
-previously configured clients and preserves older runtime generations.
+recorded separately. Campus sessions use permission-restricted local keys.
+CI checks clean installation, updates, removal, MCP discovery and synthetic
+browser workflows on macOS, Windows, Linux and both WSL engines. See the
+[development guide](development.md#checks) for the verification layers.
+
+`update` downloads and validates the latest release, replaces the invoked npm
+installation and refreshes previously configured clients. `update --local`
+refreshes the installed version without npm. Retained runtimes keep pinned
+clients working, and newer installed versions are not silently downgraded.
 [Update and removal behavior](setup.md#update-and-remove) covers ownership
-receipts, legacy adoption, conflict handling and explicit cleanup. To obtain a newer public package after publication,
-invoke its reviewed version explicitly. It does not publish a release or replace
-customized client skills silently. If interrupted setup leaves `setup.lock`,
+receipts, conflict handling and explicit cleanup. `uninstall` removes managed
+clients and npm; `--client NAME` or `--keep-package` retains the package.
+Customized files and saved data are preserved. If interrupted setup leaves `setup.lock`,
 confirm that no setup process is running before removing that directory locally.
 An invalid or incomplete runtime is never selected for serving. Failed validation
 clears its ready marker so explicit setup can rebuild it; older runtimes remain
@@ -108,10 +105,9 @@ tum-mcp scope zulip ACCOUNT_ID --channel CHANNEL_ID
 `connect` takes no arguments or connection options. Move with up/down, toggle
 services with Space, and press Enter. Choose a browser when more than one is
 installed. Only selected tabs open in one temporary browser context. Moodle,
-Artemis and Zulip all follow this flow; no separate Moodle login is needed.
+Artemis and Zulip all follow this flow.
 Sign-in/MFA stays in the browser. `TERM=dumb` uses numbered prompts. Ctrl+C
-cancels and retains completed connections. Old service/campus arguments and
-`--service`/`--auth` flags are rejected before any browser opens.
+cancels and retains completed connections.
 
 Detection covers Chrome, Edge, Brave, Chromium, Vivaldi, Opera and selected
 preview channels. Set `TUM_MCP_BROWSER` to an executable path for another
@@ -121,41 +117,30 @@ Only service-owned cookies are saved; identity-provider cookies are discarded
 when the temporary browser closes. Existing browser profiles are never imported.
 
 Zulip uses its read-only `/json/` routes with the browser session; no API key is
-required. Reconnect through the same selector when a session expires. Existing
-API-key records remain readable for compatibility, but key entry is not part of
-onboarding. See [Zulip's dispatcher](https://github.com/zulip/zulip/blob/12.0/zerver/lib/rest.py).
+required. Reconnect through the same selector when a session expires.
+See [Zulip's dispatcher](https://github.com/zulip/zulip/blob/12.0/zerver/lib/rest.py).
 Existing scopes survive reconnection; new identities start with empty scopes.
 Private Zulip channels require `--private-channel ID` as well as `--channel ID`.
 `--sensitive` enables own Artemis participation/feedback reads. It grants no
 website mutation or local execution permission.
 
 Settings live outside the installed package in `TUMMCP/config/preferences.json`.
-The default data directory is beside the legacy `TUMMoodle` directory on each OS.
-Existing Moodle data and its native-store identity are retained in place. New
-campus connections deliberately do not read or migrate native-store secrets;
-reconnect each service once to use local-file storage. The combined MCP process
-uses that storage for all `moodle_*` compatibility tools. The separate Moodle-only
-installer keeps its native-store default.
-Historical Git credentials remain local data for legacy cleanup; the current
-package provides no assignment Git workflow.
-
-New Moodle sessions live under `TUMMoodle/local-session/`; campus credentials live
-under `TUMMCP/credentials/local/`. Each directory has an independent `session.key`.
+Moodle sessions live under `TUMMoodle/local-session/`; Artemis and Zulip credentials
+live under `TUMMCP/credentials/local/`. Each directory has an independent `session.key`.
 Encrypted records and keys have owner-only permissions: 0700 directories / 0600
 keys on POSIX; protected current-user DACLs on Windows through PowerShell. No
-administrator privileges are requested. This avoids Keychain/Secret Service
+administrator privileges are requested. This avoids native credential-store
 prompts but protects less than a native store. A copy of both ciphertext and key
 is sufficient to decrypt a session. Do not share, sync publicly, or package them.
 
 Missing or damaged keys fail closed. Restore the matching key from a private
 backup. To start fresh, stop clients and move the affected **local storage folder**
-to a private backup before reconnecting; this also resets its stored Git tokens.
-Never remove the legacy Moodle directory or downloads to repair a login.
-Native-store records remain available to the older installation for rollback.
+to a private backup before reconnecting. Keep downloaded course materials when
+repairing a login.
 
 Zulip message text is retrieved live and is not persisted. Retrieved excerpts may
-be transmitted to the coding agent's configured AI provider. Moodle's existing
-document cache retains its documented plaintext/expiry behavior.
+be transmitted to the coding agent's configured AI provider. Moodle caches
+documents and extracted text locally in plaintext.
 
 Course nicknames can be mapped in `mappings` using explicit per-service IDs.
 The tools resolve one exact mapping; ambiguity never grants broader access.
@@ -177,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
@@ -191,21 +177,19 @@ progress are preserved during package updates/removal.
 ## Client and skill setup
 
 `setup --client codex` prepares a local plugin/marketplace entry using the
-portable Agent Plugins schemas. Enable it in
-Codex Plugins, restart, and verify real tool and skill loading. Disable the legacy
-TUM Moodle plugin when switching so duplicate tools/skills are not active.
-The old installation remains available for rollback. Setup reports required UI
-steps and never equates writing files with activation.
+portable Agent Plugins schemas. Enable it in Codex Plugins, restart, and verify
+real tool and skill loading. Setup reports required UI steps and never equates
+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
@@ -220,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
@@ -291,5 +275,5 @@ it is described as verified. Test data and public fixtures are synthetic. Real
 course material, local agent notes and screenshots stay under ignored local paths.
 Maintainer checks include a reviewed tarball inventory, integrity checks and an
 isolated consumer install. Never publish or stage npm packages as a test. Registry
-publication requires separate user authorization and remains paused for this work.
+publication is an explicit maintainer action.
 `tum-mcp status` reports registry state as `not_checked`; it reads local configuration.

package/npm/backend/manifest.json

@@ -1,5 +1,5 @@
 {
-  "wheel": "tum_mcp-0.6.0-py3-none-any.whl",
-  "wheelSha256": "8437422504920753d1d6781cd87c57065cfbb8c0630ff0c5fd1de237b2d00426",
+  "wheel": "tum_mcp-0.7.0-py3-none-any.whl",
+  "wheelSha256": "dabe306ea1695fa03fa119b2673cc93c0ee705b34ebabc6674958fe77f5757a6",
   "requirementsSha256": "25f9efa7a4ffb0b97abcfeb9d4706d04808273ab1b35abcfaa1ef0b66e87591b"
 }

package/npm/lock.mjs

@@ -0,0 +1,43 @@
+import { randomUUID } from 'node:crypto';
+import { readFileSync } from 'node:fs';
+import { mkdir, rename, rm, rmdir, writeFile } from 'node:fs/promises';
+import { hostname } from 'node:os';
+import { join } from 'node:path';
+
+export async function acquireLock(root, name = 'setup') {
+  await mkdir(root, { recursive: true, mode: 0o700 });
+  const lock = join(root, `${name}.lock`);
+  const owner = { pid: process.pid, host: hostname(), nonce: randomUUID() };
+  const guard = join(root, `${name}.claim`);
+  try { await mkdir(guard, { mode: 0o700 }); }
+  catch { throw new Error(`Another ${name} is claiming the lock. Retry; an interrupted ${name}.claim needs local review.`); }
+  try {
+    try { await mkdir(lock, { mode: 0o700 }); }
+    catch (error) {
+      if (error.code !== 'EEXIST') throw error;
+      let previous;
+      try { previous = JSON.parse(readFileSync(join(lock, 'owner.json'), 'utf8')); }
+      catch { throw new Error(`${name} lock has no readable owner. Confirm no operation is running before removing ${name}.lock.`); }
+      if (!Number.isSafeInteger(previous.pid) || previous.pid <= 0 || previous.host !== hostname()) {
+        throw new Error(`${name} lock belongs to an unknown owner; preserve it for local review.`);
+      }
+      let alive = true;
+      try { process.kill(previous.pid, 0); }
+      catch (failure) { if (failure.code === 'ESRCH') alive = false; }
+      if (alive) throw new Error(`Another ${name} is running; retry when it finishes.`);
+      const abandoned = `${lock}.${randomUUID()}.abandoned`;
+      await rename(lock, abandoned);
+      await rm(abandoned, { recursive: true, force: true });
+      try { await mkdir(lock, { mode: 0o700 }); }
+      catch { throw new Error(`Another ${name} acquired the lock; retry when it finishes.`); }
+    }
+    const temporary = join(lock, `${owner.nonce}.pending`);
+    await writeFile(temporary, JSON.stringify(owner), { mode: 0o600, flag: 'wx' });
+    await rename(temporary, join(lock, 'owner.json'));
+  } finally { await rmdir(guard); }
+  return async () => {
+    const current = JSON.parse(readFileSync(join(lock, 'owner.json'), 'utf8'));
+    if (current.nonce !== owner.nonce) throw new Error(`${name} lock ownership changed; it was preserved.`);
+    await rm(lock, { recursive: true, force: true });
+  };
+}

package/npm/npm-command.mjs

@@ -0,0 +1,96 @@
+import { spawnSync } from 'node:child_process';
+import { existsSync, readFileSync, realpathSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { delimiter, dirname, join, basename, resolve, relative, isAbsolute, sep } from 'node:path';
+
+export const packageName = '@jamestesting888/tum-mcp';
+
+function canonical(value) {
+  let path = resolve(value.replace(/^~(?=$|[/\\])/, homedir()));
+  const tail = [];
+  while (!existsSync(path)) { tail.unshift(basename(path)); path = dirname(path); }
+  return join(realpathSync(path), ...tail);
+}
+
+export function packageStorage(root, dataDirectory) {
+  const home = homedir();
+  const base = process.platform === 'darwin' ? join(home, 'Library/Application Support')
+    : process.platform === 'win32' ? process.env.LOCALAPPDATA || join(home, 'AppData/Local')
+    : process.env.XDG_DATA_HOME || join(home, '.local/share');
+  const storage = {
+    TUM_MCP_DATA_DIR: canonical(dataDirectory),
+    TUM_MCP_CONFIG_DIR: canonical(process.env.TUM_MCP_CONFIG_DIR || join(dataDirectory, 'config')),
+    TUM_MOODLE_DATA_DIR: canonical(process.env.TUM_MOODLE_DATA_DIR || join(base, 'TUMMoodle')),
+    TUM_MOODLE_DOWNLOAD_DIR: canonical(process.env.TUM_MOODLE_DOWNLOAD_DIR || join(home, 'Downloads/TUM Moodle')),
+  };
+  const config = storage.TUM_MCP_CONFIG_DIR;
+  const settings = join(config, 'preferences.json');
+  let workspace = join(home, 'University');
+  if (existsSync(settings)) {
+    try {
+      const prefs = JSON.parse(readFileSync(settings, 'utf8'));
+      if (prefs.workspace_root !== undefined) {
+        if (typeof prefs.workspace_root !== 'string') throw new Error('Invalid storage path');
+        workspace = prefs.workspace_root;
+      }
+    } catch { throw new Error('Storage settings could not be verified; package files and saved data were preserved.'); }
+  }
+  for (const path of [...Object.values(storage), workspace]) {
+    const inside = relative(root, canonical(path));
+    if (inside === '' || (inside.split(sep)[0] !== '..' && !isAbsolute(inside))) {
+      throw new Error('Package installation overlaps saved data or course work. Move that data outside the package before update/removal.');
+    }
+  }
+  return storage;
+}
+
+export function npmCli() {
+  const paths = (process.env.PATH || '').split(delimiter);
+  const candidates = [process.env.npm_execpath,
+    join(dirname(process.execPath), 'node_modules/npm/bin/npm-cli.js'),
+    join(dirname(dirname(process.execPath)), 'lib/node_modules/npm/bin/npm-cli.js'),
+    ...paths.flatMap(path => [join(path, 'npm'), join(path, 'node_modules/npm/bin/npm-cli.js')])];
+  for (const path of candidates) {
+    if (!path || !existsSync(path)) continue;
+    const resolved = realpathSync(path);
+    if (basename(resolved) !== 'npm-cli.js') continue;
+    const manifest = join(dirname(dirname(resolved)), 'package.json');
+    if (existsSync(manifest) && JSON.parse(readFileSync(manifest, 'utf8')).name === 'npm') return resolved;
+  }
+  throw new Error('npm could not be located beside Node or on PATH. Install Node.js with npm, then retry.');
+}
+
+export function runNpm(cli, args, capture = false) {
+  const result = spawnSync(process.execPath, [cli, ...args, '--ignore-scripts', '--no-audit', '--no-fund', '--no-update-notifier'], {
+    shell: false, stdio: capture ? ['ignore', 'pipe', 'inherit'] : 'inherit', encoding: 'utf8', timeout: 600000,
+  });
+  if (result.error || result.status !== 0) throw new Error('npm operation failed. Saved data and retained client runtimes were preserved; resolve the npm error and retry.');
+  return capture ? result.stdout.trim() : '';
+}
+
+export function installationTarget(root) {
+  const modules = dirname(dirname(root));
+  if (basename(modules) !== 'node_modules' || modules.split(/[\\/]/).some(part => ['.pnpm', '_npx'].includes(part))) {
+    throw new Error('Package management requires an npm installation. Use update --local for a source/pinned build.');
+  }
+  if (`${basename(dirname(root))}/${basename(root)}` !== packageName) {
+    throw new Error('Automatic package management requires the original package name; aliases were preserved.');
+  }
+  const parent = dirname(modules);
+  const prefix = process.platform === 'win32' ? parent : dirname(parent);
+  const shim = process.platform === 'win32' ? join(prefix, 'tum-mcp.cmd') : join(prefix, 'bin/tum-mcp');
+  if (existsSync(shim)) {
+    const owned = process.platform === 'win32'
+      ? readFileSync(shim, 'utf8').replaceAll('\\', '/').includes('node_modules/@jamestesting888/tum-mcp/npm/tum-mcp.mjs')
+      : realpathSync(shim) === join(root, 'npm/tum-mcp.mjs');
+    if (owned && (process.platform === 'win32' || basename(parent) === 'lib')) return { prefix, global: true };
+  }
+  const manifest = join(parent, 'package.json');
+  if (existsSync(manifest)) {
+    const project = JSON.parse(readFileSync(manifest, 'utf8'));
+    if (['dependencies', 'devDependencies', 'optionalDependencies'].some(key => project[key]?.[packageName])) {
+      return { prefix: parent, global: false };
+    }
+  }
+  throw new Error('The npm installation prefix could not be verified; package files were preserved.');
+}

package/npm/package-manager.mjs

@@ -0,0 +1,109 @@
+import { spawnSync } from 'node:child_process';
+import { existsSync, readFileSync, realpathSync } from 'node:fs';
+import { copyFile, mkdtemp, rm, writeFile } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { basename, dirname, isAbsolute, join, relative, sep } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { acquireLock } from './lock.mjs';
+import { installationTarget, npmCli, packageName, packageStorage, runNpm } from './npm-command.mjs';
+
+function runLauncher(root, args, quiet = false) {
+  const result = spawnSync(process.execPath, [join(root, 'npm/tum-mcp.mjs'), ...args], {
+    stdio: quiet ? ['ignore', 'pipe', 'pipe'] : 'inherit', encoding: 'utf8', shell: false, timeout: 600000,
+  });
+  if (result.error || result.status !== 0) {
+    if (quiet) process.stderr.write((result.stdout || '') + (result.stderr || ''));
+    throw new Error(`${args[0]} did not complete. Saved data and customized client files were preserved; review the details and retry.`);
+  }
+}
+
+function versionParts(version) {
+  const match = typeof version === 'string' && version.match(/^(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)(?:-([\da-zA-Z-]+(?:\.[\da-zA-Z-]+)*))?(?:\+[\da-zA-Z-]+(?:\.[\da-zA-Z-]+)*)?$/);
+  if (!match) throw new Error('npm returned an invalid package version.');
+  const prerelease = match[4]?.split('.') || [];
+  if (prerelease.some(part => /^0\d+$/.test(part))) throw new Error('npm returned an invalid prerelease version.');
+  return { core: match.slice(1, 4).map(BigInt), prerelease };
+}
+
+export function newerVersion(latest, current) {
+  const left = versionParts(latest), right = versionParts(current);
+  for (let i = 0; i < left.core.length; i++) if (left.core[i] !== right.core[i]) return left.core[i] > right.core[i];
+  const a = left.prerelease, b = right.prerelease;
+  if (!a.length || !b.length) return !a.length && Boolean(b.length);
+  for (let i = 0; i < Math.max(a.length, b.length); i++) {
+    if (a[i] === undefined) return false;
+    if (b[i] === undefined) return true;
+    if (a[i] === b[i]) continue;
+    const numericA = /^\d+$/.test(a[i]), numericB = /^\d+$/.test(b[i]);
+    if (numericA && numericB) return BigInt(a[i]) > BigInt(b[i]);
+    if (numericA !== numericB) return numericB;
+    return a[i] > b[i];
+  }
+  return false;
+}
+
+async function operate(job) {
+  const release = await acquireLock(job.target.prefix, 'tum-mcp-package');
+  try {
+    const scope = ['--prefix', job.target.prefix, `--global=${job.target.global}`];
+    if (job.action === 'uninstall') {
+      const configured = existsSync(join(job.dataDirectory, 'runtime.json')) ||
+        existsSync(join(job.configDirectory, 'clients'));
+      if (configured || job.args.some(arg => ['--purge-runtime', '--forget-credentials'].includes(arg))) {
+        runLauncher(job.root, ['uninstall', '--keep-package', ...job.args]);
+      }
+      runNpm(job.npm, ['uninstall', ...scope, packageName]);
+      console.log('TUM MCP package and managed client setup removed. Saved user data was retained unless explicitly requested.');
+      return;
+    }
+    const current = JSON.parse(readFileSync(join(job.root, 'package.json'), 'utf8')).version;
+    const latest = JSON.parse(runNpm(job.npm, ['view', `${packageName}@latest`, 'version', '--json', ...scope], true));
+    if (!newerVersion(latest, current)) {
+      console.log(`Installed ${current}; no newer npm release. Refreshing configured clients.`);
+      runLauncher(job.root, ['update', '--local']);
+      return;
+    }
+    console.log(`Preparing TUM MCP ${latest}.`);
+    const packed = JSON.parse(runNpm(job.npm, ['pack', `${packageName}@${latest}`, '--pack-destination', job.temporary, '--json', ...scope], true));
+    if (!Array.isArray(packed) || packed.length !== 1 || packed[0].name !== packageName || packed[0].version !== latest || basename(packed[0].filename) !== packed[0].filename) {
+      throw new Error('npm package metadata did not match the selected release.');
+    }
+    const archive = join(job.temporary, packed[0].filename);
+    const staging = join(job.temporary, 'prepared');
+    runNpm(job.npm, ['install', '--prefix', staging, '--global=false', archive], true);
+    const prepared = join(staging, 'node_modules', packageName);
+    runLauncher(prepared, ['setup'], true);
+    // Only a healthy prepared release may replace the user's npm installation.
+    runNpm(job.npm, ['install', ...scope, job.target.global ? archive : `${packageName}@${latest}`]);
+    if (JSON.parse(readFileSync(join(job.root, 'package.json'), 'utf8')).version !== latest) throw new Error('npm did not install the selected version; client activation was stopped.');
+    runLauncher(job.root, ['update', '--local']);
+    console.log(`Updated TUM MCP to ${latest}. Restart clients to load refreshed skills.`);
+  } finally { await release(); }
+}
+
+export async function managePackage(action, args, dataDirectory) {
+  const root = dirname(dirname(fileURLToPath(import.meta.url)));
+  const inside = relative(root, process.cwd());
+  if (inside === '' || (inside.split(sep)[0] !== '..' && !isAbsolute(inside))) throw new Error('Run package update/removal from outside the installed package directory.');
+  const target = installationTarget(root);
+  const storage = packageStorage(root, dataDirectory);
+  const configDirectory = storage.TUM_MCP_CONFIG_DIR;
+  const npm = npmCli();
+  const temporary = await mkdtemp(join(tmpdir(), 'tum-mcp-package-'));
+  try {
+    for (const name of ['package-manager.mjs', 'npm-command.mjs', 'lock.mjs']) await copyFile(join(root, 'npm', name), join(temporary, name));
+    const job = { action, args, root, dataDirectory, configDirectory, target, npm, temporary };
+    const path = join(temporary, 'job.json');
+    await writeFile(path, JSON.stringify(job), { mode: 0o600, flag: 'wx' });
+    // This worker and its cwd survive Windows replacing/removing the package files.
+    const result = spawnSync(process.execPath, [join(temporary, 'package-manager.mjs'), '--job', path], {
+      cwd: temporary, stdio: 'inherit', shell: false, env: { ...process.env, ...storage },
+    });
+    return result.status ?? (result.signal === 'SIGINT' ? 130 : 2);
+  } finally { await rm(temporary, { recursive: true, force: true }); }
+}
+
+if (process.argv[1] && process.argv[2] === '--job' && realpathSync(process.argv[1]) === fileURLToPath(import.meta.url)) {
+  try { await operate(JSON.parse(readFileSync(process.argv[3], 'utf8'))); }
+  catch (error) { console.error(error.message); process.exitCode = 2; }
+}

package/npm/runtime.mjs

@@ -2,10 +2,11 @@ import { spawnSync } from 'node:child_process';
 import { createHash, randomUUID } from 'node:crypto';
 import { existsSync, lstatSync, readFileSync, readdirSync, realpathSync } from 'node:fs';
 import { chmod, mkdir, mkdtemp, rename, rm, rmdir, writeFile } from 'node:fs/promises';
-import { homedir, hostname } from 'node:os';
+import { homedir } from 'node:os';
 import { basename, dirname, join, resolve } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { download } from './download.mjs';
+import { acquireLock } from './lock.mjs';
 
 const packageRoot = dirname(dirname(fileURLToPath(import.meta.url)));
 const pins = JSON.parse(readFileSync(join(packageRoot, 'npm/uv-artifacts.json'), 'utf8'));
@@ -109,40 +110,7 @@ async function uvExecutable() {
   return cached;
 }
 
-export async function acquireSetupLock() {
-  const lock = join(dataRoot(), 'setup.lock');
-  const owner = { pid: process.pid, host: hostname(), nonce: randomUUID() };
-  const guard = join(dataRoot(), 'setup.claim');
-  try { await mkdir(guard, { mode: 0o700 }); }
-  catch { throw new Error('Another setup is claiming the lock. Retry; an interrupted setup.claim needs local review.'); }
-  try {
-  try { await mkdir(lock, { mode: 0o700 }); }
-  catch (error) {
-    if (error.code !== 'EEXIST') throw error;
-    let previous;
-    try { previous = JSON.parse(readFileSync(join(lock, 'owner.json'), 'utf8')); }
-    catch { throw new Error('Setup lock has no readable owner. Confirm no setup is running before removing setup.lock.'); }
-    if (!Number.isSafeInteger(previous.pid) || previous.pid <= 0 || previous.host !== hostname()) {
-      throw new Error('Setup lock belongs to an unknown owner; preserve it for local review.');
-    }
-    let alive = true;
-    try { process.kill(previous.pid, 0); }
-    catch (failure) { if (failure.code === 'ESRCH') alive = false; }
-    if (alive) throw new Error('Another setup is running; retry when it finishes.');
-    const abandoned = `${lock}.${randomUUID()}.abandoned`;
-    await rename(lock, abandoned);
-    await rm(abandoned, { recursive: true, force: true });
-    try { await mkdir(lock, { mode: 0o700 }); }
-    catch { throw new Error('Another setup acquired the lock; retry when it finishes.'); }
-  }
-  await atomicWrite(join(lock, 'owner.json'), JSON.stringify(owner));
-  } finally { await rmdir(guard); }
-  return async () => {
-    const current = JSON.parse(readFileSync(join(lock, 'owner.json'), 'utf8'));
-    if (current.nonce !== owner.nonce) throw new Error('Setup lock ownership changed; it was preserved.');
-    await rm(lock, { recursive: true, force: true });
-  };
-}
+export function acquireSetupLock() { return acquireLock(dataRoot()); }
 
 export async function ensureRuntime() {
   const backend = join(packageRoot, 'npm/backend');

package/npm/tum-mcp.mjs

@@ -1,33 +1,58 @@
 #!/usr/bin/env node
 import { spawnSync } from 'node:child_process';
 import { readFileSync } from 'node:fs';
-import { acquireSetupLock, currentPython, ensureRuntime, removeRuntimeFiles } from './runtime.mjs';
+import { parseArgs } from 'node:util';
+import { acquireSetupLock, currentPython, dataRoot, ensureRuntime, removeRuntimeFiles } from './runtime.mjs';
+import { managePackage } from './package-manager.mjs';
 
-const args = process.argv.slice(2);
+let args = process.argv.slice(2);
 const version = JSON.parse(readFileSync(new URL('../package.json', import.meta.url), 'utf8')).version;
 try {
   if (args.length === 0 || (args.length === 1 && ['--help', '-h'].includes(args[0]))) {
     console.log(`TUM MCP ${version}\nCommands: setup [--client codex|claude|cursor|antigravity|generic], connect, scope, discover, status, doctor [--json] [--live], serve, skills, study, logout, uninstall, update\nRun connect without arguments to select services and an installed Chromium browser. Run setup explicitly to provision the managed Python backend.`);
   } else if (['--version', 'version'].includes(args[0])) {
     console.log(version);
-  } else if (['setup', 'update'].includes(args[0]) && args.length === 2 && ['--help', '-h'].includes(args[1])) {
-    console.log(args[0] === 'update'
-      ? 'Usage: tum-mcp update\nRefresh previously configured clients for the installed npm version.\nDownload a newer version first: npm install --global @jamestesting888/tum-mcp@latest'
-      : 'Usage: tum-mcp setup [--client codex|claude|cursor|antigravity|generic] [--host local|windows]\nProvision the managed runtime and register explicitly selected clients.');
+  } else if (['setup', 'update', 'uninstall'].includes(args[0]) && args.some(arg => ['--help', '-h'].includes(arg))) {
+    const help = {
+      update: 'Usage: tum-mcp update [--local]\nInstall the latest npm release and refresh configured clients.\n--local refreshes this installed version without contacting npm.',
+      setup: 'Usage: tum-mcp setup [--client codex|claude|cursor|antigravity|generic] [--host local|windows]\nProvision the managed runtime and register explicitly selected clients.',
+      uninstall: 'Usage: tum-mcp uninstall [--all] [--purge-runtime] [--forget-credentials]\nRemove managed client setup and this npm installation. Saved data is retained by default.\n--client NAME removes one client only. --keep-package keeps npm installed.',
+    };
+    console.log(help[args[0]]);
   } else {
-    if (args[0] === 'update' && args.length !== 1) throw new Error('Usage: tum-mcp update (no arguments). Use --help for the update workflow.');
-    const setup = ['setup', 'update'].includes(args[0]);
-    const python = setup ? await ensureRuntime() : currentPython();
-    if (!python) throw new Error('SETUP_REQUIRED: Run tum-mcp setup first.');
-    const forwarded = args;
-    const env = { ...process.env, TUM_MCP_NPM_LAUNCHER: '1' }; delete env.PYTHONPATH; delete env.PYTHONHOME;
-    const purge = args[0] === 'uninstall' && args.includes('--purge-runtime');
-    const release = purge ? await acquireSetupLock() : null;
-    try {
-      const child = spawnSync(python, ['-I', '-m', 'tum_mcp', ...forwarded], { env, stdio: 'inherit', shell: false });
-      if (child.error) throw new Error('Managed backend could not start; run setup again.');
-      process.exitCode = child.status ?? (child.signal === 'SIGINT' ? 130 : 1);
-      if (purge && child.status === 0) await removeRuntimeFiles();
-    } finally { if (release) await release(); }
+    let packageAction = args[0] === 'update';
+    if (args[0] === 'update') {
+      if (args.length > 2 || (args.length === 2 && args[1] !== '--local')) throw new Error('Usage: tum-mcp update [--local]. Use --help for details.');
+      if (args[1] === '--local') { packageAction = false; args = ['update']; }
+    }
+    if (args[0] === 'uninstall') {
+      const { values } = parseArgs({ args: args.slice(1), options: {
+        all: { type: 'boolean' }, client: { type: 'string' }, host: { type: 'string' },
+        'keep-package': { type: 'boolean' }, 'purge-runtime': { type: 'boolean' }, 'forget-credentials': { type: 'boolean' },
+      } });
+      if (values.host && !['local', 'windows'].includes(values.host)) throw new Error('Choose --host local or windows.');
+      if (values.client !== undefined && !['codex', 'claude', 'cursor', 'antigravity', 'generic'].includes(values.client)) throw new Error('Choose a supported --client name.');
+      if (values.client && (values.all || values['purge-runtime'] || values['forget-credentials'])) throw new Error('Client-only removal cannot use --all or data/runtime cleanup options.');
+      if (!values.client && !values.all) args.push('--all');
+      packageAction = !values.client && !values['keep-package'];
+      args = args.filter(arg => arg !== '--keep-package');
+    }
+    if (packageAction) {
+      process.exitCode = await managePackage(args[0], args.slice(1), dataRoot());
+    } else {
+      let python = ['setup', 'update'].includes(args[0]) ? await ensureRuntime() : currentPython();
+      if (args[0] === 'uninstall' && !python) python = await ensureRuntime();
+      if (!python) throw new Error('SETUP_REQUIRED: Run tum-mcp setup first.');
+      const forwarded = args;
+      const env = { ...process.env, TUM_MCP_NPM_LAUNCHER: '1' }; delete env.PYTHONPATH; delete env.PYTHONHOME;
+      const purge = args[0] === 'uninstall' && args.includes('--purge-runtime');
+      const release = purge ? await acquireSetupLock() : null;
+      try {
+        const child = spawnSync(python, ['-I', '-m', 'tum_mcp', ...forwarded], { env, stdio: 'inherit', shell: false });
+        if (child.error) throw new Error('Managed backend could not start; run setup again.');
+        process.exitCode = child.status ?? (child.signal === 'SIGINT' ? 130 : 1);
+        if (purge && child.status === 0) await removeRuntimeFiles();
+      } finally { if (release) await release(); }
+    }
   }
 } catch (error) { console.error(error.message); process.exitCode = 2; }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jamestesting888/tum-mcp",
-  "version": "0.6.0",
+  "version": "0.7.0",
   "description": "Read-only TUM Moodle, Artemis and Zulip integration with source-backed study workflows",
   "license": "MIT",
   "type": "module",
@@ -14,6 +14,9 @@
     "npm/tum-mcp.mjs",
     "npm/runtime.mjs",
     "npm/download.mjs",
+    "npm/lock.mjs",
+    "npm/npm-command.mjs",
+    "npm/package-manager.mjs",
     "npm/uv-artifacts.json",
     "npm/backend/*.whl",
     "npm/backend/requirements.txt",
@@ -31,7 +34,8 @@
     "prepack": "node npm/build.mjs",
     "test": "node --test npm/test/*.test.mjs",
     "test:consumer": "node npm/smoke-consumer.mjs",
-    "test:upgrade": "node npm/upgrade-consumer.mjs"
+    "test:upgrade": "node npm/upgrade-consumer.mjs",
+    "test:package-lifecycle": "node npm/package-consumer.mjs"
   },
   "publishConfig": {
     "access": "public"