zo init

zo init <project> is the first command in the pipeline. It creates everything ZO needs to track a project, plus a delivery repo scaffold.

Synopsis

zo init PROJECT_NAME [OPTIONS]

What it does

Detects host environment

Calls zo.environment.detect_environment() to capture platform, Python version, GPU/CUDA details, Docker availability. Used to populate the plan’s ## Environment section and pick an appropriate Docker base image.

Resolves delivery repo path

Three modes: explicit --existing-repo PATH (overlay), explicit --scaffold-delivery PATH (new scaffold), or default (../<project>-delivery).

Writes ZO-side artifacts

memory/{project}/{STATE,DECISION_LOG,PRIORS}.md, targets/{project}.target.md, plans/{project}.md.

Writes delivery-side artifacts

.zo/{config.yaml, memory/, plans/} (portable project state), full src/, configs/, experiments/, reports/, notebooks/phase/, tests/, docker/ scaffold.

Picks Docker compose template

Platform-aware: GPU template on Linux+CUDA, CPU template on macOS / no-GPU Linux. The deploy.resources.devices: capabilities: [gpu] block is omitted on CPU to avoid docker compose up failures.

Modes

Conversational (default)
Headless (--no-tmux)
Dry-run (preview)
Reset

zo init my-project

Launches the Init Architect in a tmux pane. The agent:

Greets you with the brand banner
Asks 5–6 confirming questions (project location, delivery repo, base image, GPU host, data path, layout mode)
Inspects the target repo if it already exists (Glob, Read, Bash)
Runs zo init ... --no-tmux --dry-run to preview exactly what will be written
Asks you to approve before committing writes
Routes the actual file writes through zo init ... --no-tmux ... so the CLI is the single source of truth

Use this on first runs of a new project, or when adopting an existing repo where you’re not sure what layout mode to pick.

zo init my-project --no-tmux \
  --branch main \
  --existing-repo /path/to/my-repo \
  --base-image pytorch/pytorch:2.4.0-cpu \
  --gpu-host local \
  --data-path /data/raw \
  --layout-mode adaptive

Writes files directly from flags. No interview, no inspection. Use for CI, scripts, and re-runs.

zo init my-project --no-tmux --dry-run

Prints the exact file tree, target.md content, plan.md Environment section that would be written. No filesystem changes. The Init Architect uses this internally before every commit.

zo init my-project --reset --yes

Deletes memory/{project}/, targets/{project}.target.md, plans/{project}.md. Refuses without --yes unless you type the project name as confirmation. Never touches the delivery repo — that’s user code, not ZO’s to delete.

Layout modes

--layout-mode controls how the scaffold interacts with existing code:

standard (default)
adaptive

Creates the full ZO layout: configs/, src/{data,model,engineering,inference,utils}/, data/{raw,processed}/, experiments/, reports/, notebooks/{,phase}/, tests/{unit,ml,fixtures}/, docker/.Best for: fresh projects, existing repos with no established code layout.

Creates only ZO meta-directories: configs/, experiments/, reports/, notebooks/phase/, docker/. Skips src/ and data/ so an existing repo’s own code layout is left alone.Best for: existing repos with established conventions (src-layout, django-style, monorepo, notebook-first).Requires --existing-repo. The Init Architect customises STRUCTURE.md and agent_working_dirs to point at the actual code paths.

Options

Option	Default	Purpose
`--no-tmux`	(off)	Disable conversational mode. Implies headless flag-driven init.
`--dry-run`	(off)	Preview writes without filesystem changes. Requires `--no-tmux`.
`--reset`	(off)	Delete ZO artifacts for this project. Requires `--yes` or typing the project name.
`--yes`, `-y`	(off)	Skip confirmation prompts. Used with `--reset`.
`--branch`	`main`	Git branch on the delivery repo.
`--existing-repo PATH`	(none)	Apply ZO scaffold as overlay to an existing repo. Requires `.git/`.
`--scaffold-delivery PATH`	(auto)	Create scaffold at this absolute path. Default is `../<project>-delivery`. Mutually exclusive with `--existing-repo`.
`--base-image IMAGE`	(auto)	Docker base image. Auto-detected via `suggest_base_image(env)`.
`--gpu-host HOST`	(auto)	GPU host. `local` if running on the GPU machine, `user@host:/path` for remote.
`--data-path PATH`	(auto)	Path to data. Use `host:/abs/path` for remote-data flows.
`--no-detect`	(off)	Skip host environment auto-detection. Leaves the plan’s `## Environment` as TODO.
`--layout-mode MODE`	`standard`	`standard` or `adaptive`. Adaptive requires `--existing-repo`.

Examples

Fresh project, conversational

zo init mnist-demo

Launches the Init Architect. Default delivery repo at ../mnist-demo-delivery.

Adopt an existing repo, adaptive layout

zo init my-project --existing-repo ~/code/my-project --layout-mode adaptive

Adds only ZO meta-dirs. Init Architect customises STRUCTURE.md to your existing src/ layout.

Headless for CI

zo init my-project --no-tmux \
  --branch feature/ml-pipeline \
  --base-image pytorch/pytorch:2.4.0-cuda12.1-cudnn9-runtime \
  --gpu-host local \
  --data-path /mnt/data

Preview before committing

zo init my-project --no-tmux --dry-run

Prints the file tree, target.md, plan.md Environment block. Re-run without --dry-run to commit.

Start over

zo init my-project --reset --yes

Wipes ZO artifacts. Delivery repo is preserved.

What gets written

After a successful zo init my-project:

zero-operators/                                 # ZO repo
├── memory/my-project/
│   ├── STATE.md
│   ├── DECISION_LOG.md
│   ├── PRIORS.md
│   └── sessions/
├── targets/my-project.target.md
└── plans/my-project.md                         # with ## Environment populated

../my-project-delivery/                         # delivery repo (or --existing-repo)
├── .zo/
│   ├── config.yaml
│   ├── memory/                                 # mirror of ZO-side memory
│   └── plans/my-project.md                     # mirror of ZO-side plan
├── configs/{data,model,training,experiment}/
├── src/{data,model,engineering,inference,utils}/    # standard mode only
├── data/{raw,processed}/                       # standard mode only
├── experiments/
├── notebooks/{,phase}/
├── reports/{,figures}/
├── tests/{unit,ml,fixtures}/
├── docker/{Dockerfile,docker-compose.yml,.dockerignore}
├── README.md, STRUCTURE.md, pyproject.toml, .gitignore

zo draft

Now that the skeleton exists, draft the plan.

The plan

What goes into plans/<project>.md.

Get started

Concepts

CLI reference

Reference

Project

Synopsis

What it does

Modes

Layout modes

Options

Examples

What gets written

Next

zo draft

The plan

​Synopsis

​What it does

​Modes

​Layout modes

​Options

​Examples

​What gets written

​Next

zo draft

The plan

Synopsis

What it does

Modes

Layout modes

Options

Examples

What gets written

Next