vercel-labs--zerolang/docs/articles/package-manifest.md

Packages Are Graph-Backed

In Zerolang, a human usually starts with the package they want, not the manifest fields:

{
  "messages": [
    {
      "role": "user",
      "text": "start a small crm api package here"
    },
    {
      "role": "assistant",
      "text": "I’ll start the package with zero.toml and add the first API route."
    },
    {
      "role": "tools",
      "calls": [
        {
          "command": "zero init --template package --manifest toml --format binary",
          "output": "graph project init ok\nwrote: ./zero.toml\nwrote: ./zero.graph"
        },
        {
          "command": "zero patch /tmp/crm-routes.patch",
          "output": "program graph patch ok"
        },
        {
          "command": "zero run -- $'GET /health\\n\\n'",
          "output": "HTTP/1.1 200 OK\ncontent-type: application/json\nconnection: close"
        }
      ]
    }
  ]
}

What This Means

A Zero package has a manifest, a graph store, and review projections:

zero.toml
zero.graph
src/main.0

The manifest tells Zero where the human-readable target projection lives. The graph store is the normal compiler input. The projection is for spans, review, and rare manual edits.

Preferred Manifest

Use zero.toml for new projects:

[package]
name = "crm-api"
version = "0.1.0"
license = "MIT"

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

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

zero.json is still accepted as a compatibility manifest format. Use one manifest in normal projects. If both exist for a directory input, zero.toml takes precedence.

What main Means

The main path names the human-readable projection associated with a target. It does not make the projection the normal package compile input.

Normal package commands compile from the checked-in zero.graph store:

zero check
zero test
zero run -- help
zero build --out .zero/out/app
zero size --json

These commands report projection state, but they do not rewrite .0 files.

Projection Import And Export

Use projection commands only when humans need them:

zero export
zero verify-projection
zero import

zero export refreshes .0 files from the graph. zero import rebuilds the graph from projection text after a human edit. zero verify-projection is the no-write drift gate.

Dependencies

Package-local imports resolve from src/ projection paths for stable human review:

• src/foo.0 defines module foo
• src/foo/mod.0 defines directory module foo

Local path dependencies are accepted. Exact versioned registry references are recorded as metadata without remote fetches in the current compiler slice.

Package inspection and docs JSON may include dependencies, package.lockfile, packageCache.cacheKeyInputs, and publicationGate facts. Diagnostics such as PKG001 and PKG004 explain invalid manifests, dependency shape issues, and package resolution failures.

Profiles

Profiles are declared in the manifest and reported by build/size JSON. Use zero build --json and zero size --json to inspect profileSemantics, profileBudget, retained helpers, and target readiness.