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

# Format

> Archive layout, path rules, and format constraints for valid .fpk artifacts.

## Archive layout

A `.fpk` artifact is a POSIX tar archive containing exactly one manifest and zero or more payload files.

Canonical layout:

```text theme={null}
manifest.json
payload/<relative-path>
payload/<relative-path>
...
```

That layout is intentionally small: one manifest plus regular payload files.

## Required rules

Producer requirements from the current public spec:

* `manifest.json` must be the first archive entry
* payload entries must be stored under `payload/`
* payload entries must be regular file entries
* directory entries must not be emitted
* entries outside `manifest.json` and `payload/` must not be emitted
* duplicate archive entry names must not be emitted
* duplicate payload relative paths must not be emitted
* payload entries must be emitted in lexical order by payload relative path

Verifier requirements:

* `manifest.json` must exist exactly once
* archive entries must be regular files
* entries outside `manifest.json` and `payload/` must be rejected
* invalid payload paths must be rejected
* duplicate payload relative paths must be rejected

## Why these rules exist

These constraints keep the format predictable:

* `manifest.json` first makes the artifact self-describing immediately
* `payload/` keeps file content separate from metadata
* no directory entries avoids tar-specific ambiguity
* normalized paths make comparison consistent across platforms

## Path rules

Payload paths in the manifest:

* must be non-empty
* must not start with `/`
* must not contain backslashes
* must not contain `//`
* must not contain empty path segments
* must not contain `.` or `..` path segments
* must use `/` separators on every platform

Examples:

| Path                    | Valid |
| ----------------------- | ----- |
| `results.jsonl`         | yes   |
| `outputs/run-1.json`    | yes   |
| `/outputs/run-1.json`   | no    |
| `outputs\\run-1.json`   | no    |
| `outputs/../run-1.json` | no    |

## What this means for developers

If `pack` succeeds, the public CLI has already emitted a conforming artifact. You usually care about the full format rules when:

* writing your own producer or verifier around `@filepacks/core`
* validating a `.fpk` file from somewhere else
* debugging why a malformed archive was rejected

## Artifact identity

For the current generic public format, the artifact digest is the SHA-256 digest of the exact `.fpk` archive bytes.