Architecture

Actors, artifact types, distribution model, and design principles.

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.

Property	Source-mode	Ref-mode
Where it lives	Facets registry	External OCI registry
Versioning	Semver + floor constraints	OCI tags and digests
Manifest reference	server: "1.0.0"	server: { image: "reg/img:tag" }
Resolution	Latest at or above floor	Tag → digest at install
Integrity	Canonical fingerprint + API surface hash	OCI 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 integrity hashes. 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

Manifest immutability

Build and publish MUST NOT modify the manifest. The author’s facet.json is included as-is in the archive.

Server-side composition

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.

Adapter-agnostic format

The manifest format is adapter-agnostic. Adapter-specific configuration lives in designated extension points. Each adapter defines its own metadata schema.

Terminal server dependencies

MCP servers MUST NOT declare dependencies on other servers. One level deep — no transitive chains.

Forward compatibility

Consumers MUST tolerate unrecognized fields. New server modes, asset types, or manifest sections can be added without breaking existing consumers.