631a6a0c53
Ships the v2026.817.0 docs to live: the doc content that was authored and verified earlier, plus a full screenshot overhaul. The content half (`cdf81e2` and the nightly commits behind it) has already been reviewed. **The screenshots are the part that needs eyes** — `f24d734`, 342 PNGs. ## Screenshots Everything was recaptured against the release commit `213dabab4f8e1f3bb1803a2924c0fea1289fcd4c` (`upstream/candidate/release-2026.817.0`). The previous shots were 375 parent-commits stale (v2026.720.0), with 228 of 310 entries flagged pending. All 342 registry entries now carry that SHA. > ⚠️ Worth knowing: the release commit is **not** an ancestor of the parent's > `master`, and local `master` was four days *older* than it. Capturing against > `master` would have both missed release UI and leaked 93 post-tag commits' worth > of UI into the release docs. ### New coverage (34 entries) Three guides shipped with **no images at all** despite being 115–136 lines. They now have them: | Guide | Shots | |---|---| | `guides/day-to-day/decisions.md` | queue, an agent-proposed decision with its options, triage strip, filter panel, named queue, Decided curtain, empty state | | `experimental/status-cards.md` | board, New card dialog, and all four drawer tabs | | `experimental/task-chat.md` | thread, composer mode picker, side pane | | `reference/api/secrets.md` | the board-side Proposals tab | Chat-Style Tasks is captured in a **separate pass**: `enableTaskChatRedesign` is instance-wide, so leaving it on would have turned every classic issue/task/work-mode shot into the redesigned chat. ## Two defects that were already live Both were shipping in the docs before this PR: 1. **`issues/detail-chat.png` and the `tasks/*` shots were mostly plugin debug output.** The Kitchen Sink example plugin mounts a panel into the issue page that dumps the raw issue JSON, and the seed installed it. Those guides were illustrating a debug panel instead of the task page. The seed no longer installs it. 2. **The seeded task thread was a monologue** — four board-user messages in a row, because the board actor cannot post agent comments. It is now a real two-sided exchange. ## Targets repointed because the UI moved | Target | Why | |---|---| | `activity/*` | `Activity.tsx` deleted; `/activity` renders `pages/audit/CompanyActivity.tsx` | | `experimental/cloud-upstream` | `CloudUpstream.tsx` deleted; the route now redirects to `/company/export` | | `settings/*`, `plugins/*`, `adapters/*` | `/instance/settings/*` are legacy redirects now | | `dashboard/stale-tasks-panel` | panel removed from `Dashboard.tsx` — target dropped | Plus eight targets with **silent selector drift**. A failed interaction step falls back to "whatever state was reached", so these had been quietly producing wrong images — a plain inbox where the doc promised a mode picker, a whole dashboard where it promised one panel. Full table in `docs/user-guides/screenshots/SCREENSHOTS_PLAN_v2026.817.0.md` §C2. ## Pipeline Decisions, status-card summaries and secret proposals are all **agent-authored**, and the board actor the seed runs as is refused by every one of them (`"Agent run context required"`, `"Secret proposals require a verified run-bound agent token"`). Rather than insert rows behind the API, `seed-new-surfaces.mjs` borrows the two doors a real run already has — a board-minted agent API key, and a locally signed agent JWT — so every write goes through the production code path. Also: - `capture.mjs` records a real `captured_against` on a detached checkout instead of the literal string `"HEAD"` (which is what every pre-2026.817 entry recorded), and gains a `scrollTo` step for content below the fold. - `run.mjs` gains `--serve` for iterating on the seed, the task-chat phase, and a keeper that holds the demo board's issue statuses steady — the demo `process` agents finish runs without declaring a disposition, so the stalled-work sweep re-blocks issues every few minutes over a capture that runs far longer. ## Reviewing Light and dark both captured at 1440×900 @2x. The new surfaces are the ones to scrutinise; the rest is a like-for-like refresh. ### One leftover Dropping `dashboard/stale-tasks-panel` leaves `{light,dark}/dashboard/stale-tasks-panel.png` tracked but unused — they need deleting by hand. 🤖 Generated with [Claude Code](https://claude.com/claude-code) --------- Co-authored-by: Claude Opus 4.8 (1M context) <[email protected]> Co-authored-by: DevRel Gemini <[email protected]> Co-authored-by: Paperclip <[email protected]> Co-authored-by: Dotta <[email protected]> Co-authored-by: ClaudeCoder <[email protected]>
4.2 KiB
Prepare MCP Integration
Take a new MCP or vendor integration from an input link or brief all the way to delivery — cited research first, an explicit human approval gate in the middle, then one governed Paperclip connector per approved connection.
A two-phase playbook for researching and shipping MCP/vendor integrations in a way people can review and sign off on. It turns a link or a short vendor brief into a cited research pull request, waits for a human to accept the exact revision, and only then writes the connector code — one Paperclip pull request per approved connection.
This is an optional catalog skill — opt-in (install when you need it). For how to install, audit, update, assign, and reset catalog skills, see the Skills reference.
When to use
- You're researching a new MCP server or vendor integration and want the findings written up with sources before anyone commits to building.
- An engineer, product manager, or researcher needs a paper trail — what the connector would do, which connections it covers, and who approved it — before code lands.
- You want new connector work delivered under the playbooks and approval gates, not stitched together ad hoc.
When not to use
- You're doing ad hoc connector coding that intentionally bypasses the playbooks — this skill exists to prevent that.
- There's no integration to research or deliver yet, just an open-ended question about a vendor.
The two-phase flow
The skill keeps research and implementation strictly separate, with a human decision between them.
Phase A — Research (no implementation)
Starting from the input link or vendor brief, Phase A produces a reviewable, cited research pull request in the paperclip-content repository. It gathers what the integration would involve and writes it up with its sources, so a person can read the findings and decide. No connector code is written in this phase.
Human-approval gate
Phase B does not start on its own. A human has to explicitly accept the exact research revision — bound to a single pull-request head SHA — along with the specific set of connections to build. Approving one revision does not approve a later one; if the research changes, it needs approval again.
Phase B — Implementation
Only after that approval does the skill implement the connector in the Paperclip app. It opens one Paperclip app pull request per approved connection, so each connection is reviewed and shipped on its own.
The one-PR-per-connection rule
Every approved connection gets its own Paperclip app pull request. Connections are not bundled together — this keeps each one reviewable in isolation and makes it clear exactly what was approved and shipped for each.
The secrets rule
Vendor credentials always live in approved secret storage — never anywhere else. They must not appear in briefs, catalog files, issue text, plans, logs, branch names, commits, or pull requests. If a credential is needed, it is referenced from secret storage, not pasted into any artifact the skill produces.
Catalog metadata
| Field | Value |
|---|---|
| Catalog id | paperclipai:optional:software-development:prepare-mcp-integration |
| Canonical key | paperclipai/optional/software-development/prepare-mcp-integration |
| Catalog path | catalog/optional/software-development/prepare-mcp-integration |
| Kind | optional |
| Category | software-development |
| Slug | prepare-mcp-integration |
| Trust level | markdown_only |
| Compatibility | compatible |
| Default install | false |
| Recommended roles | engineer, product-manager, researcher |
| Requires | git, gh, curl |
| Tags | mcp, integrations, connectors, research, github, human-approval |
See also
- Optional skills — all optional catalog skills grouped by category.
- Skills reference — file shape, install pipeline, catalog browse/install/audit/update/reset, assignment, and troubleshooting.
- App-shipped catalog — how bundled and optional catalog skills are versioned and kept current.
- Skills guide — the UI walkthrough and built-in catalog overview.