Troubleshooting¶

This page lists common issues when running the notebooks and docs.

Zensical Command Not Found¶

Install project dependencies with the dev group:

uv sync --all-groups --all-extras

Then run Zensical through uv:

uv run zensical serve

Broken Docs Build¶

Run the strict build:

uv run zensical build --strict

Fix any reported broken links or invalid anchors in docs/.

Missing Graphviz or Video Tools¶

If diagram or video rendering fails, install system packages:

sudo apt-get update
sudo apt-get install -y graphviz ffmpeg

Shielded Experiment Fails Before Training Starts¶

Learned shielded runs need world-model and opponent-model artifacts.

Run the matching notebooks in order:

uv run python notebooks/matrix/chicken/train_wm_mo.py
uv run python notebooks/matrix/chicken/train_om_mo.py
uv run python notebooks/matrix/chicken/experiments_mo.py --run-ippo-shielded=true

Plain IPPO, IPPO Lagrangian, and ICPO runs should still work without those shield artifacts.

Graph State Width Mismatch¶

A cached graph may have been built with an older environment encoding.

Remove the stale export directory for the affected environment and rebuild the world-model artifacts.

Missing Coverage in Shield Telemetry¶

Missing coverage means the shield could not find a covered state, action, or successor case in the induced graph.

The shield treats this conservatively, so frequent missing coverage usually points to a stale graph, an incompatible opponent-model artifact, or training data whose state encoding does not match the graph.

Notebook Paths Resolve Under the Wrong Directory¶

Current marimo notebooks normalize their working directory to the project root during setup.

If a custom script still writes under notebooks/.../exports, launch it from the repo root or update it to use the shared project-root helper.