learningfoundry 0.2.0__tar.gz → 0.25.0__tar.gz

{learningfoundry-0.2.0 → learningfoundry-0.25.0}/.gitignore

@@ -34,6 +34,7 @@ node_modules/
 .output/
 .vercel/
 .netlify/
+**/sveltekit_template/static/sql-wasm.wasm
 
 # TypeScript
 *.tsbuildinfo

learningfoundry-0.25.0/CHANGELOG.md

@@ -0,0 +1,291 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+## [0.25.0] - 2026-04-15
+
+### Added
+
+- `pyproject.toml` — `readme`, `keywords`, `classifiers` (Beta, Apache, Python 3.12, Education, Code Generators, Typed), `[project.urls]` (Homepage, Repository, Bug Tracker, Changelog), `[tool.hatch.build.targets.sdist]` include list
+- `src/learningfoundry/sveltekit_template/` — template copied into package so it ships in the wheel
+
+### Fixed
+
+- `src/learningfoundry/generator.py` — `_TEMPLATE_DIR` now uses `Path(__file__).parent / "sveltekit_template"` (was `../../../sveltekit_template`); template now resolves correctly in installed environments
+
+### Verified
+
+- `pyve run hatch build` — `dist/learningfoundry-0.25.0-py3-none-any.whl` and `.tar.gz` produced
+- Wheel contains 31 `sveltekit_template/` files
+- `pip install dist/learningfoundry-0.25.0-py3-none-any.whl` in clean venv — `learningfoundry --version` → `0.25.0`; `_TEMPLATE_DIR.exists()` → `True`
+- `pyve test -q` — 195 passed
+
+## [0.24.0] - 2026-04-15
+
+### Added
+
+- `README.md` — full user-facing documentation: overview, installation, quick start, CLI reference (build/validate/preview with all flags and exit codes), curriculum YAML format with all 5 block types, configuration file reference, development setup, project structure
+
+## [0.23.0] - 2026-04-15
+
+### Added
+
+- `tests/test_smoke_sveltekit.py` — 6 end-to-end smoke tests (marked `smoke`, excluded from default `pyve test` run):
+  - `test_pnpm_install_succeeds` — `node_modules/` created
+  - `test_pnpm_build_produces_build_dir` — `build/` directory exists
+  - `test_build_produces_index_html` — `build/index.html` present
+  - `test_curriculum_json_present_in_build` — `build/curriculum.json` copied by vite
+  - `test_curriculum_json_valid_in_build` — JSON is valid with 2 modules
+  - `test_build_contains_js_assets` — at least one `.js` file in build output
+- `pyproject.toml` — registered `smoke` marker; smoke file excluded from `addopts` so `pyve test` stays fast
+- Smoke tests use `scope="module"` fixtures so `pnpm install` + `pnpm build` run once per session
+
+### Verified
+
+- `pyve test tests/test_smoke_sveltekit.py -v` — 6 passed in ~13 s
+- `pyve test -q` — 195 passed (smoke excluded, fast)
+- `ruff check .` and `mypy src/` — clean
+
+## [0.22.0] - 2026-04-15
+
+### Added
+
+- `pyproject.toml [tool.mypy]` — `strict = true`, `python_version = "3.12"`, `[[tool.mypy.overrides]]` for `quizazz_builder` (`ignore_missing_imports = true`)
+- `pyproject.toml [tool.ruff.lint]` — expanded select to `["E", "F", "I", "UP", "W", "B"]` (adds pycodestyle warnings + flake8-bugbear)
+- Installed `mypy` and `types-PyYAML` into testenv
+
+### Fixed
+
+- `src/learningfoundry/integrations/quizazz.py` — removed stale `# type: ignore[import-untyped]`; now covered by mypy overrides
+- `scripts/spike_e2e.py` — removed unused `shutil` import
+
+### Verified
+
+- `pyve testenv run ruff check .` — 0 errors (with W + B rules)
+- `pyve testenv run mypy src/` — 0 errors (16 source files, strict)
+- `pyve test -q` — 195 passed
+
+## [0.21.0] - 2026-04-15
+
+### Added
+
+- `tests/test_edge_cases.py` — 22 new tests across 6 classes:
+  - `TestEmptyCurriculum` — schema rejects empty modules/lessons; generator handles zero-module `ResolvedCurriculum`; `run_validate` returns False for empty-module YAML; lesson-with-no-blocks resolves fine
+  - `TestAllBlockTypesTogether` — all 5 block types resolved in order; all are `ResolvedContentBlock`; `curriculum.json` contains all 5 types
+  - `TestLargeCurriculum` — 5 modules × 4 lessons; all modules/lessons resolved; generated JSON counts correct; spot-check text content
+  - `TestIntegrationRunBuild` — full `run_build` with fixture curriculum (all block types) through real generator; `curriculum.json` has 2 modules; mod-01 has all 5 block types; `package.json` present
+  - `TestValidateResolutionErrors` — missing text-block file returns False with error; error message includes location context
+  - `TestOptionalFields` — missing `description` defaults to `""`; missing assessments resolve to `None`
+
+### Verified
+
+- `pyve test` — 195 passed, 0 failed
+
+## [0.20.0] - 2026-04-15
+
+### Added
+
+- `src/learningfoundry/cli.py` — `preview` subcommand: calls `run_preview()`, accepts `--port` (default 5173), prints `http://localhost:{port}` on success; same error/exit-code handling as `build`
+- `tests/test_cli.py` — 6 new preview tests: help, delegation to `run_preview`, URL output, default port, validation error exit, generation error exit (21 total CLI tests)
+
+## [0.19.0] - 2026-04-15
+
+### Added
+
+- `src/learningfoundry/cli.py` — `build` subcommand (parse→resolve→generate, `--config`, `--output`, `--base-dir`, `--log-level`); `validate` subcommand (parse→resolve only, reports OK/errors); exit codes 1=validation, 2=resolution, 3=generation, 4=config
+- `tests/test_cli.py` — 15 tests: `--help`/`--version`, build success/error paths, validate OK/invalid/missing/config-error
+- `tests/conftest.py` — `reset_learningfoundry_logger` autouse fixture; fixes caplog isolation across all test modules
+
+### Fixed
+
+- Cross-module `caplog` interference caused by `setup_logging()` leaving handlers on the `learningfoundry` logger — now reset after every test via `conftest.py`
+
+## [0.18.0] - 2026-04-15
+
+### Added
+
+- `sveltekit_template/src/lib/components/LessonView.svelte` — renders all content blocks for a lesson, marks lesson in-progress on mount, marks complete on nav-next, propagates quiz scores
+- `sveltekit_template/src/routes/+layout.svelte` — app shell: sidebar (`ModuleList`) + main content slot; loads module progress from SQLite reactively
+- `sveltekit_template/src/routes/+page.svelte` — landing page with `ProgressDashboard`
+- `sveltekit_template/src/routes/[module]/[lesson]/+page.svelte` — lesson route; syncs URL params to curriculum store; renders `LessonView`
+
+### Verified
+
+- `pnpm exec svelte-check` — 0 errors, 0 warnings
+- `pnpm build` — full adapter-static build succeeds; all routes compiled
+
+## [0.17.0] - 2026-04-15
+
+### Added
+
+- `sveltekit_template/src/lib/components/ProgressBar.svelte` — accessible progress bar with clamped percent and optional label
+- `sveltekit_template/src/lib/components/LessonList.svelte` — lesson list with status icons (✓/…/○) and active highlight
+- `sveltekit_template/src/lib/components/ModuleList.svelte` — collapsible module sidebar with per-module `ProgressBar`; auto-expands active module via `$effect`
+- `sveltekit_template/src/lib/components/Navigation.svelte` — prev/next lesson buttons using `lucide-svelte` chevrons; "Finish" on last lesson; fires `onComplete`
+- `sveltekit_template/src/lib/components/ProgressDashboard.svelte` — overall + per-module progress bars, pre/post assessment scores, start/continue/complete actions
+
+### Verified
+
+- `pnpm exec svelte-check` — 0 errors, 0 warnings
+
+## [0.16.0] - 2026-04-15
+
+### Added
+
+- `sveltekit_template/src/lib/utils/markdown.ts` — `renderMarkdown()` using `marked`
+- `sveltekit_template/src/lib/components/PlaceholderBlock.svelte` — generic "coming soon" placeholder
+- `sveltekit_template/src/lib/components/TextBlock.svelte` — renders markdown via `{@html}` with `$derived`
+- `sveltekit_template/src/lib/components/VideoBlock.svelte` — YouTube embed (converts watch/youtu.be URLs to embed URLs)
+- `sveltekit_template/src/lib/components/QuizBlock.svelte` — quizazz manifest placeholder; writes score to SQLite on complete
+- `sveltekit_template/src/lib/components/ExerciseBlock.svelte` — renders exercise content or stub placeholder
+- `sveltekit_template/src/lib/components/VisualizationBlock.svelte` — renders SVG/image or stub placeholder
+- `sveltekit_template/src/lib/components/ContentBlock.svelte` — type dispatcher for all block types
+- `sveltekit_template/package.json` — added `marked ^18.0.0`
+
+### Verified
+
+- `pnpm exec svelte-check` — 0 errors, 0 warnings
+
+## [0.15.0] - 2026-04-15
+
+### Added
+
+- `sveltekit_template/src/lib/db/database.ts` — sql.js init with WASM locator, IndexedDB persistence (`getDb()`, `persistDb()`), DDL for `lesson_progress`, `quiz_scores`, `exercise_status`
+- `sveltekit_template/src/lib/db/progress.ts` — `markLessonComplete()`, `markLessonInProgress()`, `getLessonProgress()`, `saveQuizScore()`, `getQuizScore()`, `updateExerciseStatus()`, `getModuleProgress()`
+- `sveltekit_template/src/lib/db/index.ts` — barrel re-export
+- `sveltekit_template/package.json` — `postinstall` script copies `sql-wasm.wasm` to `static/`; added `@types/sql.js ^1.4.11`
+- `sveltekit_template/static/.gitkeep` — tracks static dir in git
+- `.gitignore` — ignores `sveltekit_template/static/sql-wasm.wasm`
+
+### Verified
+
+- `pnpm exec svelte-check` — 0 errors
+
+## [0.14.0] - 2026-04-15
+
+### Added
+
+- `sveltekit_template/src/lib/types/index.ts` — all TypeScript interfaces: `TextContent`, `VideoContent`, `QuizManifest`, `QuizQuestion`, `QuizAnswer`, `ExerciseContent`, `VisualizationContent`, `ContentBlock`, `Lesson`, `Module`, `Curriculum`, `LessonProgress`, `QuizScore`, `ModuleProgress`, `CurriculumProgress`
+- `sveltekit_template/src/lib/stores/curriculum.ts` — `curriculum` readable (loads `curriculum.json`), `currentPosition` writable, derived stores `modules`, `currentModule`, `currentLesson`, `lessonSequence`, `currentIndex`, `previousLesson`, `nextLesson`, and `navigateTo/navigateNext/navigatePrev` helpers
+
+### Verified
+
+- `pnpm exec svelte-kit sync && pnpm exec svelte-check` — 0 errors
+
+## [0.13.0] - 2026-04-15
+
+### Added
+
+- `sveltekit_template/package.json` — full deps: `svelte@^5`, `@sveltejs/kit@^2`, `@sveltejs/adapter-static@^3`, `sql.js`, `lucide-svelte`; devDeps: `typescript`, `tailwindcss@^4`, `@tailwindcss/vite`, `vite@^8`, `@sveltejs/vite-plugin-svelte@^7`, `vitest@^3`, `prettier`, `prettier-plugin-svelte`, `svelte-check`
+- `sveltekit_template/svelte.config.js` — `adapter-static` with `vitePreprocess()`, `fallback: 'index.html'`
+- `sveltekit_template/vite.config.ts` — `tailwindcss()` + `sveltekit()` plugins
+- `sveltekit_template/tsconfig.json` — strict TypeScript config extending `.svelte-kit/tsconfig.json`
+- `sveltekit_template/src/app.html` — SvelteKit shell with `%sveltekit.head%` and `%sveltekit.body%`
+- `sveltekit_template/src/app.css` — Tailwind v4 `@import 'tailwindcss'`
+
+### Verified
+
+- `pnpm install && pnpm build` succeeds in `sveltekit_template/` (vite 8.0.8, adapter-static output to `build/`)
+
+## [0.12.0] - 2026-04-15
+
+### Added
+
+- `src/learningfoundry/generator.py` — `generate_app()`: atomically copies `sveltekit_template/` to output dir, writes `curriculum.json` to `static/`; overwrites with warning; raises `GenerationError` if template is missing
+- `sveltekit_template/package.json`, `sveltekit_template/svelte.config.js` — minimal template stubs (expanded in D.a)
+- `tests/test_generator.py` — 11 tests covering output structure, `curriculum.json` content, overwrite behavior, and missing template
+
+### Fixed
+
+- `tests/test_exceptions.py` — added `teardown_method` to `TestLoggingSetup` to restore `learningfoundry` logger state, fixing `caplog` interference in cross-module test runs
+
+## [0.11.0] - 2026-04-15
+
+### Added
+
+- `src/learningfoundry/pipeline.py` — `run_build()`, `run_validate()`, `run_preview()` orchestrating parse → resolve → generate; `run_validate()` returns `(bool, list[str])` without generating; `run_preview()` runs `pnpm install` + `pnpm run dev`
+- `tests/test_pipeline.py` — 11 tests covering end-to-end build, generator injection, error propagation, validate-only mode, and error capture
+- `tests/fixtures/content/mod-01/lesson-01.md`, `tests/fixtures/content/mod-02/lesson-02.md` — stub markdown content for fixture curriculum
+
+## [0.10.0] - 2026-04-15
+
+### Added
+
+- `src/learningfoundry/resolver.py` — `resolve_curriculum()` with `ResolvedCurriculum`, `ResolvedModule`, `ResolvedLesson`, `ResolvedContentBlock` dataclasses; resolves text (markdown read), video (URL pass-through), quiz/exercise/visualization (provider delegation), and pre/post assessments; raises `ContentResolutionError` with block location context
+- `tests/test_resolver.py` — 16 tests covering all block types, missing files, empty markdown warning, provider delegation, error wrapping with location, and assessment resolution
+
+## [0.9.0] - 2026-04-15
+
+### Added
+
+- `src/learningfoundry/integrations/quizazz.py` — `QuizazzProvider` delegating to `quizazz_builder.compile_assessment()`; wraps all errors in `IntegrationError`; raises `ImportError` with install instructions if `quizazz-builder` is not installed
+- `tests/test_integrations/test_quizazz.py` — 8 tests covering delegation, return value, error wrapping, error chaining, and missing package
+
+## [0.8.0] - 2026-04-15
+
+### Added
+
+- `src/learningfoundry/integrations/__init__.py` — integrations package
+- `src/learningfoundry/integrations/protocols.py` — `QuizProvider`, `ExerciseProvider`, `VisualizationProvider` Protocol classes
+- `src/learningfoundry/integrations/nbfoundry_stub.py` — `NbfoundryStub` returning placeholder `ExerciseContent` dict with `"status": "stub"`
+- `src/learningfoundry/integrations/d3foundry_stub.py` — `D3foundryStub` returning placeholder `VisualizationContent` dict with `"status": "stub"`
+- `tests/test_integrations/test_nbfoundry_stub.py` — 12 tests verifying stub structure matches `ExerciseContent` TypeScript interface
+- `tests/test_integrations/test_d3foundry_stub.py` — 13 tests verifying stub structure matches `VisualizationContent` TypeScript interface
+
+## [0.7.0] - 2026-04-15
+
+### Added
+
+- `src/learningfoundry/parser.py` — `parse_curriculum()` and `_dispatch_parser()`: loads YAML, extracts version, dispatches to schema, raises `CurriculumVersionError` / `CurriculumValidationError` on failure
+- `tests/test_parser.py` — 13 tests covering valid parsing, missing/null/unsupported/malformed version, malformed YAML, schema errors, and missing file
+
+## [0.6.0] - 2026-04-15
+
+### Added
+
+- `src/learningfoundry/schema_v1.py` — Pydantic v1 curriculum schema: all block types (`TextBlock`, `VideoBlock`, `QuizBlock`, `ExerciseBlock`, `VisualizationBlock`), `Lesson`, `Module`, `CurriculumDef`, `CurriculumV1` with validators for IDs, YouTube URLs, uniqueness, and minimum counts
+- `tests/fixtures/valid-curriculum.yml` — full fixture curriculum exercising all block types and assessments
+- `tests/test_schema_v1.py` — 35 tests covering valid parsing, all block types, invalid URLs, ID format, duplicate IDs, and missing required fields
+
+## [0.5.0] - 2026-04-15
+
+### Added
+
+- `src/learningfoundry/config.py` — `LoggingConfig`, `AppConfig` dataclasses and `load_config()` with CLI > config file > defaults precedence
+- `tests/test_config.py` — 16 tests covering defaults, file overrides, CLI overrides, malformed YAML, and unknown key warnings
+
+## [0.4.0] - 2026-04-15
+
+### Added
+
+- `src/learningfoundry/exceptions.py` — full exception hierarchy: `LearningFoundryError`, `ConfigError`, `CurriculumVersionError`, `CurriculumValidationError`, `ContentResolutionError`, `IntegrationError`, `GenerationError`
+- `src/learningfoundry/logging_config.py` — `setup_logging(level, output)` using stdlib `logging`
+- `tests/test_exceptions.py` — 17 tests covering hierarchy, string representations, and logging setup
+
+## [0.3.0] - 2026-04-15
+
+### Added
+
+- `scripts/spike_e2e.py` — throwaway end-to-end spike: YAML parse → content resolve → SvelteKit skeleton generation
+- `scripts/fixtures/spike-curriculum.yml` — minimal 1-module/1-lesson fixture curriculum
+- `scripts/fixtures/content/lesson-01.md` — stub markdown content for the spike
+
+## [0.2.0] - 2026-04-15
+
+### Added
+
+- `.github/workflows/publish.yml` — publishes sdist + wheel to PyPI on `v*` tag push via OIDC trusted publishing
+
+## [0.1.0] - 2026-04-15
+
+### Added
+
+- `src/learningfoundry/__init__.py` with `__version__ = "0.1.0"`
+- `src/learningfoundry/py.typed` PEP 561 marker
+- `src/learningfoundry/cli.py` Click entry point with `--version` flag
+- `src/learningfoundry/__main__.py` enabling `python -m learningfoundry`

learningfoundry-0.25.0/PKG-INFO

@@ -0,0 +1,346 @@
+Metadata-Version: 2.4
+Name: learningfoundry
+Version: 0.25.0
+Summary: A curriculum engine that turns a YAML curriculum definition into a deployable SvelteKit learning application.
+Project-URL: Homepage, https://github.com/pointmatic/learningfoundry
+Project-URL: Repository, https://github.com/pointmatic/learningfoundry
+Project-URL: Bug Tracker, https://github.com/pointmatic/learningfoundry/issues
+Project-URL: Changelog, https://github.com/pointmatic/learningfoundry/blob/main/CHANGELOG.md
+Author: Pointmatic
+License-Expression: Apache-2.0
+License-File: LICENSE
+Keywords: curriculum,education,elearning,lms,sveltekit
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Education
+Classifier: License :: OSI Approved :: Apache Software License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Education
+Classifier: Topic :: Software Development :: Code Generators
+Classifier: Typing :: Typed
+Requires-Python: >=3.12
+Requires-Dist: click>=8.1
+Requires-Dist: pydantic>=2.0
+Requires-Dist: pyyaml>=6.0
+Provides-Extra: quizazz
+Requires-Dist: quizazz-builder>=0.1; extra == 'quizazz'
+Description-Content-Type: text/markdown
+
+# learningfoundry
+
+[![License](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](LICENSE)
+[![Python](https://img.shields.io/badge/python-3.12%2B-blue)](https://www.python.org)
+
+A curriculum engine that turns a YAML curriculum definition into a deployable SvelteKit learning application — with interactive assessments, executable notebooks, and data visualizations — in a single pipeline.
+
+---
+
+## Table of Contents
+
+- [Overview](#overview)
+- [Installation](#installation)
+- [Quick Start](#quick-start)
+- [CLI Reference](#cli-reference)
+- [Curriculum YAML Format](#curriculum-yaml-format)
+- [Configuration File](#configuration-file)
+- [Development Setup](#development-setup)
+
+---
+
+## Overview
+
+`learningfoundry` takes a single `curriculum.yml` file and generates a fully self-contained [SvelteKit](https://kit.svelte.dev/) learning application. The generated app supports:
+
+- **Text** — Markdown content rendered in the browser
+- **Video** — YouTube embeds
+- **Quiz** — Interactive assessments via [quizazz-builder](https://github.com/pointmatic/quizazz-builder) (optional)
+- **Exercise** — Executable notebooks via nbfoundry (stub provided)
+- **Visualization** — D3-based charts via d3foundry (stub provided)
+
+Learner progress is persisted locally in SQLite (via sql.js) — no backend required.
+
+---
+
+## Installation
+
+```bash
+pip install learningfoundry
+```
+
+**With optional quizazz support:**
+
+```bash
+pip install "learningfoundry[quizazz]"
+```
+
+**Requirements:**
+
+- Python 3.12+
+- [pnpm](https://pnpm.io) (for `preview` command and generated app development)
+- Node.js 18+ (for the generated SvelteKit app)
+
+---
+
+## Quick Start
+
+1. **Create a curriculum file** (see [Curriculum YAML Format](#curriculum-yaml-format)):
+
+   ```bash
+   cat > curriculum.yml << 'EOF'
+   version: "1.0.0"
+   curriculum:
+     title: "My Course"
+     description: "A short description."
+     modules:
+       - id: mod-01
+         title: "Module One"
+         lessons:
+           - id: lesson-01
+             title: "Getting Started"
+             content_blocks:
+               - type: text
+                 ref: content/lesson-01.md
+               - type: video
+                 url: "https://www.youtube.com/watch?v=dQw4w9WgXcQ"
+   EOF
+   ```
+
+2. **Validate** the curriculum:
+
+   ```bash
+   learningfoundry validate
+   # OK — curriculum is valid.
+   ```
+
+3. **Build** the SvelteKit app:
+
+   ```bash
+   learningfoundry build
+   # Build complete → dist/
+   ```
+
+4. **Preview** locally (builds then starts a dev server):
+
+   ```bash
+   learningfoundry preview
+   # Preview server started at http://localhost:5173
+   ```
+
+---
+
+## CLI Reference
+
+### `learningfoundry build`
+
+Parse → resolve → generate a SvelteKit project.
+
+```
+Usage: learningfoundry build [OPTIONS]
+
+Options:
+  -c, --config PATH       Path to the curriculum YAML file.  [default: curriculum.yml]
+  --log-level LEVEL       Logging verbosity.  [default: INFO]
+                          Choices: DEBUG, INFO, WARNING, ERROR
+  -o, --output PATH       Output directory for the generated SvelteKit project.
+                          [default: dist]
+  --base-dir PATH         Base directory for content refs.
+                          (default: curriculum file's parent directory)
+  --help                  Show this message and exit.
+```
+
+**Exit codes:**
+
+| Code | Meaning |
+|------|---------|
+| 0 | Success |
+| 1 | Curriculum validation error |
+| 2 | Content resolution error (missing file, bad URL, etc.) |
+| 3 | SvelteKit generation error |
+| 4 | Configuration file error |
+
+---
+
+### `learningfoundry validate`
+
+Validate a curriculum YAML without generating any output.
+
+```
+Usage: learningfoundry validate [OPTIONS]
+
+Options:
+  -c, --config PATH       Path to the curriculum YAML file.  [default: curriculum.yml]
+  --log-level LEVEL       Logging verbosity.  [default: INFO]
+  --base-dir PATH         Base directory for resolving content refs.
+  --help                  Show this message and exit.
+```
+
+Prints `OK — curriculum is valid.` on success, or a list of errors and exits with code 1.
+
+---
+
+### `learningfoundry preview`
+
+Build then launch a local Vite dev server.
+
+```
+Usage: learningfoundry preview [OPTIONS]
+
+Options:
+  -c, --config PATH       Path to the curriculum YAML file.  [default: curriculum.yml]
+  --log-level LEVEL       Logging verbosity.  [default: INFO]
+  -o, --output PATH       Output directory for the generated SvelteKit project.
+                          [default: dist]
+  --base-dir PATH         Base directory for content refs.
+  --port INTEGER          Port for the local dev server.  [default: 5173]
+  --help                  Show this message and exit.
+```
+
+Runs `pnpm install` and `pnpm run dev` in the generated project directory. Requires `pnpm` on `PATH`.
+
+---
+
+## Curriculum YAML Format
+
+```yaml
+version: "1.0.0"
+
+curriculum:
+  title: "Course Title"           # required
+  description: "Course overview." # optional
+
+  modules:
+    - id: mod-01                  # required, kebab-case
+      title: "Module One"         # required
+      description: "..."          # optional
+
+      # Optional pre/post assessments (requires quizazz-builder)
+      pre_assessment:
+        source: quizazz
+        ref: assessments/mod-01-pre.yml
+
+      post_assessment:
+        source: quizazz
+        ref: assessments/mod-01-post.yml
+
+      lessons:
+        - id: lesson-01           # required, kebab-case; unique within module
+          title: "Lesson One"     # required
+
+          content_blocks:
+
+            # Text block — Markdown file
+            - type: text
+              ref: content/mod-01/lesson-01.md
+
+            # Video block — YouTube URL only
+            - type: video
+              url: "https://www.youtube.com/watch?v=XXXXXXXXXXX"
+
+            # Quiz block — requires learningfoundry[quizazz]
+            - type: quiz
+              source: quizazz
+              ref: assessments/mod-01-quiz.yml
+
+            # Exercise block — requires nbfoundry (stub included)
+            - type: exercise
+              source: nbfoundry
+              ref: exercises/mod-01-exercise.yml
+
+            # Visualization block — requires d3foundry (stub included)
+            - type: visualization
+              source: d3foundry
+              ref: visualizations/mod-01-vis.yml
+```
+
+**Rules:**
+
+- Module and lesson `id` values must be unique within their scope, and match the pattern `[a-z0-9][a-z0-9-]*`.
+- Every curriculum must have at least one module; every module at least one lesson.
+- All `ref` paths are resolved relative to `--base-dir` (default: directory containing the curriculum YAML).
+- Only YouTube URLs are accepted for `video` blocks (`youtube.com/watch?v=` or `youtu.be/`).
+
+---
+
+## Configuration File
+
+An optional config file can set defaults for logging. The CLI always takes precedence.
+
+**Default location:** `~/.config/learningfoundry/config.yml`
+
+```yaml
+logging:
+  level: INFO      # DEBUG | INFO | WARNING | ERROR
+  output: stdout   # stdout | stderr
+```
+
+Pass a custom config location with `-c / --config`.
+
+---
+
+## Development Setup
+
+### Prerequisites
+
+- Python 3.12+
+- [pyve](https://github.com/pointmatic/pyve) (virtual env manager used in this project)
+- pnpm 9+ and Node.js 18+
+
+### Setup
+
+```bash
+git clone https://github.com/pointmatic/learningfoundry.git
+cd learningfoundry
+
+# Create the Python environment and install the package in editable mode
+pyve init
+pip install -e .
+
+# Create the test runner environment and install dev dependencies
+pyve testenv --init
+pyve testenv --install -r requirements-dev.txt
+```
+
+### Running Tests
+
+```bash
+# Fast unit + integration tests (~2 min)
+pyve test
+
+# End-to-end SvelteKit smoke tests (requires pnpm, ~15 s extra)
+pyve test tests/test_smoke_sveltekit.py -v
+```
+
+### Linting and Type Checking
+
+```bash
+pyve testenv run ruff check .
+pyve testenv run mypy src/
+```
+
+### Project Structure
+
+```
+learningfoundry/
+├── src/learningfoundry/
+│   ├── cli.py              # Click CLI entry point
+│   ├── config.py           # Configuration loading
+│   ├── exceptions.py       # Exception hierarchy
+│   ├── generator.py        # SvelteKit project generator
+│   ├── integrations/       # Quiz / exercise / visualization providers
+│   ├── logging_config.py   # Logging setup
+│   ├── parser.py           # YAML parser + version dispatch
+│   ├── pipeline.py         # run_build / run_validate / run_preview
+│   ├── resolver.py         # Content reference resolver
+│   └── schema_v1.py        # Pydantic v1 curriculum schema
+├── sveltekit_template/     # SvelteKit app template (copied on build)
+├── tests/                  # pytest test suite
+├── requirements-dev.txt    # Dev dependencies
+└── pyproject.toml          # Build config, ruff, mypy, pytest settings
+```
+
+---
+
+## License
+
+Apache 2.0 — see [LICENSE](LICENSE).