> ## Documentation Index
> Fetch the complete documentation index at: https://docs.agentfacets.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Introduction

> The open source Agent Facet specification

Facets are an open format and distribution system for modular AI assistant extensions. A facet packages skills, agents,
and commands into a versioned, distributable unit with a well-defined manifest, integrity model, install pipeline, and
publish flow.

This specification defines the authoritative requirements for the Facets format and protocol. For introductory material,
see [Introduction](/) and [Key Concepts](/docs/learn).

<Info>
  The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in [RFC 2119](https://www.ietf.org/rfc/rfc2119.txt) and [RFC 8174](https://www.ietf.org/rfc/rfc8174.txt).
</Info>

## Actors

<CardGroup cols={2}>
  <Card horizontal title="Author" icon="pen">
    Creates facets for agentic use. Publishes to the registry.
  </Card>

  <Card horizontal title="CLI" icon="terminal">
    Installs facets, manages the lockfile and caches.
  </Card>

  <Card horizontal title="Registry" icon="database">
    Stores archives, provides provenance, and acts as an integrity authority.
  </Card>

  <Card horizontal title="AI assistant" icon="bot">
    Loads facets into context.
  </Card>
</CardGroup>

## The facet artifact

A **facet** is a named, versioned collection of text assets — skills, agents, and commands — defined by a manifest. The author's CLI builds it into a self-contained **facet archive** (`.facet`): the manifest plus every text asset. The registry verifies and stores that archive, and consumers receive exactly the bytes the author built — no text is fetched or assembled at install time.

<Info>
  Stale text is safe (suboptimal, not broken). Changed text is a trust concern (prompt injection). That is why content is locked into the archive at build time and every install verifies the published hashes.
</Info>

## Lifecycle

<Steps>
  <Step title="Author">
    Create a `facet.json` manifest and text asset files in a local directory.
  </Step>

  <Step title="Build & publish">
    The CLI builds the archive and computes its <Tooltip tip="The canonical fingerprint (content_integrity, over the uncompressed inner tar) and the transport hash (content_hash, over the uploaded tarball) — two distinct, non-interchangeable hashes." cta="See Integrity Model" href="/specification/integrity">integrity hashes</Tooltip>; the registry verifies the upload, stores it, and publishes the hashes. A published version is immutable. See [Build](/specification/build) and [Publish](/specification/publish).
  </Step>

  <Step title="Install">
    The [plan/commit pipeline](/specification/install) resolves versions, verifies integrity (cache self-audit + lockfile comparison or registry confirmation), materializes assets, and writes manifest + lockfile + receipt atomically.
  </Step>

  <Step title="Run">
    Text assets in the assistant's context.
  </Step>
</Steps>

## Security and trust

Facets enable arbitrary text injection into AI assistant contexts.
Implementors MUST address:

1. **Content verification** -- hashes MUST be verified at download, on every cache hit, and at lockfile-entry creation. A lockfile entry for a registry facet MUST NOT be created without registry confirmation.
2. **User consent** -- consumers SHOULD understand what a facet contains before installing it.

## Sections

<CardGroup cols={2}>
  <Card title="Project Manifest" icon="files" href="/specification/project-manifest">
    The `facets.json` format -- declared facets and entry semantics.
  </Card>

  <Card title="Lockfile" icon="lock" href="/specification/lockfile">
    The `facets.lock` format -- resolved versions and integrity.
  </Card>

  <Card title="Facet Manifest" icon="file-code" href="/specification/manifest">
    The `facet.json` format -- fields, types, constraints.
  </Card>

  <Card title="Facet Archive" icon="package" href="/specification/archive">
    The two-layer `.facet` format -- layout, determinism, hashes.
  </Card>

  <Card title="Integrity Model" icon="shield-check" href="/specification/integrity">
    Content hashing and cache audit.
  </Card>

  <Card title="Installation" icon="download" href="/specification/install">
    Two-phase pipeline: planning, then commit.
  </Card>

  <Card title="Planning" icon="route" href="/specification/planning">
    Phase 1 -- turn a command into a delta.
  </Card>

  <Card title="Commit" icon="check" href="/specification/commit">
    Phase 2 -- resolve, compose, materialize, write atomically.
  </Card>

  <Card title="Materialization" icon="tag" href="/specification/materialization">
    Authored vs. effective names, aliasing, omission, collisions.
  </Card>

  <Card title="Build" icon="hammer" href="/specification/build">
    Produce the canonical `.facet` archive.
  </Card>

  <Card title="Publish" icon="upload" href="/specification/publish">
    Verify and upload to the registry.
  </Card>

  <Card title="Terminology" icon="book" href="/specification/terminology">
    Canonical terms and definitions.
  </Card>
</CardGroup>