Core Concepts
- Facet
- Assets
A named, versioned collection of text assets defined by a manifest (
facet.yaml). What the author creates locally, what gets published to the registry, and what gets extracted after install.| Term | Definition |
|---|---|
| Facet | A named, versioned collection of text assets defined by a manifest (facet.yaml). What the author creates locally, what gets published to the registry, and what gets extracted after install. |
| Facet archive | The published, self-contained artifact stored in the registry. Contains the manifest and all text assets (locally authored and composed). The transport form between publish and install. |
| Asset | A discrete unit of content within a facet. Assets are either text assets (skills, agents, commands) or server assets (MCP server references). |
| Text asset | An asset containing text — a skill, an agent prompt, or a command prompt. Text assets are included in the facet archive. |
| Server asset | An MCP server reference in a facet’s manifest. Server assets are linked, not included — server code is published and archived separately from the facet. |
| MCP server | An asset type containing code (not text). Published independently from facets, versioned independently, resolved at install time. Two execution modes: source-mode and ref-mode. |
Execution Modes
| Term | Definition |
|---|---|
| Source-mode | MCP server execution mode where source code is published to the facets registry and run using a managed runtime. Always hyphenated. |
| Ref-mode | MCP server execution mode where the facet manifest references an OCI container image hosted in an external registry. Always hyphenated. |
OCI-mode, source mode (unhyphenated), ref mode (unhyphenated).
Version Constraints
| Term | Definition |
|---|---|
| Floor constraint | The version constraint mechanism for source-mode MCP servers. Declares a minimum acceptable version; the CLI resolves to the latest at or above the floor at install time. |
| Floor version | The specific minimum version value declared in a floor constraint (e.g., "1.0.0"). |
minimum version, floor-constrained.
Integrity
| Term | Definition |
|---|---|
| Content hash | A SHA-256 hash of a published artifact (facet archive or source-mode server artifact). Verifies that downloaded bytes match what was published. |
| API surface hash | A SHA-256 hash of an MCP server’s tool declarations (names, descriptions, parameters, schemas). Detects structural breaking changes between versions. |
| OCI digest | An immutable content hash for a container image. Used to pin ref-mode MCP servers in the lockfile. |
integrity hash, content integrity hash.
Lifecycle
| Stage | What exists |
|---|---|
| Authoring | A facet — manifest and text assets in a local directory. |
| Publishing | The facet is built into an archive — text assets assembled, content hash computed, stored in the registry. |
| Installing | The archive is downloaded, verified, and extracted. Text assets are placed locally. Server references are resolved. The lockfile is written. |
| Running | The installed facet is loaded by the AI assistant. Text assets are in context. MCP servers are running processes managed by the CLI. |