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.