Compile, diff, and preview a draft

Validate a shape draft in the Workbench before you materialize it — compile it, inspect, diff against committed, export the schema, and preview the tools it exposes to agents.

A shape draft lives in the Shapes Workbench until you materialize it. Before you commit, run a short validation pass: compile the draft, read its diff against the committed version, and preview what runtime agents and tools will actually see. Materialize last, once the tools look right.

The Workbench MCP server is at https://shapes.pnbr.io/mcp. It accepts a Penumbra API key (pnbr-...) or OAuth. Every tool below is a design-time tool — nothing reaches the runtime until you call shape_workbench_materialize.

The workflow: compile early, preview before you materialize

1. Open a draft

   Open the shape with shape_workbench_open in new, edit, or fork mode. Use inspect mode to look without editing.

   fork creates a separate derived shape, not a new version of the original. Use edit when you want to revise the shape in place.

2. Compile early and often

   Run shape_workbench_compile after meaningful edits. It validates the draft and returns its version hashes, so you catch problems while the draft is cheap to change.

3. Diff against committed

   Run shape_workbench_diff to see exactly what your draft changes relative to the committed shape.

4. Preview the tools

   Run shape_workbench_preview_operating_surface to see what runtime agents and generated tools will see once you materialize.

5. Materialize

   When the diff and the preview both look right, call shape_workbench_materialize to commit the compiled shape to its project.

Compile

shape_workbench_compile validates the draft and returns its version hashes. A clean compile means the model is coherent — types, properties, and relationships hold together — and the draft is ready to diff and preview.

The version hashes let you tell drafts apart and confirm which compiled state you’re looking at. Compile after each round of edits so the hashes stay current.

Tool call

shape_workbench_compile

Compile early. It surfaces structural problems before you diff or preview, when the draft is still easy to revise.

Inspect the draft

shape_workbench_inspect reads the current draft state. Use it to confirm what you’ve authored so far — types, properties, and relationships — before you compile or diff.

Tool call

shape_workbench_inspect

You can also open a shape directly in inspect mode with shape_workbench_open when you want to look at a shape without starting an edit.

Diff the draft against committed

shape_workbench_diff compares your draft against the committed version of the shape. This is the change you’re proposing — read it before you materialize so nothing lands by surprise.

Tool call

shape_workbench_diff

Use the diff to confirm that every change is intentional: types you added, properties you renamed or edited, relationships you added or removed. If the diff shows something you didn’t mean to change, go back and fix the draft before continuing.

Export the schema

shape_workbench_export_schema exports the draft’s schema. Use it when you want the schema artifact in hand — to review the field-level shape of the data, share it, or check it into a downstream consumer.

Tool call

shape_workbench_export_schema

Preview the tools

shape_workbench_preview_operating_surface shows exactly what runtime agents and generated tools will see. A shape compiles into the tools agents use, so this preview is the last check before you commit.

Tool call

shape_workbench_preview_operating_surface

Read this before materializing. It tells you what agents and generated tools will receive once the shape is live, so you can confirm the tool surface matches your intent rather than discovering it after the shape is committed.

Preview is a read of the compilation surface, not the live runtime. It shows what the compiled shape would expose. The shape only reaches runtime once you call shape_workbench_materialize.

Materialize

When the diff is clean and the operating-surface preview matches what you want runtime agents and tools to see, commit the draft with shape_workbench_materialize. This materializes the compiled shape to its project.

Tool call

shape_workbench_materialize

Materialize defaults to a dry run. Nothing is committed until you call it with apply: true and dry_run: false, and it requires a review_note explaining the change. Run the dry run first, read what it would do, then apply.

A tight validation pass

Run this loop on every draft before you commit:

1. Compile

   shape_workbench_compile — validate the draft and get its version hashes.

2. Inspect

   shape_workbench_inspect — confirm the draft is what you authored.

3. Diff

   shape_workbench_diff — confirm every change against committed is intentional.

4. Export schema

   shape_workbench_export_schema — review the schema artifact.

5. Preview the tools

   shape_workbench_preview_operating_surface — confirm the tools agents will get.

6. Materialize

   shape_workbench_materialize — commit when the above all look right.

See /shapes/overview for shape concepts and the /agents/connect guide for connecting the runtime tool surface to agents.