stax materialize

Resolve an artifact, render it through a runtime adapter, and write the resulting files to an output directory. This is how a canonical stax artifact becomes concrete runtime files such as CLAUDE.md, .cursor/rules/*, or opencode.jsonc.

Usage

stax materialize ghcr.io/myorg/agents/backend-engineer:3.1.0 --out ./output
stax materialize ./artifact-dir --adapter codex --out ./codex-output
stax materialize ghcr.io/myorg/agents/backend-engineer:3.1.0 --json
stax materialize ghcr.io/myorg/agents/backend-engineer:3.1.0 --plan --consumer codex

Options

What stax materialize does

1. Load artifact — Pull from OCI or read a local artifact directory
2. Decode canonical layers — Parse prompt, persona, rules, MCP, package layers, and more
3. Merge packages — Resolve package references and merge canonical content
4. Render adapter files — Produce runtime-native files through the selected adapter
5. Write output — Materialize those files into --out

Example output

Materialized backend-engineer@3.1.0
  adapter: claude-code
  fidelity: best-effort
  files written: 4
  output: ./output

Planning instead of writing

Use --plan to preview the same rendered output without touching the filesystem:

stax materialize ghcr.io/myorg/agents/backend-engineer:3.1.0 --plan --consumer codex

Machine-readable output

--json returns a summary of the applied materialization, including:

• name
• version
• adapter
• targets
• fidelity
• lossy
• warnings
• files
• outputDir

Example:

stax materialize ghcr.io/myorg/agents/backend-engineer:3.1.0 --json | jq '.files'

Related commands

• stax plan-install — Preview rendered actions without writing files
• stax inspect — View artifact metadata first
• stax pull — Pull into the local cache