vercel-labs--zerolang/skill-data/packages.md

name, description

name	description
packages	Create, inspect, and repair Zero packages and manifests.

Zero Packages

Use this when working with zero.toml, compatibility zero.json, package-local modules, package tests, or multi-file Zero projects.

Create

For agent-authored packages, start graph-first:

zero init
zero patch --op 'addMain'

zero.graph is the package graph store and compiler input. .0 files are the human-readable projection; export them only when a human asks to review or edit the projection. zero init defaults to the current directory and uses that directory's folder name as the package name. Use zero init app when the user asks for a new subdirectory. It writes TOML metadata by default; use zero init --manifest json [package] only for explicit compatibility cases. Use zero init --template cli|lib|package [package] only when the user explicitly asks for starter files.

Manifest

Minimal executable package in TOML:

[package]
name = "hello"
version = "0.1.0"

[targets.cli]
kind = "exe"
main = "src/main.0"

The target main path names the human-readable projection for source maps, export/import, and review. Normal package commands compile from zero.graph.

JSON is also accepted for compatibility, but new agent-authored packages should use TOML:

{
  "package": { "name": "hello", "version": "0.1.0" },
  "targets": { "cli": { "kind": "exe", "main": "src/main.0" } }
}

If both zero.toml and zero.json exist in the same package root, Zero uses zero.toml. Keep one manifest checked in unless the task is specifically testing precedence.

Pass either the package directory or manifest to commands:

zero check
zero check zero.toml
zero run examples/systems-package

Module Imports

Package-local imports resolve from src/:

• use helpers resolves src/helpers.0
• use config.parser resolves src/config/parser.0
• use config.parser may also resolve src/config/parser/mod.0

Standard library imports use the same use form:

use std.mem
use std.parse

Avoid implicit files. If an import is unknown, run:

zero check
zero inspect

Dependencies

Current packages support local path dependencies and registry metadata. Local dependencies must point at a directory containing zero.toml or compatibility zero.json; zero.toml takes precedence.

TOML dependency metadata:

[dependencies.local-tools]
path = "../local-tools"
version = "0.1.0"

{
  "dependencies": {
    "local-tools": { "path": "../local-tools", "version": "0.1.0" }
  }
}

The resolver is declarative; it records deterministic lock facts under .zero/package-locks/ and does not fetch remote package code.

Package compiler commands validate and compile from a checked-in zero.graph store, including target and package metadata, and can operate when .0 source projections are missing. When the projection was edited, commands that consume the store (zero check, zero build, zero run, zero test, zero query, zero view, zero diff, and friends) refresh the stale store from source and note it on stderr (ZERO_STALE=fail makes that an error); they never rewrite .0 files. When zero.graph is the newer side, for example right after zero patch, they keep using the graph and note that too; when both sides changed independently they fail with RGP006 and offer zero import or zero export as repairs. Drift is classified by content (each store write records a source projection hash), never by file timestamps, so staged or cloned workspaces behave identically. Use zero verify-projection when drift must fail the workflow, and zero export only when a human-readable projection needs regeneration.

Inspect

zero inspect
zero doc
zero dev

Use --json when a tool needs exact graph, doc, or dev fields. Useful graph facts include modules, source paths, import edges, public and private symbol counts, function effects, required capabilities, target facts, dependency facts, and package cache key inputs.

Graph Authoring

For agent-authored packages, prefer the repository graph surface:

zero init
zero patch --op 'addMain'

Inspect and patch existing packages through the graph. Create an artifact under .zero/ only when another tool needs a file artifact:

zero view
zero patch --op 'addMain'

Package-level patches write zero.graph; successful patch output includes the new graph hash and top-level symbols. Use zero export only to materialize .0 for human review, and zero import after humans edit that projection; import accepts the package root or any source path inside it and updates the existing store in place. Keep derived graph artifacts out of the package source unless the user explicitly asks for them.

Repository graph stores are binary by default. Use zero init --format text or zero import --format text [package] only when the package intentionally needs a readable debug store. Normal reads auto-detect both encodings, and normal writes preserve an existing text or binary store. Stdlib std/*.graph stores are binary graph stores; std/*.0 siblings are human projections and are not used as the stdlib compile source.

Common Repairs

• IMP001: create the imported module, fix its path, or adjust use.
• IMP002: break a direct import cycle.
• PKG001: fix a local dependency path so it contains zero.toml or a compatibility zero.json.
• PKG002: break a package dependency cycle.
• PKG003: avoid resolving one package name to multiple versions.
• PKG004: update target metadata or choose a supported target.

Prefer a package-local fix over moving unrelated files.