Documentation Guides

New to zipnative? Start with the Quickstart — the four core workflows in about five minutes. For the full export surface, see api.json (mechanically extracted, never guessed).

Hands-on guides covering installation, the three surfaces (library, CLI, MCP server), the security model, the determinism contract and the frozen error vocabulary. Every guide is written as Markdown (the source of truth for the llms pipeline) and pre-rendered — use the “Copy page as Markdown” button on any guide to feed it to an agent.

• Quickstart → Install zipnative and cover the four core workflows — random-access reading, secure extraction, deterministic creation and incremental modification — in about five minutes.
• Choosing your surface → Library, CLI or MCP server? The decision in prose, the capability × surface matrix for all three packages (machine-readable twin in docs/data/surfaces.json), and the honest notes — including why no surface encrypts.
• CLI guide → zipnative-cli 1.0.0: the fifteen commands with every flag, the agent contract (--json envelope, E_* codes, --dry-run, --summary / --fields), global options, environment and the filesystem trust boundary.
• MCP guide → zipnative-mcp 1.0.0 for AI assistants: client configuration, the thirteen tools with their inputs and outputs, seven prompts, sandboxed resources, the seven environment variables, the error model and the security model.
• Security model → Every archive is untrusted input: the threat table, the CWE-tagged configurable bounds, the refusals that never opt out, and the forward reader's trust caveat.
• The determinism contract → Three guarantee levels, the frozen pure-TS encoder constants behind deterministic: true, and the documented ways reproducibility can be lost.
• Errors and error codes → The frozen machine-readable vocabulary (39 codes): branch on err.code, never on message text. Registry twin in docs/data/errors.json.
• Use cases → Five production architectures with diagrams, each built from shipped APIs — the manifest peek (openZip), untrusted-upload intake (extractZip), the reproducibility gate (deterministic: true), streaming intake at the edge (iterateZipEntries), and encrypt-first packaging (confidentiality delegated to pdfnative or Office — the archive layer has no password by design).
• Conformance and validation → The authority story: the first open clause-by-clause ISO/IEC 21320-1:2015 validator (npm run validate:zip), the foreign integrity pass, and the six-parser differential extraction matrix — blocking in CI and before every publish.
• Large and remote archives → Open an archive of any size from HTTP ranges, a Blob, a file handle or object storage with the memory of its central directory — the injected byte-range source (openZipRange), cancellation and progress on every asynchronous call, and the Zip64 streaming opt-in (1.1).
• Reproducible builds → Measure, canonicalise, prove: analyzeDeterminism, canonicalizeZip and raw transplant turn any archive — Gradle, Maven, zip, Explorer — into a reproducible artefact without recompression, under the frozen byte contract (1.1).