Skip to main content
The Facets system distributes AI assistant extensions through a registry-based model with two artifact types: facets (text) and MCP servers (code).

​
Actors

Author

Creates facets and/or MCP servers. Publishes to the registry.

Registry

Stores archives, assembles server-side composition, computes integrity hashes.

CLI

Installs facets, resolves server references, manages the lockfile and receipt, runs MCP servers.

AI assistant

Loads text assets into context. Connects to running MCP servers.

​
Artifact types

​
Facets

A named, versioned collection of text assets — skills, agents, and commands — defined by a manifest. MAY compose text from other published facets. MAY reference MCP servers, but server code is never included. When published, the registry assembles a facet archive: manifest + all text assets. Self-contained — no further text resolution at install time.

​
MCP servers

Code assets providing tool capabilities via the Model Context Protocol. Published and versioned independently from facets.
PropertySource-modeRef-mode
Where it livesFacets registryExternal OCI registry
VersioningSemver + floor constraintsOCI tags and digests
Manifest referenceserver: "1.0.0"server: { image: "reg/img:tag" }
ResolutionLatest at or above floorTag → digest at install
IntegrityCanonical fingerprint + API surface hashOCI digest + API surface hash

​
Distribution model

Text → publish time

Registry composes text and includes everything in the archive. Consumers receive a self-contained artifact.

Code → install time

The manifest declares server references. The CLI resolves to specific versions and pins in the lockfile.
Stale text is safe (suboptimal, not broken). Changed text is a trust concern (prompt injection). Stale code is dangerous (security vulnerabilities). This asymmetry drives the split: text is locked at publish; servers float with floor constraints.

​
Lifecycle

1

Author

Create a facet.json manifest and text asset files in a local directory.
2

Publish

Registry assembles the archive, computes the . A published version is immutable.
3

Install

The plan/commit pipeline resolves versions, verifies integrity (cache self-audit + lockfile comparison or registry confirmation), materializes assets, and writes manifest + lockfile + receipt atomically.
4

Run

Text assets in the assistant’s context. MCP servers as managed processes.

​
Design principles

Build and publish MUST NOT modify the manifest. The author’s facet.json is included as-is in the archive.
Text composition MUST be performed by the registry from its own trusted storage. Prevents supply chain attacks where an author replaces composed content with malicious prompts.
The manifest format is adapter-agnostic. Adapter-specific configuration lives in designated extension points. Each adapter defines its own metadata schema.
MCP servers MUST NOT declare dependencies on other servers. One level deep — no transitive chains.
Consumers MUST tolerate unrecognized fields. New server modes, asset types, or manifest sections can be added without breaking existing consumers.