mirror of
https://github.com/paperclipai/paperclip-docs.git
synced 2026-11-07 06:16:07 -10:00
d627632874
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]>
scripts/sync — Doc-sync engine config
Configuration and state for the /sync-docs skill (see .claude/skills/sync-docs/SKILL.md).
This directory holds data, not code. The skill itself is the orchestrator; it reads these files to decide what to watch, where to route changes, and where it last left off.
Files
| File | Purpose | Committed? |
|---|---|---|
anchor-map.json |
Maps parent-repo paths → docs-repo paths, with detection rules and tier (auto-merge vs PR) | Yes |
state.example.json |
Template for .sync-state.json |
Yes |
../../.sync-state.json |
Current sync state for the branch (last synced parent ref) | Yes, per-branch |
lib/parent-source.mjs |
Shared parent-code access for check-drift.mjs and verify-edit.mjs: pinned snapshot download, file walk, env-source selection, REST route matching |
Yes |
Parent source for the checkers
check-drift.mjs and verify-edit.mjs read parent code from a full snapshot of the resolved commit, not file by file through the GitHub API.
| Setting | Effect |
|---|---|
| (default) | Download repos/<parent>/tarball/<sha> once into /tmp/paperclip-sync/src-<sha>/ and reuse it. The four newest snapshots are kept. |
PAPERCLIP_SYNC_LOCAL_SRC=<dir> |
Use an existing checkout or git archive extract at the right commit. |
PAPERCLIP_SYNC_NO_SNAPSHOT=1 |
Use the GitHub contents API. The env-var scan is capped at 700 files in this mode, and the output says so in warnings. |
PAPERCLIP_SYNC_FIXTURE_DIR=<dir> |
Tests only: read JSON fixtures. Snapshot mode is off. |
Both scripts add source (snapshot / github-api) and warnings to their JSON output. Before November 2026 the API path silently capped the env scan at 700 files while parent server/src alone had ~1,665, which produced the same ~40 false drift items every run.
Branch model
main(docs) tracks the latest released paperclip tag (e.g.v2026.512.0). Deploys to docs.paperclip.ing.nightly(docs) tracks parent'smainHEAD. Deploys to the Cloudflare Pages branch preview.
.sync-state.json therefore has a different value on each branch:
// on main
{ "mode": "release", "synced_to": "v2026.512.0", "synced_sha": "abc123…" }
// on nightly
{ "mode": "nightly", "synced_to": "main", "synced_sha": "def456…" }
Anchor map
Each watcher entry declares:
parent_paths— globs in github.com/paperclipai/paperclip to watch.docs_paths— globs in this repo where corresponding doc edits live.tier—auto-merge(mechanical, schema-bound),pr(judgment calls), orcontext-only(informs other watchers but never produces edits directly).detect— short prose telling the skill how to recognise a doc-relevant change in those files (e.g. "newprogram.command()calls", "new top-level dir").
The skill reads this file at the start of every run. Edit it when you add new doc sections or new product surfaces.
Skip patterns
skip_patterns are regexes matched against parent commit messages. Anything matching is ignored entirely — this is the first line of defence against revert/wip/codex churn.
Quarantine
quarantine_hours (default 24) tells nightly mode to ignore commits younger than N hours. Reverts and fix-ups tend to land in this window and cancel out before we draft anything.