8121a9c947
Ships the docs for **paperclip v2026.720.0** to `docs.paperclip.ing`. Window: `v2026.707.0...v2026.720.0` — 196 commits, 1,523 changed files, 0 truncated leaves. Most of this release was already drafted on `nightly` over the past cycle (Cases, Folders, Decision Training, Attention, Built-in Agents, company skill policy, inbox agent policy, `costStatus`, the ACP engine graduation and `acpx_local` retirement, and `PAPERCLIP_TOOL_ACTION_SIGNING_SECRET`). This PR adds the surfaces nightly had **not** yet covered, then stamps the release version across everything touched this cycle. ## New pages **`docs/reference/api/tool-gateway.md`** — the MCP Tool Gateway, the headline experimental feature. Covers applications and connections, catalog entries and risk levels, profiles/entries/bindings, the tool-access policy and its decision outcomes, named MCP gateways and their tokens, the audit feed, and the Smoke Lab. Documents the five `tools:*` permission keys and the viewer/membership rules on routes that don't use a permission key. Flags both experimental gates (`enableApps`, and `enableSmokeLab` separately). **`docs/reference/api/summary-slots.md`** — the built-in Summarizer and summary slots. Covers slot addressing (`scopeKind` / `scopeId` / `slotKey`), generation, revisions, and the `enableSummaries` gate. Cross-references Built-in Agents rather than duplicating it. ## Updated **`docs/guides/org/skills.md`** — Skill Studio (the three-pane authoring workspace, saved inputs, test runs and their unavailability reasons, run templates, version history), nested skill folders and the My Skills view, importing skills straight from a project, and company skill forks. Cross-references the existing Folders and Company Skill Policy API pages instead of restating them. ## Release stamping `paperclip_version: v2026.720.0` applied to all 26 pages touched this cycle — bumped on 10 that already had frontmatter, added to 13 that had none (including the API pages nightly authored, which were intentionally versionless until they merged to `main`). ## ↻ Renames detected `detect-renames.mjs` reports no directory renames. It flags one `removed_dirs_no_match`: - `packages/adapters/acpx-local` — **already reconciled on nightly.** The adapter was retired upstream (ACP became a capability of each harness adapter rather than a standalone adapter). `docs/reference/adapters/acpx-local.md` is now a retired stub that points at Claude Code / Codex / Gemini CLI and documents the automatic migration. No action needed. ## Screenshots — full overhaul recommended **248 of 298** registry entries are stale. This release landed a design-system convergence (single-source design tokens, retuned theme, broad Card/Badge adoption, a multiplicative radius ladder, unified list surfaces, Lucide task-status glyphs), so nearly every captured surface moved. This is an overhaul cycle, not a targeted refresh: ```sh npm run screenshots:refresh:all ``` Full per-entry breakdown in `SCREENSHOTS_PENDING.md`. Captures go to their own PR for review — nothing is auto-pushed. ## Verification - **Drift:** clean — 0 records against `903bd15` (8 parent paths, 57 CLI commands, 66 env vars, 389 REST routes, 18 permission keys, 4 roles). - **Claim verification:** `verify-edit.mjs` against `v2026.720.0` — **0 unverified, 0 suspicious** across all three authored files. - **Reconciliation:** no disappeared manifest entries. - **`npm run docs:build`:** passes — 169 markdown files, sitemap and robots generated. - **`npm run sync:check`:** links clean (172 files), nav clean, screenshots indexed, drift clean. - **Nav orphans:** `docs/reference/cli/commands.md` and `docs/reference/cli/control-plane-commands.md` — intentional redirect anchors, expected. `.sync-state.json` bumped to `base_release_tag: v2026.720.0` / `base_release_sha: 903bd157…`, which also repoints the drift checker's pinned ref (the previous `f12bb27…` no longer resolves upstream). No open `nightly-draft/*` PRs to fold in. ## Checklist - [ ] Tool Gateway page reads correctly for an operator enabling `enableApps` for the first time - [ ] Summary Slots experimental gating is accurate - [ ] Skill Studio guide matches what you see in the running UI - [ ] Decide whether to run the screenshot overhaul before or after merging this - [ ] **After squash-merging: run `node scripts/sync/realign-nightly.mjs release/v2026.720.0 --push` before the next nightly sync.** The squash severs `main`↔`nightly` ancestry; the realign (shipped in this PR) prevents add/add conflicts at the next nightly run. 🤖 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]>
6.5 KiB
paperclip_version
| paperclip_version |
|---|
| v2026.720.0 |
Instance Admin API
A grab-bag of instance-scoped REST endpoints that don't fit neatly into the other API pages: general and experimental instance settings, on-demand database backups, the LLM reflection endpoints, environments (sandbox/runtime drivers), and execution-workspace lifecycle.
These surfaces are stable enough to call from your own tooling, but they are intentionally narrow — most operators reach them through the UI, the CLI, or via the paperclipai doctor command rather than by hand.
All routes are mounted under
/api. Most require instance-admin or board authentication; per-route notes call out exceptions.
Instance settings
| Endpoint | Purpose |
|---|---|
GET /api/instance/settings/general |
Read general instance settings (display name, defaults, etc.). |
PATCH /api/instance/settings/general |
Update general settings. Body is validated against patchInstanceGeneralSettingsSchema. |
GET /api/instance/settings/experimental |
Read the experimental-features block. |
PATCH /api/instance/settings/experimental |
Toggle experimental features. Body is validated against patchInstanceExperimentalSettingsSchema. |
POST /api/instance/settings/experimental/issue-graph-liveness-auto-recovery/preview |
Preview what the auto-recovery sweep would change without applying. |
POST /api/instance/settings/experimental/issue-graph-liveness-auto-recovery/run |
Run the auto-recovery sweep. |
The experimental "issue-graph-liveness auto-recovery" routes are paired: preview produces a dry-run summary; run applies the same changes. Both share the issueGraphLivenessAutoRecoveryRequestSchema body shape.
The experimental-settings response and patch body include enableBuiltInAgents as a boolean. Set it to true before using the Built-in Agents API; while it is off, those routes return 404 Not Found.
Database backups
POST /api/instance/database-backups
Trigger a manual database backup. Returns a structured result that includes the backup directory, retention policy, and timing. Scheduled backups follow the same code path but are not exposed as a separate route.
Instance-admin only.
Claim first instance admin
POST /api/bootstrap/claim
On a brand-new private instance that requires login, this lets the first person to sign in promote themselves to instance_admin — no manual database seeding. The first caller to claim wins; everyone after them is locked out.
Availability. This route only exists when the instance runs with deploymentMode set to authenticated and deploymentExposure set to private. On any other configuration it returns 404 with Browser first-admin claim is not available.
Authentication. The caller must be a signed-in browser session (a board actor whose session source is the browser). Other callers — agents, CLI tokens, unauthenticated requests — get 401 with Sign in from a browser session before claiming first admin.
Behaviour. If no instance_admin exists yet, the signed-in user is promoted to instance_admin. The claim is atomic — the table is locked so exactly one user can win. If the instance has already been claimed, the route returns 409 with Someone else has already claimed this instance.
The request takes no body. On success the response is:
{ "claimed": true, "userId": "<the promoted user's id>" }
LLM agent-configuration reflection
These endpoints exist so agents can introspect what server-side adapters and icons are available to them.
| Endpoint | Purpose |
|---|---|
GET /api/llms/agent-configuration.txt |
Plain-text dump of available agent adapters and their declared shape. |
GET /api/llms/agent-configuration/:adapterType.txt |
Same, scoped to one adapter type. |
GET /api/llms/agent-icons.txt |
List of supported agent-icon names (AGENT_ICON_NAMES). |
Access is limited to board callers and agents whose permissions include canCreateAgents — the routes return 403 otherwise.
Environments
Environments are the plugin-managed execution backends declared by environment-driver plugins (custom sandboxes, runners, etc.).
| Endpoint | Purpose |
|---|---|
GET /api/companies/:companyId/environments |
List configured environments for the company. |
GET /api/companies/:companyId/environments/capabilities |
List the capabilities reported by available environment drivers. |
POST /api/companies/:companyId/environments |
Create an environment. Body validated against createEnvironmentSchema. |
POST /api/companies/:companyId/environments/probe-config |
Probe a candidate environment config without persisting. Body validated against probeEnvironmentConfigSchema. |
GET /api/environments/:id |
Read one environment. |
PATCH /api/environments/:id |
Update an environment. Body validated against updateEnvironmentSchema. |
DELETE /api/environments/:id |
Delete an environment. |
POST /api/environments/:id/probe |
Probe an existing environment (driver health check). |
GET /api/environments/:id/leases |
List active leases on the environment. |
GET /api/environment-leases/:leaseId |
Read a single lease. |
Execution workspaces
Execution workspaces are the materialised working directories Paperclip creates for an issue run.
| Endpoint | Purpose |
|---|---|
GET /api/companies/:companyId/execution-workspaces |
List execution workspaces for the company. |
GET /api/execution-workspaces/:id |
Read one workspace. |
GET /api/execution-workspaces/:id/close-readiness |
Whether the workspace is safe to close (no pending operations, no dirty state). |
GET /api/execution-workspaces/:id/workspace-operations |
List the operations recorded against the workspace. |
PATCH /api/execution-workspaces/:id |
Update a workspace. Body validated against updateExecutionWorkspaceSchema. |
POST /api/execution-workspaces/:id/runtime-services/:action |
Run a runtime-service control action against the workspace. |
POST /api/execution-workspaces/:id/runtime-commands/:action |
Run a runtime-command control action against the workspace. Both routes share the workspaceRuntimeControlTargetSchema body and the same handler. |
Related
- Reference → Adapters API — adapter registry endpoints.
- Reference → Plugins API — plugin install and lifecycle.
- Reference → Deployment → Environment Variables — the env-vars these admin surfaces interact with.