@agent-native/core 0.122.3 → 0.123.0

package/docs/content/template-dispatch-messaging-routing.mdx

@@ -0,0 +1,114 @@
+---
+title: "Messaging, routing, and approvals"
+description: "How Slack, Microsoft Teams, Discord, Telegram, WhatsApp, email, and A2A requests all land in one Dispatch inbox, get routed to the right agent, and can be gated behind an approval."
+---
+
+# Messaging, routing, and approvals
+
+Dispatch is the one inbox for every channel your team talks to the agent from, and the router that decides whether it answers directly, hands the request to a domain agent, or waits for a human to approve it first. This page is for anyone connecting a channel, tuning routing, or reviewing what needs approval.
+
+## Central inbox {#inbox}
+
+Slack, Microsoft Teams, Discord interactions, Telegram, WhatsApp Cloud API, and provider-webhook email all land in one place, alongside inbound A2A requests from other agents. The Dispatch agent triages each one and either handles it directly or delegates it. See [Messaging](/docs/messaging) for how to wire a channel into your workspace.
+
+## Orchestrator vs specialist {#orchestrator}
+
+Dispatch does _not_ try to be the email app or the analytics app. When someone asks "summarize last week's signups," Dispatch calls the analytics agent over [A2A](/docs/a2a-protocol) and returns the answer. When someone asks "draft a reply to Alice," Dispatch calls the mail agent. The chat is set up as a router: it reads `AGENTS.md` and routes to specialist sub-agents or remote A2A agents rather than answering domain questions itself.
+
+<Diagram id="doc-block-dispatch3" title={"Routing and approval"} summary={"Every channel lands in the same inbox. The orchestrator either handles a request directly, delegates it to a domain agent over A2A, or — for a gated action — sends it to the approval queue first."}>
+
+```html
+<div class="dsp-route-flow">
+  <div class="diagram-col">
+    <div class="diagram-node">Slack · Teams · Discord</div>
+    <div class="diagram-node">Telegram · WhatsApp</div>
+    <div class="diagram-node">Email webhook · A2A request</div>
+  </div>
+  <div class="diagram-arrow diagram-muted" aria-hidden="true">&rarr;</div>
+  <div class="diagram-panel center" data-rough>
+    <span class="diagram-pill accent">Dispatch inbox &amp; orchestrator</span
+    ><small class="diagram-muted">triage</small>
+  </div>
+  <div class="diagram-arrow diagram-muted" aria-hidden="true">&rarr;</div>
+  <div class="diagram-col">
+    <div class="diagram-node">Handled directly</div>
+    <div class="diagram-node">
+      Delegated to a domain agent<br /><small class="diagram-muted"
+        >over A2A</small
+      >
+    </div>
+    <div class="diagram-node">
+      <span class="diagram-pill warn">Gated action</span><br /><small
+        class="diagram-muted"
+        >&rarr; Approvals queue</small
+      >
+    </div>
+  </div>
+</div>
+```
+
+```css
+.dsp-route-flow {
+  display: flex;
+  align-items: center;
+  gap: 12px;
+  flex-wrap: wrap;
+}
+.dsp-route-flow .diagram-col {
+  display: flex;
+  flex-direction: column;
+  gap: 8px;
+}
+.dsp-route-flow .diagram-arrow {
+  font-size: 20px;
+  line-height: 1;
+}
+.dsp-route-flow .center {
+  display: flex;
+  flex-direction: column;
+  align-items: center;
+  gap: 4px;
+}
+```
+
+</Diagram>
+
+## Connecting Slack, Teams, Discord, Telegram, WhatsApp, and email {#connecting}
+
+Wire up each channel from Dispatch's **Messaging** page — see [Messaging](/docs/messaging) for the setup steps for each platform. Once an external sender messages the agent, Dispatch can link them to a workspace user with a one-time `/link TOKEN` code; see the Identities section on [Operating the workspace](/docs/template-dispatch-operations#identities).
+
+## Approval flow {#approvals}
+
+Dispatch can gate its own durable, workspace-wide changes behind a second admin's review — it does not gate arbitrary business actions inside domain apps (a Mail send or a Forms webhook has its own risk controls, not this queue). From Dispatch's **Approvals** page:
+
+- Toggle **Require approval for durable changes** on or off. When it's on, it applies to saved destinations, shared Dream proposals, All-app agent resources, and Dispatch settings.
+- Set the list of **approver emails** who can review requests. This requires a team workspace, not a solo one.
+- The pending/recent request list shows each request's summary, status, and who requested it, with **Approve** and **Reject** buttons for anything still pending.
+
+Agents use the same workflow through actions: `get-dispatch-settings` and `set-dispatch-approval-policy` manage the policy and approver list; `list-dispatch-approvals` lists requests; `approve-dispatch-change` and `reject-dispatch-change` resolve one.
+
+## Delivery investigation {#destinations}
+
+The **Destinations** page (`/destinations`) is where you save reusable delivery targets — a Slack channel, a Telegram chat, or an email address, each with a name, platform, destination id, and an optional thread/topic reference and notes — and trace whether a scheduled or agent-sent message actually went out.
+
+- Each saved destination can send a quick test message inline before you wire a real job to it.
+- A queue-health panel shows whether the delivery queue is processing normally, since Dispatch delivers messages through a queue-and-processor pattern rather than a fire-and-forget call after the request that triggered them.
+
+Agents manage destinations through `list-destinations`, `upsert-destination`, `delete-destination`, and send through them with `send-platform-message`.
+
+<WireframeBlock id="doc-block-dispatch4">
+  <Screen
+    surface="desktop"
+    html={
+      "<div style='display:flex;flex-direction:column;gap:14px;padding:18px;min-height:520px;box-sizing:border-box'><div style='display:flex;align-items:center;gap:10px'><h1 style='margin:0'>Destinations</h1><span class='wf-pill accent'>3 saved</span><div style='flex:1'></div><button class='primary'>Add destination</button></div><div class='wf-card' style='display:flex;flex-direction:column;gap:8px'><div style='display:flex;justify-content:space-between;align-items:flex-start'><div><strong>Daily digest channel</strong><br/><span class='wf-muted'>slack &middot; C0123456789</span></div><button>Delete</button></div><span class='wf-muted'>&rsaquo; Send a test message</span></div><div class='wf-card' style='display:flex;flex-direction:column;gap:8px'><div style='display:flex;justify-content:space-between;align-items:flex-start'><div><strong>On-call Telegram</strong><br/><span class='wf-muted'>telegram &middot; 123456789</span></div><button>Delete</button></div><span class='wf-muted'>&rsaquo; Send a test message</span></div><div class='wf-card' style='display:flex;flex-direction:column;gap:10px'><strong>Add destination</strong><input value='Name'/><input value='Platform: slack'/><input value='Destination id'/><button class='primary'>Save destination</button></div></div>"
+    }
+  />
+</WireframeBlock>
+
+## What's next
+
+- [**Dispatch**](/docs/template-dispatch) — the workspace control plane overview
+- [**Secrets, integrations, and workspace connections**](/docs/template-dispatch-vault-integrations) — the vault and provider integrations
+- [**Operating the workspace**](/docs/template-dispatch-operations) — jobs, Dreams, and the operator console
+- [**Messaging**](/docs/messaging) — full per-platform wiring steps
+- [**A2A Protocol**](/docs/a2a-protocol) — how Dispatch delegates to specialist agents

package/docs/content/template-dispatch-operations.mdx

@@ -0,0 +1,160 @@
+---
+title: "Operating the workspace: jobs, Dreams, and the operator console"
+description: "Recurring jobs, the Dreams memory review loop, the /operations console's Monitoring and Database tabs, and where to look for thread history, change history, and usage."
+---
+
+# Operating the workspace: jobs, Dreams, and the operator console
+
+Once Dispatch is coordinating a workspace, this is where you keep it healthy day to day: recurring jobs, the Dreams review loop that watches how agents are actually doing, and the operator console for monitoring, database admin, thread debugging, audit history, and usage. It's for whoever runs the workspace.
+
+## Scheduled jobs hub {#jobs}
+
+Cross-app [recurring jobs](/docs/recurring-jobs) live here: "every weekday at 7, pull yesterday's key metrics from analytics and draft a morning summary email." The **Automations** page shows enabled state, last run, next run, and last error for every job, sourced from the underlying `jobs/*.md` schedules, and lets you enable or disable a job without editing files by hand. A failed job's row links straight to **Troubleshoot in Thread Debug**. To create one, describe what you want automated in the composer — personal or organization scope — and the agent turns it into a job with `manage-automations`.
+
+## Dreams {#dreams}
+
+Dreams are Dispatch's review loop for agent memory. A dream pass looks over existing agent runs, thread debug data, feedback, evals, and repeated tool failures, then writes a report with proposed changes. The proposals can target personal memory, shared `LEARNINGS.md`, workspace instructions, workspace skills, workspace knowledge, workspace agents, or recurring jobs, but shared and workspace-level changes stay reviewable rather than being applied silently.
+
+Dream proposals are checked against the personal memory index, existing `memory/*.md` files, and shared `LEARNINGS.md` before they are saved. Duplicate lessons are skipped in the report, while likely stale personal memories are updated in place instead of producing parallel notes. Within a report, Dreams also deduplicate repeated evidence by thread, signal type, and normalized quote, strip injected context from user-correction detection, and summarize raw eval/tool rows into human-readable bullets before they appear in proposal text. When a pass finds signals but intentionally creates no proposals, the report includes guardrail notes explaining which evidence was suppressed.
+
+When Dispatch approval policy is enabled, applying a shared or team-wide dream proposal creates a pending approval request instead of writing immediately — see [Messaging, routing, and approvals](/docs/template-dispatch-messaging-routing#approvals). Creating, updating, or deleting an All-app workspace resource also queues an approval request. Personal memory proposals and selected-only resource edits can still be applied directly after review.
+
+Use Dreams when you want to answer questions like "what did agents keep getting wrong this week?", "what should we remember?", or "which repeated lesson deserves a skill?" Inbound Slack, email, Telegram, WhatsApp, and web-derived evidence is treated as untrusted input, so proposals from those sources require review and provenance before they affect shared memory. Workspace-instruction proposals require durable evidence spanning at least two threads or two source apps; eval-only noise, account setup issues, quota limits, and single-app UI wording corrections stay out of global instructions.
+
+<Diagram id="doc-block-dispatch5" title={"Dreams input pipeline"} summary={"Evidence from untrusted sources is truncated and redacted before it's compiled into a report, and the scan itself runs under Zod-validated, clamped limits."}>
+
+```html
+<div class="dsp-dreams-flow">
+  <div class="diagram-col">
+    <div class="diagram-node">Threads</div>
+    <div class="diagram-node">Feedback &amp; evals</div>
+    <div class="diagram-node">Tool failures</div>
+  </div>
+  <div class="diagram-arrow diagram-muted" aria-hidden="true">&rarr;</div>
+  <div class="diagram-box" data-rough>
+    Truncate &amp; redact<br /><small class="diagram-muted"
+      >bounded snippet length · secrets redacted</small
+    >
+  </div>
+  <div class="diagram-arrow diagram-muted" aria-hidden="true">&rarr;</div>
+  <div class="diagram-box" data-rough>
+    Strip injected context<br /><small class="diagram-muted"
+      >drop text after a fake &lt;context&gt; marker</small
+    >
+  </div>
+  <div class="diagram-arrow diagram-muted" aria-hidden="true">&rarr;</div>
+  <div class="diagram-panel center" data-rough>
+    <span class="diagram-pill accent">Dream report</span
+    ><small class="diagram-muted">proposals + source health</small>
+  </div>
+  <div class="diagram-arrow diagram-muted" aria-hidden="true">&rarr;</div>
+  <div class="diagram-col">
+    <div class="diagram-node">Review sheet</div>
+    <div class="diagram-node">
+      Apply<br /><small class="diagram-muted">or queue for approval</small>
+    </div>
+  </div>
+</div>
+```
+
+```css
+.dsp-dreams-flow {
+  display: flex;
+  align-items: center;
+  gap: 12px;
+  flex-wrap: wrap;
+}
+.dsp-dreams-flow .diagram-col {
+  display: flex;
+  flex-direction: column;
+  gap: 8px;
+}
+.dsp-dreams-flow .diagram-box {
+  display: flex;
+  flex-direction: column;
+  gap: 4px;
+}
+.dsp-dreams-flow .diagram-arrow {
+  font-size: 20px;
+  line-height: 1;
+}
+.dsp-dreams-flow .center {
+  display: flex;
+  flex-direction: column;
+  align-items: center;
+  gap: 4px;
+}
+```
+
+</Diagram>
+
+### Dream input validation boundaries
+
+Because evidence is collected from external, untrusted sources (such as chat transcripts, webhooks, and third-party integrations), the Dream pipeline limits what a single message can do to a report:
+
+- **Bounded evidence length:** evidence snippets are truncated before they're written into a proposal — roughly 120–260 characters for most quoted evidence, up to 1,200 characters for full message/row text — so one oversized message can't dominate a report.
+- **Secret redaction:** secret-looking substrings — `sk-...` keys, `Bearer ...` tokens, long base64 blobs — are redacted out of evidence text before it's compiled.
+- **Injected-context stripping:** a user message containing a fake `<context>` marker has everything after that marker dropped before the pipeline checks it for correction or frustration signals, so a message can't smuggle instructions into what looks like a genuine user correction.
+- **Clamped scan parameters:** candidate limit, per-source/per-thread timeouts, and concurrency are Zod-validated and clamped at the action boundary (for example `limit` 1–50, `sourceTimeoutMs` up to 60s, `threadConcurrency` up to 10), so a malformed or oversized request can't force an unbounded scan.
+
+In the Dispatch UI, open **Dreams** to run a manual pass, review candidate threads, inspect the report, and open each proposal's review sheet before applying or rejecting it. Use **Settings** to edit the recurring cron schedule, source scope, timeout/concurrency limits, candidate limit, and minimum candidate threshold; use **Ensure schedule** after saving when you want the `jobs/dispatch-dream.md` recurring job materialized from those settings. The review sheet shows approval behavior, the current target content, proposed content, and source evidence. Agents use the same workflow through actions:
+
+- `list-dream-candidates` finds recent threads with grounded signals such as explicit user corrections, failed runs, tool errors, feedback, eval failures, and successful checkpointed workflows. Pass `sourceId: "all"` or `sourceIds` to scan multiple thread-debug sources; `sourceTimeoutMs`, `sourceConcurrency`, `sourceStartStaggerMs`, `threadConcurrency`, and `threadTimeoutMs` keep production scans partial and bounded, and the response includes per-source health.
+- `create-dream-report` creates the report and pending proposals. Multi-source reports include a Source Health section so partial scans are visible during review. Repeated corrections and recurring failures can become workspace-resource proposals such as `workspace-instruction`; repeated successful checkpointed workflows can become `workspace-skill` proposals.
+- `get-dream-settings` and `set-dream-settings` read and update the recurring dream schedule, source scope, timeout/concurrency controls, limit, and minimum candidate threshold.
+- `get-dream`, `preview-dream-proposal`, `apply-dream-proposal`, and `reject-dream-proposal` handle review.
+- `ensure-dream-job` creates the safe recurring dream job once manual reports are useful.
+
+The Dispatch template's local action runner also exposes packaged Dispatch actions, so in development you can run the same workflow from `apps/dispatch`:
+
+```bash
+pnpm action get-dream-settings
+pnpm action set-dream-settings --enabled true --schedule "0 9 * * 1" --allSources true --limit 8
+pnpm action create-dream-report --allSources true --sourceTimeoutMs 30000 --limit 8
+```
+
+## The Operations console {#operations}
+
+`/operations` is the focused operator console. It has two tabs, and both reuse existing framework surfaces rather than building new ones:
+
+<Table
+  id="doc-block-dispatch6"
+  title="Operations tabs"
+  columns={["Tab", "Reuses", "What it shows"]}
+  rows={[
+    [
+      "Monitoring",
+      "Shared observability dashboard",
+      "Traces, conversations, evaluations, experiments, and feedback",
+    ],
+    [
+      "Database",
+      "Code-mode database admin (DbAdminPage)",
+      "Browse and edit the workspace's SQL tables directly",
+    ],
+  ]}
+/>
+
+Use `navigate --view operations|monitoring|observability|database` or `view-screen` to align the agent with whichever tab is open.
+
+## Thread Debug, Audit, and Metrics {#advanced}
+
+Use these for concrete thread, change-history, and usage investigations instead of building a new tracker.
+
+- **Thread Debug** (`/thread-debug`) searches across the current or a configured thread-debug source by title, preview, message text, tool name, or owner email — or you can paste a thread id directly. A selected thread opens with **Transcript**, **Runs**, **Internals** (debug runs, trace summaries and spans, feedback and evals), and **Raw** tabs. Agents use `list-agent-thread-sources`, `search-agent-threads`, and `get-agent-thread-debug`.
+- **Audit** (`/audit`) is a flat, chronological change history — summary, actor, action, and timestamp — for routes, settings, and approvals. Agents read it with `list-dispatch-audit`.
+- **Metrics** (`/metrics`) is the workspace-level LLM usage dashboard: total spend (or Builder.io credit spend), calls, active users, workspace apps, and chat threads, broken down by app, model, and work type, plus a daily activity chart, a per-app access table with last-activity, a per-user table, and a recent-calls table. Pick a 7/30/90-day window. Agents read it with `list-dispatch-usage-metrics`.
+
+## Tools catalog and Identities {#identities}
+
+`/tools` is the shared Extensions catalog — the sandboxed mini-app widgets available in the workspace — reused inside Dispatch rather than rebuilt.
+
+`/identities` links an external sender to a workspace user. Generate a Slack or Telegram link token, have the person send `/link TOKEN` from that platform, and the two identities are connected from then on. Agents manage this with `create-link-token` and `list-linked-identities`.
+
+## What's next
+
+- [**Dispatch**](/docs/template-dispatch) — the workspace control plane overview
+- [**Secrets, integrations, and workspace connections**](/docs/template-dispatch-vault-integrations) — the vault and provider integrations
+- [**Messaging, routing, and approvals**](/docs/template-dispatch-messaging-routing) — channels and the approval queue
+- [**Recurring Jobs**](/docs/recurring-jobs) — scheduled tasks Dispatch runs
+- [**Observability**](/docs/observability) — the dashboard the Monitoring tab reuses

package/docs/content/template-dispatch-vault-integrations.mdx

@@ -0,0 +1,316 @@
+---
+title: "Secrets, integrations, and workspace connections"
+description: "How Dispatch's secrets vault, reusable provider integrations, and Workspace Connections let one credential serve every app in the workspace — plus how the agent can query a connected provider's raw API on demand."
+---
+
+# Secrets, integrations, and workspace connections
+
+Dispatch is where your workspace's credentials live: API keys, OAuth tokens, and third-party accounts get saved once here, then granted to whichever apps need them. This page covers the vault, reusable provider integrations, and Workspace Connections — the newer flow the agent uses to set up, grant, and directly query a connected provider.
+
+## Secrets vault {#vault}
+
+A central store for API keys, OAuth tokens, and shared credentials. Apps in the workspace resolve secrets from Dispatch instead of duplicating them in every `.env`.
+
+- A secret is saved once, under a `credential_key` name other apps reference — never the app's own copy.
+- A **grant** gives one named app access to a secret. Requesting access when you don't have a grant creates a **request** that an admin reviews and approves or denies.
+- Every use is written to an **audit log**: who used which secret, from which app, and when.
+
+<DataModel
+  id="doc-block-1pitn7l"
+  title="Secrets vault schema"
+  summary={
+    "Secrets are stored once; grants give a named app access; requests + reviews gate sensitive access; the audit log records who used which secret when. Defined in @agent-native/dispatch (packages/dispatch/src/db/schema.ts)."
+  }
+  entities={[
+    {
+      id: "secrets",
+      name: "vault_secrets",
+      note: "Stored credential values",
+      fields: [
+        {
+          name: "id",
+          type: "text",
+          pk: true,
+        },
+        {
+          name: "owner_email",
+          type: "text",
+        },
+        {
+          name: "org_id",
+          type: "text",
+          nullable: true,
+        },
+        {
+          name: "name",
+          type: "text",
+        },
+        {
+          name: "credential_key",
+          type: "text",
+        },
+        {
+          name: "value",
+          type: "text",
+          note: "secret value",
+        },
+        {
+          name: "provider",
+          type: "text",
+          nullable: true,
+        },
+      ],
+    },
+    {
+      id: "grants",
+      name: "vault_grants",
+      note: "Per-app access grant",
+      fields: [
+        {
+          name: "id",
+          type: "text",
+          pk: true,
+        },
+        {
+          name: "secret_id",
+          type: "text",
+          fk: "vault_secrets.id",
+        },
+        {
+          name: "app_id",
+          type: "text",
+        },
+        {
+          name: "granted_by",
+          type: "text",
+        },
+        {
+          name: "status",
+          type: "text",
+        },
+      ],
+    },
+    {
+      id: "requests",
+      name: "vault_requests",
+      note: "Access request + review",
+      fields: [
+        {
+          name: "id",
+          type: "text",
+          pk: true,
+        },
+        {
+          name: "credential_key",
+          type: "text",
+        },
+        {
+          name: "app_id",
+          type: "text",
+        },
+        {
+          name: "reason",
+          type: "text",
+          nullable: true,
+        },
+        {
+          name: "status",
+          type: "text",
+        },
+        {
+          name: "reviewed_by",
+          type: "text",
+          nullable: true,
+        },
+      ],
+    },
+    {
+      id: "audit",
+      name: "vault_audit_log",
+      note: "Who used which secret when",
+      fields: [
+        {
+          name: "id",
+          type: "text",
+          pk: true,
+        },
+        {
+          name: "secret_id",
+          type: "text",
+          fk: "vault_secrets.id",
+          nullable: true,
+        },
+        {
+          name: "app_id",
+          type: "text",
+          nullable: true,
+        },
+        {
+          name: "action",
+          type: "text",
+        },
+        {
+          name: "actor",
+          type: "text",
+        },
+      ],
+    },
+  ]}
+  relations={[
+    {
+      from: "secrets",
+      to: "grants",
+      kind: "1-n",
+      label: "granted via",
+    },
+    {
+      from: "secrets",
+      to: "audit",
+      kind: "1-n",
+      label: "use recorded by",
+    },
+  ]}
+/>
+
+## Reusable provider integrations {#integrations}
+
+One place to connect provider accounts, track credential references, and grant apps access. Dispatch owns provider identity and app grants; domain apps still own app-specific source choices, such as Brain's Slack channel allow-list or Analytics' metric/dashboard configuration. Connect a provider once from Dispatch's **Integrations** page and grant it to Brain, Analytics, Mail, or Dispatch itself without copying raw secrets between apps.
+
+## Ad hoc provider access {#provider-api}
+
+A grant is not a capability limit. When a canned action doesn't cover the exact endpoint, filter, or pagination mode you need, three actions give the agent a safe escape hatch onto the provider's real HTTP API:
+
+- **`provider-api-catalog`** lists which providers are configured — Slack, GitHub, Notion, HubSpot, Gmail, Google Calendar, Stripe, Jira, and others — with base URLs, auth style, docs/spec URLs, placeholders, and examples. It never returns secret values.
+- **`provider-api-docs`** fetches a provider's public docs, spec, or changelog page and can search the extracted content for the exact endpoint or field you need.
+- **`provider-api-request`** makes the actual authenticated call: method, path, query, headers, and body, constrained to the provider's host with credentials injected automatically. Private/internal URLs are blocked and secrets are redacted from responses.
+
+<AnnotatedCode
+  id="doc-block-dispatch2"
+  title="provider-api-request call"
+  filename="provider-api-request call"
+  language="json"
+  code={
+    '{\n  "provider": "slack",\n  "path": "/conversations.history",\n  "query": { "channel": "C0123456789", "limit": 50 },\n  "stageAs": "support-channel-last-50"\n}'
+  }
+  annotations={[
+    {
+      lines: "2",
+      note: "`provider` is one of the configured provider APIs. Use `provider-api-catalog` to see the full list and each provider's auth style.",
+    },
+    {
+      lines: "3",
+      note: "`path` is the provider's real REST path, not a Dispatch-invented shape — copy it from `provider-api-catalog`/`provider-api-docs` when unsure.",
+    },
+    {
+      lines: "4",
+      note: "Query params are passed straight through to the provider's HTTP API.",
+    },
+    {
+      lines: "5",
+      label: "Stage instead of return",
+      note: "`stageAs` writes the parsed response rows into a staged dataset instead of returning the full payload — query it afterward with `query-staged-dataset`.",
+    },
+  ]}
+/>
+
+## Workspace Connections and staged datasets {#workspace-connections}
+
+A **workspace connection** is a saved, shared account for one provider — Slack, GitHub, Notion, Salesforce, and more — that any granted app can use without doing its own OAuth or holding its own key.
+
+<Diagram id="doc-block-dispatch1" title={"Connection setup, grant, and query"} summary={"Plan a setup without ever returning secret values, apply it with credential ref names only, grant or preview impact per app, then use the connection through provider-api-request or a staged dataset."}>
+
+```html
+<div class="dsp-conn-flow">
+  <div class="diagram-col">
+    <div class="diagram-node">
+      plan-workspace-connection-setup<br /><small class="diagram-muted"
+        >inspect provider, missing creds</small
+      >
+    </div>
+  </div>
+  <div class="diagram-arrow diagram-muted" aria-hidden="true">&rarr;</div>
+  <div class="diagram-box" data-rough>
+    apply-workspace-connection-setup<br /><small class="diagram-muted"
+      >credential ref names only — never raw secrets</small
+    >
+  </div>
+  <div class="diagram-arrow diagram-muted" aria-hidden="true">&rarr;</div>
+  <div class="diagram-col">
+    <div class="diagram-node">
+      set-workspace-connection-grant<br /><small class="diagram-muted"
+        >per-app access</small
+      >
+    </div>
+    <div class="diagram-node">
+      preview-workspace-connection-impact<br /><small class="diagram-muted"
+        >before revoke · disable · delete</small
+      >
+    </div>
+  </div>
+  <div class="diagram-arrow diagram-muted" aria-hidden="true">&rarr;</div>
+  <div class="diagram-panel center" data-rough>
+    <span class="diagram-pill accent">provider-api-request</span
+    ><small class="diagram-muted">stageAs &rarr; staged dataset</small>
+  </div>
+  <div class="diagram-arrow diagram-muted" aria-hidden="true">&rarr;</div>
+  <div class="diagram-box">
+    query-staged-dataset<br /><small class="diagram-muted"
+      >filter · group · aggregate</small
+    >
+  </div>
+</div>
+```
+
+```css
+.dsp-conn-flow {
+  display: flex;
+  align-items: center;
+  gap: 12px;
+  flex-wrap: wrap;
+}
+.dsp-conn-flow .diagram-col {
+  display: flex;
+  flex-direction: column;
+  gap: 8px;
+}
+.dsp-conn-flow .diagram-box {
+  display: flex;
+  flex-direction: column;
+  gap: 4px;
+}
+.dsp-conn-flow .diagram-arrow {
+  font-size: 20px;
+  line-height: 1;
+}
+.dsp-conn-flow .center {
+  display: flex;
+  flex-direction: column;
+  align-items: center;
+  gap: 4px;
+}
+```
+
+</Diagram>
+
+- **`plan-workspace-connection-setup`** inspects a provider (or an existing connection) and returns what's needed: required and suggested credential ref names, which apps commonly use it, and a summary of current grants. It never returns secret values.
+- **`apply-workspace-connection-setup`** saves the connection using credential ref names only — anything that looks like a raw secret (a Slack token, a GitHub PAT, a private key, and so on) is rejected outright.
+- **`set-workspace-connection-grant`** grants or revokes one app's access, or switches the whole connection between "every app" and "selected apps only."
+- **`preview-workspace-connection-impact`** shows which apps would lose access before you revoke, disable, or delete a connection.
+- **`list-workspace-connections`** lists the provider catalog, saved connections, and every app's current access in one call.
+- **`delete-workspace-connection`** removes a connection's metadata and grants; secret values stay in Vault or OAuth stores either way.
+
+Once a connection exists, `provider-api-request` can pass `stageAs: "name"` to write the response into scratch storage instead of returning it inline. `list-staged-datasets`, `query-staged-dataset` (filter, group, aggregate, or project columns without re-fetching), and `delete-staged-dataset` manage that storage. A staged dataset is scoped to the requesting app and user, capped at 200,000 rows or 50MB, and is meant for working data during an analysis — not permanent storage.
+
+## MCP hub mode and the /mcp connector {#mcp}
+
+Dispatch can still act as the workspace's [MCP hub](/docs/mcp-clients#hub) so every other app in the workspace pulls the same org-scope MCP server list. Separately, Dispatch's own `/mcp` endpoint is the recommended external MCP connector for Claude, ChatGPT, Codex, Cursor, or another MCP host that should reach multiple workspace apps — add `https://dispatch.agent-native.com/mcp` as a connector, then choose which workspace apps it can reach from Dispatch's **Agents** page. Use a direct app URL only when that host should be isolated to one app.
+
+To add a server to that shared list, upload an HTTP MCP server definition under `mcp-servers/*.json` in Dispatch **Resources**, then scope it to All apps or selected app grants — the same scoping every other workspace resource uses.
+
+## What's next
+
+- [**Dispatch**](/docs/template-dispatch) — the workspace control plane overview
+- [**Messaging, routing, and approvals**](/docs/template-dispatch-messaging-routing) — channels, the orchestrator, and the approval queue
+- [**Operating the workspace**](/docs/template-dispatch-operations) — jobs, Dreams, and the operator console
+- [**Dispatch — architecture for developers**](/docs/template-dispatch-developers) — the package/app split and customizing it
+- [**Onboarding**](/docs/onboarding) — registering a setup step so a new API key shows up in the sidebar checklist