Package & ship a solution

In one line. Package the solution you built once as a recipe, publish it to a Hub, and install it into a fresh project for the next team — without copying a single document or credential. You’ll build. A published Solution: record a checkpoint, snapshot and freeze Project A, publish it to the signed Hub with a setup guide and sample data, install it as Project B, wire Project B’s own credentials and model, and prove it by running a sample invoice end to end. You’ll use. Build: Invoice settlement · Access & roles · Hubs & distribution · Glossary

The setup: you built the invoice solution in Build: Invoice settlement. It works — for one team, in one project. Now Finance West wants it. Then the German subsidiary. Then a customer. Rebuilding it by hand each time is slow, error-prone, and drifts: version three quietly differs from version one. You want to build once and deploy to many.

The load-bearing idea: structure travels; data doesn’t. A package carries agent instructions, schemas, pipeline steps, guard rails and pages — never your documents, your search index, or your model keys. You’ll take Project A (the finished invoice solution) and stand up a working copy in Project B (the next team), passing through a Hub in between. Plan for about 45 minutes; the full publish and install mechanics live in Hubs & distribution.

Two grains of packaging exist, and you’ll see both:

	Solution (whole project)	Object Package (single object)
You ship	The entire invoice project	Just the Invoice Extractor agent
It installs into	a new project (or an existing one, via Install here)	an existing project
Use for	standing up the whole app for a new team or tenant	adding one reusable piece to a project that exists

Steps

Stage 1 — Prepare the source: checkpoint, snapshot, freeze

(Project A)

You never publish a moving target. Lock the configuration first; you’ll describe the package at publish time. These are three separate entries under Studio ▸ Governance ▸ Versioning — there is no switching between tabs.

1. Studio ▸ Governance ▸ Versioning ▸ History — record a checkpoint with a message like “v1.0 invoice solution — ready to ship”. This is your named, rollback-able milestone, and the page then shows what changed, when, and by whom.
2. Studio ▸ Governance ▸ Versioning ▸ Snapshots — take a snapshot of the project’s configuration. Your belt-and-braces copy before you hand the solution to other teams; you can restore from it later.
3. Studio ▸ Governance ▸ Versioning ▸ Freeze — freeze the project so its configuration cannot be changed. The freeze-status chip flips from green Active to red Frozen, and nobody can quietly rewrite the recipe you’re about to publish.

Tip — the shipping rhythm. Record a checkpoint at each milestone, snapshot before anything risky, freeze once a solution is stable and shipping. Lift the freeze only when you genuinely need to change it, then freeze again.

Checkpoint. The freeze chip reads Frozen, and your checkpoint shows on History.

You’ll describe and publish the package in Stage 3 — but first understand exactly what ships, in Stage 2.

Stage 2 — Know what ships, and what the installer has to supply

(conceptual)

When you publish, the platform walks everything the solution needs in order to run and sorts it into three kinds. This is why some fields appear in the publish dialog and others don’t, and why the install asks the receiving team to pick their own objects. Walk your invoice solution piece by piece:

Piece of the invoice solution	Ships?	What happens
Invoice Extractor agent — instructions, persona, sub-agents, skills, guard rails	Yes	Pure configuration. It travels with the package and is re-created in Project B.
The pages your users land on	Yes	Configuration too — shipped as part of the Solution.
The language model the agent uses	No	Belongs to the environment. The package says “I need a GPT-4-class chat model”; it never carries your endpoint or key. Project B must already have one.
Any MCP server the agent calls; the platform version	No	Required at the destination, with its own credentials. The install checks for it and lists it as missing if it isn’t there.
The Invoice collection schema / view the agent reads and writes	The pointer travels, not the data	The package carries a named slot plus a description (“the invoices view”); at install the receiving team picks one of their collections or views.
A Datasheet the agent queries (if your build used one)	Same	A slot plus a description, pointed at Project B’s datasheet at install.
Your invoices, extracted values, search index	No, ever	Data. Stripped at publish. Project B starts empty.
Your model keys and secrets	No, ever	Stripped at publish. Nothing sensitive ships.

Read the table top to bottom and you have the whole model. Configuration travels with the package. Anything that belongs to your environment — a model, a connection, a server — has to already exist at the destination, and the install lists what is missing before you commit. Anything that points at data asks the installer to pick one of their own collections. Structure travels; data doesn’t.

Tip. On the single-agent track, the data-pointer rows are exactly the description textareas in the publish dialog and the dropdowns the installer fills in. On the Solution track, the environment rows surface as the install compatibility check: the requirement rows and the credentials preview the installer sees before committing — see Stage 4.

Stage 3 — Publish to the Hub

(Project A)

Two choices of where the package lands, matching the two grains: publish the whole project (this build’s main path — a signed Solution on the Hub), or publish just the Invoice Extractor agent to Hubs ▸ Agents (covered under production notes below).

1. In Project A, open Studio ▸ Hubs ▸ Solutions and click Publish to Hub. If your platform trusts several hubs, the Target hub picker chooses where it lands. The list of trusted hubs itself is managed by a Platform Admin on Account menu ▸ Administration ▸ Admin ▸ Extensions ▸ Hub Servers.
2. Describe the package in the modal, for a stranger:
   • Name / Version / Category / Summary — e.g. Invoice Processing, 1.0, Finance, one sentence on what each team gets.
   • Listing icon — small PNG/SVG.
   • Overview & setup guide — markdown, with a live preview. This becomes the Solution’s Setup guide tab; write what the installer must do on day one.
   • Sample / demo data — attach a test invoice or two. They ship with the Solution (stripped of secrets) and power Run demo after install.
   • Demo entry point — optionally, the project route “Run demo” should open on.
3. Click Publish to Hub. A live per-stage progress bar runs (framing → packaging → signing → uploading), then the receipt shows exactly what shipped: asset count, bytes, content hash — secrets redacted.

Publishing strips every document, every stored value and every secret, then signs the package so the receiving side can prove it hasn’t been tampered with. It also records which platform version the package was built on, which is what the install-side check compares against. Full mechanics: Hubs & distribution.

Checkpoint. Your Invoice Processing Solution appears under Browse all solutions on the same page, with a Signed pill and v1.0 — no approval is needed to publish; governance kicks in at install and at production promotion (Stage 4).

Stage 4 — Browse, preflight, and install

(Project B)

Now play the receiving team. For the Solution track the install creates the new project for you, so you can start from any context that can reach the Hub — the workspace’s Import from Hub entry opens the same marketplace without a project.

1. Open Studio ▸ Hubs ▸ Solutions. The marketplace opens on a collapsible Featured strip, then a split browser: search or filter the list on the left, and select Invoice Processing to load its detail pane.
2. Read before you install: the Overview tab (summary + the environment promotion ladder — which version is live where), the Setup guide tab (your Stage 3 markdown), Version history, and Samples.
3. Preflight. In Overview, click Check install compatibility. You get: signature ✓, each requirement marked met or missing (the platform-version row is real — a Solution built on a newer ring fails preflight on an older one), and the credentials preview: “you’ll need to configure N credentials”, with counts and where (connection keys, script secrets) but never values. The missing rows are exactly the environment capabilities from Stage 2 — fix them before installing.
4. Install. Click Install as new, name the project (e.g. Invoice Processing — Finance West), and Confirm & Import. A live per-stage progress bar runs while the platform verifies the signature, unpacks the modules, and creates the project — Invoice collection schema, extractor agent, skills, guard rails, the Four-Eyes lifecycle, pages, all re-created fresh. No invoices come across; the new project starts empty of data. (Inside an existing project, Install here drops the modules into it instead.)

Governance on this path. Some installs are approval-required — the result panel then offers a one-click Approve & install, keeping the gate with the platform, not the package. Shipping a Solution up the ladder is governed harder still: promoting a version to the next environment executes immediately, but Request production release queues for approval on the Release Approvals tab of Account menu ▸ Administration ▸ Admin ▸ Extensions ▸ Hub Servers, where a Super Admin signs it off — and the target hub is fixed at request time, so if the destination changes before approval, the approval is refused. Details: Hubs & distribution.

Can’t see Hubs at all? The Hubs chip sits on the top bar while you are in Studio, next to Exit Studio. A workspace can hide it, and then there is no chip — ask your administrator to turn it on.

Stage 5 — Wire the destination: credentials and data pointers

The install re-created your collections and modules, but the environment pieces still need Project B’s own — exactly what the Stage 4 credentials preview promised.

On the Solution track (this build): the Configure imported credentials dialog opens automatically after install. Bind Project B’s language model and key (not yours — it never shipped) and fill the connection keys and script secrets the preview counted; you can start with demo values and add real ones later. Two extras land with the project: the sample files + setup guide appear in a Solution Samples folder in the project’s Drive (one click from the result panel), and Run demo with sample data pushes the shipped samples through the normal intake so you can watch the solution work before touching real data.

On the single-agent track (one agent imported from Hubs ▸ Agents), a configuration dialog opens instead — for each slot, pick a local object:

+- Import: Invoice Extractor -------------------------------[x]-+
| This needs you to map the following to your project:          |
|                                                               |
| Language model * [ Select a model  v ]                        |
|   "any GPT-4-class chat model"        <- the publisher's note |
|                                                               |
| View *           [ Select a view   v ]                        |
|   "the invoices view"                                         |
|                                                               |
| Datasheet *      [ Select a datasheet v ]                     |
|   "invoice line-items table"                                  |
|                                            [ Import ]         |
+---------------------------------------------------------------+

1. Language model (required) — pick Project B’s GPT-4-class model. This is the environment capability resolving locally: Project B’s key, not yours.
2. View (required) — pick the invoices view in Project B (or the one the Solution just created). This is the pointer that binds the agent to this project’s data.
3. Datasheet (required, if the agent referenced one) — pick Project B’s. Each field shows the description you wrote at publish time, so you know exactly what to choose.
4. Click Import. The platform re-creates the configuration and points the slots at the local objects you picked.

Checkpoint. On the Solution track the result panel reads “✓ Created project …” with your samples materialized; on the single-agent track you get an “…imported successfully” toast. Either way, the installed agent appears in Project B under Studio ▸ Agents ▸ Agent Toolkit ▸ Agents.

Stage 6 — Prove it: a plain project object that runs

(Project B)

The reassuring payoff: an installed object is just a normal project object. There is no special “imported” mode to learn.

1. In Project B, open Studio ▸ Agents ▸ Agent Toolkit ▸ Agents. The Invoice Extractor is there like any agent you’d build by hand — open it; every reference resolved to this project’s model, view, and datasheet, not Project A’s.
2. Confirm the Invoice collection, its schema and labels, the Four-Eyes lifecycle, and the pages came across.

Then the real proof that structure travelled and the binding works — run a sample invoice end to end:

3. In Project B’s consumer app, open the Invoice collection (App ▸ Documents) — it’s empty. Good: no data shipped.
4. Upload a single sample invoice PDF (reuse the test invoice from Build: Invoice settlement).
5. Watch the live progress chip: the installed Invoice Extractor, running on Project B’s bound model, extracts the fields — total, vendor, dates — exactly as it did in Project A.
6. Follow the invoice through the Four-Eyes lifecycle (Intake → AI Processing → AI Recommendation → L1 Review → L2 Approval), reviewing and approving as before.
7. The invoice reaches Approved in Project B.

You moved a complete solution between projects without copying a single invoice. The recipe travelled; the data started fresh.

If extraction fails or the agent errors: it’s almost always an environment piece that never resolved — Project B doesn’t have a matching language model, or you bound the wrong one. Re-open the agent and check the model picker (or re-open the credentials dialog). The Stage 4 compatibility check and credentials preview would have flagged this before install — run it again to see which row is missing. Empty pickers in the import dialog usually mean the target object — a view, a datasheet — doesn’t exist yet in Project B: create it first, then re-import.

Make it production-worthy

• Make Stage 1 a habit, not a one-off. Before each re-publish: record a checkpoint on History, take a Snapshot for safety, and Freeze so the published recipe can’t drift. To ship v1.1: lift the freeze → edit → re-checkpoint → re-snapshot → re-freeze → Publish to Hub again, choosing Publish the next version. Every project installed from the Hub then shows an update available banner: upgrade in place (keeps documents, queues and history; auto-saves a rollback snapshot) or install side-by-side — and the ⋯ ▸ Roll back menu returns a project to any prior published version.
• Ship a single agent when the team already has a project. Sometimes the next team just wants the extractor agent, not a whole new app. In Project A, open the Invoice Extractor in Studio ▸ Agents ▸ Agent Toolkit ▸ Agents and use its ⋮ ▸ Publish: logo, Name, Description, Tags, plus the description textareas for each thing the installer must supply (the model) or point at (the view, datasheet, collection). Publish lands it in Studio ▸ Hubs ▸ Agents; in an existing Project B, open that tab, select it, Import, and fill the slots as in Stage 5. The agent drops in as a plain agent — no new project created.
• Govern both ends. Freeze Project A’s configuration before publishing, so the published recipe is the blessed one; ship across environments up the promotion ladder — promoting to the next environment is immediate, Request production release waits for a Super Admin’s approval on the Release Approvals tab of Account menu ▸ Administration ▸ Admin ▸ Extensions ▸ Hub Servers, with the target hub fixed at request time (Hubs & distribution). And set up access in Project B after install: the Solution carries the shape of the lifecycle and its stage gates, but you assign the L1-Reviewer and L2-Approver personas to the new team’s actual people on Studio ▸ Governance ▸ Users & Access (Access & roles). Personas travel as shape; who holds them does not, and shouldn’t.

What to keep from this build: structure travels, data doesn’t — a package is a recipe, not a copy. Configuration ships by value; anything that belongs to the destination environment has to already be there; anything that points at data is chosen by the installer. Hold those three in your head and you can predict the whole publish-and-install experience. Checkpoint, snapshot, freeze before you publish; assign personas in the destination after you install. The worked builds taught you to build solutions — this one taught you to ship any of them: package once, install everywhere, with nothing sensitive leaving the building.

Where to go next

• Hubs & distribution — the full publish / Hub / install mechanics and dialogs.
• Build: Invoice settlement — the solution you just shipped, if you haven’t built it yet.
• The Agentic System pattern — when what you’re shipping is a whole domain brain, not one workflow.