---
title: "Introduction"
url: https://developers.dagio.ai/introduction/
---

# Introduction

   
                     
                                                            
                    
              
         
   

## Build around the work

Surface brings together knowledge, data and the work needed to produce a result. Compose an app from Workspaces, records and views, then connect the information and Actions that move your business forward. AI works in the same context, using your permissions and producing results you can review.

This documentation follows a business that manages clients, prepares quotes and approves proposals. The example grows throughout the guides: a Clients database becomes connected Workspaces and then a working process. The same principles apply to research, software products or a manuscript.

## Two ways to access the same work

In your browser, the Surface application at `app.dagio.ai` gives you access to your Workspaces, Surface editing and AI work. In a compatible AI host, Surface presents the same content alongside the host’s native conversation. Use the same Dagio account and find saved changes through either access, according to your permissions.

The web application’s conversation and your AI host’s conversation remain separate. Content saved in Surface preserves the work: switching interfaces does not create a copy of your Workspace. Conflicts, permissions and [collaboration](https://developers.dagio.ai/collaboration/) rules still apply. [Work with AI](https://developers.dagio.ai/ai/) explains context and change review.

## Device cache

Settings opens as a full-page workspace: navigation on the left and a centered content column with bordered setting groups on the right.

Open **Settings → Storage & cache** to enable or disable caching and set **Cache size**.
Disabling caching is not recommended: content downloads again when opened. These settings apply globally to your account on this device. Preloading includes
the Space’s descendants; links to other Spaces do not start additional downloads.
For Knowledge and Content, folder lists are prepared before Surface content downloads.
When the Space supports Graph, its global Graph is also prepared. Filtered local Graph views load on demand.
Progress shows Graph preparation, the number of folders prepared, then content downloads.
Reopening reuses valid cached content and downloads missing or changed content. Progress separates
content already cached from new downloads.
Data records are included even when they have no document content. Leaving a Space stops its
background queue; returning reuses valid cached content. After a temporary connection failure,
downloads can resume when access is re-established. An explicit pause remains paused.

Section titles sit above the bordered setting groups. Below usage, **View details** shows one row per
Space with its size, status, activity and a Clear action. Both global and per-Space cleanup ask for
confirmation and protect open Spaces and unsaved edits. Close a Space before clearing its downloads.
If protected data exceeds the selected size, background downloads stop. Cache location is currently
managed by the browser; choosing a local folder is not supported by the current storage engine.
Clearing the local cache keeps saved server data and History. Cached access still requires your
current permissions; it does not provide an independent offline copy.

## Choose a path

| Your goal                     | Start here                             | What you obtain                          |
| ----------------------------- | -------------------------------------- | ---------------------------------------- |
| Use your first app            | [Quickstart](https://developers.dagio.ai/quickstart/)        | A client record and a first view         |
| Adapt information and screens | [Models](https://developers.dagio.ai/models/)                | A coherent app structure                 |
| Connect two apps              | [Integrations](https://developers.dagio.ai/workspace-links/) | Client selection and related quotes      |
| Automate work                 | [Flows](https://developers.dagio.ai/flows/)                  | Steps, a result and progress tracking    |
| Generate or verify sources    | [Model reference](https://developers.dagio.ai/reference/)    | Fields, values, variants and constraints |

## One shared definition

A Model defines your app: objects, Fields, views, Actions and rules. Studio and AI use this shared definition. An AI proposal remains visible and reviewable in the same tools you use for your own changes.

Surface interfaces present the Fields, content and Query results defined by the Model. Their controls invoke app Actions with the corresponding permissions. A visible button never grants permission to perform the corresponding operation.

## Read, try and reuse

Guides explain complete uses. Tables give available choices and expected values; examples show how they fit together in the same Clients/Quotes app. The [Surface component reference](https://developers.dagio.ai/surface-components/) details the elements available for your views. Copy buttons and Markdown versions make documentation usable with your AI.

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

## Applied examples : Your Clients/Quotes environment

An app brings together a home, records and the actions that move work forward.

### Configuration

Fragment placed in `homePresentation`. [Properties and accepted values](https://developers.dagio.ai/reference/workspace-home-presentation/).

```json
{
  "contract": "WorkspaceHomePresentation@1",
  "header": {
    "intro": "Clients and quotes",
    "primaryNavigation": {
      "destinationKey": "clients",
      "label": "Open clients"
    }
  },
  "launchers": {
    "title": "Move work forward",
    "description": "Choose an action",
    "icons": [
      {
        "actionKey": "create-client",
        "icon": "users"
      },
      {
        "actionKey": "prepare-quote",
        "icon": "document"
      }
    ]
  },
  "blocks": [
    {
      "kind": "section",
      "sectionKey": "recent-quotes",
      "variant": "collection",
      "placement": "main",
      "maximumVisible": 4,
      "viewAll": {
        "destinationKey": "quotes",
        "label": "All quotes"
      }
    }
  ]
}
```

### Variation and connection

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

```json
{
  "key": "client",
  "definitionPaths": [
    "workspace/clients/surface/client"
  ],
  "editActionKey": "edit-client",
  "identity": {
    "title": {
      "kind": "field",
      "fieldPath": "fields/company"
    },
    "avatar": {
      "kind": "initials",
      "maximumLetters": 2
    },
    "subtitle": {
      "kind": "field",
      "fieldPath": "fields/status"
    }
  },
  "valueLabels": [
    {
      "fieldPath": "fields/status",
      "values": [
        {
          "value": "prospect",
          "label": "Prospect"
        },
        {
          "value": "active",
          "label": "Active"
        }
      ]
    }
  ],
  "card": {
    "summary": {
      "kind": "field",
      "fieldPath": "fields/notes"
    },
    "tags": {
      "namespace": "user",
      "maximumVisible": 3
    },
    "metricKeys": [],
    "openLabel": "Open client"
  },
  "queryBindings": [],
  "metrics": [],
  "detail": {
    "primaryActionKey": null,
    "creationActionKeys": [],
    "actionKeys": [],
    "sections": [
      {
        "kind": "fields",
        "key": "follow-up",
        "label": "Client follow-up",
        "fieldPaths": [
          "fields/notes",
          "fields/status"
        ]
      }
    ],
    "settings": {
      "fieldPaths": [
        "fields/email"
      ]
    },
    "tags": {
      "namespace": "user",
      "maximumVisible": 3
    },
    "relatedGroups": [],
    "primaryActionLabel": null
  }
}
```

### 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. Clients · Data
2. References · Knowledge
3. Preparation · Work
4. Quotes · Product

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