Strengthen marimo notebook conversion guidance

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

@@ -51,12 +51,25 @@ Also read:
 - Use the original `.ipynb` for tutorial intent, narrative, and featured W&B
   behavior.
 - Treat the current `.py` as the current conversion state.
+- When the user designates a live marimo or molab notebook, or an artifact
+  exported from it, as authoritative, it overrides the repository `.py` as the
+  current implementation state. The original `.ipynb` remains a reference for
+  intent, not a reason to rewrite the designated artifact. Do not edit the live
+  notebook or update a branch unless requested. When syncing is requested,
+  export or download after the final approved live edit and preserve cell order,
+  boundaries, setup status, identifiers, dependency metadata, working
+  integrations, and configuration such as `hide_code` and `disabled` unless the
+  request requires changing them or a demonstrated runtime issue requires a
+  dependency correction.
 - Treat `.logs/` as historical diagnostic evidence.
 - Use a fresh `marimo check` for current static validity.
 - Use `examples/marimo/mnist-registry/mnist_registry.py` as the structural
   exemplar when the references do not specify a choice, especially its
   separation of marimo orchestration cells from reusable `@app.function`
   helpers. Do not copy tutorial-specific details from the exemplar.
+- Notebook review or repair does not authorize submitting live credentials or
+  remote-write controls, committing, pushing, or changing a pull request.
+  Perform those actions only when the user explicitly requests them.
 
 ## Conversion priorities
 
@@ -99,7 +112,12 @@ Give a concrete fix for each issue. Do not modify files unless asked.
 
 Before considering a conversion complete:
 
-- `uvx marimo check <notebook.py>` passes.
+- `uvx marimo check <notebook.py>` passes after the final notebook edit; do
+  not rely on a saved conversion log or an earlier successful check.
+- A fresh sandboxed local session or molab session opens without cell errors.
+  Every intended widget, form, and embedded player visibly renders, and each
+  orchestration cell reads a documented reactive value. Keep remote-write
+  controls unsubmitted, or use an offline/test backend, during this smoke test.
 - Notebook structure follows
   [`references/marimo-idioms.md`](references/marimo-idioms.md), including the
   separation of teaching code, marimo orchestration, and reusable helpers.
@@ -115,6 +133,8 @@ Before considering a conversion complete:
   closes prior runs and avoids duplicate stateful updates where practical.
 - Cross-cell consumers of W&B state use explicit result or completion values,
   and producers synchronize server-visible state before downstream reads.
-- A fresh molab session can authenticate without credentials from the local
-  computer, and no credential appears in notebook output, run configuration,
-  logs, or the diff.
+- A fresh molab session presents an authentication path that does not assume
+  credentials from the local computer. Inspect the inputs and gate without
+  submitting real credentials; test live authentication only when explicitly
+  requested or with a designated test backend. No credential appears in
+  notebook output, run configuration, logs, or the diff.

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

@@ -25,12 +25,21 @@ marimo notebook from a Jupyter `.ipynb`. The converter writes diagnostics to
   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.
+- Move `%pip` and `!pip install` requirements into PEP 723 metadata, then remove
+  the obsolete install command, generated install commentary, and any empty
+  cell it leaves behind. Do not replace package installation with a subprocess.
 - Remove Jupyter-only artifacts such as `%magic` commands, shell escapes, and
   unnecessary `display()` calls.
+- Translate remaining shell escapes by purpose instead of mechanically wrapping
+  every command in `subprocess`. Use `fsspec` when file-like or filesystem
+  access is useful, and reserve `subprocess` for programs that genuinely need a
+  separate process.
 - 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.
+- When cleanup is requested and it improves clarity, replace notebook-global
+  scratch variables with locals inside helper functions. Do not do this during
+  an exact synchronization or when it would rename or obscure teaching code
+  without resolving a demonstrated graph problem.
 - Prefer explicit markdown cells for prose. Do not leave tutorial text inside
   code comments or string literals in logic cells.
 
@@ -44,6 +53,32 @@ marimo notebook from a Jupyter `.ipynb`. The converter writes diagnostics to
   multiple cells. Keep cell-local imports private with an underscore alias
   such as `from torch.utils.data import DataLoader as _DataLoader`.
 
+## Molab and Remote Assets
+
+- Do not assume molab's **Mirror from GitHub** action provides a checkout of the
+  whole repository. A notebook and its dependency metadata can be present
+  while sibling data files are not.
+- Preserve a working asset-loading backend. Do not replace it solely because a
+  different backend might avoid a hypothetical hosted-environment limit.
+- Use `fsspec.filesystem("github", org=..., repo=...)` with repository-relative
+  paths when repository listing or marimo's Remote Storage browser is useful.
+  Anonymous hosted sessions can share GitHub's API quota; respond to a
+  demonstrated rate-limit failure with an optional token from runtime secrets
+  or environment, or use raw HTTPS for the affected known files. Never hardcode
+  a token.
+- A named HTTP filesystem with `raw.githubusercontent.com` URLs avoids GitHub's
+  repository API when only known public files are required. A bare
+  `HTTPFileSystem` can open concrete URLs but has no listable root, so do not
+  select it solely to expose a browsable source in marimo's Remote Storage
+  panel.
+- Declare `fsspec[http]`, not only `fsspec`, for HTTP files, Git-LFS content,
+  and GitHub files larger than 1 MB.
+- Pass file-like objects directly when the consumer supports them. Otherwise,
+  adapt in memory with `io.BytesIO` or `io.StringIO`, or materialize only the
+  specific file an API requires.
+- Clone a repository only when the tutorial needs Git history, repository
+  semantics, or a local directory tree rather than a few read-only assets.
+
 ## Widget Cleanup
 
 - Replace ipywidgets with native `mo.ui` components when there is a direct
@@ -61,8 +96,15 @@ marimo notebook from a Jupyter `.ipynb`. The converter writes diagnostics to
 
 ## Final Check
 
-Run:
+After the final notebook edit, run:
 
 ```bash
 uvx marimo check marimo/convert/<example-name>/<example_name>.py
 ```
+
+Then open the notebook in a fresh molab session or a local sandbox. Confirm
+that intended controls and embeds render, change each safe control at least
+once, and inspect cell errors. Static checking cannot detect a nonexistent
+runtime attribute such as `.clicked` or a widget that was constructed but
+never returned for display. Keep remote-write controls unsubmitted, or use an
+offline/test backend, during this smoke test.

.agents/skills/marimo-wandb-notebooks/references/marimo-idioms.md

@@ -33,14 +33,25 @@ Do not add marimo orchestration, generated dependency plumbing, or
 underscore-prefixed scratch variables to teaching code merely to satisfy the
 reactive graph.
 
-Use underscore-prefixed temporaries in orchestration or presentation cells when
-useful. When teaching code is naturally expressed as a function, keep the
-function clean and put its gate or UI wiring in separate cells.
+Preserve original identifiers in teaching code. Do not mechanically prefix a
+unique name with `_` merely because no later cell reads it. First inspect actual
+definitions and references across cells. Use private names to resolve a real
+cross-cell redefinition or for newly introduced implementation-only plumbing,
+such as file handles, context-manager targets, or UI internals.
+
+When teaching code is naturally expressed as a function, keep the function
+clean and put its gate or UI wiring in separate cells.
 
 ## Reactivity
 
 - Let the dependency graph determine execution. A cell runs when its inputs are
   ready.
+- `mo.stop()`, `if`, `for`, and `with` control runtime execution; they do not
+  create a static scope. Imports, assignment targets, loop targets, and context
+  manager targets anywhere in a cell still define names in marimo's graph. Give
+  each shared name one owning cell. Keep unique teaching names public even when
+  they have no downstream consumer; use `_` for genuinely private plumbing or
+  repeated scratch names, or move procedural work into a function.
 - Do not rely on cross-cell mutation for reactivity; marimo does not track
   object mutations or attribute assignments. Prefer creating a new value, or
   mutate an object only in the cell that defines it.
@@ -107,10 +118,26 @@ helpers. Do not repeat the same gate in downstream cells.
   named helpers.
 - Prefer native components such as `mo.ui.table`, `mo.callout`, `mo.vstack`,
   and `mo.hstack` over formatting complex UI as markdown.
+- Use `mo.video` for a direct video URL, file, or bytes. For a hosted player
+  such as YouTube, use the provider's canonical HTTPS embed URL in a trusted
+  `mo.Html` iframe with a descriptive title and a normal link fallback.
+- For the W&B header pattern used by the media tutorial, use
+  `https://raw.githubusercontent.com/wandb/docs/main/icons/Endorsed_primary_blackwhite.svg`
+  in the light theme and
+  `https://raw.githubusercontent.com/wandb/docs/main/icons/Endorsed_primary_goldwhite.svg`
+  in the dark theme. Render both and switch them with marimo's `body.dark`
+  class; visually verify both themes. For the verified marimo `mo.callout`
+  pattern, select the theme with `:host-context(body.dark)` so the rule crosses
+  the component boundary.
 
 ## UI
 
-- Show widgets directly and read their `.value` in orchestration cells.
+- Constructing or assigning a widget does not display it. End the definition
+  cell with the widget or a layout containing it; returning it only wires the
+  reactive dependency graph.
+- Show widgets directly and read documented reactive state such as `.value` in
+  orchestration cells. Do not invent callback-style attributes such as
+  `.clicked`; inspect the live object or official API when uncertain.
 - Prefer native `mo.ui` components before reaching for `anywidget`.
 
 ## Error Handling

.agents/skills/marimo-wandb-notebooks/references/tutorial-notebook-objectives.md

@@ -32,9 +32,13 @@ Use this when creating, reviewing, or polishing W&B example notebooks.
 
 ## Reader Verification
 
-- End with a clear "Verify and next steps" section.
-- Tell the reader exactly what to inspect in the W&B UI, including relevant
-  charts, tabs, panels, Artifacts, Registry collections, or run summary fields.
+- Preserve the source notebook's ending. Add or adapt concise verification and
+  next-step guidance only when readers otherwise lack a clear way to confirm
+  the tutorial result; do not append generic boilerplate during a repair or
+  exact synchronization.
+- When verification guidance is needed, tell the reader exactly what to inspect
+  in the W&B UI, including relevant charts, tabs, panels, Artifacts, Registry
+  collections, or run summary fields.
 - Apply a fresh-eyes test: a reader following the documented prerequisites
-  should be able to complete the tutorial and verify the result from the final
-  section alone.
+  should be able to complete the tutorial and verify the result from the
+  notebook's guidance.

.agents/skills/marimo-wandb-notebooks/references/wandb-patterns.md

@@ -4,6 +4,10 @@ Use these patterns when a marimo example uses the W&B Python SDK.
 
 ## Authentication
 
+- Keep exactly one reader-facing Authentication section. Consolidate signup,
+  API-key, entity, and login guidance and controls there. Remove duplicate
+  standalone Colab-era signup and API-key prompts once their essential guidance
+  is represented in this section; preserve unique tutorial-specific context.
 - Offer a `mo.ui.text(kind="password")` API-key field.
 - Call `wandb.login()` only after the reader explicitly submits the form or
   clicks the run button.
@@ -37,6 +41,26 @@ active across cells, finish any prior active run before starting another one.
   idempotent when practical, such as skipping an alias or Registry link that is
   already present.
 
+### Runs Created By Child Processes
+
+When readers need a dashboard link before a blocking command-line program
+finishes, preassign the W&B run identity before launching the process:
+
+- Resolve concrete project, entity, and run ID values, then derive the run URL
+  from those same values with `wandb.Settings(...).run_url`.
+- Start with `os.environ.copy()` and add `WANDB_PROJECT`, `WANDB_ENTITY`, and
+  `WANDB_RUN_ID`. Pass that mapping as `env` and use `check=True` with
+  `subprocess.run`; never display the environment because it can contain
+  secrets.
+- Keep preparation, process execution, and URL presentation in separate cells.
+  Make the process and URL cells depend on the prepared values, not on each
+  other, so the dashboard link can render while the command is still running.
+- Do not assume authentication enables a framework's W&B integration. Pass its
+  explicit integration option when required—for Hugging Face Trainer commands,
+  use `--report_to wandb`—and verify that the expected run is created.
+- Pass actual values in the argument list. List-form `subprocess.run` does not
+  expand shell variables such as `$WANDB_PROJECT`.
+
 ## Ordering Remote Effects
 
 marimo orders cells through name dependencies; it cannot observe mutations to
@@ -69,6 +93,19 @@ marimo orders cells through name dependencies; it cannot observe mutations to
 - Move non-teaching plumbing into helpers when it improves the teaching
   surface.
 
+## Media From Remote Filesystems
+
+- Preserve the real media format when adapting a remote file. For example,
+  pass MP4 bytes through `io.BytesIO` to `wandb.Video(..., format="mp4")`
+  instead of relabeling the source as a GIF.
+- Decode audio with a library such as `soundfile` and pass the detected sample
+  rate to `wandb.Audio`; do not guess from the tutorial text or source code.
+- For OBJ text read from a remote filesystem, use `io.StringIO` and pass
+  `file_type="obj"` to `wandb.Object3D`. Some file-like objects expose a
+  `.name` that an SDK can mistake for a local path.
+- When logging HTML content rather than a local path, pass the text explicitly
+  with `data_is_not_path=True`.
+
 ## Expected Failures
 
 - Catch only expected, recoverable W&B failures where the notebook can provide