Bundles: import and export

A bundle is how content moves between browsers and machines in the local-only MVP.

What is in the zip

A .guidepost.zip file is an ordinary zip. Export names it <appKey>.guidepost.zip.

Entry	Contents
bundle.json	schemaVersion, exportedAt, sourceMode (local or remote), apps, segments, items
assets/<sha256>	Uploaded images, named by content hash. Only files that an exported item uses are included. A bundle with no uploads has no assets/ folder
signature.json	Optional. The studio does not write or check it

The field-by-field layout is in the content schema reference.

Included: the latest saved draft of every item in the application (all nine kinds, including documentation links), the application record (its sites, theme variables, help bubble and announcement settings), the segments, and the uploaded files those items use.

Not included: anyone's progress or dismissals, earlier published versions, archived items, site access (the browser permission for each origin), and content from other applications.

Bundles exported before the product rename end in .waypoint.zip. They import exactly like current ones: the importer reads the content, not the file name.

Export

In the studio, Bundles, Export .guidepost.zip. The file is saved by the browser as a download.

Import

Bundles, Import, then choose a .guidepost.zip (or .waypoint.zip) file. The file is validated against the schema before anything is written. When the bundle belongs to a different application, the studio switches to it. The studio always uses the new-version conflict mode, and ends with a sentence that says what happened, for example "Imported 5 items into application "claims". 2 were drafts and stay drafts until you publish them."

Situation	Result
The id is new to this profile	Added with the bundle's status and version. A published item is live straight away
The id already exists and the bundle copy is published	Becomes the next published version. The earlier versions stay in the history
The id already exists and the bundle copy is a draft	Replaces your draft. What is published stays as it was
The file is not a bundle, is damaged, is from a newer Guidepost, or fails validation	A plain message, and nothing is written

The importer also supports skip and overwrite modes (used by tests and tooling). Missing references are items that point at content ids that are not in the bundle.

Worked example

Moving a tour from a laptop to a colleague:

1. On the laptop, set the application key claims, press Export. You get claims.guidepost.zip.
2. Send it. The colleague installs the extension, turns on author mode, sets the same key and the site origin.
3. Import. Content arrives as new versions. They review in the studio and publish.

Gotchas

• Import brings content, not site access. The recipient still grants the origin.
• Items from older bundles are migrated on read (schema version 1 to 2 adds tags and a default locale). Anything that fails schema validation is rejected before it is written.
• Drafts stay drafts. Export takes the latest saved draft, not the published version. An item you published and then edited exports as a draft, so on the other side it is not live until someone publishes it. Publish what you want live before you export. Imported drafts start at version 0, so their first publish is v1.
• Exports include drafts, and content with a locator that matches your internal URLs. Treat a bundle like source: review before sharing outside your organisation.
• Progress is not part of a bundle.