From c9e867797939fe069278c4ae660f86f7692ed866 Mon Sep 17 00:00:00 2001 From: Dotta <34892728+cryppadotta@users.noreply.github.com> Date: Sat, 19 Sep 2026 08:16:56 -0500 Subject: [PATCH] docs: document chat connector UX and make the runbook self-contained (#13675) ## Thinking Path > - Paperclip helps people manage AI agents and their work. > - Connections let agents work with external services. > - Contributors use the connection runbook to add and review providers. > - The runbook depended on private issue references and did not capture the chat setup UX conventions. > - This pull request adds a chat connector UX guide and puts the missing requirements in the runbook. > - Contributors can apply the guidance without access to the internal issue tracker or a personal skill installation. ## Linked Issues or Issue Description **Issue type** Missing documentation and unclear contributor instructions. **Where is the issue?** `doc/connections/CONNECTOR-PLAYBOOK.md` and the chat connector setup guidance. **What's wrong?** The runbook sent contributors to private issues for validation, OAuth ownership rules, and catalog review. The Slack setup work also established useful UX rules that other providers should share. **Suggested fix** Add a companion UX document. Link it from the runbook. Include validation and review requirements directly in the public documentation. Use portable company and instance examples. Related implementation: https://github.com/paperclipai/paperclip/pull/13638. A search of related PRs found no duplicate documentation change. ## What Changed - Add `CHAT-CONNECTOR-UX.md` with setup, credential, identity, footer, test, and management conventions. - Include adaptation examples for Discord, Telegram, and email providers. - Link the companion from the runbook introduction, contents, and UX section. - Replace private issue references with inline architecture boundaries, risk classification, validation evidence, and per-tool review requirements. - Replace personal deployment examples with sample company and instance addresses. - Mark the recorded Notion provider observations as a dated snapshot. ## Verification - Passed `git diff origin/master --check`. - Passed local validation of all 35 relative links and heading anchors in the two documents. - Passed code-fence and private-reference scans. - Reviewed the guide against the Slack setup decisions and the existing connection docs. - Attempted `pnpm -r typecheck`, `pnpm test:run`, and `pnpm build`. They could not complete because this fresh worktree has no installed dependencies (`@types/node` and the CLI `tsx` entry point are missing). No application code changed. - GitHub CI passed on commit `070fefc8b2513cb9469bae76e66940c33c1465ea`, including typecheck, build, general and serialized tests, runner verification, browser tests, and canary dry run. - Security checks passed. Greptile scored the current commit 5/5 with no findings or unresolved review threads. ## Risks Low risk. This changes two documentation files only. Provider APIs and screens can change. The guide requires authors to verify provider capabilities, and the Notion example identifies its observation date. The documentation does not assert new runtime support. ## Model Used OpenAI GPT-6 through Codex. The exact runtime model ID and context window are not exposed in this session. Used reasoning, repository inspection, shell execution, and documentation editing. ## Checklist - [x] I have included a thinking path that traces from project context to this change - [x] I have specified the model used (with version and capability details) - [x] I have checked ROADMAP.md and confirmed this PR does not duplicate planned core work - [x] I have searched GitHub for duplicate or related PRs and linked them above - [x] I have either (a) linked existing issues with `Fixes:` / `Closes` / `Refs` OR (b) described the issue in-PR following the relevant issue template - [x] I have not referenced internal/instance-local Paperclip issues or links - [x] My branch name describes the change and contains no internal issue id or instance-derived details - [x] I have run the applicable documentation checks locally and they pass; application checks were attempted and the environment limitation is recorded above - [x] I have added or updated tests where applicable (documentation validation; no runtime changes) - [x] I have updated relevant documentation to reflect my changes - [x] I have considered and documented any risks above - [x] All Paperclip CI gates are green - [x] Greptile is 5/5 with no open P2s, recommendations, or follow-ups - [x] I will address all Greptile and reviewer comments before requesting merge Co-authored-by: Paperclip --- doc/connections/CHAT-CONNECTOR-UX.md | 295 ++++++++++++++++++++++++++ doc/connections/CONNECTOR-PLAYBOOK.md | 212 ++++++++++++------ 2 files changed, 446 insertions(+), 61 deletions(-) create mode 100644 doc/connections/CHAT-CONNECTOR-UX.md 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.