The surface contract

There are two ways to build an agent that touches Slack, Teams, and Excel.

The first treats them as integration targets. The agent lives in a dashboard. Runs are launched, drafts reviewed, approvals recorded — all inside the dashboard. Slack gets a notification when a run finishes. Excel gets an export. Teams gets a card with a deep-link. The surfaces are downstream, and the product is the dashboard.

The second treats them as the surface itself. There is no dashboard. The agent runs inside the Slack DM the controller already has open, the Excel sidebar attached to the workbook that holds the close, the Teams thread the audit lead is reading on day six of the close. The work is wherever the operator was already going to be, and the agent meets them there.

Both architectures function. They are not equivalent. The choice determines what the agent owes the surfaces, what the surfaces owe the agent, and what the operator inherits when something breaks. This is the surface contract. Most agent products treat it as integration glue. We treat it as the load-bearing decision of the product.

This article is for the technical buyer evaluating where Yig sits inside an existing stack, the security reviewer authorising the access scopes that make surface-first work, and the CTO asking whether Yig requires a new centre of gravity in the toolstack or fits into the one already there. The agent fits. The reason it fits is that the surfaces are the product.

Two architectures

The two architectures look similar at a distance and diverge sharply on contact.

An agent-with-surfaces is a dashboard product. Surfaces are output channels — places the dashboard pushes notifications when something has happened. The operator sees the notification, follows a link back to the dashboard, and does the actual work there.

An agent-as-surface inverts this. The Slack DM is where the controller asks for the reconciliation, sees the draft, and approves it. The Excel sidebar is where the FP&A lead reviews the variance commentary line by line, against the cells those variances reference. The Teams thread is where the audit lead picks up the close mid-cycle and reads the prior thirty-seven runs in order. The surfaces are where the work happens, not where it is announced.

The difference is not cosmetic. The first treats Slack as a notification channel — throwaway by design, announce something and trust the operator to follow up elsewhere. The second treats Slack as a seat. A seat holds identity, message ordering, an audit thread, the operator’s history with the agent over a hundred prior runs. Those two things have different obligations, different failure modes, different audit consequences.

Agent-with-surfaces (dashboard-first)

  ┌────────────┐   notify    ┌──────────┐
  │ Dashboard  │ ──────────▶ │  Slack   │  ─ link back ─┐
  │            │   export    ┌──────────┐               │
  │ (work      │ ──────────▶ │  Excel   │  ─ link back ─┤
  │  happens   │   notify    ┌──────────┐               │
  │  here)     │ ──────────▶ │  Teams   │  ─ link back ─┘
  └────────────┘             └──────────┘
  Centre of gravity: the dashboard


Agent-as-surface (surface-first)

  ┌───────────────────────────────────────────────────┐
  │  Slack DM        Excel sidebar      Teams thread  │
  │     │                │                  │          │
  │     ▼                ▼                  ▼          │
  │   draft           draft               draft        │
  │   review          review              review       │
  │   audit thread    audit thread        audit thread │
  │     │                │                  │          │
  │     └────────┬───────┴──────────┬──────┘           │
  │              ▼                  ▼                   │
  │       Same agent,         Same audit log            │
  │       same workflow                                 │
  └───────────────────────────────────────────────────┘
  Centre of gravity: where the operator already was

A dashboard-first product can be sold. A controller can be trained to log into it. A pilot can be run from it. The economics catch up later. Every interaction is two surfaces — the one the operator was already in, and the dashboard the product wants them to visit — and the cognitive cost of the second compounds across a year. By the third quarter the controller opens the dashboard only to dismiss the notifications.

A surface-first product is harder to build. It has to honour someone else’s host environment in two distinct shapes — a messaging product and a spreadsheet — and the contracts are not portable. What works as a guest in Slack would be a violation in Excel.

The surface is not where the agent reports out. It is where the agent works.

That decision determines almost everything else.

The contract, per surface

A contract is a list of things each party owes the other.

A surface-first agent lives in surfaces that did not exist to host it. Slack, Teams, and Feishu are messaging products. Excel is a spreadsheet. None were designed as agent runtimes. Each exposes a set of public extension points an agent can occupy — a bot user with a DM thread, a task pane attached to a workbook. Occupying those points is not a casual integration choice. It is a contract.

Surface	What the surface owes the agent	What the agent owes the surface
Messaging (Slack, Teams, Feishu)	Stable identity for the bot user. Message ordering inside a thread the agent can rely on to reconstruct what was said and when. A thread the agent can pin work to, so the audit trail for a run is anchored to one conversation rather than scattered across DMs. A workspace-level identity for the operator, so the agent does not re-prove who is asking on every message.	Correct citation back to the underlying data — when the agent says “the December variance is $1.2M” the controller can click through to the source. No chat noise; no greetings, no filler. Opt-in interrupts only — the agent does not message without having been asked. A run identifier on every draft so the conversation can be picked up by a different reviewer or continued in a different surface.
Excel	A task pane that survives workbook reloads. A cell-range reference model the agent can point at — sidebar showing A1:F127 for the variance schedule, not “the variance table” — with the operator’s selection stayed in sync. A workbook identity the agent can read, so it knows which entity, period, and version it is looking at. The right to write into cells only on operator approval.	Cell-range citation that survives if the operator inserts a row. No silent writes — every change is staged for approval before it commits, and the live preview marks proposed cells with distinct styling that rolls back if rejected. No noise in the workbook itself; working notes live in the sidebar, not in a cell.

The left column is not negotiable. The agent cannot manufacture stable identity inside Slack out of thin air. If the workspace strips the bot user’s permissions, the agent stops working. The agent cannot fabricate a cell-range reference model Excel does not expose. Where the surface does not give the agent what it needs, the agent has to degrade visibly. The operator must know that the surface and the agent are no longer in the contract they expect.

The right column is a discipline. Chat noise in messaging. Silent writes in Excel. Each surface has a way of being a guest that respects the surface’s existing role, and a way that does not. The discipline is to choose the first when the second would be easier to ship.

A surface that hosts the agent has obligations the agent cannot waive, and obligations the agent must honour.

A missing row is not a polish item. It is the difference between an agent that lives in a surface and an agent that visits one. The operator can tell which inside two days.

Who owns identity, history, and errors

Contracts get interesting when something breaks.

Consider a stale Slack token mid-review. A controller has been working with the agent inside a Slack DM for three weeks of a close cycle. The thread holds thirty-seven prior runs — variance commentary, accrual estimates, FX rate questions, intercompany reconciliations. The token authorising the bot user has expired. The agent cannot post into the thread. Which party owns each step of the recovery?

This walkthrough is the contract the agent is held to. Per-surface failure messaging and the queued-draft handling ship today; the cross-surface plumbing — one surface speaking about another surface’s failure through a shared run identifier — lands across v1.6–v1.7. The contract is the constraint we build to.

1. The agent detects the failure when it tries to post a draft. The next run completes its reasoning, builds the commentary, and attempts to post into the existing thread. The post fails. The agent has a finished draft and no way to deliver it. The agent does not retry silently — that would create the appearance of work happening when nothing reaches the operator.

2. The agent does not invent a different surface for the message. A poorly-disciplined agent would email the draft, or post into a different channel, or write the draft into a file and link to it. None preserve the audit thread. The draft was supposed to land where the prior thirty-seven runs are. Landing it elsewhere breaks the operator’s ability to read the close in one place. The agent waits.

3. The surface’s own audit record names the failure. A draft was produced, the surface delivery failed, the reason was workspace-level authorisation expiry, no message reached the operator. The per-surface append-only record exists whether or not anyone fixes the token. Convergence onto a single cross-surface trail keyed by run identifier is the same v1.7 contract item.

4. The operator finds out from the surface itself. A controller returning to the Slack DM sees the agent’s session-expired message — explicit about what failed and what recovery requires. The agent does not push the failure into a different surface to demand attention. Cross-surface visibility — the Excel sidebar speaking about a Slack failure — is the next contract item the architecture is closing, scheduled on the same plan-registry track as the shared audit trail.

5. IT, not the agent, fixes the token. The token belongs to the customer’s Slack workspace. The agent is a guest. The workspace owns whether the guest is allowed in. When the workspace administrator re-authorises the bot user, the next attempted post succeeds, the queued draft is delivered into the original thread, and the audit log records both the failure window and the recovery. The thread is unbroken.

6. The controller decides whether the queued draft is still valid. A draft produced two hours ago against the entity’s TB may still be correct. A draft produced two days ago, on data that has since moved, may not. The controller reviews it like any other draft. The agent does not re-run automatically — the operator decides whether the work is still fresh.

In a dashboard-first architecture, the same failure has a different shape. The dashboard is the system of record. A stale Slack token is a notification failure — the dashboard knows about the draft, the ping did not arrive. The operator finds out when they next open the dashboard, possibly days later. There is no audit thread in Slack to preserve, because the work was never in Slack. Recovery is easier on the engineering side, and less honest about what failed. What failed was a piece of furniture, not a contract.

The surface is the seat of identity. The agent is a guest.

A guest does not redecorate the room when the host changes the lock. A guest waits for the lock to change back, and tells the host clearly that it is waiting.

Why dashboards break this contract

The default alternative to surface-first is a dashboard with notifications.

It is the architecture most agent products ship by default, because it is most familiar to consumer-software lineages. Build a place that holds the agent. Add notification integrations to Slack and email. Add an Excel export. Add a document generator on the side. This violates the surface contract in three specific ways. Each is structural — none can be polished out.

1. Identity laundering. When a notification arrives in Slack saying “your run is ready,” the action is the dashboard’s, not the operator’s. The Slack thread does not record that the controller initiated a variance review at 11:14am on day six of the close. It records that the dashboard sent a notification. The next reviewer who reads the thread sees a doorbell, not a record of work. The audit identity sits in the dashboard’s session logs, not where the next reviewer will look. The Slack thread tells one story. The dashboard log tells another. Reconstructing the truth requires the auditor to pull from both.

2. Notification as throwaway. Slack messages in a notification architecture are designed to be dismissed. The notification says “your run is ready,” the operator clicks through, the work happens in the dashboard, the Slack message has no further function. It is a doorbell. The thread cannot be reviewed by a different controller picking up the close mid-cycle, cannot be cited in an audit response as the place where the variance commentary was discussed and approved. It is decorative. In a surface-first architecture, the Slack thread is the work — every draft, every review, every approval lives in it. The controller can hand it to a colleague who reads it top to bottom and knows the state of the close. The notification architecture cannot do that.

3. Cold-start tax. Every interaction starts at the dashboard, even when the operator’s day is in Slack and Excel. The controller is already in Slack. They have an Excel workbook open. The notification arrives, and their next action is to leave both surfaces, open the dashboard, log in if the session has expired, find the run, review the draft. Across a hundred interactions a week, the cost is not small. The architecture’s gravitational pull is away from Slack and Excel, toward a place the operator has no other reason to be. Over a year, the dashboard becomes the tab the operator opens to dismiss notifications and close again, and the agent is back to one-way.

A dashboard with notifications is not a surface-first architecture wearing different clothes. It is a different product.

Each violation maps to the contract. Identity laundering breaks what Slack owes the agent. Notification-as-throwaway breaks what the agent owes Slack. The cold-start tax breaks what every surface owes the agent — the operator already being there. Three violations, one architecture that cannot honour any of them.

The cost shows up at audit time. A regulator asking “who reviewed this variance” wants a thread with a name, a timestamp, a draft, a reviewer comment, an approval. A dashboard architecture produces that artifact in a dashboard log. A surface-first architecture produces it in the same Slack thread the controller worked in. The first answer asks the auditor to trust the dashboard. The second hands the auditor a record the customer already controls.

What a surface-first roadmap looks like

The surface contract constrains what we can promise.

We can promise work happens at the surfaces the operator already lives in. We can promise the architecture is converging on a shared run identifier so that a draft started in Slack and approved in Excel will produce a single defensible record — the per-surface audit logs ship today, the shared join key lands across v1.6–v1.7. We can promise the agent will not invent a new place for the operator to visit, will not exfiltrate work to a vendor-side dashboard, will not make a surface a notification channel for work that lives somewhere else.

We cannot promise that every new productivity surface the world invents will be a Yig surface. Each new surface is a contract. The surface has to expose identity, message ordering, an attachment model the agent can pin work to, and a permission model the customer’s IT lead can authorise. The agent has to be a disciplined guest — no noise, no silent writes, no inventing a different surface when the contracted one breaks. When a surface does not offer the left column, we do not occupy it. When the agent cannot honour the right column, we do not ship the surface.

The list grows slowly. Slack, Teams, Feishu, Excel, the CLI, the API. Each was a deliberate yes, with a list of things the agent will not do inside that surface, written before any code shipped. A new surface will be a new contract, drafted in full before the agent is allowed to enter.

The dashboard remains absent. The roadmap does not lead to a Yig dashboard with surface integrations on the side. It leads to more surfaces, each held to the same contract, each adding density to the operator’s existing day without inviting them inside a vendor-built place they would not otherwise go. The absence of a dashboard is not a feature we are saving. It is a position we hold on purpose.

Every surface we add is a contract we accept. Every surface we refuse is one we did not want to honour.

There is a question this leaves open. Whether the architecture scales to operators whose stack does not centre on the messaging-and-spreadsheet pairing we have contracted with — whose work is in a different chat tool, a different spreadsheet, a different document editor. Those surfaces are not in the contract yet. Each will be a deliberate decision, with the same shape: what the surface owes the agent, what the agent owes the surface, what happens when the contract breaks. Until the contract is drafted and the agent is disciplined enough to honour it, the surface is a no.

The agent meets the operator where they already are, or it does not meet them at all.