---
title: "Surfaces and objects"
url: https://developers.dagio.ai/documents/
---

# Surfaces and objects

   
                             
                                                                     
                 
             
          
   

## Structured content

A Surface combines objects in one universal composition: rich text, images, tables and linked views. Each object has a stable identity for links, search and targeted AI operations. Renaming or moving an object preserves that identity. H1–H6 headings structure text within an object; they have no business identity, Tags or independent protection.

A template entry that needs its own address uses a Rich text object with its own header. Work documentation templates compose these entries in the same Surface editor, with View, Edit and Layout.

## Work documentation templates

In the application Builder, a step's **Work documentation → Assign template** offers reusable starting
points. **Task details** defines the request, scope, expected result and success criteria; **Task
summary** recalls that request and reports performed work, verification and remaining work.
Project brief, Action plan, Issue report, Procedure, Review, Checklist and Analysis cover common
work alongside meeting, research, specification, decision and reporting templates. **Specification**
can describe a product, service, process or technical solution.

Each template includes relevant typed Fields, such as dates, owner, priority or outcome, and its
own usage Instructions. Adjust them through the shared **Fields** editor. Required Fields identify
expected metadata; you can still save an incomplete draft. Dates, people, references and achieved
results are not invented. Long descriptions and evidence belong in the titled content objects.
Creating a template copies its definitions; later catalogue changes do not rewrite saved templates
or existing work. These metadata Fields do not control the Workmap's execution state.

Each step accepts at most one assigned template. It defines the **Home Surface** created by default
for that step when new work starts. Additional Surfaces can still be created during execution,
including from the same template; they do not replace the Home. The Home remains editable and
retains its identity after renaming, moves or changes to the application Model. Its
illustrated card opens the local Definition, Instructions, Fields and Contents. Editing this copy
affects this step only; the source catalogue remains unchanged. New assignments show **Modified**
when their local definition differs from the assigned starting point, and **Custom** identifies a
custom starting point. Removing an assignment or deleting its step lists the definitions and local
changes that will be lost. Existing work and its created Surfaces are retained.

During execution, **Home** navigation always exposes the assigned Surface. It cannot be moved to
trash or merged into another Surface, and trashing a folder containing it is also refused.
Complementary Surfaces can still be removed normally. These protections are enforced by the shared
write path for the application and MCP, not only by disabled menu items. Existing Work captures
are retained; the new Home role is recorded when starting new work.

## Surface metadata

The document body, stored Fields, description and dates belong to the same revision. Reading these
values does not authorize changing protected attributes. Model declarations and effective values
remain separate; native content without a Model does not acquire an invented one. Human and AI
access still follows the applicable permissions and disclosure protections. Retained consultation
remains read-only.

In Clients, **Qualification notes** contains Need, Constraints and Next action. AI can work on the Constraints object while preserving other objects and their edits.

| Property | Options / expected values | Description |
| --- | --- | --- |
| Title | Readable text | Presents the object in the Surface |
| Protection | Object lock | Protects admitted changes to the object and its descendants |

## Edit an object

Work directly in the Surface. To request a rewrite, select the object and state the intention: “Rephrase the constraints without changing the amounts.” The proposal must respect scope and protections. Changing structure is not equivalent to editing text.

## Formats and provenance

Native content retains its format, revisions and references. Document, Markdown, Code, Canvas and Asset use editors suited to their contents. UI composition chooses where an editor appears without reinterpreting its persistent format.

A confirmed export is distinct from reading the file or downloading it through the host app. If the
export is confirmed but reading or delivery fails, resume that export without generating another
file; current access is still checked. If the response is unknown, resume the same pending request
before changing the source or format. Confirmation alone does not establish that the file was saved
on your device.

When a historical export profile is offered for a Work’s references, select the retained capture.
The document uses that capture’s revisions and order, with the original program’s profile, even
when the application has since changed. It does not replace those references with their current
contents. Current access and protections still apply: an old capture grants no additional access.
Resuming keeps the same confirmed export without executing the Work Action again.

For MCP clients, use `surface_work_document_composition_options_get` to discover profiles for the
selected Work capture, then `surface_work_document_composition_preview` to review the original
references and format. Confirm through `surface_work_document_composition_start`, passing the
returned `manifestHash` as `expectedManifestHash` and keeping the same `idempotencyKey`. After a lost
response, recover that same intent rather than generating another export.
`surface_document_export_get` reads the resulting
export through the shared download path. The current `applicationContext` remains distinct from
the original `programModelRevisionId`; the request does not supply its own source bodies,
permissions or manifest.

## Compose a documentary copy

Document Studio prepares a document from the exact occurrences and versions of a reviewed
composition. Choose their titles, levels and order, then add or remove offered sections. The review
retains citations and provenance without replacing sources with their current versions.

Explicitly confirm saving an independent copy in a new declared Surface or a new revision of the
selected document. Read access alone is insufficient: source export must be allowed, and the
destination must permit your write without weakening search, AI disclosure or confidentiality
protection. A citation grants no future access to its source. After an unknown response, resume
the same request; after a known receipt, reopening the copy does not repeat the write. The copy
remains an editable document, distinct from a binary export.

From the saved copy, select its destination document profile and a rich format that it permits.
Export retains the native document instead of converting it to simplified text. Unsupported
layouts, fonts or resources refuse the whole file rather than remove content. Images must be
materialized: a remote address does not become an independent copy. A confirmed render can be
downloaded again without recreating the file; an uncertain response resumes the same request.

Consult [history](https://developers.dagio.ai/history/) before restoring a revision and the [native formats reference](https://developers.dagio.ai/native-formats/) when generating content with a tool.
## Object limit

In **Settings → Surfaces**, set the maximum objects per Surface from 1 through 1,000.
The default is 1,000. This setting and Model limits control new additions; lowering it never hides
existing objects or prevents an edit without growth. Search and links use object identities,
with no separate 500-element index cap.

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

## Applied examples : Client notes and exported document

Content stays editable in the record; the export profile selects the authorized quotes.

### Configuration

Component properties `NativeContent.props`. [Properties and accepted values](https://developers.dagio.ai/surface-components/#nativecontent).

```json
{
  "recordProfileKey": "client",
  "contentKind": "document"
}
```

### Variation and connection

Fragment placed in `documentProfiles[]`. [Properties and accepted values](https://developers.dagio.ai/reference/managed-document-profile-v3/).

```json
{
  "contract": "DocumentProfile@3",
  "key": "client-quotes-export",
  "source": {
    "kind": "record-query",
    "recordProfileKey": "client",
    "queryBindingKey": "client-quotes",
    "viewKey": "quotes-table"
  },
  "exportFormats": [
    "markdown"
  ],
  "budget": {
    "maximumRows": 100,
    "maximumPages": 4,
    "maximumOutputBytes": 1000000
  }
}
```

### 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. Quote S-1042
2. Subject and need
3. Proposal
4. Retained references

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