calkit-python 0.41.14__tar.gz → 0.41.15__tar.gz

{calkit_python-0.41.14 → calkit_python-0.41.15}/AGENTS.md

@@ -43,3 +43,6 @@ The only exception here is if splitting up a function makes it easier to
 write meaningful unit tests.
 If a function is only used inside one other function, nest it inside the
 caller at the top.
+
+No spaces on either side of en or em dashes used for ranges or pauses in prose,
+respectively.

{calkit_python-0.41.14 → calkit_python-0.41.15}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: calkit-python
-Version: 0.41.14
+Version: 0.41.15
 Summary: Reproducibility simplified.
 Project-URL: Homepage, https://calkit.org
 Project-URL: Issues, https://github.com/calkit/calkit/issues

{calkit_python-0.41.14 → calkit_python-0.41.15}/calkit/cli/check.py

@@ -180,7 +180,8 @@ def _check_julia_env(
         try:
             subprocess.check_call(
                 cmd,
-                env=os.environ.copy() | {"JULIA_LOAD_PATH": "@:@stdlib"},
+                env=os.environ.copy()
+                | {"JULIA_LOAD_PATH": calkit.julia.load_path()},
             )
         except subprocess.CalledProcessError:
             calkit.environments.save_cache(
@@ -206,7 +207,9 @@ def _check_julia_env(
     cmd = calkit.julia.ensure_startup_file_disabled_in_command(cmd)
     try:
         subprocess.check_call(
-            cmd, env=os.environ.copy() | {"JULIA_LOAD_PATH": "@:@stdlib"}
+            cmd,
+            env=os.environ.copy()
+            | {"JULIA_LOAD_PATH": calkit.julia.load_path()},
         )
     except subprocess.CalledProcessError:
         calkit.environments.save_cache(

{calkit_python-0.41.14 → calkit_python-0.41.15}/calkit/cli/main/core.py

@@ -581,6 +581,18 @@ def get_status(
         if pipeline_status and not pipeline_status.has_pipeline:
             typer.echo("This project has no pipeline.")
             return
+        # A failed environment check makes get_status bail out before computing
+        # staleness, leaving stale_stages empty. Don't let that masquerade as an
+        # up-to-date pipeline---say plainly that the status is unknown.
+        elif pipeline_status and pipeline_status.failed_environment_checks:
+            # The failing environments were already named in the warning emitted
+            # right after computing pipeline_status, so keep this explanatory
+            # only rather than repeating the list.
+            typer.echo(
+                "Pipeline status unavailable until the failed environment "
+                "checks above are resolved."
+            )
+            return
         elif pipeline_status and pipeline_status.is_stale:
             typer.echo("Stale stages:")
             for stage_name in pipeline_status.stale_stage_names:
@@ -2586,7 +2598,8 @@ def run_in_env(
             subprocess.check_call(
                 julia_cmd,
                 cwd=wdir,
-                env=os.environ.copy() | {"JULIA_LOAD_PATH": "@:@stdlib"},
+                env=os.environ.copy()
+                | {"JULIA_LOAD_PATH": calkit.julia.load_path()},
             )
         except subprocess.CalledProcessError:
             raise_error("Failed to run in julia environment")

{calkit_python-0.41.14 → calkit_python-0.41.15}/calkit/cli/new.py

@@ -2108,7 +2108,7 @@ def new_julia_env(
         except subprocess.CalledProcessError:
             raise_error(f"Failed to install Julia version {julia_version}")
         cmd = ["julia", f"+{julia_version}", f"--project={env_dir}", "-e"]
-        install_cmd = f'using Pkg; Pkg.activate("{env_dir}");'
+        install_cmd = f'using Pkg; Pkg.activate("{calkit.julia.escape_string(env_dir)}");'
         for package in packages or []:
             install_cmd += f' Pkg.add("{package}");'
         cmd.append(install_cmd)

{calkit_python-0.41.14 → calkit_python-0.41.15}/calkit/cli/notebooks.py

@@ -310,14 +310,18 @@ def check_env_kernel(
                     "still failed."
                 )
         # Don't include version in display_name; IJulia appends it automatically
+        # Escape interpolated values for the Julia string literals---notably the
+        # Windows project path, whose backslashes are otherwise read as invalid
+        # unicode escapes.
+        esc = calkit.julia.escape_string
         julia_cmd = (
             "import IJulia;"
             "kp=IJulia.installkernel("
-            f'"{kernel_name}",'
-            f'"--project={env_dir_abs}",'
+            f'"{esc(kernel_name)}",'
+            f'"--project={esc(env_dir_abs)}",'
             '"--startup-file=no",'
-            f'displayname="{display_name}",'
-            'env=Dict("JULIA_LOAD_PATH" => "@:@stdlib")'
+            f'displayname="{esc(display_name)}",'
+            f'env=Dict("JULIA_LOAD_PATH" => "{esc(calkit.julia.load_path())}")'
             ");"
             "println(kp);"
         )
@@ -474,8 +478,7 @@ def execute_notebook(
         # Create this environment and write it to file
         envs[res.name] = res.env
         ck_info["environments"] = envs
-        with open("calkit.yaml", "w") as f:
-            calkit.ryaml.dump(ck_info, f)
+        calkit.save_calkit_info(ck_info)
     # Detect language from environment
     if language is None:
         detected_language = language_from_notebook(path)
@@ -501,16 +504,20 @@ def execute_notebook(
         raise ValueError(
             "Language must be one of 'python', 'matlab', 'julia', or 'r'"
         )
-    # Try to set kernelspec metadata so execution uses the expected kernel
+    # Try to set kernelspec metadata so execution uses the expected kernel.
+    # Always read/write as UTF-8: notebooks routinely contain non-ASCII (e.g.,
+    # Greek letters such as "ν" in code), and on Windows the default open()
+    # encoding is cp1252, which mangles UTF-8 content into mojibake ("ν" ->
+    # "ν") and breaks execution.
     try:
-        with open(path, "r") as f:
+        with open(path, "r", encoding="utf-8") as f:
             nb_json = json.load(f)
         metadata = nb_json.setdefault("metadata", {})
         kernelspec = metadata.setdefault("kernelspec", {})
         kernelspec["name"] = kernel_name
         kernelspec["display_name"] = display_name
-        kernelspec.setdefault("language", language.lower())
-        with open(path, "w") as f:
+        kernelspec["language"] = language.lower()
+        with open(path, "w", encoding="utf-8") as f:
             json.dump(nb_json, f, indent=1)
     except Exception as e:
         if verbose:

{calkit_python-0.41.14 → calkit_python-0.41.15}/calkit/cli/update.py

@@ -746,7 +746,7 @@ def update_julia_env(
     env_dir = os.path.dirname(spec_path) or "."
     julia_version = env.get("julia")
     julia_bin = ["julia", f"+{julia_version}"] if julia_version else ["julia"]
-    cmds = [f'Pkg.activate("{env_dir}")']
+    cmds = [f'Pkg.activate("{calkit.julia.escape_string(env_dir)}")']
     if add:
         pkg_list = "[" + ", ".join(f'"{p}"' for p in add) + "]"
         cmds.append(f"Pkg.add({pkg_list})")

{calkit_python-0.41.14 → calkit_python-0.41.15}/calkit/core.py

@@ -144,7 +144,9 @@ def load_calkit_info(
     if wdir is not None:
         fpath = os.path.join(wdir, fpath)
     if os.path.isfile(fpath):
-        with open(fpath) as f:
+        # Always read as UTF-8; on Windows the default open() encoding is
+        # cp1252, which mangles non-ASCII content (e.g., Greek letters).
+        with open(fpath, encoding="utf-8") as f:
             info = ryaml.load(f)
     if info is None:
         info = {}
@@ -166,7 +168,7 @@ def load_calkit_info(
                         if wdir is not None:
                             include_fpath = os.path.join(wdir, include_fpath)
                         if os.path.isfile(include_fpath):
-                            with open(include_fpath) as f:
+                            with open(include_fpath, encoding="utf-8") as f:
                                 include_data = ryaml.load(f)
                             info[kind][obj_name] |= include_data
     return info
@@ -180,7 +182,9 @@ def save_calkit_info(
     fpath = "calkit.yaml"
     if wdir is not None:
         fpath = os.path.join(wdir, fpath)
-    with open(fpath, "w") as f:
+    # Always write as UTF-8; on Windows the default open() encoding is cp1252,
+    # which mangles non-ASCII content (e.g., Greek letters) into mojibake.
+    with open(fpath, "w", encoding="utf-8") as f:
         ryaml.dump(info, f)
 
 

{calkit_python-0.41.14 → calkit_python-0.41.15}/calkit/julia.py

@@ -27,9 +27,36 @@ def get_julia_exe() -> str:
     return "julia"
 
 
+def load_path() -> str:
+    """Return the ``JULIA_LOAD_PATH`` scoping resolution to the active project
+    and stdlib.
+
+    Julia splits ``JULIA_LOAD_PATH`` on the platform path separator---``;`` on
+    Windows and ``:`` elsewhere---so a hardcoded ``:`` leaves ``@stdlib`` off
+    the load path on Windows and even stdlib packages (e.g. ``Pkg``) fail to
+    resolve. ``os.pathsep`` matches Julia's rule on every platform.
+    """
+    return os.pathsep.join(["@", "@stdlib"])
+
+
+def escape_string(value: str) -> str:
+    """Escape ``value`` for embedding in a Julia double-quoted string literal.
+
+    Julia treats ``\\``, ``"`` and ``$`` specially inside double quotes. In
+    particular a Windows path like ``C:\\Users\\...`` is otherwise read as an
+    invalid ``\\U`` unicode escape, so any value interpolated into Julia source
+    (e.g., a ``--project`` path passed via ``julia -e``) must be escaped.
+    """
+    return value.replace("\\", "\\\\").replace('"', '\\"').replace("$", "\\$")
+
+
 def _is_julia_command(arg: str) -> bool:
-    """Whether ``arg`` is a Julia executable (julia or the juliaup launcher)."""
-    base = os.path.basename(arg)
+    """Whether ``arg`` is a Julia executable (julia or the juliaup launcher).
+
+    The comparison is case-insensitive so Windows paths like ``julia.EXE``
+    (e.g. the ``WindowsApps`` execution-alias shim) are recognized.
+    """
+    base = os.path.basename(arg).lower()
     if base.endswith(".exe"):
         base = base[: -len(".exe")]
     return base in ("julia", "julialauncher")

{calkit_python-0.41.14 → calkit_python-0.41.15}/calkit/notebooks.py

@@ -242,11 +242,9 @@ def declare_notebook(
             }
         )
     # Write calkit.yaml
-    fpath = os.path.join(wdir, "calkit.yaml")
     ck_info["pipeline"] = pipeline_dict
     ck_info["notebooks"] = notebooks
-    with open(fpath, "w") as f:
-        calkit.ryaml.dump(ck_info, f)
+    calkit.save_calkit_info(ck_info, wdir=wdir)
     if must_be_rerun:
         raise RuntimeError(
             f"Notebook stage '{stage_name}' was modified while the pipeline "

{calkit_python-0.41.14 → calkit_python-0.41.15}/calkit/pipeline.py

@@ -1011,6 +1011,35 @@ def get_output_storage_map(
     return result
 
 
+def _dump_yaml_if_changed(data, fpath: str, verbose: bool = False) -> bool:
+    """Write ``data`` to ``fpath`` as YAML only if it changes the file.
+
+    ``calkit status`` recompiles the pipeline to DVC on every call, and the VS
+    Code extension polls status continuously. Blindly rewriting an identical
+    file causes two problems: (1) bumping ``dvc.yaml``'s mtime wakes the
+    extension's file watcher, which triggers yet another status poll---an
+    endless loop that keeps re-taking DVC's lock; and (2) the serializer formats
+    slightly differently across platforms and ruamel versions, so the file
+    churns in Git for no real change. Comparison is on the parsed structure, so
+    trivial reformatting is not treated as a change. DVC keys stage staleness on
+    ``dvc.lock`` (not on ``dvc.yaml``'s mtime), so skipping a no-op write is
+    safe. Returns whether the file was written.
+    """
+    if os.path.isfile(fpath):
+        try:
+            with open(fpath) as f:
+                if (calkit.ryaml.load(f) or {}) == data:
+                    return False
+        except Exception:
+            # Unreadable or invalid existing YAML: fall through and overwrite.
+            pass
+    if verbose:
+        typer.echo(f"Writing to {os.path.basename(fpath)}")
+    with open(fpath, "w") as f:
+        calkit.ryaml.dump(data, f)
+    return True
+
+
 def to_dvc(
     ck_info: dict | None = None,
     wdir: str | None = None,
@@ -1099,8 +1128,7 @@ def to_dvc(
                 with open(dvc_yaml_fpath) as f:
                     existing = calkit.ryaml.load(f) or {}
             existing.setdefault("stages", {}).update(wrapper_stages)
-            with open(dvc_yaml_fpath, "w") as f:
-                calkit.ryaml.dump(existing, f)
+            _dump_yaml_if_changed(existing, dvc_yaml_fpath)
         return wrapper_stages
     # Detect stages with the old ``slurm:`` field before model validation
     # because model_validate pops it in place.
@@ -1194,8 +1222,7 @@ def to_dvc(
         for sname in slurm_field_stages:
             stage_data = ck_yaml_data["pipeline"]["stages"][sname]
             stage_data["scheduler"] = stage_data.pop("slurm")
-        with open(ck_yaml_path, "w") as _f:
-            calkit.ryaml.dump(ck_yaml_data, _f)
+        _dump_yaml_if_changed(ck_yaml_data, ck_yaml_path)
     # Validate and initialize scheduler options (SLURM/PBS) for stages
     # whose outer environment is a job scheduler. Env defaults are applied
     # at job-submission time, not here.
@@ -1372,10 +1399,7 @@ def to_dvc(
                 dvc_stages[stage_name] = stage
         dvc_yaml["stages"] = dvc_stages
         dvc_yaml_fpath = os.path.join(wdir, "dvc.yaml") if wdir else "dvc.yaml"
-        with open(dvc_yaml_fpath, "w") as f:
-            if verbose:
-                typer.echo("Writing to dvc.yaml")
-            calkit.ryaml.dump(dvc_yaml, f)
+        _dump_yaml_if_changed(dvc_yaml, dvc_yaml_fpath, verbose=verbose)
         # DVC errors out (FileIsGitIgnored) if dvc.lock is Git-ignored, so make
         # sure it isn't---this keeps both status and pipeline runs working
         calkit.dvc.ensure_dvc_lock_not_ignored(wdir)

{calkit_python-0.41.14 → calkit_python-0.41.15}/calkit/tests/test_core.py

@@ -43,6 +43,21 @@ def test_detect_project_name(tmp_dir):
     assert calkit.detect_project_name() == "someone-else/some-project"
 
 
+def test_save_calkit_info_preserves_unicode(tmp_dir):
+    # Regression: on Windows, opening calkit.yaml without encoding="utf-8"
+    # writes as cp1252, which either errors or corrupts non-ASCII content
+    # (e.g., the Greek letter "ν") into mojibake ("ν"). ruamel dumps raw
+    # unicode (allow_unicode=True), so the encoding of the file handle matters.
+    info = {"name": "p", "owner": "o", "title": "viscosity ν"}
+    calkit.save_calkit_info(info)
+    # The value must survive the round-trip intact.
+    assert calkit.load_calkit_info()["title"] == "viscosity ν"
+    # Raw bytes must be the UTF-8 encoding of "ν", not cp1252 mojibake.
+    raw = open("calkit.yaml", "rb").read()
+    assert "ν".encode("utf-8") in raw
+    assert "ν".encode("utf-8") not in raw
+
+
 def test_load_calkit_info(tmp_dir, monkeypatch):
     subpath = "some/project"
     os.makedirs(subpath)

{calkit_python-0.41.14 → calkit_python-0.41.15}/calkit/tests/test_julia.py

@@ -1,16 +1,40 @@
 """Tests for ``calkit.julia``"""
 
+import os
 from unittest import mock
 
 import pytest
 
 from calkit.julia import (
+    _is_julia_command,
     check_version_in_command,
     ensure_startup_file_disabled_in_command,
+    escape_string,
     get_julia_exe,
+    load_path,
 )
 
 
+def test_escape_string_windows_path():
+    # A Windows path embedded in a Julia string literal must have its
+    # backslashes escaped, otherwise "C:\\Users" is read as an invalid \\U
+    # unicode escape (ParseError).
+    assert escape_string("C:\\Users\\peteb") == "C:\\\\Users\\\\peteb"
+    # Double quotes and dollar signs are the other special characters.
+    assert escape_string('a"b') == 'a\\"b'
+    assert escape_string("a$b") == "a\\$b"
+    # Plain values (e.g. the load path) are unchanged.
+    assert escape_string("@;@stdlib") == "@;@stdlib"
+
+
+def test_load_path_uses_platform_separator():
+    # Julia splits JULIA_LOAD_PATH on the platform path separator, so the
+    # value must use ';' on Windows and ':' elsewhere (== os.pathsep).
+    assert load_path() == f"@{os.pathsep}@stdlib"
+    assert "@" in load_path()
+    assert "@stdlib" in load_path()
+
+
 def test_get_julia_exe(monkeypatch, tmp_path):
     # Prefer julia on the PATH when present
     def which_julia(name):
@@ -44,6 +68,28 @@ def test_get_julia_exe(monkeypatch, tmp_path):
     assert get_julia_exe() == "julia"
 
 
+def test_is_julia_command_case_insensitive():
+    # Windows resolves the execution-alias shim to an uppercase extension
+    # (e.g. ``julia.EXE``); the check must still recognize it.
+    assert _is_julia_command("C:/x/julia.EXE")
+    assert _is_julia_command("C:/x/Julia.Exe")
+    assert _is_julia_command("C:/x/julialauncher.EXE")
+    assert _is_julia_command("/usr/bin/julia")
+    assert _is_julia_command("julialauncher")
+    assert not _is_julia_command("python")
+    assert not _is_julia_command("C:/x/python.exe")
+
+
+def test_disable_startup_file_accepts_uppercase_exe():
+    # Regression: julia.EXE (Windows execution alias) was rejected as not a
+    # Julia command, failing the env check and masking real pipeline status.
+    cmd = ensure_startup_file_disabled_in_command(
+        ["C:/x/julia.EXE", "--version"]
+    )
+    assert cmd[0] == "C:/x/julia.EXE"
+    assert "--startup-file=no" in cmd
+
+
 def test_check_version_in_command():
     cmd = ["julia", "+1.11", "--project", "whatever"]
     # Case 1: juliaup is available

{calkit_python-0.41.14 → calkit_python-0.41.15}/calkit/tests/test_pipeline.py

@@ -521,6 +521,55 @@ def test_to_dvc_unignores_dvc_lock(tmp_dir):
     assert not repo.ignored("dvc.lock")
 
 
+def test_to_dvc_skips_no_op_writes(tmp_dir):
+    # Compiling to DVC happens on every `calkit status` (which the VS Code
+    # extension polls continuously). Rewriting an unchanged dvc.yaml churns Git
+    # across platforms (trivial reformatting) and wakes the extension's dvc.yaml
+    # watcher into another status poll, an endless loop that keeps re-taking
+    # DVC's lock. The write must be skipped unless the parsed content changes.
+    subprocess.check_call(["calkit", "init"])
+    ck_info = {
+        "pipeline": {
+            "stages": {
+                "s1": {
+                    "kind": "command",
+                    "environment": "_system",
+                    "command": "echo a > a.txt",
+                    "outputs": ["a.txt"],
+                }
+            }
+        },
+    }
+    with open("calkit.yaml", "w") as f:
+        calkit.ryaml.dump(ck_info, f)
+    # First compile creates dvc.yaml.
+    calkit.pipeline.to_dvc(ck_info=ck_info, write=True)
+    assert os.path.isfile("dvc.yaml")
+    # Pin an old mtime; a no-op recompile of identical content must leave it.
+    pinned = 1000000000.0
+    os.utime("dvc.yaml", (pinned, pinned))
+    calkit.pipeline.to_dvc(ck_info=ck_info, write=True)
+    assert os.path.getmtime("dvc.yaml") == pinned
+    # A semantically-equal but reformatted/commented file is also left as-is, so
+    # trivial cross-platform reformatting doesn't churn the file in Git.
+    with open("dvc.yaml") as f:
+        original = f.read()
+    with open("dvc.yaml", "w") as f:
+        f.write("# hand-written comment\n" + original)
+    with open("dvc.yaml") as f:
+        reformatted = f.read()
+    os.utime("dvc.yaml", (pinned, pinned))
+    calkit.pipeline.to_dvc(ck_info=ck_info, write=True)
+    with open("dvc.yaml") as f:
+        assert f.read() == reformatted
+    assert os.path.getmtime("dvc.yaml") == pinned
+    # A real change, though, is written.
+    ck_info["pipeline"]["stages"]["s1"]["command"] = "echo b > a.txt"
+    calkit.pipeline.to_dvc(ck_info=ck_info, write=True)
+    with open("dvc.yaml") as f:
+        assert f.read() != reformatted
+
+
 def test_sbatch_stage_to_dvc(tmp_dir):
     """Cover the SLURM stage compilation paths.
 

calkit_python-0.41.15/vscode-ext/README.md

@@ -0,0 +1,148 @@
+# Calkit for VS Code
+
+Turn a research or analytical project into a navigable, reproducible
+system.
+
+Most projects where the output artifacts (figures, datasets, results,
+papers, presentations) are what matter accumulate a tangle of scripts,
+notebooks, environments, and data. Calkit gives that tangle a structure: every
+artifact is traceable to the pipeline stage that produced it, every stage to its
+code and environment. This extension is the integration layer on top—it
+surfaces the whole system in one place, lets you traverse between layers
+(artifact → stage → environment → source), and lets you make changes at any
+layer and re-run to keep everything in sync.
+
+## The Calkit sidebar: a holistic view of the project
+
+The **Calkit** activity-bar view presents the project as connected sections:
+
+- **Questions**: The research questions the project sets out to answer.
+- **Environments**: Every computational environment (uv, Pixi, venv, conda,
+  renv, Docker, Julia, MATLAB, SSH, SLURM/PBS, and nested combinations).
+- **Pipeline**: The stages that produce the project's artifacts, each showing
+  live status (up to date, **stale**, or running).
+- **Notebooks**: Jupyter notebooks and the environments/stages they belong to.
+- **Figures**, **Datasets**, **Results**, **Publications**, and
+  **Presentations**: The output artifacts, each annotated with the stage (or
+  import source) it came from.
+
+Items are cross-linked, so you can traverse the system in any direction:
+expand a figure to jump to the stage that made it, jump from a stage to its
+environment, open the stage's script/notebook, or open an output file—then run
+the stage again. A badge and per-section warnings flag anything that needs
+attention (stale outputs, artifacts with no defined source, notebooks with no
+environment).
+
+Use the toolbar to filter the tree across all sections, refresh status,
+hide/show sections, open `calkit.yaml`, or initialize a new Calkit
+project in a plain folder.
+
+## Provenance & traceability
+
+- **Show Source**: From an open figure, PDF, dataset, or other pipeline output,
+  jump straight to the producing stage in the sidebar (and into its source).
+- **Figure source links**: In Quarto (`.qmd`) and LaTeX (`.tex`) documents, a
+  "Source: \<stage\>" CodeLens appears above each `![](…)` / `\includegraphics{…}`
+  that references a pipeline output; right-click also offers **Go to Figure
+  Source**. (From a compiled PDF, LaTeX Workshop's reverse-SyncTeX takes you to
+  the `\includegraphics` line, where these actions take over.)
+- **Stale-output awareness**: Outputs whose stage needs re-running are flagged
+  in the sidebar and in the file explorer.
+- **File history**: View a tracked file's history from the sidebar or explorer.
+- **Scheduler logs**: Stages that run under SLURM/PBS surface their log file in
+  the tree so you can open it with a click.
+
+## Pipeline
+
+- Run the whole pipeline, an individual stage, or the stage for the file
+  you're editing.
+- Define new stages graphically, including turning a notebook, script, or an
+  existing artifact into a reproducible stage; edit existing stages.
+- Visualize the pipeline DAG.
+- Open the rendered PDF of a LaTeX/Quarto stage from its source.
+
+## Environments
+
+- Create and edit environments graphically (package lists, spec files, base
+  images, etc.) for uv, Pixi, venv, conda, renv, Docker, Julia, MATLAB, SSH, and
+  SLURM/PBS.
+- Select a notebook's environment and let the extension register/select the
+  matching Jupyter kernel—or edit that environment right from the notebook
+  toolbar.
+- Use nested environments like `slurm:main` for notebook jobs that need to,
+  e.g., to reserve GPUs on a cluster.
+- Start, stop, and restart notebook server sessions for SLURM- and
+  Docker-backed workflows from the notebook toolbar.
+
+## Figures & artifacts
+
+- Browse figures in a gallery and carousel, including interactive Plotly
+  figures (`.json`), with per-figure provenance and a one-click jump to the
+  producing stage.
+- Preview Plotly JSON files in a dedicated **Plotly Preview** editor.
+- Open a notebook's executed HTML output.
+
+## Getting started
+
+1. Open a project folder. If it isn't a Calkit project yet, the sidebar offers
+   **Initialize Calkit Project**.
+2. Explore the Calkit sidebar to see environments, the pipeline, and
+   artifacts.
+3. From a notebook, run **Calkit: Select Notebook Environment**, pick or create
+   an environment (providing SLURM options like `--gpus`/`--time` if needed), and
+   the extension registers/selects the kernel and connects the session.
+
+## Requirements
+
+- VS Code with the Jupyter extension installed.
+- The Calkit CLI available on your `PATH`. If it's missing or too old, the
+  extension prompts with install/upgrade options.
+
+## How environments are stored in `calkit.yaml`
+
+Selecting an environment for a notebook writes it to `calkit.yaml`, updating
+either `notebooks` or `pipeline.stages` depending on whether the notebook is part
+of a pipeline stage.
+
+```yaml
+# Standalone notebook
+notebooks:
+  - path: my-notebook.ipynb
+    environment: my-env
+
+# Notebook that is a pipeline stage
+pipeline:
+  stages:
+    my-notebook:
+      kind: jupyter-notebook
+      notebook_path: my-notebook.ipynb
+      environment: my-env
+```
+
+## Settings
+
+- `calkit.autoRefreshStatus`: Automatically run `calkit status` to refresh
+  pipeline staleness when project files change (disable if frequent status
+  checks interfere with Git operations; you can still refresh manually).
+- `calkit.notebook.defaultJupyterPort`: Default port for Calkit-backed Jupyter
+  servers.
+- `calkit.sidebar.hiddenSections`: Sidebar sections to hide (managed via the
+  sidebar's **Manage Sections** action).
+
+## Commands
+
+Most actions are available from the sidebar, notebook toolbar, and editor
+context menus. Highlights, all under the **Calkit** category in the command
+palette:
+
+- Project: **Initialize Calkit Project**, **Open calkit.yaml**, **Save**,
+  **Refresh**, **Filter** / **Clear Filter**, **Manage Sections**
+- Pipeline: **Run Pipeline**, **Run Stage**, **New Stage**, **Edit Stage**,
+  **Show Pipeline DAG**, **Open Rendered PDF**, **Show Source**, **Go to Figure
+  Source**
+- Environments: **Create Environment**, **Edit Environment**, **Select Notebook
+  Environment**, **Edit Notebook Environment**
+- Notebook sessions: **Start Jupyter SLURM Job**, **Stop Jupyter SLURM Job**,
+  **Restart Notebook Server**, **Open Executed HTML**
+- Figures: **Browse Figures**, **Open Plotly Preview**
+- Artifacts: **Define Pipeline Stage**, **Define Import**, **View File History**