paperclipai/paperclip-docs

0 Fork 0

mirror of https://github.com/paperclipai/paperclip-docs.git synced 2026-11-10 03:51:29 -10:00

Files

T

c65bc9a9bf Release docs for paperclip v2026.916.0 (#125 )

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]>

2026-09-17 11:15:48 +02:00

5.2 KiB

Raw Permalink Blame History

paperclip_version, seo_title, seo_description

paperclip_version	seo_title	seo_description
v2026.916.0	The managed-agent Command	Provision and qualify a locked-down Anthropic managed agent and environment, then save the company profile Paperclip uses to run it.

Managed Agent Command

managed-agent provisions the remote, provider-hosted runtime a company can use in place of a locally executed adapter. Today it targets Anthropic's Managed Agents beta: it creates (or adopts) a locked-down Agent and Environment on Anthropic's side, checks that both match Paperclip's strict no-network, no-tools safety profile, and then stores a managed-agent profile on your company that the runtime reads when it dispatches work.

paperclipai managed-agent setup --company-id <company-id> \
  --profile-key <key> \
  --display-name "<name>" \
  --api-key-secret-id <uuid>

This is a board-operator, one-time provisioning task, not something you run per heartbeat. You set a company up once so its agents can run on the managed provider; after that the runtime does the dispatching.

Note: The command reads ANTHROPIC_API_KEY from the CLI process environment to talk to Anthropic directly. Export a valid key before you run it, or the command stops before doing anything.

`managed-agent setup`

setup is the only subcommand. It creates or adopts a locked-down Anthropic Agent and Environment, verifies them, and stores the resulting company profile.

Under the hood it either finds existing Anthropic resources tagged with your --profile-key (or the explicit ids you pass) or creates new ones with a fixed safety posture: an Environment with limited networking, no allowed hosts, and no installed packages, and an Agent with no tools, no MCP servers, no skills, and no multi-agent config. If anything you adopt does not match that posture, setup refuses it rather than trusting it.

# Provision from scratch, acknowledging the beta's retention terms
paperclipai managed-agent setup --company-id <company-id> \
  --profile-key acme-prod \
  --display-name "Acme Production" \
  --api-key-secret-id 6f1c2e3a-1b2c-4d5e-8f90-0a1b2c3d4e5f \
  --acknowledge-retention

# Adopt an Anthropic Agent and Environment you already created
paperclipai managed-agent setup --company-id <company-id> \
  --profile-key acme-prod \
  --display-name "Acme Production" \
  --api-key-secret-id 6f1c2e3a-1b2c-4d5e-8f90-0a1b2c3d4e5f \
  --agent-id <anthropic-agent-id> \
  --environment-id <anthropic-environment-id> \
  --acknowledge-retention

Required options

Flag	Use
`--profile-key <key>`	Required. Stable company profile key. It also tags the Anthropic resources so `setup` can find them again on a later run.
`--display-name <name>`	Required. Human-readable profile display name, also used to name the Anthropic Agent and Environment.
`--api-key-secret-id <id>`	Required. The id of an existing company secret that holds `ANTHROPIC_API_KEY`. Must be a UUID.

Optional options

Flag	Default	Use
`--model <id>`	`claude-sonnet-5`	The pinned Claude model. It must be the qualified Managed Agents model, `claude-sonnet-5`.
`--max-session-list-cost-usd <usd>`	`1.00`	Default hard session cost ceiling. Must resolve to at least one cent.
`--agent-id <id>`	(unset)	Adopt an existing Anthropic Agent instead of creating one.
`--agent-version <version>`	(unset)	Pin a specific existing Agent version.
`--environment-id <id>`	(unset)	Adopt an existing Anthropic Environment instead of creating one.
`--probe`	`false`	Read-only qualification. Verifies (or discovers) resources and prints the profile it would store, without creating or persisting anything.
`--acknowledge-retention`	`false`	Required to actually provision. Acknowledges the beta's data-retention terms and its non-ZDR, non-HIPAA status.

setup also accepts the standard client options and is company-scoped: -C, --company-id <id> is required (from the flag or your context profile), because the finished profile is stored against that company. See Common Options.

Tip: Run with --probe first. It exercises the whole discovery-and-verification path and shows you the exact profile that would be saved, so you can confirm the model, ceiling, and adopted resources before you commit them with a real run.

What gets stored

On a real (non-probe) run, setup stores a profile on the company that records the profile key and display name, the resolved Anthropic Agent id and pinned version, the Environment id, the default model and session cost ceiling, the id of the secret holding the key, and a qualification stamp describing the safety posture that was verified. With --probe, that same profile is printed instead of saved.

5.2 KiB Raw Permalink Blame History