### Get Agent Onboarding Guide

Source: https://github.com/random-walks/jellycell/blob/main/docs/getting-started.md

Print the canonical agent guide to standard output or write it to AGENTS.md and CLAUDE.md files for AI assistant integration.

```bash
jellycell prompt                    # print to stdout (pipe into any agent's context)
```

```bash
jellycell prompt --write            # drop AGENTS.md + CLAUDE.md at the repo root
```

--------------------------------

### Install and Run Jellycell with Pip

Source: https://github.com/random-walks/jellycell/blob/main/examples/paper/README.md

Installs Jellycell with server and examples extras using pip, then runs the analysis notebook and exports the tearsheet.

```bash
pip install 'jellycell[server,examples]'
```

```bash
jellycell run notebooks/analysis.py -m "first pass"
```

```bash
jellycell export tearsheet notebooks/analysis.py
```

```bash
jellycell render
```

```bash
jellycell view
```

--------------------------------

### Install jellycell

Source: https://github.com/random-walks/jellycell/blob/main/docs/index.md

Install the core CLI or the full package including the server for live viewing.

```bash
pip install jellycell            # CLI only
pip install 'jellycell[server]'  # with `jellycell view`
```

--------------------------------

### Install jellycell

Source: https://context7.com/random-walks/jellycell/llms.txt

Install the CLI tool or the version including the live viewer.

```bash
pip install jellycell            # CLI only
pip install 'jellycell[server]'  # adds the live viewer
```

--------------------------------

### Install jellycell

Source: https://github.com/random-walks/jellycell/blob/main/README.md

Install the CLI tool or the version with the live viewer server.

```bash
pip install jellycell            # CLI only (no live viewer)
pip install 'jellycell[server]'  # with `jellycell view`
```

--------------------------------

### Initialize Development Environment

Source: https://github.com/random-walks/jellycell/blob/main/docs/development/dev-setup.md

Clone the repository and install all dependencies and pre-commit hooks.

```bash
git clone https://github.com/random-walks/jellycell
cd jellycell
make dev
```

--------------------------------

### Emit Agent Guide with jellycell prompt

Source: https://github.com/random-walks/jellycell/blob/main/docs/cli-reference.md

Emit the canonical agent guide to stdout or install it as `AGENTS.md` and `CLAUDE.md` using the `--write` flag. Options include specifying a target directory, writing only agent files, and forcing overwrites.

```bash
jellycell prompt | pbcopy                    # stdout — pipe into your agent
```

```bash
jellycell prompt --write                     # drop AGENTS.md + CLAUDE.md in cwd
```

```bash
jellycell prompt --write /path/to/repo-root  # target a specific directory
```

```bash
jellycell prompt --write --agents-only       # skip the CLAUDE.md stub
```

```bash
jellycell prompt --write --force             # overwrite existing files
```

--------------------------------

### Bootstrap and Run Experiment

Source: https://github.com/random-walks/jellycell/blob/main/examples/ml-experiment/README.md

Commands to install dependencies and execute the training run using either uv or pip.

```bash
# uv (preferred — installs numpy/matplotlib via [examples])
uv sync
cd examples/ml-experiment
uv run jellycell run notebooks/train.py -m "baseline, LR=0.02 EPOCHS=40"
uv run jellycell export tearsheet notebooks/train.py
uv run jellycell view                                # needs [server]

# pip
pip install 'jellycell[server,examples]'
jellycell run notebooks/train.py -m "baseline, LR=0.02 EPOCHS=40"
jellycell export tearsheet notebooks/train.py
jellycell view
```

--------------------------------

### Clone and Set Up Local Environment

Source: https://github.com/random-walks/jellycell/blob/main/CONTRIBUTING.md

Clone the repository, navigate to the directory, and run 'make dev' for environment setup and 'make test' to run the test suite.

```bash
git clone https://github.com/random-walks/jellycell
cd jellycell
make dev       # uv sync + pre-commit install
make test      # pytest
```

--------------------------------

### Install and Run Jellycell with UV

Source: https://github.com/random-walks/jellycell/blob/main/examples/paper/README.md

Installs Jellycell and its dependencies using uv, then runs the analysis notebook and exports the tearsheet.

```bash
uv sync
```

```bash
cd examples/paper
```

```bash
uv run jellycell run notebooks/analysis.py -m "first pass"
```

```bash
uv run jellycell export tearsheet notebooks/analysis.py
```

```bash
uv run jellycell render
```

```bash
uv run jellycell view
```

--------------------------------

### Bootstrap Jellycell with uv

Source: https://github.com/random-walks/jellycell/blob/main/examples/large-data/README.md

Installs necessary packages using uv and runs jellycell commands for development and export. Ensure you are in the example directory.

```bash
uv sync
cd examples/large-data
uv run jellycell run notebooks/large_data.py -m "first pass"
uv run jellycell export tearsheet notebooks/large_data.py
uv run jellycell view                                # needs [server]
```

--------------------------------

### Bootstrap Jellycell with pip

Source: https://github.com/random-walks/jellycell/blob/main/examples/large-data/README.md

Installs jellycell with server and example dependencies using pip and runs jellycell commands for development and export.

```bash
pip install 'jellycell[server,examples]'
jellycell run notebooks/large_data.py -m "first pass"
jellycell export tearsheet notebooks/large_data.py
jellycell view
```

--------------------------------

### Start Live-Reloading Docs Server

Source: https://github.com/random-walks/jellycell/blob/main/docs/development/preview.md

Run this command to start the Sphinx development server. It serves documentation and auto-rebuilds on changes in `docs/` or `src/jellycell/`. Useful for prose and docstring authoring.

```bash
make docs
```

--------------------------------

### Install Jellycell

Source: https://github.com/random-walks/jellycell/blob/main/docs/getting-started.md

Install jellycell with the server component for the live viewer, or without it for CLI-only usage. Requires Python 3.11 or newer.

```bash
pip install 'jellycell[server]'
```

```bash
pip install jellycell
```

```bash
uv tool install 'jellycell[server]'
```

--------------------------------

### Serve Jellycell Project Live

Source: https://github.com/random-walks/jellycell/blob/main/docs/getting-started.md

Start a live development server that watches for changes and reloads the page automatically. Opens at http://127.0.0.1:5179/.

```bash
jellycell view
```

--------------------------------

### Jellycell init JSON output example

Source: https://github.com/random-walks/jellycell/blob/main/docs/cli-reference.md

Example structure of the JSON output when initializing a Jellycell project. Includes schema version, path, name, and created files.

```json
{"schema_version": 1, "path": "/abs/path", "name": "my-project", "created": ["jellycell.toml", "notebooks/", ...]}
```

--------------------------------

### Conventional Commit Examples

Source: https://github.com/random-walks/jellycell/blob/main/CONTRIBUTING.md

Examples demonstrating the conventional commit message format for various types of changes.

```git
feat(cache): add cache rebuild-index CLI command
fix(format): handle PEP-723 block with trailing whitespace
docs: clarify agent guide stability contract
refactor(run): extract Kernel context manager
test(lint): cover pep723-position edge cases
```

--------------------------------

### Bootstrap Jellycell Environment

Source: https://github.com/random-walks/jellycell/blob/main/examples/demo/README.md

Commands to install dependencies and execute notebook runs using either uv or pip.

```bash
# uv (preferred)
uv sync                                   # from repo root — no extras needed
cd examples/demo
uv run jellycell run notebooks/tour.py -m "first pass"
uv run jellycell export tearsheet notebooks/tour.py
uv run jellycell view                     # needs [server] extra

# pip
pip install 'jellycell[server]'
jellycell run notebooks/tour.py -m "first pass"
jellycell export tearsheet notebooks/tour.py
jellycell view
```

--------------------------------

### Regenerate Agent Guide Snapshots

Source: https://github.com/random-walks/jellycell/blob/main/docs/reference/contracts.md

Use this command to update the agent guide test snapshots after modifying the documentation content.

```bash
uv run pytest tests/unit/test_prompt_snapshot.py --force-regen
```

--------------------------------

### Load Simulated Project Inputs with Jellycell

Source: https://github.com/random-walks/jellycell/blob/main/examples/demo/site/tour.html

Simulate reading project inputs using `jc.load`. This example constructs a literal dictionary instead of reading from a file.

```python
raw = {"users": USERS, "sessions": SESSIONS, "conversions": CONVERSIONS}
print(f"loaded {len(raw)} metrics")
```

--------------------------------

### Bootstrap Jellycell Project

Source: https://github.com/random-walks/jellycell/blob/main/examples/minimal/README.md

Use uv sync for dependency management or pip with a virtual environment to install and run the minimal Jellycell project. Ensure you are in the repository root for uv sync.

```bash
uv sync                                                   # run from repo root
cd examples/minimal
uv run jellycell run notebooks/hello.py
```

```bash
python -m venv .venv && source .venv/bin/activate
pip install jellycell                                     # CLI only
jellycell run notebooks/hello.py
```

--------------------------------

### Notebook file format

Source: https://github.com/random-walks/jellycell/blob/main/docs/agent-guide.md

Example of a .py notebook file using jupytext percent format and PEP-723 dependency blocks.

```python
# /// script
# requires-python = ">=3.11"
# dependencies = ["pandas"]
# ///

# %% [markdown]
# # Analysis title

# %% tags=["jc.load", "name=raw"]
import pandas as pd
df = pd.read_csv("data/input.csv")

# %% tags=["jc.step", "name=summary", "deps=raw"]
summary = df.describe()
```

--------------------------------

### Regenerating Agent Guide Content Tests

Source: https://github.com/random-walks/jellycell/blob/main/docs/development/releasing.md

If the agent guide content has changed, regenerate the prompt snapshot tests. This ensures the snapshot reflects the updated content.

```bash
pytest tests/unit/test_prompt_snapshot.py --force-regen
```

--------------------------------

### Define a jellycell Notebook

Source: https://context7.com/random-walks/jellycell/llms.txt

Example of a .py notebook using PEP-723 headers and jupytext cell markers.

```python
# /// script
# requires-python = ">=3.11"
# dependencies = ["pandas", "matplotlib"]
#
# [tool.jellycell]
# timeout_seconds = 1800
# ///

# %% [markdown]
# # Tour
# One-paragraph description of what this notebook does.

# %% tags=["jc.load", "name=raw"]
import pandas as pd
raw = pd.read_csv("data/sales.csv")

# %% tags=["jc.step", "name=summary", "deps=raw"]
import jellycell.api as jc
summary = raw.describe()
jc.save(summary, "artifacts/summary.json")
jc.table(summary, caption="Sales summary")
```

--------------------------------

### Write a Jellycell Notebook

Source: https://github.com/random-walks/jellycell/blob/main/docs/getting-started.md

Example of a jellycell notebook with metadata, markdown cells, and Python code cells. It loads data, performs a calculation, and saves the result.

```python
# /// script
# requires-python = ">=3.11"
# dependencies = []
# ///

# %% [markdown]
# # Hello jellycell

# %% tags=["jc.load", "name=raw"]
raw = {"a": 1, "b": 2, "c": 3}

# %% tags=["jc.step", "name=total", "deps=raw"]
import jellycell.api as jc

total = sum(raw.values())
jc.save({"raw": raw, "total": total}, "artifacts/summary.json")
print(f"total = {total}")
```

--------------------------------

### Jellycell Notebook Example with Cell Tags

Source: https://github.com/random-walks/jellycell/blob/main/docs/spec/v0.md

Demonstrates how to use Jellycell cell tags (`jc.load`, `jc.step`, `jc.figure`, `jc.table`) to define data loading, processing, and artifact generation steps within a notebook. Dependencies between cells are specified using the `deps=` attribute.

```python
# /// script
# requires-python = ">=3.11"
# dependencies = ["pandas", "matplotlib"]
# ///

# %% [markdown]
# # Mortality trend analysis

# %% tags=["jc.load", "name=raw"]
import pandas as pd
df = pd.read_csv("data/who_mortality.csv")

# %% tags=["jc.step", "name=summary", "deps=raw"]
summary = df.groupby("country")["deaths"].sum().sort_values()
jc.save(summary, "artifacts/summary.parquet")
jc.table(summary.head(20), caption="Top 20 countries")

# %% tags=["jc.figure", "deps=summary"]
import matplotlib.pyplot as plt
summary.tail(20).plot.barh()
jc.figure(caption="Top 20 by deaths")  # path auto-chosen

```

--------------------------------

### Reporting Bugs: Get jellycell Version

Source: https://github.com/random-walks/jellycell/blob/main/CONTRIBUTING.md

Command to retrieve the installed jellycell version for bug reporting.

```bash
jellycell --version or python -m jellycell --version
```

--------------------------------

### Initialize and Run Projects

Source: https://context7.com/random-walks/jellycell/llms.txt

Commands for initializing a project, scaffolding notebooks, and executing or viewing them.

```bash
jellycell init my-project
cd my-project

# (once per repo) drop AGENTS.md + CLAUDE.md so agentic tools read jellycell's guide
jellycell prompt --write

jellycell new tour                  # scaffold notebooks/tour.py
# edit in your editor of choice
jellycell run notebooks/tour.py     # first run executes; cached afterward
jellycell render notebooks/tour.py  # writes site/tour.html
jellycell view                      # live viewer (needs [server] extra)
```

--------------------------------

### Initialize and Run jellycell Projects

Source: https://github.com/random-walks/jellycell/blob/main/README.md

Commands for initializing a project, scaffolding notebooks, and executing or serving them.

```bash
jellycell init my-project
cd my-project

# (Once per repo) drop AGENTS.md + CLAUDE.md so Cursor / Codex / Copilot / Claude Code read jellycell's agent guide
jellycell prompt --write

# Scaffold a notebook
jellycell new tour
# edit notebooks/tour.py in your editor of choice

# Run it — first time executes, subsequent runs hit the cache
jellycell run notebooks/tour.py

# Build static HTML reports
jellycell render notebooks/tour.py

# Or serve the live viewer with reload on save (requires [server] extra)
jellycell view
```

--------------------------------

### Bootstrap and Run Jellycell Pipeline

Source: https://github.com/random-walks/jellycell/blob/main/examples/timeseries/README.md

Commands to set up the environment and execute the timeseries pipeline using either uv or pip.

```bash
# uv (preferred — installs numpy/pandas/matplotlib/pyarrow via [examples])
uv sync
cd examples/timeseries
uv run jellycell run notebooks/01-explore.py -m "first pass: synthetic daily series"
uv run jellycell run notebooks/02-decompose.py -m "additive decomposition"
uv run jellycell run notebooks/03-forecast.py -m "SES forecast + diagnostics"
uv run jellycell render
uv run jellycell view                                # needs [server]

# pip
pip install 'jellycell[server,examples]'
for nb in notebooks/*.py; do jellycell run "$nb" -m "first pass"; done
jellycell render
jellycell view
```

--------------------------------

### Create a Jellycell Project

Source: https://github.com/random-walks/jellycell/blob/main/docs/getting-started.md

Initialize a new jellycell project named 'my-analysis' and navigate into its directory. This scaffolds the basic project structure.

```bash
jellycell init my-analysis
cd my-analysis
```

--------------------------------

### Initialize a new Jellycell project

Source: https://github.com/random-walks/jellycell/blob/main/docs/cli-reference.md

Scaffold a new Jellycell project in the specified directory. Use --name to set a custom project name.

```bash
jellycell init my-analysis --name my-analysis
```

--------------------------------

### Execute development commands

Source: https://github.com/random-walks/jellycell/blob/main/CLAUDE.md

Standard make commands for development, testing, and documentation.

```makefile
make dev              # uv sync + pre-commit install
make test             # full pytest suite
make test-unit        # unit tests only (fast)
make lint             # ruff + mypy
make docs             # sphinx-autobuild, live at :8001
make docs-build       # sphinx-build -W (CI mirror)
make preview          # points to an example project for live viewer preview
make release-check    # dry-run build + version print
```

--------------------------------

### Jellycell Repository Layout

Source: https://github.com/random-walks/jellycell/blob/main/docs/spec/v0.md

Provides an overview of the Jellycell project's directory structure, outlining the organization of source code, documentation, examples, and tests.

```default
jellycell/
├── .github/workflows/
│   ├── ci.yml
│   └── release.yml
├── docs/
│   ├── index.md
│   ├── getting-started.md
│   ├── file-format.md
│   ├── project-layout.md
│   ├── cli-reference.md
│   ├── agent-guide.md
│   └── spec/v0.md
├── examples/
│   ├── minimal/
│   ├── paper/
│   └── ml-experiment/
├── src/
│   └── jellycell/
│       ├── __init__.py
│       ├── __main__.py
│       ├── _version.py
│       ├── api.py
│       ├── config.py
│       ├── paths.py
│       ├── format/
│       ├── cache/
│       ├── run/
│       ├── render/
│       ├── export/
│       ├── lint/
│       ├── server/
│       └── cli/
├── tests/
│   ├── unit/
│   ├── integration/
│   └── fixtures/
├── pyproject.toml
├── README.md
├── CHANGELOG.md
├── LICENSE
└── jellycell.toml.example
```

--------------------------------

### Scaffold New Notebook with jellycell new

Source: https://github.com/random-walks/jellycell/blob/main/docs/cli-reference.md

Scaffold a new notebook file within the `notebooks/` directory. Specify the desired name for the notebook.

```bash
jellycell new analysis        # creates notebooks/analysis.py
```

--------------------------------

### Reproduce pipeline results

Source: https://github.com/random-walks/jellycell/blob/main/examples/timeseries/manuscripts/findings.md

Commands to execute the timeseries analysis notebooks in the jellycell environment.

```bash
cd examples/timeseries
jellycell run notebooks/01-explore.py
jellycell run notebooks/02-decompose.py
jellycell run notebooks/03-forecast.py
```

--------------------------------

### Jellycell View Data Flow

Source: https://github.com/random-walks/jellycell/blob/main/docs/spec/v0.md

Describes the data flow for the 'jellycell view' command, detailing server setup, file watching, and client interaction for live updates.

```default
1. cli.view.callback() → requires [server] extra
2. server.app.build(project) → Starlette app
3. watchfiles.watch(project.watched_paths) in a task
   on change → render.rerender(path) + sse.push(ReloadEvent)
4. uvicorn.run(app, host, port)
Client opens /:
  index.html listing notebooks + recent artifacts
Client opens /nb/analysis:
  connects to /events (SSE)
  on reload event → fetch /nb/analysis fragment, swap
```

--------------------------------

### Create Project Checkpoints with jellycell checkpoint create

Source: https://github.com/random-walks/jellycell/blob/main/docs/cli-reference.md

Create reproducible project snapshots as `.tar.gz` archives. You can provide an auto-timestamped name or specify a custom name and message.

```bash
jellycell checkpoint create                       # auto-timestamped name
```

```bash
jellycell checkpoint create --name v1-draft -m "submitted for review"
```

--------------------------------

### Configure Git LFS for Large Artifacts

Source: https://github.com/random-walks/jellycell/blob/main/examples/large-data/README.md

Installs Git Large File Storage (LFS) and configures it to track large artifact files. This is an alternative to git-ignoring large files.

```bash
git lfs install
git lfs track "artifacts/large_data/*.parquet"
git add .gitattributes
```

--------------------------------

### Define a New CLI Command

Source: https://github.com/random-walks/jellycell/blob/main/docs/development/adding-commands.md

Example of a new CLI command using Typer and Pydantic for structured output. Ensure JSON output is handled separately from human-readable output.

```python
# src/jellycell/cli/commands/mycmd.py
from __future__ import annotations

import json
from pathlib import Path

import typer
from pydantic import BaseModel
from rich.console import Console

from jellycell.cli.app import app
from jellycell.paths import Project

console = Console()


class MyCmdReport(BaseModel):
    """JSON output shape for `jellycell mycmd`. Spec §10.1 schema contract."""

    schema_version: int = 1
    project: str
    result: str


@app.command("mycmd")
def mycmd(
    path: Path = typer.Argument(..., help="Thing to operate on"),
    json_output: bool = typer.Option(False, "--json", help="Emit JSON to stdout"),
) -> None:
    """One-line summary. Shown in `jellycell --help`. """
    project = Project.from_path(Path.cwd())
    # ... do the work ...
    report = MyCmdReport(project=project.root.name, result="ok")

    if json_output:
        typer.echo(report.model_dump_json())
    else:
        console.print(f"[green]ok[/green] {report.result}")

```

--------------------------------

### Jellycell Run Data Flow

Source: https://github.com/random-walks/jellycell/blob/main/docs/spec/v0.md

Illustrates the step-by-step process when executing the 'jellycell run' command, including parsing, dependency resolution, caching, and execution.

```default
1. cli.run.callback(path, --json)
   └─> Project.from_path(cwd) → Project (validated jellycell.toml)
2. format.parse(path) → Notebook (jupytext under the hood)
3. pep723.extract(path) → ScriptMeta (merged into Project)
4. run.Runner(project).run(notebook)
   ├─ ast-walk cells to resolve deps (from tags + jc.deps calls)
   ├─ topological sort → exec order
   ├─ for each cell:
   │   ├─ key = cache.hashing.key(cell, dep_keys, env_hash)
   │   ├─ if cache.store.has(key):
   │   │    load Manifest; restore any missing artifacts from blobs
   │   │    yield CellResult(status="cached")
   │   ├─ else:
   │   │    Kernel.execute(cell.source)
   │   │    → Outputs + artifacts-written-during-run (via jc.* hooks)
   │   │    cache.store.put(key, manifest, blobs)
   │   │    cache.index.insert(manifest)
   │   │    yield CellResult(status="ok"|"error")
   └─ return RunReport
5. --json: print RunReport as JSON; human: rich table
```

--------------------------------

### Bootstrap jellycell environment

Source: https://github.com/random-walks/jellycell/blob/main/examples/README.md

Commands to initialize the environment and run jellycell workflows using either uv or pip.

```bash
# uv — recommended; single `sync` pulls all extras
uv sync
cd examples/<name>
uv run jellycell run notebooks/<script>.py -m "first pass"
uv run jellycell export tearsheet notebooks/<script>.py
uv run jellycell view                                 # needs [server]

# pip — pick the extras you want
pip install 'jellycell[server,examples]'              # matplotlib + pandas + pyarrow
cd examples/<name>
jellycell run notebooks/<script>.py -m "first pass"
jellycell export tearsheet notebooks/<script>.py
jellycell view
```

--------------------------------

### Calculate Derived Metric with Jellycell Cache Invalidation

Source: https://github.com/random-walks/jellycell/blob/main/examples/demo/site/tour.html

Exercise cache invalidation by calculating a derived metric. Changing input parameters in upstream cells (like `CONVERSIONS` in the setup cell) will automatically trigger re-runs only for the affected downstream cells.

```python
headline = f"{raw['conversions']} of {raw['sessions']} sessions converted"
jc.save({"headline": headline}, "artifacts/headline.json")
print(headline)
```

--------------------------------

### Configure PEP-723 metadata with overrides

Source: https://github.com/random-walks/jellycell/blob/main/docs/file-format.md

Demonstrates how to include a PEP-723 block at the top of a file to specify dependencies and file-scope configuration overrides.

```python
# /// script
# requires-python = ">=3.11"
# dependencies = ["pandas", "matplotlib"]
#
# [tool.jellycell]
# timeout_seconds = 1200     # override run.timeout_seconds for this file
# ///
```

--------------------------------

### Creating a Jellycell Checkpoint

Source: https://github.com/random-walks/jellycell/blob/main/docs/agent-guide.md

Bundle the current project state into a `.tar.gz` file using `jellycell checkpoint create -m` for reproducibility or rollback.

```bash
jellycell checkpoint create -m "submitted for review"
```

--------------------------------

### jellycell init

Source: https://github.com/random-walks/jellycell/blob/main/docs/cli-reference.md

Scaffold a new Jellycell project.

```APIDOC
## COMMAND jellycell init

### Description
Scaffold a new jellycell project.

### Parameters
#### Path Parameters
- **path** (string) - Required - The directory path for the new project.

#### Flags
- **--name** (string) - Optional - Project name. Defaults to the target dir name.
- **--force** (boolean) - Optional - Overwrite an existing jellycell.toml.

### Request Example
`jellycell init my-analysis --name my-analysis`

### Response
#### Success Response (200)
- **schema_version** (integer) - The schema version of the output.
- **path** (string) - The absolute path of the project.
- **name** (string) - The project name.
- **created** (array) - List of created files and directories.

#### Response Example
{"schema_version": 1, "path": "/abs/path", "name": "my-project", "created": ["jellycell.toml", "notebooks/", ...]}
```

--------------------------------

### Pre-release Checklist Commands

Source: https://github.com/random-walks/jellycell/blob/main/docs/development/releasing.md

Run these commands to perform checks before cutting a release. This includes linting, testing, building documentation, and a specific release check.

```bash
make lint
make test
make docs-build
make release-check
```

--------------------------------

### Development Loop Commands

Source: https://github.com/random-walks/jellycell/blob/main/CONTRIBUTING.md

Common commands for running tests, linting, formatting, and building documentation during development.

```bash
make test             # full test suite
make test-unit        # fast tests only
make lint             # ruff + mypy
make format           # apply ruff formatting + autofix
make docs             # live-reload docs at :8001
make docs-build       # sphinx-build -W (CI-mirror)
```

--------------------------------

### Execute CLI during Development

Source: https://github.com/random-walks/jellycell/blob/main/docs/development/dev-setup.md

Run the Jellycell CLI using the uv environment.

```bash
uv run jellycell --help
uv run python -m jellycell --version
```

--------------------------------

### Serve Live Catalogue with jellycell view

Source: https://github.com/random-walks/jellycell/blob/main/docs/cli-reference.md

Serve the live catalogue using the `jellycell view` command. You can specify host and port, or disable the response cache by setting `JELLYCELL_VIEW_NOCACHE=1`.

```bash
jellycell view                                # use [viewer] config
```

```bash
jellycell view --host 0.0.0.0 --port 8080
```

```bash
JELLYCELL_VIEW_NOCACHE=1 jellycell view       # disable response cache
```

--------------------------------

### Preview HTML Reports with Live Reload

Source: https://github.com/random-walks/jellycell/blob/main/docs/development/preview.md

Use this command to preview HTML reports generated by Jellycell. It requires the `[server]` extra and live-reloads on file changes. Navigate to the `examples/demo` directory first.

```bash
cd examples/demo
jellycell view    # requires [server] extra; live-reloads on file changes
```

--------------------------------

### List Project Checkpoints with jellycell checkpoint list

Source: https://github.com/random-walks/jellycell/blob/main/docs/cli-reference.md

List available project checkpoints, ordered with the newest first.

```bash
jellycell checkpoint list                         # newest first
```

--------------------------------

### Render Jellycell notebooks to HTML

Source: https://github.com/random-walks/jellycell/blob/main/docs/cli-reference.md

Render notebooks to HTML reports. Can render all notebooks or a single specified notebook. Use --standalone for inline images.

```bash
jellycell render                              # all notebooks + index
```

```bash
jellycell render notebooks/foo.py             # single notebook
```

```bash
jellycell render --standalone                 # inline images (one-file HTML)
```

--------------------------------

### Render Jellycell Project to Static HTML

Source: https://github.com/random-walks/jellycell/blob/main/docs/getting-started.md

Generate static HTML files for the project, including an index page and individual pages for each notebook.

```bash
jellycell render            # writes site/index.html + one page per notebook
```

--------------------------------

### Define Configuration Parameters

Source: https://github.com/random-walks/jellycell/blob/main/examples/demo/manuscripts/tearsheets/tour.md

Sets global constants for the simulation. These variables are surfaced in the tearsheet for quick reference.

```python
USERS = 120
SESSIONS = 450
CONVERSIONS = 38
```

--------------------------------

### Jellycell Project Configuration (`jellycell.toml`)

Source: https://github.com/random-walks/jellycell/blob/main/docs/spec/v0.md

Defines project-level settings for Jellycell, including paths for notebooks, data, and artifacts, as well as run-time configurations like kernel selection and timeouts. Also specifies viewer settings and linting rules.

```toml
[project]
name = "my-project"

[paths]
notebooks = "notebooks"
data = "data"
artifacts = "artifacts"
reports = "reports"
manuscripts = "manuscripts"
cache = ".jellycell/cache"

[run]
kernel = "python3"
subprocess = true
timeout_seconds = 600

[viewer]
host = "127.0.0.1"
port = 5179
watch = ["notebooks", "manuscripts", "artifacts"]

[lint]
enforce_artifact_paths = true
enforce_declared_deps = false
warn_on_large_cell_output = "10MB"

```

--------------------------------

### Run Configuration Section

Source: https://github.com/random-walks/jellycell/blob/main/docs/project-layout.md

Defines execution settings for Jupyter kernels and subprocesses.

```toml
[run]
kernel = "python3"                # Jupyter kernel name
subprocess = true                 # subprocess-only; in-process is unsupported
timeout_seconds = 600             # per-cell default; `timeout=N` tag overrides
```

--------------------------------

### Viewer Configuration Section

Source: https://github.com/random-walks/jellycell/blob/main/docs/project-layout.md

Settings for the Jellycell viewer server.

```toml
[viewer]
host = "127.0.0.1"
port = 5179
watch = ["notebooks", "manuscripts", "artifacts"]     # paths triggering reloads
```

--------------------------------

### Paths Configuration Section

Source: https://github.com/random-walks/jellycell/blob/main/docs/project-layout.md

Configures relative paths for project resources.

```toml
[paths]
notebooks = "notebooks"           # source .py files
data = "data"                     # input data
artifacts = "artifacts"           # output files
site = "site"                     # rendered HTML catalogue
manuscripts = "manuscripts"       # optional prose companions
cache = ".jellycell/cache"        # content-addressed cache
```

--------------------------------

### Use jellycell Helpers in Notebooks

Source: https://github.com/random-walks/jellycell/blob/main/README.md

Use jc.save and jc.load to manage artifacts and track dependencies between cells.

```python
# %% cell-id=tour:1 name=raw
import pandas as pd
df = pd.read_csv("data/sales.csv")
jc.save(df, "artifacts/sales.parquet")

# %% cell-id=tour:2 name=summary deps=raw
df = jc.load("artifacts/sales.parquet")
summary = df.describe()
jc.table(summary)
```

--------------------------------

### Run Jellycell notebook with caching

Source: https://github.com/random-walks/jellycell/blob/main/docs/cli-reference.md

Execute a notebook end-to-end with caching. Use --force to re-execute all cells or -m to add a journal entry message.

```bash
jellycell run notebooks/foo.py
```

```bash
jellycell run notebooks/foo.py --force                    # re-execute all cells
```

```bash
jellycell run notebooks/foo.py -m "fixed sign error"      # journal entry message
```

--------------------------------

### Bootstrap Agent Development Tools

Source: https://github.com/random-walks/jellycell/blob/main/docs/getting-started.md

Generate AGENTS.md and CLAUDE.md files at the repository root to enable automatic integration with AI coding assistants. Use --force to override existing files.

```bash
cd my-repo     # the git root, which may contain multiple jellycell projects
jellycell prompt --write
```

--------------------------------

### Development Workflow Commands

Source: https://github.com/random-walks/jellycell/blob/main/docs/development/dev-setup.md

Commonly used Makefile targets for testing, linting, formatting, and documentation.

```bash
make test            # full pytest suite
make test-unit       # fast unit tests only
make lint            # ruff + mypy
make format          # ruff format + fix lint issues
make docs            # sphinx-autobuild at http://127.0.0.1:8001
```

--------------------------------

### Project directory layout

Source: https://github.com/random-walks/jellycell/blob/main/docs/agent-guide.md

The standard directory structure for a jellycell project.

```default
my-project/
├── jellycell.toml       # project config
├── notebooks/           # .py source notebooks (jupytext percent format)
├── data/                # input data, read by jc.load
├── artifacts/           # writable output files (images, parquet, json, ...)
├── site/             # rendered HTML output
├── manuscripts/         # narrative docs (optional)
└── .jellycell/
    └── cache/           # content-addressed cache (git-ignored)
```