@agent-native/core 0.122.4 → 0.123.0

package/corpus/core/docs/content/messaging.mdx

@@ -22,6 +22,7 @@ Connect your agent to Slack, Microsoft Teams, Discord interactions, email, Teleg
 - **Run a Discord slash command.** The built-in Discord adapter handles HTTP interactions; ordinary Discord messages require a separate Gateway runtime.
 - **Message the agent on Telegram or WhatsApp** from your phone.
 - **Same agent, same memory.** Whatever you tell it on Slack is remembered when you email it later. The web chat and external messages share one thread history.
+- **Act on other tools from a message.** An @mention can end in a row in Notion, an issue in Jira, or a record in HubSpot — see [@mention in Slack → row in Notion](/docs/messaging-recipes) for the full worked example.
 - For one-way in-app alerts (bell icon, webhooks) see [Notifications](/docs/notifications).
 
 <Diagram id="doc-block-1s9dj7c" title="Many channels, one agent" summary={"Every platform fans into the same agent loop and the same SQL thread history — so a Slack DM and an email continue the same conversation."}>
@@ -233,6 +234,10 @@ and `link_shared` events to the Clips unfurl handler.
 - **Production allowlists** — set `SLACK_ALLOWED_TEAM_IDS` and, for shared Slack apps, `SLACK_ALLOWED_API_APP_IDS` so a valid signing secret cannot be reused by an unexpected workspace.
 - **Clips app unfurls** — Clips can share the managed Slack app credentials, but a Slack app has only one Events API Request URL; route `link_shared` to Clips when chat and unfurls share an app.
 
+### Want to act on other tools from a Slack message? {#slack-to-notion}
+
+See [Messaging Recipes — @mention in Slack → row in Notion](/docs/messaging-recipes) for the full worked example: wiring the Notion provider API, storing the credential in the vault, and asking your agent to write the action.
+
 ## Set up Microsoft Teams {#microsoft-teams}
 
 The built-in Teams adapter uses the Bot Framework activity endpoint. Incoming
@@ -417,159 +422,9 @@ If you don't need an orchestrator, any single template can wire up messaging dir
 
 ---
 
-## For developers {#for-developers}
-
-Everything below is the technical reference. If you've finished the setup steps above, you can stop here unless you're customizing the integration plugin or building your own adapter.
-
-### How it works {#how-it-works}
-
-Inbound platform webhooks use a cross-platform SQL-queue pattern so they work on every serverless host (Netlify, Vercel, Cloudflare Workers, Fly, Render, Node) without relying on platform-specific background-execution APIs.
-
-1. The platform `POST`s to `/_agent-native/integrations/<platform>/webhook`. The handler verifies the signature, parses the payload into an `IncomingMessage`, and **inserts a row into `integration_pending_tasks`** with `status='pending'`.
-2. The handler fires a fire-and-forget `POST /_agent-native/integrations/process-task` and returns `200` immediately, well inside Slack's 3-second SLA.
-3. The processor endpoint runs in a **fresh function execution** with its own full timeout budget. It atomically claims the task (`pending` → `processing` via `claimPendingTask`), runs the agent loop, posts the reply through the adapter, and marks the task `completed`.
-4. A recurring retry job (`startPendingTasksRetryJob`, every 60s) sweeps tasks stuck in `pending` >90s or `processing` >5min and re-fires the processor. Capped at 3 attempts, then marked `failed`.
-
-<Diagram id="doc-block-19wzu23" title="Inbound webhook lifecycle" summary={"The webhook only verifies, enqueues, and returns 200. A fresh function execution drains the queue and runs the agent loop, with a 60s retry job as the safety net."}>
+## Reference {#reference}
 
-```html
-<div class="msg-flow">
-  <div class="msg-row">
-    <div class="diagram-node">
-      Platform<br /><small class="diagram-muted">Slack · email · etc.</small>
-    </div>
-    <div class="diagram-arrow diagram-muted" aria-hidden="true">&rarr;</div>
-    <div class="diagram-box" data-rough>
-      <strong>/webhook</strong><br /><small class="diagram-muted"
-        >verify signature + parse</small
-      ><br /><span class="diagram-pill">INSERT pending task</span>
-    </div>
-    <div class="diagram-arrow diagram-muted" aria-hidden="true">&rarr;</div>
-    <div class="diagram-pill ok">return 200</div>
-  </div>
-  <div class="msg-fire">
-    <span class="diagram-muted">fire-and-forget</span>
-    <span class="diagram-arrow diagram-muted" aria-hidden="true">&darr;</span>
-  </div>
-  <div class="msg-row">
-    <div class="diagram-box" data-rough>
-      <strong>/process-task</strong><br /><small class="diagram-muted"
-        >fresh execution · own timeout</small
-      >
-    </div>
-    <div class="diagram-arrow diagram-muted" aria-hidden="true">&rarr;</div>
-    <div class="diagram-pill accent">claim</div>
-    <div class="diagram-arrow diagram-muted" aria-hidden="true">&rarr;</div>
-    <div class="diagram-pill accent">agent loop</div>
-    <div class="diagram-arrow diagram-muted" aria-hidden="true">&rarr;</div>
-    <div class="diagram-pill accent">adapter.sendResponse</div>
-    <div class="diagram-arrow diagram-muted" aria-hidden="true">&rarr;</div>
-    <div class="diagram-pill ok">completed</div>
-  </div>
-  <div class="diagram-panel msg-retry" data-rough>
-    <span class="diagram-pill warn">every 60s</span>
-    <span class="diagram-muted"
-      >retry job sweeps stuck tasks (pending &gt;90s · processing &gt;5min) and
-      re-fires /process-task &mdash; capped at 3 attempts, then
-      <strong>failed</strong></span
-    >
-  </div>
-</div>
-```
-
-```css
-.msg-flow {
-  display: flex;
-  flex-direction: column;
-  gap: 12px;
-}
-.msg-flow .msg-row {
-  display: flex;
-  align-items: center;
-  gap: 10px;
-  flex-wrap: wrap;
-}
-.msg-flow .msg-fire {
-  display: flex;
-  align-items: center;
-  gap: 8px;
-  padding-inline-start: 12px;
-}
-.msg-flow .msg-retry {
-  display: flex;
-  align-items: center;
-  gap: 8px;
-  flex-wrap: wrap;
-}
-```
-
-</Diagram>
-
-Inbound and outbound conversations live in the same SQL thread, so you can continue a Slack DM from the web UI or vice versa.
-
-<Endpoint id="doc-block-stk4pd" method="POST" path="/_agent-native/integrations/slack/webhook" summary="Slack Events API inbound webhook" auth={"HMAC-SHA256 of the raw body using `SLACK_SIGNING_SECRET`, checked against the `X-Slack-Signature` header. In production also gated by `SLACK_ALLOWED_TEAM_IDS` / `SLACK_ALLOWED_API_APP_IDS`."} params={[
-  {
-    "name": "X-Slack-Signature",
-    "in": "header",
-    "type": "string",
-    "required": true,
-    "description": "Slack request signature, verified before any processing."
-  },
-  {
-    "name": "X-Slack-Request-Timestamp",
-    "in": "header",
-    "type": "string",
-    "required": true,
-    "description": "Timestamp used in the signature base string."
-  }
-]} request={{
-  "contentType": "application/json",
-  "example": "{\n  \"type\": \"event_callback\",\n  \"team_id\": \"T0123\",\n  \"api_app_id\": \"A0123\",\n  \"event\": {\n    \"type\": \"message\",\n    \"channel_type\": \"im\",\n    \"user\": \"U0123\",\n    \"text\": \"summarize last week's signups\"\n  }\n}"
-}} responses={[
-  {
-    "status": "200",
-    "description": "Acknowledged immediately. The agent loop runs in the separate /process-task execution. The first time a Request URL is saved, Slack POSTs a `url_verification` challenge and the adapter replies with the `challenge` value automatically.",
-    "example": "{ \"ok\": true }"
-  },
-  {
-    "status": "401",
-    "description": "Signature verification failed, or the team/app id is not in the production allowlist."
-  }
-]}>
-
-Receives Slack events (DMs and channel `app_mention`s). Verifies the request signature, parses the payload into an `IncomingMessage`, inserts a `pending` row into `integration_pending_tasks`, fires the fresh-execution processor, and returns **200 immediately** — well inside Slack's 3-second SLA. The same route shape exists per platform under `/_agent-native/integrations/<platform>/webhook`.
-
-</Endpoint>
-
-#### Why this pattern (and not the platform-native shortcuts) {#why-this-pattern}
-
-Serverless functions freeze the moment the response is sent. Anything still running — including a fire-and-forget Promise, a deferred LLM call, or an in-flight tool — gets killed mid-execution. The only way to keep an agent loop alive is to start a **new** function execution for it, which is what the self-fired `/process-task` POST does.
-
-Do NOT use any of these alternatives:
-
-- **Netlify Background Functions** — Netlify-only, requires a `-background.ts` filename suffix, breaks on every other host.
-- **Cloudflare `event.waitUntil()`** — CF Workers only, not portable.
-- **Vercel `after()` / Fluid** — Vercel-only, gated behind specific runtimes.
-- **Naked fire-and-forget Promises after `return`** — silently killed when the function freezes; no error in the logs, the user just never gets a reply.
-
-The SQL-queue + self-webhook + retry-job combination is the only thing that works identically on every supported host. The retry job is the safety net — never assume the initial dispatch flushed before the function froze.
-
-### The integrations plugin {#plugin}
-
-The plugin auto-mounts when no custom version exists. To customize, create:
-
-```ts
-// server/plugins/integrations.ts
-import { createIntegrationsPlugin } from "@agent-native/core/server";
-import { scriptRegistry } from "../../agent.config";
-
-export default createIntegrationsPlugin({
-  actions: scriptRegistry,
-  systemPrompt: "You are a helpful assistant...",
-});
-```
-
-Which platforms are active depends on which env vars are set. The plugin registers webhook routes for each one under `/_agent-native/integrations/`.
+The webhook routes and environment variables below apply across every platform. For the technical internals — the inbound webhook lifecycle, the integrations plugin, threading and identity, per-platform security, proactive sends, and writing a custom adapter — see [Messaging Internals](/docs/messaging-internals).
 
 ### Webhook URLs {#webhook-urls}
 
@@ -605,163 +460,10 @@ Integration credentials resolve from the integration owner's scoped secrets firs
 
 The built-in runtime adapters are **Slack**, **Microsoft Teams**, **Discord interactions**, **Telegram**, **WhatsApp Cloud API**, and **provider-webhook email** (Resend or SendGrid). Discord support is interaction-only; ordinary Discord message ingestion is not included.
 
-### Threading and identity {#threading-and-identity}
-
-Each external conversation maps to a persistent thread in the agent-native database:
-
-- **Slack DM** → one thread per Slack user.
-- **Slack channel @mention** → one thread per channel.
-- **Microsoft Teams** → tenant + team/channel + Bot Framework conversation.
-- **Discord interaction** → application + guild/DM + channel.
-- **Telegram chat** → one thread per chat and `message_thread_id` topic.
-- **WhatsApp conversation** → business phone-number ID + sender number.
-- **Email** → threading derived from `Message-ID` / `In-Reply-To` / `References` headers.
-
-External threads appear in the web UI alongside web-originated threads, tagged with their source platform. Identity resolution: when a Slack/email user matches a registered user (typically by email), they're linked to that account.
-
-### Security {#security}
-
-Every incoming webhook is signature-verified before processing:
-
-- **Slack** — HMAC-SHA256 of the body using `SLACK_SIGNING_SECRET`, checked against the `X-Slack-Signature` header. The first time you save a Request URL in Slack's Event Subscriptions panel, Slack POSTs a `url_verification` challenge to it; the framework's adapter detects this and replies with the `challenge` value automatically, so the URL flips green in Slack without any extra work on your end.
-- **Microsoft Teams** — Microsoft Bot Framework JWT verification, including signing keys, issuer, app audience, service URL claim, channel endorsement, and tenant allowlist.
-- **Discord** — Ed25519 verification over the timestamp plus exact raw body. Invalid PING probes return 401.
-- **Telegram** — secret token set when registering the webhook.
-- **WhatsApp** — Meta's verification challenge (using `WHATSAPP_VERIFY_TOKEN`) plus payload signature.
-- **Email** — Svix-style signature verification when `EMAIL_INBOUND_WEBHOOK_SECRET` is set (Resend and SendGrid both use this format). If the secret is unset, the webhook is accepted but a warning is logged.
-
-The email adapter also enforces:
-
-- **Allowed domains** — optional `allowedDomains` array in the integration's `integration_configs` row; senders outside the list are dropped.
-- **Rate limit** — SQL-queue-backed rate limit of 20 inbound messages per sender per hour.
-
-### Proactive sends {#proactive-sends}
-
-The agent can send messages on its own initiative through the Dispatch `send-platform-message` action for `"slack"`, `"telegram"`, or `"email"`. Microsoft Teams requires a saved Bot Framework conversation reference, Discord interaction tokens expire, and the WhatsApp adapter does not implement template-message proactive sends, so those three are reply-only.
-
-### Custom adapters {#custom-adapters}
-
-To add a new messaging platform, implement the `PlatformAdapter` interface:
-
-```ts
-import type { H3Event } from "h3";
-import type {
-  PlatformAdapter,
-  IncomingMessage,
-  OutgoingMessage,
-} from "@agent-native/core/server";
-import type { EnvKeyConfig } from "@agent-native/core/server";
-
-const myAdapter: PlatformAdapter = {
-  platform: "my-chat",
-  label: "My Chat",
-  capabilities: {
-    replyText: true,
-    proactiveMessages: false,
-    nativeThreads: true,
-    contextualReplies: true,
-    deferredWebhookResponse: false,
-  },
-
-  // Env keys this adapter needs (rendered in the settings UI)
-  getRequiredEnvKeys(): EnvKeyConfig[] {
-    return [
-      { key: "MY_CHAT_BOT_TOKEN", label: "My Chat Bot Token", required: true },
-    ];
-  },
-
-  // Handle platform-specific verification challenges (e.g. Slack's
-  // url_verification). Return { handled: true, response } to short-circuit.
-  async handleVerification(event: H3Event) {
-    return { handled: false };
-  },
-
-  // Validate the webhook request signature
-  async verifyWebhook(event: H3Event): Promise<boolean> {
-    // Implement the provider's documented signature/JWT verification here.
-    // Fail closed; never ship `return true` as a placeholder.
-    throw new Error("Webhook verification is not implemented");
-  },
-
-  // Parse the webhook payload into a normalized IncomingMessage.
-  // Return null to silently ignore the event (bot messages, edits, etc.).
-  async parseIncomingMessage(event: H3Event): Promise<IncomingMessage | null> {
-    return {
-      platform: "my-chat",
-      externalThreadId: "channel-or-thread-id",
-      text: "the user's message",
-      senderId: "my-chat-user-id",
-      threadRef: "provider-thread-id",
-      replyRef: "provider-message-id",
-      platformContext: { channelId: "channel-id" },
-      timestamp: Date.now(),
-    };
-  },
-
-  // Format plain agent text into a platform-appropriate OutgoingMessage.
-  // opts.threadDeepLinkUrl, when provided, is a URL back to the originating
-  // thread in the dispatch UI — render it as a button (Slack) or inline link.
-  formatAgentResponse(
-    text: string,
-    opts?: { threadDeepLinkUrl?: string },
-  ): OutgoingMessage {
-    return { text, platformContext: {} };
-  },
-
-  // Post the agent's response back to the platform
-  async sendResponse(
-    message: OutgoingMessage,
-    context: IncomingMessage,
-  ): Promise<void> {
-    // Call the platform's API, using context.platformContext for routing
-  },
-
-  // Return current connection/configuration status for the settings UI.
-  // baseUrl is the app's public URL, used for status checks that need it.
-  async getStatus(baseUrl?: string) {
-    return {
-      platform: "my-chat",
-      label: "My Chat",
-      enabled: true,
-      configured: !!process.env.MY_CHAT_BOT_TOKEN,
-    };
-  },
-};
-```
-
-If the provider requires an immediate response, implement
-`getImmediateWebhookResponse(incoming)`. Keep short-lived delivery credentials
-in `incoming.responseContext`, not `platformContext`; terminal queue rows erase
-the active payload. The response is returned only after verification and a
-durable queue insert.
-
-Register it in your integrations plugin:
-
-```ts
-export default createIntegrationsPlugin({
-  actions: scriptRegistry,
-  systemPrompt: "You are a helpful assistant...",
-  adapters: [myAdapter],
-});
-```
-
-Reference implementations live in `packages/core/src/integrations/adapters/`. See `microsoft-teams.ts` for official JWT validation and token caching, `discord.ts` for signed deferred interactions, and `telegram.ts` or `whatsapp.ts` for native reply references.
-
-### Reliability via Dispatch + A2A continuations {#reliability}
-
-When [Dispatch](/docs/dispatch) delegates a request to another app over [A2A](/docs/a2a-protocol#continuations), the continuation-recovery flow guarantees the user gets a Slack/email reply even if the downstream agent crashes mid-execution. The original webhook task stays in `processing` until the continuation either resolves or the retry sweep marks it stuck; either way, the platform thread gets a final reply rather than going silent.
-
-This means a multi-app workspace fronted by Dispatch is more resilient than a single template wired to messaging directly — failures in any one downstream app degrade to a graceful error message instead of a dropped reply. See [A2A continuations](/docs/a2a-protocol#continuations) for the full delivery-guarantee story.
-
-### Common pitfalls {#pitfalls}
-
-- **Don't double-read the request body.** h3 v2's body stream is consume-once: if you call `readBody(event)` after the framework has already parsed `event.node.req.body` (or vice versa), the second read hangs the request indefinitely. This shows up most often with Resend and SendGrid — both stream the inbound payload and the dangling read never resolves, the platform times out, and the webhook gets retried until it dedups. If you wrap the framework's webhook handler in your own middleware, pass the already-parsed `IncomingMessage` via the `incoming` option rather than letting the handler re-parse.
-- **Don't run agent loops inside the webhook handler.** The handler must enqueue and return — the agent loop runs in the processor's fresh execution. Putting it inline guarantees serverless freeze kills the run. Furthermore, public-facing gateway integrations (such as Netlify or Vercel) enforce strict HTTP timeout limits (e.g., Netlify's 10-second request limit). Because agent runs and tools often take longer than this window, trying to run the loop synchronously within the webhook request will cause the gateway to terminate the connection, resulting in aborted execution and dropped replies. The HMAC-signed self-webhook `/process-task` queue pattern is the only way to satisfy gateway limits while executing the full agent loop safely.
-- **Don't rely on dedup memory across cold starts.** The dedup key lives in the SQL `(platform, external_event_key)` unique index, not an in-process Map. If you replace the queue, keep the SQL-level dedup or duplicate Slack retries will trigger duplicate agent runs.
-- **Keep the self-webhook URL reachable.** The processor URL is built from `APP_URL` / `URL` / `DEPLOY_URL` / `BETTER_AUTH_URL`, falling back to the inbound request headers. On preview deploys with rewritten hostnames, set one of these explicitly or the dispatch will hit a 404.
-
 ## What's next {#whats-next}
 
+- [Messaging Recipes](/docs/messaging-recipes) — the full @mention-in-Slack-to-Notion-row worked example
+- [Messaging Internals](/docs/messaging-internals) — the webhook lifecycle, custom adapters, and security internals
 - [Dispatch](/docs/dispatch) — concept overview for using a central inbox across apps
 - [Dispatch template reference](/docs/template-dispatch) — recommended central inbox for multi-app workspaces
 - [A2A Protocol](/docs/a2a-protocol) — how Dispatch delegates work to other agents, including continuation recovery

package/corpus/core/docs/content/multi-app-workspace.mdx

@@ -7,7 +7,7 @@ description: "Host many agent-native apps in one monorepo with shared auth, RBAC
 
 <Callout tone="info">
 
-**Which workspace doc?** This page covers the **deployment shape** — one monorepo, many apps, shared auth and a unified deploy. For the agent customization layer (Agent Resources: `AGENTS.md`, memory, skills, custom agents) see [Agent Resources](/docs/agent-resources); for governance (who reviews, approves, and owns what) see [Workspace Governance](/docs/workspace-management).
+**Developer page.** This page is for developers scaffolding or deploying a multi-app repo. It covers the **deployment shape** — one monorepo, many apps, shared auth and a unified deploy. For the agent customization layer (Agent Resources: `AGENTS.md`, memory, skills, custom agents) see [Agent Resources](/docs/agent-resources); for governance (who reviews, approves, and owns what) see [Workspace Governance](/docs/workspace-management).
 
 </Callout>
 

package/corpus/core/docs/content/multi-tenancy.mdx

@@ -119,6 +119,7 @@ This is the same pipeline used for per-user scoping. For the SQL-level mechanics
 
 ## What's next {#related}
 
+- [**Organizations, Teams & Permissions**](/docs/organizations-teams-permissions) — a practical, start-here guide to org roles, resource roles, and the environment variables involved
 - [**Authentication**](/docs/authentication#organizations) — sessions, social providers, and the org-management surface
 - [**Security — Data Scoping**](/docs/security#data-scoping) — SQL-level isolation, the `ownableColumns()` contract, and access guards
 - [**Multi-App Workspace**](/docs/multi-app-workspace) — hosting multiple agent-native apps in one monorepo with shared auth and RBAC

package/corpus/core/docs/content/native-chat-ui.mdx

@@ -5,6 +5,14 @@ description: "Action-declared native chat renderers, reusable DataTable/DataChar
 
 # Native Chat UI
 
+<Callout tone="info">
+
+**Developer page.** This page is for developers building action-declared chat widgets. For the end-user experience of chat, see [Using Your Agent](/docs/using-your-agent).
+
+</Callout>
+
+When you ask for a chart, a table, or a compact report, you get a real interactive widget instead of a wall of text or a screenshot — here's how that's built.
+
 Native chat UI is the in-app rendering path for first-party agent output. An
 action returns structured JSON, the chat runtime recognizes an explicit widget
 discriminant, and `<AssistantChat>` renders a real React component in the

package/corpus/core/docs/content/notifications.mdx

@@ -37,11 +37,27 @@ await notify(
         >
       </div>
     </div>
+    <div class="fan-row">
+      <span class="diagram-pill">email</span>
+      <div class="diagram-box" data-rough>
+        Resend / SendGrid<br /><small class="diagram-muted"
+          >always registered &middot; best-effort</small
+        >
+      </div>
+    </div>
+    <div class="fan-row">
+      <span class="diagram-pill">slack</span>
+      <div class="diagram-box" data-rough>
+        Block Kit JSON to an incoming webhook<br /><small class="diagram-muted"
+          >always registered &middot; best-effort</small
+        >
+      </div>
+    </div>
     <div class="fan-row">
       <span class="diagram-pill">webhook</span>
       <div class="diagram-box" data-rough>
         POST JSON to NOTIFICATIONS_WEBHOOK_URL<br /><small class="diagram-muted"
-          >best-effort</small
+          >always registered &middot; best-effort</small
         >
       </div>
     </div>
@@ -121,28 +137,10 @@ channel no-ops for the emission.
 
 The webhook and Slack channels resolve `${keys.NAME}` references in both the URL and `NOTIFICATIONS_*_AUTH` against the owner's ad-hoc [secrets](/docs/security), so the raw value never enters the agent's context. Per-key URL allowlists are enforced — same rule the automations `web-request` tool uses.
 
-<Diagram id="doc-block-1lduyog" title="Channels and severity" summary={"inbox is always on; webhook needs an env var; custom channels register at startup. Severity drives badge styling and is passed through to every channel."}>
+<Diagram id="doc-block-1lduyog" title="Severity drives the badge" summary={"Severity is passed through to every channel and drives the bell dropdown's badge color."}>
 
 ```html
 <div class="diagram-channels">
-  <div class="diagram-panel col" data-rough>
-    <strong>Channels</strong>
-    <div class="diagram-box" data-rough>
-      inbox<br /><small class="diagram-muted"
-        >always on &mdash; part of the primitive</small
-      >
-    </div>
-    <div class="diagram-box" data-rough>
-      webhook<br /><small class="diagram-muted"
-        >needs NOTIFICATIONS_WEBHOOK_URL</small
-      >
-    </div>
-    <div class="diagram-box" data-rough>
-      custom<br /><small class="diagram-muted"
-        >registerNotificationChannel()</small
-      >
-    </div>
-  </div>
   <div class="diagram-panel col" data-rough>
     <strong>Severity drives the badge</strong>
     <div class="sev-row">

package/corpus/core/docs/content/observability.mdx

@@ -382,3 +382,4 @@ Identity fields explicitly set via `setUser({ id, email, username })` are preser
 - [**Tracking**](/docs/tracking) — product analytics (PostHog, Mixpanel, Amplitude) for your app's own events
 - [**Actions**](/docs/actions) — the operations that appear as tool calls in traces
 - [**Security**](/docs/security) — data scoping and credential handling
+- [**Toolkit piece: Observability Kit**](/docs/toolkit-observability) — the dashboard and feedback UI built on this data model

package/corpus/core/docs/content/onboarding.mdx

@@ -62,6 +62,15 @@ infrastructure, and add providers only when you need them.
 
 ### What you'll see
 
+<WireframeBlock id="doc-block-ob1">
+  <Screen
+    surface="panel"
+    html={
+      "<div style='display:flex;flex-direction:column;gap:10px;padding:14px 16px;min-height:460px;box-sizing:border-box'><div style='display:flex;align-items:center;gap:8px'><strong style='flex:1'>Setup</strong><span class='wf-pill accent'>1 of 4</span><span data-icon='chevronUp'></span></div><div class='wf-card' style='display:flex;align-items:center;gap:8px'><span data-icon='check' style='color:var(--wf-ok)'></span><span style='flex:1'>Database</span><small class='wf-muted'>optional</small></div><div class='wf-card' style='display:flex;flex-direction:column;gap:8px'><div style='display:flex;align-items:center;gap:8px'><strong style='flex:1'>Connect an AI engine</strong><span class='wf-pill' style='color:var(--wf-warn);border-color:var(--wf-warn)'>required</span></div><small class='wf-muted'>Connect Builder (one click) or paste an LLM key</small><button class='primary'>Connect Builder.io</button><small style='text-decoration:underline'>or paste your own key</small></div><div class='wf-card' style='display:flex;align-items:center;gap:8px'><span style='flex:1'>Authentication</span><small class='wf-muted'>optional</small></div><div class='wf-card' style='display:flex;align-items:center;gap:8px'><span style='flex:1'>Email delivery</span><small class='wf-muted'>optional</small></div><div style='flex:1'></div><small style='text-decoration:underline;align-self:flex-start'>Hide setup</small></div>"
+    }
+  />
+</WireframeBlock>
+
 - A **Setup** panel above the agent chat with a checklist like "Connect an AI
   engine", "Email delivery", etc.
 - A counter at the top (e.g. "1 of 4") shows how many steps are ready.
@@ -105,6 +114,10 @@ behind a picker or disclosure when a step has several equivalent providers.
 - **Email delivery** (optional) — useful before deploy for password resets,
   team invitations, and share notifications. Use the provider you already use;
   local development can run without it.
+- **Connect a GitHub repository** (optional) — grants a scoped GitHub token so
+  the agent can read/write repo files for cloud or headless work, without
+  cloning the repo or running code. Skip it for local development where the
+  agent already has the repo on disk.
 
 Templates can add their own steps on top of these — e.g. a CRM template might
 add "Connect Gmail", a docs template might add "Pick a default workspace". See
@@ -239,12 +252,13 @@ before it is available.
 
 ### Built-in steps
 
-| ID         | Required | Description                                       |
-| ---------- | -------- | ------------------------------------------------- |
-| `llm`      | yes      | Builder connection or a provider LLM key          |
-| `database` | no       | Default database or any SQL `DATABASE_URL`        |
-| `auth`     | no       | Built-in accounts, optional OAuth or access token |
-| `email`    | no       | Resend or SendGrid for transactional email        |
+| ID                  | Required | Description                                             |
+| ------------------- | -------- | ------------------------------------------------------- |
+| `llm`               | yes      | Builder connection or a provider LLM key                |
+| `database`          | no       | Default database or any SQL `DATABASE_URL`              |
+| `auth`              | no       | Built-in accounts, optional OAuth or access token       |
+| `email`             | no       | Resend or SendGrid for transactional email              |
+| `github-repository` | no       | Scoped GitHub token for cloud/headless repo file access |
 
 Any of these can be overridden by re-registering with the same `id` after the
 defaults load.