> ## Documentation Index
> Fetch the complete documentation index at: https://docs.surfacearea.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Author worlds from chat

> The in-dashboard Assistant can author a connector, validate it, publish it, build a world from it, import data, and open a session - without you leaving the chat.

The Assistant is a chat agent built into the Surface Area dashboard. Describe the system you want mirrored and it writes the connector, validates it against the real compiler, publishes it, builds a world from it, puts data in, and opens a session you can call.

The Assistant drives the same surfaces the `gateway` command-line tool drives. A template that does not compile is refused in chat exactly as it is refused in a terminal.

## The path the Assistant follows

<Steps>
  <Step title="It reads the connector-authoring skill first">
    Before writing anything, the Assistant loads the connector-schema-authoring skill. The skill holds the instructions for the `gateway-world/1` contract: what belongs in `world.json` (entities, fields, keys, relationships), what belongs in `connector.toml` (the vendor connection, authentication by environment-variable name, the operations the world serves), how handlers work, how to record provenance, and what "done" means.

    The files it writes therefore match the conventions the compiler enforces.
  </Step>

  <Step title="It validates until the contract holds">
    The Assistant compiles its draft with the trusted schema runtime -- the same code that runs on a publish -- and gets back every error with the path it occurred at. Nothing is written while it does. It loops on validation until the template compiles, then reports the summary: vendor, entities, operations, tools.

    A template that fails validation never reaches your project.
  </Step>

  <Step title="It publishes the connector">
    A valid template is published to the hub as a commit. A new slug creates the connector; an existing slug commits a revision against the head you based the edit on, so a head that moved is refused rather than overwritten.

    Publishing is gated: the Assistant needs hub write access and the matching autonomy setting, or it asks you to confirm before it writes.
  </Step>

  <Step title="It builds a world from the connector">
    `init_world_from_connector` makes a world in your project from the connector's head commit, pinned by repository, commit, and digest. The platform initializes and builds it and returns a request id plus the world's container id; the world serves the vendor's routes as soon as its first version is `READY`.

    Pass `worldSlug` for an exact slug. Left out, the platform derives one from the display name and appends a random tail, so two worlds named the same thing never collide.

    <Info>
      Building a world needs the world-provisioning permission and the
      `provisionWorlds` autonomy setting, or your confirmation on the spot. Give the Assistant your own
      request id for a build and a retry resumes it instead of creating a second
      world.
    </Info>
  </Step>

  <Step title="It imports the data">
    Rows go in through the world's own gate, either inline or from a file. Every row is checked against the contract, and a row that breaks it is refused with the field named -- nothing is written when that happens.

    Ask for a dry run first. `dryRun` reports every refusal without writing anything, so a vendor export that disagrees with the contract shows up before you commit a version. A successful import lands as a new `READY` version with per-entity counts.
  </Step>

  <Step title="It opens a session">
    The Assistant opens a live session against the world's head version and returns the URLs: the tool surface, and the `api`, `ui`, and `browser` surfaces where the world declares them. Point your agent at the API URL.

    A session holds a running container while open, so close it when you are done.
  </Step>
</Steps>

## What to ask it

* "Mirror our billing vendor's REST API as a connector, then build a world from it."
* "Validate this connector template and tell me what does not compile."
* "Build a world from the `acme-crm` connector and call it `acme-crm-staging`."
* "Import these rows into `acme-crm-staging`, but dry-run them first."
* "Open a session on `acme-crm-staging` with the API surface."

## How the Assistant behaves

**It plans before it commits.** The Assistant shows you the files it wrote and the validation verdict before anything is published, and every provisioning or destructive step asks for confirmation unless you have granted it the matching autonomy.

**It works inside one project.** Everything it can see and everything it writes belongs to the project you opened it from.

**Your conversations are saved.** A **Past Conversations** list holds recent sessions. Reopen one to pick up where you left off with its full history intact.

<Info>
  A coding agent in your own editor can do the same work over the platform's MCP
  server, with the same tools: `get_connector_authoring_skill`,
  `validate_connector_template`, `publish_connector`,
  `init_world_from_connector`, `import_world_data`, and `open_world_session`. See
  [MCP Server](/mcp).
</Info>

## Related pages

* [Getting started with worlds](/worlds/getting-started) is the same path in a terminal.
* [Mock any vendor API](/worlds/custom-connections) covers `connector.toml`, capture, handlers, and conformance by hand.
* [Put data in a world](/worlds/data) covers the rows file, import modes, and live seeding.
* [What makes a world good](/worlds/good-world) is the bar the Assistant's output should clear.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.