@jamestesting888/tum-mcp 0.5.0 → 0.6.0

package/docs/setup.md

@@ -2,8 +2,7 @@
 
 [README](../README.md) · [Tools and scopes](tum-mcp.md) · [Development](development.md)
 
-These instructions apply to **0.5.0**. Upgrade older installations before using
-the interactive connection flow below.
+Use the latest package for the connection, managed update and removal flows below.
 
 ## Install
 
@@ -13,7 +12,7 @@ targets are macOS ARM64/x64, Windows ARM64/x64 and glibc Linux ARM64/x86_64.
 Linux needs a graphical desktop for native browser sign-in; WSL can use Windows.
 
 ```sh
-npm install --global @jamestesting888/tum-mcp@0.5.0
+npm install --global @jamestesting888/tum-mcp@latest
 tum-mcp setup --client codex
 tum-mcp connect
 tum-mcp doctor
@@ -21,8 +20,10 @@ 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 need their MCP servers reloaded. Generic setup writes configuration
-for manual installation. Setup preserves unrelated settings and refuses to
+Antigravity setup installs all five 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
 replace customized entries. It does not authenticate or fetch courses.
 
 ## Connect
@@ -60,7 +61,7 @@ release; distributions still use engine 1 or 2. See Microsoft's
 Both engines have dedicated CI checks on the current WSL 3.x runner image.
 
 ```sh
-npm install --global @jamestesting888/tum-mcp@0.5.0
+npm install --global @jamestesting888/tum-mcp@latest
 tum-mcp setup --client cursor --host windows
 tum-mcp connect
 tum-mcp doctor
@@ -95,13 +96,18 @@ browser discovery still requires functioning interop.
   tools. Saved sessions are **Not verified** until checked; registration alone
   does not prove a desktop client is running the server.
 - `tum-mcp doctor --live` verifies saved local sessions with bounded service
-  reads. `--json` provides structured output; combine the flags if needed.
+  reads and checks optional GitHub CLI authentication. `--json` provides structured
+  output; combine the flags if needed. Default doctor checks only CLI availability.
+- For optional study publishing, install GitHub CLI and complete
+  `gh auth login --hostname github.com` interactively on the agent's execution host.
+  The [publishing workflow](study.md#publish-a-study-website) uses private repositories
+  with public Pages websites and requires an eligible paid GitHub plan.
 - An expired session uses the same `tum-mcp connect` selector. Reconnecting the
   same identity preserves course/channel scopes.
 - If no browser appears, check its installation or `TUM_MCP_BROWSER`. A managed
   or incompatible Chromium build may prevent automation; try another browser.
-- Git is optional for assignment workspaces. Docker is optional for approved
-  isolated tests. Missing either does not prevent course reads.
+- Git and Docker are optional. Neither is needed for course reads or the
+  GitHub CLI based study publisher.
 - Do not paste passwords, cookies, MFA codes or API keys into chat or bug reports.
 
 Sessions are encrypted with owner-restricted local key files. This avoids native
@@ -111,12 +117,70 @@ explain migration and backup. Existing Moodle data and downloads are preserved.
 
 ## Update and remove
 
-Update with `npm install --global @jamestesting888/tum-mcp@latest`, then rerun
-setup. Review conflicts instead of deleting customized client configuration.
-`tum-mcp uninstall --client cursor` (or your client) removes unchanged managed
-registration while retaining sessions, downloads and personal work. Codex plugin
-removal uses its Plugins UI. Remove the npm package separately with
-`npm uninstall --global @jamestesting888/tum-mcp`.
+```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
+files. WSL Windows registrations keep their distribution/user/data paths.
+
+Ownership receipts track the entries and files installed by TUM MCP. Unchanged
+managed files advance; unrelated settings and extra files stay intact. Direct
+edits to an entry or skill stop that client's update and are reported for review;
+other clients can still advance. Old runtime generations remain available for
+existing pinned clients. Interrupted setup can recover a stopped lock owner;
+an ownerless/unknown legacy lock requires local review. A failed new runtime is
+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:
+
+```sh
+tum-mcp uninstall --all
+npm uninstall --global @jamestesting888/tum-mcp
+```
+
+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.
+
+For explicit cleanup, **close coding clients first**, then run:
+
+```sh
+tum-mcp uninstall --all --purge-runtime --forget-credentials
+npm uninstall --global @jamestesting888/tum-mcp
+```
+
+`--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
+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
 

package/docs/study.md

@@ -0,0 +1,325 @@
+# Course study projects
+
+The five reading, study, audio and publishing skills ship with version **0.6.0**.
+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
+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,
+quotations and source links for the intended public audience before publishing.
+
+Install GitHub CLI on the execution host and run `gh auth login --hostname github.com`.
+`tum-mcp doctor` checks CLI availability without network access; `doctor --live`
+also verifies GitHub authentication. It does not publish anything, open sign-in
+automatically, extract tokens, or change Git credential settings.
+
+```sh
+# Preview the chosen name and hosting requirements without GitHub mutations.
+tum-mcp study publish --project PROJECT
+# After choosing public website content; the repository stays private.
+tum-mcp study publish --project PROJECT --public-site
+# Optional account/name override on first setup:
+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
+failed setup retries the same saved repository rather than creating duplicates.
+
+Only the generated website renderer and lesson 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
+not contain credentials.
+
+After setup, successful `tum-mcp study build PROJECT` commands update that same
+repository automatically. Unchanged verified exports require no network calls
+or commits. The study skills finish related edits in one build. Remote edits
+are preserved for review; the publisher never force-pushes.
+
+```sh
+tum-mcp study publish status PROJECT
+tum-mcp study publish sync PROJECT       # retry pending/failed deployment
+tum-mcp study publish pause PROJECT      # pause future automatic uploads
+tum-mcp study publish resume PROJECT
+tum-mcp study build PROJECT --local-only # skip uploading this build
+```
+
+Uploads are verified against the Pages build and GitHub checks for the exact
+commit. Pending deployment exits with code 2 and is resumable; a successful
+repository update alone is not a deployed site. Authentication, plan or network
+failures preserve the local build. Polling has a budget of at most 60 seconds,
+in addition to bounded API requests.
+The `tum-mcp study` launcher prints local, hosted and repository URLs, plus pending
+or paused status. Study progress remains per browser; passage comments require
+the local preview and are disabled in the hosted export. Device synchronization
+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,
+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.
+
+```text
+Initialize ./pse-ws26 for Patterns in Software Engineering (WS26/27).
+Use its available Artemis teaching material and record any missing sources.
+```
+
+The agent inventories Moodle materials, announcements and forums; Artemis
+lectures, learning units, student slides and statements; and mapped Zulip course
+discussions. It reads only enabled sources. An unavailable login or partially
+retrieved source is recorded as a gap rather than an empty course.
+
+```text
+pse-ws26/
+  AGENTS.md                 Course knowledge and current inventory
+  materials/
+    content/                Lectures, slides and reading
+    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
+  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.
+
+## State-based workflow
+
+`sync-study` starts with `tum-mcp study status PROJECT`, a read-only local check:
+
+| Mode | Action |
+| --- | --- |
+| `initialize` | Verify the chosen available course, then initialize its inventory. |
+| `sync` | Reuse the bound course/semester and known source IDs; check the requested changes. |
+| `recover` | Inspect incomplete, damaged or conflicting local state before writing. |
+
+Existing material without state is inspected before adoption. Damaged state and
+customized instructions are preserved; they are never treated as an empty project.
+The status check does not authenticate services or prove upstream freshness.
+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
+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.
+Unchanged payloads can be reused when their source binding, URL, locator and
+reliable revision match. Pending content stays pending across repeated checks;
+a metadata-only check cannot make unfetched content current.
+
+The agent updates course facts outside the inventory block. The helper checks
+that its managed block has not been edited before replacing it. LF/CRLF
+conversions are accepted, and synchronization preserves the existing line-ending style. A failed write
+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
+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:
+
+- 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.
+- Flip cards with arrow navigation, Space to flip and 1/2 for Again/Got it.
+- Practice questions with exactly four options, one justified answer and feedback for every option.
+
+The agent uses stored material first, so local content edits work offline. Ask for
+an upstream refresh when you want new course content; an existing check is reused
+within the same request. Unchanged units and reviewed material are retained.
+
+The skill audits objective coverage, technical accuracy and distractors. Its
+STE-inspired English uses short, direct sentences while retaining necessary terms
+and conditions. The design contract uses TUM blue/navy with quiet reading surfaces,
+local fonts, light/dark themes, keyboard navigation and a phone layout. The outline
+collapses using a midpoint boundary arrow revealed on hover or keyboard focus;
+touch screens keep a visible control. On phones it opens a viewport overlay from
+any reading position, with its own scroll and Escape to close. Theme stays in the
+outline; the reset icon is on the course home. A Next link follows the active
+activity at the end of each view.
+
+Revision combines flashcards and practice from topics you select. Open Revision in
+the outline, choose topics and collapse the checklist when ready. It reuses the
+course's categories; selecting a category includes all its topics, and a mixed
+checkbox shows a partly selected category. Revision reuses the
+original items, sources and progress; selecting or removing topics never clears
+your results. The topic selection is remembered locally for this course.
+
+The topic picker and its nested categories collapse independently. You can select a
+whole category while it is closed; its count and mixed state reflect the selection.
+At End of set, outlined question rows include a Review action and chevron. Click
+one to review it in a popup. Closing the popup returns
+you to the same results row without changing progress.
+
+The website uses Atkinson Hyperlegible Next for headings, explanations and controls.
+Code and mathematical notation retain their specialist fonts. Equations adapt to
+their container and keep local horizontal scrolling for indivisible wide expressions.
+Use `\(v_i\)` in teaching text for inline variables and short expressions (JSON:
+`"Use \\(v_i\\)."`). They compile locally to native MathML, including in tables,
+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
+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.
+Revision notes retain their original topic and card/question identity.
+
+Tell your agent: **“Address the open comments in this study project.”** The skill
+reads the notes, checks the cited material, improves the affected explanation and
+verifies the result before recording a resolution. Notes and status changes sync
+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
+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
+and reported, so the agent must review compatibility when extending them.
+
+```sh
+tum-mcp study inspect ./pse-ws26
+tum-mcp study build ./pse-ws26
+```
+
+From the course project folder, launch the prepared app with:
+
+```sh
+tum-mcp study
+```
+
+It opens the default browser at `http://127.0.0.1:8765`. Keep the terminal open;
+press Ctrl+C to stop. In WSL, it opens the Windows browser through Windows interop.
+If automatic opening is unavailable, open the printed URL. For a different project
+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
+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.
+
+## Create and maintain audio notes
+
+Use `prepare-study` to author the interactive course, then ask `audio-notes` to
+convert that prepared content into spoken lessons. For example:
+
+```text
+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,
+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
+course; it does not refresh campus sources or rebuild the website automatically.
+
+Before synthesis, Audio Notes consolidates repeated explanations and reviews the
+script for coverage, clear terminology, concise examples and useful recall. It
+preserves distinct ideas and conditions rather than targeting a fixed duration.
+Teaching reviews are tied to the script and narration-guidance fingerprints;
+updated guidance prompts a review of existing scripts without automatically
+regenerating unchanged speech. These checks do not establish learning outcomes.
+
+All course-specific audio files stay inside the project's `audio/` directory:
+
+```text
+audio/
+  scripts/01_category.txt    Editable narration, matching the track name
+  tracks/01_category.m4a     One final AAC M4A per category
+  chapters/01_category.json  Section titles and measured timestamps
+  manifest.json             Last verified published coverage and fingerprints
+  plan.json                 Current categories and missing/changed/pending work
+  voice.json                Actual provider, voice and settings; no credentials
+  playlist.m3u              Tracks in the intended study order
+  README.md                 Playback, durations and update details
+  SOURCES.md                Prepared content and original source locators
+  COVERAGE.md               Source concepts mapped to narration and audio
+  .build/                   Candidates, resumable chunks, downloads and QA
+  archive/                  Recoverable superseded versions
+```
+
+Names remain stable across updates, using prefixes and slugs such as
+`01_security-foundations`. New content within a category updates that complete
+track; a new category receives a new track. Existing audio is compared with
+semantic content and file hashes, so unchanged speech can be reused. Scripts alone
+do not count as completed audio coverage. Manual edits are preserved and reconciled.
+
+The skill prefers free ElevenLabs when custom-text generation and downloading work.
+Its anonymous website and authenticated API have different access requirements.
+If free usage runs out or that route is unavailable, local Kokoro is the automatic
+fallback unless the user explicitly restricts the provider. Affected categories
+are regenerated with one Kokoro profile; completed categories remain intact.
+Each category keeps its actual profile on later updates, and mixed providers across
+categories are disclosed. Usage limits are respected; no paid usage or quota
+workarounds are implied. Only reviewed narration goes to a cloud speech provider.
+
+Kokoro weights, voices and pronunciation assets are cached once per execution
+host/user, outside the course, with a reusable isolated runtime. The skill specifies
+Windows, macOS and Linux locations, version/hash verification and safe cache reuse.
+Course manifests record portable dependency identities rather than requiring a
+previous machine's model paths. Setup is lazy, only when local synthesis is needed.
+Actual OS/architecture, runtime and course-language compatibility are checked before
+generation; unsupported or restricted hosts retain pending work with an explanation.
+
+Candidates are validated before replacing usable tracks. Incomplete generations
+remain pending with reusable work under `.build/`. Ask **“Complete the audio notes
+for the updated study website”** to reconcile added, changed, removed or moved
+material with the previous verified coverage. This is an agent skill, not a new
+`tum-mcp study` CLI subcommand or a built-in speech service.
+
+## Packaged app template
+
+The complete web-app template is packaged with `prepare-study` in `assets/site/`.
+It includes the shell, navigation, flip cards, practice, diagrams and styling.
+Agents author course content in `study/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
+
+After installing a locally built development artifact:
+
+```sh
+tum-mcp study demo ./algorithms-demo
+tum-mcp study serve ./algorithms-demo
+```
+
+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.
+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
+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.
+
+```sh
+tum-mcp study init PROJECT --course "Exact course title" --snapshot snapshot.json
+tum-mcp study sync PROJECT --snapshot snapshot.json
+```
+
+Import paths are confined to the snapshot directory. Data is stored under the
+bound project; credentials and unrelated personal records must never enter it.
+Keep real course projects private and out of package artifacts. Uninstalling the
+package preserves projects; remove your own project directory separately when wanted.