Moving packs between environments

A bundle is a pack as a single JSON file: the pack, its PACK.md guidance, its connections, the upstream packs it reads, and its knowledge bases (documents, node tree, chunks, context graph), all keyed by slugs and paths instead of ids. No org, no users, no credentials, so the same file imports anywhere.

edisyl pack export <pack> --out pack.json    # no --out: bundle to stdout, hash to stderr
edisyl pack inspect pack.json                # what it needs, what it carries
edisyl pack import pack.json --as pack-copy --connection 'Warehouse=postgres://u:p@h:5432/db'
edisyl pack pull acme-domain --out acme.json # fetch a published pack from the registry

What travels, and what doesn’t

• contentHash is the version. The same knowledge hashes identically in every environment, so two bundles are the same pack when their hashes match. Import re-hashes what it receives and refuses a bundle that no longer matches its own hash.

  Danger

  Never hand-edit a bundle file, and never round-trip one through a JSON parser that might reorder keys or normalize numbers; either will change the hash and the import will refuse it.

• Connections are environment state, not pack content. Every connection the bundle names must be supplied: --connection '<name>=<value>', or the EDISYL_PACK_CONN_<NAME> variable that pack inspect prints, unless one of that name already exists locally, or you pass --allow-missing-connections. A value is a DSN, a raw token (for API providers), or an inline JSON config used verbatim.

• Upstream packs aren’t imported transitively by default. Each declared upstream must already exist locally. --upstream '<bundle slug>=<local slug>' binds one to a differently named local pack; --with-references pulls missing upstreams from the registry, upstreams first.

• The guidance’s revision history stays behind: it’s a record of who edited in one org. The imported pack’s PACK.md changelog opens with a single imported revision.

After import

Imports land org-visible and queue index rebuilds in the background. Knowledge search and data resolution read from the index, so a freshly imported pack finds nothing until those finish. --no-reindex skips them: only useful when you’re about to import more bundles right after.

inspect and import also accept a registry ref (slug[@contentHash]) instead of a file path. inspect -j prints a computed summary: hash, upstreams, connections with their env vars, per-knowledge-base counts, not the raw file itself.