mirror of
https://github.com/paperclipai/paperclip-docs.git
synced 2026-11-09 04:09:33 -10:00
c65bc9a9bf
Brings **paperclip-docs** in line with paperclip **v2026.916.0**, shipping the `v2026.831.1 → v2026.916.0` cycle drafted on `nightly`, stamped to the release tag, with a documentation changelog entry. This branch was cut from `nightly` **after** merging `origin/main` into it, so it sits on top of the operator-first connectors catalog (#124) rather than reverting it. ## Manifest **New pages (4)** - `docs/reference/api/connection-intents.md` — Connection Intents API - `docs/reference/cli/connections.md` — `connections` command - `docs/reference/cli/managed-agent.md` — `managed-agent` command - `docs/reference/cli/test-drive.md` — `test-drive` command **Updated pages (17)** - Roles & Permissions + Company Administration — `tools:*` role-default changes - Connect an Agent to GitHub — managed GitHub connection (Connectors), Option C - Agents API — Managed/Remote Agent Profiles, `***REDACTED***` env serialization - Tool Gateway API — agent self-authorization (`start-authorization`, `token`) - Instance Admin API — instance-settings + task-drain routes - Plugin SDK — `ctx.access` + `ctx.authorization` clients, login-PTY/duplex streaming - Environment Variables — Paperclip ID Connector block + HTTP adapter allowlist var - Adapters: Codex (`gpt-5.6-sol` default, Fast mode, auth cache), Claude Code (Fable 5.1 + CLI floor), Grok Local (SuperGrok subscription auth), HTTP (SSRF guard), Sandbox Providers (Daytona warm runner), OpenCode (model pre-flight) - CLI: `adapter detect-model`, `onboard` tool-action signing secret - Command palette — recent tasks in sidebar - `docs/reference/changelog.md` — new `v2026.916.0` accordion entry All 21 touched pages stamped `paperclip_version: v2026.916.0`. ## Verification **Tag-accuracy gate (Phase 5.7)** — `check-tag-accuracy.mjs --tag v2026.916.0 --base main --head nightly` flagged 5 pages, **every one verified present in the code at the release tag** and cleared as known `verify-edit` false-positive classes. No content was quarantined; **no post-tag leaks**: | Page | Flagged claim(s) | Verified at tag | |---|---|---| | `cli/connections.md` | `PAPERCLIP_RUNTIME_TOOLS_*` (3) | present in `cli/src/commands/client/connections.ts` (runtime-injected env) | | `cli/managed-agent.md` | `--profile-key`, `--api-key-secret-id` | present in `cli/src/commands/managed-agent.ts` (`.requiredOption`/`.option`) | | `cli/test-drive.md` | `--harness` | present in `cli/src/commands/test-drive.ts` (`new Option`) | | `deploy/environment-variables.md` | `PAPERCLIP_ID_CONNECTOR_*` (5) | present in `.env.example` at tag | | `plugins/sdk.md` | `PLUGIN_*` (6) | present in `packages/plugins/sdk/src/index.ts` (exported constants) | Rationale: nightly's drafts were authored from parent `af8439a`, **226 commits inside the tag**, so they document in-tag surfaces by construction. ### ⚠ Drift `check-drift.mjs --against v2026.916.0` returned 14 records — **all verified present at the tag** (checker false positives), listed here for the reviewer to confirm: - **env-var (9, high-confidence in the tool, verified present):** `PAPERCLIP_WORKSPACE_GIT_SCAN_{CONCURRENCY,QUEUE_CAPACITY,TIMEOUT_MS,CACHE_TTL_MS}` and `PAPERCLIP_ID_CONNECTOR_{BASE_URL,ENVIRONMENT,INSTANCE_ID,SIGN_PRIVATE_KEY,SEAL_PRIVATE_KEY}` — all present in `.env.example` at the tag; the drift scanner's scoped file scan missed them. - **Verify: rest-route (5, medium-confidence):** `POST/PUT/GET /api/companies/import/transfers*` — present at the tag in `server/src/routes/companies.ts`, registered via the `COMPANY_IMPORT_TRANSFERS_ROUTE_PATH` prefix constant (the documented prefix/dynamic-registration blind spot). ### ⚠ Verification Failures None. All tag-accuracy and drift flags above were verified present at the tag. ### ↻ Renames detected None. The connectors catalog (`docs/connectors/**`) arrived via the `main` merge (#124), not as a renamed surface; no new top-level draft directories were introduced this cycle. ## Screenshots **238 of 342 screenshots** flagged stale across 50 routes (see `SCREENSHOTS_PENDING.md`). This is a wide 16-day window touching ~921 UI files, so most are dependency-touch flags rather than confirmed visual changes. Recommend `npm run screenshots:refresh` on this release branch as a dedicated follow-up before merge; PNGs go to a separate PR for human review. ## Build gates (all green on this branch) - `npm run docs:build` — 257 pages - `npm run docs:test` — SEO metadata, crawlable-links (71,749 links resolve), doc-link-resolution, skill-source-blocks, static-routes, hierarchical-nav ## Post-merge checklist (Phase 9 — do NOT skip) - [ ] Squash-merge this PR (repo is squash-only) - [ ] `git checkout main && git pull` - [ ] `git tag docs/v2026.916.0 && git push --tags` - [ ] `node scripts/sync/realign-nightly.mjs release/v2026.916.0 --push` (restore ancestry; keep nightly post-tag drafts) - [ ] Flip `nightly` `.sync-state.json` back to `"branch_mode": "nightly"` (leave `base_release_tag` at `v2026.916.0`) - [ ] Verify `docs.paperclip.ing` serves the release: a new page (`/reference/cli/test-drive/`), a changed page, and the changelog top entry reads `Docs for v2026.916.0` - [ ] If production is stale, republish: `npm run docs:build && npx wrangler pages deploy .site --project-name paperclip-docs --branch main` 🤖 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]>
64 lines
2.7 KiB
Markdown
64 lines
2.7 KiB
Markdown
---
|
|
paperclip_version: v2026.916.0
|
|
seo_title: The connections Command
|
|
seo_description: Search the connections catalog or request access to a service from inside an active heartbeat run, using the runtime tools the run provides.
|
|
---
|
|
|
|
# Connections Command
|
|
|
|
The `connections` commands let an agent look up connectable services and ask for access to them — from *inside* a running heartbeat run. They are how an agent discovers "is there a connector for this service?" and then raises the intent to connect it, without leaving the terminal environment the runtime hands it.
|
|
|
|
```sh
|
|
paperclipai connections search "<query>"
|
|
paperclipai connections request <service>
|
|
```
|
|
|
|
> **Note:** These commands only work during an active heartbeat run. They call runtime connection tools whose endpoints and token are injected into the run's environment (`PAPERCLIP_RUNTIME_TOOLS_CONNECTIONS_SEARCH_URL`, `PAPERCLIP_RUNTIME_TOOLS_CONNECTION_REQUEST_URL`, and `PAPERCLIP_RUNTIME_TOOLS_TOKEN`). Run them anywhere else and they stop with an error explaining they need the runtime connection environment from an active run.
|
|
|
|
---
|
|
|
|
## Search for a connection
|
|
|
|
`connections search` looks up services or capabilities in the connections catalog. The query is optional — omit it to browse.
|
|
|
|
```sh
|
|
paperclipai connections search "google calendar"
|
|
paperclipai connections search github
|
|
paperclipai connections search
|
|
```
|
|
|
|
| Argument / flag | Use |
|
|
|---|---|
|
|
| `[query]` | A service name or capability to search for. Optional; defaults to an empty search. |
|
|
| `--json` | Print the result as formatted (indented) JSON. |
|
|
|
|
The result is written to stdout as JSON. Without `--json` it is compact single-line JSON; with `--json` it is pretty-printed.
|
|
|
|
---
|
|
|
|
## Request a connection
|
|
|
|
`connections request` raises a connection request for a specific service, identified by its slug — the kind of value `connections search` returns.
|
|
|
|
```sh
|
|
paperclipai connections request google-calendar
|
|
paperclipai connections request github --json
|
|
```
|
|
|
|
| Argument / flag | Use |
|
|
|---|---|
|
|
| `<service>` | **Required.** The connectable service slug to request. |
|
|
| `--json` | Print the result as formatted (indented) JSON. |
|
|
|
|
Like `search`, the response prints to stdout as JSON, pretty-printed when you pass `--json`.
|
|
|
|
> **Tip:** Search first, request second. Take the service slug from a `search` result and feed it straight into `request` so you are asking for a service the catalog actually knows about.
|
|
|
|
---
|
|
|
|
## See also
|
|
|
|
- [Run Commands](./run.md) — the heartbeat runs whose environment makes these commands work.
|
|
- [Adapter Commands](./adapter.md) — the runtimes that execute agent work server-side.
|
|
- [Output and Scripting](./output-and-scripting.md) — working with the JSON these commands emit.
|