Packages & projects

X07 packages are source-only (x07AST JSON), and projects pin dependencies with a deterministic lockfile.

Files

• x07.json — project definition
• x07-package.json — package definition (required only for publishable packages)
• x07.lock.json — pinned dependency graph + hashes

Manifest schema (canonical)

• New and actively maintained projects should use x07.project@0.3.0.
• The toolchain still accepts x07.project@0.2.0 for legacy manifests.
• project.patch (transitive dependency overrides) requires x07.project@0.3.0.

Module roots (important)

x07.json contains a module_roots list. This should list your source directories (usually src for projects, and modules for publishable package repos).

When you run x07 pkg lock, dependencies are fetched into .x07/deps/... and pinned in x07.lock.json. Tooling that accepts --project (for example x07 build --project x07.json and x07 run --project x07.json) automatically adds the locked dependency module roots from the lockfile.

Do not add .x07/deps/*/modules paths to module_roots manually.

If you see an unknown module compile error and you don’t know which package provides it, use:

• x07 pkg provides <module-id>

Quickstart

mkdir mypkg
cd mypkg
x07 init

# Browse packages at https://x07.io/packages
# Add the latest non-yanked version from the index:
x07 pkg add NAME --sync

# Or pin explicitly:
x07 pkg versions NAME
x07 pkg add NAME@VERSION --sync

# Remove a dependency:
x07 pkg remove NAME --sync

x07 init also writes the agent kit (AGENT.md, x07-toolchain.toml, .agent/skills/, and .agent/docs/).

If you are creating a publishable package repo, start with x07 init --package instead of x07 init (it creates x07-package.json, modules/, tests/, and the same agent kit). Follow the next_steps in the init JSON report for the canonical pack/login/publish workflow.

x07 pkg lock downloads dependencies into .x07/deps/… and writes x07.lock.json. Commit x07.lock.json to make builds reproducible.

In CI, use:

• x07 pkg lock --project x07.json --check

When the index can be consulted, --check also fails on:

• yanked dependencies (allow only with --allow-yanked)
• active advisories (allow only with --allow-advisories)

If you need to override a transitive dependency (for example to move off a yanked/advised version), use project.patch in x07.json:

{
  "schema_version": "x07.project@0.3.0",
  "patch": {
    "some-dep": { "version": "1.2.3" }
  }
}

Some packages may declare required helper packages via meta.requires_packages. When present, x07 pkg lock may add those transitive deps to x07.json before locking. Treat this as a convenience, not a contract; prefer the capability map and x07 init --template ... so the dependency set is explicit.

When fetching is required, x07 pkg lock defaults to the official registry index. Override with --index sparse+https://registry.x07.io/index/, or use --offline to forbid network access.

Deterministic builds

X07’s lockfile ensures:

• exact versions
• exact content hashes
• reproducible builds

Dependency resolution

• uses a sparse-index-style registry model
• the lockfile is canonical JSON