---
title: "Surfaces and records"
url: https://developers.dagio.ai/surfaces/
---

# Surfaces and records

   
                             
                                                                 
                
             
         
   

## A record that stays open

A Surface is content or a record with a stable identity. The North Studio record brings information, notes and links into a screen you can read and edit. It does not require a large modal form for every change.

The Model determines which Fields appear in the main content and which belong in settings. Long text appears as a section with a heading and editable text below it. Choices, dates and booleans retain controls suited to their values.

| Element  | Expected content                | Interaction                              |
| -------- | ------------------------------- | ---------------------------------------- |
| Identity | Title, subtitle, avatar or icon | Recognize the record immediately         |
| Sections | Fields, text or Query results   | Read and edit in context                 |
| Settings | Configuration Fields            | Open a focused form                      |
| Actions  | Operations allowed in context   | Prepare a proposal, archive              |
| Links    | Relation groups                 | Open related objects or full collections |

In the local Builder Data record, Fields appear in the right sidebar alongside relations. Document content keeps the main area. Editing a Field retains its validation and automatic saving. On narrow screens, the sidebar follows the content.

## Extension Surfaces and linked data

Install an extension to add its illustrated templates to **New Surface** in compatible Spaces.
A GridCraft workbook is created in a Content Space and opens inside its Surface. Its identity,
links, permissions and history stay with that Surface.

Open the Surface **Data** panel to add an authorized Data Space and choose its Fields. **Refresh**
reads the source again and replaces the linked table's imported cells. Cell edits do not write
back to the source. **Unlink** removes the connection while keeping the cells. Saving and restoring
history keep the workbook and its connections together. Opening or cancelling source selection
is not an edit.

Each refresh checks current source access. An existing saved capture follows its Surface's access
rights; it does not grant permission to read the source again. The assistant uses the same access
checks and the extension's native content commands, including when the editor is closed.
Query Data Sources require their native provider and are unavailable until it is supplied.

Extension preferences appear in **Settings → Extensions**. GridCraft's theme, language, formula bar
and AutoComplete are user preferences; workbook calculation settings remain with the workbook.

## Design an application in the local Builder

Open **Builder** from the application to configure the current context. **Model**, **Spaces**,
**Workmaps**, **Chat Views** and **Links** keep their own navigation. Cards open focused settings; the application
remains visible while you design it.

Changes save as a design draft. While the Builder is open, the application previews that draft.
Closing returns to the published definition; reopening resumes the draft. **Publish** reviews and
applies it to this application. Publishing a reusable version in the private catalogue is a separate
operation. Existing records and Surface history are retained.

Saving includes the full Model and its Instructions, with a total JSON request budget of 1 MiB.
Field and Surface limits still apply. If a save fails, keep the Builder open and use **Recheck draft**
to retry the retained changes after resolving the error.

In **Model → Application settings**, choose **Application icon** to open the icon library across the settings area. Filter by category, search and use the numbered pages. Descriptions use the shared multiline field with a resize handle below its bottom border.

The Model and Space layouts open **Settings →** from the same header row. **Add space** keeps its
header while you switch between **Create a space**, **Marketplace**, a Pro **Private Repository**,
and the repositories of Business organizations you can access. Use **Search spaces...** and the
Data, Knowledge and Content categories to filter the catalogue. These choices retain your account
and organization permissions.

**Model JSON**, **Chat View JSON** and custom Workmap layout JSON open an editor filling the Builder content area with syntax highlighting, folding, search, completion and schema diagnostics. **Format JSON** formats explicitly. Domain errors still block admission; return to the Builder after correcting them. Editing a draft does not publish the Model.

In **Workmaps → Steps → Definition**, **Completion criteria** uses one rich Surface editor for
headings, lists, formatting and links. The criteria are captured when work is created and remain
readable in its details and by the assistant. Editing the Model affects future work. Criteria guide
completion; they do not certify it automatically.

Space Layout is the single entry point for **Space Settings**, **Space Fields**, **Space Views**
and **Space Instructions**; each page returns to the layout without a second set of tabs. The
**Instructions** button sits on the right of the layout header. Fields retain typed defaults.
Fields use compact rows and a compact editor with **Back to Fields**. The icon library fills the
Builder content area in Field and Space settings as it does in Model settings. Editable Instructions
start with about twelve text lines, inner padding and a formatting toolbar joined to the field border.
An Action has illustrated Definition, Instructions, Chat View and Placement cards, with **Delete**
below the four cards. Deletion changes the draft and takes effect when you publish. Its form and custom JSON share an
interactive preview. Workmap steps can contain substeps and their own Actions.

In a step, **Work documentation** starts with an empty list. **Add Templates** opens the template
selector: create a template, browse the Marketplace, use a Pro Private Repository or an accessible
Business Organization repository. **Custom template** starts a Page, Slide or Board. Each template
opens **Definition**, **Instructions**, **Fields** and **Contents**. Fields use the same management
controls as Space Fields. Contents opens the Surface editor with **View**, **Edit** and **Layout**.
Reusable templates cannot carry private live media or component bindings.

Starting work creates an independent Surface for each configured template, including its own Field
definitions, default values and instructions. Edit its values in the **Fields** details panel. More
Surfaces can be added during work, using an explicitly selected template or a blank Surface. Model
changes affect future work; existing work keeps its captured templates. Deleting a template asks
for confirmation and retains Surfaces already created from it. The assistant reads a Surface's
Fields and instructions when it opens that Surface.

An open Workmap step has **Delete** below its cards. Confirmation removes the step, its substeps
and Actions used only by those steps from the draft. Keep at least one top-level step in each path.
Publishing the change affects future work; existing work retains its captured steps and documents.

**Chat Views** lists reusable conversation cards. The **Add Chat View** button beside the title opens a template
selector: **Information card**, **Comparison**, **Response form** or **Custom** for an empty card.
Choose a template, then edit its layout, rich content and questions. Describe when the assistant should
use it. An Action's **Chat View** can reference one of these cards or keep its own view. The preview
uses the same components as the application and MCP App.

During a conversation, the assistant can choose a declared card or compose a new card from the
available components. Display cards can contain sections, tables and local controls; response forms
wait for the user's answer. Cards display data supplied to them: external information requires a
connected data tool. Submitting an answer does not approve a business operation. The local app owns
its own threads; conversations in ChatGPT or another MCP host stay with that host. Remote hosting
and live host qualification remain separate from the local Builder.

The local conversation runtime supplies Surface instructions and its available tools at each
step. With a connected account and model that permit web search, the assistant can retrieve current
information and display it in a card. Source links remain in the saved conversation. If the
provider refuses search, the chat reports that limitation. A card's layout does not grant data access.

For a question about your work, the local assistant can discover the current application or personal
Space, then read its explicit instructions and relevant Knowledge entries. It loads those documents
when needed. The Surface EN/FR system manual is included with the application; users have nothing
to install. In development, enable **Developer mode** and **System Knowledge view** in **Settings → Developer**, then
choose **Open System Knowledge**. It uses the same Knowledge Space view, in read-only mode. The local
chat and MCP assistants can search and read the same manual on demand. MCP connections also receive
minimal Surface navigation instructions. The manual
describes product usage; available tools and permissions still determine what an assistant can do.

Linked items use exact spaces, reciprocal labels and cardinalities. Cross-application Links map
exact Fields and take effect when saved.

In **Application settings**, enabling **Working guide** creates a Knowledge named **Working Guide**.
It stays visible in the application's Spaces, where you can rename it and edit its instructions and
notes. Keep your conventions, methods and quality criteria there. Enabling **Application memory**
creates a separate internal Knowledge; it appears in Spaces only in development. The assistant uses
it for concise, reusable lessons and explicit corrections, with evidence and an uncertainty status.
It searches before writing, consolidates existing lessons and archives obsolete ones. Memory must
not contain secrets, raw chat transcripts or transient execution state. Your Working Guide takes
precedence over learned memory; neither grants permissions.

The chat and MCP assistants discover these roles and load only relevant instructions and entries
when needed. A greeting does not load their contents. Disabling a role retains its Space and notes;
disabling memory also blocks its dedicated read/write tools. Re-enabling reuses the same Space.
Publish Builder changes to apply them to the application. Builder AI assistance still requires its
compatible conversation host.

## Collection views in the local Application Builder

The Model can declare Table, Kanban, Calendar, Timeline, Gantt and a Canvas of record cards for the
same Data collection. Configure the view names and Field mappings in **Spaces → Data → Views**.
Kanban uses a choice Field; Calendar uses a date; Timeline uses start and end dates. Each card or
scheduled item opens the original record. Filters and search retain the same collection Query.

Kanban moves update the record through its version-checked writer. Gantt requires explicit duration,
progress and milestone mappings as well as start/end dates. Its finish-to-start dependencies and
critical path use a complete bounded Query, and missing schedule values remain visible rather than
becoming zero. Canvas arranges the current page's records and their related Links; **Save layout**
retains the shared arrangement. This collection view is distinct from native Canvas drawing content.

Universal Surface content is built into Data, Knowledge and Content; there is no Canvas activation
switch in Model settings. **Add Surface** creates the same composition for text, shapes, images and
pages. Document is a rich text component inside that composition. Models retain their object and
resource restrictions. Saving, protected objects and revision restoration use the shared content
lifecycle. Images retain immutable references; missing qualified fonts or image sources are reported.
Reusable component sources, visual data, native export and remote hosting are separate integrations.

Page views identify their bounded coverage. Gantt refuses an incomplete or oversized capture instead
of displaying a partial critical path. These additions are available in the local Builder; remote
MCP App integration is separate.

## Contextual Actions in the local Builder

In **Spaces → Actions**, declare a name, workspace and instructions for AI. Saved Data
records, Content/Knowledge entries and Workmap details expose the corresponding Actions menu.
**Prepare action** reads the saved target and exact Model revision. Save pending changes first.
Preparation does not execute a Flow, call a paid model or change progress. The same preparation is
available through MCP; actual modifications retain the existing permission and revision checks.
Sending from this local UI to the ChatGPT conversation requires the separate MCP App connection.

The same declaration chooses whole-item, selected-text, single-row or multiple-row placements.
Text Actions use the saved document selection; Data selections include up to 100 exact record
revisions. Pending edits must be saved first. Row checkboxes preserve normal record navigation.
An optional interactive view declares text or choice inputs and previews them in the Builder.
MCP `action_view` opens that view in a compatible conversation host; `action_respond` validates
its response before continuation. Validation does not modify business data or advance a Workmap.
Real ChatGPT host delivery and remote authentication remain separate from local preview tests.

## Edit without losing context

Select a value and make your change. Field validation applies at the point required by the operation. An input being edited remains distinct from a remote update. When another change affects that value, the interface lets you inspect the conflict rather than erase your input.

Before archiving, deleting or restoring content, review the proposed effects and affected descendants. The receipt distinguishes changed content from items left unchanged. These operations preserve references and history; they are not a physical data purge. A restore retains the reference to its original operation, available in details.

## Classify with Tags

The **Tags** panel distinguishes the whole content from a declared section. Save content changes
before preparing an addition or removal. Read-only access lets you inspect Tags and their history,
not change them. To reuse a Tag, select it from an accessible resource, open the destination, then
review the proposal.

A confirmation with an unknown result resumes as the same request. If the Tag was recorded but
refreshing fails, reopen the panel to read its state without repeating the change. Changing the
language preserves your labels, input and selected section; exact references remain available in
details.

## Read related information

The side panel groups relations by type. North Studio can show **Quotes**, **Related work** and **Documents**. Each group displays a bounded preview; **View all** opens the complete collection with its context and filters.

## Example

The **Client needs** section contains editable text. **Status** offers Prospect, Active or Inactive. **Settings** holds follow-up options. The **Quotes** panel displays related proposals. All of these elements describe the same record.

<!-- surface-examples:start -->

## Applied examples : Visible notes, accessible settings

Place follow-up on the Surface and email in settings, while retaining the same Fields.

### Configuration

Fragment placed in `presentation.recordProfiles[].detail.sections`. [Properties and accepted values](https://developers.dagio.ai/reference/workspace-record-profile/).

```json
[
  {
    "kind": "fields",
    "key": "follow-up",
    "label": "Client follow-up",
    "fieldPaths": [
      "fields/notes",
      "fields/status"
    ]
  }
]
```

### Variation and connection

Fragment placed in `presentation.recordProfiles[].detail.settings`. [Properties and accepted values](https://developers.dagio.ai/reference/workspace-record-profile/).

```json
{
  "fieldPaths": [
    "fields/email"
  ]
}
```

### UI layout example

The illustrative layout below places this configuration in the Clients/Quotes app. Insert each fragment at the stated location, with Field, Query and Action references matching the Model declarations.

1. Client identity
2. Notes and follow-up
3. Settings
4. Linked quotes

<!-- surface-examples:end -->