Learning Space

Learn from a local, visual lesson collection at your own pace. A learning space can include prepared lessons and optional resources, while learner progress and notes stay on the device.

The engine provides accessible reading components, local preview, learner progress, search, review, notebook tools, and private learner data export. Content preparation remains a maintainer-only file workflow; learners are the only product persona.

Learner experience

Start with a prepared lesson, or open an empty learning space and enter something you want to understand. Add notes, a link, or a passage when you have a resource; leave the resource blank when you do not. Learning goals entered in the empty state are saved locally in the browser and are never uploaded.

The runtime is local-first: there are no accounts, telemetry, hosted scheduling, or cloud sync. Learners can read lessons, search concepts, track progress, review activities, keep notes, and export their own browser-local data.

Quick start

Requirements:

• Node.js 24 LTS
• npm bundled with Node.js 24 LTS

For a project that contains prepared learning content, run:

npx lecture-site-engine@latest init

This creates a starter collection and installs the agent skill files. The generated per-lecture raw file is a visibly marked scaffold placeholder, not source evidence:

lectures/
  course.yaml
  01-introduction/
    lecture.template.md
    raw-lecture.txt
.claude/skills/lecture-site-engine/SKILL.md
.codex/skills/
  lecture-site-engine/
SKILL.md

init installs only the Lecture Site Engine entry points: the root SKILL.md, the Claude Code skill, and the Codex lecture-site-engine skill. Existing consumer-owned skill files are preserved. Auxiliary skills bundled in the repository are not added to a consumer project by init.

Replace the placeholder with the learning content supplied by the project maintainer, then ask the coding agent to follow the lecture-site-engine skill and create the lesson. The agent should preserve that source and write the generated lesson to lecture.template.md. Raw-source files are never agent-generated output. The 01-introduction directory is only a starter scaffold; it is not a course outline or a decision to create exactly one lesson.

Validate and preview:

npx lecture-site-engine validate
npx lecture-site-engine dev

The CLI stages its runtime app under .lecture-site-engine/ and chooses a compatibility-safe Next launch path, so this command is the complete preview workflow. Open the ready URL printed by the command, normally http://localhost:3000. If the port is already in use, Next may choose another port; use the URL it reports.

Maintainer content setup

Install the content-preparation skill from skills.sh:

npx skills add salitaba/lecture-skill --skill lecture-site-engine

Claude Code discovers:

.claude/skills/lecture-site-engine/SKILL.md

Codex discovers:

.codex/skills/lecture-site-engine/SKILL.md

The repository may contain additional independently discoverable Codex skills for development, but init does not install them:

• banner-design
• brand
• design
• design-system
• slides
• ui-styling
• ui-ux-pro-max

Install as a ChatGPT/Codex plugin

This repository also contains a skills-only plugin at plugins/lecture-site-engine. It packages the content-preparation workflow for sharing through a GitHub-backed marketplace.

After cloning or publishing this repository, add its marketplace:

codex plugin marketplace add salitaba/lecture-skill

Then install lecture-site-engine from the Lecture Site Engine marketplace in the ChatGPT desktop app, or run:

codex plugin add lecture-site-engine@lecture-site-engine

This is a skills-only plugin. It provides maintainer guidance and local CLI workflows; it does not expose the Next.js site as a hosted ChatGPT app or remote MCP service. For public visibility in the official ChatGPT Plugins Directory, submit the skills bundle through the OpenAI Platform after pushing the repository.

Other agents can follow the root SKILL.md. The lecture skill explains the supported frontmatter, section structure, teaching components, source-fidelity rules, validation loop, and review workflow.

After initialization, a useful maintainer prompt is:

Read and follow the lecture-site-engine skill. Use the raw lecture source in lectures/01-introduction/raw-lecture.txt, create or update the matching lecture.template.md, preserve source-grounded meaning, and run npx lecture-site-engine validate until it passes.

Content preparation workflow

The content-preparation agent begins by inspecting source status and reporting whether relevant source files are present, missing, or scaffold placeholders. It then keeps a clear standalone request as one lesson. For a broad topic, it asks one targeted lesson-vs-collection question, recommending a collection when the subject is naturally course-sized, or states a clear assumption when the scope is already decided. The starter scaffold never silently determines the learning path size.

Maintainer-provided source is preferred for prepared lessons. If it is unavailable, the maintainer may explicitly authorize bounded research. General reading links belong in resource_links; source-grounded claims may use lesson-local sources, supported source_refs, and the prose-adjacent citation component. Research-backed output is a derived draft and does not become human source evidence. The engine never fetches or verifies URLs at runtime.

The staged flow is: content brief → (authorized) research brief → scope checkpoint → selected lesson or confirmed collection → validation and handoff. The final report should identify created/updated files, lesson count, validation result, source status, warnings, and the next command or decision.

A preferred response shape for a broad, internet-backed request is:

Authoring brief: [mode, scope, assumptions, source status, expected paths]
Research brief: [bounded concepts, proposed outline, concise source links]
Scope checkpoint: [one recommended lecture-vs-course decision]
Draft and verification: [created files, lecture count, validation/source-review status]
Handoff: [warnings, human-source limitation, next action]

After the scope is clear, use:

1. Supply source evidence next to each lesson template when available.
2. Ask Claude Code, Codex, or another agent to follow SKILL.md.
3. Run npx lecture-site-engine validate.
4. Preview with npx lecture-site-engine dev.
5. Add more lectures with npx lecture-site-engine new:lecture.
6. Create a source worksheet with npx lecture-site-engine review:source.
7. Create a portable package with npx lecture-site-engine package:review when maintainer review is requested.

The initializer and scaffold commands never overwrite existing authored templates or raw source files. Scaffold placeholders do not count as evidence and must be replaced before authoring or source-fidelity approval.

Collection structure

lectures/
  course.yaml                 # optional course metadata
  raw-course.txt              # optional shared human source evidence
  01-introduction/
    raw-lecture.txt
    lecture.template.md
  02-core-concepts/
    raw-lecture.txt
    lecture.template.md

The collection landing page links to each lecture, provides previous/next navigation, and tracks browser-local learner progress. course.yaml can define the title, description, audience, level, duration, optional module groups, and advisory prerequisite mappings. Prerequisites never lock lecture access.

Release 2 adds a browser-local notebook plus authored evidence and learning-depth components. Lecture frontmatter may declare stable sources; citation and supported teaching components can reference them with source_refs. Local figure assets are path-contained, content-hashed, copied into preview/export output, and recorded in package manifests. equation is rendered server-side with strict KaTeX HTML/MathML and local fonts. data_table supports bounded text, number, and ISO-date cells, stable sorting, and formula-safe CSV export. These authored features are searchable and printable; notebook records remain learner-controlled browser data.

Release 3 adds deterministic collection study planning and portable .ics calendar export. Study plans use authored or reading-time estimates, support accessible re-planning and editing, and use floating local calendar times without notifications or hosted services. Learner pages do not include teacher-facing feedback or reporting controls.

Unified interaction and assessment engine

The five assessment components (quiz, question_set, free_response, practice_task, and flashcard) share one internal registry and capability model. Every assessment can optionally declare a stable lowercase id and syntax-validated objective_refs metadata. Registry IDs are deterministic and do not replace existing page anchors, so authored links remain stable.

The runtime provides a common accessible shell, status announcements, keyboard-friendly reveal controls, and useful static/print fallbacks. Choice attempts for quizzes and question sets may persist locally and are revalidated against the current authored options; written-response, rubric, and flashcard lifecycle state remains local to the mounted activity. The collection and lecture indexes expose all five types, while answer review and answer-key exports remain limited to objective choice activities.

Validation JSON and static review-package records include deterministic assessment summaries by type and evaluation mode, objective references, answer-key coverage, and an explicit learnerStateIncluded: false marker. They never include answer text or learner attempts.

Learning objectives and local review

Learning objectives may use the optional stable form - [objective-id] Learner-facing objective text. Assessment components can point to those explicit IDs with objective_refs; references to legacy unmarked objectives are rejected because those generated IDs are display-only. Existing unmarked objectives remain valid and visible.

The learner dashboard connects objectives to local evidence and an authored-order review queue. Review records live only in the browser under lecture-progress:<lecture-id>:reviews; untouched activities are not auto-scheduled. Learners choose ratings such as Again, Hard, Good, or Easy. “Demonstrated recently” describes recent positive evidence, not a grade, certificate, or permanent mastery claim.

Learner tools and local privacy

Lecture and collection pages provide labelled links to Search, Focused review, Notebook, Learner data, and—when a collection is active—Study plan. Search is also available with Ctrl+K or Meta+K. Search combines authored content with the learner’s permitted notes and highlights; focused review is refresh-safe; notebook, backup, and study-plan records stay local to the browser.

All learner state remains browser-local. There are no accounts, telemetry, network search, notifications, hosted scheduling, or cloud sync. The Learner data page inventories known records and lets the learner create a versioned JSON backup, preview a backup before importing it, merge by default, explicitly confirm replacement, reset individual features or the selected scope, and undo the most recent change during the current page session. Backups include validated learner-controlled records such as plans, but exclude templates, raw source evidence, authored correct answers, instructor notes, manifests, and reviewer-package data.

Release 2 budgets are explicit and test-covered: the authored search benchmark uses 500 records across a 50-lecture fixture and must rank within 150 ms in the focused test; typed data tables allow at most 12 columns and 500 rows; learner-data imports are capped at 2 MiB. These are validation/product limits, not promises of network or cloud capacity.

The five tool routes are statically exported and included in portable reviewer-package route planning. Their no-JavaScript output provides honest indexes or availability messages; browser-only due state, personal annotations, and import controls activate after hydration. Reviewer packages still contain no learner state, even though a learner can explicitly export their own backup from the running site. Search result visibility is a presentation rule, not secure removal of authored answer material from static reviewer files.

lectures/raw-course.txt is optional evidence for a real course source spanning multiple lectures. Review tooling reads it when present, but an agent loads it into context only for an explicitly requested shared-source split, cross-lecture reconciliation, or full-course review; its presence alone is not authorization. Per-lecture sources are the default context. Do not paste generated lecture output into any raw-source file. The system can preserve and classify files but cannot cryptographically determine whether user-supplied text was AI-generated.

Useful commands

| Command | Purpose | | --- | --- | | npx lecture-site-engine init | Install skills and create a starter collection | | npx lecture-site-engine new:lecture | Create the next lecture scaffold | | npx lecture-site-engine validate | Validate templates and metadata | | npx lecture-site-engine doctor | Check project readiness | | npx lecture-site-engine dev | Start the local preview | | npx lecture-site-engine review:source | Create a source-fidelity worksheet | | npx lecture-site-engine package:review | Build a static reviewer handoff |

When working inside a cloned Lecture Site Engine repository, the same commands are available as npm run ... scripts.

Release from a laptop

The repository includes a guarded release command that publishes directly to npm from your laptop. It checks npm authentication, runs the complete release check, bumps the version, publishes the package, and creates a local release commit and tag.

Authenticate once:

npm login --registry=https://registry.npmjs.org

Preview a release without changing files or git history:

npm run release -- patch --dry-run

Release the next patch, minor, or major version:

npm run release -- patch
npm run release -- minor
npm run release -- major

An exact version is also accepted, for example npm run release -- 0.1.3.

After a local release, push the commit if desired:

git push origin main

Do not push the generated v*.*.* tag, because the tag-based GitHub workflow also publishes to npm. Use --ci only when you want the previous tag-driven GitHub release instead:

npm run release -- patch --ci

Learn more

• SKILL.md: maintainer instructions for preparing learner-facing content.
• DEVELOPMENT.md: repository development, testing, packaging, and release guidance.
• docs/mvp-review-checklist.md: reviewer quality checklist.
• examples/multi-lecture/: example collection.