learningfoundry 0.79.3__tar.gz → 0.83.0__tar.gz

{learningfoundry-0.79.3 → learningfoundry-0.83.0}/CHANGELOG.md

@@ -7,6 +7,98 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.83.0] - 2026-06-18
+
+**Option C — live marimo exercises** (Subphase K-2, Stories K.g–K.j). The single release for the subphase: nbfoundry now compiles a `ready` exercise to a runnable **marimo notebook** instead of a static `sections`/`expected_outputs` dict (which rendered as inert source in a `<pre>` — no executed cells, plots, or metrics). learningfoundry stages the notebook + an `exercises-manifest.json` sidecar, ships a learner-side `launch`/`stop` CLI that owns the notebook's lifecycle, and the frontend `ready` renderer becomes a launch banner.
+
+### Added
+
+- **`learningfoundry launch <id>` / `learningfoundry stop [<id>]` CLI** (Stories K.i.1–K.i.4) — the learner-side runtime that owns a `ready` exercise's marimo lifecycle (a static page cannot spawn an OS process). `launch` resolves the notebook path / `mode` / port from `exercises-manifest.json`, socket-probes the port, manages a port-keyed pidfile under `.learningfoundry/`, and spawns `marimo edit|run <notebook> --headless -p <port> --no-token` detached; it offers to replace a **launch-owned** marimo on the port but never blind-kills a **foreign** process. `stop <id>` tears down one exercise; bare `stop` stops all launch-owned notebooks. Cross-platform Python (`marimo` is a learner-runtime dependency found via `PATH`, never imported by the build).
+- **Notebook staging + `exercises-manifest.json`** (Story K.h) — the resolver pulls `notebook_source` out of the banner content into an `ExerciseArtifact`; the generator writes each notebook to `exercises/<id>/<id>.py` (outside the web root) and the `id → {notebook_path, mode, port}` manifest sidecar at the project root.
+- **`ExerciseBlock.mode`** (`edit` | `run`, default `edit`; Story K.g) — the author's per-exercise choice of how `launch` serves the notebook (editable notebook vs. read-only app).
+- **`progressRepo.getExerciseStatus(exerciseRef)`** (Story K.j.1) — reads the persisted `exercise_status` so the banner derives its completed slate on load.
+
+### Changed
+
+- **nbfoundry contract → Option C** (Story K.g) — `compile_exercise` returns `{title, description, hints, environment, notebook_source}` (consumer-dependency-spec BR-1); the codegen MUST be torch-free (torch is a learner-runtime dependency only). The pass-through `NbfoundryProvider` carries the new dict unchanged.
+- **`ExerciseBlock.svelte` `ready` renderer → launch banner** (Story K.j.1) — Copy the `learningfoundry launch <id>` command (transient "Copied ✓") → Open Exercise ↗ (new tab to `http://localhost:<port>`) → Mark as Complete (persists `exercise_status`, fires the completion callbacks) → completed slate (derived on load). Stub status still renders the placeholder.
+- **`ExerciseContent` TS type + `stub_exercise()` → banner shape** (Story K.j.1) — `description` replaces `instructions`; `mode`/`port` are ready-only optionals; the resolver injects `id`/`status`/`mode`/`port` onto `ready` content.
+
+### Removed
+
+- **The Option-B static-display path** (Stories K.h, K.j.1) — `ExerciseContent.sections`/`expected_outputs`/`assets`, the `ExerciseSection`/`ExpectedOutput` TS types, and the K.e `static/exercises/<id>/` image-asset staging. The live notebook renders its own cells and outputs at run time.
+
+### Notes
+
+- **Phase-bundled release.** Stories K.g–K.j ran unversioned; this single **minor** bump (v0.83.0) ships the whole subphase. Future: Marimo-WASM in-browser execution (Option A) for non-GPU exercises and graded `submission` (cell-output scoring) remain deferred — the banner/launch contract is forward-compatible.
+
+### Verified
+
+- `pyve test` → 498 passed. `npx vitest run` → 289 passed. `svelte-check` → 0 errors / 0 warnings. `ruff` + `mypy src/` clean.
+
+## [0.82.0] - 2026-06-18
+
+`ExerciseBlock` ready renderer + real `ExerciseContent` types (Story K.f), the third and final story of the Subphase K-1 nbfoundry bundle. A `ready` exercise now renders inline in the SvelteKit frontend (manual-completion flavor) instead of drawing only instructions + hints; graded `submission` remains deferred to `## Future`.
+
+### Added
+
+- **`ExerciseBlock.svelte` ready renderer (manual completion).** Renders code-scaffold `sections` (read-only in v1; the `editable` flag marks learner insertion points but is reserved for the Marimo-WASM future), `expected_outputs` (`image` via the runtime-composed `/exercises/<id>/<path>` URL with `alt` + `loading="lazy"`; `text`/`table` inline), collapsible hints, and local-run setup instructions from `environment`. A "Mark as Complete" control persists `exercise_status` via `progressRepo.updateExerciseStatus(id, 'complete')`, fires a typed `oncomplete` event `{ exerciseRef: id, status: 'completed' }`, and contributes to lesson-level block completion through `ContentBlock`. `status: stub` still renders the placeholder card.
+- **Real `ExerciseContent` TypeScript types** (`lib/types/index.ts`): `ExerciseSection` (title/description/code/editable), the `ExpectedOutput` discriminated union (`image` with `path`+`alt`; `text`/`table` with `content`), `ExerciseEnvironment`, plus `assets: string[]` and the resolver-injected `id: string`. Kept in lockstep with the Python compiled-exercise dict (Hidden Coupling).
+
+### Changed
+
+- **Resolver injects the exercise `id` into the resolved content** (both stub and ready) so the frontend has the `/exercises/<id>/<path>` asset-URL namespace and the `exerciseRef` progress key. Authoritative over the compiled dict (nbfoundry doesn't know learningfoundry's id or an explicit author override).
+- **`stub_exercise()` factory now includes `assets: []`** so the `ExerciseContent` type invariant holds for stub content too (matches the documented stub shape).
+
+### Notes
+
+- **Pinned open item resolved (no notebook-location field).** The released-nbfoundry compiled dict carries no runnable-notebook location in the v1 (Option B / static) path — `marimo_wasm_bundle` is the Option-A future field. The renderer therefore surfaces the code-scaffold `sections` plus `environment.setup_instructions` and relies on the learner's cloned curriculum repo to run the exercise locally. Authoritative source: `docs/specs/nbfoundry/consumer-dependency-spec.md` BR-1 + § "v1 Rendering Behavior".
+
+### Verified
+
+- `pyve test` → 453 passed (was 450; +3 resolver id-injection tests). `npx vitest run` → 285 passed (+7 `ExerciseBlock.test.ts`). `svelte-check` → 0 errors. `ruff` + `mypy src/` clean.
+
+## [0.81.0] - 2026-06-18
+
+Exercise `id` + asset staging (Story K.e), the second of the Subphase K-1 bundle. A compiled `ready` exercise's referenced asset files are now staged into `static/exercises/<id>/<path>`, where `id` is the build-output namespace and the progress key — auto-derived from the `ref` stem and unique curriculum-wide.
+
+### Added
+
+- **`ExerciseBlock.id: str | None = None`** in `schema_v1.py`. Auto-derived from the `ref` filename stem when omitted; uniqueness enforced **curriculum-wide** on `CurriculumDef` (the id is a `static/exercises/<id>/` URL + progress key, not just per-module). A stem collision between two exercises — even in different modules — fails loud at parse time so the author sets an explicit `id`. Mirrors the `AssessmentDefinition.id` auto-gen precedent (Story J.r).
+- **Exercise asset staging in the resolver.** After compiling a `ready` exercise, the resolver reads the dict's `assets: list[str]` and emits `Asset(source=base_dir/path, dest_relative="exercises/<id>/<path>")` into the shared `assets_by_dest` aggregator (deduped on `dest_relative`). `stub` exercises carry no assets and stage nothing.
+- **`static/exercises` added to the generator's `_PRESERVED_PATHS`**, so previously-staged exercise assets survive a `learningfoundry build` re-run. The existing asset-copy loop stages exercise assets unchanged (it writes any `dest_relative`).
+
+### Changed
+
+- **Generalized the `Asset` dedup note and `_copy_assets` docstring** to cover both content-hashed image paths and non-hashed exercise paths (the dedup key is `dest_relative` for both; the size-based copy skip is exact for hashed paths, a cheap heuristic for exercise paths).
+
+### Verified
+
+- `pyve test` → 450 passed (was 437; +13 new tests across `test_schema_v1.py`, `test_resolver.py`, `test_generator.py`). No regressions.
+- `ruff check` clean; `mypy src/` clean.
+
+## [0.80.0] - 2026-06-18
+
+Real nbfoundry exercise integration (Story K.d), the first of the Subphase K-1 bundle. Now that nbfoundry is published, `ready` exercise blocks compile through a real `NbfoundryProvider`; stub-vs-real selection is a per-block `status` field handled in the resolver, defaulting to `ready` so a typo'd `ref` fails loud instead of silently degrading to a placeholder.
+
+### Added
+
+- **`NbfoundryProvider` (`integrations/nbfoundry.py`).** A real `ExerciseProvider` that lazy-imports and delegates to `nbfoundry.compile_exercise(ref_path, base_dir)`, returning its dict unchanged. Missing package → `ImportError` with a `pip install learningfoundry[nbfoundry]` hint; any nbfoundry error → `IntegrationError` citing `ref_path`. Signature-identical to the protocol — the `status` switch lives in the resolver, not the provider.
+- **`[nbfoundry]` optional-dependency extra (`nbfoundry>=0.1`)** in `pyproject.toml`, plus a mypy `ignore_missing_imports` override mirroring `quizazz`.
+- **`ExerciseBlock.status: Literal["stub", "ready"] = "ready"`** in `schema_v1.py`. `ready` (default) compiles via `NbfoundryProvider`; `stub` is the explicit "not built yet" opt-in.
+- **`stub_exercise(ref_path)` factory (`integrations/nbfoundry_stub.py`).** Single source of truth for the placeholder dict, shared by the resolver's `stub` path and the retained `NbfoundryStub`.
+
+### Changed
+
+- **Resolver owns the `status` switch.** `status: stub` emits `stub_exercise()` directly — no provider call, no nbfoundry import, so an all-stub curriculum never imports nbfoundry. `status: ready`/default compiles via the provider and fails loud on a bad ref. The default exercise provider is now `NbfoundryProvider` (was `NbfoundryStub`).
+- **`NbfoundryStub` demoted to a test double / "no-notebooks" injectable** — it is no longer the default provider and is never selected by the `status` switch.
+- **Provider protocols are now `@runtime_checkable`**, enabling runtime `isinstance` conformance assertions alongside the mypy-checked contract.
+
+### Verified
+
+- `pyve test` → 437 passed (was 413; +24 new tests across `test_nbfoundry.py`, `test_nbfoundry_stub.py`, `test_schema_v1.py`, `test_resolver.py`). No regressions.
+- `ruff check` clean; `mypy src/` clean. The protocol-match contract is enforced in CI via the resolver's `exercise_provider = NbfoundryProvider()` default assignment into an `ExerciseProvider`-typed slot.
+
 ## [0.79.3] - 2026-06-15
 
 Fix `learningfoundry preview` appearing to hang silently during the `pnpm install` step and then reporting an empty failure on Ctrl-C. The install step captured pnpm's output (with no timeout) while leaving stdin attached, so progress and any interactive prompt were hidden — a prompting or slow install looked like a silent hang — and a non-zero exit produced `` `pnpm install` failed in `dist`: `` with nothing after the colon. Fixed via Story K.a.

{learningfoundry-0.79.3 → learningfoundry-0.83.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: learningfoundry
-Version: 0.79.3
+Version: 0.83.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
@@ -23,6 +23,8 @@ Requires-Python: >=3.12
 Requires-Dist: click>=8.1
 Requires-Dist: pydantic>=2.0
 Requires-Dist: pyyaml>=6.0.3
+Provides-Extra: nbfoundry
+Requires-Dist: nbfoundry>=0.1; extra == 'nbfoundry'
 Provides-Extra: quizazz
 Requires-Dist: quizazz>=0.1; extra == 'quizazz'
 Description-Content-Type: text/markdown
@@ -63,7 +65,7 @@ A curriculum engine that turns a YAML curriculum definition into a deployable Sv
 - **Text** — Markdown content rendered in the browser
 - **Video** — YouTube embeds
 - **Assessment** — Interactive assessments via [quizazz](https://github.com/pointmatic/quizazz) (optional)
-- **Exercise** — Executable notebooks via nbfoundry (stub provided)
+- **Exercise** — Scaffolded model-training exercises via [nbfoundry](https://github.com/pointmatic/nbfoundry) (optional; `status: stub` for not-yet-built)
 - **Visualization** — D3-based charts via d3foundry (stub provided)
 
 Learner progress is persisted locally in SQLite (via sql.js) — no backend required.
@@ -76,10 +78,12 @@ Learner progress is persisted locally in SQLite (via sql.js) — no backend requ
 pip install learningfoundry
 ```
 
-**With optional quizazz support:**
+**With optional integration extras:**
 
 ```bash
-pip install "learningfoundry[quizazz]"
+pip install "learningfoundry[quizazz]"    # assessments
+pip install "learningfoundry[nbfoundry]"  # exercises
+pip install "learningfoundry[quizazz,nbfoundry]"
 ```
 
 **Requirements:**
@@ -207,6 +211,27 @@ This serves the SvelteKit project from source via Vite's dev server; it does **n
 
 ---
 
+### `learningfoundry launch` / `learningfoundry stop`
+
+Run a `ready` exercise's marimo notebook locally. These are **learner-side** commands — run from inside the generated app (where `build` writes `exercises-manifest.json`), not from the author's repo. The generated app is static and a browser page can't spawn a process, so the exercise's banner asks the learner to copy and run `learningfoundry launch <id>`.
+
+```
+Usage: learningfoundry launch [OPTIONS] EXERCISE_ID
+       learningfoundry stop [OPTIONS] [EXERCISE_ID]
+
+Options:
+  --dir PATH              Directory holding exercises-manifest.json (the
+                          generated app's root).  [default: .]
+  --log-level LEVEL       Logging verbosity.  [default: INFO]
+  --help                  Show this message and exit.
+```
+
+`launch <id>` resolves the notebook path / `mode` / port from the manifest, checks the port, then spawns `marimo edit|run <notebook> --headless -p <port> --no-token` detached (so it outlives the CLI) and prints the local URL. If the port is already held by a **launch-owned** marimo it offers to replace it; a **foreign** process on the port is never killed. `stop <id>` tears down that exercise's notebook; bare `stop` stops every launch-owned notebook.
+
+> **`marimo` is a learner-runtime dependency**, not a learningfoundry dependency — `launch` finds it on `PATH` (it is never imported by the build). Install it alongside the exercise's other run requirements (e.g. `pip install marimo torch`); the banner lists them. A missing `marimo` yields an install hint, not a traceback.
+
+---
+
 ## Curriculum YAML Format
 
 ```yaml
@@ -266,10 +291,13 @@ curriculum:
               source: quizazz
               ref: assessments/mod-01-assessment.yml
 
-            # Exercise block — requires nbfoundry (stub included)
+            # Exercise block — `ready` requires learningfoundry[nbfoundry];
+            # `status: stub` renders a placeholder with no install needed.
+            # See "Authoring nbfoundry exercises" below for the full author flow.
             - type: exercise
               source: nbfoundry
               ref: exercises/mod-01-exercise.yml
+              status: stub
 
             # Visualization block — requires d3foundry (stub included)
             - type: visualization
@@ -692,6 +720,61 @@ questions:
 - **`learningfoundry[quizazz]` is an optional extra.** Plain `pip install learningfoundry` does not pull in quizazz; running `learningfoundry build` on a curriculum that references `source: quizazz` will fail with an `ImportError`. Install the extra explicitly.
 - **`<QuizBlock>` is a vendor component name** — preserved at the vendor boundary. A future "consistency rename" pass that tried to rename it to `<AssessmentBlock>` (learningfoundry's wrapper component) would break the integration silently. See the "Vendor terminology stops at the vendor boundary" note in [project-essentials.md](docs/specs/project-essentials.md).
 
+### Authoring nbfoundry exercises
+
+[nbfoundry](https://github.com/pointmatic/nbfoundry) is the exercise provider — scaffolded, model-training exercises. Under the hood (Option C) nbfoundry compiles each exercise to a **runnable marimo notebook**; learningfoundry stages it at build time and the lesson renders a **launch banner**. The learner copies the `learningfoundry launch <id>` command, runs it to start the notebook locally, opens it in a new tab, works through the cells, and clicks **Mark as Complete**. The exercise runs in the learner's own Python environment, so PyTorch and other heavy dependencies stay out of the build and the browser. In-browser (Marimo-WASM) execution and graded submission are deferred to future versions; the authored YAML does not change when they land.
+
+**What you need.**
+
+- *Build side:* `pip install learningfoundry[nbfoundry]` installs the [`nbfoundry` PyPI package](https://pypi.org/project/nbfoundry/) so `learningfoundry build` can compile exercise YAML into the notebook. Like `[quizazz]`, it is an optional extra — plain `pip install learningfoundry` does not pull it in, and a `ready` exercise referencing `source: nbfoundry` without it fails the build with an `ImportError` and an install hint.
+- *Learner side:* running the exercise needs **`marimo`** (plus the exercise's own dependencies, e.g. `torch`) on the learner's `PATH`. `learningfoundry launch` finds `marimo` there — it is a **learner-runtime** dependency, never imported by the build. The banner lists the exercise's prerequisites.
+
+**Referencing an exercise.** Add an `exercise` content block to a lesson:
+
+```yaml
+content_blocks:
+  - type: exercise
+    source: nbfoundry
+    ref: exercises/mod-01/cnn-classifier.yml   # located under --base-dir
+    status: ready                              # "ready" (default) | "stub"
+    mode: edit                                 # "edit" (default) | "run"
+    # id: cnn-classifier                       # optional; see below
+```
+
+- **`status: ready`** (the default) compiles the exercise to a notebook at build time. A typo'd `ref` fails the build **loud** rather than silently degrading to a placeholder.
+- **`status: stub`** renders the "nbfoundry integration pending" placeholder card — the explicit "not built yet" opt-in while you scaffold the curriculum. No nbfoundry call, no install needed for stub-only curricula.
+- **`mode`** chooses how `learningfoundry launch` serves the notebook: **`edit`** (the default) opens marimo's editable notebook (the learner writes code into the scaffold); **`run`** opens it as a read-only app. It is the same notebook either way — the choice is pedagogical.
+
+**How `id` works.** Every exercise has an `id` that is two things at once: the **notebook namespace** (the build writes the marimo notebook to `exercises/<id>/<id>.py` and indexes it in `exercises-manifest.json`, which `learningfoundry launch <id>` reads) and the **progress key** (`exerciseRef`) recorded in the in-browser database. When you omit `id:`, it is auto-derived from the `ref` filename **stem** (`exercises/mod-01/cnn-classifier.yml` → `cnn-classifier`). The `id` must be **unique across the whole curriculum** — not just within a module.
+
+**Organizing source freely.** The `id` namespaces the *output notebook*; it does **not** constrain where you organize *source* content. Lay out exercise YAML however you like under `--base-dir` — nbfoundry locates it via the relative `ref`:
+
+```
+# Source (organize however you like):     # Build output (id-namespaced notebook):
+exercises/mod-01/cnn-classifier.yml       dist/exercises/cnn-classifier/cnn-classifier.py
+exercises/mod-02/intro.yml                dist/exercises/intro/intro.py
+```
+
+The notebook renders its own plots, tables, and metrics when it runs — there is no separate image-staging step (that was the retired Option-B static-display path).
+
+**The stem-collision case.** Because the auto-derived `id` is just the filename stem, two exercises whose `ref` files share a stem collide — even in different modules:
+
+```yaml
+# mod-01 lesson:  ref: exercises/mod-01/intro.yml   → id "intro"
+# mod-02 lesson:  ref: exercises/mod-02/intro.yml   → id "intro"   ❌ build error
+```
+
+This is a **loud build-time error**, not a silent overwrite (two exercises would otherwise share one notebook path + progress key). Fix it by setting an explicit `id:` on at least one:
+
+```yaml
+  - type: exercise
+    source: nbfoundry
+    ref: exercises/mod-02/intro.yml
+    id: mod-02-intro          # explicit, curriculum-unique
+```
+
+**Why a stable `id` matters.** Set an explicit `id:` when you expect to **reorganize source content** later. Because the `id` is both the notebook namespace and the progress key, keeping it stable while you move or rename the underlying `ref` file preserves both the `learningfoundry launch <id>` command *and* learners' recorded completion — whereas relying on the auto-derived stem means a rename silently changes the `id` and orphans prior progress.
+
 ### Assessments
 
 Each module declares an `assessments[]` array; each entry carries:

{learningfoundry-0.79.3 → learningfoundry-0.83.0}/README.md

@@ -34,7 +34,7 @@ A curriculum engine that turns a YAML curriculum definition into a deployable Sv
 - **Text** — Markdown content rendered in the browser
 - **Video** — YouTube embeds
 - **Assessment** — Interactive assessments via [quizazz](https://github.com/pointmatic/quizazz) (optional)
-- **Exercise** — Executable notebooks via nbfoundry (stub provided)
+- **Exercise** — Scaffolded model-training exercises via [nbfoundry](https://github.com/pointmatic/nbfoundry) (optional; `status: stub` for not-yet-built)
 - **Visualization** — D3-based charts via d3foundry (stub provided)
 
 Learner progress is persisted locally in SQLite (via sql.js) — no backend required.
@@ -47,10 +47,12 @@ Learner progress is persisted locally in SQLite (via sql.js) — no backend requ
 pip install learningfoundry
 ```
 
-**With optional quizazz support:**
+**With optional integration extras:**
 
 ```bash
-pip install "learningfoundry[quizazz]"
+pip install "learningfoundry[quizazz]"    # assessments
+pip install "learningfoundry[nbfoundry]"  # exercises
+pip install "learningfoundry[quizazz,nbfoundry]"
 ```
 
 **Requirements:**
@@ -178,6 +180,27 @@ This serves the SvelteKit project from source via Vite's dev server; it does **n
 
 ---
 
+### `learningfoundry launch` / `learningfoundry stop`
+
+Run a `ready` exercise's marimo notebook locally. These are **learner-side** commands — run from inside the generated app (where `build` writes `exercises-manifest.json`), not from the author's repo. The generated app is static and a browser page can't spawn a process, so the exercise's banner asks the learner to copy and run `learningfoundry launch <id>`.
+
+```
+Usage: learningfoundry launch [OPTIONS] EXERCISE_ID
+       learningfoundry stop [OPTIONS] [EXERCISE_ID]
+
+Options:
+  --dir PATH              Directory holding exercises-manifest.json (the
+                          generated app's root).  [default: .]
+  --log-level LEVEL       Logging verbosity.  [default: INFO]
+  --help                  Show this message and exit.
+```
+
+`launch <id>` resolves the notebook path / `mode` / port from the manifest, checks the port, then spawns `marimo edit|run <notebook> --headless -p <port> --no-token` detached (so it outlives the CLI) and prints the local URL. If the port is already held by a **launch-owned** marimo it offers to replace it; a **foreign** process on the port is never killed. `stop <id>` tears down that exercise's notebook; bare `stop` stops every launch-owned notebook.
+
+> **`marimo` is a learner-runtime dependency**, not a learningfoundry dependency — `launch` finds it on `PATH` (it is never imported by the build). Install it alongside the exercise's other run requirements (e.g. `pip install marimo torch`); the banner lists them. A missing `marimo` yields an install hint, not a traceback.
+
+---
+
 ## Curriculum YAML Format
 
 ```yaml
@@ -237,10 +260,13 @@ curriculum:
               source: quizazz
               ref: assessments/mod-01-assessment.yml
 
-            # Exercise block — requires nbfoundry (stub included)
+            # Exercise block — `ready` requires learningfoundry[nbfoundry];
+            # `status: stub` renders a placeholder with no install needed.
+            # See "Authoring nbfoundry exercises" below for the full author flow.
             - type: exercise
               source: nbfoundry
               ref: exercises/mod-01-exercise.yml
+              status: stub
 
             # Visualization block — requires d3foundry (stub included)
             - type: visualization
@@ -663,6 +689,61 @@ questions:
 - **`learningfoundry[quizazz]` is an optional extra.** Plain `pip install learningfoundry` does not pull in quizazz; running `learningfoundry build` on a curriculum that references `source: quizazz` will fail with an `ImportError`. Install the extra explicitly.
 - **`<QuizBlock>` is a vendor component name** — preserved at the vendor boundary. A future "consistency rename" pass that tried to rename it to `<AssessmentBlock>` (learningfoundry's wrapper component) would break the integration silently. See the "Vendor terminology stops at the vendor boundary" note in [project-essentials.md](docs/specs/project-essentials.md).
 
+### Authoring nbfoundry exercises
+
+[nbfoundry](https://github.com/pointmatic/nbfoundry) is the exercise provider — scaffolded, model-training exercises. Under the hood (Option C) nbfoundry compiles each exercise to a **runnable marimo notebook**; learningfoundry stages it at build time and the lesson renders a **launch banner**. The learner copies the `learningfoundry launch <id>` command, runs it to start the notebook locally, opens it in a new tab, works through the cells, and clicks **Mark as Complete**. The exercise runs in the learner's own Python environment, so PyTorch and other heavy dependencies stay out of the build and the browser. In-browser (Marimo-WASM) execution and graded submission are deferred to future versions; the authored YAML does not change when they land.
+
+**What you need.**
+
+- *Build side:* `pip install learningfoundry[nbfoundry]` installs the [`nbfoundry` PyPI package](https://pypi.org/project/nbfoundry/) so `learningfoundry build` can compile exercise YAML into the notebook. Like `[quizazz]`, it is an optional extra — plain `pip install learningfoundry` does not pull it in, and a `ready` exercise referencing `source: nbfoundry` without it fails the build with an `ImportError` and an install hint.
+- *Learner side:* running the exercise needs **`marimo`** (plus the exercise's own dependencies, e.g. `torch`) on the learner's `PATH`. `learningfoundry launch` finds `marimo` there — it is a **learner-runtime** dependency, never imported by the build. The banner lists the exercise's prerequisites.
+
+**Referencing an exercise.** Add an `exercise` content block to a lesson:
+
+```yaml
+content_blocks:
+  - type: exercise
+    source: nbfoundry
+    ref: exercises/mod-01/cnn-classifier.yml   # located under --base-dir
+    status: ready                              # "ready" (default) | "stub"
+    mode: edit                                 # "edit" (default) | "run"
+    # id: cnn-classifier                       # optional; see below
+```
+
+- **`status: ready`** (the default) compiles the exercise to a notebook at build time. A typo'd `ref` fails the build **loud** rather than silently degrading to a placeholder.
+- **`status: stub`** renders the "nbfoundry integration pending" placeholder card — the explicit "not built yet" opt-in while you scaffold the curriculum. No nbfoundry call, no install needed for stub-only curricula.
+- **`mode`** chooses how `learningfoundry launch` serves the notebook: **`edit`** (the default) opens marimo's editable notebook (the learner writes code into the scaffold); **`run`** opens it as a read-only app. It is the same notebook either way — the choice is pedagogical.
+
+**How `id` works.** Every exercise has an `id` that is two things at once: the **notebook namespace** (the build writes the marimo notebook to `exercises/<id>/<id>.py` and indexes it in `exercises-manifest.json`, which `learningfoundry launch <id>` reads) and the **progress key** (`exerciseRef`) recorded in the in-browser database. When you omit `id:`, it is auto-derived from the `ref` filename **stem** (`exercises/mod-01/cnn-classifier.yml` → `cnn-classifier`). The `id` must be **unique across the whole curriculum** — not just within a module.
+
+**Organizing source freely.** The `id` namespaces the *output notebook*; it does **not** constrain where you organize *source* content. Lay out exercise YAML however you like under `--base-dir` — nbfoundry locates it via the relative `ref`:
+
+```
+# Source (organize however you like):     # Build output (id-namespaced notebook):
+exercises/mod-01/cnn-classifier.yml       dist/exercises/cnn-classifier/cnn-classifier.py
+exercises/mod-02/intro.yml                dist/exercises/intro/intro.py
+```
+
+The notebook renders its own plots, tables, and metrics when it runs — there is no separate image-staging step (that was the retired Option-B static-display path).
+
+**The stem-collision case.** Because the auto-derived `id` is just the filename stem, two exercises whose `ref` files share a stem collide — even in different modules:
+
+```yaml
+# mod-01 lesson:  ref: exercises/mod-01/intro.yml   → id "intro"
+# mod-02 lesson:  ref: exercises/mod-02/intro.yml   → id "intro"   ❌ build error
+```
+
+This is a **loud build-time error**, not a silent overwrite (two exercises would otherwise share one notebook path + progress key). Fix it by setting an explicit `id:` on at least one:
+
+```yaml
+  - type: exercise
+    source: nbfoundry
+    ref: exercises/mod-02/intro.yml
+    id: mod-02-intro          # explicit, curriculum-unique
+```
+
+**Why a stable `id` matters.** Set an explicit `id:` when you expect to **reorganize source content** later. Because the `id` is both the notebook namespace and the progress key, keeping it stable while you move or rename the underlying `ref` file preserves both the `learningfoundry launch <id>` command *and* learners' recorded completion — whereas relying on the auto-derived stem means a rename silently changes the `id` and orphans prior progress.
+
 ### Assessments
 
 Each module declares an `assessments[]` array; each entry carries:

{learningfoundry-0.79.3 → learningfoundry-0.83.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "learningfoundry"
-version = "0.79.3"
+version = "0.83.0"
 description = "A curriculum engine that turns a YAML curriculum definition into a deployable SvelteKit learning application."
 readme = "README.md"
 license = "Apache-2.0"
@@ -34,6 +34,9 @@ dependencies = [
 quizazz = [
     "quizazz>=0.1",
 ]
+nbfoundry = [
+    "nbfoundry>=0.1",
+]
 
 [project.urls]
 Homepage = "https://github.com/pointmatic/learningfoundry"
@@ -71,6 +74,10 @@ python_version = "3.12"
 module = "quizazz"
 ignore_missing_imports = true
 
+[[tool.mypy.overrides]]
+module = "nbfoundry"
+ignore_missing_imports = true
+
 [tool.coverage.run]
 source = ["src/learningfoundry"]
 omit = ["*/sveltekit_template/*"]

{learningfoundry-0.79.3 → learningfoundry-0.83.0}/src/learningfoundry/__init__.py

@@ -1,4 +1,4 @@
 # Copyright 2026 Pointmatic
 # SPDX-License-Identifier: Apache-2.0
 
-__version__ = "0.79.3"
+__version__ = "0.83.0"

{learningfoundry-0.79.3 → learningfoundry-0.83.0}/src/learningfoundry/asset_resolver.py

@@ -85,11 +85,20 @@ _PASSTHROUGH_PREFIXES: tuple[str, ...] = (
 class Asset:
     """A single asset that must be copied into the generated project.
 
+    ``dest_relative`` is the dedup key wherever Assets aggregate (the
+    resolver's ``assets_by_dest`` map): two records with the same
+    destination collapse to one copy. This holds both for the content-hashed
+    markdown-image paths produced here (``content/<sha256[:12]>/<basename>``,
+    where a matching hash implies matching bytes) and for the **non-hashed**
+    exercise-asset paths the resolver emits (``exercises/<id>/<path>``,
+    Story K.e) — same key, same dedup semantics.
+
     Attributes:
         source: Absolute path to the source file on disk.
         dest_relative: Destination path relative to the generated project's
-            ``static/`` directory (e.g. ``"content/abc123def456/diagram.png"``).
-            Always uses forward slashes — this becomes a URL fragment too.
+            ``static/`` directory (e.g. ``"content/abc123def456/diagram.png"``
+            or ``"exercises/mod-01-exercise-01/data/sample.csv"``). Always
+            uses forward slashes — this becomes a URL fragment too.
     """
 
     source: Path

{learningfoundry-0.79.3 → learningfoundry-0.83.0}/src/learningfoundry/cli.py

@@ -1,6 +1,7 @@
 # Copyright 2026 Pointmatic
 # SPDX-License-Identifier: Apache-2.0
 
+import shutil
 import sys
 from pathlib import Path
 
@@ -13,6 +14,7 @@ from learningfoundry.exceptions import (
     CurriculumValidationError,
     CurriculumVersionError,
     GenerationError,
+    LaunchError,
     SchemaExtensionError,
 )
 from learningfoundry.logging_config import setup_logging as _setup_logging
@@ -24,6 +26,7 @@ EXIT_VALIDATION = 1
 EXIT_RESOLUTION = 2
 EXIT_GENERATION = 3
 EXIT_CONFIG = 4
+EXIT_RUNTIME = 5
 
 
 # ---------------------------------------------------------------------------
@@ -270,3 +273,114 @@ def preview(
         sys.exit(EXIT_CONFIG)
 
     click.echo(f"Preview server started at http://localhost:{port}")
+
+
+# ---------------------------------------------------------------------------
+# launch
+# ---------------------------------------------------------------------------
+
+_launch_dir_option = click.option(
+    "--dir",
+    "launch_dir",
+    type=click.Path(file_okay=False, path_type=Path),
+    default=Path("."),
+    show_default=True,
+    help=(
+        "Directory holding `exercises-manifest.json` (the generated app's "
+        "root). Defaults to the current directory."
+    ),
+)
+
+
+@main.command()
+@click.argument("exercise_id")
+@_launch_dir_option
+@_log_level_option
+def launch(exercise_id: str, launch_dir: Path, log_level: str) -> None:
+    """Launch an exercise's marimo notebook locally."""
+    _setup_logging(level=log_level)
+
+    from learningfoundry import launch as _launch
+
+    try:
+        spec = _launch.resolve_launch_spec(launch_dir, exercise_id)
+    except LaunchError as exc:
+        click.echo(f"Launch error: {exc}", err=True)
+        sys.exit(EXIT_VALIDATION)
+
+    if shutil.which("marimo") is None:
+        click.echo(
+            "marimo not found on PATH. It is a learner-runtime dependency — "
+            "install it (e.g. `pip install marimo`) to run exercises.",
+            err=True,
+        )
+        sys.exit(EXIT_RUNTIME)
+
+    status = _launch.classify_port(launch_dir, spec.port)
+    if status == "foreign":
+        click.echo(
+            f"Port {spec.port} is in use by another process. Refusing to "
+            "kill it — free the port (or stop that process) and retry.",
+            err=True,
+        )
+        sys.exit(EXIT_RUNTIME)
+    if status == "ours":
+        if not click.confirm(
+            f"An exercise is already running on port {spec.port}. Replace it?"
+        ):
+            click.echo("Left the running exercise in place.")
+            return
+        _launch.stop_launch_on_port(launch_dir, spec.port)
+
+    pid = _launch.spawn_detached(_launch.marimo_argv(spec), launch_dir)
+    _launch.write_pidfile(
+        launch_dir,
+        _launch.PidfileEntry(
+            pid=pid,
+            exercise_id=spec.id,
+            port=spec.port,
+            mode=spec.mode,
+        ),
+    )
+    click.echo(
+        f"Launched `{spec.id}` ({spec.mode}) → http://localhost:{spec.port}"
+    )
+    click.echo(f"Stop it with: learningfoundry stop {spec.id}")
+
+
+# ---------------------------------------------------------------------------
+# stop
+# ---------------------------------------------------------------------------
+
+@main.command()
+@click.argument("exercise_id", required=False)
+@_launch_dir_option
+@_log_level_option
+def stop(exercise_id: str | None, launch_dir: Path, log_level: str) -> None:
+    """Stop a launch-owned marimo notebook (all of them if no id is given)."""
+    _setup_logging(level=log_level)
+
+    from learningfoundry import launch as _launch
+
+    if exercise_id is not None:
+        try:
+            spec = _launch.resolve_launch_spec(launch_dir, exercise_id)
+        except LaunchError as exc:
+            click.echo(f"Stop error: {exc}", err=True)
+            sys.exit(EXIT_VALIDATION)
+        stopped = _launch.stop_launch_on_port(launch_dir, spec.port)
+        if stopped is not None:
+            click.echo(f"Stopped `{stopped.exercise_id}` (port {stopped.port}).")
+        else:
+            click.echo(f"No running exercise found for `{exercise_id}`.")
+        return
+
+    # No id → stop every launch-owned marimo.
+    ports = _launch.launched_ports(launch_dir)
+    if not ports:
+        click.echo("No running exercises.")
+        return
+    for port in ports:
+        stopped = _launch.stop_launch_on_port(launch_dir, port)
+        if stopped is not None:
+            click.echo(f"Stopped `{stopped.exercise_id}` (port {stopped.port}).")

{learningfoundry-0.79.3 → learningfoundry-0.83.0}/src/learningfoundry/exceptions.py

@@ -43,3 +43,28 @@ class GenerationError(LearningFoundryError):
 class SchemaExtensionError(LearningFoundryError):
     """Project schema-extensions file is missing, malformed, or declares an
     unsupported field type / shape (Story J.h)."""
+
+
+class LaunchError(LearningFoundryError):
+    """Base for `learningfoundry launch` / `stop` runtime errors (Story K.i)."""
+
+
+class ManifestNotFoundError(LaunchError):
+    """The `exercises-manifest.json` sidecar was not found in the launch dir.
+
+    The learner runs `launch`/`stop` from inside the generated app's root,
+    where `build` writes the manifest; a missing file usually means the wrong
+    directory or an un-built app.
+    """
+
+
+class UnknownExerciseError(LaunchError):
+    """The requested exercise id is absent from the manifest.
+
+    The message lists the ids the learner can actually launch.
+    """
+
+
+class ManifestError(LaunchError):
+    """The `exercises-manifest.json` sidecar is malformed (bad JSON, not an
+    object, or an entry missing required fields)."""