DottaandPaperclip
45862dd210
## Thinking Path > - Paperclip is the open source app people use to manage AI agents for work. > - Its user journeys span tasks, agents, projects, connected apps, governance, and CLI operations. > - Existing tests do not provide a shared index of entry points and verification steps. > - Contributors need to see which surfaces a change affects and what evidence exists. > - This pull request adds an optional product feature map with recipes and explicit coverage gaps. > - The map adds no CI checks or required maintenance for future pull requests. > - Contributors can use it to find verification steps and state what they checked. ## Linked Issues or Issue Description **Issue type** Missing documentation. **Where is the issue?** User-journey verification guidance in AGENTS.md and doc/DEVELOPING.md. **What's wrong?** There is no shared index of product features, user entry points, available test evidence, and remaining coverage gaps. Shared components can hide differences between their hosts. **Suggested fix** Add a documentation-only capability index and verification recipes. The format takes inspiration from [Omnigent's feature map](https://github.com/omnigent-ai/omnigent/tree/91acfbbb59f6fc210ff95a9e9428aadd62e06582/feature-map). The recipes describe Paperclip's own behavior and tests. Searched GitHub PRs and issues for `feature map` and `feature-map`. No duplicate change was found. Checked ROADMAP.md. This PR documents existing capabilities. ## What Changed - Added 35 feature recipes, 171 named sub-features, and 91 entry points across product, CLI, operator, and developer surfaces. - Each recipe describes setup, expected results, existing automated evidence, manual verification, and coverage gaps. - Added a dated source snapshot of 185 non-test page TSX modules in 15 areas. The snapshot describes documentation coverage, not runtime health. - Included entry points within existing pages, CLI/API operations, and experimental surfaces. Identified helper-only test evidence where a rendered journey has no automated proof. - Linked the map from AGENTS.md and doc/DEVELOPING.md as an optional reference. - The final diff contains only Markdown and the inventory JSON. It adds no checker, tests, package commands, workflows, dependencies, scheduled work, or mandatory inventory updates. ## Verification - PASS: local documentation links resolve and the inventory JSON parses. Confirmed the final PR diff contains only 39 documentation files. - PASS: `node --test '.github/scripts/tests/*.test.mjs'` — 381 existing tests after removal of the feature-map tests. - PASS: `git diff --check`. - Earlier local build and typecheck passed. The full local test run was stopped after 26 minutes with failures in unchanged chat-channel and native-runner integration tests. It did not complete. These application checks were not repeated for the documentation-only removal. - [CI on the preceding head](https://github.com/paperclipai/paperclip/actions/runs/37398407523) passed all applicable checks. Checks on the final documentation-only head are pending. - PASS: Greptile review on final head `45c4b0aeb26540324825da43e81bee2336ad1c1f` is 5/5. There are no unresolved findings. - Live product/provider journeys were not run to author the map. The recipes identify available evidence and manual steps, not new qualification results. ## Risks Low product risk: the PR changes documentation only. Recipes and the source snapshot can become stale. Maintenance is optional and based on review. Linked tests do not prove that every documented journey works. The map states remaining coverage gaps. ## Model Used OpenAI Codex, GPT-6 family, with repository inspection, reasoning, tool use, and code execution. The exact serving model ID and context window were not exposed in this session. ## 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 (only public GitHub `#NNN` / `github.com/paperclipai/paperclip` URLs) - [x] My branch name describes the change (e.g. `docs/...`, `fix/...`) and contains no internal Paperclip ticket id or instance-derived details - [x] I have run tests locally and they pass - [x] I have added or updated tests where applicable - [x] I have updated relevant documentation to reflect my changes - [x] I have considered and documented any risks above - [ ] 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>
7.8 KiB
Connection setup
People connect an app or account, choose who may use it, and recover incomplete setup from either Apps or a task that needs access. A saved draft, a completed provider login, a usable connection, and a resumed task are separate checkpoints. Chat channels additionally require an endpoint and linked sender identity.
Sub-features
catalog: find a provider, inspect its available methods, and open setup; unavailable methods explain their prerequisite rather than silently switching.identity-and-access: select personal/shared identity and eligible agents; an empty explicit selection and company-wide access must not be confused.credentials: provider sign-in, key, or generic MCP URL follows its supported setup method; credentials are not retained in browser draft storage.handoff: provider popup/full-page callback returns to the correct setup host with the original task intent and identity choice intact.draft-recovery: cancel, Back, Save & exit, reload, Finish setup, and reconnect preserve the exact draft rather than creating duplicate connections.task-request: only the addressed person resolves the requested connection; usable access releases the pending task request through normal continuation.channel-setup: provider endpoint, represented agent, linked sender, and communication instructions are configured before an external message is used.failure: denied login, unreachable/private URL, expired credentials, and permission errors leave an actionable state rather than a false success.
How to get to it (user POV)
apps-catalog
Open Apps (/apps), choose an app, and connect from its landing page. Select an
available method and access, then complete setup. Existing connections open
their details; unfinished ones offer a way to finish setup.
mcp-link
Use Connect with a link or /apps/byo for a generic MCP server. Paste its
URL, select access, and follow the probe's sign-in/key guidance. Provider-specific
catalog setup and a generic endpoint may use different flows.
task-request
Open the task's pending connection request and its setup action as the named user. Setup can open in a task dialog and may use an OAuth popup. Follow the request's original link if setup falls back to a standalone page.
resume-connection
From Apps or connection details, use Finish setup, reconnect, or the offered authentication recovery action. Reload or return from the provider before checking whether the same saved connection became usable.
chat-channel
With chat connectors enabled, select a supported chat/email provider in Apps
or open /apps/chat/connect. Complete that provider's endpoint setup, then
open its settings (/apps/chat/:endpointId/settings). Follow identity linking
as the intended sender before messaging the agent externally.
Driving it
Preconditions: follow the baseline. Choose a disposable provider account/resource and record its auth method, deployment mode, account ownership, and access selection. For live setup, use the provider's documented prerequisites in the connector playbook. Automated fixtures do not establish OAuth registration, public callbacks, or production provider access.
apps-catalog
Automated: Browse, unconnected app, and AppsConnect cover catalog entry, access selection, provider-specific method choices, and setup failures with mocked APIs. Connection intents drives store and task setup against one fake provider through a useful continuation:
pnpm exec vitest run ui/src/pages/apps/Browse.test.tsx ui/src/pages/apps/AppsConnect.test.tsx
pnpm exec playwright test -c tests/e2e/playwright.config.ts tests/e2e/connection-intents.spec.ts
Manual: connect from an unconnected provider landing. Select the intended identity and agent access, complete authentication, reload, and inspect the saved connection. Run a permitted read-only action with an eligible agent and verify its useful result. Try an ineligible agent and confirm denial. Repeat with a user who cannot install company-wide; the UI must not imply broad access.
mcp-link
Automated: AppsConnect's generic MCP cases cover probe-driven auth, private or unreachable endpoints, preregistered clients, secret-backed headers, and unsafe authorization URLs. These are component/API mocks, not remote provider proof.
Manual: connect a known test MCP URL through the link flow, verify its saved endpoint and a read-only action, then repeat with a bad URL and wrong credential. The error should explain the next action and preserve non-secret setup context. Test no-auth and authenticated endpoints separately; never infer one from the other.
task-request
Automated: interaction card checks addressed-user controls. AppsConnect tests cover page/dialog parity, task-bound OAuth, popup handoff, and verifying a saved connection before closing. The connection-intents browser suite above exercises fixture-backed continuation.
Manual: ask an agent to use an unavailable app, open its request as the named user, and complete setup in the dialog. Verify the card settles, the exact task resumes, and the agent returns a useful provider result. Repeat the page-host fallback and denied OAuth path. As another user, confirm that merely seeing the task does not grant the right to resolve the request.
resume-connection
Automated: AppsConnect tests cover exact-draft resume, declined OAuth, reconnect lookup failure/retry, response-lost creation, archived connection revival, and saved account reuse. App detail covers the connection host. These tests do not complete a real provider login.
Manual: leave setup through its footer, reload Apps, choose Finish setup, and confirm the same connection is resumed. Decline provider login and recover from that checkpoint. Reconnect an expired disposable account and verify a permitted action afterwards. Count connections before/after to catch accidental duplicates.
chat-channel
Automated: setup routing, saved setup state, email setup, and identity confirmation cover shared UI logic with fixtures. Provider-specific live setup is not implied.
Manual: complete setup for one named provider, reload endpoint settings, link the intended sender, and send a disposable message. Verify one task and a useful reply in the originating conversation. Inspect an unlinked sender's denial and the endpoint's pause behavior. Repeat independently for each provider at issue; Slack setup does not qualify Discord, Telegram, GitHub, email, or iMessage.
Gotchas
- A successful OAuth callback is not proof of saved connection access or task continuation. Verify all three checkpoints.
- Personal identity, shared account access, and per-agent access are distinct. Connecting an account does not waive an Off action or Ask first review.
- A tool app connection is not a chat endpoint. The same provider can offer both.
- Old Apps/Connections URLs can redirect to Apps. Use the current navigation and record the actual destination rather than documenting an obsolete screen.
- Full provider matrix, AI-account selection, gateway/profile administration, and account revocation lifecycles remain outside this seed recipe.
- For governed actions after setup, use questions and approvals.