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

# Concepts

> Core filepacks terms, what they mean in practice, and how they fit into the four-command workflow.

## Artifact

An artifact is a deterministic `.fpk` archive representing one packaged directory of files.

Key properties:

* immutable once written
* portable as a single file
* self-describing through `manifest.json`
* structurally comparable against another artifact

In practice, an artifact is the review boundary you hand to a teammate, upload from CI, or compare against a previous run.

## Manifest

`manifest.json` is the canonical metadata document inside the archive.

It is the first archive entry and includes:

* `artifact_name`
* `created_with`
* `file_count`
* `files[]`
* `format_version`
* `payload_digest`
* `total_bytes`

Each file entry records:

* `path`
* `size`
* `hash`

The manifest is what `inspect`, `verify`, and `compare` reason about. It is the source of truth for what the artifact claims to contain.

## Payload

Payload files are stored under `payload/` inside the archive.

The manifest refers to them by normalized relative path without the `payload/` prefix.

Example:

* archive entry: `payload/reports/summary.txt`
* manifest path: `reports/summary.txt`

## Determinism

Determinism means the same logical input produces the same `.fpk` bytes.

In the current implementation, that depends on:

* lexical directory traversal
* sorted manifest entries
* fixed tar header metadata
* stable manifest serialization
* `manifest.json` written first

## Archive digest and payload digest

Two digests matter:

| Digest         | Meaning                                    | Where you see it                                         |
| -------------- | ------------------------------------------ | -------------------------------------------------------- |
| archive digest | SHA-256 of the exact `.fpk` bytes          | CLI `pack` and `inspect` output as `digest=sha256:<hex>` |
| payload digest | SHA-256 over the sorted manifest file list | `manifest.json` as `payload_digest`                      |

The archive digest identifies the artifact file itself. The payload digest proves that the manifest's file inventory still matches the payload file list.

## Verification

Verification checks whether the payload still matches the manifest.

That includes:

* manifest validity
* expected payload paths
* file sizes
* file hashes
* the aggregate `payload_digest`

Use `verify` to confirm an artifact is intact — for example, before using it as a baseline or sharing it for review. `verify` exits `0` on success and `1` on failure.

## Structural comparison

Structural comparison answers a simple question: did any packaged file change?

It compares two manifests and reports added, removed, and changed file paths.

Use `compare` to understand what changed between two runs. `compare` exits `0` when the artifacts are identical and `20` when they differ — an exit code that is directly usable in CI and automation.

## When to use inspect vs verify

| Command   | Use it when you want to...         | It does not prove...                               |
| --------- | ---------------------------------- | -------------------------------------------------- |
| `inspect` | read the artifact summary quickly  | that the payload still matches the manifest        |
| `verify`  | confirm the artifact is intact     | that the output is semantically good or acceptable |
| `compare` | see whether packaged files changed | why the change is good or bad                      |

## Baseline and candidate

When comparing artifacts:

* **baseline** means the accepted or previously known-good artifact
* **candidate** means the new artifact you want to review

The public OSS CLI does not resolve baselines for you. You pass explicit file paths.

## Typical workflow

A common review loop looks like this:

```bash theme={null}
npx filepacks pack ./run-prev --output ./baseline.fpk
npx filepacks pack ./run-current --output ./candidate.fpk
npx filepacks inspect ./candidate.fpk
npx filepacks verify ./candidate.fpk
npx filepacks compare ./baseline.fpk ./candidate.fpk
```

## CLI versus core library

The CLI exposes a narrow command set.

The core package exposes the same public operations programmatically:

* `pack()`
* `inspect()`
* `verify()`
* `compare()`

`pack()` in `@filepacks/core` also accepts an optional `name` field for the artifact name. The public CLI does not currently expose a `--name` flag.

For Node.js examples and return-value details, see [Programmatic API](/programmatic-api).

## Current OSS boundary

The public repo intentionally excludes:

* typed artifact manifests
* registry protocols
* local store management
* tags and baseline workflows
* additional CLI commands outside `pack`, `inspect`, `verify`, and `compare`

For format-level detail, continue to [Artifacts](/artifacts). For practical command patterns, use [CLI workflows](/cli/workflows).