fix(MDA): docs cleanup and improvements

src/docs.json

@@ -1662,6 +1662,7 @@
                         "group": "Connectors",
                         "pages": [
                           "langsmith/managed-deep-agents-connectors/index",
+                          "langsmith/managed-deep-agents-connectors/integrations",
                           "langsmith/managed-deep-agents-connectors/mcp",
                           "langsmith/managed-deep-agents-connectors/github",
                           "langsmith/managed-deep-agents-connectors/langsmith"

src/langsmith/managed-deep-agents-channels/github.mdx

@@ -25,16 +25,16 @@ This page covers the **channel** (conversation ingress/egress). Use the [GitHub
 
 ## Add a GitHub channel
 
-Add `channels/github.py` or `channels/github.ts` next to your agent entry. The file name becomes the channel name (`github` → `POST /channels/github/events`). Export a named `channel` created with `define_github_channel` / `defineGitHubChannel`.
+Add `channels/github.py` or `channels/github.ts` next to your agent entry. The file name becomes the channel name (`github` → `POST /channels/github/events`). Export a named `channel` created with `channels.github`:
 
 Handlers are ordered: the first match for a delivery wins. Each handler needs `on` and a `prompt` callback that builds the **human message** for that turn. The agent system prompt remains `instructions.md`.
 
 <CodeGroup>
 
 ```python channels/github.py
-from managed_deepagents.channels.github import define_github_channel
+from managed_deepagents import channels
 
-channel = define_github_channel(
+channel = channels.github(
     handlers=[
         {
             "on": "pull_request.opened",
@@ -52,9 +52,9 @@ channel = define_github_channel(
 
 ```ts channels/github.ts
 import type { PullRequestOpenedEvent } from "@octokit/webhooks-types";
-import { defineGitHubChannel } from "managed-deepagents/channels/github";
+import { channels } from "managed-deepagents";
 
-export const channel = defineGitHubChannel({
+export const channel = channels.github({
   handlers: [
     {
       on: "pull_request.opened",
@@ -72,7 +72,7 @@ export const channel = defineGitHubChannel({
 
 </CodeGroup>
 
-Pair with a shared-bot (or equivalent) identity for channel-only installs. The channel actor is the installation/service principal `github-app:<installationId>`, not the pull request author. Replies use the App installation token—Connect-with-GitHub OAuth is not required for this path.
+Pair with a conversation-scoped (or equivalent) identity for channel-only installs. The channel user is the installation/service principal `github-app:<installationId>`, not the pull request author. Replies use the App installation token—Connect-with-GitHub OAuth is not required for this path.
 
 ### Event filters (`on`)
 
@@ -111,7 +111,7 @@ flowchart LR
 
 1. GitHub POSTs to `https://<agent-server>/channels/github/events` (the file stem `github` becomes the path segment).
 2. The runtime verifies `X-Hub-Signature-256` against `GITHUB_WEBHOOK_SECRET`, dedupes on `X-GitHub-Delivery`, and returns HTTP 202.
-3. It picks the first matching handler, calls `prompt` to build the inbound text, then invokes the graph over trusted loopback with actor and source-thread identity (`source.provider: "github"`).
+3. It picks the first matching handler, calls `prompt` to build the inbound text, then invokes the graph over trusted loopback with user and source-thread identity (`source.provider: "github"`).
 4. When the matched handler has `autoReply` enabled and the conversation address is `owner/repo#N`, it posts the agent response as an issue/PR comment with the App installation token. Events without an issue/PR number skip the comment even when `autoReply` is `true`.
 
 LangGraph auth is bypassed only on `POST /channels/{name}/events` so GitHub can deliver without an ingress secret; the loopback invoke still uses `MDA_INGRESS_SECRET`.
@@ -145,7 +145,7 @@ Put these in the project `.env` (or LangSmith workspace secrets) before `mda dep
 | `GITHUB_APP_ID` | Yes | App id for JWT minting |
 | `GITHUB_APP_PRIVATE_KEY` | Yes | PEM private key for the App |
 | `GITHUB_INSTALLATION_ID` | Yes | Installation the channel acts as (single-install) |
-| `MDA_INGRESS_SECRET` | Yes when identity uses trusted loopback / `trusted_backend` | Trusted invoke from the Events path into the graph |
+| `MDA_INGRESS_SECRET` | Yes when identity uses trusted loopback / `backend` auth | Trusted invoke from the Events path into the graph |
 
 ## Configure the GitHub App
 
@@ -184,7 +184,7 @@ Put these in the project `.env` (or LangSmith workspace secrets) before `mda dep
     Add a Slack Events channel alongside GitHub.
   </Card>
   <Card title="Identity" icon="fingerprint" href="/langsmith/managed-deep-agents-identity">
-    Choose identity presets for channel callers.
+    Choose an identity scope for channel callers.
   </Card>
   <Card title="Deploy an agent" icon="upload" href="/langsmith/managed-deep-agents-deploy">
     Route secrets and deploy the channel-enabled agent.

src/langsmith/managed-deep-agents-channels/index.mdx

@@ -28,7 +28,7 @@ For the full project layout, see the [CLI project file reference](/langsmith/man
 
 ## How channels work
 
-1. You declare a channel under `channels/` (for example `defineSlackChannel` / `defineGitHubChannel`).
+1. You declare a channel under `channels/` (for example `channels.slack(...)` / `channels.github(...)`).
 2. Compile and deploy discover the file name as the channel name (`channels/slack.ts` → `slack`).
 3. The runtime mounts provider ingress for that channel on the Agent Server (`POST /channels/{name}/events`).
 4. Inbound messages invoke your agent with [identity](/langsmith/managed-deep-agents-identity) stamps so tools and memory see the same caller model as HTTP runs.
@@ -40,16 +40,16 @@ Channels require a root identity declaration. Provider-specific delivery details
 
 | Pattern | Identity approach | Thread behavior |
 | --- | --- | --- |
-| Shared workspace bot | `shared-bot` preset (`threads: "channel"`) | Conversations are scoped by provider source thread (for example Slack `slack:T…:U…` or GitHub `github-app:<installationId>`). |
-| Linked web + Slack | `validated_token` (for example Supabase/guest) + Connect-with-Slack | Unlinked Slack users get a connect prompt; linked users run as the web actor so browser and Slack share history when `threads: "actor"`. |
+| Shared workspace bot | `defineIdentity({ scope: { threads: "conversation" } })` | Conversations are scoped by provider source thread (for example Slack `slack:T…:U…` or GitHub `github-app:<installationId>`). |
+| Linked web + Slack | Validated-token auth (for example Supabase/guest) + Connect-with-Slack | Unlinked Slack users get a connect prompt; linked users run as the web user so browser and Slack share history when `threads` is `"user"`. |
 
 The GitHub channel uses an installation/service actor and does not require Connect-with-GitHub. For Slack app setup, secrets, Event Subscriptions, and Connect-with-Slack, see [Slack](/langsmith/managed-deep-agents-channels/slack). For GitHub App webhooks, see [GitHub](/langsmith/managed-deep-agents-channels/github).
 
 ## Test and deploy
 
 <ManagedDeepAgentsTestAndDeploy />
 
-When `channels/` is present, `mda deploy` preflights secrets listed in each compiled channel manifest’s `requiredEnv` (for example Slack’s signing secret and bot token, or GitHub App webhook/App credentials) before upload. Missing secrets fail the deploy early.
+When `channels/` is present, `mda deploy` provisions what each channel needs before upload: a Slack channel gets its Slack app created and installed through the workspace's Slack connection in LangSmith (see [Slack](/langsmith/managed-deep-agents-channels/slack#the-slack-app)), while a GitHub channel preflights the secrets listed in its compiled manifest’s `requiredEnv` (GitHub App webhook/App credentials). Missing GitHub secrets fail the deploy early.
 
 ## Next steps
 
@@ -61,7 +61,7 @@ When `channels/` is present, `mda deploy` preflights secrets listed in each comp
     Declare a GitHub App webhook channel with handlers for any event.
   </Card>
   <Card title="Identity" icon="fingerprint" href="/langsmith/managed-deep-agents-identity">
-    Choose `shared-bot` or linked `validated_token` for channel callers.
+    Choose conversation-scoped threads or linked validated-token auth for channel callers.
   </Card>
   <Card title="CLI reference" icon="terminal" href="/langsmith/managed-deep-agents-cli">
     Look up `channels/` project file rules and deploy preflight.