> ## 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.

# Why filepacks

> Why deterministic artifacts are easier to review, compare, and trust than loose output directories.

Repeated workflows usually emit plain directories. That is easy to produce, but awkward to trust:

* a directory has no stable artifact identity
* verification is improvised
* comparison depends on whatever diff tool you reach for
* handoff often loses the exact context of what was packaged

filepacks fixes that by turning the directory into a deterministic `.fpk` archive with a canonical manifest.

## The problem with loose directories

Suppose a baseline run and a candidate run both produce:

```text theme={null}
outputs/results.json
outputs/summary.txt
```

Without an artifact boundary, you still have to answer:

* what exactly was included in the snapshot?
* are the files still byte-for-byte what was originally captured?
* which files changed between runs?

Without an artifact boundary, those answers usually come from a mix of shell commands, ad hoc logs, screenshots, or local conventions.

## What filepacks adds

filepacks gives you one portable file and a small repeatable workflow:

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

That workflow gives you:

* a single `.fpk` file as the portable artifact boundary
* `manifest.json` as the canonical file inventory
* deterministic archive construction for stable bytes
* local verification against recorded file sizes and hashes
* structural comparison between baseline and candidate artifacts

## Why determinism matters

If the same logical input produces the same artifact bytes, the archive digest becomes a meaningful identity for the packaged output.

That helps with:

* reproducible review
* baseline-versus-candidate workflows
* durable evidence capture in CI
* human review grounded in concrete files
* agent workflows that need deterministic evidence instead of ambiguous text summaries

## Why this helps agents and evals

When an AI coding agent or eval runner produces output files, those outputs often need to survive beyond the original process. Packing them into a `.fpk` artifact makes them:

* portable enough to hand to another person or agent
* inspectable later without recreating the run
* comparable against an accepted baseline
* verifiable before use in review or automation

Example:

```bash theme={null}
npx filepacks pack ./agent-output --output ./run-42.fpk
npx filepacks compare ./run-41.fpk ./run-42.fpk
```

`compare` exits `0` if nothing changed and `20` if any packaged file changed. That is enough for a CI job, harness, or review bot to distinguish “same output” from “needs review”.

## Why not just use tar, zip, screenshots, or logs?

Generic tools can capture files, but they do not define the public filepacks contract:

* `manifest.json` must be first
* payload files must live under `payload/`
* directory entries are not allowed
* paths must be normalized relative paths
* tar header metadata is fixed for deterministic output
* verification and comparison are part of the intended workflow

Screenshots and logs can help with explanation, but they are not a deterministic artifact format. They do not tell you exactly which files were packaged, how they hash, or whether a later copy still matches the original output.

## Why filepacks stays narrow

The current OSS surface is intentionally conservative. It focuses on packaging, inspection, verification, and comparison of deterministic file evidence.

It is not trying to be:

* a cloud platform
* a storage sync layer
* a registry service
* a general workflow engine
* a replacement for Git

## Where it fits

filepacks is a good fit when you want generated output to stay reviewable and portable without introducing a larger hosted system.

That includes:

* agent run outputs
* eval artifacts that are just file trees
* CI-generated reports and build outputs
* regression bundles for baseline/candidate review

For concrete examples, continue to [Use cases](/use-cases) and [Agent workflows](/agent-workflows).