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

# Debrief Contracts

> How a customer gateway can shape a guided debrief that Atlas later presents with speech and canvas pages.

## The payload

A debrief contract is a structured payload that tells Atlas how to present completed external work back into a meeting.

This is useful when work finishes outside the room and Atlas should later:

* open with a short explanation
* preload canvas pages
* walk the room through the result step by step
* pause naturally between sections

Think of it as a presentation plan, not a rigid script.

## Recommended delivery model

For new builds, prefer pushing debriefs into Atlas through the [Workspace API](/atlas/workspace-api).

That keeps the flow explicit:

1. your trusted agent or workflow finishes the work
2. it upserts the debrief into Atlas by `externalId`
3. Atlas stores it immediately and can present it later
4. the same client can verify it with a `GET` or a full list call

Use the gateway-fed sync model below only when you already have an older integration that exposes debriefs from a gateway manifest action.

The contract itself stays the same either way.

## Legacy gateway sync model

Atlas does **not** expect the customer gateway to write directly into Supabase.

Instead:

1. the customer gateway exposes a normal read action
2. Atlas calls that action from the dashboard
3. Atlas normalizes the returned debrief payloads
4. Atlas upserts them into its own control-plane storage
5. Atlas then shows them in the dashboard and can present them in-room

Recommended action names:

* `list_ready_debriefs`
* `list_debriefs`

The current Atlas dashboard checks for those names in the gateway manifest and uses the first one it finds.

## Recommended action response shape

The easiest response shape is:

```json theme={null}
{
  "status": "completed",
  "data": {
    "debriefs": [
      {
        "externalId": "eval_123",
        "title": "Braintrust Eval Debrief",
        "summary": "Latest eval results with score breakdown and next steps.",
        "status": "ready",
        "audience": {
          "type": "groups",
          "groupSlugs": ["support-leads"]
        },
        "contract": {
          "version": "atlas-debrief-v1",
          "title": "Braintrust Eval Debrief",
          "canvas": {
            "pages": [
              {
                "title": "Overview",
                "html": "<div>...</div>"
              }
            ]
          }
        }
      }
    ]
  }
}
```

Important field:

* `externalId`

Atlas uses that as the stable external key when it syncs debriefs into its own storage.

## Field guide

If you hand this page to an internal coding agent, the practical guidance is:

* `externalId`
  * stable ID for the same debrief across refreshes
  * do **not** generate a new random ID on every poll
  * good examples: eval run ID, workflow run ID, job execution ID
* `title`
  * short user-facing label in the Atlas dashboard
  * aim for something a person can skim quickly
* `summary`
  * one-line description for the dashboard list
  * this should explain why the debrief matters, not restate the title
* `status`
  * usually just `ready`
  * Atlas currently expects ready-to-present debriefs here
* `audience`
  * optional lightweight targeting for who should see this debrief in the org
  * default is `all`
  * recommended shape:
    * `{"type":"all"}`
    * `{"type":"users","userEmails":["a@company.com"]}`
    * `{"type":"groups","groupSlugs":["recruiting-leads"]}`
* `contract.version`
  * use `atlas-debrief-v1`
* `contract.title`
  * usually the same as the top-level `title`
  * this is the debrief title Atlas sees at presentation time
* `contract.summary`
  * optional longer summary for Atlas context
* `contract.atlas.openingSpeech`
  * the first sentence Atlas says before it pauses
  * example: `I have a debrief ready on the latest eval run. Let me know when you're ready to proceed.`
* `contract.atlas.instructions`
  * extra delivery guidance for Atlas
  * for example: `Keep this concise and pause after each section.`
* `contract.atlas.delivery`
  * use `manual` if Atlas should wait for the room to say `ready` or `next`
  * omit it if you do not care yet
* `contract.canvas.pages`
  * what Atlas should show if there is a canvas
  * each page should have user-facing `title` and rendered `html`
* `contract.sections`
  * what Atlas should say section by section
  * use this when you want controlled progression, pauses, or speech-only debriefs
* `contract.sections[].speech`
  * the actual content Atlas should present for that section
* `contract.sections[].checkpointPrompt`
  * optional prompt Atlas uses before pausing
  * example: `Let me know when you want to move to the next section.`
* `contract.sections[].pageIndex`
  * which canvas page that section belongs to
  * omit it for speech-only debriefs

Good first rules for an internal coding agent:

* if the workflow produced charts or tables, include `canvas.pages`
* if the workflow produced mostly narrative text, use `sections`
* if both exist, include both
* if you are unsure, start with:
  * one `openingSpeech`
  * one `summary`
  * one or more `sections`
  * and only add canvas pages when you have something genuinely visual to show

## What good debriefs feel like

Good debriefs are easy to follow in a live room.

If you are building these with an internal coding agent, give it this quality bar:

* show the most important thing first
* keep it concise and actionable
* make each page earn its place
* do not read a report aloud
* optimize for attention, clarity, and the next decision

If a workflow produced a lot of material, the debrief should still stay light. Atlas can always fetch or explain more detail later when the room asks.

## Debrief audience

Atlas supports lightweight audience targeting on synced debriefs.

Use this when a gateway should only surface a debrief to:

* everyone in the org
* specific users
* specific stakeholder groups

Recommended shape on the top-level debrief item:

```json theme={null}
{
  "externalId": "recruiting_weekly_123",
  "title": "Recruiting Weekly Brief",
  "summary": "Hiring pipeline update for recruiting leads.",
  "status": "ready",
  "audience": {
    "type": "groups",
    "groupSlugs": ["recruiting-leads"]
  },
  "contract": {
    "version": "atlas-debrief-v1",
    "title": "Recruiting Weekly Brief"
  }
}
```

For named people, use:

```json theme={null}
{
  "audience": {
    "type": "users",
    "userEmails": ["a@company.com", "b@company.com"]
  }
}
```

Notes:

* if you omit `audience`, Atlas treats the debrief as `all`
* keep this lightweight; Atlas is not meant to be a deep enterprise policy engine
* group slugs should match the org groups defined in Atlas workspace settings
* the gateway suggests the intended audience, and Atlas stores and lightly enforces it in the dashboard

Atlas also accepts a few aliases for compatibility, including:

* `targetUsers`
* `targetGroups`
* `stakeholderEmails`
* `stakeholderGroups`
* `stakeholders`
* `contract.metadata.audience`

But if you are building a new gateway, prefer the explicit top-level `audience` object.

## Page grounding

Each `canvas.pages[]` item can also include optional `grounding`.

Use it for small factual support that helps Atlas understand the current page better without reading all of it aloud.

Good grounding fields:

* `summaryText`
* `source`
* `chartType`
* `labels`
* `values`

Keep grounding concise:

* short factual summary, not another paragraph dump
* small lists of labels or values, not the full dataset
* enough detail to support follow-up questions about the current page

Do not use grounding as a hidden second report.

If you already have a large body of source material, keep the debrief itself light and let Atlas fetch fresh detail through gateway tools when the room asks.

## Canvas guidance

Send the smallest canvas that still makes the point clearly.

Good working heuristics:

* aim for `1` to `3` pages for most debriefs
* use `4` or `5` pages only when each page clearly has a different purpose
* keep one main idea per page
* prefer one chart or one table per page, not many
* prefer short summaries over raw dumps
* if the result is mostly narrative, use `sections` and keep the canvas simple or omit it entirely

If the external result is large, Atlas does **not** need the whole thing rendered on canvas. Put the takeaway in `sections[].speech`, render only the useful visual or summary, and keep the rest in `metadata` or behind the gateway.

Common mistakes:

* too many pages
* overly dense tables with lots of columns and rows
* giant embedded scripts or repeated chart libraries
* pasting a long report verbatim instead of summarizing it
* multiple visuals competing on the same page
* pages that only restate what Atlas is already going to say aloud

## Good page patterns

Good first-page patterns:

* three KPI cards and one short takeaway sentence
* one short summary paragraph and one compact table
* one bar chart and one sentence explaining what matters

Good follow-up page patterns:

* top 3 issues and recommended next steps
* one comparison table with only the most important rows
* one timeline or one checklist

If you are unsure whether something belongs on canvas, ask:

* would a human benefit from seeing this while Atlas speaks?

If the answer is no, keep it in `sections` instead.

## Few-shot examples

### Good: lightweight metrics page

* title: `Overview`
* canvas:
  * three KPI cards
  * one sentence: `Pass rate improved, but citations still need attention.`
* speech:
  * short explanation of what changed

### Good: narrative debrief with no canvas

* `sections[]` only
* Atlas speaks:
  * what completed
  * what changed
  * what should happen next
* no canvas because there is nothing genuinely visual to show

### Good: one simple evidence page

* title: `Top Issues`
* canvas:
  * compact table with `Area`, `Why it matters`, `Next step`
* speech:
  * short walkthrough of the top 2 or 3 issues

### Bad: raw report dump

* one huge HTML page
* many sections pasted verbatim
* multiple large charts
* long markdown converted directly to HTML

That usually makes the canvas harder to read and gives Atlas too much low-signal material.

## Template library

The template examples now live on [Debrief Templates](/gateway/debrief-templates).

Use that page when you want:

* full JSON examples
* Monday morning brief
* research summary
* eval debrief
* starter-shape guidance

## Minimum viable contract

The clean minimum is:

* `title`
* optional `summary`
* optional `atlas.openingSpeech`
* either:
  * `canvas.pages[]` with `html`
  * or `sections[]` with speech only

Everything else can be added later.

## Recommended long-term version

Atlas now supports a stable long-term shape:

```json theme={null}
{
  "version": "atlas-debrief-v1",
  "title": "Braintrust Eval Debrief",
  "summary": "Latest eval results with score breakdown and next steps.",
  "atlas": {
    "openingSpeech": "I have a debrief ready on the latest eval run. Let me know when you're ready to proceed.",
    "instructions": "Keep this conversational and pause between sections.",
    "delivery": "manual"
  },
  "canvas": {
    "title": "Eval Debrief",
    "deliveryMode": "replace",
    "pages": [
      {
        "title": "Overview",
        "html": "<div>...</div>"
      },
      {
        "title": "Score Distribution",
        "html": "<div>...</div>"
      },
      {
        "title": "Follow-ups",
        "html": "<div>...</div>"
      }
    ]
  },
  "sections": [
    {
      "title": "Overview",
      "speech": "Here is the overview...",
      "checkpointPrompt": "Let me know when you want to move to the score distribution.",
      "pageIndex": 0,
      "delivery": "wait_for_prompt"
    },
    {
      "title": "Score Distribution",
      "speech": "This page shows the score spread by suite...",
      "pageIndex": 1,
      "delivery": "wait_for_prompt"
    },
    {
      "title": "Follow-ups",
      "speech": "The main follow-ups are...",
      "pageIndex": 2,
      "delivery": "wait_for_prompt"
    }
  ],
  "actions": {
    "speakToRoom": true,
    "openCanvas": true
  },
  "metadata": {
    "source": "braintrust",
    "runId": "eval_123"
  }
}
```

## Minimal version

This smaller payload is also fine:

```json theme={null}
{
  "version": "atlas-debrief-v1",
  "title": "Eval Debrief",
  "canvas": {
    "pages": [
      {
        "title": "Overview",
        "html": "<div>...</div>"
      }
    ]
  }
}
```

Atlas will fill in the missing behavior with defaults.

## Speech-only version

If you do not want any canvas at all, a speech-only debrief is also valid:

```json theme={null}
{
  "version": "atlas-debrief-v1",
  "title": "Workflow Debrief",
  "summary": "The workflow completed successfully.",
  "atlas": {
    "openingSpeech": "I have a short workflow debrief ready. Let me know when you want me to begin.",
    "delivery": "manual"
  },
  "sections": [
    {
      "title": "Summary",
      "speech": "The workflow completed successfully. Three records were updated and no approvals are pending.",
      "checkpointPrompt": "If you want, I can explain the changes in more detail.",
      "delivery": "wait_for_prompt"
    }
  ]
}
```

## What Atlas does with it

When Atlas uses a debrief contract, it can:

* preload the canvas pages into the room
* start in active mode
* open with `atlas.openingSpeech` if present
* advance section by section when the room says `ready`, `continue`, `next`, or `proceed`
* answer questions in between instead of blindly plowing ahead

## Optional fields and defaults

Atlas is intentionally forgiving here.

If you omit fields, Atlas falls back to sensible defaults:

* no `summary`
  * Atlas still uses the `title`
* no `atlas.openingSpeech`
  * Atlas can still present the debrief
* no `sections`
  * Atlas derives sections from the canvas pages in order
* no `pageIndex`
  * Atlas maps sections to pages by position
* no `actions`
  * Atlas assumes normal room presentation behavior

The main required field for a canvas-backed debrief is:

* `canvas.pages[].html`

For a speech-only debrief, the main required field is:

* `sections[].speech`

## Why sections are separate from pages

Keep `sections` and `canvas.pages` separate.

That gives you a cleaner long-term contract:

* `canvas.pages`
  * what Atlas should show
* `sections`
  * what Atlas should say
  * when it should pause
  * which page each section belongs to

This is more flexible than forcing every page to carry all of the speaking logic.

## Delivery guidance

Use these simple defaults:

* `atlas.delivery: "manual"`
  * Atlas waits for the room to proceed
* `sections[].delivery: "wait_for_prompt"`
  * Atlas presents one section, then pauses

This usually feels better than auto-advancing.

## Backward compatibility

Atlas still accepts the earlier dated contract shape used in the initial prototype.

The recommended shape going forward is:

* `version: "atlas-debrief-v1"`

## Good first use cases

* eval completed
* workflow finished
* internal review ready
* candidate packet prepared
* sales research compiled
* incident summary ready

## What makes a debrief genuinely useful

A good debrief is not just "some data is available."

It should represent a moment where a human would actually benefit from Atlas bringing something back into the room.

Good triggers usually look like:

* an overnight research batch finished and now needs a short walkthrough
* a weekly or daily report is ready for a team review
* an eval or workflow completed and the interesting part is the result, not the raw execution log
* a webhook from an internal system means there is now a human-ready summary worth presenting
* a scheduled morning startup or weekly wrap-up should begin from a clear briefing

Practical rule:

* do the scheduling, cron, webhook, and upstream orchestration in your own gateway or workflow system
* only expose the debrief to Atlas once it is genuinely ready to present

Atlas is best when it receives something already shaped for human review, not an intermediate machine artifact.

## Reference shape: clean weekly debrief

If you are building a first production debrief, this is a good target:

1. `Overview`
   * three KPI cards
   * one sentence on what changed
2. `Main Drivers`
   * one chart or one compact comparison table
   * the top two or three reasons behind the change
3. `Follow-ups`
   * the most important next actions
   * who should care and what should happen next

For speech:

* one short opening line
* one concise section per page
* one pause between sections

This is usually much better than:

* pasting the whole report into page 1
* speaking the full report aloud
* making Atlas summarize a giant blob in real time

If you already have a long report, keep the report in your system of record and let the debrief be the presentation layer.

## Recommended rollout

Start with one debrief shape that is easy to trust:

1. one title
2. one summary
3. three canvas pages
4. one short opening line
5. one section per page

Once that works, you can add richer metadata and follow-up actions later.