stax build

Compile TypeScript agent or package definitions into deterministic OCI artifacts. stax build validates the selected entry, reads referenced layers from disk, and writes a local artifact directory under .stax/artifacts/ by default.

Usage

stax build
stax build .stax/backend/agent.ts
stax build --persona maya-chen
stax build --all-personas
stax build --symlink-mode flatten

Options

Flag	Description
`--persona <name>`	Build for a specific persona only
`--all-personas`	Pass through persona fan-out selection to the builder
`--symlink-mode`	Control symlink handling: `flatten` resolves file targets

Entry discovery

When run without an explicit entry path, stax build scans:

.stax/<name>/agent.ts
.stax/<name>/package.ts

If exactly one entry is found, it is built automatically. If multiple entries exist, the CLI asks you to choose one explicitly.

What happens during a build

Load entry — Imports the selected definition file
Validate references — Ensures required fields and referenced paths exist
Package layers — Canonicalizes JSON layers and creates deterministic tar+gzip directory layers
Write artifact — Emits manifest.json plus content-addressed blobs under .stax/artifacts/

Example output

Built artifact: sha256:a3f8c1…e7d2
  path: /repo/.stax/artifacts
  layers: 6
    application/vnd.stax.prompt.v1+markdown (412 bytes)
    application/vnd.stax.rules.v1.tar+gzip (828 bytes)
    application/vnd.stax.skills.v1.tar+gzip (0 bytes)

Notes

The current reference CLI does not implement --dry-run or --refresh-lock.
Lockfile support is documented in the spec as forward work, but this build command currently writes only the local artifact directory.

stax validate — Check definitions without building
stax inspect — Examine a built artifact
stax push — Publish the artifact to a registry