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]>
Connector catalog, setup guides, and shared access documentation,
followed by a final code-accuracy repair pass. This PR does not change
application behavior.
## Final accuracy pass
Checked against shipped Paperclip `v2026.916.0`, commit
`dffc2b3ca1b9e88fa21cb17493083e682dffd1ca`, rather than the dirty local
checkout or the earlier canary baseline.
- Corrects connector/method-specific identity choices, human audiences,
and managed GitHub versus PAT scope and verification.
- Explains that **Always allow** covers different arguments for the same
agent/action/connection, with project scope when present; uses actual
button labels and removes the test-panel control from review
instructions.
- Qualifies new-action quarantine, including safe-default read
exceptions. Removes unconditional approval guarantees.
- Separates provider channel/repository reach from Paperclip sender
authorization.
- Completes sandbox sign-in and model credential-selection instructions
from the current UI implementation.
- Repairs Notion's hub summary, removes incomplete optional
Notion/Sentry client-registration procedures, and corrects Linear's
provider-versus-Paperclip attribution.
- Removes unsupported Postman tier claims, contradictory Cloudinary/Mem0
verification assertions, API-equivalence claims, and overbroad
successful-test assurances.
- Retains Supabase's required project reference: both released method
definitions explicitly require it. An earlier review suggested
otherwise; release code is authoritative here.
- Updates the release baseline and removes draft commit chronology from
the public introduction.
## Availability and remaining runtime gates
- **Google:** Verification is pending. Per the product-owner
clarification, authorization can continue where Google offers an
Advanced option; this is not available for every account and does not
override Workspace policy or other Google prerequisites. Notices on the
hub and all Google guides now distinguish an unverified-app warning from
blocked authorization.
- **Slack is available but not yet fully functional; follow-up fixes are
planned.** For agent tools, the released OAuth endpoint/scope defaults
differ from Slack's documented MCP contract. The page now warns against
treating that route as production-ready and removes the misleading
bot-scope walkthrough. Chat-channel bot setup remains separate.
Engineering must reconcile the integration and run OAuth plus one read
before removing this warning. Source:
https://docs.slack.dev/ai/slack-mcp-server/
- No credentialed connector run was performed in this pass. Code
consistency, provider documentation, UI rendering, and successful live
execution are separate evidence levels. No claim of runtime
certification for all connectors.
## Validation
- Root build: 253 crawlable documentation pages.
- Full `docs:test`: all eight suites passed locally, including
root/subpath routes, sitemap history, fingerprints, navigation, skill
source blocks, crawlable links, doc-link resolution, and SEO metadata.
- Internal-link lint: 258 Markdown files; no broken internal links.
- Latest cleanup: full build, all eight docs:test suites, internal-link
lint and diff whitespace checks passed; 1,878 link-resolution checks.
- Fixed the Calendar MCP reference URL; browser-checked the five
inconclusive external destinations (Miro article loads; Asana, Google
Cloud, OpenAI and xAI reach sign-in/console screens). Authenticated
destinations were not tested beyond those screens.
- Replaced the Sandbox providers editorial TODO with a scope note and
removed the CLI overview's unfinished-guide announcement.
- Browser client navigation: 687 checks passed using installed Chrome.
Initial launch lacked the downloaded Playwright browser; rerun used
`DOCS_CHROMIUM_PATH` without changing the tests.
- Nine representative connector/shared pages at 1440px and 390px: HTTP
200, one article H1, no page-level horizontal overflow. Mobile
screenshot inspected; approval page opened in the Codex browser.
- Navigation audit reports three existing non-connector orphan files;
this patch does not alter those files or their navigation.
The previous revision's provider-page expansion, Google shared setup
guide, navigation additions, and accidental node_modules-symlink cleanup
remain in this PR. Internal review ledgers remain outside the
publication branch. No merge or production deployment authorized.
---------
Co-authored-by: DevRel Gemini <[email protected]>
Co-authored-by: Paperclip <[email protected]>
Co-authored-by: Claude Opus 5 (1M context) <[email protected]>
Co-authored-by: Michael Nguyen <[email protected]>
Syncs docs to parent release **v2026.831.1** (cumulative from
`v2026.824.1`, via merge-base `664052f`). Authored fresh against the
release tag; every claim verified at the tag.
## What changed
**New**
- **Kimi Code adapter** (`kimi_local`) — new reference page, wired into
the adapters overview, nav, and anchor-map source mapping.
**Reference**
- **Env vars** — `PAPERCLIP_WORKSPACE_REAPER_COOLDOWN_DAYS`, opt-in
`SENTRY_DSN`, and the operator controls `PAPERCLIP_HIDDEN_SETTINGS` /
`PAPERCLIP_SETTING_DEFAULTS`.
- **Instance Settings** — new "operator controls for hosted deployments"
section (hide surfaces / override defaults).
- **Node.js floor → 24.11.0** across installation, setup,
local-development, plugin dev, Modal, and the getting-started/terminal
guides.
- **Grok adapter** — `permissionMode` no longer defaults to `dontAsk`;
when unset no flag is passed, and `--always-approve` is the unattended
policy.
- **CLI `agent`** — Kimi skills install path (`~/.kimi-code/skills`) +
`KIMI_CODE_HOME`.
**Guides**
- **Onboarding** — rebuilt around a single-card wizard that opens on
creating your agent; the mission step is gone, the goal is set
afterward.
- **Settings unification** — Invites folded into a Members tab, one
shared settings nav, and the company brand color + per-company
attachment size limit removed (also reflected in the Companies and Cases
APIs).
- **Governance behavior** — silent-run detection and stranded-task
recovery no longer act on their own; agent thought text is excluded from
automatic comments; invalid agent credentials now return `401`.
**Changelog** — entry added for v2026.831.1.
## Gates
- `docs:build`, SEO metadata, crawlable-links, sitemap-lastmod
(194/194), lint-links, verify-nav — all pass.
- **Edit verification:** every new high-confidence claim verified at the
tag.
- **Tag-accuracy gate:** 31 files checked, **0 post-tag leaks**, 30
clean, 1 review (below).
## ⚠ Drift (Verify before acting — not auto-resolved)
Medium-confidence REST-route drift in `docs/reference/api/companies.md`
— the import-transfer routes may no longer exist at these paths (likely
a false negative from prefix/dynamic registration; confirm before
editing):
- `POST /api/companies/import/transfers`
- `PUT /api/companies/import/transfers/{transferId}/parts/{partIndex}`
- `GET /api/companies/import/transfers/{transferId}`
- `POST /api/companies/import/transfers/{transferId}/preview`
- `POST /api/companies/import/transfers/{transferId}/apply`
## ⚠ Review
- `docs/reference/adapters/kimi-local.md` — new page; the only flagged
claim is the `secret-id` JSON **example placeholder** (not a real
identifier). Authored directly from the adapter's config surface at the
tag.
## Screenshots (deferred)
288 of 342 registered screenshots are stale (org-wide rename +
settings/onboarding rewrites), tracked in `SCREENSHOTS_PENDING.md`.
Recapture is a follow-up pass — **the merged pages describe the new
onboarding/settings UI while screenshots still show the old flow until
then.**
---------
Co-authored-by: Claude Opus 4.8 <[email protected]>
Cumulative docs sync from v2026.817.0 to the v2026.824.0 stable tag.
New/updated: Tailscale HTTPS broker, workspaces HTTPS exposure, release channels + `paperclipai channels`, resumable company import (guide + companies API), secret catalog, Claude setup-token login, adapter device-login, issue file-resource availability, document comments, interaction resolver-policy/governance. Version-stamped touched pages and added the v2026.824.0 docs-changelog entry.
Verified every page against the v2026.824.0 tag; stripped post-tag master leaks (Kimi adapter, reaper-cooldown env var, mission-less onboarding rewrite) that nightly had drafted ahead of the release. Screenshots flagged (192 stale) but not recaptured this release.
Co-Authored-By: Claude Opus 4.8 <[email protected]>
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]>
## What
Adds a **Changelog** category (Reference tier) with a **Docs** page that
tracks what changed in *these docs* — pages added, rewritten, or
expanded — per release. It's framed as a changelog for the documentation
itself, not a mirror of Paperclip's product release notes (which it
links out to).
Backfilled with the full documentation history: **10 releases** from
`v2026.513.0` (this repo's genesis) through `v2026.722.0`, reconstructed
from each release commit's own docs summary. Each release is a
collapsible accordion; the newest stays open.
## New design-system component
Introduces a reusable native `<details>`/`<summary>` **accordion** (no
JS):
- `site/styles.css` — `details.accordion` styled with existing tokens
(border/radius, parchment hover, rotating chevron, theme-aware), with an
optional `.accordion-meta` right-aligned label.
- `site/app.js` — allowlists `DETAILS`/`SUMMARY` + the `open` attribute
in the client-side markdown sanitizer so collapsible content survives
SPA rendering.
Usage:
```html
<details class="accordion" open>
<summary>Title <span class="accordion-meta">meta</span></summary>
<div class="accordion-body">
Markdown content — keep the blank lines so it parses.
</div>
</details>
```
## Files
- `docs/reference/changelog.md` (new)
- `site/content.json` — Changelog category / Docs page nav entry
- `site/styles.css`, `site/app.js` — accordion component
## Verification
- `npm run sync:lint-links` — clean, no broken internal links (links
verified against current tree; renamed/retired pages point at live
targets).
- `npm run sync:verify-nav` — passes (only orphans are the intentional
CLI redirect pages).
- `npm run docs:build` — all 10 accordions render,
`/reference/changelog/` route builds.
## Note
This is a **manual** changelog for now. A follow-up could hook a
"prepend a new accordion" step into the `/sync-docs` release phase so
future releases self-populate.
🤖 Generated with [Claude Code](https://claude.com/claude-code)
---------
Co-authored-by: Claude Opus 4.8 <[email protected]>
Release docs for **paperclip v2026.722.0** (window `v2026.720.0 →
v2026.722.0`; 256 changed parent files, 60 commits, diff window clean —
0 truncated leaves).
Nothing here goes live until this PR is merged to `main`.
## Surfaces authored this run
| Surface | Docs | Parent PR |
|---|---|---|
| **Run-bound agent secret access** — `access.`-prefixed / `api`
delivery mode; `GET /api/agents/me/secrets`, `POST
/api/agents/me/secrets/:key/value` (`Cache-Control: no-store`) |
`api/secrets.md`, `api/agents.md` | #9921 |
| **Local agents run natively on Windows** (ACPX, no Bash wrapper; env
via session options; `.cmd` shim; symlink→copy on EPERM) |
`adapters/acpx-local.md` | #9980 |
| **`PAPERCLIP_*` bindings flow through**; only `PAPERCLIP_API_KEY`
rejected (override removed); `DO_NOT_TRACK` /
`PAPERCLIP_TELEMETRY_DISABLED` opt-out |
`deploy/environment-variables.md` | #9974, #9946, #9906 |
| **Safer `CODEX_HOME` sandbox sync** — explicit allowlist, not whole
home | `adapters/codex.md` | #9972 |
| **Plugin SDK** environment-sync exports + `onEnvironmentSyncIn/Out`
hooks | `reference/plugins/sdk.md` | — |
| **CLI `company export --force`** | `reference/cli/company.md` | — |
| **Connections v3 (Apps)** experimental foundation —
`remote_http`→`mcp_remote`, `connection_grants`, AppDefinition catalog |
`experimental/connections-apps.md` (new) | #9958, #9981, #9982 |
Riding along from earlier nightly drafts (part of this release): secret
folders (`administration/secret-folders.md`), searchable agent picker,
cloud-managed bootstrap gate (`api/instance-admin.md`).
## Verification
All authored claims verified against parent code at tag `v2026.722.0`
(`verify-edit`): **0 high-confidence unverified**. `docs:build`,
`sync:lint-links`, and `sync:verify-nav` all pass. Frontmatter stamped
`paperclip_version: v2026.722.0`. The 2 nav orphans (`cli/commands.md`,
`cli/control-plane-commands.md`) are the intentional redirect anchors.
### ⚠ Drift (all resolved as false positives — no action)
`sync:check-drift` flagged 4 `rest-route-missing` candidates:
- `GET /api/agents/me/secrets` and `POST
/api/agents/me/secrets/{key}/value` (in `api/agents.md` and
`api/secrets.md`).
These are the **new** routes this PR documents. The flags fire because
the drift checker searched a stale `last_seen` sha and REST-route
matching is medium-confidence (router-prefix registration hides the
literal). Both routes were verified verbatim against
`server/src/routes/secrets.ts` at tag `v2026.722.0`. No change needed.
One `verify-edit` env-var flag
(`PAPERCLIP_CLOUD_PROD_PROVIDER_RAILWAY_TOKEN`) is the release-note
**illustrative example** of a user-chosen name, framed in prose as "for
example a secret called …" — not a real product variable. No change
needed.
### ↻ Renames detected
None.
### ⚠ Reconcile
None.
## Screenshots
See `SCREENSHOTS_PENDING.md`. 13 unique captures (×2 light/dark) are
genuinely stale — mainly agent-config surfaces (`AgentConfigForm.tsx`
gained the Secret access editor) and secrets. Net-zero `+0/-0` UI
touches were filtered out. Not auto-captured — recapture via `npm run
screenshots:refresh` goes to a separate review PR. The new
`secret-folders.md` and `connections-apps.md` pages have no captures
yet.
## Post-merge (squash-only repo)
After squash-merging, run `node scripts/sync/realign-nightly.mjs
release/v2026.722.0 --push` and bump `.sync-state.json`
`base_release_tag` to `v2026.722.0`. Skipping the realign arms the
add/add-conflict trap 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]>
## Summary
- adds a new **Experimental** documentation section with an overview and
10 feature pages covering motivation, enablement, usage, and caveats
- wires the section into `site/content.json` and refreshes the
experimental flag list in administration settings
- adds six screenshot capture targets and 12 QA-verified screenshots
(light and dark) for experimental feature surfaces
- includes the screenshot-pipeline fixes needed to seed and capture
those surfaces reliably
## Screenshots
Adds light and dark captures for:
- environments
- cloud upstream
- file viewer
- external objects
- server info
- recovery preview
The 12 PNGs were verified on Paperclip task PAP-14814 on July 21, 2026
and were preserved byte-for-byte during the rebase.
## Verification
- `npm run sync:lint-links` — pass; no broken internal links
- `npm run sync:verify-nav` — pass; only the two pre-existing CLI
orphans
- `npm run sync:verify-screenshots` — pass; every documented screenshot
is tracked and indexed
- `npm run docs:build` — pass
Paperclip: PAP-14705
---------
Co-authored-by: DevRel Gemini <[email protected]>
Co-authored-by: Paperclip <[email protected]>
Co-authored-by: Claude Fable 5 <[email protected]>
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]>
## Summary
- Add a dedicated **Community Desktop App (unofficial)** guide covering
installation, Local/Remote modes, server connections, updates, and
troubleshooting.
- Clearly identify `aronprins/paperclip-desktop` as
community-maintained, unofficial, and unsupported by the Paperclip team.
- Remove the desktop app as a primary installation/start path across the
installation, update, quickstart, glossary, terminal setup,
export/import, and overview docs.
- Register the new page under **How-to Guides → Deploy & Maintain** and
retain small cross-links where desktop-specific guidance is useful.
## Verification
- `npm run docs:build` — passed on the final PR branch.
- `sync:lint-links` — previously passed across 162 files with no broken
links.
- `sync:verify-nav` — previously passed with only two pre-existing
orphan pages.
- `docs:test:static-routes` — previously passed.
- Verified the new route, sitemap entry, and cross-links in the built
`.site` output.
Closes PAP-14693.
---------
Co-authored-by: DevRel Gemini <[email protected]>
Co-authored-by: Paperclip <[email protected]>
## Summary
- New API reference page `docs/reference/api/checkbox-confirmations.md`
for the `request_checkbox_confirmation` issue-thread interaction kind
(shipped in v2026.609.0, paperclipai/paperclip#7649):
create/list/accept/reject routes, full payload schema + validation
limits, results/outcomes, continuation policy, target staleness,
idempotency.
- Registered in the API nav (`site/content.json`) after Issues.
- Card screenshot added under
`docs/user-guides/screenshots/{light,dark}/interactions/` (same capture
both themes — the delegated QA pass produced a light capture; swap-safe
path).
Campaign v2026-609-0 · piece `api-docs--checkbox-confirmations` ·
PAP-13235.
**Merging this PR = publishing the page** (delivery gate for the
campaign piece).
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-authored-by: DevRel Gemini <[email protected]>
Co-authored-by: Paperclip <[email protected]>
Back-fills documentation for the human multi-user collaboration surface
(company members, invites, roles, permissions, offboarding). These
features are already shipped and live; this fills doc gaps and fixes one
live permission-key drift. Branched off `main` (not `nightly`) because
it's editorial back-fill of released features, intended to ship
independently of the nightly sync cadence.
## Tier 1 — correctness
- **Fix live permission drift** in `administration/company.md`: the
grant list and Owner/Admin role descriptions were missing
`environments:manage` and `tasks:manage_active_checkouts` (both present
in `packages/shared/src/constants.ts` `PERMISSION_KEYS`;
`environments:manage` is an Owner/Admin default in
`server/src/services/company-member-roles.ts`).
- **New** `administration/roles-and-permissions.md`: canonical 8-key
catalog (what each gates), role→default-grant matrix, additive
precedence rule, `instance_admin` layer, and current limitations.
- `maintenance/follow-ups.md`: note to teach the drift checker the
permission catalog so this can't silently drift again. (Sync tooling
itself untouched.)
## Tier 2 — how-tos
- `how-to/add-a-human-teammate.md` — invite → join request → approve →
set role/grants (UI + CLI).
- `how-to/offboard-a-member.md` — suspend vs archive, work reassignment,
membership-status-gates-access, instance-level cleanup.
- `how-to/enable-multi-user-login.md` — `local_trusted → authenticated`,
board-claim handoff, then invite people.
## Tier 3 — concept
- `guides/org/members-and-access.md` — shared human+agent principal
model, roles vs grants, human roles ≠ agent org chart, instance admin,
the member profile page, and the "left a project ≠ lost access"
clarification.
## Verification
- All 5 new pages registered in `site/content.json` (valid JSON, +5
pages).
- `sync:lint-links` and `sync:verify-nav` clean for these changes. The
single link the linter reports pre-exists on `main` in a skills file
untouched here; the 2 nav orphans are the intentional CLI redirect
anchors.
- All content verified against `paperclipai/paperclip@master` source
(permission keys, role defaults, CLI syntax, deployment modes).
## Follow-up after merge
Back-merge `main → nightly` so the next release merge stays clean.
🤖 Generated with [Claude Code](https://claude.com/claude-code)
---------
Co-authored-by: Claude Opus 4.8 (1M context) <[email protected]>
## Summary
- Adds a Hermes-specific how-to guide for connecting Hermes Agent to
Paperclip through the external invite and gateway flow.
- Includes the attached screenshots in the docs release asset tree and
references them throughout the walkthrough.
- Adds the guide to the How-to navigation and cross-links it from Bring
Your Own Agent.
## Validation
- `npm run sync:verify-nav`
- `npm run sync:verify-screenshots`
- `npm run docs:test:static-routes`
- `npm run docs:build:auto`
- Targeted link check for `docs/how-to/connect-hermes-agent.md`
## Notes
`npm run sync:lint-links` still fails on an unrelated pre-existing link
in `docs/reference/skills/optional/research/last30days.md` that resolves
to `docs/reference/skills/optional/research/url`.
---------
Co-authored-by: Paperclip <[email protected]>
Round 2 — worked the human-review items, verified each against parent source:
- Skills: the per-agent `required` attribute is retired upstream
(AgentSkillEntry dropped required/requiredReason; AgentSkillOrigin dropped
paperclip_required; resolveDesiredSkillAssignment now persists exactly the
desired set with no bundled union). Fixed reference/skills.md and
reference/cli/skills.md: removed "non-required" qualifiers, the retired
`required` frontmatter row, the wrong "forced into every agent" claim, and
corrected the snapshot example + the UI grouping (Company skills + Unmanaged,
no "Required" group).
- paperclip-dev skill removed upstream: dropped from the bundled list and
swapped stale source/key examples to paperclip-create-agent.
- Experimental features: strengthened the settings.md caution to match the new
in-app "no compatibility guarantees" warning.
- Task watchdogs: new operator guide page (guides/projects-workflow/
task-watchdogs.md) + nav entry. API/config/behaviour verified against
routes/issues.ts, schema/issue_watchdogs.ts, and doc/TASK-WATCHDOG.md intent.
Reviewed, no change needed: instance-scoped environments (routes still match
docs), skills store (UI reframe; guide already accurate), plugin-sdk lease
params (fields not documented).
verify-edit all clean; build/links/nav/drift all green.
Co-Authored-By: Claude Opus 4.8 (1M context) <[email protected]>
Publish accumulated nightly drafts to main and document the new surfaces
shipped between v2026.529.0 and v2026.609.0 (130 parent commits).
New pages (gaps not covered by nightly drafts):
- docs/reference/cli/token.md — `token agent` / `token board` API-key commands
- docs/reference/cli/connect.md — interactive `connect` setup wizard
- docs/reference/api/teams-catalog.md — teams catalog REST API
Also:
- Stamp paperclip_version: v2026.609.0 on 49 release doc pages
- Register the 3 new pages in site/content.json nav
- Bump .sync-state.json base_release_tag to v2026.609.0
Verification: 49 pages checked against v2026.609.0; 11 verifier flags,
all confirmed false-positives (flagged flags/env-vars exist in parent).
Drift: 0. Reconciliation: 0.
Co-Authored-By: Claude Opus 4.8 (1M context) <[email protected]>
Three settled surfaces aged past the 24h quarantine since the last run:
- Teams Catalog (#7550): new `teams` CLI page + Team Catalog guide for the
installable bundled/optional starter teams.
- Company Artifacts (#7621): new Artifacts guide + `GET /api/companies/{id}/artifacts`
API section under Companies.
- Low-trust review containment / trust presets (#7530): new Administration page
covering the `standard` / `low_trust_review` presets and quarantine-then-promote
review flow.
Nav merged in site/content.json. PENDING.md and SCREENSHOTS_PENDING.md regenerated
(40 screenshots stale in the settled window). Phase 5.5 verification clean; drift clean.
Co-Authored-By: Claude Opus 4.8 (1M context) <[email protected]>
Cumulative nightly sync from v2026.525.0 → parent master b754582:
- New API page for resource memberships (join/leave projects & agents)
- Document annotations API + guide sections on issue documents
- Bundled plugin discovery (experimental first-party plugins) in admin + API docs
Co-Authored-By: Claude Opus 4.7 (1M context) <[email protected]>
Adds docs/how-to/update-paperclip.md covering the three install paths
(Desktop App, npx/CLI, git clone) and wires it into the How-to Guides
sidebar.
Co-authored-by: Claude Opus 4.7 (1M context) <[email protected]>
Covers both storage shapes (plain value on the agent vs secret reference
via Company Settings → Secrets), with per-provider notes for Anthropic,
OpenAI, Google Gemini, xAI, Cursor, and OpenCode. Includes a callout for
the Claude.ai subscription → console-key switch that's been tripping up
existing users.
Co-authored-by: Claude Opus 4.7 (1M context) <[email protected]>
- New adapter page: Grok Local (`grok_local`), wired into the Adapters
overview table and nav.
- Issues guide: document locking workflow (lock/unlock, derived-document
redirect for agents) and the new Board-view scaling controls (density,
cold-lane mode, column page size). Documents are now live-refreshed.
- Issues API reference: lock / unlock endpoints, plus the
`redirectedFromLockedDocument` response for agent writes into locked
documents.
- Sandbox Providers (Cloudflare): reliability tuning notes — larger
instance type, SSE keepalives, UTF-8-safe stdout, sandbox-aware probe
budgets, corrected Pi install path.
- LLM Wiki plugin: bundled bootstrap assets and namespace-safe spaces
migration validation.
- SCREENSHOTS_PENDING.md regenerated for v2026.517.0.
- .sync-state.json bumped to v2026.517.0.
Co-Authored-By: Claude Opus 4.7 (1M context) <[email protected]>
Three first-party plugins were missing from the docs because they
shipped before /sync-docs started tracking the repo (or were missed
in a prior batched catchup):
- NEW docs/reference/plugins/llm-wiki.md — full reference page for
the LLM Wiki plugin (introduced in v2026.512.0, PR #5716). Covers
what the plugin contributes to the dashboard, its managed agent
and skills, REST routes, and operator tips.
- docs/administration/plugins.md — adds the missing
plugin-orchestration-smoke-example bullet to the first-party
examples list (sibling to the four already listed).
- docs/reference/adapters/sandbox-providers.md — adds a Fake Sandbox
(provider: "fake-plugin") section for the private
@paperclipai/plugin-fake-sandbox package, intended for testing and
reproducing plugin-runtime issues without external infrastructure.
- site/content.json — nav entry for the new LLM Wiki page under
Reference / Plugins.
Co-Authored-By: Claude Opus 4.7 <[email protected]>
Authored docs to track the v2026.512.0 → v2026.513.0 window:
- New: docs/how-to/develop-a-plugin-locally.md — friendly walkthrough
of `paperclipai plugin init`, local-path install, dev watcher, reload.
- New: docs/guides/day-to-day/blocked-inbox.md — guide to the new
Blocked Inbox tab, chip variants, filters, sort, and triage.
- docs/guides/day-to-day/issues.md — Blocked tab cross-ref; new
"Recovery actions" and "Walking through sub-issues" sections.
- docs/reference/api/issues.md — "Recovery actions" API section
(routes, RecoveryAction shape, resolution-outcome enum).
- docs/reference/adapters/claude-local.md — "Resuming a session's
workspace" subsection (host cwd, system-root rejection, non-file
skip, driver-plugin allowlist).
- docs/reference/plugins/sdk.md — "Worker entrypoint validation"
section; version bumped to v2026.513.0.
- docs/administration/plugins.md — "Developing plugins locally"
subsection linking the new how-to.
- site/content.json — nav entries for the two new pages.
- SCREENSHOTS_PENDING.md — new UI surfaces flagged for capture.
Co-Authored-By: Claude Opus 4.7 <[email protected]>
Closes the four coverage gaps surfaced by the docs audit:
Gap 1 — env vars (verify-edit: 0 high-confidence unverified)
- docs/reference/deploy/environment-variables.md
- Added `BETTER_AUTH_SECRET` row to "Deployment And Auth" (falls back
to `PAPERCLIP_AGENT_JWT_SECRET`; server refuses to start without
either), and `SERVE_UI` row to "Server Configuration" (overrides
`server.serveUi`). Both values copied verbatim from parent at
v2026.512.0 (.env.example + server/src/auth/better-auth.ts).
Gap 2 — skill bundles (verify-edit: 0 unverified)
- docs/reference/skills.md
- Added one-liner entries for `diagnose-why-work-stopped`,
`paperclip-converting-plans-to-tasks`, `para-memory-files`,
`terminal-bench-loop`. Descriptions distilled from each parent
`SKILL.md` frontmatter at v2026.512.0.
Gap 3 — Plugin SDK page (verify-edit: 0 high-confidence unverified)
- docs/reference/plugins/sdk.md (new)
- site/content.json (new "Plugins" section under Reference tier)
- Comprehensive reference for @paperclipai/plugin-sdk. Every public
export (definePlugin, runWorker, startWorkerRpcHost, test harness,
bundler presets, dev server, host-client factory, JSON-RPC protocol
helpers, all manifest/protocol types, zod re-export, constants)
is listed verbatim from packages/plugins/sdk/src/index.ts at
v2026.512.0. 13 unverified items are SHOUT_CASE SDK constants
mis-classified as env vars by verify-edit (all confidence: null).
Gap 4 — REST routes (verify-edit: 0 high-confidence unverified)
- docs/reference/api/adapters.md (new) — 9 endpoints from
server/src/routes/adapters.ts.
- docs/reference/api/plugins.md (new) — install/lifecycle/config/jobs/
webhooks/local-folders/bridge endpoints from
server/src/routes/plugins.ts.
- docs/reference/api/instance-admin.md (new) — umbrella covering
instance-settings, instance-database-backups, llms reflection,
environments, and execution-workspaces.
- site/content.json — added the three new pages to the API section.
- All seven flagged route files turned out to be public/admin surfaces;
none qualified as internal-only.
FOLLOW-UPS.md
- Added "Internal REST routes — intentionally undocumented" section
recording the Gap 4 triage outcome.
Verification gates
- npm run sync:test — 26/26 passed
- npm run docs:build — clean (90 markdown files)
- npm run sync:lint-links — same 3 pre-existing broken screenshots
- npm run sync:verify-nav — same 1 pre-existing orphan
- check-drift: 41 -> 43 (+2; both are the new SERVE_UI / BETTER_AUTH_SECRET
rows hitting the known env-var-missing false-positive class tracked
in FOLLOW-UPS.md; the routes-missing item for instance-admin.md is a
filename-normalization false positive — routes exist in parent).
Co-Authored-By: Claude Opus 4.7 (1M context) <[email protected]>
Manifest summary:
- pr/cli-commands: NEW `paperclipai secrets list|declarations|create|link|doctor|providers|migrate-inline-env` command group [evidence: cli/src/commands/client/secrets.ts added].
- pr/adapters/cursor-cloud: NEW adapter package (genuinely new per detect-renames; agentConfigurationDoc surfaced from src/index.ts).
- pr/adapters/acpx-local: NEW adapter package (genuinely new); ACPX runtime execution still being enabled in stages.
- pr/adapters (sandbox-providers): NEW cloudflare, daytona, exe-dev sandbox provider plugins (genuinely new per detect-renames). E2B already shipped in v2026.427.0; now grouped with siblings on the new sandbox-providers page.
- auto-merge/env-vars: 20 file matches but no new env vars added beyond a code re-org of PAPERCLIP_SECRETS_STRICT_MODE.
- pr/rest-routes: 12 modifications, no new top-level routes.
- pr/agent-skills: NEW skills/diagnose-why-work-stopped and skills/terminal-bench-loop (genuinely new) — internal skills.
- pr/plugin-sdk, pr/schemas, pr/web-ui, pr/server-services, pr/server-adapters: internal.
Edits applied: 5
- docs/reference/adapters/cursor-cloud.md (NEW page mirroring cursor-local structure)
- docs/reference/adapters/acpx-local.md (NEW page mirroring claude-local structure)
- docs/reference/adapters/sandbox-providers.md (NEW page covering cloudflare, daytona, exe-dev, e2b)
- docs/reference/cli/commands.md (add `secrets` command group; bump paperclip_version)
- site/content.json (nav additions: Cursor Cloud, ACPX Local, Sandbox Providers in Adapters Reference)
Verification:
- All `paperclipai secrets` subcommand names and flags verified verbatim against cli/src/commands/client/secrets.ts.
- All cursor-cloud and acpx-local field names verified verbatim against agentConfigurationDoc strings in packages/adapters/*/src/index.ts.
- Sandbox provider env vars (DAYTONA_API_KEY, EXE_API_KEY, E2B_API_KEY) flagged as high-confidence-unverified — known false positives: these env vars are documented in plugin README.md and plugin manifest.ts files, not in server/src/config.ts. verify-edit.mjs only searches the server env source set. Logged in CATCHUP_RUN_REPORT_2.md.
Renames detected: none (detect-renames confirmed all five new dirs are genuinely new)
Reconcile flags: none
Release notes one-liner: "Secrets CLI, Cursor Cloud and ACPX adapters, Cloudflare/Daytona/exe.dev sandbox providers."
Co-Authored-By: Claude Opus 4.7 (1M context) <[email protected]>
- Add a collapsible Mermaid state-diagram alongside the ASCII diagram for renderers that support it.
- Document that release preserves assigneeUserId (verified against svc.release in the runtime: only assigneeAgentId, checkoutRunId, and status are written).
- Add a Common Mistakes table covering PATCHing into in_progress, retrying 409s, free-text blockers, cancelled blockers, executionState participant rules, reopen vs status, and the X-Paperclip-Run-Id header.
Co-Authored-By: Paperclip <[email protected]>
Adds docs/reference/skills.md covering file shape, install
pipeline, assignment, scoping, skill-vs-plugin-vs-adapter,
naming collisions, versioning, and troubleshooting. Wires it
into the Reference tier in content.json and updates the org
skills guide to link to it. Also corrects the agents API page,
which advertised skillIds/skillKeys for /agents/:id/skills/sync
but the validator only accepts desiredSkills.
Co-Authored-By: Paperclip <[email protected]>
Introduces docs/reference/cli/commands.md — a single searchable
reference covering every paperclipai subcommand, flag, environment
variable, and exit code, plus five end-to-end example flows. Linked
into the Reference → CLI nav and cross-referenced from the CLI
overview. Resolves PAP-1794.
Co-Authored-By: Paperclip <[email protected]>
Two static-review findings from PAP-2514 applied:
- Rename to "Quickstart Path" (was "5-Minute Path"). The 5-minute claim
with a 15-minute table read as misleading; the title is now honest and
the 5-minute promise stays in the body where it can be qualified.
- Move installation out of the numbered path. Install is one-time setup;
the path proper is now three steps totaling ~5–11 min, which lines up
with the body's promise sentence. Drops the misleading "Desktop App
is faster if you're not a Node developer" line — Claude Code being a
separate prereq breaks that claim.
Co-Authored-By: Paperclip <[email protected]>
Sets explicit time expectations and links to the four-page first-run
sequence (install → company → agent → watching). Reduces nav friction
for first-time readers — the skeptical engineer can scan the path,
the times, and the end-state screenshot before committing to the full
flow.
Co-Authored-By: Paperclip <[email protected]>
Section metadata (icon key, description) used to live in a separate
SECTION_META table in app.js, keyed by section title. Moved both fields
onto each section in content.json so the manifest is the single source
of truth. Dropped the inlined SECTION_ICONS SVG palette in favor of the
Lucide UMD script — sections now reference any Lucide icon by its
kebab-case id.
Co-Authored-By: Claude Opus 4.7 (1M context) <[email protected]>
Dotta