Quickstart

One loop covers everything ziv does day to day: create a project, open a workspace with an agent, work, validate and build the package, then wrap up and archive.

1. Create a project

ziv project new my-proofs

This creates a git repository, registers it as a project, scaffolds a zpi package, and makes the seed commit. To adopt an existing repo instead: ziv project add <repoPath>.

2. Open a workspace

ziv workspace new --name prove-maynard --agent prover --goal "Prove the Twin Prime Bound entry"

A workspace is an isolated git worktree with its own conversation history, owned by one agent. The registered agents are prover (drafts and verifies proofs), paper-to-package (transcribes a mathematical paper faithfully into zpi), and zpi-agent (the general package operator). workspace new drops you straight into the session — add --no-open to create without entering.

3. Work

Inside the session:

• /login <provider> to authenticate (e.g. /login anthropic), /model to pick a model.
• Work with the agent. It reads and edits the package through the KB tools, and validates with ziv check / ziv build itself.
• /wrap-up closes out the session in an orderly way (it is guarded — the agent finishes its bookkeeping first).

Re-enter later with ziv open <name> (new conversation) or ziv resume <name> (continue the last one).

4. Check and build

ziv check          # mechanically validate the zpi package
ziv build          # ship gate: compile + write ziv.manifest.json

check runs the layered validation (per-entry, cross-entry, graph). build compiles the dependency graph and writes the manifest that publishes a grade for every statement — see the grade model.

5. Wrap up and archive

ziv workspace archive prove-maynard

Archiving is guarded: a dirty worktree or a running session refuses to archive. ziv workspace list shows every workspace and its state; abort-complete unwinds a stuck completion.

That’s the whole loop. The CLI reference covers every verb, and the zpi format explains what the package actually is.