A reactive notebook for Python — run reproducible experiments, query with SQL, execute as a script, deploy as an app, and version with git. Stored as pure Python. All in a modern, AI-native editor.
Python artificial-intelligencedagdata-sciencedata-visualizationdataflowdeveloper-toolsmachine-learningnotebookspipelinepythonreactivesqlweb-app
docs(ai): keep sidebar code mode aligned with marimo-pair (#10683)
Shahmir Varqha8d130b92e224
diff --git a/marimo/_server/ai/skills/marimo-pair/SKILL.md b/marimo/_server/ai/skills/marimo-pair/SKILL.mdindex eb8e278006..0fedea06bb 100644--- a/marimo/_server/ai/skills/marimo-pair/SKILL.md+++ b/marimo/_server/ai/skills/marimo-pair/SKILL.md@@ -41,6 +41,25 @@ passing your Python as the `code` argument. Everything you do — inspectingstate, testing transformations, and persisting changes via `cm` — runs through`execute_code` in the scratchpad (see below).+## Required First Kernel Command++Start every code-mode session with this dedicated `execute_code` call:++```python+import marimo._code_mode as cm+help(cm)+```++Follow this order for every live kernel, including read-only tasks:++1. Run only the inspection command above.+2. Wait for successful `help(cm)` output.+3. Use `cm.get_context()` or another `cm` API in a later `execute_code` call.++Do not combine the inspection with task-specific code, and do not use another+`cm` API before the inspection succeeds. This verifies the private, unstable+API exposed by the marimo version in the user's active kernel.+## Scratchpad Scope`execute_code` evaluates Python in marimo's scratchpad: a temporary namespace@@ -80,14 +99,6 @@ anything a user would run — methods can change or disappear across marimoversions and kernels. Treat every `import marimo._code_mode as cm` asscratchpad-only.-At session start, inspect what `cm` exposes in the active kernel:--```python-import marimo._code_mode as cm--help(cm)-```-Open a code-mode context to queue notebook changes.```pythondiff --git a/marimo/_server/ai/skills/marimo-pair/references/gotchas.md b/marimo/_server/ai/skills/marimo-pair/references/gotchas.mdindex 147dc25f52..b072de6a35 100644--- a/marimo/_server/ai/skills/marimo-pair/references/gotchas.md+++ b/marimo/_server/ai/skills/marimo-pair/references/gotchas.md@@ -47,8 +47,11 @@ The same single-definition rule applies to imports: a public name (like `pd`)can only be defined in one cell. If two cells both `import pandas as pd`, youget a `Multiply-defined names` error at validation.-**Fix:** Use a `_` prefix on the second import (`import pandas as _pd`) or-consolidate imports into a shared cell.+**Fix:** Reuse the existing import — reference `pd` directly, or edit the+owning cell (`ctx.edit_cell`) if the import belongs there instead. If several+cells need the import, consolidate it into the setup cell or a shared+import-only cell. Load the `notebook-improvements` capability for setup-cell+guidance.## `inspect.getsource()` on methods is indenteddiff --git a/marimo/_server/ai/skills/marimo-pair/references/notebook-improvements.md b/marimo/_server/ai/skills/marimo-pair/references/notebook-improvements.mdindex ec6f7669a6..c04cc78338 100644--- a/marimo/_server/ai/skills/marimo-pair/references/notebook-improvements.md+++ b/marimo/_server/ai/skills/marimo-pair/references/notebook-improvements.md@@ -25,6 +25,14 @@ it must be self-contained: imports, constants, and definitions that depend onlyon each other. Reading a name defined elsewhere (e.g. `df`, a UI element) failswith `The setup cell cannot have references`.+**Keep the setup cell import-only if you can.** marimo skips re-running+descendants when an edited cell contains only import statements, because+imports resolve independently of the notebook's reactive dataflow. This+applies to every import-only cell, not only `setup`. It matters most for+`setup`, because every other cell depends on it: if the setup cell also defines+constants or other values, editing it re-runs the entire notebook. Put those+definitions in a separate cell downstream of `setup`.+First check if the notebook already has a cell named `"setup"`. If not, createone and hoist scattered imports into it. `name="setup"` auto-positions the cellfirst — no `before`/`after` needed:diff --git a/tests/_server/ai/test_prompts.py b/tests/_server/ai/test_prompts.pyindex ab974b2007..05060c097b 100644--- a/tests/_server/ai/test_prompts.py+++ b/tests/_server/ai/test_prompts.py@@ -423,6 +423,9 @@ def test_chat_system_prompt_code_mode():assert "load_capability" in promptassert "`gotchas`" in promptassert "references/gotchas.md" not in prompt+ assert "## Required First Kernel Command" in prompt+ assert "Run only the inspection command above" in prompt+ assert "before the inspection succeeds" in promptdef test_chat_system_prompt_code_mode_includes_extras():