Skip to main content
A build turns an author’s source tree into the canonical .facet archive. That archive is the artifact of record: the bytes publish later verifies and uploads. Command behavior, flags, and output are documented at facet build.

​
Steps

  1. Validate the manifest. Parse facet.json and validate it against the manifest schema. The name MUST be a valid facet identity, and at least one asset MUST be declared, which is a text asset or an MCP server declaration, or else a composed facet. Schema validation also enforces asset-name grammar, the shared skill and command namespace, and declaration validity.
  2. Resolve prompts. Read each declared text asset from its conventional path: skills/<name>/SKILL.md, agents/<name>.md, commands/<name>.md. A missing file is a build error. A primary text-asset file MAY carry author-supplied YAML front matter. It ships verbatim and is reconciled with manifest metadata at install time. See Text assets.
  3. Resolve supplementary files. Read each declared supplementary file as opaque bytes. Binary and empty files are valid, and front matter is never parsed. A missing file, a symlink or other non-regular file, an unsafe path, or a resolved-path collision is a build error.
  4. Validate content. A declared primary text asset MUST NOT be empty or whitespace only. Validation is static. A build MUST NOT locate a declared command, start a process, connect to a URL, or authenticate.
  5. Assemble the archive. Derive the entry set from the manifest, compute a SHA-256 hash for every entry, assemble the deterministic inner tar, compute the integrity hash over its uncompressed bytes, gzip it, and write the outer tar containing build-manifest.json and the compressed inner archive. MCP server declarations contribute no archive entry. They travel inside the embedded facet.json, so a changed declaration changes the facet’s integrity hash.
The version field is not constrained by the schema. A registry MAY require semver, and this one does: a non-semver version builds locally and is rejected at publish.

​
Boundaries

A build never contacts the registry, never modifies the manifest, and never contacts or launches a declared MCP server. What happens to the artifact next is defined in Publish.