Skip to main content
This page defines what happens during facet install and facet upgrade — how facet archives are downloaded, text assets are extracted, server references are resolved, and everything is pinned in a lockfile. The install flow has two distinct resolution paths:
  1. Text — already resolved. The facet archive is self-contained (composed by the registry at publish time). No text resolution at install time.
  2. MCP servers — references that MUST be resolved to specific versions at install time.

​
Install

​
Inputs

A facet name (or name@version) to install.

​
Steps

  1. Download the facet archive. Query the registry for the facet at the requested version (or latest if no version specified). Download the archive. Verify the content hash against the registry’s recorded hash (see Integrity Model). A hash mismatch MUST be a hard failure — the archive MUST be rejected.
  2. Read the manifest. Parse facet.yaml from the archive.
  3. Install text assets. Extract the archive’s text assets (skills, agent prompts, command prompts — both locally authored and composed) into the local facet directory. No resolution is needed — the archive is self-contained.
  4. Resolve MCP server references. For each entry in the servers section: Source-mode (string value — floor version):
    • Query the registry for the latest version of the named server at or above the floor constraint.
    • Download the server artifact.
    • Verify the server artifact’s content hash.
    • Compute the server’s API surface hash for future breaking-change detection.
    Ref-mode (object value — OCI image):
    • Resolve the OCI image tag to a digest by querying the OCI registry. If the reference is already a digest, use it as-is.
    • Pin the resolved digest in the lockfile.
    • Compute the server’s API surface hash for future breaking-change detection.
    Resolution is always one level deep. MCP servers are terminal — they MUST NOT declare dependencies on other servers. There is no transitive resolution.
  5. Write the lockfile. Record the exact resolved versions and integrity hashes: 
    # facets.lock
facet:
  name: acme-dev
  version: "1.0.0"
  integrity: "sha256:abc123..."

servers:
  # Source-mode server
  jira:
    version: "1.5.2"
    integrity: "sha256:def456..."
    api_surface: "sha256:789abc..."
  github:
    version: "2.4.0"
    integrity: "sha256:ghi012..."
    api_surface: "sha256:345def..."
  # Ref-mode server
  slack:
    image: "ghcr.io/acme/slack-bot:v2"
    digest: "sha256:e4d909..."
    api_surface: "sha256:567ghi..."
  6. Configure servers for the active platform. For each resolved server, generate the platform-specific configuration needed to start the server (e.g., MCP server config entries for the active AI assistant). Platform configuration details are handled by the CLI’s platform adapters.

​
Lockfile-First Installs

If a lockfile already exists, facet install MUST use the pinned versions instead of resolving from the registry. This ensures reproducible installs across team members and environments. Only facet upgrade resolves newer versions. The lockfile SHOULD be version-controlled so that all team members and CI environments get the same versions.

​
Upgrade

facet upgrade checks for newer facet versions and newer MCP server versions in a single interactive flow.

​
Steps

  1. Read the lockfile and manifest. Load the currently pinned facet version and server versions.
  2. Check for updates.
    • Facet: Query the registry for the latest version of the installed facet. A newer version MAY contain updated composed text, new server references, changed server floor constraints, or new local content.
    • Source-mode servers: Query the registry for the latest version at or above the floor constraint.
    • Ref-mode servers: Re-resolve the OCI tag to check for a newer digest.
  3. Detect API surface changes. For each server with a newer version:
    • Download the new server artifact and compute its API surface hash.
    • Compare to the API surface hash in the lockfile.
    • If unchanged — the upgrade is structurally safe.
    • If changed — a structural change occurred. The consumer MUST be warned about structural changes.
  4. Present available updates. Show the consumer what updates are available, including API surface change status for each server. The consumer controls which updates to apply.
  5. Apply selected updates.
    • If the facet version changed: download the new archive, verify integrity, re-extract text assets, and re-resolve any server references that have new floor constraints.
    • If server versions changed: download new server artifacts, verify integrity, update platform configuration.
  6. Write the updated lockfile. Record the new versions, content hashes, and API surface hashes for all updated artifacts.

​
Lockfile Semantics

The lockfile (facets.lock) pins the exact state of an installation:
FieldDescription
facet.nameThe installed facet name.
facet.versionThe exact installed facet version.
facet.integrityContent hash of the facet archive.
servers.<name>.versionSource-mode: the exact resolved server version.
servers.<name>.integritySource-mode: content hash of the server artifact.
servers.<name>.imageRef-mode: the OCI image reference (tag or digest) from the manifest.
servers.<name>.digestRef-mode: the resolved OCI digest pinned at install time.
servers.<name>.api_surfaceAPI surface hash at install time — the baseline for change detection (both modes).

​
Not in the Install Flow

  • Text asset resolution — text is already in the archive. No install-time fetching of composed facets.
  • Transitive server resolution — servers are terminal. No multi-level dependency resolution.
  • Local disk layout specifics — where files are placed on disk is an implementation concern, not a specification-level decision.