Glossary

This glossary defines terms that carry specific meaning within the stax specification. Terms marked with (normative) have precise definitions that affect conformance.

A

Adapter (normative)

A translator that converts a canonical stax artifact into runtime-native files for a specific consumer. Each adapter targets one runtime (e.g., claude-code, codex, cursor) and may support both portable and exact materialization modes. See Adapters.

Agent artifact (normative)

An OCI artifact with media type application/vnd.stax.agent.config.v1+json that contains the complete, immutable definition of an AI agent — its identity, prompt, persona, rules, skills, knowledge, MCP servers, secrets declarations, and runtime hints.

Annotation

An OCI manifest annotation (key-value string pair) used to record metadata about an artifact. stax defines annotations under the dev.stax.* namespace. See OCI Artifact Format.

Archive safety rules (normative)

Constraints on tar+gzip layer contents that prevent path traversal, symlink escapes, absolute paths, and other filesystem attacks. See Layers.

B

Build

The process of compiling TypeScript agent definitions into a deterministic OCI artifact. Performed by stax build. See CLI — build.

C

Canonical

The single authoritative representation of a concept in stax. A canonical artifact is the OCI artifact produced by stax build. Canonical JSON follows deterministic serialization rules (sorted keys, no trailing commas, no comments). Canonical layers are the unambiguous source-of-truth before adapter translation.

Conformance (normative)

The degree to which an implementation satisfies the specification. stax defines three levels: must-level (required for any conforming implementation), should-level (expected unless justified), and may-level (optional). See Specification — Conformance.

Consumer

Any system that reads a stax artifact — a runtime, platform, CI pipeline, or human. Consumers materialize artifacts into runtime-native files or inspect them for metadata.

D

Dependency (normative)

A reference from an agent or package to another stax package. Dependencies are declared in defineAgent() or definePackage() and resolved at build time using the lockfile. See Dependencies.

Deterministic build (normative)

A build where the same inputs always produce byte-identical outputs. stax achieves this through canonical JSON serialization, sorted archive entries, fixed tar metadata, and locked dependency digests. See Layers.

E

Exact mode (normative)

A materialization mode where the adapter attempts byte-for-byte fidelity with the runtime's native file format. Contrast with portable mode. See Materialization.

F

Fidelity (normative)

The degree of accuracy achieved when translating a canonical artifact into a specific runtime's format. Adapters report fidelity as full, high, or lossy. See Adapters — Fidelity.

I

Instruction tree (normative)

A directory structure (instructions/) containing path-scoped instruction files. Each file applies only when the agent works within a matching filesystem path. See Instruction Trees.

K

Knowledge (normative)

Static reference documents (Markdown, text, PDF, CSV) packaged in the knowledge/ layer. Knowledge is read-only and immutable once built. Contrast with memory, which is mutable. See Knowledge.

L

Layer (normative)

A content-addressed blob in an OCI artifact. Each layer has a specific media type (e.g., application/vnd.stax.prompt.v1+markdown) and contains one category of agent configuration. See Layers.

Lockfile (normative)

stax.lock — the intended JSON lockfile format for recording the exact digest of every resolved dependency. Ensures reproducible builds across machines and time. The current reference CLI does not yet emit it automatically. See Lockfile.

Lossy (normative)

A translation where some information from the canonical artifact cannot be represented in the target runtime's format. Adapters MUST emit warnings when lossy translation occurs. See Materialization.

M

Materialization (normative)

The process of translating a canonical artifact into runtime-native files via an adapter. Performed by stax materialize. See Materialization.

MCP (Model Context Protocol) (normative)

A protocol for connecting AI agents to external tools and data sources. stax packages MCP server declarations (transport, command, arguments, environment, secrets) in the mcp layer. See MCP.

Memory (normative)

Mutable, session-scoped or persistent state owned by the consumer runtime. stax artifacts may include seed memory (initial state) but consumers own the runtime memory lifecycle. Contrast with knowledge, which is immutable. See Memory.

Merge rules (normative)

The rules governing how values from multiple packages combine when an agent depends on several packages. Different field types use different strategies: prompts concatenate, rules append, MCP servers merge by key, secrets union. See Merge Rules.

N

Normative

Language that defines required behavior. stax uses RFC 2119 keywords: MUST, MUST NOT, SHOULD, SHOULD NOT, and MAY.

O

OCI (Open Container Initiative)

The industry standard for container image and artifact distribution. stax uses OCI manifests, content-addressed layers, and registry APIs to store and distribute agent artifacts. See OCI Artifact Format.

P

Package (normative)

A reusable bundle of agent configuration (rules, skills, MCP servers, knowledge, secrets) that can be depended on by agents or other packages. Defined with definePackage(). See Packages.

Persona (normative)

An identity overlay containing a name, role, expertise, communication style, and behavioral traits. Personas are defined with definePersona() and referenced by agents. See Persona.

Portable mode (normative)

A materialization mode optimized for broad compatibility across runtimes. May use simplified file structures. Contrast with exact mode. See Materialization.

R

Referrer

An OCI artifact that references another artifact via the subject field. stax uses referrers for signatures, attestations, approvals, and provenance metadata. See OCI Artifact Format — Referrers.

Runtime

A system that executes AI agents — Claude Code, Codex CLI, Cursor, GitHub Copilot, Windsurf, OpenCode, etc. Each runtime has its own configuration format; adapters translate stax artifacts into these formats.

S

Secret (normative)

A named credential declaration in the secrets layer. stax artifacts declare what secrets an agent needs but never contain secret values. Consumers supply actual values at runtime. See Secrets.

Skill (normative)

A Markdown file with YAML frontmatter that defines a reusable capability. Skills are packaged in the skills layer and may contain template variables. See Skills.

Source artifact (normative)

An OCI artifact containing a workspace source snapshot (e.g., a Git checkout). The model is defined in the spec and targeted by stax build-source, but the current reference CLI does not generate source artifacts yet. See Workspace Sources.

Surface (normative)

A named slot in the agent's instruction hierarchy (e.g., system, project, user, session). Surfaces define where prompt content and rules are placed in the final instruction tree. See Surfaces.

V

Validation (normative)

The process of checking agent definitions against the specification's structural and semantic rules. Performed by stax validate or as part of stax build. See CLI — validate.