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 <noreply@paperclip.ing>
This commit is contained in:
DottaandPaperclip authored and GitHub committed 2026-09-19 08:16:56 -05:00
1 parent 1ef3b08714
commit c9e8677979
2 files changed
+446 -61

No files matched your search

+295
View File
@@ -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.
+151 -61
View File
@@ -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<br/>/PAP/apps/connect?source=notion
participant UI as Paperclip UI<br/>/ACME/apps/connect?source=notion
participant S as Paperclip instance server<br/>(cloud or self-hosted — same path)
participant M as mcp.notion.com<br/>(MCP server + OAuth AS)
participant N as Notion web<br/>(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.<br/>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.