TU/e Study Hub documentation

This is the documentation front door for people and coding agents. The guides under Living documentation describe the repository as it works today. Files under docs/superpowers are decision history and implementation plans; use them for context, not as the current API contract.

Production is currently self-hosted at tuestudyhub.xyz on an OVH Ubuntu 24.04 VPS. A standalone Next.js container runs behind Caddy, while published course and plugin data persists in the VPS filesystem store. See VPS deployment for the authoritative hosting contract.

Published site

The living guides are published at docs.tuestudyhub.xyz, built from this directory by MkDocs and served from GitHub Pages. Study Hub links to it from Settings → Help & docs. A merge to main that touches docs/ republishes the site; there is no separate content store to keep in step.

mkdocs.yml owns the configuration:

• A new living guide needs one nav entry. Nothing else registers it.
• exclude_docs keeps superpowers/ and VPS deployment off the public site. The runbook holds no secrets, but it maps ports, paths, deploy-key handling, and ops-dashboard authentication, so it stays repository-only.
• Links that leave the published tree — into src/, into repository-root files, into superpowers/ — are rewritten to GitHub by scripts/docs/repo_links.py. Keep writing them as ordinary relative links.
• mkdocs build --strict runs on every pull request that touches docs/, so a broken cross-reference fails there rather than on the site. Preview locally with pip install -r scripts/docs/requirements.txt && mkdocs serve.
• site_url is also the custom domain. Pages serves one only while the deployed site carries a CNAME file, so scripts/docs/write_cname.py derives that file from site_url during the build. Moving the site is a one-line change here; docs is a CNAME to hectoragofi.github.io in the Spaceship DNS zone, not an A record to the VPS like every other subdomain.

Find the right guide

Goal	Primary guide	Then inspect
Add or change UI	Design system	src/app/globals.css, src/components/ui
Change page annotation or drawing	Drawing overlay	src/components/DrawingOverlay.tsx, src/course-os/services/drawings
Add a course	Adding a course	src/courses/fixture, src/courses/index.ts
Add course content	Learning block specification	src/course-os/registry/blockRegistry.ts
Add a new learning capability	Learning block specification	src/course-os/registry/blocks.ts, src/blocks
Understand agent expectations	Agent guide	root AGENTS.md
Understand the Course OS	Architecture design	src/course-os
Build or review Study Hub AI	AI foundation	src/ai, src/app/api/ai
Build or review Visual Explainer	Visual Explainer	src/ai/visual-explainer, services/visual-explainer-worker
Connect Claude, ChatGPT, or another MCP client	Remote MCP	src/mcp, src/app/mcp
Operate accounts or cross-device sync	Accounts and sync	src/auth, src/sync, supabase
Understand published course documents	Course documents	src/course-os/documents
Edit a published course	Direct course editing	src/course-os/ui/editor, src/course-os/editor
Build or debug an extension	Plugin SDK	src/plugins, public/plugin-runtime, public/plugin-fixtures
Package an extension	Developing a .tuesh extension	src/course-os/plugins
Operate, budget, or recover the platform	Operations	src/course-os/operations
Deploy or update the VPS	VPS deployment	Dockerfile, compose.vps.yaml, scripts/vps
Understand the external ops dashboard boundary	VPS deployment	standalone ops repository
Audit 2IRR00 source coverage	Curriculum map	Coverage audit

Living documentation

• Design system — product feel, typography, tokens, layout, components, motion, responsive behavior, and accessibility.
• Adding a course — the end-to-end authoring and validation workflow, with a minimal example and acceptance checklist.
• Learning block specification — the semantic content envelope and registered block catalog.
• Drawing overlay — the freehand layer over pages: how strokes stay pinned, how they are scoped and stored, and what it deliberately does not save.
• Plugin SDK — the manifest vocabulary, capability catalog, studyHub API, error codes, and the limits the host enforces on every extension.
• Developing a .tuesh extension — archive layout, integrity, limits, permission review, and owner installation workflow.
• Agent guide — task routing, source-of-truth rules, invariants, and verification.
• Accounts and cross-device synchronization — optional Google login, local partitions, synchronized domains, transfer choices, conflicts, RLS, and deployment wiring.
• Remote Study Hub MCP — guarded OAuth access to course reads, canonical Tutor state, notes, progress, and source-grounded flashcards from compatible external clients.
• Visual Explainer — private grounded storyboard generation, constrained visual primitives, durable jobs, quality review, access limits, and the isolated renderer.
• Course documents — the immutable revision format, verified Blob read path, identity index, hashes, schema versions, and publication boundary.
• Direct course editing — owner access, modes, local drafts, publication, conflicts, and identity-preserving follow-up.
• Platform operations — budgets, live-store reporting, reviewable cleanup, recovery drills, dashboard evidence, and infrastructure migration boundaries.
• VPS deployment — the Docker/Caddy topology, filesystem publication store, secrets, deployment workflow, backups, and recovery checks.
• Minimal JSON example — a format-oriented example. TypeScript is the normal in-repository authoring format.

Documentation conventions

Each living guide follows the same pattern:

1. State the contract in plain language.
2. Link to the code that enforces it.
3. Include a concrete workflow or example.
4. End with verification criteria.

When code and prose disagree, the schemas, registries, and tests are authoritative. Update the guide in the same change that updates the contract.

Historical records

docs/superpowers/specs records why major designs were chosen. docs/superpowers/plans records how those designs were implemented. They are useful for intent and tradeoffs, but may describe an earlier repository state.

docs/superpowers/reports records measured evidence — baselines, budgets, and external-service proofs — that later goals cite instead of re-deriving.

plugin-ideas.md is the extension ideas backlog. It is proposal material, not a contract; ideas graduate into fixtures or packages through the guides above.