Convert notebooks to marimo

.agents/skills/README.md

@@ -13,7 +13,8 @@ plus optional `references/` files.
 
 ## Scripts
 
-Use [`../scripts/prepare-marimo-example.sh`](../scripts/prepare-marimo-example.sh)
+Use [`../../scripts/convert-colab-to-marimo.py`](../../scripts/convert-colab-to-marimo.py)
 to create the initial marimo notebook from a Jupyter `.ipynb`, capture
 `marimo check` output, and write a temporary `.conversion/` report directory
-for the polishing pass.
+for the polishing pass. The report directory includes a Markdown handoff,
+raw convert/check output, structured JSON metadata, and an event log.

.agents/skills/marimo-wandb-notebooks/SKILL.md

@@ -9,15 +9,25 @@ description: Create, convert, review, or refactor repo-ready marimo example note
 
 | Situation | Do this |
 | --- | --- |
-| Always | Read [`references/marimo-idioms.md`](references/marimo-idioms.md). |
-| Starting from an existing marimo `.py` | Do not run `prepare-marimo-example.sh`. Inspect the `.py`, run `uvx marimo check <notebook.py>`, and polish against the repo conventions below. |
-| Starting from `.ipynb` | Run [`../../scripts/prepare-marimo-example.sh`](../../scripts/prepare-marimo-example.sh) `<notebook.ipynb> --name <example-name>`, then read [`references/conversion-cleanup.md`](references/conversion-cleanup.md) with `.conversion/conversion-report.md` and `.conversion/marimo-check.txt`. |
+| Always | Read [`references/marimo-idioms.md`](references/marimo-idioms.md) and [`references/tutorial-notebook-objectives.md`](references/tutorial-notebook-objectives.md). |
+| Starting from an existing marimo `.py` | Inspect the `.py` and read nearby pipeline logs (`result.json`, `marimo-check.log`, and `marimo-convert.log`) in `.logs/` first. For converted notebooks under `marimo/convert/`, also read [`references/convert-cleanup.md`](references/convert-cleanup.md) before broad cleanup. |
+| Starting from `.ipynb` | Run [`../../../scripts/convert-colab-to-marimo.py`](../../../scripts/convert-colab-to-marimo.py) `<notebook.ipynb> --name <example-name>`, then read [`references/convert-cleanup.md`](references/convert-cleanup.md) and the generated `marimo/convert/<name>/.logs/result.json`. |
 | Notebook uses W&B | Read [`references/wandb-patterns.md`](references/wandb-patterns.md). |
 
+Preserve tutorial teaching value while applying marimo conventions.
+
 The canonical exemplar is
 `examples/marimo/mnist-registry/mnist_registry.py` — when in doubt, match
 its structure.
 
+## Existing conversion triage
+
+For notebooks under `marimo/convert/`, diagnose logs before polishing. Read
+`.logs/result.json`, inspect the failed stage's log, fix `marimo check`
+blockers first, then run a fresh `uvx marimo check`. See
+[`references/convert-cleanup.md`](references/convert-cleanup.md) for the full
+triage and cleanup checklist.
+
 ## Repo conventions
 
 - Each example lives in its own directory: `examples/marimo/<example-name>/`,
@@ -42,45 +52,24 @@ its structure.
 
 ## Notebook structure
 
-Order the notebook as a narrative the reader scrolls through top to bottom:
-
-1. **Setup cell** — `with app.setup(hide_code=True):` holds all imports,
-   constants, and environment detection (e.g. device selection). One place,
-   not scattered across cells.
-2. **Intro prose** — a markdown cell (`hide_code=True`) with the title,
-   "What you will build", and "Prerequisites". Prose goes in markdown cells,
-   never mixed into code cells.
-3. **`mo.outline()`** in its own cell near the top, so readers see the
-   notebook's shape at a glance.
-4. **Configuration** — all UI controls batched into a single submittable
-   form (see below).
-5. **The pipeline** — logic cells that consume the form, interleaved with
-   `## Section` markdown cells.
-6. **Verify and next steps** — a closing markdown cell telling the reader
-   exactly what to look at (in the W&B UI: which charts, tabs, panels) and
-   what to try next.
-7. **Helper functions** — `@app.function` / `@app.class_definition` cells
-   under a `## Helper functions` section at the bottom.
-
-## Gate execution once, then let the graph run
-
-Batch expensive controls into one form, gate once with `mo.stop`, and let
-downstream cells depend on names defined after the gate. See
-[`references/marimo-idioms.md`](references/marimo-idioms.md) for the detailed
-pattern.
-
-## Separate logic from presentation
-
-Put heavy work in named helpers and keep view cells focused on rendering. See
-[`references/marimo-idioms.md`](references/marimo-idioms.md) for details.
+Use this marimo skeleton: setup cell, intro, outline, configuration form,
+gated pipeline, verify/next steps, helper functions. See
+[`references/marimo-idioms.md`](references/marimo-idioms.md) for marimo
+mechanics and
+[`references/tutorial-notebook-objectives.md`](references/tutorial-notebook-objectives.md)
+for narrative structure.
+
+## Core priorities
+
+- Gate expensive work once, then let marimo's graph run.
+- Preserve visible teaching code, especially featured W&B API calls.
+- Keep notebook globals scarce; move distracting scratch work into helpers.
 
 ## Final verification
 
 - `uvx marimo check <notebook.py>` passes.
 - Globals audit: anything only used inside one step should live in a helper.
-- The notebook reads top-to-bottom as a tutorial; every code cell either
-  shows output or is a named helper.
-- Fresh-eyes test: a reader with a new W&B account can follow Prerequisites,
-  submit the form, and verify the result from "Verify and next steps" alone.
-- `.conversion/` files are temporary debugging artifacts and must not be
+- Tutorial-objectives audit passes: narrative flow, visible API examples, and
+  reader verification are preserved.
+- `.logs/` files are temporary debugging artifacts and must not be
   referenced by the final notebook or docs.

.agents/skills/marimo-wandb-notebooks/references/convert-cleanup.md

@@ -0,0 +1,68 @@
+# Convert Cleanup
+
+Use this after `scripts/convert-colab-to-marimo.py` creates the initial
+marimo notebook from a Jupyter `.ipynb`. The converter writes diagnostics to
+`marimo/convert/<name>/.logs/`.
+
+## Start from convert logs
+
+- For batch runs, start with `marimo/convert/convert-summary.txt` to find
+  notebooks that need action.
+- Read `marimo/convert/<name>/.logs/result.json` first. Check `status`,
+  `failed_stage`, `source`, `target`, and each command's exit code.
+- If `failed_stage` is `convert`, read
+  `marimo/convert/<name>/.logs/marimo-convert.log` before editing the notebook.
+- If `failed_stage` is `check`, read
+  `marimo/convert/<name>/.logs/marimo-check.log` before editing the notebook.
+- If `status` is `ok`, still skim `result.json` to confirm the source and target
+  paths before cleanup.
+- Fix `marimo check` issues first; they often point to converted cells that
+  need to be split, reordered, or moved into helpers.
+
+## Common Converter Leftovers
+
+- Follow [`tutorial-notebook-objectives.md`](tutorial-notebook-objectives.md)
+  when deciding which instructional cells and W&B API examples to preserve.
+- Ensure the PEP 723 script metadata lists every runtime package the notebook
+  imports. The converter may miss dependencies.
+- Remove Jupyter-only artifacts such as `%magic` commands, shell escapes, and
+  unnecessary `display()` calls.
+- Make the intended output the final expression of each display cell. Indented
+  or conditional expressions will not render as cell output.
+- Replace notebook-global scratch variables with local variables inside helper
+  functions when they are only used in one step.
+- Prefer explicit markdown cells for prose. Do not leave tutorial text inside
+  code comments or string literals in logic cells.
+
+## Common Check Failures
+
+- Circular dependencies often come from imports or helper names returned by a
+  later cell and consumed by an earlier helper cell. Fix by moving shared
+  imports/constants into `app.setup(...)` or into the helper cell that uses
+  them, and avoid returning imported symbols from downstream logic cells.
+- `multiple-definitions` errors can happen after moving the same import into
+  multiple cells. Keep cell-local imports private with an underscore alias
+  such as `from torch.utils.data import DataLoader as _DataLoader`.
+
+## Widget Cleanup
+
+- Replace ipywidgets with native `mo.ui` components when there is a direct
+  equivalent.
+- Replace `interact`, `observe`, `link`, and `jslink` patterns with marimo
+  reactivity. Split UI definition, value consumption, and rendering into
+  separate cells.
+- Use `mo.ui.anywidget()` only when no native marimo component fits.
+
+## LaTeX Cleanup
+
+- Use raw strings for markdown containing LaTeX, such as `mo.md(r"$x^2$")`.
+- Replace MathJax-only constructs with KaTeX-compatible syntax.
+- Visually verify math-heavy outputs because KaTeX failures can be quiet.
+
+## Final Check
+
+Run:
+
+```bash
+uvx marimo check marimo/convert/<example-name>/<example_name>.py
+```