TutorLumin Workspaces

TutorLumin course and workbook workspaces use a Hugo-first, Markdown-first authoring model.

This keeps authored teaching text traversable by both humans and AI tools while preserving Hugo as the render authority for the locked student experience on tutorlumin.co.uk.

Core rules

• Hugo remains the render authority.
• Markdown files are the source of truth for authored lesson text.
• Course and workbook workspaces are real Git-backed worktrees, not database-authored content stores.
• Student delivery is locked behind the TutorLumin product surface; raw workspaces are an authoring and orchestration layer.
• Student workbooks must be pinned to an explicit course release or commit, never a moving branch tip.

Authoring shape

Use Markdown for page-level teaching text and lightweight page metadata.

Keep small page-local fields in front matter:

• title
• summary
• ordering or section flags
• simple display toggles

Keep larger structured teaching logic in sidecar files near the content:

• quiz.yaml
• checkpoint.yaml
• can-do.yaml
• rubric or grading data
• release manifests
• module metadata shared across pages

This keeps page Markdown readable while giving AI tools and automation stable structured data.

Delivery model

• Authoring source lives in the course or workbook workspace.
• TutorLumin compiles and serves the approved release into the locked student surface.
• Nextcloud should mount workspaces as views when needed, but should not become the canonical store for workbook or course state.
• SQL-backed systems such as student-ops should store links, release pins, projections, and operational metadata, not the canonical authored course body.

Workspace metadata

TutorLumin workspaces should advertise the contract explicitly in workspace.yaml and related course metadata:

• authoring.format: hugo_markdown
• authoring.render_authority: hugo
• authoring.front_matter_policy: page_local_metadata
• authoring.structured_data_policy: sidecar_files
• delivery.surface: tutorlumin_student
• delivery.host: tutorlumin.co.uk
• delivery.locked: true

Workbook scaffolding

Student workbook scaffolds should include:

• Hugo-compatible content/ roots
• release metadata under data/releases/
• workbook metadata that records the pinned course workspace and release
• starter module content that can be rendered through the standard TutorLumin pipeline

Do not treat workbook creation as a copy of a mutable course branch. Treat it as a new workspace that records which course release it is pinned to.