Skip to content

Move runtime env configuration into .projio/config.yml

Problem

Projects currently configure conda environments via ad-hoc mechanisms: - workflow/runtime.env (pixecog) — shell vars like PYTHON, PYTHON_DOCS, CONDA_ENV - .projio/projio.mk — hardcoded env paths (labpy for MKDOCS, etc.) that get stale - MCP tools parse Makefile vars (_resolve_project_python(), _resolve_docs_python()) — fragile, indirect

This creates drift: runtime.env says docs use rag, projio.mk hardcodes labpy for MKDOCS, MCP tools resolve yet another path.

Proposed design

Add code.envs section to .projio/config.yml:

code:
  project_utils: code/utils
  conda_prefix: /storage/share/python/environments/Anaconda3
  envs:
    default: cogpy        # pipelines, notebooks, snakemake
    docs: rag             # mkdocs site builds
    rag: rag              # RAG index builds

What changes

  1. projio config schema — add code.envs and code.conda_prefix fields
  2. projio.mk generation — read envs from config instead of hardcoding. MKDOCS, PYTHON, DATALAD etc. derived from conda_prefix + envs.{purpose}
  3. MCP tools — _resolve_project_python() and _resolve_docs_python() read from config, not Makefile parsing
  4. pipeio_nb_exec — env parameter becomes optional; defaults to code.envs.default from config
  5. site_build — uses code.envs.docs from config
  6. projio sync — validates that configured envs exist, warns if stale

Migration for pixecog

  1. Add code.envs to .projio/config.yml
  2. Delete workflow/runtime.env
  3. Delete workflow/config.yml, workflow/Snakefile, workflow/mod_registry.yml, workflow/pipe_flow_mod_registry.yml (all stale, replaced by pipeio)
  4. Keep workflow/docs.mk until targets absorbed by projio.mk
  5. Update Makefile to remove include workflow/runtime.env

Key constraint

projio.mk must be fully derivable from .projio/config.yml — no project-specific hardcoded paths in the generated file.

Source context: pixecog

PixEcog (pixecog): Neuropixels and ECoG dataset and analysis

Recent commits: 

9b2f6fa Scaffold ecephys TTL removal mod, flow overview + mod docs, demo notebook
80194af Add TTL characterization & removal demo notebook (preprocess_ieeg)
dc93496 Update mkdocs pipeline nav

README:

type: readme

Quick Start for Collaborators

Follow this checklist to get started with Pixecog documentation and workflows.

🐀 Pixecog Project — Compact Overview

Core principles

  • One immutable BIDS raw dataset (raw/) as the canonical baseline
  • Each analysis pipeline ha