paperclipai/paperclip-docs

0 Fork 0

mirror of https://github.com/paperclipai/paperclip-docs.git synced 2026-11-09 04:09:33 -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

6.2 KiB

Raw Permalink Blame History

paperclip_version, seo_title, seo_description

paperclip_version	seo_title	seo_description
v2026.916.0	The test-drive Command	Spin up an isolated, self-initialized Paperclip instance with a ready-made company and CEO agent so you can try the product locally.

Test Drive Command

test-drive is the fastest way to see Paperclip working on your own machine. One command starts a fresh local instance, creates a company and a CEO agent for you, seeds the provider credential that agent needs, and opens the dashboard in your browser. It is built for kicking the tyres — a manual, throwaway environment you can create, poke at, and walk away from.

paperclipai test-drive

The command runs a local Paperclip instance the same way run does, then bootstraps starter content on top of it. Nothing here talks to a remote control plane you already operate; it stands up its own.

Note: Use test-drive for evaluation and demos, not for a company you intend to keep. It runs in local_trusted mode, bound to loopback, in a data directory it treats as disposable. For a durable local setup, reach for run or the setup commands.

What it does, step by step

When you run test-drive, it:

Isolates the environment first. Before the CLI's normal config and .env loading happens, test-drive clears every PAPERCLIP_* variable (and a handful of others like DATABASE_URL, HOST, and PORT) from the process so a stray shell export cannot point it at some other instance. The one thing it preserves is the environment variable you named with --api-key-env, if you used it.
Redacts your API key. If you pass --api-key, the value is scrubbed from the process argument list immediately, so it does not leak into logs, telemetry, diagnostics, or crash output.
Asserts database isolation. It refuses to run against a data directory wired to an external PostgreSQL database (DATABASE_URL, DATABASE_MIGRATION_URL, or a config database.mode of postgres), so the test drive always uses its own embedded database.
Starts the instance. It boots a local server on a free loopback port (starting at 3100), repairing the data directory and accepting defaults without prompting.
Bootstraps a company and agent. If the data directory is empty, it creates a company, defines and stores the provider secret, and creates a CEO agent wired to the matching adapter. If a company already exists there, it reuses it and tells you the bootstrap flags were ignored.
Opens the dashboard. It prints the URL and opens it in your browser (unless you pass --no-browser).

Note: The data directory is retained when Paperclip exits. If you did not pass --data-dir, test-drive creates a fresh temporary directory for you and prints its path — clean it up yourself when you are done.

Choosing a harness and model

The --harness flag decides which adapter your CEO agent is created against, and therefore which provider credential it expects:

Harness	Adapter	Credential it looks for
`claude` (default)	`claude_local`	`ANTHROPIC_API_KEY`
`codex`	`codex_local`	`OPENAI_API_KEY`
`opencode`	`opencode_local`	`OPENROUTER_API_KEY`

--model sets the agent's initial model and is optional for claude and codex. For opencode it is required and must be an openrouter/<model> identifier (for example openrouter/anthropic/claude-sonnet-4), with no empty path segments.

# Try it with Codex instead of Claude
paperclipai test-drive --harness codex

# OpenCode requires an openrouter/<model> id
paperclipai test-drive --harness opencode --model openrouter/anthropic/claude-sonnet-4

Supplying the credential

The agent needs a provider key. You have three ways to give test-drive one, in priority order:

--api-key <value> — pass the key directly. Convenient, but the value can briefly appear in your shell history and process arguments, so test-drive warns you and redacts it from its own argv.
--api-key-env <variable> — name an environment variable the key already lives in. This is preserved through the isolation step above.
Nothing — test-drive falls back to the harness's default variable (ANTHROPIC_API_KEY, OPENAI_API_KEY, or OPENROUTER_API_KEY).

--api-key and --api-key-env are mutually exclusive. If no credential can be found, the command stops before creating anything and tells you exactly which variable to set.

# Key already exported in your shell
export ANTHROPIC_API_KEY=sk-ant-...
paperclipai test-drive

# Key in a differently named variable
paperclipai test-drive --api-key-env MY_TEAM_ANTHROPIC_KEY

Options

Flag	Default	Use
`-d, --data-dir <path>`	a fresh temp directory	Paperclip data directory to create or reuse. Omit it to get an isolated throwaway directory.
`--company-name <name>`	`Test Company`	Name for the company that gets created.
`--agent-name <name>`	`CEO`	Name for the CEO agent that gets created.
`--harness <harness>`	`claude`	Initial agent harness: `claude`, `codex`, or `opencode`.
`--model <model-id>`	(adapter default)	Initial agent model. Required for `opencode` as `openrouter/<model>`.
`--api-key-env <variable>`	(harness default var)	Read the provider key from this environment variable. Conflicts with `--api-key`.
`--api-key <value>`	(unset)	Provider API key passed directly. Conflicts with `--api-key-env`.
`--no-browser`	browser opens	Do not open the initialized instance in a browser; just print the URL.

Tip: The bootstrap flags — --company-name, --agent-name, --harness, --model, and the credential flags — only take effect when the data directory is empty. Point --data-dir at an existing test-drive directory and it reuses what is already there.

6.2 KiB Raw Permalink Blame History