learningfoundry 0.82.0__tar.gz → 0.83.0__tar.gz

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

@@ -7,6 +7,35 @@ 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`.

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: learningfoundry
-Version: 0.82.0
+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
@@ -211,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
@@ -701,9 +722,12 @@ questions:
 
 ### Authoring nbfoundry exercises
 
-[nbfoundry](https://github.com/pointmatic/nbfoundry) is the exercise provider — scaffolded, model-training exercises that render inline in a lesson with code-scaffold sections, expected outputs, hints, and local-run instructions, plus a "Mark as Complete" control. In v1 the exercise is **informational**: the learner runs the code in their own local environment (JupyterLab, Marimo, VS Code) and marks it complete. In-browser execution and graded submission are deferred to future versions; the authored YAML does not change when they land.
+[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.**
 
-**What you need.** `pip install learningfoundry[nbfoundry]` installs the Python builder side (the [`nbfoundry` PyPI package](https://pypi.org/project/nbfoundry/)) so `learningfoundry build` can compile exercise YAML. Like `[quizazz]`, it is an optional extra — plain `pip install learningfoundry` does not pull it in, and building a curriculum with a `ready` exercise that references `source: nbfoundry` without the extra fails with an `ImportError` and an install hint.
+- *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:
 
@@ -713,23 +737,26 @@ content_blocks:
     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 through nbfoundry at build time. A typo'd `ref` fails the build **loud** rather than silently degrading to a placeholder.
+- **`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 **build-output asset namespace** (`static/exercises/<id>/…`, where expected-output images and other assets are staged) 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.
+**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 vs. the flat output.** The `id` namespaces the *output*; it does **not** constrain where you organize *source* content. You can lay out exercise YAML and its assets however you like under `--base-dir` — nbfoundry locates them via the relative `ref` and the asset paths inside the compiled dict — and learningfoundry stages every referenced asset into the flat `static/exercises/<id>/<path>` tree:
+**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 (flat, id-namespaced):
-exercises/mod-01/cnn-classifier.yml             static/exercises/cnn-classifier/loss-curve.png
-exercises/mod-01/assets/loss-curve.png          static/exercises/cnn-classifier/sample.csv
-exercises/shared/sample.csv
+# 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
@@ -737,7 +764,7 @@ exercises/shared/sample.csv
 # 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 asset URL + progress key). Fix it by setting an explicit `id:` on at least one:
+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
@@ -746,7 +773,7 @@ This is a **loud build-time error**, not a silent overwrite (two exercises would
     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 asset URL namespace and the progress key, keeping it stable while you move or rename the underlying `ref` file preserves both the staged asset URLs *and* learners' recorded completion — whereas relying on the auto-derived stem means a rename silently changes the `id` and orphans prior progress.
+**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
 

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

@@ -180,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
@@ -670,9 +691,12 @@ questions:
 
 ### Authoring nbfoundry exercises
 
-[nbfoundry](https://github.com/pointmatic/nbfoundry) is the exercise provider — scaffolded, model-training exercises that render inline in a lesson with code-scaffold sections, expected outputs, hints, and local-run instructions, plus a "Mark as Complete" control. In v1 the exercise is **informational**: the learner runs the code in their own local environment (JupyterLab, Marimo, VS Code) and marks it complete. In-browser execution and graded submission are deferred to future versions; the authored YAML does not change when they land.
+[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.**
 
-**What you need.** `pip install learningfoundry[nbfoundry]` installs the Python builder side (the [`nbfoundry` PyPI package](https://pypi.org/project/nbfoundry/)) so `learningfoundry build` can compile exercise YAML. Like `[quizazz]`, it is an optional extra — plain `pip install learningfoundry` does not pull it in, and building a curriculum with a `ready` exercise that references `source: nbfoundry` without the extra fails with an `ImportError` and an install hint.
+- *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:
 
@@ -682,23 +706,26 @@ content_blocks:
     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 through nbfoundry at build time. A typo'd `ref` fails the build **loud** rather than silently degrading to a placeholder.
+- **`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 **build-output asset namespace** (`static/exercises/<id>/…`, where expected-output images and other assets are staged) 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.
+**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 vs. the flat output.** The `id` namespaces the *output*; it does **not** constrain where you organize *source* content. You can lay out exercise YAML and its assets however you like under `--base-dir` — nbfoundry locates them via the relative `ref` and the asset paths inside the compiled dict — and learningfoundry stages every referenced asset into the flat `static/exercises/<id>/<path>` tree:
+**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 (flat, id-namespaced):
-exercises/mod-01/cnn-classifier.yml             static/exercises/cnn-classifier/loss-curve.png
-exercises/mod-01/assets/loss-curve.png          static/exercises/cnn-classifier/sample.csv
-exercises/shared/sample.csv
+# 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
@@ -706,7 +733,7 @@ exercises/shared/sample.csv
 # 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 asset URL + progress key). Fix it by setting an explicit `id:` on at least one:
+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
@@ -715,7 +742,7 @@ This is a **loud build-time error**, not a silent overwrite (two exercises would
     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 asset URL namespace and the progress key, keeping it stable while you move or rename the underlying `ref` file preserves both the staged asset URLs *and* learners' recorded completion — whereas relying on the auto-derived stem means a rename silently changes the `id` and orphans prior progress.
+**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
 

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

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "learningfoundry"
-version = "0.82.0"
+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"

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

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

{learningfoundry-0.82.0 → 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.82.0 → 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)."""

{learningfoundry-0.82.0 → learningfoundry-0.83.0}/src/learningfoundry/generator.py

@@ -27,10 +27,9 @@ _TEMPLATE_DIR = Path(__file__).parent / "sveltekit_template"
 # rebuild — keeps `learningfoundry preview` snappy when only markdown
 # text changed and no new images were introduced.
 #
-# `static/exercises` is preserved for the same reason for nbfoundry exercise
-# assets (staged non-hashed under `static/exercises/<id>/<path>`, Story K.e),
-# so a rebuild that didn't touch a given exercise's assets leaves them in
-# place.
+# (Marimo exercise notebooks live at `exercises/<id>/<id>.py` — outside the
+# web root — and are regenerated every build by `_write_exercises`, so they
+# are intentionally NOT preserved here.)
 #
 # `static/sql-wasm.wasm` is preserved because it is gitignored and not
 # shipped in the template — `pipeline._ensure_sql_wasm` is the single
@@ -43,7 +42,6 @@ _PRESERVED_PATHS: tuple[str, ...] = (
     "build",
     ".svelte-kit",
     "static/content",
-    "static/exercises",
     "static/sql-wasm.wasm",
 )
 
@@ -103,6 +101,7 @@ def generate_app(
 
     _atomic_copy(src, output_dir)
     _copy_assets(resolved, output_dir)
+    _write_exercises(resolved, output_dir)
     _write_curriculum_json(resolved, output_dir)
 
     logger.info("Generated SvelteKit project at: %s", output_dir)
@@ -216,9 +215,10 @@ def _compute_total_duration_minutes(resolved: ResolvedCurriculum) -> int | None:
 def _write_curriculum_json(resolved: ResolvedCurriculum, output_dir: Path) -> None:
     """Serialize ResolvedCurriculum to output_dir/static/curriculum.json.
 
-    The ``assets`` list is intentionally stripped — it carries on-disk
-    ``Path`` objects (which are not JSON-serialisable) and is consumed only
-    by the generator's asset-copy step, never by the SvelteKit frontend.
+    The ``assets`` and ``exercises`` lists are intentionally stripped — they
+    carry build-output metadata (on-disk ``Path`` objects / notebook source)
+    consumed only by the generator's copy/write steps, never by the SvelteKit
+    frontend.
     """
     static_dir = output_dir / "static"
     static_dir.mkdir(parents=True, exist_ok=True)
@@ -227,6 +227,7 @@ def _write_curriculum_json(resolved: ResolvedCurriculum, output_dir: Path) -> No
     try:
         data = dataclasses.asdict(resolved)
         data.pop("assets", None)
+        data.pop("exercises", None)
         data["total_duration_minutes"] = _compute_total_duration_minutes(resolved)
         curriculum_json.write_text(
             json.dumps(data, indent=2, ensure_ascii=False) + "\n",
@@ -240,17 +241,61 @@ def _write_curriculum_json(resolved: ResolvedCurriculum, output_dir: Path) -> No
     logger.debug("Wrote curriculum.json (%d bytes)", curriculum_json.stat().st_size)
 
 
+def _write_exercises(resolved: ResolvedCurriculum, output_dir: Path) -> None:
+    """Write each ``ready`` exercise's marimo notebook to its runnable path and
+    emit the ``exercises-manifest.json`` sidecar at the project root.
+
+    Notebooks live **outside** ``static/`` — the learner runs them with
+    ``marimo`` (via ``learningfoundry launch``), they are not web-served. The
+    sidecar maps ``id → {notebook_path, mode, port}``; ``learningfoundry
+    launch`` reads it to serve the right notebook. Both are regenerated each
+    build (not preserved) — only the curriculum author runs ``build``; the
+    learner runs the cloned output, so their marimo edits are never clobbered.
+    """
+    if not resolved.exercises:
+        return
+
+    manifest: dict[str, dict[str, object]] = {}
+    for ex in resolved.exercises:
+        notebook = output_dir / ex.notebook_path
+        try:
+            notebook.parent.mkdir(parents=True, exist_ok=True)
+            notebook.write_text(ex.notebook_source, encoding="utf-8")
+        except OSError as exc:
+            raise GenerationError(
+                f"Failed to write exercise notebook `{notebook}`: {exc}"
+            ) from exc
+        manifest[ex.id] = {
+            "notebook_path": ex.notebook_path,
+            "mode": ex.mode,
+            "port": ex.port,
+        }
+
+    manifest_path = output_dir / "exercises-manifest.json"
+    try:
+        manifest_path.write_text(
+            json.dumps(manifest, indent=2, ensure_ascii=False) + "\n",
+            encoding="utf-8",
+        )
+    except OSError as exc:
+        raise GenerationError(
+            f"Failed to write exercises manifest to `{manifest_path}`: {exc}"
+        ) from exc
+
+    logger.info(
+        "Wrote %d exercise notebook(s) + manifest.", len(resolved.exercises)
+    )
+
+
 def _copy_assets(resolved: ResolvedCurriculum, output_dir: Path) -> None:
     """Copy each ``Asset`` to ``output_dir/static/<dest_relative>``.
 
     Idempotent: a destination file whose size matches the source is left
-    untouched. For content-hashed image paths
-    (``content/<sha256[:12]>/<basename>``) a matching size on a matching-hash
-    path implies matching content, so the skip is exact. For non-hashed
-    exercise paths (``exercises/<id>/<path>``, Story K.e) the size check is a
-    cheap heuristic — a same-size edit to a staged exercise asset would be
-    skipped; the `static/exercises` preservation across rebuilds plus the
-    stable `id` namespace make that an acceptable trade for fast rebuilds.
+    untouched. ``dest_relative`` is content-hashed
+    (``content/<sha256[:12]>/<basename>``), so a matching size on a
+    matching-hash path implies matching content — re-copying would be wasted
+    I/O. (Marimo exercise notebooks are written separately by
+    ``_write_exercises``, not copied here.)
     """
     if not resolved.assets:
         return

{learningfoundry-0.82.0 → learningfoundry-0.83.0}/src/learningfoundry/integrations/nbfoundry_stub.py

@@ -27,13 +27,10 @@ def stub_exercise(ref_path: Path) -> dict:  # type: ignore[type-arg]
         "ref": str(ref_path),
         "status": "stub",
         "title": f"Exercise: {ref_path.stem}",
-        "instructions": (
+        "description": (
             f"<p>Exercise placeholder for <code>{ref_path}</code>. "
             "nbfoundry integration pending.</p>"
         ),
-        "sections": [],
-        "expected_outputs": [],
-        "assets": [],
         "hints": [],
         "environment": None,
     }