paperclipai/paperclip-docs
1
0 Fork 0
mirror of https://github.com/paperclipai/paperclip-docs.git synced 2026-11-07 06:16:07 -10:00
Code Issues Packages Projects Releases Wiki Activity
281 Commits 57 Branches 11 Tags
main
Commit Graph
36 Commits
Author SHA1 Message Date
Aron PrinsClaude Opus 4.8DevRel GeminiPaperclipDottaClaudeCoder
 		d627632874 Release docs for paperclip v2026.1106.0 (#172) 
Docs for parent release `v2026.1106.0` (`d69631b0`), up from
`v2026.1023.0` (`1b4c8038`): 515 parent commits.

## How this branch was built

The tag is 914 commits behind what `nightly` has drafted, so this branch
isn't cut from `nightly` HEAD. It starts at nightly commit `1952052`
(parent `043f2514`), 19 commits before the tag, then adds:

- the `main` hotfix (#160)
- the sync tooling from `nightly`
- docs for those 19 commits

Later nightly drafts stay on `nightly`, so no pages had to be removed.
No `nightly-draft/*` PRs are open.

## What changed

- **Runner by default:** new Claude, Codex, OpenCode and Pi agents start
on Paperclip Runner on supported hosts, with **Legacy runner** and
**Upgrade runner**.
- **Workspaces:** cleanup of finished workspaces, optional Git
expiration, and restore points for unsaved work. Restore points are off
by default.
- **New pages:** Prompt injection prevention, Google Workspace, GitHub
Copilot, Speko, Braintrust, Daytona, Ditto and Unikraft.
- **Breaking and upgrade notes:** the run history limit, Sentry run
failures off by default and the DSN variables, the Docker start command
for custom images, `--yes` on `instructions-file:delete`, and slower
migrations on large instances.
- **Also covered:** project repositories as skill sources, roster bulk
edit, Artifacts V1 (experimental, off by default), composer dismissal,
`expectedStatusVersion`, `unexecuted_review_stage`, and plugin workspace
providers.
- **Changelog:** a v2026.1106.0 entry in `reference/changelog.md`.

## Older text corrected

These were wrong at the tag, and most are also wrong on the live site:

- which permissions let an agent read a peer's configuration or change
instructions (`api/agents.md`)
- `decideNowCount`, which doesn't exist; the field is `deskBadgeCount`
- `file-resources` routes, which are board-only
- the **Create project** dialog fields, a CEO rule the code doesn't
enforce, and where a terminated agent's reports appear
- `instructions-file:put` and `:delete` examples that always failed
(`cli/agent.md`)
- a curl example that returned `422` (`api/cases.md`)
- Google Workspace **Reconnect** instructions, which claimed it reopens
the service picker
- the `permissionKey` table, which listed 8 of 21 keys
- drafting text at the end of `api/agents.md`

## ⚠ Please check these

- **Product behaviour that may be a parent bug.** The docs now describe
the tag's code, which you may prefer to fix upstream:
- The project **Environment** dropdown saves a choice, but runs ignore
it (`experimental/environments.md`).
- `environments:manage` is granted by roles but no environment route
checks it.
- `suggest-changes` is documented as agent-only, because only agents
have a consent path. Company skill policy decides skill edits.
- **Reader-visible mismatches in the parent UI.** The docs follow the
code. Upstream copy still mentions a "Built-in agents tab", says Copilot
"awaits qualification", and tells people to "Reconnect Google Workspace
to change access".

## ⚠ Post-tag leaks removed

Nothing to remove from an already-drafted page: post-tag surfaces such
as 1Password, Vercel, Supabase deploy, custom gateway onboarding and
Artifacts V1 as default never came onto this branch. Authors left out
post-tag hunks of the next nightly draft, and the reasons are in the run
notes.

## ⚠ Drift

None. Zero findings at the tag, from a full parent snapshot.

## ⚠ Verification Failures

The tag-accuracy gate reports one leak and nine review entries. None is
a real failure:

- **Leak:** `reference/cli/service.md`, `paperclipai payload and`. This
is a false positive; it's prose from a real message at
`cli/src/commands/service.ts:184`.
- **Review, 8 new connector pages:** the gate can't confirm new pages.
Reviewers confirmed each surface exists at the tag.
- **Review, `local_tools`:** an example value from the tag's Runner
README.

Not provable from code, and kept deliberately:

- `sandbox-providers.md` uses `sandbox.yaml`. The tag's README says
`install.yaml`, which returned 404 when checked. The upstream fix is
post-tag.
- The Google Workspace row about older OAuth brokers rests on release
notes and a design doc. The broker isn't in this repo.
- External claims about provider behaviour (for example Braintrust,
Daytona, Unikraft and Google scopes).

## ↻ Renames detected

None. The rename helper wasn't run: the 19-commit delta adds no new
adapter, skill, or plugin directories that it would check.

## Verification

All checks read a checkout pinned to the tag.

- **First round:** authors, a release-notes audit, an audit of
corrections stranded on `nightly`, an audit of 321 lines the last
realign dropped from `main` (about 130 checked directly in code), and
six fresh verifiers.
- **Second round:** seven new verifiers re-checked every changed area,
tracing behaviour rather than matching labels, and fixed about 50 more
defects. That volume means more may remain.
- **Limits of that second round:**
- Each verifier reported what it only string-matched. That includes
parts of Artifacts V1, the **Upgrade runner** notice, Copilot run
behaviour, and some Plugin SDK contract text.
  - The second-round fixes themselves weren't reviewed by a third round.
- **Gates:** `docs:build`, `docs:test` and `sync:check` pass.
- **Nothing was run against a live instance.** All of this comes from
reading code.

## Screenshots

**196 of 278 screenshots are stale and none were recaptured.** The list
is in `SCREENSHOTS_PENDING.md`. Some visibly differ from the text, such
as the removed **Run with provider trace** button and the old roster
tabs.

## After merge

1. Keep the PR title as is: `tag-docs-release.yml` reads the version
from it.
2. Confirm the `docs/v2026.1106.0` tag exists.
3. Run `node scripts/sync/realign-nightly.mjs release/v2026.1106.0
--push`, then audit for dropped lines and duplicated paragraphs, and set
`nightly` state back to `branch_mode: nightly`.
4. Check that `docs.paperclip.ing` serves the release: a new page, a new
claim, and the changelog's top entry.

🤖 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-11-07 13:02:42 +01:00
Aron PrinsClaude Opus 4.8DevRel GeminiPaperclipDottaClaudeCoder
 		0ea1994fa7 Release docs for paperclip v2026.1023.0 (#156) 
## Summary

Release docs for Paperclip **v2026.1023.0** (parent tag commit
`1b4c8038`).

- **Window:** `v2026.1012.0` → `v2026.1023.0`. The tag was cut from
parent `master` at 2026-10-12, so the cumulative window is the
merge-base `22a3ea34` → `1b4c8038`. That's 200 commits and 2,501 files,
with no compare truncation.
- **Branch:** cut from `nightly` (`1b81e21`). Nightly had drafted
against parent master up to `043f2514` (Oct 22), which is 496 commits
past the tag. Most of nightly's #151–#155 work is post-tag.
- **Review:** six reviewers checked all 161 changed pages hunk by hunk
against a local checkout of the tag, using post-tag history
(`1b4c8038..043f2514`) to date each claim. The tag-accuracy gate was
then re-run on the result.

**Headline doc changes:**
- **New pages (21):**
  - [Custom model providers](docs/connectors/custom-model-providers.md)
  - [Decision Models API](docs/reference/api/decision-models.md)
  - [Cases](docs/experimental/cases.md)
  - [External agents: OpenAI Dot](docs/experimental/external-agents.md)
  - [Agent cryptographic identity](docs/guides/org/agent-identity.md)
- [Agent complaints and
suggestions](docs/administration/agent-commentary.md)
  - [Runtime Commands](docs/reference/cli/runtime.md)
- 14 connector guides: Bitly, Calendly, Context7, Enterpret, Exa,
Firecrawl, Gauge, GSC Wizard, Make, Parallel Search, Superagent, Tavily,
Telem.AI and Windsor.ai
- **Updated pages:**
  - Private tasks and projects, with sharing and inherited privacy.
- Costs: estimated, unpriced and subscription spend, the Overview
breakdowns, provider cost reports, and the Decisions view.
  - Operators get default company editing permissions (#15377).
  - Agent setup checks and your primary agent.
  - Slack: automatic setup and **Require at-mention**.
  - The simplified dedicated GitHub App setup.
  - Cursor and Pi on Paperclip Runner, and the **Harness** label.
  - Expanded assistant MCP tools and the `paperclip:configure` scope.
  - CSV and HTML artifact previews.
  - The plugin agent lifecycle contract.
- Server-host AI sign-in, and new Linear, Airtable and Hugging Face
methods.
- A changelog entry, and 102 pages stamped `paperclip_version:
v2026.1023.0`.

### ⚠ Post-tag leaks removed

These document parent `master` features that are **not in
v2026.1023.0**. They stay on `nightly` for a later release.

- **Pages removed (7):**
  - `connectors/github-copilot.md` (92b23813)
  - `connectors/google-workspace.md` (23b2ceb0)
  - `connectors/braintrust.md` (92cfd701)
  - `connectors/daytona.md` (0b62c736)
  - `connectors/ditto.md` (a1e2173c)
  - `connectors/speko.md` (22d05644)
  - `connectors/prompt-injection-prevention.md` (2c96f767)

Their nav entries and catalog rows are already removed, and no page
links to them.
- **Reverted to `main`:**
  - 54 pages whose nightly changes were all post-tag. That includes:
- The Google per-app "no longer listed" notes and Gmail archive
(23b2ceb0, e4ce9890).
- The skills guide and the company-skill-policy API (repository packages
and auto-updates: a9830414, 473c80d1, df4ee06e).
    - The Cases API (handoffs and workflows: 505e1a55, 0a5f1546).
- The companies API (observability and prompt injection: ac9459ba,
2c96f767).
- `deploy/docker.md`, the claude-code and hermes adapters, and
`cli/agent.md` / `cli/service.md` (`--runner`, managed-shim guard).
  - The rest only changed Sources-link SHAs or had nightly-only wording.
- **Sections trimmed:**
- The Runner-default rollout, its upgrade notice and `runner` fields
(adb69e8f, 8193abb9, 39e44a9d, 734c2653).
  - Grok Bot and Muse (b8ffeb97, e6dcc6b0).
  - Task workspaces and plugin project storage (f329b24e, 8b4ab65b).
  - Task Retry and recovery status lines (d33b40a5).
- The commentary read API, `commentary:view`, and Pipelines removal
(e6dcd1e8, e5927e1d, 90777488).
  - Scoped and async budget enforcement (30b753f6).
- Plugin WebSocket routes, agent detail tabs, resource-lifecycle
delivery and Runner tasks (42715d45, db65a086, 33cc567f).
- Slack managed Cloud setup and DM at-mention changes (f0e12c85,
df06df23).
- Review-bot queued-comment, reconnect and naming changes (3b8324a2,
52459590, 7eea9d82).
  - OpenRouter attribution headers (9179d8dc).
  - Agent, project and routine search (7b9334cd).
  - Artifacts upload (762d680d).
- Env-var rows: `NATIVE_HARNESS_BACKUP_*`, `WORKSPACE_COMPACTION_*`,
`GIT_CACHE_*`/`GIT_BASE_*`, `SKILL_VERSION_RETENTION_*`, `NATIVE_MCP_*`
and `SENTRY_RUN_FAILURES`.
  - `/api/liveness` (a0651c96).
- Source links pinned to post-tag commits now point at the tag commit.

### ⚠ Drift

Checked against the tag (`check-drift --against 1b4c8038`). There are 33
candidates, the same set as the last nightly runs:
- **High:** `PAPERCLIP_WORKSPACE_GIT_SCAN_*`,
`PAPERCLIP_WORKSPACE_GIT_SNAPSHOT_TIMEOUT_MS`, `PAPERCLIP_RUNNER_API_*`,
`PAPERCLIP_MCP_AUTHORIZATION_ORIGIN` and `PAPERCLIP_CLOUD_CONNECTOR_*`
are known false positives. They're read through helpers or `env.`
receivers the checker doesn't scan.
- **High:** `PAPERCLIP_ID_CONNECTOR_*` is documented as retired, which
is intentional.
- Verify: `agent-avatars` (`:file` param), `companies/import/transfers*`
(constant route path), `chats/{agentRef}` (`router[method]` loop), and
`mcp/requests/{id}` plus the Dot pairing routes (array registration in
`public-mcp.ts`). These are known false positives.

### ⚠ Verification Failures / review notes

- **Tag-accuracy gate false positives:**
- `cli/runtime.md`: `--sha256` is a `.requiredOption` in
`cli/src/commands/runtime.ts`. `SSL_CERT_FILE`, `SSL_CERT_DIR` and
`NODE_EXTRA_CA_CERTS` are passed through by key list in
`buildPiSetupEnvironment`.
- `plugins/sdk.md`: `ENVIRONMENT_ACQUISITION_PROVIDER_STATES` is an SDK
export.
- `skills.md`: `PAPERCLIP_HELPER_STATE_DIR` is read in the skill's
upload script.
- `adapters/cursor-local.md`: the `acpx*` fields are validated in
`paperclip-runner-permissions.ts`.
- **New pages the gate can't auto-confirm:** each was confirmed by hand
at the tag, against the app definitions, routes and UI.
- **Claims kept on weaker evidence (commit message or UI string, not
code) — please eyeball:**
  - "a new bot starts in mentions-only mode" (github-setup).
  - "Mentions work in issue and PR descriptions" (review-bot setup).
  - Airtable's "HTTPS or localhost" sign-in note.
  - The "37 tools" figure on assistant-connections.
  - Reservation semantics on the costs guide.

### Screenshots

142 of 278 screenshots depend on UI files changed in this window (see
`SCREENSHOTS_PENDING.md`). They were last captured against v2026.1012.0
(#150), and a recapture is still pending.

### Checks

`docs:build` and `sync:check` pass: no broken links, and the only
orphans are the four pre-existing ones (`you-com`, `hosted-beta` and the
two intentional CLI redirect pages). All eight `docs:test` suites pass.

### After merge

1. Confirm the `docs/v2026.1023.0` tag was created.
2. Run `node scripts/sync/realign-nightly.mjs release/v2026.1023.0
--push`.
3. Re-apply this branch's decisions on `nightly`.
4. Flip `nightly`'s state back to `branch_mode: nightly`.
5. Verify docs.paperclip.ing serves the changelog entry and new pages.

🤖 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-10-24 13:01:34 +02:00
Aron PrinsandClaude Opus 5.5 d811a89622 Screenshots: recapture all for v2026.1012.0 and align guides with the release UI (#150) 
## Summary

Every docs screenshot is retaken from Paperclip **v2026.1012.0**, in
light and dark. Verifying them showed that about 50 guides described UI
the release had moved or renamed, so those guides are updated too.

**Screenshots**
- 138 automated captures (276 PNGs), all stamped `v2026.1012.0`
(`bba6a45`). The final run had no failed steps or skipped captures, and
the luminance and theme check passes on all 278 files.
- Four independent reviewers checked every light shot against its
caption, then a fix round cleared the findings.
- 37 captures (74 PNGs) are retired: none is embedded on any page, or
the screen no longer exists in the release.
- The capture pipeline (`scripts/screenshots/*`) is fixed for the
release UI:
- turns off the remote "Introducing Connectors" announcement that
covered most shots;
  - masks local temp paths as `~/acme/…`;
- keeps the demo company quiet during capture (no recovery loops, no
capture-created activity rows);
- seeds the states the guides describe: status cards, 50/80/100%
budgets, a blocked inbox, schedule triggers, a checkbox confirmation,
skills-capable agents and more;
- uses updated routes and steps for the moved UI, and gains
`scrollToTop`, `readyText`, per-target `experimental` flags, and comma
lists for `--only`.
- **The budget shots show a fixed incident card.** In v2026.1012.0 a
warning-threshold incident is labelled "hard stop · This scope is
paused", which is wrong. The fix is
[paperclipai/paperclip#16201](https://github.com/paperclipai/paperclip/pull/16201).
The costs and budget shots were captured from v2026.1012.0 with that
patch applied, and the budget guides say so and explain what
v2026.1012.0 itself shows.

**Docs aligned with the release UI**
- **Audit:** costs, budgets, runs and the timeline moved under Audit.
That covers Costs and Budgets, Activity Log, Work Timeline, Set a
monthly budget, and Dashboard.
- **Agents:** the agent page's side menu (**Overview**, **Harness /
Runtime**), the two-step **New agent** dialog, **Run now**, and the org
chart as a view toggle. That covers Agents, Your first agent, Watching
agents work, Key concepts, Org structure, Agent adapters and Adapters.
- **Projects, routines, tasks, approvals:** current tabs, buttons and
flows.
- **Skills, plugins, company, settings:** current labels, including
instant-join invites, the Experimental settings list, and **Settings →
Experimental** paths on 21 pages.
- **Removed features:** Auto-Create Recovery Tasks and Cloud Sync are
marked as removed in this release.
- Every rewrite was checked against the v2026.1012.0 UI source, then by
two independent verifiers. A changelog entry is added under
v2026.1012.0.

## Checks
- [x] `npm run docs:build`
- [x] `npm run docs:test` (all suites)
- [x] `sync:lint-links` and `sync:verify-nav`: only the 4 intentional
orphans remain
- [x] SEO metadata and crawlable links

## Known, accepted
- The activity feeds lead with agent setup events rather than task
events.
- The dashboard agent strip shows two cards for Ada.
- Agent budgets can only be created from the CLI or API in this release,
and the guides say so.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

---------

Co-authored-by: Claude Opus 5.5 <[email protected]>
 2026-10-13 18:44:53 +02:00
Aron PrinsClaude Opus 4.8DevRel GeminiPaperclipDottaClaudeCoder
 		2535f6c99c Release docs for paperclip v2026.1012.0 (#149) 
## Summary

Release docs for Paperclip **v2026.1012.0** (parent tag commit
`bba6a45f`).

- **Window:** `v2026.1005.0` → `v2026.1012.0`. That is 132 commits and
1,242 files, with no compare truncation.
- **Branch:** cut from `nightly` (`fe556e1`). Nightly had drafted
against parent master up to `abbd8800`. The release was cut from master
at `22a3ea3` (Oct 6), so nightly's last 39 commits are post-tag.
- **Review:** every changed page was checked by hand against a checkout
of the tag. The tag-accuracy gate was then re-run on the result.

**Headline doc changes:**
- **New pages:**
- [Assistant connections
(MCP)](docs/experimental/assistant-connections.md), with the [Assistant
MCP API](docs/reference/api/assistant-mcp.md) and [`paperclipai
mcp`](docs/reference/cli/mcp.md) references
- [Saved connection
instructions](docs/connectors/connection-instructions.md)
  - [Check AI account usage](docs/connectors/ai-usage.md)
- [Task-pinned AI routing](docs/experimental/task-pinned-ai-routing.md)
  - [Neon](docs/connectors/neon.md)
- **Breaking changes documented:**
- Restore locks moved to SQLite (#14869). [Update
Paperclip](docs/how-to/update-paperclip.md) now has a "stop everything
first" upgrade and rollback flow.
- Stored tool grants are enforced as written (#14915). This is covered
in the [Tool Gateway API](docs/reference/api/tool-gateway.md) and the
[Access model](docs/connectors/access-model.md).
- **Other release coverage:**
- The connection-instructions contract for HTTP and process adapters
(`connectionInstructions`, `PAPERCLIP_CONNECTION_INSTRUCTIONS_FILE`).
- Much shorter default instructions, and default config grants for new
agents.
  - The `update_skill` tool.
  - Aggregator accounts gathered into one catalog.
  - Chat-first navigation and the combined inbox.
  - The rebuilt New task dialog.
  - "Model at capacity" and "Model unavailable".
  - Sonnet 5.5, GPT-6.1 Sol and new harness pins.
- The supported remote Codex range, and Codex resuming after a server
restart.
  - Watchdog thresholds of 5 and 15 minutes.
  - `tool_discovery_busy`.
  - The Docker provider pack.
- A changelog entry, and 75 pages stamped `paperclip_version:
v2026.1012.0`.

### ⚠ Post-tag leaks removed

These document parent `master` features that are **not in
v2026.1012.0**. They stay on `nightly` for the next release.

- **Pages removed (7):**
  - `administration/agent-commentary.md` (b508a05c)
  - `guides/org/agent-identity.md` (a590ab76)
  - `reference/cli/runtime.md` (a6306ba6)
  - `connectors/custom-model-providers.md` (9f7057e1)
  - `connectors/enterpret.md` (88ff98b8)
  - `connectors/superagent.md` (8cbd21b3)
  - `connectors/telem.md` (f77fcbf4)

Their nav entries and catalog rows are already removed, and no page
links to them.
- **Reverted to `main`:**
- `roles-and-permissions.md`, `administration/company.md` and
`add-a-human-teammate.md`. Operator's 14 default keys come from
582911ba.
- The costs guide and `api/costs.md`. Durable accounting, by-user costs
and per-account quota come from 799e4d55, eab93fd4 and 892b0b36.
  - `adapters/cursor-local.md` (a6306ba6)
- `deploy/database.md` and `deploy/environment-variables.md`, which
carried agent identity and complaints.
  - `browser-use-cloud.md`
  - `back-up-and-restore-a-company.md`
- **Sections trimmed:**
- The assistant MCP pages now match the tag:
`paperclip:read`/`paperclip:write`/`offline_access` only, 10 direct
tools, and no file transfer (2d0c1381, 99a9de99).
- Server-host sign-in for Anthropic, OpenAI and xAI is back to the
terminal-command flow (e38d6d16, 2ca0d26a).
  - OpenRouter is OpenCode-only again (9f7057e1).
  - Requested vs granted OAuth scopes are removed (ea8e6861).
  - PR review waits are removed (228f0e28).
- Historical-question reminders and "No project" in the composer are
removed (faa8e452, ee3c728b).
  - Plugin lifecycle hooks are removed (1cebdd4c).
  - Cursor on the Runner is removed (a6306ba6).
  - The aggregator "Waiting for sign-in" status is removed.
  - Source links pinned to post-tag commits now point at the tag commit.

### ⚠ Drift

Checked against the tag:
- **High:** the `operator` default grants were **real** drift. Fixed by
reverting the post-tag tables.
- **High:** the agent-identity paths and env vars were real at nightly
but are post-tag. They're removed (see above).
- **High:** `PAPERCLIP_WORKSPACE_GIT_SCAN_*`,
`PAPERCLIP_WORKSPACE_GIT_SNAPSHOT_TIMEOUT_MS`, `PAPERCLIP_RUNNER_API_*`
and `PAPERCLIP_CLOUD_CONNECTOR_*` are known false positives. They are
read through helpers the checker doesn't scan.
- **High:** `PAPERCLIP_ID_CONNECTOR_*` is documented as retired, which
is intentional.
- Verify: the `/accounting/*`, `costs/by-user` and
`agents/{id}/identity` routes are no longer documented, because they're
post-tag.
- Verify: `agent-avatars`, `companies/import/transfers*` and
`chats/{agentRef}` are known param/constant-registration false
positives.

### ⚠ Verification Failures / review notes

- **`reference/cli/mcp.md`:** the gate flags `--device` and `--url`.
This is a false positive: both are `requiredOption`s in
`cli/src/commands/mcp.ts` at the tag.
- **New pages the gate can't auto-confirm:** each was verified by hand
at the tag. They are assistant-connections, task-pinned-ai-routing,
ai-usage and connection-instructions.
- **`neon.md`:** says "open **Connectors**", following the Supabase
guide. The parent's notes call the screen "Apps → Browse".
- **`connection-intents.md`:** the AgentMail card details ("shares the
key with every person in the company", "resumes after reload") are only
partly confirmed.
- **`task-chat.md`:** the queued-message details came from an earlier
nightly and couldn't be traced to a specific commit.
- **Upstream inconsistency:** the Codex adapter's in-code doc string
(`codex-local/src/index.ts:181`) contradicts the code about the bypass
flag. Our docs follow the code.

### Screenshots

**126 of 350 screenshots are stale** across 26 routes (see
`SCREENSHOTS_PENDING.md`). None were recaptured in this PR.

### Other open PRs

- **#143** (Browser Use Cloud + Neon, targets `main`): both are now
covered here. Suggest closing it.
- **#140** (Enterpret, targets `main`): Enterpret is post-tag
(88ff98b8). Suggest retargeting it to `nightly` or closing it.

## Checks

- [x] `npm run docs:build`
- [x] `npm run docs:test` (all suites)
- [x] `sync:lint-links` and `sync:verify-nav`. The only orphans are the
7 pages above plus 4 intentional ones.
- [x] `check-tag-accuracy` re-run. The only remaining flags are the ones
explained above.
- [x] Removed the 7 post-tag pages listed above (`cbece5b`), plus fixes
from a second, independent verification pass
- [ ] After the squash-merge, run `node scripts/sync/realign-nightly.mjs
release/v2026.1012.0 --push`, then flip `nightly`'s `.sync-state.json`
back to `branch_mode: nightly`.
- [ ] Confirm the `docs/v2026.1012.0` tag and that docs.paperclip.ing
serves the new changelog entry.

🤖 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-10-13 13:45:13 +02:00
Aron PrinsClaude Opus 4.8DevRel GeminiPaperclipDottaClaudeCoder
 		3679b7e739 Release docs for paperclip v2026.1005.0 (#147) 
## Summary

Release docs for Paperclip **v2026.1005.0** (parent tag commit
`467125fa`).
- **Window:** `v2026.1001.0` → `v2026.1005.0`, 179 commits, 1,645 files,
compare truncation 0.
- **Branch:** cut from `nightly` (`c42305a`). Nightly had drafted
against parent master up to `a6306ba6`, which is 159 commits past the
tag.
- **Review:** every changed page was checked by hand against a checkout
of the tag.

**Headline doc changes:**
- **New pages:**
  - [Browser Use Cloud](docs/connectors/browser-use-cloud.md)
- [Memory connectors](docs/connectors/memory-connectors.md), plus
Cognee, Honcho, Supermemory and Zep
  - [Agent Chat](docs/experimental/agent-chat.md)
  - [Paperclip Runner](docs/reference/adapters/paperclip-runner.md)
- **Breaking changes applied:**
- @-mentions no longer start a run (#14577). Ten pages that still said
they did are fixed.
- Keyboard shortcuts are always on, and `/api/auth/preferences` is gone.
  - Connector setup is one screen (#14811).
- Agent files that persist across tasks, a GitHub skill **Sources** tab,
aggregators on by default, two-way Slack, Grok Build on the Runner,
refreshed model catalogs, and the new env vars, including
`PAPERCLIP_RUNNER_API_TOOLS_ENABLED` / `_COMPANY_IDS`.
- A changelog entry, and 113 pages stamped `paperclip_version:
v2026.1005.0`.

### ⚠ Post-tag leaks removed

These document parent `master` features that are **not in
v2026.1005.0**. They stay on `nightly` for the next release.

- **Pages removed entirely (9):**
  - `connectors/ai-usage.md` (7d59de61)
  - `connectors/custom-model-providers.md` (9f7057e1)
  - `connectors/connection-instructions.md` (4857799a)
  - `administration/agent-commentary.md` (b508a05c)
- `experimental/assistant-connections.md`,
`reference/api/assistant-mcp.md` and `reference/cli/mcp.md` (e34abee6,
22a3ea34, 2d0c1381)
  - `guides/org/agent-identity.md` (a590ab76)
  - `reference/cli/runtime.md` (a6306ba6)
- **Reverted to `main`:**
  - `agentmail.md` (6c1a75da)
  - `openrouter.md`; only the released access-line change was re-applied
- `asana.md` (4ac37410); only the released access-line change was
re-applied
  - `delegation.md` and `team-catalog.md` (862a5758, b17019e1)
  - `adapters/overview.md` (a6306ba6)
  - `api/tool-gateway.md`, the GET → 405 change
- **Sections trimmed (~50 pages):**
  - AgentMail as a default connection
  - **Check usage**
  - aggregator account sync and grouping (b43073d1)
  - MCP `offline_access` (839cac13) and readable test results (6d654f63)
  - saved connection guidance
- the **Update skill** tool (eb049aeb) and managed-checkout import roots
(427e0484)
  - low-trust scoped work and owner-chat edits (0829d94a, 4039d4f0)
  - reduced default instructions (b17019e1)
  - Chat leading the nav and the combined inbox (1c07b590)
  - steer/interrupt recovery (cc67d4e1)
  - branch artifacts without a remote (db72ad4c)
  - Cursor on the Runner (a6306ba6)
  - Claude/Codex model ordering (92ad158c, d9b64ee2)
  - Daytona stalled-log polling (4e524632)
  - the agent identity env vars
  - the shared task composer for new tasks (2c43b391)

### ⚠ Drift

Checked against the tag. **No real drift remains:**
- **Env vars that exist at the tag but are read through helpers the
checker doesn't scan (false positives):**
  - `PAPERCLIP_WORKSPACE_GIT_SCAN_*`
  - `PAPERCLIP_WORKSPACE_GIT_SNAPSHOT_TIMEOUT_MS`
  - `PAPERCLIP_RUNNER_API_COMPANY_CAPTURE_MAX_BYTES`
  - `PAPERCLIP_CLOUD_CONNECTOR_*`
- `PAPERCLIP_ID_CONNECTOR_*` are documented as **retired**, which is
correct.
- Verify: `/api/companies/{companyId}/chats/{agentRef}` is registered
dynamically (`router[method]`, `issues.ts:17185`). False positive.
- Verify: `/api/agent-avatars/...png` and
`/api/companies/import/transfers*` are known false positives from
constant or param registration.

### ⚠ Verification Failures / review notes

- **Asana:** `asana.md` keeps "register your own Asana OAuth app". The
tag's `asana.json` advertises "Sign in with Asana" (DCR), but Asana's v2
MCP server needs a registered app, and sign-in only works after post-tag
#14756. Confirm you're happy with that wording.
- **Google Docs/Sheets/Slides/Calendar:** the "Reconnect after the scope
change" paragraph isn't confirmed in code.
- **`grok-local.md`:** "Intel Mac rejected" and "subscription sign-in,
no automatic fallback" are only partly confirmed.
- **`paperclip-runner.md`:** "Grok cannot automatically approve
Paperclip tool calls under narrower ACP modes" isn't confirmed directly.
- **`cognee.md`:** the tag's setup text says `uv` is required, which
contradicts `tool-access.ts:3560`. The page follows the code.
- **`work-modes.md`:** the per-reply mode chip was removed because it
couldn't be found at the tag.
- **`browser-use-cloud.md`:** the `frame-src` CSP advice is general
advice, not code-backed.

### Screenshots

**180 of 350 screenshots are stale**, across 41 routes (see
`SCREENSHOTS_PENDING.md`). None were recaptured in this PR; refresh
separately with `npm run screenshots:refresh`.

### Other open PRs

- **#143** (Browser Use Cloud + Neon, targets `main`): Browser Use Cloud
is covered here, and Neon is post-tag (5b8b2b38). Suggest closing it or
retargeting it to `nightly`.

## Checks

- `docs:build` passes.
- `sync:check` passes, with no broken internal links.
- `docs:test` passes in full: SEO metadata, crawlable links (275
routes), doc link resolution (2,198 checks), static routes, asset
fingerprints, skills nav, and skill source blocks.

## After merge (Phase 9)

- [ ] `docs/v2026.1005.0` tag is created by the workflow (keep the PR
title as is).
- [ ] `node scripts/sync/realign-nightly.mjs release/v2026.1005.0
--push`. The nine removed pages stay on `nightly`.
- [ ] Flip `nightly`'s `.sync-state.json` back to `branch_mode:
nightly`.
- [ ] docs.paperclip.ing serves the release: the changelog's top entry
reads v2026.1005.0, and `/connectors/browser-use-cloud/` returns 200.

🤖 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-10-07 09:19:28 +02:00
Aron PrinsClaude Opus 4.8DevRel GeminiPaperclipDottaClaudeCoder
 		186095cd39 Release docs for paperclip v2026.1001.0 (#142) 
Release docs for paperclip **v2026.1001.0** (tag `8f8a0ab7`, 77 commits
from the `v2026.916.1` merge-base `dffc2b3`).

## What's in the release

Agent characters across the app, a rebuilt Slack setup, safe routine
webhooks, experimental MCP aggregators (default-off
`enableMcpAggregators`), Railway and You.com connectors, the CreateOS
sandbox provider, queued answers during active runs, and runner-created
company skills. Two breaking changes are documented: coding agents now
run in full auto by default, and the legacy Composio broker is retired.

## How this branch was built

This branch was cut from `nightly`, with `main` merged in. Nightly had
drafted parent `master` up to `0f14d261`, which is **93 commits past the
tag**. So every page changed against `main` was checked line by line
against the tag source, and post-tag content was reverted to what ships.

**Merge with `main`:** `main` published Fireflies, Railway, and You.com
guides in #138/#141 while nightly drafted its own versions. This branch
keeps `main`'s live versions. Nightly's Fireflies and Railway drafts
describe post-tag behaviour anyway.

## Changes

- 37 doc pages vs `main`, all stamped `paperclip_version: v2026.1001.0`.
One new page: `connectors/mcp-aggregators.md`.
- `docs/reference/changelog.md`: v2026.1001.0 entry. It also rounds up
the six connector guides published since v2026.916.1.
- Zapier, Arcade, Composio, and Executor pages and catalog rows now say
they need the experimental **MCP aggregators** setting. At the tag, all
four are filtered out of **Connectors** until it is on
(`packages/shared/src/remote-mcp-connectors.ts`). This is new for
Zapier, which used to be visible to everyone.
- The connector-model version notes in `connectors.md`,
`recognized-providers.md`, and `slack.md` are moved to v2026.1001.0.
- `SCREENSHOTS_PENDING.md`: regenerated for the release window. 194 of
350 screenshots are flagged across 40 routes (file-change flags only).
- `.sync-state.json`: base moved to `v2026.1001.0`.

### ⚠ Post-tag leaks removed

Present on `master`, absent at `v2026.1001.0`. These stay on `nightly`
for a later release.

- **Memory connectors** (Zep, Supermemory, Cognee, Honcho) and the
toggle, from `18dac1e1`: `connectors.md`, `connections-apps.md`,
`mem0.md`.
- **MCP aggregators on by default** and agent provider choice, from
`8781f06a`, `aa8fc863`, `b41ccf09`, `4721f558`: `mcp-aggregators.md`,
`connectors.md`. The `--retry-provider-choice`, `--target-service`, and
`--selection-interaction-id` flags are removed from
`cli/connections.md`.
- **Slack** governed tools, personal search, Idle state, scheduled
messages and `im:write`, message mirroring, channels enabled by default,
and the MCP-access troubleshooting row, from `a10702a8`, `b0155a68`,
`8725d6ce`, `a7d3b17a`: `slack.md`,
`wire-slack-discord-notifications.md`.
- **Fireflies routine signing**: the `app_webhook` and `fireflies_hmac`
modes, payload data blocks, and the Fireflies example, from `24429024`:
`routines.md` (guide and API) and `create-a-daily-routine.md`.
- **Tasks**: the artifact media gallery (`1ccae464`), Ancestors in the
Tasks panel (`2788f20f`), retry-budget escalation to `blocked`
(`6bc830b6`), and alphabetized experimental settings (`794b09f8`).
- **Settings**: per-user keyboard shortcuts and `/api/auth/preferences`
(`01d9a121`), the `PAPERCLIP_HIDDEN_SETTINGS` `instance.experimental.*`
wildcard (`e2f1a66a`), Cloud **Invite people** on Members (`c341588b`),
and the Cloud lifecycle routes (`8c6cc7dc`).
- **Plugin SDK**: the `organizationSwitcher` slot (`7badae69`) and the
environment-creation cleanup helpers (`1dbffb4c`).
- **Agents and adapters**: the model and reasoning-effort refresh
(`cdf04a33`), covering Opus 5.5, `gpt-6-sol`/`luna`, Gemini 3.8 Flash,
Grok 4.x, Kimi K3 256k, and the Cursor/OpenCode model lists. Also Grok
in the Cloud picker (`83abfa46`) and `inheritRuntimeFrom: "caller"`
(`7944ed3d`).
- **Retired `PAPERCLIP_WAKE_PAYLOAD_JSON`** (`4b8ec588`): restored in
`environment-variables.md` and `reference/skills.md`.

### ⚠ Verification Failures

For a reviewer to confirm:

- **Codex full auto on the ACP engine.** Per the verifier, at the tag
Codex's approval-and-sandbox bypass applies on the CLI lane, while the
default ACP engine keeps Codex in its workspace sandbox with network on.
`codex.md` now says so. `agent-adapters.md` → "Agents run in full auto
by default" still lists Codex without that qualifier.
- `GET /api/agent-avatars/{version}/{palette}/{pose}.png`
(`api/agents.md`) is medium-confidence drift. It is confirmed at the tag
in `server/src/routes/agent-avatars.ts`.

The mechanical tag-accuracy gate reported **0 high-confidence leaks**,
even on the unfixed nightly content. Every leak above is behavioural or
prose, and was caught by a per-page adversarial pass against the tag
source.

### ⚠ Drift

All pre-existing and known false positives:

- env-var-missing (high):
`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}`,
which sit in grouped or commented `.env.example` blocks.
- Verify: rest-route-missing (medium): the five
`/api/companies/import/transfers*` routes, registered through
`COMPANY_IMPORT_TRANSFERS_ROUTE_PATH`.

### Open nightly-draft PRs

Local branches `nightly-draft/2a99de8-sandbox-and-routine-triggers` and
`nightly-draft/3e63a7e-acp-engine` are not part of this release.

### ☐ Before merge

- Delete the duplicate `docs/connectors/you-com.md` (nightly's draft;
`main`'s `youcom.md` is the registered page). It is an orphan with a
duplicate `seo_title`; the automated run could not delete files.
- Optionally run `npm run screenshots:refresh` on this branch.

## Checks

`docs:build`, `docs:test` (all six gates), `sync:lint-links`,
`sync:verify-nav`, and `sync:verify-screenshots` all pass locally. The
only new orphan is the duplicate `docs/connectors/you-com.md`.

🤖 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-10-03 09:04:25 +02:00
Aron PrinsClaude Opus 4.8DevRel GeminiPaperclipDottaClaudeCoder
 		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
Aron PrinsandClaude Opus 4.8 27d7a5ab4c Release docs for paperclip v2026.831.1 (#120) 
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]>
 2026-09-02 13:06:00 +02:00
Aron PrinsandClaude Opus 5 325c9eb819 seo: hand-write titles and descriptions for all 192 pages (#115) 
## Why

The build derived `<title>` from the **sidebar label** and the
description from the **first paragraph clipped to 220 characters**. Both
are the wrong source. A sidebar label is written for a 240px-wide nav
that supplies its own context; a search result has none.

On production that produced:

- **7 pages titled "Overview"**, and 32 pages sharing a title with
another page
- **109 of 193 descriptions cut off mid-word**, and 174 over 160
characters (where Google truncates)

```
/guides/welcome/key-concepts/
  BEFORE (220):  ...and if you misunderstand them early, the product wi
```

Near-identical titles are the weak-differentiation signal behind
"crawled — currently not indexed", which is the exact symptom on this
property.

## What changed

`seo_title` and `seo_description` frontmatter on **every one of the 192
pages**, written by hand against each page's real content and optimised
for the click — lead with what the reader can do, name the concrete
things covered, no keyword stuffing, no repeating the title.

| | Before | After |
|---|---|---|
| Duplicate titles | 32 pages | **0** |
| Duplicate descriptions | — | **0** |
| Descriptions cut mid-word | 109 | **0** |
| Descriptions over 160 chars | 174 | **0** |
| Title length (incl. suffix) | up to "Overview" | **26–60** |
| Description length | 31–240 | **122–158** |

**No prose was rewritten.** I measured content overlap between the
colliding pairs first — only 17–23%, so these were always distinct pages
wearing the same label, not duplicate content. The `docs/` diff is **564
insertions, zero deletions**.

### Examples

```
BEFORE — all seven identical:  "Overview | Paperclip Docs"
AFTER:  "Adapters Overview"      "API Overview"        "CLI Overview"
        "Deployment Overview"    "Bundled Skills"      "Optional Skills"
        "Experimental Features"

BEFORE — both identical:  "Issues | Paperclip Docs"
AFTER:  "Issues: Creating and Tracking Work"   /guides/day-to-day/issues/
        "Issues API"                           /reference/api/issues/
```

```
/guides/getting-started/five-minute-path/
BEFORE (220):  The shortest route from a running Paperclip instance to an agent that has
               just completed work for you. After Paperclip is installed, the path takes
               about 5 minutes: create a company, hire a CEO agent, approve its first s
AFTER  (131):  Install Paperclip, create a company, hire a CEO agent, and approve its
               first strategy — a working AI company in about five minutes.
```

## Plumbing

- **`site/build-release.mjs`** prefers the authored fields; the derived
path stays only as a fallback the CI gate prevents ever reaching.
`<title>`, `<meta name="description">`, and the `TechArticle` JSON-LD
all read from the same source.
- **`site/app.js`** uses the same fields, so a client-side transition
cannot leave a different title on screen than the crawler was served.
Verified in-browser: navigating `/guides/day-to-day/issues/` →
`/reference/api/issues/` swaps to exactly the server-rendered values, no
JS errors.
- **`scripts/verify-seo-metadata.mjs`** (new) enforces presence,
uniqueness, length, complete-sentence endings, and the
frontmatter-safety rules. Wired into `docs:test` and CI as its own step.

I negative-tested the gate rather than assuming it works — it correctly
fails on a duplicate title, a mid-word description, and a missing field,
and passes again once restored.

## Automating it going forward

`skills/sync-docs/SKILL.md` now:

- gains an **"Authored SEO metadata"** section: why the fields exist,
the enforced rules as a table, and how to actually write them (title
names the subject not the nav position; description writes for the
click; never generate mechanically from the first paragraph — *that is
the fallback the gate exists to prevent*).
- requires both fields in the **page-authoring instruction** given to
every subagent, with guidance on when to update an existing description
versus leave it.
- runs `docs:test:seo-metadata` and `docs:test:crawlable-links` as
**fail-loud gates in Phase 7** before commit.
- documents all six build gates in the files/gates section.

So once this lands, a new page cannot ship without hand-written
metadata, and a title collision cannot reach production.

## Verified

All six verifiers pass:

```
Static route verification passed
Asset fingerprint verification passed
Hierarchical Skills nav verification passed
Skill source block verification passed (11 skill pages, 1 control page)
Crawlable-link contract passed: 40886 internal links across 194 pages resolve in one hop
Authored-SEO contract passed: 192 pages carry a unique, hand-written seo_title and seo_description
```

🤖 Generated with [Claude Code](https://claude.com/claude-code)

---------

Co-authored-by: Claude Opus 5 (1M context) <[email protected]>
 2026-08-25 22:51:42 +02:00
Aron PrinsandClaude Opus 4.8 6c4519af4a Release docs for paperclip v2026.824.0 (#110) 
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]>
 2026-08-25 10:02:16 +02:00
Aron PrinsClaude Opus 4.8DevRel GeminiPaperclipDottaClaudeCoder
 		631a6a0c53 Release docs for paperclip v2026.817.0 (content + screenshot overhaul) (#95) 
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]>
 2026-08-18 12:43:56 +02:00
Aron PrinsClaude Opus 4.8DevRel GeminiPaperclip
 		44e12ab37c Release docs for paperclip v2026.722.0 (#72) 
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]>
 2026-07-23 10:10:05 +02:00
Aron PrinsClaude Opus 4.8DevRel GeminiPaperclip
 		8121a9c947 Release docs for paperclip v2026.720.0 (#67) 
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]>
 2026-07-20 19:59:18 +02:00
DottaDevRel GeminiPaperclip
 		773f72838a docs: Checkbox Confirmations API reference (v2026.609.0) (#54) 
## 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]>
 2026-07-09 14:21:34 -05:00
Aron Prins 7e25158fca Release docs for paperclip v2026.707.0 (#49) 
Promotes v2026.707.0 docs from nightly: Custom sandbox images + Ramp skill (new), Work Timeline (#48) and Secret scopes (#47) content, screenshot capture targets, environments nav reconcile, sync-state bump to v2026.707.0, and accuracy fixes from adversarial verification. 0 drift.
 2026-07-08 11:11:32 +02:00
Aron PrinsandClaude Opus 4.8 2368a2be5f Release docs for paperclip v2026.618.0 
Promote nightly drafts (v2026.609.0 → v2026.618.0) to main and fill coverage gaps.

New surfaces authored:
- Novita Agent Sandbox provider (driver: novita) — sandbox-providers.md
- paperclip-board bundled skill — skills.md (skills/ went 5 → 6; "four" → "five")

Promoted nightly drafts (all ⊆ v2026.618.0, no post-tag leakage):
- adapters: codex/gemini/opencode/pi/openclaw-gateway, sandbox-providers (Kubernetes)
- api/agents, plugins/sdk, environment-variables (TRUST_PROXY/OTEL)
- day-to-day guides: artifacts, issues, routines

Stamped paperclip_version: v2026.618.0 on all 13 touched pages.
Regenerated SCREENSHOTS_PENDING.md (90/276 stale — flag only, separate capture PR).

Deferred: experimental conference-room board-chat (flag-gated).
sync:check clean (no broken links); drift = 5 known server-env false positives.

Co-Authored-By: Claude Opus 4.8 (1M context) <[email protected]>
 2026-06-19 00:48:23 +02:00
Aron PrinsandClaude Opus 4.8 acfebdf637 nightly: K8s sandbox provider, adapter gateway routing, TRUST_PROXY/OTEL, agent read-config access (paperclip 412a04c) 
Cumulative window v2026.609.0 -> master HEAD 412a04c (59 commits). Applied:
- environment-variables.md: TRUST_PROXY (reverse-proxy trust), OpenTelemetry
  opt-in tracing (OTEL_*), and adapter provider-override env vars.
- api/agents.md: read-only config/skill/config-revision endpoints no longer
  require agents:create for board members (agents still gated).
- adapters/sandbox-providers.md: new Kubernetes sandbox provider section.
- adapters/{codex,pi,opencode}-local.md: PAPERCLIP_*_PROVIDERS gateway routing
  (+ codex GPT-5.5 / omit-default-model, opencode small-model).
- adapters/gemini-local.md: headless auth pre-selection + token-overflow
  fresh-session retry.
- adapters/openclaw-gateway.md: role/scopes/paperclipApiUrl/workspaceRuntime.
- plugins/sdk.md: optional companyId tenant scoping on metrics.write + log.

Deferred (experimental/half-built) to PENDING.md: Conference Room Chat,
Skills Store, dark mode, onboarding NUX, activity feed, issues list filters.
All edits verified against parent code (Phase 5.5).

Co-Authored-By: Claude Opus 4.8 (1M context) <[email protected]>
 2026-06-15 11:27:49 +02:00
Aron PrinsandClaude Opus 4.8 b243dfe70d Release docs for paperclip v2026.609.0 
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]>
 2026-06-10 12:08:31 +02:00
Aron PrinsandClaude Opus 4.8 3b58fb017c nightly: Teams Catalog, Company Artifacts, low-trust review presets (paperclip a800140) 
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]>
 2026-06-07 13:30:21 +02:00
Aron PrinsandClaude Opus 4.8 44d4c5d604 nightly: referenced catalog skills (last30days), routine pause-suppression, company archive cascade 
Cumulative window v2026.529.0 → e78c064 (24h-quarantined nightly cutoff).
Three user-visible surfaces newly documented this run:

- skills: app-shipped catalog now supports *referenced* entries fetched from
  an external GitHub repo pinned to a commit (CatalogSkill.source). First one
  is the research-category last30days skill. Documented in the Skills
  reference and the org Skills guide.
- routines: scheduled ticks are suppressed (recorded as skipped, no backfill)
  while the routine's project is paused.
- companies: archiving runs a cascade that pauses active agents
  (pauseReason company_archived) and cancels queued wake-ups.

All claims verified against parent code (Phase 5.5 clean). Build + link/nav
checks pass; no drift. Teams Catalog, company-artifacts page, and low-trust
review containment are quarantined (<24h) and deferred to the next run.

Co-Authored-By: Claude Opus 4.8 (1M context) <[email protected]>
 2026-06-06 15:56:57 +02:00
Aron PrinsandClaude Opus 4.8 70ed497e12 nightly: full CLI reference handbook + wireframe skill + OpenAPI endpoint 
CLI API-parity coverage (paperclip #6626, parent 03e1e3ab) cleared 24h
quarantine and is now eligible. Adopt the comprehensive per-command CLI
reference under Reference → CLI, replacing the single-page commands.md
monolith. Guide/runbook track deferred to a later expansion.

- Reference → CLI rebuilt to 28 per-command pages (overview, installation,
  common-options, output-and-scripting, setup, dev-environments,
  authentication, company, project, goal, issue, agent, prompt, run,
  routine, adapter, approval, activity, dashboard, cost, workspace, access,
  skills, secrets, cloud, plugin, asset, feedback).
- Retire commands.md + control-plane-commands.md → "moved" tombstones plus
  route redirects in site/redirects.json. Repoint inbound links
  (reference/skills.md, how-to/sync-to-cloud-upstream.md).
- Rewrite deferred-guide links to existing equivalents; smooth an
  installation.md example that tripped a drift false-positive.
- Document the bundled `wireframe` catalog skill (reference/skills.md,
  guides/org/skills.md).
- Add the GET /api/openapi.json endpoint to the API overview
  (server/src/routes/openapi.ts).

Verified: docs:build OK, sync:check OK (links clean, drift 0, screenshots
indexed; 2 intended tombstone orphans). Regenerated PENDING.md +
SCREENSHOTS_PENDING.md; updated .sync-state.json.

Co-Authored-By: Claude Opus 4.8 (1M context) <[email protected]>
 2026-06-04 21:26:13 +02:00
Aron PrinsandClaude Opus 4.8 5f08200d05 nightly: issue artifacts — output playback, attachment streaming, skill upload 
Cumulative window v2026.529.0 → parent master edeab22c (24h quarantine).
One feature cluster: agent-produced issue artifacts (video/file deliverables)
that reviewers — including cloud reviewers without workspace access — can view
and play back on the board.

- docs/reference/api/issues.md — attachment openPath/downloadPath, ?download=1
  disposition, HTTP Range (206) streaming, video/zip allowed types + inference.
- docs/reference/skills.md — bundled paperclip skill artifact-upload helper.
- docs/guides/day-to-day/issues.md — Output section + inline video / open-vs-download.

All 3 PR-tier edits verified against parent (verify-edit: 39/39 on api/issues,
0 unverified across all). docs:build + sync:check green. Drift: none.

Co-Authored-By: Claude Opus 4.8 (1M context) <[email protected]>
 2026-06-03 10:03:49 +02:00
Aron PrinsandClaude Opus 4.8 9c5aae8962 Release docs for paperclip v2026.529.0 
Add the two release features quarantined from nightly, and stamp
paperclip_version on every touched page.

- Claude Local: document UI-driven live model discovery (#6953) —
  /v1/models lookup via ANTHROPIC_API_KEY, 60s cache, built-in fallback,
  Bedrock IDs, and the refresh control.
- Workspaces: document reused-workspace environment consistency and
  finalize-gated dependent wakes / interaction.accept (#6969).
- Stamp paperclip_version: v2026.529.0 on all 14 touched pages.
- Regenerate SCREENSHOTS_PENDING.md: 90/276 stale for this window.

Inherits the six features already drafted on nightly: resource
memberships (#6677), document annotations (#6733), bundled plugins in
plugin manager (#6734), skills CLI + catalog (#6782), first-admin
claim (#6755).

Co-Authored-By: Claude Opus 4.8 (1M context) <[email protected]>
 2026-05-30 19:00:46 +02:00
Aron PrinsandClaude Opus 4.8 534a8b4c0d nightly: skills CLI + catalog, first-admin browser claim (paperclip 524e18b) 
Cumulative nightly sync v2026.525.0 → parent master 524e18b (24h quarantine).

- Skills CLI command group (paperclipai skills …): control-plane workflow
  section + full subcommand/flag reference (#6782).
- App-shipped skills catalog (bundled/optional) + install-catalog / audit /
  install-update / reset lifecycle in the skills reference and org guide (#6782).
- Private browser first-admin claim (POST /api/bootstrap/claim) in the
  instance-admin API reference and installation guide (#6755).

Verified against parent: 0 high-confidence unverified claims. No drift, no
renames, no auto-merge/env changes. 5 commits held in quarantine.

Co-Authored-By: Claude Opus 4.8 (1M context) <[email protected]>
 2026-05-30 11:15:23 +02:00
Aron PrinsandClaude Opus 4.7 51b9fe35bb nightly: resource memberships, document annotations, bundled plugins (paperclip b754582) 
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]>
 2026-05-28 12:27:12 +02:00
Aron PrinsandClaude Opus 4.7 ee349a369a Release docs for paperclip v2026.525.0 (#14) 
* nightly: regenerate PENDING manifest (paperclip c0c5a82)

10 PR-tier candidates against v2026.517.0..master:
- modal sandbox provider plugin (new doc page)
- worktree init --force scope fix
- routine env runtime contract (migration 0086)
- workspace diff viewer plugin (new)
- plugin SDK surface + managed-resources concept
- environmentProbe RPC timeout 120s
- SecretBindingPicker in JsonSchemaForm
- inbox planning badge removed
- secret form textarea overflow fix
- new-issue autocomplete pointer fix

No drift, no reconciliation candidates. All 14 parent commits past
quarantine. Anchor-map db-migrations watcher path is stale
(packages/db/migrations -> packages/db/src/migrations) — noted for
maintenance.

Co-Authored-By: Claude Opus 4.7 (1M context) <[email protected]>

* nightly: document Modal sandbox provider (paperclip 4b1e92a..e5a0f5d)

* nightly: clarify scope of worktree init --force (paperclip 242a2c2)

* nightly: document routine env + secret-ref binding picker (paperclip 705c1b8..c0c5a82)

* nightly: document workspace diff viewer plugin (paperclip 5071c4c)

* nightly: audit plugin SDK reference + add managed resources note (paperclip c0c5a82)

* nightly: nav for modal adapter and workspace-diff plugin

Merges the two NAV_ADDITION entries returned by the doc-draft subagents
in this run, in one coordinated edit so the index file stays consistent.

Co-Authored-By: Claude Opus 4.7 (1M context) <[email protected]>

* nightly: workspace diff polish + manifest refresh (paperclip f2575305)

- docs/reference/plugins/workspace-diff.md: document split/unified toggle,
  working-tree vs against-ref toggle, base-ref input with defaultBaseRef
  prefill, sticky toolbar, and head → working-tree fallback when no
  base ref is set (paperclip #6383).
- PENDING.md: regenerate cumulative manifest against parent f2575305
  (20 commits in window, 13 doc-relevant entries). Adds entries for the
  provider vault secrets UX (#6381), cheap recovery model guard (#6371),
  sidebar fix (#6341), cloud tenant import exemption (#6378), and UI/dev
  QoL polish (#6384).
- .sync-state.json: bump last_seen_parent_sha to f2575305, refresh
  manifest hash, mark applied.

Co-Authored-By: Claude Opus 4.7 (1M context) <[email protected]>

* docs(nightly): add troubleshooting for 401 after creating a new secret

Customer hit a 401 after adding a new secret at the company level. The
new how-to didn't flag that creating a secret doesn't auto-rewire the
agent's env-var binding — fixed by adding two troubleshooting entries
covering the unbound-secret case and the provider-side rejection path.

Co-Authored-By: Claude Opus 4.7 (1M context) <[email protected]>

* nightly: manifest refresh (paperclip e3c875c, effective c91a062)

Cumulative window v2026.517.0 → c91a062 (21/29 commits; 8 quarantined).
Adds entry #14 for #6380 runtime control-plane fixes — overwhelmingly
internal correctness, surfaced as context-only with a note on the new
PORTABLE_JSON_BODY_LIMIT (64mb) constant for portable imports. All 13
prior entries still present in the cumulative diff — no reconciliation.
Drift check clean.

Co-Authored-By: Claude Opus 4.7 (1M context) <[email protected]>

* release: docs for paperclip v2026.525.0

Roll-up of nightly drafts plus newly-authored coverage for surfaces shipped
in v2026.525.0 that nightly hadn't reached yet:

- new: docs/how-to/sync-to-cloud-upstream.md (Cloud Upstream sync flow)
- new: docs/how-to/connect-aws-secrets-vault.md (AWS provider vault discovery)
- update: docs/reference/cli/commands.md — paperclipai cloud connect/push
- update: docs/reference/adapters/acpx-local.md — bare Claude model IDs, structured diagnostics, ~/.claude/settings.json handling
- update: docs/reference/api/agents.md — scoped permissions + authorization service, decision-reason table
- update: docs/reference/api/issues.md — retry-now endpoint
- update: docs/reference/deploy/secrets.md — Provider Vaults section
- update: docs/how-to/bring-your-own-agent.md — invite flow moved into add-agent modal

Bumped paperclip_version frontmatter to v2026.525.0 on all touched pages
(including nightly-authored Modal, workspace-diff, plugin SDK, routines,
worktree --force pages).

Updated .sync-state.json: base_release_tag v2026.517.0 -> v2026.525.0.

Co-Authored-By: Claude Opus 4.7 (1M context) <[email protected]>

---------

Co-authored-by: Claude Opus 4.7 (1M context) <[email protected]>
 2026-05-25 20:36:18 +02:00
Aron Prins 471de65da1 fix: harden docs rendering and stale references 2026-05-25 13:32:06 +02:00
Aron PrinsandClaude Opus 4.7 bd1799fc8d Release docs for paperclip v2026.517.0 
- 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]>
 2026-05-18 11:24:58 +02:00
Aron PrinsandClaude Opus 4.7 68d514fb26 Release docs for paperclip v2026.513.0 
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]>
 2026-05-14 09:53:29 +02:00
Aron PrinsandClaude Opus 4.7 2b5368e5af release: address v2026.512.0 coverage gaps 
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]>
 2026-05-13 15:51:54 +02:00
DottaandPaperclip 92e34c1dee Expand R4 issue lifecycle reference with mermaid + common mistakes 
- 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]>
 2026-04-27 18:19:15 -05:00
DottaandPaperclip eb3c4a4c09 Add skills reference (R6) 
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]>
 2026-04-27 16:29:22 -05:00
DottaandPaperclip 93ef8292de Expand skills/sync and request_board_approval payload docs 
- docs/reference/api/agents.md: add skills/sync request body fields
  (skillIds, skillKeys), worked examples in three languages, and the
  desiredSkills hire-time pointer.
- docs/reference/api/approvals.md: add the per-type payload shape
  table for request_board_approval, with the title/summary/
  recommendedAction/risks fields and a JSON example, plus brief notes
  on approve_ceo_strategy and hire_agent payloads.

Refs PAP-2507, PAP-1815, PAP-1819.

Co-Authored-By: Paperclip <[email protected]>
 2026-04-27 11:50:51 -05:00
DottaandPaperclip 53ebf1d18d Document inbox-lite, issue interactions, and lifecycle cross-link 
- docs/reference/api/agents.md: add the GET /api/agents/me/inbox-lite
  surface (compact heartbeat inbox with dependencyReady, blocker
  counts, activeRun) so agents can use it without reading the
  heartbeat skill.
- docs/reference/api/issues.md: add the issue Interactions API
  (suggest_tasks, ask_user_questions, request_confirmation) including
  accept/reject/respond, the idempotency-key pattern for plan
  approvals, and the recommended plan-approval sequence.
- docs/guides/day-to-day/issues.md: link from the Status Reference to
  the new state-machine reference.

Refs PAP-2507, PAP-1815, PAP-1817.

Co-Authored-By: Paperclip <[email protected]>
 2026-04-27 11:46:41 -05:00
DottaandPaperclip 3e78cda1b3 Expand issue lifecycle and agent runtime env var reference 
- docs/reference/api/issues.md: replace the minimal lifecycle stub
  with a full state-machine reference: status table, ASCII state
  diagram, allowed-transitions table, automatic side effects,
  executionState/review-stage notes, blockedByIssueIds semantics, and
  hiddenAt.
- docs/reference/deploy/environment-variables.md: add
  PAPERCLIP_WAKE_PAYLOAD_JSON, an "Always set?" column on the
  agent-runtime table, the full PAPERCLIP_WAKE_REASON enumeration, and
  an X-Paperclip-Run-Id audit-trail callout.

Refs PAP-2507, PAP-1817, PAP-1820.

Co-Authored-By: Paperclip <[email protected]>
 2026-04-27 11:37:18 -05:00
Aron PrinsandClaude Opus 4.7 56b8d7d52d Refactor docs IA into Guides + Reference tiers; add 10 new guides 
Reorganise all docs under a two-tier sidebar (Guides / Reference) with
tier-grouped landing cards that auto-size to the section count (3-col
default, 2x2 when a tier has 4 cards).

Moves
- docs/user-guides/guides/** -> docs/guides/{welcome,getting-started,
  day-to-day,org,projects-workflow,power}/
- docs/{api,cli,adapters,deploy} -> docs/reference/{api,cli,adapters,deploy}
- New docs/administration/ for company/settings/plugins/cli-auth
- 265 internal cross-links rewritten by scripts/rewrite-links.mjs
- site/redirects.json preserves old URLs

New guides
- guides/org/agents.md (absorbs how-agents-work.md)
- guides/day-to-day/issues.md (absorbs managing-tasks.md)
- guides/day-to-day/costs.md (absorbs costs-and-budgets.md)
- guides/projects-workflow/routines.md (absorbs heartbeats-and-routines.md)
- guides/projects-workflow/workspaces.md (absorbs execution-workspaces.md)
- guides/projects-workflow/projects.md
- guides/projects-workflow/goals.md
- guides/org/adapters.md (AdapterManager UI walkthrough)
- administration/{company,settings,plugins,cli-auth}.md

Expanded
- approvals.md, skills.md, org-structure.md with missing UI walkthroughs

Site
- content.json: tier field, merged Welcome into Getting Started, collapsed
  Administration to single section
- app.js: tier-grouped sidebar + landing; redirect map on route changes
- styles.css: tier headers and adaptive landing grid

Screenshots
- docs/user-guides/screenshots/SCREENSHOTS_TODO.md runbook for capturing
  on a disposable demo instance. No screenshots captured in this branch.

Co-Authored-By: Claude Opus 4.7 (1M context) <[email protected]>
 2026-04-22 19:02:48 +02:00