learningfoundry 0.62.2__tar.gz → 0.69.1__tar.gz

{learningfoundry-0.62.2 → learningfoundry-0.69.1}/.gitignore

@@ -39,4 +39,11 @@ node_modules/
 *.tsbuildinfo
 
 # project-guide
-docs/project-guide/**/*.bak.*
+/docs/project-guide/.metadata.yml
+/docs/project-guide/README.md
+/docs/project-guide/developer/
+/docs/project-guide/templates/
+/docs/project-guide/**/*.bak.*
+
+# Project
+/scripts/data/

{learningfoundry-0.62.2 → learningfoundry-0.69.1}/CHANGELOG.md

@@ -7,6 +7,141 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.69.1] - 2026-05-18
+
+### Added
+
+- **`CurriculumMeta`** — new optional `meta:` block on the top-level `curriculum:` mapping (Story J.h). Mirrors the existing `LessonMeta` / `ModuleMeta` shape with three declared fields (`target_audience`, `objectives`, `prerequisites`) plus `extra="allow"` so authors can attach curriculum-wide pedagogical context without forcing a schema change. Threaded through the resolver into `curriculum.json`; mirrored in the SvelteKit `Curriculum` TypeScript interface. Rendering is deferred to a later phase, matching the J.a precedent for `ModuleMeta`.
+- **Project-specific schema extensions** — opt-in mechanism for tightening the three `meta` blocks' `extra="allow"` posture into strict whitelist-reject validation (Story J.h). When `learningfoundry-schema-extensions.yml` is present next to `curriculum.yml`, learningfoundry synthesizes strict subclasses of `CurriculumMeta` / `ModuleMeta` / `LessonMeta` with project-declared fields appended and `extra` flipped to `forbid`. Motivated by LLM-driven authoring workflows where phantom fields (typos like `prequisites` instead of `prerequisites`) silently pass `extra="allow"` and get lost in the resolved JSON.
+- **`--schema-extensions PATH`** CLI flag on `build`, `validate`, and `preview`. Resolution order: CLI flag > `[tool.learningfoundry] schema_extensions = "..."` in `pyproject.toml` next to the curriculum > auto-discovery of `learningfoundry-schema-extensions.yml` next to the curriculum > none (base behaviour preserved).
+- **Supported extension field types:** `str`, `int`, `bool`, `list[str]`, `enum` (with `values:` list). Per-field `required: bool` (default `true`) and `default:` (optional — presence makes the field optional regardless of `required`).
+- **`SchemaExtensionError`** — new typed exception for missing / malformed / invalid extension files. Mapped to exit code 4 (`EXIT_CONFIG`) in the CLI.
+- **New module:** [`src/learningfoundry/schema_extensions.py`](src/learningfoundry/schema_extensions.py) with `SchemaExtensions`, `MetaExtensions`, five discriminated `FieldDef` variants, `build_extended_meta_models`, `build_extended_curriculum_v1`, `load_schema_extensions`.
+- **Tests:** [`tests/test_schema_extensions.py`](tests/test_schema_extensions.py) — 45 cases covering base behaviour preservation, strict whitelist rejection, every supported field type, required/default rules, per-model `extra` override, `CurriculumMeta` extension propagation, end-to-end through `parse_curriculum` and `run_validate`, file-path resolution precedence, CLI invocation via Click `CliRunner`, and strict validation of the extension file itself. Plus 6 new `CurriculumMeta` cases in `test_schema_v1.py` and 2 round-trip cases in `test_resolver.py`.
+- **Docs:** new "Strict project-specific extensions" subsection in [README.md](README.md) and `CurriculumMeta` entry in the meta reference; new "Project-specific `meta` schema extensions" subsection in [docs/specs/features.md](docs/specs/features.md); new `schema_extensions.py` subsection plus `CurriculumMeta` in the schema overview in [docs/specs/tech-spec.md](docs/specs/tech-spec.md).
+
+### Notes
+
+- Backward compatible: when no extensions file is found, today's `extra="allow"` behaviour is preserved bit-for-bit. No existing curriculum needs to change.
+- The mechanism is scoped to `meta` blocks (`CurriculumMeta`, `ModuleMeta`, `LessonMeta`) — `Lesson`, `Module`, `CurriculumDef` themselves stay unconditionally strict. `Hook` extensions are deferred (small surface, no asks).
+- A Python-module schema hook (`schema_module = "..."`) is recorded as a possible follow-up if a curriculum ever needs cross-field validators.
+
+## [0.69.0] - 2026-05-08
+
+### Added
+
+- **Sidebar module flow renders assessments at their resolved positions** (Story J.f). [LessonList.svelte](src/learningfoundry/sveltekit_template/src/lib/components/LessonList.svelte) now interleaves assessment rows with lesson rows according to each assessment's `position`: `before_lessons` at the top, `{ before_lesson: <id> }` / `{ after_lesson: <id> }` around the named lesson, `after_lessons` at the bottom. Order in `module.assessments` is the canonical iteration order — the resolver emitted it that way and the component does not re-resolve placement.
+- **Role label + pass-threshold annotation on each assessment row.** Role rendered capitalized (`pre` → `Pre Assessment`); `pass_threshold` rendered as a secondary `"70% to pass"` annotation when set. Rows are non-interactive — gating semantics is a future concern.
+- **`interleaveModuleFlow`, `capitalizeRole`, `formatPassThreshold`** helpers in [module-list.helpers.ts](src/learningfoundry/sveltekit_template/src/lib/components/module-list.helpers.ts) plus 10 new unit tests in `module-list.test.ts` and 5 new DOM tests in `LessonList.test.ts`.
+- [ModuleList.svelte](src/learningfoundry/sveltekit_template/src/lib/components/ModuleList.svelte) now passes `mod.assessments` to `LessonList`.
+
+### Phase J close (Story J.g)
+
+- **Cross-cutting Phase J smoke fixture** at [tests/fixtures/phase-j-curriculum.yml](tests/fixtures/phase-j-curriculum.yml) and [tests/fixtures/phase-j-content/](tests/fixtures/phase-j-content/) exercises every Phase J affordance — lesson + module `meta`, all three tutorial directives, all three assessment roles with mixed positions, and `duration_minutes` aggregation — in a single curriculum. The new [tests/test_phase_j_smoke.py](tests/test_phase_j_smoke.py) (9 cases) pins the composition end-to-end through parse → resolve → generate. Per-feature tests stay narrow; this one is the integration anchor.
+- **README "Pedagogical authoring" section** stitches the per-feature docs into a single author-facing story with a worked example covering meta blocks, tutorial directives, and the `assessments[]` array. Includes a migration paragraph for `pre_assessment` / `post_assessment` → `assessments[]` for any external curriculum that pre-dates v0.68.0.
+- **features.md FR-2** now has a brief "Phase J: Pedagogical authoring" header tying the J.a–J.f subsections together and pointing at the integration test.
+
+J.g is doc + integration-test only — shares the v0.69.0 release with J.f, no extra version bump.
+
+### Notes
+
+- Defensive belt: a lesson-anchored assessment whose target lesson does not exist is silently dropped at render time. The parser already rejects unknown refs at build time (`Module.validate_assessment_lesson_refs`); this guard ensures the component does not crash if one slips through.
+- Mid-lesson assessment placement, gating ("must pass post to advance"), per-role styling beyond label text, and assessment-specific routes remain out of scope.
+
+## [0.68.0] - 2026-05-08
+
+### Removed (BREAKING)
+
+- **`Module.pre_assessment` / `Module.post_assessment`** are gone from the curriculum schema, the resolved-curriculum dataclass, the generated `curriculum.json`, and the SvelteKit `Module` TypeScript interface (Story J.e). No alias, no deprecation warning, no shim — pre-1.0 makes the clean break acceptable. Curriculum YAML authors **must** migrate to the new `assessments[]` array; an unmigrated `pre_assessment` / `post_assessment` field at module level now produces a `ValidationError` from strict-mode Pydantic.
+- ProgressDashboard's "Pre-assessment: X/Y" / "Post-assessment: X/Y" inline score rows are gone. The per-learner score data still lives in IndexedDB; a future story rebuilds the score-display UI atop the new shape.
+
+### Added
+
+- **`Module.assessments: list[AssessmentDefinition]`** — generalized array replacing the two-slot pre/post (Story J.e). Each `AssessmentDefinition` carries:
+  - `role`: open string (conventional values `pre`, `practice`, `post`, `checkpoint`).
+  - `position`: discriminated union — `"before_lessons"` / `"after_lessons"` / `{ before_lesson: <id> }` / `{ after_lesson: <id> }`.
+  - `source`, `ref`, optional `pass_threshold`.
+- **Parse-time lesson-id validation.** A `model_validator` on `Module` rejects assessments whose `before_lesson` / `after_lesson` ref names a lesson that does not exist in the module, with an error message naming the module id, the assessment role, and the unknown lesson id.
+- **Resolver materializes canonical assessment order.** `_resolve_assessments` walks the `assessments` array and emits a `ResolvedAssessment` list in placement order: `before_lessons` first, then for each lesson the `before_lesson` and `after_lesson` anchors, then `after_lessons`. Order is the canonical iteration order; each entry retains its original `position` (serialized as JSON-friendly string or single-key mapping) so the frontend can interleave at render time.
+- **TypeScript `AssessmentDefinition` and `AssessmentPosition` types** in [lib/types/index.ts](src/learningfoundry/sveltekit_template/src/lib/types/index.ts).
+
+### Notes
+
+- Frontend rendering of assessments at their resolved positions in the module flow lands in **Story J.f** (v0.69.0). Until then, `module.assessments[]` is plumbed through end-to-end but no UI surfaces it.
+- `pass_threshold` is recorded but not enforced in v1 — gating semantics is a future concern that may also touch the progress-DB schema.
+
+## [0.67.1] - 2026-05-08
+
+### Added
+
+- **Build-time lint for unbalanced tutorial-scaffold directives** (Story J.d.2). New [directives.py](src/learningfoundry/directives.py) (`lint_directives`) scans every `text` content block's markdown for `::: worked-example` / `::: faded-example` / `::: independent-practice` opens with no matching `:::` close on its own line, and raises `ContentResolutionError` with the lesson location and the 1-based opening line number. Hooked into [resolver.py](src/learningfoundry/resolver.py) `_resolve_text` after the markdown is read but before image-asset resolution, so authors get a build-time error rather than discovering the problem as a render-time anomaly.
+- Lint is conservative by design: only the three known directive names are tracked; unknown names (`::: tip`) pass through untouched, and lines inside fenced code blocks (``` or `~~~`) are skipped so prose that demonstrates the directive syntax isn't mistaken for an actual directive.
+- tech-spec.md gained a `directives.py` subsection documenting the lint contract and the TS↔Python coupling on the `KNOWN_DIRECTIVES` list.
+
+## [0.67.0] - 2026-05-08
+
+### Added
+
+- **Tutorial scaffold container directives in lesson markdown** (Story J.d.1). Three named container directives — `::: worked-example`, `::: faded-example`, `::: independent-practice` — recognised by a custom `marked` extension at [markdown-directives.ts](src/learningfoundry/sveltekit_template/src/lib/utils/markdown-directives.ts). Each directive opens with `::: <name>` on its own line and closes with `:::` on its own line; inner content is itself markdown so headings, lists, math, and emphasis nest naturally.
+- **CSS for the three directive treatments** in [app.css](src/learningfoundry/sveltekit_template/src/app.css): `lf-directive-worked-example` = filled gray card; `lf-directive-faded-example` = outlined dim card; `lf-directive-independent-practice` = amber-highlighted challenge prompt. Pure CSS so the styles ship in the bundled output regardless of Tailwind content-detection.
+- README "Tutorial scaffold directives" section with author-facing examples; features.md FR-3 subsection documenting the rendering contract.
+
+### Notes
+
+- Unknown directive names (e.g. `::: tip`) pass through untouched at render time. The Python-side lint that flags malformed or unknown directive blocks at build time lands in **Story J.d.2** (v0.67.1).
+- Static styling only — interactivity (progressive reveal, hint toggles, checkmark affordances) is out of scope.
+
+## [0.66.0] - 2026-05-08
+
+### Added
+
+- **Curriculum-wide aggregate time estimate** (Story J.c). [generator.py](src/learningfoundry/generator.py) sums every lesson's `meta.duration_minutes` and emits the result as `curriculum.total_duration_minutes` at the top level of `curriculum.json`. Lessons without `meta` or without `duration_minutes` are skipped; when no lesson contributes, the field is `null`.
+- **Index page renders the estimate above the dashboard** when non-null, formatted as `≈ Xh Ym` (or `≈ Xm` under an hour, `≈ Xh` for whole-hour totals). Hidden entirely when `total_duration_minutes` is `null`. New helper [duration.ts](src/learningfoundry/sveltekit_template/src/lib/utils/duration.ts) (`formatDurationEstimate`) owns the formatting; [+page.svelte](src/learningfoundry/sveltekit_template/src/routes/+page.svelte) renders it.
+- TypeScript `Curriculum` interface gained `total_duration_minutes?: number | null` ([lib/types/index.ts](src/learningfoundry/sveltekit_template/src/lib/types/index.ts)).
+
+### Notes
+
+- Per-module aggregation, learner-elapsed-time display, and adaptive estimates from past learner pace remain out of scope (Phase J / J.c).
+
+## [0.65.0] - 2026-05-08
+
+### Added
+
+- **Lesson role chip in the sidebar** (Story J.b). When `lesson.meta.role` is set, [LessonList.svelte](src/learningfoundry/sveltekit_template/src/lib/components/LessonList.svelte) renders a small uppercase chip (e.g. `OPENER`, `PRACTICE`) at the right edge of the lesson row, distinct in styling from the progress glyph and the locked-row indicator. Hidden when `meta.role` is absent.
+- **Lesson hook tagline above the title** (Story J.b). When `lesson.meta.hook.tagline` is set, [LessonView.svelte](src/learningfoundry/sveltekit_template/src/lib/components/LessonView.svelte) renders the tagline as a quiet italic line directly above the `<h1>` lesson title. Hidden when absent.
+- Test fixture [valid-curriculum.yml](tests/fixtures/valid-curriculum.yml) now exercises lesson and module `meta` end-to-end; smoke test pins the meta-passthrough data contract on the production `build/curriculum.json`.
+
+### Notes
+
+- `hook.image_prompt` is intentionally not rendered — no consumer exists pre image-generation pipeline.
+- Module-level `meta.theme` rendering on the module index and `meta.duration_minutes` aggregation land in subsequent Phase J stories.
+
+## [0.64.0] - 2026-05-08
+
+### Added
+
+- **Pedagogical metadata on lessons and modules** (Story J.a — Phase J kickoff). New `Hook`, `LessonMeta`, and `ModuleMeta` Pydantic models in [schema_v1.py](src/learningfoundry/schema_v1.py); optional `meta` fields on `Lesson` and `Module`. `LessonMeta` carries `role`, `hook` (`tagline` + optional `image_prompt`), `introduces`, `reinforces`, and `duration_minutes`; `ModuleMeta` carries `theme`, `big_problem`, `objectives`, `experiential_summary`, and `target_audience`. All meta models use `extra="allow"` so authors can attach genre-specific fields without schema churn.
+- **`meta` propagated verbatim into `curriculum.json`.** [resolver.py](src/learningfoundry/resolver.py) carries the resolved meta dicts on `ResolvedLesson` and `ResolvedModule`; [generator.py](src/learningfoundry/generator.py) emits them through `dataclasses.asdict`. Absent meta serializes as `"meta": null`.
+- **TypeScript mirrors** for `Hook`, `LessonMeta`, and `ModuleMeta` in [lib/types/index.ts](src/learningfoundry/sveltekit_template/src/lib/types/index.ts).
+
+### Notes
+
+- No frontend rendering of `meta` yet — surfacing of `meta.role` and `meta.hook.tagline` lands in Story J.b; `duration_minutes` aggregation lands in Story J.c.
+
+## [0.63.0] - 2026-05-03
+
+### Added
+
+- **`WasmAssetMissingError` is now visible to the learner** (Story I.bb). When `Database.getDb()` rejects because `/sql-wasm.wasm` is unavailable, a persistent layout-level banner appears above the main content area: "Progress recording is paused. Your activity in this session will not be saved. Try refreshing to retry." with a Refresh CTA that calls `location.reload()`. Pre-fix the failure was CLI-log-only — the learner saw checkmarks fail to land, no in-progress icons, no module advancement, and no UI signal explaining why. Story I.aa hardened the asset pipeline so this should be rare in deployed apps; Story I.bb closes the loop on what the learner actually sees if it ever recurs (asset-pipeline regression, deploy misconfiguration, browser cache poisoning, network partition).
+- New [src/lib/stores/db-init.ts](src/learningfoundry/sveltekit_template/src/lib/stores/db-init.ts) — `dbInit` writable store (`pending` | `ready` | `wasm-missing` | `failed`) plus an idempotent `initializeDatabase()` that drives the store from a one-shot `database.getDb()` call wired into `+layout.svelte`. Single-signal layout-level surfacing (option (c) from the story design notes), so per-write rejections don't have to handle the case independently.
+- New [RecordingPausedBanner.svelte](src/learningfoundry/sveltekit_template/src/lib/components/RecordingPausedBanner.svelte) renders only when `dbInit` is in `wasm-missing` state. AlertTriangle icon, amber palette, accessible `role="status"` + `aria-live="polite"`.
+
+### Changed
+
+- **`progress.ts` swallows `WasmAssetMissingError` at the repository boundary.** Once the layout banner is up, per-call rejections are an information duplicate that every UI call site would have to defend against. Writes (`markLessonComplete` / `markLessonOpened` / `markLessonInProgress` / `saveQuizScore` / `updateExerciseStatus` / `resetProgress`) resolve as no-ops; reads (`getLessonProgress`, `getQuizScore`) return `null`; `getModuleProgress` returns an empty `not_started` shape so the dashboard renders the empty state instead of an error page. Non-WASM errors still propagate. Module-level doc comment in [progress.ts](src/learningfoundry/sveltekit_template/src/lib/db/progress.ts) documents the rule so a future maintainer doesn't refactor the catches away.
+- **`+layout.svelte`** wraps `<main>` in a flex column that hosts the banner above the scrollable content region; main keeps `overflow-y-auto`, banner stays pinned at the top.
+- **[features.md](docs/specs/features.md) FR-4** now documents the recording-paused state as a hard requirement (closes the requirements gap Story I.aa identified).
+
 ## [0.62.2] - 2026-05-02
 
 ### Fixed

{learningfoundry-0.62.2 → learningfoundry-0.69.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: learningfoundry
-Version: 0.62.2
+Version: 0.69.1
 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
@@ -48,6 +48,7 @@ A curriculum engine that turns a YAML curriculum definition into a deployable Sv
 - [Video blocks](#video-blocks)
 - [Lesson titles and markdown headings](#lesson-titles-and-markdown-headings)
 - [Images and assets](#images-and-assets)
+- [Pedagogical authoring](#pedagogical-authoring)
 - [Content locking](#content-locking)
 - [Configuration File](#configuration-file)
 - [Development Setup](#development-setup)
@@ -219,14 +220,28 @@ curriculum:
       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
+      # Optional assessments (requires quizazz-builder).
+      # Each assessment carries an open-string `role` and a `position`
+      # (`before_lessons`, `after_lessons`, or `{ before_lesson: <id> }`
+      # / `{ after_lesson: <id> }`). The order in `assessments` after
+      # build is the canonical placement order.
+      assessments:
+        - role: pre
+          position: before_lessons
+          source: quizazz
+          ref: assessments/mod-01-pre.yml
+
+        - role: practice
+          position: { before_lesson: lesson-04 }
+          source: quizazz
+          ref: assessments/mod-01-practice.yml
+          pass_threshold: 0.7
+
+        - role: post
+          position: after_lessons
+          source: quizazz
+          ref: assessments/mod-01-post.yml
+          pass_threshold: 0.8
 
       lessons:
         - id: lesson-01           # required, kebab-case; unique within module
@@ -390,6 +405,211 @@ For production deployment to a CDN, just run `cd dist && pnpm build` — the `st
 
 ---
 
+## Pedagogical authoring
+
+Phase J adds first-class authoring affordances for the worked-example → faded-example → independent-practice progression and for declaring pedagogical context the build pipeline can act on. Three building blocks compose into one story:
+
+1. **`meta` blocks** declare the *intent* of a module or lesson — its theme, role, opening hook, learning items, and time estimate.
+2. **Container directives** in lesson markdown style worked / faded / independent-practice cards inline.
+3. **`assessments[]`** on each module places quizzes at named positions (before all lessons, before/after a specific lesson, after all lessons) — replacing the legacy `pre_assessment` / `post_assessment` pair (see migration note below).
+
+A small worked example bringing the three together:
+
+```yaml
+modules:
+  - id: mod-01
+    title: "Why convolutions exist"
+
+    meta:
+      theme: "Why convolutions exist"
+      objectives:
+        - "Explain why FC nets fail on images"
+        - "Describe weight sharing"
+      target_audience: "Intermediate Python; high-school math"
+
+    assessments:
+      - role: pre
+        position: before_lessons
+        source: quizazz
+        ref: assessments/mod-01-pre.yml
+      - role: practice
+        position: { before_lesson: lesson-02 }
+        source: quizazz
+        ref: assessments/mod-01-practice.yml
+        pass_threshold: 0.7
+      - role: post
+        position: after_lessons
+        source: quizazz
+        ref: assessments/mod-01-post.yml
+        pass_threshold: 0.8
+
+    lessons:
+      - id: lesson-01
+        title: "What is a convolution?"
+        meta:
+          role: opener
+          hook:
+            tagline: "What if your first layer of vision was just a flashlight on the world?"
+          introduces: [receptive_field, simple_cells]
+          duration_minutes: 15
+        content_blocks:
+          - type: text
+            ref: content/mod-01/lesson-01.md
+```
+
+And the lesson markdown can sprinkle in the three directives:
+
+```markdown
+# What is a convolution?
+
+::: worked-example
+Compute the output shape for a 32×32 input, 3×3 kernel, stride 1, padding 0.
+
+We apply $(W - K + 2P) / S + 1 = 30$. Output: **30×30**.
+:::
+
+::: faded-example
+For a 64×64 input, 5×5 kernel, stride 1, padding 2 — what's the output shape?
+:::
+
+::: independent-practice
+Given a 28×28 input, design a `Conv2d` that outputs 14×14. State your kernel, stride, and padding.
+:::
+```
+
+### `meta` reference
+
+**Lesson `meta`** carries:
+- `role` — open string, conventional values `opener`, `concept`, `story`, `math`, `tutorial`, `practice`, `hands_on`, `bonus`. Renders as a small chip in the sidebar.
+- `hook` — `{ tagline, image_prompt? }`. The tagline renders as a quiet italic line above the lesson title.
+- `introduces` / `reinforces` — lists of learning-item ids (open vocabulary; useful for downstream tooling).
+- `duration_minutes` — integer; aggregated across the curriculum into `total_duration_minutes` and surfaced on the index page as `≈ Xh Ym`.
+
+**Module `meta`** carries:
+- `theme`, `big_problem`, `objectives`, `experiential_summary`, `target_audience`. Rendering of these is deferred; today they pass through to `curriculum.json` for downstream tooling.
+
+**Curriculum `meta`** (Story J.h) carries:
+- `target_audience`, `objectives`, `prerequisites`. Curriculum-wide pedagogical context — passed through to `curriculum.json` for downstream tooling, no rendering in v1.
+
+### Custom `meta` fields
+
+Both `LessonMeta` and `ModuleMeta` (and the `hook` sub-block) accept undeclared fields — authors can attach genre-specific data alongside the declared ones without a schema change:
+
+```yaml
+lessons:
+  - id: lesson-01
+    title: "What is a convolution?"
+    meta:
+      # Declared fields — type-checked:
+      role: opener
+      introduces: [receptive_field]
+      duration_minutes: 15
+
+      # Author-defined extras — accepted as-is:
+      covers: ["pe:hubel-wiesel", "hi:receptive-field-discovery"]
+      difficulty: intermediate
+      prerequisites: [lesson-00]
+      author_notes: "Revisit after the kernel-size deep-dive lands."
+    content_blocks:
+      - type: text
+        ref: content/mod-01/lesson-01.md
+```
+
+The escape hatch is scoped to `meta` (and `hook`) only. `Lesson`, `Module`, and the top-level `curriculum:` reject unknown fields, so a misplaced `difficulty:` at the lesson level (sibling of `meta`, not nested inside it) still fails the build — the strictness that catches typos like a mis-nested `sequential: true` is preserved everywhere outside the `meta` blocks.
+
+Declared fields keep their normal type checks; only undeclared keys ride through unvalidated. Extras pass through unchanged into the generated `curriculum.json`, so downstream tooling (custom Svelte components, analytics dashboards, external reports) can read them without any further pipeline wiring.
+
+### Strict project-specific extensions
+
+The permissive `extra="allow"` posture above is too loose for LLM-driven authoring — an LLM that writes `prequisites` instead of `prerequisites` will pass validation, lose the data in `curriculum.json`, and break downstream consumers silently. The schema-extensions mechanism is an opt-in tightening: a project drops `learningfoundry-schema-extensions.yml` next to its `curriculum.yml`, declares the additional fields it cares about, and learningfoundry flips the `meta` blocks from "allow anything" to "reject anything not on the list."
+
+Minimal example — `learningfoundry-schema-extensions.yml`:
+
+```yaml
+version: "1"
+lesson_meta:
+  fields:
+    covers:        { type: list[str], default: [] }
+    difficulty:    { type: enum, values: [intro, intermediate, advanced] }
+    prerequisites: { type: list[str], default: [] }
+```
+
+With this file in place:
+
+```yaml
+# curriculum.yml lesson — typo `prequisites` instead of `prerequisites`
+meta:
+  difficulty: intermediate
+  prequisites: [lesson-00]   # ❌ now a build error
+```
+
+`learningfoundry validate` exits non-zero with a message naming the offending field (the Pydantic `ValidationError` puts `prequisites` directly in the output). Without the extensions file, the same typo silently passes — the original `extra="allow"` posture is preserved.
+
+**Supported field types:** `str`, `int`, `bool`, `list[str]`, `enum` (with `values:` list). Each field accepts `required: bool` (default `true`) and `default:` (presence makes the field optional). Per-model `extra: allow` overrides the default `extra: forbid` if you want one meta layer tight and another loose during a staged rollout.
+
+**File-path resolution order** (highest precedence first):
+
+1. `--schema-extensions PATH` CLI flag on `build`, `validate`, `preview`.
+2. `[tool.learningfoundry] schema_extensions = "..."` in `pyproject.toml` next to the curriculum.
+3. Auto-discovery: `learningfoundry-schema-extensions.yml` next to the curriculum.
+4. None — base `extra="allow"` behaviour, no enforcement.
+
+The extensions file is itself strict-validated, so a typo there (e.g. `defalt:` instead of `default:`) fails at load time naming the field, not silently degrading the contract the file is supposed to tighten. The mechanism applies to all three meta layers (`curriculum_meta`, `module_meta`, `lesson_meta`) independently — declaring one does not require declaring the others.
+
+### Tutorial scaffold directives
+
+Three named container directives:
+
+- `::: worked-example` — filled gray card. Use it for fully worked solutions.
+- `::: faded-example` — outlined dim card. Use it for similar problems with reduced scaffolding.
+- `::: independent-practice` — amber-highlighted challenge prompt. Use it for problems the learner solves on their own.
+
+Inner markdown (headings, lists, math, emphasis) renders normally inside each directive. Unknown directive names pass through untouched at render time. Static styling only — no progressive-reveal interactivity in v1. An unbalanced known-name block (open with no `:::` close on its own line) fails the build with the lesson location, so the failure mode is loud rather than rendered as silent prose.
+
+### Assessments
+
+Each module declares an `assessments[]` array; each entry carries:
+
+- `role` — open string. Conventional values: `pre`, `practice`, `post`, `checkpoint`. Surfaces as a capitalized label in the sidebar (`Pre Assessment`, `Practice Assessment`, …).
+- `position` — discriminated union:
+  - `before_lessons` — anchors at the start of the module flow.
+  - `after_lessons` — anchors at the end.
+  - `{ before_lesson: <lesson-id> }` — anchors immediately before the named lesson.
+  - `{ after_lesson: <lesson-id> }` — anchors immediately after.
+- `source`, `ref` — provider + path, same shape as `quiz` content blocks.
+- `pass_threshold` — optional `0.0`–`1.0`. Recorded but not gating in v1; surfaces as a `"X% to pass"` annotation on the assessment row when set.
+
+Lesson-anchored refs (`before_lesson` / `after_lesson`) are validated against the module's `lessons` at build time — typing a wrong lesson id fails the build with the module id, role, and unknown lesson id.
+
+### Migrating from `pre_assessment` / `post_assessment` (pre-v0.68.0)
+
+`Module.pre_assessment` and `Module.post_assessment` were removed in v0.68.0 (Story J.e). To migrate an external curriculum that pre-dates the cutover, replace each block with a single `assessments[]` entry using the `before_lessons` or `after_lessons` position:
+
+```yaml
+# BEFORE (v0.67.x and earlier)
+pre_assessment:
+  source: quizazz
+  ref: assessments/mod-01-pre.yml
+post_assessment:
+  source: quizazz
+  ref: assessments/mod-01-post.yml
+
+# AFTER (v0.68.0+)
+assessments:
+  - role: pre
+    position: before_lessons
+    source: quizazz
+    ref: assessments/mod-01-pre.yml
+  - role: post
+    position: after_lessons
+    source: quizazz
+    ref: assessments/mod-01-post.yml
+```
+
+Strict-mode Pydantic rejects an unmigrated `pre_assessment` / `post_assessment` field with a `ValidationError` naming the offending field, so the build fails loudly until the migration is complete. There is no compatibility shim or deprecation warning — pre-1.0 makes the clean break acceptable.
+
+---
+
 ## Content locking
 
 Control access to modules and lessons with a three-level configuration hierarchy (most local wins):