diff --git a/doc/connections/CHAT-CONNECTOR-UX.md b/doc/connections/CHAT-CONNECTOR-UX.md
new file mode 100644
index 00000000000..daae0d48859
--- /dev/null
+++ b/doc/connections/CHAT-CONNECTOR-UX.md
@@ -0,0 +1,295 @@
+# Chat Connector UX
+
+Use this companion to the [Connection authoring runbook](./CONNECTOR-PLAYBOOK.md)
+when designing or reviewing chat and email connector setup, account linking, and
+ongoing configuration. These conventions apply to Slack, Discord, Telegram,
+AgentMail, and other providers according to their supported capabilities.
+
+Make connecting an agent feel like a short, understandable sequence of actions.
+At every point, the person should know what to do, where to do it, what Paperclip
+has observed, and what happens next. These are Paperclip product conventions
+extracted from a live Slack setup iteration, not a requirement to reproduce
+Slack's screens or six steps for every provider.
+
+## Start with the actual provider journey
+
+Before changing a flow, identify:
+
+- What the user is connecting: agent, provider app/bot/mailbox, and workspace or destination.
+- How credentials are obtained and which ones this transport actually needs.
+- Whether inbound delivery needs a public HTTPS callback, an outbound socket, polling, or another mechanism.
+- How an external person becomes a Paperclip identity, and how a new person requests organization access.
+- The simplest supported first message and how subsequent replies reach the same conversation.
+
+Inspect the current implementation and verify provider-dependent details against
+current official documentation when implementing them. Do not infer capabilities
+from another provider's wizard or from similar-looking credentials. For
+Paperclip code changes, follow the repository's [design system](../../DESIGN.md) and
+[connection authoring runbook](./CONNECTOR-PLAYBOOK.md); use its existing components and tokens.
+
+For examples of how these principles transfer across providers, read
+[Provider adaptation](#provider-adaptation).
+
+## 1. Give each meaningful action a stable step
+
+Use these stages where applicable: choose agent, create/configure the provider
+app, supply credentials, verify inbound delivery, connect your personal account,
+and try a conversation. Merge or omit stages that have no distinct user action.
+Separate creating an app from entering its credentials when the user must leave
+Paperclip between those actions. Keep personal account linking separate from
+the message test: they establish different things.
+
+A step keeps its number and purpose throughout the flow. Do not turn “Add
+credentials” into “Finish setup” under the same number after submission. Avoid
+vague finishing screens that repeat configuration already supplied earlier.
+Explain consequential choices, such as an agent being permanent for a connection,
+at the point where the user makes them.
+
+During setup, replace the generic Browse/Review sidebar with the setup steps:
+
+- Use compact, evenly spaced numbered stops with readable labels.
+- Center a vertical connector line on the numbered circles; leave a small gap at each end so it does not touch them.
+- Keep completed/available steps clickable for going back. Distinguish current, complete, and unavailable states visually and accessibly.
+- Preserve entered values and draft progress across back navigation, external-provider visits, refresh, and Save & exit. Resume at the relevant step.
+- Earlier steps remain reviewable; revisiting them must not silently change an installed app, registered command, or established connection identity.
+
+## 2. One footer row, owned by the step
+
+**Every wizard state puts Save & exit on the left and the primary action on the
+right in the same vertically centered row.** Save & exit uses a subdued gray
+text treatment. Related secondary actions go immediately to the left of the
+primary action, not in an unrelated block above or below it.
+
+The step owns its whole footer. Do not render another Save & exit in a parent
+beneath the form. Apply this rule to loading, errors, linked/unlinked states,
+verification, and optional tests, not just the first screen. Prefer a shared
+footer component when several steps need it. On narrow screens, wrap deliberately
+while preserving order and grouping; do not introduce horizontal overflow.
+
+Leave a clear vertical gap between the final field/help link and the footer.
+“Save” should match real persistence; expose save errors and do not advance on a
+failed save.
+
+## 3. Put prerequisites first; reveal technical detail on demand
+
+A prerequisite that can prevent the whole connection from working belongs at the
+top, before app creation or credentials. Use a visible tinted background, a
+concise explanation, and a specific action or Learn more link. For a public
+callback, distinguish having HTTPS from being reachable by the provider. A
+private-network HTTPS URL alone is not proof of public reachability.
+
+Only show prerequisites relevant to the chosen transport and deployment. Do not
+require a public URL for a connector that does not use public callbacks. When
+relevant, explain that Paperclip Cloud supplies HTTPS and link self-hosters to
+maintained setup documentation instead of embedding a long server tutorial.
+
+Generated manifests, webhook URLs, and diagnostic settings should not dominate
+the normal path:
+
+- Offer a small, descriptive text link such as “View Slack App Manifest” below the relevant fields, aligned toward their trailing edge.
+- Open generated configuration in an accessible modal with a read-only preview and copy action. Do not expose a long raw document by default.
+- Put webhook URLs and repair instructions in troubleshooting when app creation already supplied them.
+- Do not ask users to paste or edit the same configuration again unless verification shows a real need.
+
+## 4. Make the editable surface simple and coherent
+
+Expose meaningful choices—app name, bot display name, invocation name—directly
+as normal form fields. Avoid an extra bordered container around a small group
+of ordinary fields. Use standard enabled input text colors; actual values must
+not look like disabled text or placeholders.
+
+The editable values, generated configuration, creation link, and later
+instructions derive from the same saved state. Validate edits before generating
+or submitting them. Use the actual chosen app/bot name in subsequent instructions.
+When edits become unsafe after installation, make that boundary explicit and
+preserve the installed configuration on reconnect.
+
+Show a help icon beside each provider-configuration and credential field,
+visible even when the field is not hovered. Reveal its short explanation on
+hover or keyboard focus, with a usable touch interaction. Explain
+where the value appears or how to find it. Essential instructions and validation
+errors stay visible outside tooltips. Avoid introductory copy that merely
+repeats what the fields and action buttons already say.
+
+## 5. Minimize provider-side work and make handoffs legible
+
+Use supported manifest-prefill links, installation links, or OAuth flows when
+they eliminate manual work. Verify support before promising a one-click setup;
+workspace selection, consent, installation, or credential copying may still be
+necessary. Do not put credentials into creation links.
+
+An action such as “Create Slack app” should open the provider immediately. If it
+also advances Paperclip, let the handoff register first—a short delay around one
+second was effective for Slack. Prevent duplicate activation and cancel pending
+navigation if the user leaves or goes back. Keep “I already created the app” as
+a clear secondary path. A successful click is not proof that installation or
+verification succeeded.
+
+Use text links for supporting navigation such as “Open provider app settings.”
+Reserve the prominent button for the step's main action.
+
+## 6. Place credential instructions next to each credential
+
+When secrets live on different provider screens, say so plainly and give each
+field its own short numbered instructions. Prefer this pattern:
+
+1. Open the provider app settings link and choose **the actual app name**.
+2. Choose **the exact provider section label**.
+3. Copy **the exact credential label** and paste it into the field below.
+
+Keep the opening link and “choose your app name” on one readable, normal-contrast
+line where space permits. Repeat that entry point for each independent sequence
+so users do not have to reconstruct a path from a distant paragraph.
+
+Use password fields and validate provider-documented formats locally. Detect
+common mix-ups with actionable inline messages: name the expected credential,
+name the mistaken type, and say where to find the right one. Slack examples:
+a bot token starts with `xoxb-`; an `xapp-` app token is not the HTTP Signing
+Secret, and an `xoxb-` bot token is not that secret either. Do not impose these
+formats on other providers or invent format checks for opaque secrets. Format
+validation does not prove validity or permission scope. Never echo pasted secrets
+in warnings, logs, URLs, or diagnostic screenshots.
+
+Screenshots must depict the exact credential and current provider screen.
+Identify them as provider screenshots in a caption/container so they cannot be
+mistaken for live Paperclip controls. Remove obsolete or misleading screenshots.
+Use a troubleshooting modal only when it adds guidance beyond the inline steps;
+delete redundant “Can't find it?” links when the page already explains the path.
+
+## 7. Separate connection setup, identity linking, and membership
+
+Installing a bot connects a provider resource. Linking an external identity
+connects a person to their Paperclip permissions. Organization membership is a
+separate approval boundary. Make all three understandable without exposing
+implementation details to the user.
+
+For new connections, default unlinked-person access to off; retain existing
+explicit choices. Integrate the configuring user's identity link into onboarding
+and show how other people can join later from the Access tab:
+
+- Provide the actual connect command or equivalent provider-supported action, with copy support. It should discover identity without starting agent work.
+- Update the UI live when the external identity is observed. Show the candidate identity, target Paperclip account, and an explicit ownership confirmation.
+- Use an amber container while linking is required/pending, then green after successful linking. Include text/icons so color is not the only signal.
+- Explain that future messages use that person's current Paperclip permissions.
+- Let other people follow a private, expiring confirmation link and sign in. Nonmembers can request access; approval precedes confirmation. They should not need another bot or shared credentials.
+
+Preserve authentication, bootstrap, feature-rollout, token, and company-access
+checks when making invitations reachable to nonmembers. A narrow ability to
+request membership must not grant membership, link the identity automatically,
+or bypass a gate. Clearly distinguish link expiry, an outstanding access request,
+and a connection failure, and provide the next action for each.
+
+## 8. Make the first conversation easy and optional
+
+After connection verification and required identity linking, suggest one concrete
+message. Use the simplest interaction the provider and adapter actually support:
+a real @mention where supported, a command when necessary, or an email recipient,
+subject, and short body. Do not force a slash command merely because identity
+linking used one. For mentions, explain selecting the real bot from suggestions
+when copied plain text alone is insufficient.
+
+Give a compact sequence: open/prepare the destination, send a copyable message,
+then continue in the thread or reply mechanism that preserves the conversation.
+Avoid a second generic Open Provider button when the instructions already convey
+this. Remove filler such as “Complete this real conversation to finish setup.”
+
+Detect the current linked user's first qualifying message automatically and show
+a checkmark when observed. Keep a manual “I've sent the test message” action and
+a way to finish without the optional test. Do not block completion solely because
+the event has not arrived or the status poll failed. Conversely, optional testing
+does not waive required credentials, verification, or identity authorization.
+
+## 9. Make ongoing management compact and contextual
+
+After setup, replace Browse/Review with the connection's Settings, Access,
+Conversations, and Activity navigation. Use real links and the shell's own
+navigation components so labels and selection survive production layouts and
+mobile drawers. Avoid duplicate tab navigation in the content area.
+
+- **Settings:** Repeat the simple first-message instruction with a copy icon. Use domain labels such as “Allowed Channels” instead of vague “Destinations” when accurate. Keep permissions, reconnect, and installation concepts distinct.
+- **Access:** Put instructions for other people to connect here, alongside the unlinked-person policy and identity links. Explain the practical permission effect without repeating abstract identity-model copy.
+- **Conversations:** Follow task-list visual conventions in a compact row: provider icon, channel/destination, task title, provider link near the destination, task link near the title. Preserve separate meaning from a task list; adapt cleanly on mobile.
+- **Activity:** Use scannable event rows, precise timestamps, clear outcomes, and actionable errors. Paginate older activity. First-page updates must not reset someone reading an older page. Keep connection health and lifecycle controls secondary, such as in an expandable section.
+
+Remove routine “Active” badges from shared headers and conversation rows.
+Highlight meaningful exceptions such as paused, revoked, or failing states where
+a user can act on them.
+
+Health must describe evidence, not assumptions. An unobserved optional callback
+is not a failure. Distinguish unverified, working, and changed/broken configuration.
+HTTPS termination at a trusted deployment boundary must not create false URL-drift
+warnings for the internal HTTP hop; continue detecting genuine host, port, and
+path changes. Keep callback verification evidence separate for distinct surfaces.
+
+## Apply and verify
+
+For a requested redesign, identify the relevant principles and fix the concrete
+flow. Do not expand a narrow UI request into transport replacement, a new auth
+system, or a repository-wide redesign. Keep API contracts synchronized when the
+UX actually needs backend behavior.
+
+Exercise the affected states: fresh setup, back/resume, external handoff,
+misplaced credentials, pending/failed verification, unlinked/linked identity,
+nonmember access requests, optional message detection, and populated management
+pages. Pick the relevant states for the change rather than running every scenario
+for a text edit. Check mobile layout, standard field contrast, visible help icons,
+and footer alignment in each affected conditional state. Validate provider
+behavior with real evidence when available and authorized; distinguish mocked
+browser coverage from a live provider test. Do not send real messages, install
+external apps, or modify memberships without authorization from the task.
+
+## Provider adaptation
+
+Use these as design prompts, not a current provider API specification. Verify the
+selected adapter and official provider documentation before implementing steps,
+links, credential validation, or test-message instructions.
+
+| Decision | Slack lesson | Transfer to other providers |
+| --- | --- | --- |
+| Step boundaries | App creation, credentials, verification, linking, and testing became separate steps. | Separate distinct actions, not every field. An OAuth-only provider may need fewer steps; bot creation elsewhere may need a dedicated handoff. |
+| Editable identity | App name, bot display name, command drive the same manifest. | Expose only editable properties supported by that provider. Keep creation artifacts and later instructions consistent with saved values. |
+| Credential acquisition | Bot token and Signing Secret live on different screens. | Use the provider's exact credential labels and locations. An API key, bot token, application secret, and signing secret are not interchangeable. |
+| Reachability | HTTP callbacks need provider-reachable HTTPS. | Derive the prerequisite from the actual delivery mechanism. Outbound sockets or polling do not automatically require an inbound public URL. |
+| First message | Prefer a real @mention for normal conversation. | Prefer the provider's simplest supported trigger. Never offer a mention if privacy rules or the adapter prevent receiving it. |
+| Identity link | A private connect action links a person to their Paperclip account. | Use a provider-supported private interaction or equivalent verified confirmation. Do not assume slash commands, ephemeral replies, or DMs exist everywhere. |
+| Ongoing scope | “Allowed Channels” makes the policy concrete. | Use the relevant destination noun: channels, groups, repositories, chats, or mailboxes. Show only scope controls the integration enforces. |
+
+### Discord example
+
+Keep provider app/bot creation and installation to a server understandable as
+distinct actions if the supported flow requires both. Put each credential beside
+its own retrieval instructions. Do not borrow Slack's signing-secret or manifest
+steps. Account linking and the message test should reflect the supported private
+interaction and mention/thread behavior. Explain any channel permission or event
+subscription prerequisite before asking for a message that depends on it.
+
+### Telegram example
+
+Center setup on the actual bot-creation and token-acquisition flow. If no separate
+manifest or public callback action is required for the selected transport, omit
+those steps. Verify what reaches the bot in private chats versus groups before
+choosing a test instruction. A provider's privacy mode may require a command or
+reply instead of an ordinary mention. Use the actual bot username and keep
+personal linking distinct from sending a task request.
+
+### AgentMail / email example
+
+Use mailbox and sender language rather than bot/channel terminology. If the
+integration provisions the mailbox inside Paperclip, do not invent an external
+app-creation step. Supply the actual email address and a short copyable test
+subject/body, and explain how replies continue the conversation. Verify how the
+integration authenticates senders and grants authority; a displayed From address
+alone must not automatically establish a Paperclip identity. Apply the same
+pending/success feedback, optional test, and member-access boundaries using the
+email integration's actual mechanisms.
+
+### Review examples
+
+- **One-token setup:** A short agent → credentials → identity → test flow can be better than six mostly empty screens.
+- **Already installed:** Resume at credentials or verification as appropriate; do not require another installation. Keep prior app details reviewable without silently changing registration.
+- **Working behind HTTPS proxy:** Show successful verified traffic truthfully. Hide raw URL repair instructions unless there is a real mismatch; do not discard host/path checks to silence a warning.
+- **Signed-in newcomer:** Let a valid private invitation request membership without exposing normal organization UI or granting agent authority. After approval, explicitly confirm the identity.
+- **No test event yet:** Keep waiting feedback and manual completion available when prerequisites are satisfied. Do not mark another person's message as the configuring user's success.
+
+The intended result is consistent interaction and permission semantics across
+providers, with instructions and step count tailored to each real workflow.
diff --git a/doc/connections/CONNECTOR-PLAYBOOK.md b/doc/connections/CONNECTOR-PLAYBOOK.md
index 6bd8a9de77c..795e6c44667 100644
--- a/doc/connections/CONNECTOR-PLAYBOOK.md
+++ b/doc/connections/CONNECTOR-PLAYBOOK.md
@@ -8,15 +8,19 @@ Status: canonical end-to-end authoring guide for Apps v2 catalog connections.
For connector artwork, follow [Connector icons](./CONNECTOR-ICONS.md): fixed gray Paperclip frames, authentic vendor artwork, explicit theme variants, optical fit and exact provenance. Brand-library additions do not activate connectors. Use the shared registry/resolver and branding generator; do not introduce per-screen logos or outer-surface overrides.
This runbook is the repeatable, agent-executable procedure for adding a vendor
-to the Apps catalog as data, not as a plugin. It follows the accepted
-connections framework in [PAP-13211](/PAP/issues/PAP-13211), the first-30
-rollout matrix in [PAP-2432](/PAP/issues/PAP-2432), and the production
-validation scope in [PAP-12373](/PAP/issues/PAP-12373).
+to the Apps catalog as data, not as a plugin. The architecture, reuse-path
+classification, credential boundaries, and production validation requirements
+are specified below so contributors can implement a connector without access
+to an internal issue tracker.
+
+For chat and email setup, account linking, and ongoing configuration, also follow
+[Chat connector UX](./CHAT-CONNECTOR-UX.md). It covers step navigation, footer
+layout, credential instructions, provider handoffs, identity linking, optional
+message tests, and management pages, with examples for other providers.
Use it when Paperclip acts on an external system through a governed connection: a stored credential, a capability catalog, access profiles and policy rules, and audit. Inbound integrations, such as an external client acting on Paperclip, use gateway or webhook guidance instead.
-**A catalog entry is a convenience layer, not a prerequisite.** Since
-[PAP-17087](/PAP/issues/PAP-17087), an operator can connect any
+**A catalog entry is a convenience layer, not a prerequisite.** An operator can connect any
standards-compliant remote HTTP MCP server from **Connect your own MCP server**
or **Paste a config** with no Paperclip code change at all — including servers
that need browser sign-in. Those two routes are the documented baseline; see
@@ -35,7 +39,12 @@ remote MCP methods may opt in to [Vercel Connect](./VERCEL-CONNECT.md), where
durable provider credentials remain in the operator's Vercel account and
Paperclip resolves short-lived tokens at invocation time. Before writing a
connector, read [Identity vs. connections](./README.md#identity-vs-connections)
-for the P1/P2/P3 boundary and the D7 standing rule.
+for background. The boundary is mandatory: sign-in authenticates a person;
+a resource connection authorizes external work; Login with Paperclip issues
+first-party identity tokens to registered clients. Sign-in tokens are never
+reused as resource tokens, and `id.paperclip.ing` never stores resource tokens
+or hosts a connections hub. Keep company-scoped connection credentials and
+agent access under the instance's connection governance.
AI provider credentials use the same vault, applications, grants, installations,
and delegation model with `connectionPurpose: ai` and `transport: runtime_auth`.
@@ -52,6 +61,8 @@ for compatibility, personal defaults, resolver isolation, and legacy adoption.
- [Current access defaults](#current-default-access-policy)
- [Golden-path agent tutorial](#golden-path-agent-tutorial)
- [Connection UX and user journeys](#connection-ux-and-user-journeys)
+- [Chat and email connector UX](./CHAT-CONNECTOR-UX.md)
+- [Production validation evidence](#step-9-align-with-production-validation)
- [AppDefinition field reference](#appdefinition-field-reference)
- [Troubleshooting](#troubleshooting-and-failure-classification)
- [Definition of done](#definition-of-done)
@@ -70,7 +81,7 @@ A complete connector proposal produces:
- Credential secret refs into `company_secrets`; never raw env values.
- Action catalog metadata with risk classes, schemas, resource filters, and quarantine defaults.
- Default profile and policy behavior for read, write, and destructive actions.
-- A smoke checklist aligned to [PAP-12373](/PAP/issues/PAP-12373): connect,
+- A smoke checklist following [production validation](#step-9-align-with-production-validation): connect,
discover catalog, allowed read call, correctly governed write call,
denied/quarantined call when the method declares one, revoke, and audit
evidence.
@@ -505,6 +516,13 @@ its declaration. Record which runtime paths were tested live versus deterministi
#### Connection UX and user journeys
+For chat and email onboarding or management screens, apply
+[Chat connector UX](./CHAT-CONNECTOR-UX.md) alongside this section. Keep the
+provider's actual capabilities and the distinction between resource setup,
+personal identity linking, and company membership explicit. The chat wizard may
+choose its agent before app creation; a separate agent-resource assignment
+wizard, described below, applies when that assignment is an independent action.
+
Design the whole journey, from finding the app to doing useful work with an
agent. A successful credential exchange is only one step. Describe who the
user is, where they start, what they want to accomplish, and where they will
@@ -1199,15 +1217,30 @@ A plugin may bundle one or more catalog entries, but it must still create normal
### Step 2: Classify The Reuse Path
-Classify the vendor before writing metadata. Use the [PAP-2432](/PAP/issues/PAP-2432) matrix terms so rollout planning, security review, and QA can compare providers consistently.
+Classify the vendor before writing metadata. Use these definitions so rollout
+planning, security review, and QA can compare providers consistently. The
+examples are starting points; confirm current provider capabilities in Phase 1.
-| Reuse path | Use when | Typical transport | Examples from the matrix |
+| Reuse path | Use when | Typical transport | Examples |
| --- | --- | --- | --- |
| MCP-direct | The vendor exposes an official or stable MCP server whose tools map cleanly to Paperclip grants. | `mcp_remote`; `local_stdio` only for approved trusted templates. | Linear, Notion, Sentry, Vercel, Exa, Apify, Context7. |
| OpenAPI-shim | The vendor has a documented REST/OpenAPI surface but no stable MCP server, and a generated/thin shim can expose safe actions. | Shim service or approved template that presents an MCP-compatible catalog to Paperclip. | Datadog, Apollo, QuickBooks, Ramp/Brex, Zendesk. |
| Vendor-deep-wrapper | The vendor boundary depends on app-installation tokens, event validation, rich domain semantics, resource grants, or high-risk writes. | Vendor-specific wrapper behind the same connection model. | GitHub, Slack, Google Workspace writes, Atlassian, Microsoft 365, Cloudflare, Figma, Stripe, Salesforce, HubSpot, Intercom, PagerDuty. |
-Record the classification in the proposal along with the transport and the reason a lighter path is or is not enough.
+Record the classification in the proposal along with the transport and the
+reason a lighter path is or is not enough. For each method, also record auth
+mode, credential owner, required resource filters, initial actions, webhook or
+sync requirements, and security tier. A provider name alone is not a sufficient
+classification: a read-only method and a method that sends messages or changes
+infrastructure can have different risks.
+
+Use the shipped definition and `recommendedDefaultsForApp` for runtime behavior.
+Risk tiers describe exposure; they do not replace action policies. S1 covers
+low-risk reads; S2 covers business data and narrow writes; S3 covers broad
+content or operational access; S4 covers payments, external sends, production
+changes, deletion, or tenant administration. High-impact methods need explicit
+security review and negative access tests. Prove the transport and governance
+path with narrow actions before expanding to broader capabilities.
### Step 3: Pick Auth And Credential Ownership
@@ -1403,20 +1436,45 @@ Recommended defaults for a new catalog entry:
### Step 9: Align With Production Validation
-[PAP-12373](/PAP/issues/PAP-12373) owns real-vendor gallery smoke evidence and connector validation. Do not duplicate that issue's screenshot/evidence matrix in this playbook. A connector proposal should instead state exactly how it will be validated there:
+Validate every exposed provider/method combination against a real account in
+an isolated, production-like instance. Deterministic tests and Storybook cover
+Paperclip behavior; they do not prove provider consent, credential scope, live
+delivery, or revocation. Use the following evidence matrix directly in the
+connector proposal or PR. No separate private validation issue is required.
-- Connect succeeds against the real vendor using production-like OAuth/app/key setup.
-- Catalog discovery produces the expected actions and the declared changed-tool
- behavior.
-- An allowed read call succeeds through the gateway.
-- A write call is Allowed by the new-connection default unless an explicit
- provider or operator policy narrows it.
-- A blocked/quarantined action, when declared, cannot be listed or invoked by
- an agent.
-- Revocation removes tools and blocks execution immediately.
-- Activity/audit rows prove actor, run/issue context, resource id, decision, reason code, and outcome.
+| Scenario | Required result | Evidence to retain |
+| --- | --- | --- |
+| Setup and consent | The gallery entry opens the correct method; prerequisites, provider handoff, credentials, and back/resume work. | Redacted setup/review screenshots; method, deployment mode, date, commit, and outcome. |
+| Authentication | The selected OAuth/app/key path succeeds and resolves the intended account/resource. | Redacted auth result, scopes, callback origin/path, credential-source and client-ownership mode; no secret values. |
+| Catalog and configuration | Discovery returns the reviewed actions; resource filters and selected access persist. | Tool names/count, schema hashes, risk/default-policy review, and saved filter names. |
+| Allowed execution | A narrow read succeeds through the gateway; writes follow the effective policy. | Tool, actor, decision, redacted result, and correlated call/audit record. Use a disposable resource for an authorized live write; otherwise mark write execution untested. |
+| Denied execution | Ungranted actors, another company, disallowed resources, revoked connections, and declared blocked/quarantined actions cannot execute. | Expected denial and reason code, with the automated or live test that exercised the boundary. Cover listing where the policy requires tools to be hidden. |
+| Runtime delivery | An actual agent/run-scoped gateway call succeeds when runtime logic changes. Chat/email also routes an incoming message and its reply to the same task. | Redacted task/conversation and call correlation; identify live versus simulated events. |
+| Refresh and recovery | Catalog refresh, token refresh/reconnect, and recoverable failures preserve the correct identity and policy. | Before/after outcome, redacted error code, and successful retry; no duplicated connection. |
+| Revoke and reconnect | Revocation blocks subsequent execution; supported reconnect reuses the intended identity/history. | Removal or denial evidence followed by reconnect result. |
+| Activity and secret handling | Activity explains what occurred and why; stored responses, logs, and artifacts contain no credential values. | Actor, run/issue context, resource, decision, reason code, outcome, plus redaction-check result. |
-If a gallery card cannot pass this path against a real vendor, de-list it or mark it unavailable until the missing auth, transport, or governance dependency is fixed.
+For chat/email, also verify the applicable UX states in
+[Chat connector UX](./CHAT-CONNECTOR-UX.md#apply-and-verify): new connections deny
+unlinked people by default; linking requires ownership confirmation; nonmembers
+request access before receiving authority; an optional message test never
+becomes an unexplained completion gate. Show verification based on observed
+traffic, and distinguish optional, unobserved callbacks from real failures.
+
+Record **pass**, **fail**, **not run**, or **not applicable** for each scenario,
+with a reason for the last two. Include the environment, method key, commit,
+reproduction steps, expected/actual result, and links to redacted evidence that
+reviewers can access. Put the requirements and conclusions in the PR or a
+repository document; an internal tracker or expiring artifact link must not be
+the only place they exist. Do not publish credentials, OAuth codes, session
+cookies, private tenant content, personal account details, or secret-bearing URLs.
+
+Use Phase 9's lifecycle to collect the evidence. A consent restriction, unavailable
+account, or missing provider feature is a named validation gap, not a passing
+result. If a gallery card cannot complete its required path against a real
+provider, keep it unavailable until the missing auth, transport, or governance
+dependency is fixed. Re-run affected scenarios after a material change rather
+than citing evidence from an older implementation.
## MCP-Direct Connections (Hosted MCP + OAuth)
@@ -1491,8 +1549,7 @@ registers a client on the fly and stores it on the connection:
`customer` and `dcr` in the method's `ownershipModes` when the vendor
supports both.
-Since [PAP-17087](/PAP/issues/PAP-17087), DCR is **one of four** registration
-tiers, and `ownershipModes` gates only the *curated* path. The broker resolves a
+DCR is **one of four** registration tiers, and `ownershipModes` gates only the *curated* path. The broker resolves a
client in this order: a deployment-preconfigured client, then a Client ID
Metadata Document when the authorization server advertises one (requires a public
HTTPS `PAPERCLIP_PUBLIC_URL`), then DCR, then client credentials the operator
@@ -1510,8 +1567,8 @@ not be auto-registered, and the broker will not fall through to the generic
registration path for it.
**DCR needs neither Paperclip ID nor Paperclip Connect.** DCR is always
-instance-local (ratified in the PAP-14828 connector-service spec, section 10
-item 8.4: "DCR is always instance-local; the service has no DCR involvement").
+instance-local: the hosted connector service does not register DCR clients
+or hold their credentials.
Each instance registers its own public client with the vendor and uses its own
`/api/tools/oauth/callback` redirect. **Cloud-hosted and self-hosted instances
use the SAME path** — the only per-instance difference is the hostname inside
@@ -1538,7 +1595,7 @@ axes; a private HTTPS host can be fine even when plain HTTP is not.
### Documentation standards for every connection doc
Every connection doc — playbook appendix, proposal, or user-facing doc —
-must include all three of the following (they are part of the template below):
+must include all of the following (they are part of the template below):
1. **Service involvement statement.** Say explicitly whether Paperclip ID or
Paperclip Connect participates in the flow. For RFC 7591 DCR providers the
@@ -1569,7 +1626,7 @@ Copy this section into a connector proposal or implementation issue.
- App key:
- App name:
- Owner:
-- First-30 classification: MCP-direct / OpenAPI-shim / vendor-deep-wrapper
+- Reuse classification: MCP-direct / OpenAPI-shim / vendor-deep-wrapper
- Reason for classification:
- Security tier: S1 / S2 / S3 / S4
- Plugin needed? No / Yes, because:
@@ -1660,7 +1717,9 @@ Copy this section into a connector proposal or implementation issue.
## Validation Hook
-- Real-vendor smoke issue:
+- Environment, method key, date, and tested commit:
+- Reproduction steps and accessible redacted evidence:
+- Per-scenario result (pass / fail / not run / not applicable, with reasons):
- Connect evidence:
- Catalog evidence:
- Allowed read:
@@ -1672,14 +1731,17 @@ Copy this section into a connector proposal or implementation issue.
## Appendix: Linear Dry Run
-This dry run applies the template to Linear, one of the [PAP-2432](/PAP/issues/PAP-2432) Batch A providers.
+This dry run applies the template to Linear as an example of a hosted MCP
+connection with scoped business-data reads and narrow issue writes.
### Vendor
- App key: `linear`
- App name: Linear
-- First-30 classification: MCP-direct with a thin GraphQL/resource-filter wrapper if the hosted MCP server cannot enforce all filters itself.
-- Reason for classification: Linear has a hosted MCP endpoint shape in the current gallery, and the first-30 matrix calls Linear a direct MCP/GraphQL thin-wrapper provider.
+- Reuse classification: MCP-direct with a thin GraphQL/resource-filter wrapper if the hosted MCP server cannot enforce all filters itself.
+- Reason for classification: Linear exposes a hosted MCP endpoint; a thin
+ GraphQL/resource-filter wrapper is needed only for restrictions the hosted
+ server and gateway cannot already enforce.
- Security tier: S2, because it exposes product planning data and narrow issue mutations but not payments, tenant admin, or production infrastructure.
- Plugin needed: No. The default gallery card, OAuth connect, resource filters, action catalog, profiles, policies, and audit cover the required UX. A plugin would only be warranted later for custom Linear dashboards or background sync workers.
@@ -1771,7 +1833,8 @@ before accepting it as an S2 Allowed action.
### Validation Hook
-Linear's real-vendor evidence belongs in [PAP-12373](/PAP/issues/PAP-12373). The smoke pass should prove:
+Record Linear's evidence using the production validation matrix above. The
+smoke pass should prove:
- OAuth connect succeeds with a customer-created Linear OAuth app (or an
explicitly reviewed external credential source) and the instance callback
@@ -1785,26 +1848,28 @@ Linear's real-vendor evidence belongs in [PAP-12373](/PAP/issues/PAP-12373). The
- Audit rows include company, connection, run/issue, agent/user actor, tool, decision, reason code, and outcome.
### AppDefinition catalog authoring
-Connector proposals now target the versioned `AppDefinition` contract in `packages/shared/src/types/app-definition.ts`. Seed data is one JSON file per provider under `packages/shared/src/app-definitions/`; regenerate Wave 1 with `pnpm connections:ingest-app-definitions`. The generator parses all 99 captured templates, validates required placeholders, OAuth ownership modes, and API-key placement, and produces deterministic output for review. FIRST-30 remains authoritative for `riskTier` and `requiredResourceFilters`; managed ownership modes stay data-visible but runtime-hidden until availability is injected.
+Connector proposals now target the versioned `AppDefinition` contract in `packages/shared/src/types/app-definition.ts`. Seed data is one JSON file per provider under `packages/shared/src/app-definitions/`; regenerate Wave 1 with `pnpm connections:ingest-app-definitions`. The generator parses all 99 captured templates, validates required placeholders, OAuth ownership modes, and API-key placement, and produces deterministic output for review. Review `riskTier` and `requiredResourceFilters` against the method capabilities and resource boundaries described above; managed ownership modes stay data-visible but runtime-hidden until availability is injected.
## Appendix: Notion Dry Run (MCP-Direct With DCR)
-This dry run applies the template to Notion, the first MCP-direct connector to
-ship with RFC 7591 dynamic client registration (PAP-16637; server
-implementation PAP-16649, PR #11009). Unlike the Linear appendix, every
-endpoint and constraint below comes from a live request log, not vendor docs
-alone.
+This dry run applies the template to Notion using RFC 7591 dynamic client
+registration. The request sequence and redirect probes below preserve the
+recorded August 6–7, 2026 live observations in this document. Treat provider
+endpoints, token lifetimes, tool availability, and plan restrictions as a dated
+snapshot; recheck them against official documentation and live validation for
+a new implementation.
### Vendor
- App key: `notion`
- App name: Notion
-- First-30 classification: MCP-direct. Notion ships an official hosted MCP
+- Reuse classification: MCP-direct. Notion ships an official hosted MCP
server; its ~20 `notion-*` tools map directly to Paperclip grants.
- Reason for classification: no shim or wrapper needed — the hosted server
speaks Streamable HTTP, which `server/src/services/mcp-http.ts` already
- handles. The FIRST-30 matrix's "thin wrapper for block/database policy" is
- explicitly deferred; v1 enforcement is gateway policy plus filters-as-config.
+ handles. A separate block/database-policy wrapper is deferred; v1
+ enforcement is gateway policy plus filters-as-config. Verify each advertised
+ restriction at the actual enforcement boundary before claiming support.
- Security tier: S3 — workspace content read/write, but no payments, tenant
admin, or production infrastructure.
- Plugin needed: No. Gallery card, OAuth connect, filters, catalog, profiles,
@@ -1838,8 +1903,13 @@ alone.
### Connection Flow (mandatory)
-Paperclip ID / Paperclip Connect involvement: **none — DCR is instance-local**
-(PAP-14828 spec section 10 item 8.4); **cloud-hosted and self-hosted use the
+The UI examples use `ACME` as a sample company prefix. Replace it and any
+`paperclip.example.com` origin with your own company prefix and instance origin.
+These are example addresses, not a shared test deployment.
+
+Paperclip ID / Paperclip Connect involvement: **none — DCR is instance-local**.
+The instance registers the client, exchanges and refreshes tokens, and stores
+credential references in its own vault. **Cloud-hosted and self-hosted use the
same path**. The only per-instance difference is the hostname in the redirect
URI.
@@ -1863,7 +1933,7 @@ Redirect constraints (probed): `https-or-loopback-http`.
sequenceDiagram
autonumber
actor U as User's browser
- participant UI as Paperclip UI
/PAP/apps/connect?source=notion
+ participant UI as Paperclip UI
/ACME/apps/connect?source=notion
participant S as Paperclip instance server
(cloud or self-hosted — same path)
participant M as mcp.notion.com
(MCP server + OAuth AS)
participant N as Notion web
(app.notion.com, notion.com)
@@ -1894,7 +1964,7 @@ sequenceDiagram
Note over S,M: Later: agent runs reach notion-* tools via the managed MCP gateway.
Server refreshes ahead of use — each refresh ROTATES the refresh token.
```
-### Dry-Run Request Log (PAP-16649, 2026-08-06/07)
+### Dry-Run Request Log (2026-08-06/07)
The verified request sequence for a first connect:
@@ -1937,11 +2007,10 @@ plain-HTTP non-loopback origins.
- Instance prerequisites: the instance base URL must be HTTPS on any host or
loopback HTTP (Notion's redirect-URI rule). A plain-HTTP non-loopback origin
gets "This provider requires an HTTPS or loopback origin. Configure TLS
- before connecting." — add TLS first (e.g. a tailscale cert, as
- paperclip-dev did). Apps is a standard product surface and `/apps/*` routes
- are always available. The connecting user must be allowed to install
+ before connecting." — configure a valid TLS certificate first. Apps is a
+ standard product surface and `/apps/*` routes are always available. The connecting user must be allowed to install
integrations in their Notion workspace.
-- How to verify: visit `/PAP/apps/connect?source=notion`, complete the Notion
+- How to verify: visit `/ACME/apps/connect?source=notion`, complete the Notion
consent flow, and land on the wizard's actions step listing `notion-*`
tools. Then confirm an agent run sees Notion tools through the runtime MCP
gateway and that a write call such as `notion-create-pages` follows the
@@ -1950,12 +2019,13 @@ plain-HTTP non-loopback origins.
### Resource Filters
-- Required filters: workspace, page, database (per FIRST-30).
+- Required filters: workspace, page, database.
- Optional filters: object type, database/data-source scope.
- Write-enabling filters: workspace plus page/database scope for
create/update.
-- Enforced by: gateway policy plus filters-as-config in v1; the FIRST-30
- "thin wrapper for block/database policy" is explicitly deferred. Notion-side
+- Enforced by: gateway policy plus filters-as-config in v1; a separate
+ block/database-policy wrapper is deferred. A saved filter is not proof of
+ enforcement: test an out-of-scope request through the gateway. Notion-side
scoping also applies — the consent step lets the user share only selected
pages/databases with the integration.
@@ -1988,10 +2058,30 @@ The shipped `packages/shared/src/app-definitions/notion.json` (regenerate via
### Actions
-Notion's hosted server exposes ~20 `notion-*` tools. Representative risk
-classes below; the full catalog review with per-tool defaults is PAP-16652
-(P4). Changed-action quarantine applies only when the connection explicitly
-enables `quarantineNewEntries`.
+The recorded Notion catalog exposed about 20 `notion-*` tools. The table below
+is representative, not an exhaustive allowlist. On each implementation or
+catalog change, enumerate the actual tools and complete the following review
+for every tool before enabling it:
+
+1. Record its stable name, input/output schema hash, and read/write/destructive
+ classification based on what it does, not its name or provider annotation alone.
+2. Map workspace, page, and database selectors to the actual enforcement
+ boundary. Prove an out-of-scope call is denied; do not promise a filter that
+ the gateway or provider cannot enforce.
+3. Record profile visibility and the effective policy. The current S3 default
+ allows active actions; any narrower provider/operator policy needs its own
+ explicit rule and test. Keep permanently blocked tools disabled.
+4. Specify argument/result redaction and the expected actor, resource, decision,
+ reason, and outcome audit fields. Test an ungranted actor and revoked connection.
+5. Identify plan-gated tools and unavailable capabilities. Catalog discovery
+ alone does not prove a listed tool can execute for the connected account.
+6. Record how newly discovered or schema-changed tools are treated. Changed-action
+ quarantine applies only when the connection enables `quarantineNewEntries`;
+ test that behavior rather than relying on a manifest declaration.
+
+Keep the completed inventory with the connector's accessible review evidence.
+A new delete/archive/bulk tool requires a fresh risk review; it must not inherit
+a read classification from these examples.
| Tool | Risk | Default status | Filters | Approval default | Audit fields | Negative case |
| --- | --- | --- | --- | --- | --- | --- |
@@ -2007,7 +2097,7 @@ method S4 or add a reviewed narrow policy and tests before enabling it.
### Wizard Path
-1. Operator opens `/PAP/apps/connect?source=notion` (or the Notion gallery
+1. Operator opens `/ACME/apps/connect?source=notion` (or the Notion gallery
card → Connect). The deep link POSTs connect immediately and redirects the
browser to `auth.startUrl`.
2. Operator completes Notion consent (workspace picker → approve).
@@ -2038,10 +2128,10 @@ the TLS guidance error above — the operator never reaches Notion.
### Validation Hook
-End-to-end evidence belongs to PAP-16654 (P6) and the PAP-12373 matrix:
+Collect end-to-end evidence using the production validation matrix above:
- Zero-setup OAuth connect succeeds on
- `https://paperclip-dev.tail29c1aa.ts.net/PAP/apps/connect?source=notion`
+ `https://paperclip.example.com/ACME/apps/connect?source=notion`
with no pre-provisioned OAuth env vars (proves DCR).
- Catalog discovery lists the expected `notion-*` tools and applies the
connection's declared changed-tool behavior.