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

# FAQ

> Common questions about what filepacks does, where it fits, and how to use the current OSS surface well.

## What is a `.fpk` file?

A `.fpk` file is a deterministic POSIX tar archive with:

* `manifest.json` as the first entry
* payload files stored under `payload/`

The manifest records the artifact name, file count, per-file hashes and sizes, and a payload digest. That makes the artifact self-describing and locally verifiable without unpacking.

## Why would I use filepacks instead of keeping the directory?

Use filepacks when the directory needs a stable, portable review boundary.

A `.fpk` file gives you:

* one file instead of a loose tree
* a canonical manifest
* deterministic archive bytes
* local verification
* structural comparison against another run

## What commands are publicly supported?

The public CLI supports only:

* `filepacks pack <input> --output <file>`
* `filepacks inspect <file>`
* `filepacks verify <file>`
* `filepacks compare <baseline> <candidate>`

## What should I use filepacks for in practice?

filepacks works best for repeated workflows that produce a directory of output files you want to review, compare, or archive:

* **CI builds**: capture a build output as a portable artifact, verify it, and compare it against the last known-good build
* **Agent runs**: pack agent output after each run, compare to a previous run to detect unexpected changes
* **Eval pipelines**: pack each eval run output, compare against a baseline to track regressions
* **Portable evidence**: share a single `.fpk` file instead of a directory; the recipient can `inspect` and `verify` it locally

## Is filepacks only for humans, or can automation use it too?

Both. Humans can read the summary output and review the changed paths. Automation can use:

* deterministic artifact files
* `verify` success or failure
* `compare` exit `0` vs `20`
* `@filepacks/core` structured results

## Does the public CLI support tags, baselines, or registries?

No. Those flows are outside the current public OSS surface.

## Can I inspect an artifact without unpacking it?

Yes. `filepacks inspect <file>` reads artifact metadata directly from the `.fpk` file.

## How do I verify corruption or drift?

Run:

```bash theme={null}
npx filepacks verify ./artifact.fpk
```

If the artifact is invalid, `verify` exits non-zero and reports mismatch lines.

## How do I compare two artifacts?

Run:

```bash theme={null}
npx filepacks compare ./baseline.fpk ./candidate.fpk
```

The command exits `0` if they are structurally identical and `20` if files were added, removed, or changed.

## Does compare tell me whether the change is good?

No. `compare` is structural only. It tells you that packaged files changed, not whether the change is correct or desirable.

## Can I use filepacks from code?

Yes. Install `@filepacks/core` and call:

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

## Can an AI agent or eval runner use filepacks?

Yes. The CLI and core API are simple enough to integrate directly into an agent workflow or eval harness. After a run produces output files, pack the directory:

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

`compare` exits `0` if nothing changed and `20` if anything did — that exit code is usable in any script or CI job.

The `@filepacks/core` package exposes the same operations programmatically if you need structured results inside a harness.

## What does verification prove?

`verify` proves that the artifact payload still matches the manifest.

It does not prove that the files are semantically correct, only that the artifact is internally consistent and intact.

## Does the public repo support typed artifacts?

No. The current v0 OSS manifest validator rejects typed artifact fields such as `schema_version` and `artifact_type`.

## Are directories stored as archive entries?

No. The public `.fpk` format stores regular file entries only. Directory entries must not be emitted.

## What Node version do I need?

The CLI and core packages declare `node >=18`.