# Surfaces: where people meet Soot

Where founders, members and customers meet Soot, which credential each one uses, and when Soot waits for a person to decide.

A Soot has no interface of its own. People meet it through **surfaces**: Nest, the CLI, a coding agent (MCP), the SDK and the widget on a website, and chat apps such as Telegram. This document covers who uses which surface, what they see, how a project plugs into Soot, and why every surface follows the same rules. If each place decided for itself "who may answer, who may approve, what the customer sees", permissions would drift apart and data would leak every time a channel is added.

## Model: one kernel, one rule set

The runtime is the kernel. It holds conversations, runs, attention items, identity and every "who may do what" decision. A surface does three things: it displays the part of the runtime's state projected for that place, passes back what people decide, and tags each message with the right speaker. It does not derive permissions from the channel type and it does not keep a second copy of the rules.

```text
 Owner (operator)      Member              Customer / visitor
 Nest · CLI · MCP     Nest · chat DM       website · app · public chat
        │                   │                       │
        ▼                   ▼                       ▼
 ┌─ surface: project data, tag the speaker, receive decisions ──────┐
 │  Runtime (kernel)                                                │
 │  conversation per place · run · attention item · Authorize()     │
 │  A Soot decides within its permissions; asks a person when needed│
 └──────────────────────────────────────────────────────────────────┘
```

Two consequences. A question or an approval request in Nest and in Telegram is the same item with one answer; whoever answers first, the other place shows "handled". And what a Soot can do does not depend on who is talking to it: tools, credentials and the list of tasks waiting for approval live in the Soot and host configuration. A surface only decides who may **speak** and who may **handle** an item.

## Three groups of people and their credentials

| Group | Who | Credential | What they see |
|---|---|---|---|
| Owner | Founder, the person running the runtime | Operator token (Nest, CLI); scoped `sop_` token (coding agent) | Everything on the runtime, every approval request |
| Member | The owner's staff | Member key (a fixed-user key with `conversations:read_team`, `control`...), or a linked chat account | Their own work; an approver can also approve work of the Soots they were granted |
| Customer | End user of the project | Trusted backend (`conversation_clients`) sets `X-Soot-User`; or `spk_` plus visitor `svs_` for anonymous people | Only their own conversations, in the public projection |

Each credential type goes through its own gate and none can stand in for another: an operator token never goes down to the browser; a user's key calling an admin route gets 403 (only a token that was never issued or has been revoked gets 401); the backend authenticates the user itself and then sets the identity, and a browser cannot send that header. `spk_` is a public key that selects a client policy. It does not prove who is staff or who is a customer, so organization-level privacy has to go through the project's backend. A conversation belongs to `tenant/user/Soot`; knowing an ID grants nothing in another tenant. An operator connection deliberately does not open into customer tenants: the owner receives **items that need handling** and does not read customer transcripts. A client config change only takes effect after activate (saved is not active). Declare clients with `soot schema deployment`; issue and revoke keys with `soot auth --help`.

**Device pairing**: to open someone's Nest on another machine, the owner issues a one-time code; the Nest on the other machine exchanges it (`/pair`, `/v1/pair/claim`) for its own device key, which can be revoked per machine. The exchange step needs no other credential because the code is the credential. Only the owner issues codes and revokes machines.

## Two kinds of channel

Channels for the owner and the team (Nest, CLI, MCP, internal Telegram or Discord) talk to Lead or the coordinator (Đầu mối), receive the items that need the owner, and answer in place according to role. Customer channels (widget, app channel, public bot) talk to the customer-facing Soot that the team attached; an item that needs the owner never carries its content there, and the customer sees only a pointer with no host-written text.

Each chat bot belongs to one team (or one Soot) and answers only with that team. An **internal** bot lets only linked people talk to it. An **external** bot lets customers talk, with limits, and is never the owner's chat channel. Lead lives in Nest and belongs to no team, so it is never the target of a bot; a team binding that has no coordinator yet has no target. Attaching a bot does not change the Soot's tools, packs, credentials or role. See places-settings.

## The surfaces

| Surface | For | Entry point | Source |
|---|---|---|---|
| Nest | Owner, members | Operator connection, or member connection | `desktop/` |
| CLI `soot` | Owner, scripts, CI | Operator token | `cmd/soot/` |
| Coding agent (MCP) | Owner, through Claude Code, Codex, Cursor | `sop_` token, stdio or `/v1/mcp` | `cmd/soot/mcp.go`, `internal/feature/mcpserver/` |
| Chat channel (Telegram, Discord) | Owner, members, customers | `/v1/channel/*` with an `sca_` credential | `internal/core/channel/`, adapter in Soot Forge `packs/chat-channels` |
| App channel / bridge | The project's backend, customers inside the app: each person's own conversation and shared places many readers see (channel-adapter §12) | SDK `@tofound/soot-sdk` | `contrib/sdk/typescript/src/{channel,livechat}` |
| Browser SDK and widget | Visitors on a website | `/public/v1/*` with `spk_`, `svs_` | `contrib/sdk/typescript/src/browser.ts`, `internal/core/transport/httpapi/public*.go` |

A new platform is an adapter that speaks the channel-adapter contract, not a change in core ([extensions.md](https://trysoot.com/docs/extensions/index.md)).

### Many channels, one rule set

Adding a chat channel adds no rule, because each layer knows one thing:

1. **The adapter** knows the platform's protocol. It translates every message into one shape: who spoke, in which place, whether the Soot was addressed, which message is being answered. It does not decide who may speak, never answers on its own and writes no text for people.
2. **The runtime** knows identity and place. It maps binding, place and speaker to a conversation, decides who may speak, and remembers where that conversation's answers go ([Who speaks, where, who handles it](#who-speaks-where-who-handles-it)).
3. **The Soot** sees only a conversation with messages. It answers; it never picks a channel or a destination.
4. **The way out** runs in reverse: the runtime addresses the answer and the adapter renders it the platform's way (a quoted reply, a pointer to a DM).

Permissions follow who owns the conversation (owner, member, visitor), not the kind of channel, so a new channel reuses the [shared rules](#shared-rules-for-every-surface).

Adapter code runs in three places with three levels of trust, so it ships in three forms. They cannot be one package; what they share is the host's rules and the vocabulary of the two contracts.

| Where the code runs | Form | For | Contract, credential |
|---|---|---|---|
| Beside the runtime, started by the deployment | The `soot-channel` process in the `chat-channels` pack (Soot Forge) | Platforms with a public bot API: Telegram, Discord. The operator enters a bot token and writes no code | channel-adapter, `sca_` |
| In the project's backend | A library: SDK `channel` | The project's own chat. Only the project's backend knows who the signed-in user is, and the messages live in its store | channel-adapter (remote binding), binding key |
| In the visitor's browser | The widget, or SDK `browser` | Visitors on a website. A browser cannot hold a server secret | live-chat-attention, `/public/v1/*`, `spk_` and `svs_` |

SDK `live-chat` is a second form for a project that already has its own chat system: a durable inbox/outbox bridge that runs in the project's backend.

## First path

There are three ways to start, all on the same runtime. Individual: install the Nest app (which bundles the runtime) or run `soot nest`, pick an AI provider, chat with Lead. Terminal: `soot spawn <dir>` creates a workspace and starts the runtime, `soot check --show` shows the resolved permissions, `soot run "..."` hands over a task. Project: `soot spawn --project <dir>` writes a scaffold (a `support` Soot, empty tool permissions, offline scripted AI, `docs/soot.md` for coding agents), then `soot serve`, add a connection in Nest, and the backend calls it with the SDK.

The scripted model only tests behavior locally; only a real chat turn proves the AI is ready (`/readyz` and `soot check` do not). Provider keys live in the host's vault; Soot does not read `.env`.

## Nest

Nest is a Tauri app (with a build that runs in the browser) written in React. All decisions live in the runtime; Nest projects state and sends answers back.

### Page structure

The rail is a list of modules in a registry (`desktop/src/app/registry/areas.ts`). The rail, the ⌘K command palette, `nest://` links and shortcuts are all generated from that same array, so adding a page means adding one line (nest-registry).

| Area | Its job |
|---|---|
| Hộp việc (Work inbox) | A wide window (over 760 px) always has the work list on the left (one `nav`): the Lead row first, then three fixed groups, Cần bạn ("Needs you"), Đang chạy ("Running") and Xong ("Done"), and the button that composes new work. Each piece of work is one row and one thread; opening a row opens its thread on the right, including the card of work that needs you. With no row chosen, the right side is the start view: the "Gửi tới" ("Send to") box (Lead by default; `@team` or `@Soot` sends directly), the "Bước tiếp" ("Next step") card for the first work that needs you, counts you can click, and the `home` pieces; no row is drawn twice. A narrow window (760 px or less) shows one pane at a time with a back button, and its start view carries the three groups itself. Each group is bounded, then "Xem cả N …" ("See all N …"); work nobody will run is one Cần bạn row, "N việc chưa có ai làm" ("N pieces of work nobody is doing"); a group keeps its grey skeleton until every read has answered. `home` pieces sit under the three groups; `project.tab` pieces are tabs of the project being viewed (goals and work, support…). It replaces Tổng quan (Overview) and Cuộc trò chuyện (Conversations); the old words and old links open Hộp việc |
| Đội Soot, Sản phẩm (Soot teams, Projects) | Each team's Soots, groups, permissions and channels; Soots grouped by project |
| Dữ liệu (Data) | Tables, memory, files, documents ([data.md](https://trysoot.com/docs/data/index.md)) |
| Kết quả (Results) | Finished tasks, cost, self-improvement ([evolution.md](https://trysoot.com/docs/evolution/index.md)) |
| Trang của Soot (Soot pages) | Pages declared by a pack and served by the runtime (pieces) |
| Cài đặt (Settings) | General, Server, Members (including who may approve), Screens, Kho khóa (the vault: every key in one place), AI, Permissions (which tools wait for approval), Channels (chat bots, website, SDK and the coding agent connection), Browser, Public knowledge, Updates |

Nest reveals itself gradually: the "Quản lý" ("Manage") group appears only when there are at least two Soots, a data page, or the owner turns it on; when hidden it can still be opened with ⌘K and links. A new user sees one main path: talk to Lead. Familiar jobs for a non-technical manager: see what the team does and approve at Hộp việc › Cần bạn ("Needs you"); hand over work in the "Gửi tới" box of Hộp việc; create a Soot, form a team, set a schedule by messaging Lead; take hard customers through the handoff items; put chat on a website at Đội Soot › team › Kênh (Channels).

### Lead and coordinator

Lead is the owner's assistant in Nest. Each server has one Lead, always named "Lead", outside every team. Only Lead has the admin tool (`nest-lead_manage`): create a Soot, form a team, set a schedule, change the model, grant data permissions. Its actions go through the same management actions as the manual screens, with the same revisions and receipts, so there is no second copy of configuration in a prompt. For reversible work Lead acts right away and reports with a link; deleting, widening permissions and raising budgets go to Cần bạn. Lead never says "created" before there is a receipt. The manual screens remain as the fallback path.

Each team has a **coordinator** (Đầu mối): the Soot that takes the team's first task, runs the team's schedules and answers the team's bot. The coordinator has no admin permissions. See [agents.md](https://trysoot.com/docs/agents/index.md) and contracts/lead.md.

### Several runtimes in one Nest

One Nest can connect to several runtimes (local machine, server, VM). Soots, teams and tasks are merged across all connections; the notion of a server shows up only when two Soots have the same name or when the owner filters by machine in the window bar. Each connection has its own operator key and identity.

Nest trusts each server separately (Settings › Server). `GET /v1/runtime` returns a durable `runtime_id`; when the identity changes, Nest drops the session and clears the cache. In the packaged build the operator key sits in the app's own store; in the browser build it lives only in page memory, never in a URL or web storage. A browser calling a server directly needs HTTPS and `browser_origins` (`soot schema deployment`). Reads that one screen asks for at the same time share one `GET /v1/reads` (each read still passes the key's own permissions; `work-reads` §4), so a first connection to a remote server costs two round trips: `GET /v1/runtime`, then one batch.

Disconnecting only stops observing; it does not stop or undo work on the server.

### Settings: save, apply, try

Configuration belongs to the server running the runtime, not to Nest. Nest shows the **saved** version and the **running** version separately because they can differ.

Four steps: validate (only asks the host; saves nothing, calls no model), save (one revision), apply (the host switches to that revision, possibly waiting for running work; only the "Đã áp dụng" ("Applied") label confirms the running version) and try (one real chat turn, only when the saved version equals the running version).

Writes carry `expected_revision` and a stable `request_id`. A conflict (409) keeps the draft so the person can read the new version and send again. If a response is lost, Nest asks for the receipt with a GET and does not repeat the POST. Secrets are entered only in Nest or in the CLI on the host, never pasted into chat because conversations are recorded; when needed, Lead opens a safe form.

## Cần bạn ("Needs you"): where people decide

The owner's attention is the scarcest resource. A Soot decides everything within its authority and looks for a person only when: the host chose to block the action (money, public posting, deletion); only a person can do it (logging in, plugging in a credential); it is outside its authority (price, date, promise); or nobody knows what happened (a write timed out). "Wants a second opinion" is not a reason. Each ask is one decision: a line saying what is needed and why, the options with the Soot's recommendation, what the Soot has already done, and a link to the object. The person picks a button or writes one line.

Nest has exactly one place for this, Hộp việc › Cần bạn: one list and one count shared by the rail badge and the window title. Each item carries one of three verbs: Answer (question, handoff), Review (decision, grant, an item that a need view draws as a screen or a layout the Soot proposes), Fix (error).

| Item (`kind`) | How it arises | The person answers with |
|---|---|---|
| Approval (`approval`) | A Soot calls a tool the host blocks | Approve and run, or Reject with a reason the Soot can read |
| Decision (`decision`) | `report_blocker` with options | Pick a button, or write one line of guidance. If `if_unanswered` allows silence, the default is chosen, only for reversible options |
| Handoff (`handoff`) | `report_blocker` without options | Do it themselves, then press "Đã xử lý" ("Handled") |
| Grant (`grant`) | A Soot asks for a data store or a pack it does not have | Grant and continue, or Reject |
| Contract line grant (`need`, id `contract-grant:<id>`, action `contract.grant`) | A Soot of team A is refused when it reads a table or writes a queue of team B, then asks with `report_blocker` grant kind `contract`; every request for the same line is one item | Grant and continue, or Reject with a reason (`POST /v1/settings/contract-grants/{id}`, `soot teams grant` / `decline`; [workspace.md](https://trysoot.com/docs/workspace/index.md#granting-a-contract-line-when-needed)) |
| Question (`question`) | `ask` in an interactive conversation | Answer |
| Unknown outcome (`unknown_outcome`) | A write whose success or failure is unknown | Check the target, then settle it |
| Error, schedule, missing credential, token budget, improvement proposal, outdated knowledge | The runtime detects it | Fix the cause, rerun, skip, apply or discard |
| Card (`card`) | A schedule step returns `raise`, costs no model | Pick a button. `id` is set only once, so the tool restates the card each tick without keeping state |
| Work sent in a loop (`mail_loop`) | Work passed back and forth between teams more than `mail.max_hops` times | Start it by hand, or discard |
| Work sent but not running (`mail_held`) | Work sent to a team with no coordinator (`team_needs_coordinator`), a team that takes only approved work (`inbox_hold`), a start that failed (`start_failed`), or a sending team that has used its daily count (`mail_rate_limited`); `payload.code` gives the reason | Pick a coordinator right in Hộp việc (the work then runs by itself), or start it by hand |
| Work not delivered (`mail_undelivered`) | Work sent to a team on another runtime has not arrived after 30 minutes, or was refused outright (`mail_not_granted`, `mail_unsupported`, ...) | Retry now (`POST /v1/workspace/mail/sync`), or fix the permission on the other runtime |
| Work waiting on you (`task_waiting`, id `task-waiting:<task>`) | An open task is blocked, waits for approval, is your own, or its last run stopped for a person or an error (`payload.state`: `waiting`, `blocked`, `failed`); there is no such item when another item already stands for the same task (a task thread need, a mail card, a schedule card) | Open the thread and answer, unblock it or run it again |
| Work with no one on it (`tasks_unowned`, id `tasks-unowned[:<project>]`) | A `todo` task nobody was assigned or nobody pressed Start on, not a mail; one item per project, with `payload.count` and up to 20 sample tasks (`payload.sample`), the rest read through the task list | Assign it to a team or a Soot and start it, or close it |
| A customer waits for your reply (`live_chat_handoff`, id `live-chat:<session>:<turn>`) | A Soot hands a customer chat (app, website, channel) to a person with `report_blocker` without options; the item belongs to the customer's tenant (live-chat-attention) | Reply to the customer right in Cần bạn, then give the chat back to the Soot (`POST /v1/sessions/{id}/member-messages`, `/control`; owner only, not through a scoped token) |

Each item has a `severity` (`error`, `warning`, `info`); group by that level, not by `kind`. Work created by evals is left out of the list unless asked for. List: `soot attention list`; answer: `soot attention answer`. The count is the number of items the runtime returns: Nest adds nothing from the task list, so the rail badge, the window title, the head of the Cần bạn group and `soot attention list` all show the same number.

Sending work to a team ([workspace.md](https://trysoot.com/docs/workspace/index.md#sending-a-task-a-task-is-a-message)) is `soot tasks send --to team:<id> "…"` or `POST /v1/workspace/tasks` with `deliver: true`; Lead sends with `send` in the workspace tool. The task has a `mail` field (route, state, `reply`); the milestones are the events `mail_delivered`, `mail_held`, `mail_reply`. In Nest, the "Gửi tới" box of Hộp việc sends work by this same route; sending to Lead is still a conversation (`mail_for_lead`). Sent work is a row in Đang chạy even before it arrives; a refusal code becomes one sentence and a fix button (`retarget`, `reconnect`, `coordinator`, `budget`, `start`, `sync`).

A pack declares `"approval": "operator"` by default for a tool, which is safe for an unknown host. The host owns the real decision through `grants.approvals` in the deployment, which overrides the pack in both directions; only the host's own deployment can loosen it. Nest shows every blocked tool in Settings › Permissions with 30 days of decisions, and suggests "Để Soot tự chạy" ("Let Soot run it") for a tool that was approved many times and never rejected: autonomy grows with what the owner has shown they accept. Operating-system notifications follow the same list: approvals and unknown outcomes notify immediately, other items notify once or are batched.

The same items reach the owner's linked DM in Telegram or Discord, with buttons for the options so they can be answered in place; for anything the buttons cannot resolve there is a link back to Nest.

## Shared rules for every surface

These rules live in code (`internal/core/authz`, `internal/core/channel`, `internal/core/conversation/attention.go`) and the contracts check them with fixtures.

| Rule | Content |
|---|---|
| One item, one answer | Once resolved anywhere, every other place sees it as handled |
| Ask where the work arises | Only `question` (and `decision` for a linked asker) appears in a shared place |
| Closed list | Other item types reach only the owner's places; a new type by default requires the `own` permission |
| Only the asker answers | Anyone else, including the owner, gets `403 not_asker` |
| Pointer, not content | An owner-only item meeting a customer or a shared place leaves at most one fixed line |
| Privacy | Secrets stay in Nest. Shared places and live chat receive the public projection. Per-person data is looked up from the conversation's place, not from words in a message |
| Who writes the text | The host writes the sentences for Nest and chat users. For customers the runtime sends only a code; the client writes the text |
| The Soot is the permission boundary | Tools, credential scope, approval config and grants decide what a run can do, the same on every surface |
| Anyone may speak | Linking is not a gate; abuse is handled with limits and a blocklist |

## Who speaks, where, who handles it

Every message comes from a **speaker** (`speaker`) with a stable id that does not expose the platform handle. A conversation is keyed by **place**, not by person: a DM, a group or thread, a bridge thread, a widget session. Everyone in the place sees the Soot's replies, so the transcript is shared and labeled with the speaker. While a run is in progress, a new message from the same speaker is absorbed into that run (steering the run); a message from someone else is queued as its own run. An open question belongs to the asker: a message from someone else does not answer it and does not close it. This rule is in `internal/core/conversation/steer.go`, so the host chat, the bridge and the widget behave the same.

**Linking** replaces pairing: anyone in a shared place can talk to the Soot without doing anything first. Linking (a one-time code from Nest, sent to the bot) only says "this chat account is that Nest person", so their DM receives owner items and their button presses carry the right role. People who have not linked are limited per person and per binding pool (pool `0` means only linked people may speak), plus a blocklist; past the limit they get one notice and then silence. Default numbers: `internal/core/channel/places.go`, `internal/core/config/channels.go`.

One function, `Authorize(principal, place, action, item)` (`internal/core/authz/authorize.go`), answers for every surface. It runs again on every press and does not cache roles.

| Role | Who | Scope |
|---|---|---|
| `owner` | Operator connection, the owner's chat account | Everything |
| `approver` | A member the owner granted (all Soots or some) | `handle` and `approve` for the granted Soots |
| `member` | A key with `read_team` and `control` | `handle` handoffs of the Soots in the key |
| `anyone` | Unlinked people, customers, visitors | Speak only, and answer their own question |

`handle` is the team's work (handoffs, decisions, taking over live chat). `approve` is approving tools and settling unknown outcomes. `own` is everything else of the owner's: grants, budgets, channels, roles. A member's permissions are never wider than their key.

| Place | Owner-only items |
|---|---|
| Nest | Yes, by role |
| DM of a linked person | Yes, if the role can handle it |
| `owner_chat` (a chat group the owner designates with the `/owner` code) | Yes, in place of the owner's DM. Everyone sees the title and options; secrets and diffs stay in Nest. Anyone without enough permission who presses gets `403 not_authorized` |
| Shared place, live chat | Never; at most a pointer |

## Projects plug into Soot (SDK)

A project uses `@tofound/soot-sdk` (`contrib/sdk/typescript/`; usage is in its README) to plug into the same runtime. The main paths:

| Want | Use | Credential |
|---|---|---|
| A backend chats with a Soot on behalf of a logged-in user | Conversation API, SDK `client` | `conversation_clients` |
| An outside system reports work (alert, webhook) | `POST /v1/events` through your adapter | operator token, backend only |
| Hand over a background task and receive a structured result | `/v1/jobs`, SDK `jobs`, `soot jobs` | operator or `sop_` with scope `jobs` |
| A drive-by visitor chats on a website | Widget or SDK `browser` | `spk_` and `svs_` |
| The app's own chat is the interface | SDK `channel` or `live-chat` | binding key |
| A Soot tool calls your API and needs to know who is speaking | Principal token | the host's JWKS |

Concepts to know:

- **Run.** Sending a message creates a run that is `queued`, then `running`, then `completed`, `failed` or `stopped`; `waiting_input` means the Soot asked the user again and has stopped executing, and the answer is a new message. When a POST loses its response, keep the conversation ID, request ID and run ID and reconcile with a GET; resending as a new run would skip the unknown state. Run errors have stable codes and do not expose the provider's raw error.
- **Event.** `(soot, source, subject)` identifies the conversation; `id` is the retry key. Core has no receiver per vendor: your adapter authenticates the webhook and then normalizes it. A 202 response means durably received, not finished. Core has no case or takeover for events; that belongs to packs. `text` is at most 64 KiB of UTF-8 and the Soot reads it whole; a longer one is refused with 400 naming the limit.
- **Job.** One background run of a Soot or team, with an `idempotency_key`, a JSON result and a JWS-signed callback (verify with the host's JWKS). A job is only an entry point; internal tracking belongs to [workspace.md](https://trysoot.com/docs/workspace/index.md). Contract: jobs. The model reads `task`, `input` and `output_schema` whole, inline in the run (at most 60 KiB of run text); more is refused with `invalid_job` naming the limit, never cut.
- **Public web.** A customer chats right on the website without going through your backend: `spk_` plus a challenge exchanged for a short-lived `svs_` session. Because the key is public, the customer is bound by the client's budget and policy, and the Soots exposed may use read tools only. The widget (source in Soot Forge `packs/live-chat/widget/`, served by the runtime at `/public/widget/*`) keeps credentials out of the host page in an iframe; adopters who want their own UI use the SDK `browser`, same model.
- **App channel.** The SDK `channel` is the server-mode adapter of channel-adapter: the host keeps message merging, turns and owner, the SDK does not reply by itself, and it acks only after writing to your store. The SDK `live-chat` is a durable inbox/outbox bridge: a send failure becomes `uncertain` and is never resent automatically.
- **Principal token.** A short-lived JWS for each tool call, so your API knows the person in the conversation, whom the model neither chooses nor sees: principal-token.

## Live chat and customers

A customer can answer only their own **questions**. A question shows as a card with buttons, shows once, and closes with the chosen result. Work that needs the owner (approval, handoff, decision) does not reach the customer; the customer receives a pointer that is just a code (`team`, `approval`, `not_ready`, `unavailable`) and the client writes the text, or shows nothing if the Soot already replied on its own. The runtime does not write text for customers.

Design decisions worth remembering: this is a sibling contract of `channel-adapter` (same item vocabulary, two different trust boundaries, because a customer is not a Nest user); the asker's permission is enforced by the runtime, not by the client; and the widget has no rules of its own, every attention state lives in the SDK `browser`, so changing a rule only needs a runtime upgrade.

When a real person is needed, a member with `read_team` and `control` sees the live-chat conversation in Nest, takes over, replies publicly under their own name, or messages the Soot privately (the customer does not see it). While a person holds the conversation, new customer messages are still stored and shown to the member, and the Soot does not run on its own.

Current status: the runtime already projects question cards, results and pointers (`internal/core/conversation/attention.go`, event `attention.pointer`, capability `live-chat-attention-v1`). The live-chat-attention and places-settings contracts have moved to the `soot-cs-engine` project (`internal/test/guard/cs_allowlist.txt` keeps a copy here until removal); do not edit the copy. Customer care (console, handoff policy) is an extension, not part of core: [extensions.md](https://trysoot.com/docs/extensions/index.md). The old `cs/` bridge has been deleted; production projects use the SDK's app channel.

## CLI and coding agent

`soot` is the surface for scripts, CI and people who prefer a terminal; every admin operation is the same management action as in Nest. `soot --help` lists commands.

The owner also controls Soot from Claude Code, Codex or Cursor. `soot mcp` (stdio, local machine) or `<server>/v1/mcp` (HTTP, remote server) generates tools from the same action registry as the CLI. A scoped `sop_` token (`read`, `jobs`, `manage`, `data`) is created in Settings › Channels › Coding agent connection or with `soot tokens`, is shown only once, and is its own credential (`SOOT_MCP_TOKEN`), not an operator token. People keep the decisions: approving, granting permissions, releasing a held item and creating or revoking tokens are **not** in MCP and are rejected with a scoped token (`approval_needs_person`). Your coding agent cannot give the `support` Soot permission to edit files or run a shell on its own. Contract: mcp-operator.

## Sent work across surfaces

Who may hand work to a team depends on who owns the conversation, not on the kind of channel. A conversation in the owner's workspace (tenant `operator` and not a live chat) gives the Soot a writable `task` tool and `send`. That is a chat in Nest, the owner's DM with a paired bot on Telegram or Discord, and the owner's chat through a coding agent. Read-only runs cannot send: evals, dry runs and the Lead's brief. Customers, members and apps connected through the SDK never send work into the owner's workspace. All three places read one function, `conversation.InOwnerWorkspace` (`internal/core/conversation/reach.go`).

Work a Soot sends from the owner's chat is the Soot's mail, not the person's. So every limit still applies: the hops in a chain, the daily bound, a team that holds its inbox.

The reply comes back where the person asked. When a Soot sends or starts work from a chat outside Nest (a paired DM), once the team replies the Soot gets one more turn in that chat to tell the person, as when the Soot chose `wait` itself. Each reply wakes it once. This does not apply while the Soot works for a teammate, and a `needs_person` reply does not wake it. Function: `conversation.AnswersOutsideNest`.

While it waits, a person on any surface is not left blind. When the work stops to wait for someone in the chain (even on another server), when it passes `due`, or when it runs long (reported less and less often), the host hands the sender's side one line. A customer's chat that came through an intake gets one turn to tell the customer where the work is. A Soot that sent with `wait` gets one turn in that thread. Nest reads it from the task log (`mail_progress`). The line says only where the work is; it does not reveal the team or the person. The shared rule is in work-mail D6.

A coding agent has the same single door for sending work: the MCP tool `task_send` (same scope as `task_start`) calls the same send that `POST /v1/workspace/tasks` with `deliver: true` and `soot tasks send` call. The sender is recorded as `mcp:<token>`.

With a member key, Hộp việc is the conversations that key opened (`GET /v1/workspace/inbox`). A member sees no task, nothing of the owner's work, another member's or a customer's, also through `GET /v1/reads`. "Gửi tới" lists only the Soots and teams the key may talk to, and a send opens a conversation with that Soot. Every other `/v1/workspace/*` route stays the owner's; a member's `POST /v1/workspace/tasks` gets `403`.

From a customer to work is a person's step. A customer's hand-off card in Cần bạn has a "Giao cho đội" button. It opens Hộp việc's composer filled with the Soot's summary of what it needs (a general title when it left none) and one line saying the work comes from a customer chat, with where the customer wrote. Nest copies none of the customer's messages, not even their first one, and carries no conversation id. The owner reads it, picks "Gửi tới" and sends; the card stays in Cần bạn.

The owner can also open a door ahead of time for one kind of report: an intake (contract intake). In the deployment, the owner declares the report's fields, which Soot takes reports and which team on this runtime handles them. That Soot gets one more tool, `file_report`. It is not `send`: a customer still cannot send work, only go through the door the owner opened, to the team the owner chose. The mail to the team carries content only: the fields, the Soot's summary, the reporter's own words if any, and how many people reported it. The runtime keeps where to answer each reporter with the work, not in the mail. The receiving team never learns where a report came from: no conversation id, no name, no channel. A report of the same subject joins the open work. When the work is done, failed or blocked, the runtime wakes the Soot that took the reports inside each conversation that reported, one turn per conversation. Who gets answered where: [Who speaks, where, who handles it](#who-speaks-where-who-handles-it); what the runtime, adapters and packs each own: [Boundaries: who owns what](#boundaries-who-owns-what).

When you add a new surface:

1. Which tenant do its conversations belong to? Only the owner is `operator`; everyone else is in their own tenant.
2. Add no rule by `Source.Kind`: sending work reads `InOwnerWorkspace`, the reply in the chat reads `AnswersOutsideNest`.
3. Every door that sends work calls the engine's send (`SendTask`, `StartTask`); write no second send path.
4. Add rows for the surface to `TestOpSendOnlyInWorkspaceRuns`, and a read test with a key that is not the owner's.

## Boundaries: who owns what

The runtime (core) holds permissions, identity, choice of where to send, and limits. An adapter (Soot Forge, or one you write with the SDK `channel`) holds the platform protocol, message format and dedup. A client (widget, SDK, the project's app) writes the text for customers. A pack (extension) holds customer-care behavior and handoff policy. Host and Soot config decide which tools wait for approval and which credential touches which tool. Nest only displays, drafts and keeps unsaved changes.

Things surfaces deliberately do not do: decide who may answer; derive permissions from the channel type; keep a second configuration in the UI or a prompt; pass secrets through chat; open an operator connection into customer transcripts.

## Not yet available

Messenger, Zalo and email adapters. Lead exists only in Nest and is not a bot target. Approving with a button in a shared place is deliberately not built.
