Skip to main content

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.

​
Archive layout

A .fpk artifact is a POSIX tar archive containing exactly one manifest and zero or more payload files. Canonical layout: 
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:
PathValid
results.jsonlyes
outputs/run-1.jsonyes
/outputs/run-1.jsonno
outputs\\run-1.jsonno
outputs/../run-1.jsonno

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