Building Creation Wizard

The Building Creation Wizard is the seven-step modal that turns a configuration into a named, reusable building kind you can place in any project — with its own roster, sprite, settings, and UI mode.

How It Works

The Wizard is a two-pane dialog: a step form on the left and a Live Preview panel on the right with an isometric render of the building, a summary table, and a collapsible TOML preview that updates as you type. A step indicator across the top lets you jump between steps; the footer has Back, Next, and Create.

All seven steps must pass validation before Create succeeds. The indicator shows a warning dot on any step with unresolved errors. Pressing Close with unsaved changes prompts for confirmation before discarding.

When you click Create, the Wizard writes a TOML file to disk — the source of truth for your custom kind. Place the kind from the Building Type Drawer like any built-in, and every instance inherits the defaults you set here.

Open the Wizard from the Building Type Drawer’s “Create New” entry, or from a GenericBuilding when you want to save a working prototype as a permanent kind.

1. Identity

Step one is where you give the building its name, description, icon, and color.

Kind — A PascalCase identifier (ResearchLab, DesignStudio, Helpdesk). This is the canonical name the system uses internally and the slug for the building’s folder on disk. The Wizard checks the kind against existing builtins and saved custom kinds in the background; a duplicate or invalid kind shows an inline error. The Display name field below shows the humanized version that will appear in the UI.
Description — A short paragraph (up to 500 characters) describing what the building is for. This shows up in the Building Type Drawer and the building’s window.
Icon — An emoji picker. Pick something recognizable; the default placeholder is a construction emoji.
Color — A palette swatch used for the building’s accent color on the map and in its window header.

Pick the kind first. Many later steps depend on it — the folder slug derives from it, the live preview only renders once a kind is set, and validation gates rely on it.

2. Size & Layout

Step two sizes the building on the map grid and sets placement limits.

Quick Presets — Square footprints from 2×2 up to 5×5.
Width and Height — Independent dimensions from 1 to 8 if you want a non-square building.
Only one building of this type per project — A toggle that locks the building to a single instance per territory. Built-in HQ uses this constraint; use it for any kind that wouldn’t make sense to have two of.
Max instances — A numeric cap (0 means unlimited). Disabled when the “only one” toggle is on, since the cap is implicitly 1.

The live preview updates immediately as you change the footprint so you can see how the building will sit on the map.

3. Agents

Step three is the team-building step. You can add up to 6 agents per building.

For each agent slot you configure:

Kind — A human label for the agent’s role. This is what appears under their portrait in the Building Window. Examples: “Planner,” “Lead Designer,” “Customer Support.”
Role — A snake_case identifier the system uses internally (planner, lead_designer).
Model — Optional model override. Leave blank to inherit the per-role default from Settings → Agent Defaults.
Instruction file — The markdown file that holds the agent’s starting system prompt. The Wizard creates the file for you in the building’s folder.
Position — A tile coordinate on the building’s grid. The preview panel becomes interactive on this step: click an agent in the form, then click an empty tile in the preview to place them. The Wizard warns if you try to drop two agents on the same tile.
Skills — A list of slash commands the agent can invoke. See Skills (Slash Commands).
Sprite — Optional per-agent sprite. Falls back to a generic agent sprite if unset.

Designing the team here is the most important step. The Wizard accepts up to six slots, but you don’t need to fill them all — many useful custom buildings have just two or three agents.

4. Visuals

Step four controls the building’s sprite, scale, position, and animation.

Sprite source — A segmented control with three options:
- None — No sprite. The building renders as a plain colored block.
- Library — Pick a sprite from Viberia’s built-in sprite library. Library sprites come with their own metadata, so scale, height offset, and animation become read-only when one is selected.
- Custom — Import a PNG sprite sheet from disk. The custom-sprite import modal lets you configure frame layout and animation as part of the import.
Sprite scale — A slider from 0.10 to 2.00. Adjust if the chosen sprite renders too large or too small for the footprint.
Height offset — Vertical offset in pixels, −50 to +50. Use this to lift a sprite off the ground or sink it into the tile for visual fit.
Animation — For custom sprites, an expandable section with frame count, FPS, layout (strip or grid), columns, and a ping-pong toggle. Library sprites carry their animation metadata with them, so this section becomes informational only.

The live preview reflects every change as you make it — including animated playback for sprites with multi-frame metadata.

5. Additional Settings

Step five is where the building gets its own configuration surface. There are two sections:

Settings fields — User-configurable values that show up in the Building Window after the building is placed. Each field has:

A key (snake_case, used as the storage key)
A label and description
A type: text, secret, url, number, boolean, or select
Optional required, placeholder, default, group, and (for select) options
Optional min, max, step (for numbers)

The step ships with three preset shortcuts: API Key (secret, required), Base URL (url), and Enable Feature (boolean toggle). These are common enough that they’re one-click.

MCP servers — Templates for MCP servers that the building installs by default. Each entry has a name, display name, transport (stdio or sse), command/args/url, and environment variables. Env values can reference settings keys via $setting:my_api_key — so a building can prompt the user for an API key once in its settings and have that key wired into every MCP server template that needs it.

Both lists are optional. A building with no settings fields and no MCP templates is still valid; the Wizard simply skips those sections in the generated TOML.

6. UI Mode (Standard vs Webpage)

Step six picks the building’s primary UI surface.

Standard Mode is the default and the recommended choice. The Building Window shows the familiar sections: agent portraits, prompt editor, skills picker, MCP list, additional directories, and a how-to-use note. Every built-in building except Linear uses this mode.

Webpage Mode replaces the standard content with an embedded webview pointing at a URL. The agents you configured in step three still exist and still have their own chat windows, but the webview is the primary surface. Webpage Mode requires that you’ve defined at least one settings field of type url in step five — that field is what the building reads to know which page to embed. If you flip to Webpage Mode without a URL field, the Wizard warns and links you back to step five.

Webpage Mode has two sub-options when active:

URL field — A dropdown of every URL-typed settings field you’ve defined; pick the one the building should use.
Show URL bar in webpage mode — Toggles a small URL bar across the top of the embedded webview, useful when you want users to be able to navigate inside the embed.

This step also has an optional Starter README text area. Whatever you type here is written to the building’s workspace folder as a markdown file when the building is created. Use it for a quick “Welcome — this building does X” primer that agents and users will see when they open the workspace folder.

7. Review

Step seven is a verification step before saving.

The top of the page is a Summary section — one card per earlier step, each one a button that takes you back to that step if you want to fix something. The cards show:

Identity (kind, icon, color, description)
Size & limits (footprint and max instances)
Team (agent kinds, positions, skill counts)
Visual (sprite, scale, offset)
Settings (field count and types)
MCP servers (count and transport)
UI mode (Standard or Webpage; URL field if applicable)
Target directory where the TOML will be written

If any step still has validation errors, a red Validation issues panel lists them with a Go button per item, jumping you back to the offending step.

Below the summary is the Generated TOML section — a preview of the actual file the Wizard will write. Click Edit TOML to switch into a manual edit mode for advanced tweaks the Wizard’s form doesn’t expose. Apply your changes and the Wizard parses them back into form state (with a warning if anything couldn’t be round-tripped).

The review step also has an AI Assistant input. Type a natural-language request — “set building size to 4×4 and rename the agent to Planner” — and the assistant rewrites the TOML for you. Each AI change is recorded on an undo stack (up to 20 entries) so you can roll back if it goes wrong.

When everything passes, click Create. The Wizard writes the TOML, the new kind appears in the Building Type Drawer, and you can place it in any project.

Where the TOML lives and how to edit it

The Wizard writes building definitions to ~/.pitauri/buildings/<slug>/, where <slug> is the folder name derived from your kind. Each folder contains:

A building.toml file — the building’s definition.
An agents/ directory — one markdown file per agent for its system prompt.
An optional README.md if you provided a Starter README in step six.

The TOML file is the source of truth. You can edit it by hand in any text editor — or in the Toolbox’s Markdown Editor — when you need to adjust something the Wizard doesn’t expose. Common reasons: long agent prompts authored elsewhere, fine-tuning MCP env templates, or adding a settings field variant that has no preset.

After editing, restart Viberia (or reload from the Building Type Drawer) to pick up the change. If you break the TOML schema, the building fails to load and you’ll see an error pointing at the file — repair it or re-run the Wizard to regenerate a clean version.

You can also re-open the Wizard for an existing kind by selecting it from the Building Type Drawer and choosing “Edit.” The Wizard parses the on-disk TOML back into form state so you can pick up where you left off.

Use Cases

Save a working prototype. Configure a GenericBuilding on the fly, then promote the same shape into a reusable kind once the team works.
Wrap an internal tool. Author a Webpage Mode building pointing at a Grafana dashboard or Notion workspace, with agents alongside that can act against what you’re seeing.
Build a domain-specific helper. A “Helpdesk” with a Triager and Responder; a “ResearchLab” with a Searcher and Summarizer.
Standardize team templates. Author one “FeatureSquad” kind and drop instances into every product project so every team starts identical.
Bundle MCP integrations. Define MCP templates plus the settings fields they need, so users of the kind get a working integration with a single field to fill in.

Limitations

Six agents per building is a hard cap in step three. If you need more, split into two buildings.
PascalCase kinds only. Kinds with spaces, hyphens, or lowercase first letters won’t validate.
Webpage Mode requires a URL settings field. You must define one in step five before switching the mode in step six; the Wizard surfaces an inline warning otherwise.
Editing the kind doesn’t update existing instances. Buildings you’ve already placed keep whatever per-instance settings they had at placement time. To pick up new defaults across the board, you’ll need to re-place or manually update each instance.
TOML round-trip is best-effort. Most fields parse cleanly, but unusual hand-edits (comments in unexpected places, unsupported field types) can trigger a warning that the form state is incomplete. The TOML on disk is still the source of truth.
Sharing is manual. Custom kinds live in files on your machine. To share a kind with a teammate, send them the building folder; Viberia has no built-in registry for swapping kinds across users.