docs(release): stable notes for the 2026.828.0-beta.0 soak (v2026.831.0) (#12610)

## Thinking Path

> - Paperclip is the open source app people use to manage AI agents for
work
> - The release process promotes a soaked beta to stable; the stable's
GitHub Release body comes from `releases/beta/v<beta-version>.md` on
`master`
> - The `draft_stable_notes` job seeded this file as a raw commit-log
skeleton when `2026.828.0-beta.0` published
> - The stable preflight fails without the merged file, and the skeleton
is not fit to publish as release notes
> - This pull request rewrites the skeleton into finished stable notes
for the v2026.831.0 promotion
> - The benefit is that the stable release ships with accurate,
readable, user-facing notes on time

## Linked Issues or Issue Description

**Issue type**

Missing content

**Where is the issue?**

`releases/beta/v2026.828.0-beta.0.md` — the drafted stable-notes
skeleton for the `2026.828.0-beta.0` soak.

**What's wrong?**

The file holds the auto-generated skeleton (grouped commit subjects with
nested PR summaries). The stable promotion publishes this file verbatim
as the GitHub Release body, so it must be rewritten into release-notes
voice before the stable dispatch.

**Suggested fix**

Rewrite the skeleton at full stable depth per
`.agents/skills/release-changelog/SKILL.md`: verified breaking changes
with upgrade paths, delta-aware highlights, grouped improvements and
fixes with inline PR attribution, an upgrade guide covering migrations
and new environment variables, and a contributors section.

## What Changed

- Rewrote `releases/beta/v2026.828.0-beta.0.md` from the generated
skeleton into finished notes titled `# Paperclip v2026.831.0`
- Six breaking changes, led by the Node.js 24.11.0 minimum; each has an
upgrade path
- Five highlights: runtime skill delivery to agents, the Kimi Code
adapter, operator settings-visibility controls, the HTTP/2 sandbox
callback bridge, and the shortened onboarding arc
- Upgrade guide covers migrations `0223`–`0230` (each attributed from
its SQL) and the new `PAPERCLIP_HIDDEN_SETTINGS`,
`PAPERCLIP_SETTING_DEFAULTS`, `SENTRY_DSN`, and
`PAPERCLIP_WORKSPACE_REAPER_COOLDOWN_DAYS` variables
- Entries already shipped to stable users in v2026.824.1 are noted as
such instead of re-announced
- Contributors section lists 7 verified community handles; core
maintainers and bots are excluded per the canonical list

## Verification

- Range verified as `664052f8e..dbf052577` (baseline v2026.824.1
merge-base to the `beta/v2026.828.0-beta.0` source commit); every entry
traces to a commit in that range
- Stable version confirmed with `./scripts/release.sh stable --date
2026-08-31 --print-version` → `2026.831.0`
- Migration list confirmed with `git diff --name-only
664052f8e..dbf052577 -- packages/db/src/migrations/` and each file's SQL
read at the source commit
- Environment variable names confirmed against
`docs/deploy/environment-variables.md` and source at `dbf052577`
- Contributor handles confirmed via `gh pr view <n> --json author` for
each attributed community PR

## Risks

- Low risk: a single markdown file; no source changes. The main risk is
a factual error in the notes — mitigated by verifying each claim against
the source commit rather than commit messages alone. If the promotion
date slips past 2026-08-31 UTC, the title needs a re-date (the
beta-keyed filename makes this harmless).

## Model Used

- Claude (Anthropic), model ID `claude-fable-5` (Claude Fable 5),
extended thinking enabled, tool use (git/GitHub CLI research against the
release range) via Claude Code

## Checklist

- [x] I have included a thinking path that traces from project context
to this change
- [x] I have specified the model used (with version and capability
details)
- [x] I have checked ROADMAP.md and confirmed this PR does not duplicate
planned core work
- [x] I have searched GitHub for duplicate or related PRs and linked
them above
- [x] I have either (a) linked existing issues with `Fixes: #` / `Closes
#` / `Refs #` OR (b) described the issue in-PR following the relevant
issue template
- [x] I have not referenced internal/instance-local Paperclip issues or
links (only public GitHub `#NNN` / `github.com/paperclipai/paperclip`
URLs)
- [x] My branch name describes the change (e.g. `docs/...`, `fix/...`)
and contains no internal Paperclip ticket id or instance-derived details
- [x] I have run tests locally and they pass
- [x] I have added or updated tests where applicable
- [x] I have updated relevant documentation to reflect my changes
- [x] I have considered and documented any risks above
- [ ] All Paperclip CI gates are green
- [ ] Greptile is 5/5 with no open P2s, recommendations, or follow-ups
- [x] I will address all Greptile and reviewer comments before
requesting merge

---------

Co-authored-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com>

releases/beta/v2026.828.0-beta.0.md

@@ -0,0 +1,65 @@
+# Paperclip v2026.831.0
+
+> Released: 2026-08-31
+
+Paperclip v2026.831.0 soaked as `2026.828.0-beta.0` and carries 175 commits. The company skill library now actually reaches your agents at run time, Kimi Code joins the adapter lineup, operators hosting Paperclip for others get real control over which settings surfaces their users see, the sandbox callback bridge is rebuilt on a bounded HTTP/2 transport, and onboarding sheds its mission step for a shorter arc with the agent front and center. It also raises the Node.js floor to 24 — read the Upgrade Guide before updating a source install.
+
+## Breaking Changes
+
+- **Node.js 24.11.0 or newer is required.** Every package manifest declares the new floor and the Docker images ship Node 24. Only managed installs (`paperclipai install`) refuse outright on an older Node; npm installs and a directly started server on Node 22/23 print an unsupported-version warning and continue. A warning is not support — upgrade Node before taking this release. ([#11792](https://github.com/paperclipai/paperclip/pull/11792), [#11890](https://github.com/paperclipai/paperclip/pull/11890))
+- **Invalid agent credentials are rejected instead of downgraded.** A bearer token that fails verification now returns a 401 naming the cause (expired, unverifiable, terminated agent, wrong company, …) instead of silently falling through to the anonymous local-user actor. Any integration that depended on that fall-through will start seeing 401s — that fall-through was the bug. ([#11589](https://github.com/paperclipai/paperclip/pull/11589))
+- **The company brand color and per-company attachment size limit are gone.** The fields are removed from the company General page, the create/update APIs, and the portability manifest; migration `0229` drops the columns. Export bundles that carry the old fields still import — the values are ignored. ([#12291](https://github.com/paperclipai/paperclip/pull/12291))
+- **Silent-run detection no longer takes action on its own.** Output silence still surfaces as a suspicious/critical level on active-run summaries in the UI, but it no longer creates evaluation issues, recovery actions, comments, or wake requests. Stranded-task recovery similarly stops automatic takeovers: exhausted and unsafe recovery now routes to a board-owned action instead of reassigning work by itself. ([#12242](https://github.com/paperclipai/paperclip/pull/12242), [#11961](https://github.com/paperclipai/paperclip/pull/11961))
+- **Agent thought text stays out of automatic issue comments.** ACPX run summaries are limited to the final output segment, and the legacy full-summary setting is deliberately ignored so configuration cannot bypass the containment. ([#11801](https://github.com/paperclipai/paperclip/pull/11801), @nearfolk)
+- **Grok no longer defaults `--permission-mode` to `dontAsk`.** The adapter passes no permission-mode flag unless one is explicitly configured; `--always-approve` remains the unattended policy. ([#11898](https://github.com/paperclipai/paperclip/pull/11898))
+
+## Highlights
+
+- **Your skill library now reaches your agents** — Skills used to be something you installed and hoped for. Now every agent run carries a deterministic manifest of the company's skill library in its instructions, agents can list skills over MCP, newly hired CEOs get the five core Paperclip skills by default, and installing a skill offers an "Enable for agents" step that pre-selects every skills-capable agent. When a skill fails to materialize, the failure is surfaced in the run output with its cause instead of the skill silently vanishing — and legacy runners are pinned back to the canonical operational skill. ([#12147](https://github.com/paperclipai/paperclip/pull/12147), [#12138](https://github.com/paperclipai/paperclip/pull/12138), [#12136](https://github.com/paperclipai/paperclip/pull/12136), [#12146](https://github.com/paperclipai/paperclip/pull/12146), [#12225](https://github.com/paperclipai/paperclip/pull/12225))
+- **Kimi Code is a first-class adapter** — `kimi_local` runs Moonshot's Kimi Code CLI on the shared ACP engine by default — live streaming transcripts, tool-call lifecycle, the same machinery as Claude, Codex, and Gemini — with an automatic headless-CLI fallback when ACP prerequisites are missing. ([#9967](https://github.com/paperclipai/paperclip/pull/9967), @hawikk)
+- **Operators can shape what their users see** — For anyone hosting Paperclip for others: `PAPERCLIP_HIDDEN_SETTINGS` hides settings surfaces by key — instance pages, individual experimental flags, company pages like Members, Invites, Secrets, Export, and Import, and even individual tabs like Provider vaults and Proposals. Hiding `company.import` floors the API too, and cloud-managed instances floor imports unconditionally. `PAPERCLIP_SETTING_DEFAULTS` overrides the schema default of selected instance settings without persisting anything, and a managed-sandbox-only mode hides host-path and execution-engine surfaces entirely. ([#11823](https://github.com/paperclipai/paperclip/pull/11823), [#12199](https://github.com/paperclipai/paperclip/pull/12199), [#12284](https://github.com/paperclipai/paperclip/pull/12284), [#12285](https://github.com/paperclipai/paperclip/pull/12285), [#12293](https://github.com/paperclipai/paperclip/pull/12293))
+- **The sandbox callback bridge, rebuilt to not fall over** — The bridge that lets sandboxed agents call back into Paperclip now prefers a bounded Node HTTP/2 duplex transport, demoting the file-polling relay to a soft-deprecated fallback: bytes stay binary end to end, every resource dimension is budgeted by a process-owned byte ledger (route data, broker forwards, decoder buffers, pending writes), the in-sandbox gateway survives faults after readiness and fails loudly before it, and a duplex channel dying mid-run fails the run closed instead of letting it end "successfully" with lost writes. The retired v1 transport is deleted outright. ([#12120](https://github.com/paperclipai/paperclip/pull/12120), [#11769](https://github.com/paperclipai/paperclip/pull/11769), [#12003](https://github.com/paperclipai/paperclip/pull/12003), [#12060](https://github.com/paperclipai/paperclip/pull/12060), [#11966](https://github.com/paperclipai/paperclip/pull/11966), [#12171](https://github.com/paperclipai/paperclip/pull/12171))
+- **Onboarding gets to the point** — The mission step is gone; the wizard opens on creating your agent, which asks for a name and nothing else (every onboarding hire starts in the `general` role). The steps are rebuilt on a single card with the brand pill held across them — dormant while you set up, alive when you review — and the auth page wears the new brand lockup. The idle "test your environment" card is gone too; the probe still runs on Connect and still blocks a failing hire. ([#11935](https://github.com/paperclipai/paperclip/pull/11935), [#11905](https://github.com/paperclipai/paperclip/pull/11905), [#12274](https://github.com/paperclipai/paperclip/pull/12274), [#12074](https://github.com/paperclipai/paperclip/pull/12074))
+
+## Improvements
+
+- **Opt-in error monitoring with Sentry** — Set `SENTRY_DSN` and install the optional `@sentry/node` peer to get server-side error capture; the DSN rides the authenticated session response so the browser reports too, behind a React error boundary. Everything is fail-open: no DSN, no package, no Sentry, no problem. ([#12190](https://github.com/paperclipai/paperclip/pull/12190), [#12249](https://github.com/paperclipai/paperclip/pull/12249), [#12270](https://github.com/paperclipai/paperclip/pull/12270))
+- **Company imports land better** — Last release made big imports resumable; this release makes arriving pleasant. Imported companies get de-duplicated names, an already-imported bundle names the company it landed as, every import outcome ends with a dashboard CTA, agents paused by an import carry a dedicated pause reason with visible notices and a Resume button in the thread, and the dashboard shows a banner with "Resume all" while imported agents sit paused. ([#12145](https://github.com/paperclipai/paperclip/pull/12145), [#12144](https://github.com/paperclipai/paperclip/pull/12144), [#12143](https://github.com/paperclipai/paperclip/pull/12143), [#12140](https://github.com/paperclipai/paperclip/pull/12140), [#12142](https://github.com/paperclipai/paperclip/pull/12142))
+- **Settings, unified** — Company and instance settings share one navigation; instance general controls live on the company General page; invites moved into a tab of the Members page; the separate instance Heartbeats page is gone; and user-facing copy now says "organization" where it used to say "company". Hosted tenants also get issue prefixes derived from the organization name, following renames. ([#11789](https://github.com/paperclipai/paperclip/pull/11789), [#12289](https://github.com/paperclipai/paperclip/pull/12289), [#12282](https://github.com/paperclipai/paperclip/pull/12282), [#12243](https://github.com/paperclipai/paperclip/pull/12243), [#12292](https://github.com/paperclipai/paperclip/pull/12292))
+- **Environments you can actually manage** — Deleting an environment now walks you through it: agents are reassigned in the same action, lease holders are listed, and destroying reusable sandboxes is a separate consent-labeled choice. Custom-image templates report boot-relevant drift with attribution and can be relinked in one click, and the managed default environment shows up by its name ("Paperclip Computer"), not its driver key. ([#12053](https://github.com/paperclipai/paperclip/pull/12053), [#11751](https://github.com/paperclipai/paperclip/pull/11751), [#11641](https://github.com/paperclipai/paperclip/pull/11641), [#11838](https://github.com/paperclipai/paperclip/pull/11838))
+- **Faster sandbox file movement** — Inbound workspace, asset, and referenced-project syncs run in parallel where the provider opts in, and Daytona file uploads are transparently zstd-compressed with a raw fallback. Referenced projects finally honor `.gitignore` during staging, and reported transfer byte counts are the real ones. ([#11736](https://github.com/paperclipai/paperclip/pull/11736), [#12271](https://github.com/paperclipai/paperclip/pull/12271), [#12184](https://github.com/paperclipai/paperclip/pull/12184), [#12180](https://github.com/paperclipai/paperclip/pull/12180))
+- **Managed workspaces hold up across restarts** — A shared port registry with lease heartbeats and identity checks keeps runtimes reliable across control-plane restarts, degraded embedded databases are detected and replaced with bounded restart supervision, cloned worktrees quarantine their copied services instead of fighting the originals, deferred database seeds are first-class operations with verified evidence, and the workspace login handoff is a signed, single-use ticket gated on real readiness. macOS worktrees can adopt their port owners now too. ([#11740](https://github.com/paperclipai/paperclip/pull/11740), [#11651](https://github.com/paperclipai/paperclip/pull/11651), [#11653](https://github.com/paperclipai/paperclip/pull/11653), [#11706](https://github.com/paperclipai/paperclip/pull/11706), [#11671](https://github.com/paperclipai/paperclip/pull/11671), [#11763](https://github.com/paperclipai/paperclip/pull/11763), @tf00185077)
+- **Wakes and recovery got more precise** — Question answers are delivered durably through a dedicated delivery ledger, blockers-resolved wakes are level-triggered and cycle-aware so a terminal reset can't strand a dependent, recovery retries survive restarts with bounded lineages, routine runs that failed transiently clear themselves when work resumes, and agent resume is authorized through direct grants. ([#12307](https://github.com/paperclipai/paperclip/pull/12307), [#11732](https://github.com/paperclipai/paperclip/pull/11732), [#11979](https://github.com/paperclipai/paperclip/pull/11979), @zach-hermes, [#11817](https://github.com/paperclipai/paperclip/pull/11817), [#9689](https://github.com/paperclipai/paperclip/pull/9689), [#12047](https://github.com/paperclipai/paperclip/pull/12047))
+- **Quality of life** — "Agent mode" is now "Auto mode" with full labels on the mode chips, every inbox item can be archived, parked browser tabs pick up new releases within the hour instead of serving a stale UI until a hard refresh, and the development runner honors `--data-dir` isolation. ([#11866](https://github.com/paperclipai/paperclip/pull/11866), [#11636](https://github.com/paperclipai/paperclip/pull/11636), [#12198](https://github.com/paperclipai/paperclip/pull/12198), [#12193](https://github.com/paperclipai/paperclip/pull/12193))
+- **Groundwork, deliberately off** — A native Codex execution runner (adapter `paperclip_runner`) landed behind the default-off `enableNativeRunner` instance flag, along with its persistence contracts and transport. It refuses hires and runs while the flag is off; nothing changes for existing adapters. ([#12188](https://github.com/paperclipai/paperclip/pull/12188), [#12169](https://github.com/paperclipai/paperclip/pull/12169), [#12176](https://github.com/paperclipai/paperclip/pull/12176))
+
+## Fixes
+
+- **Sign-up and sign-in work on Better Auth 1.7** — the upgrade needed an `issuer` column Better Auth expects; migration `0230` adds and backfills it. ([#11886](https://github.com/paperclipai/paperclip/pull/11886), [#12396](https://github.com/paperclipai/paperclip/pull/12396))
+- **The rich text editor renders again** — a second Lexical copy from a stale override broke node identity; the tree is back to one pinned copy, and prose containing angle brackets no longer kicks you out of the rich editor. ([#12317](https://github.com/paperclipai/paperclip/pull/12317), [#12290](https://github.com/paperclipai/paperclip/pull/12290))
+- **Docker orphans get reaped** — `tini` is PID 1 in the server image, so processes adopted after their parent exits are cleaned up instead of accumulating as zombies; a behavioral probe in CI keeps it that way. ([#12137](https://github.com/paperclipai/paperclip/pull/12137), @zannis)
+- **Adapters** — Hermes surfaces the real reasoning text from `reasoning.available` events instead of a placeholder ([#9237](https://github.com/paperclipai/paperclip/pull/9237), @harjothkhara); Grok stops warning when the default model sentinel isn't in the discovered list ([#12062](https://github.com/paperclipai/paperclip/pull/12062)); the Claude/Codex/Gemini ACP adapters share one workspace-restore teardown ([#12196](https://github.com/paperclipai/paperclip/pull/12196)); and the adapter Test lane verifies auth for every Claude ACP target with a deny-by-default probe environment. ([#11810](https://github.com/paperclipai/paperclip/pull/11810))
+- **Plugins** — errored plugins retry at boot instead of staying dead, plugin detail-tab deep links survive a reload, and plugin bundles get the host's real JSX runtime. ([#12054](https://github.com/paperclipai/paperclip/pull/12054), [#11826](https://github.com/paperclipai/paperclip/pull/11826))
+- **Task chat** — the composer clears the moment you send (and restores the draft on failure), the live tail shows the run's actual status instead of "Waiting for transcript...", and carets line up. ([#11772](https://github.com/paperclipai/paperclip/pull/11772), [#11802](https://github.com/paperclipai/paperclip/pull/11802))
+- **Git workspace sync** — imported histories with no common ancestor are grafted instead of failing the run, sync-created merge commits carry a deterministic identity, and PR preparation can attach to an existing branch without touching it. ([#11638](https://github.com/paperclipai/paperclip/pull/11638), [#11637](https://github.com/paperclipai/paperclip/pull/11637), [#11703](https://github.com/paperclipai/paperclip/pull/11703))
+- **Server correctness** — image-upload namespaces accept identity-provider characters with traversal rejected cleanly, the setup-token start guard is pinned to the served adapter, sandbox-driver environments skip the host provision command, rendered markdown code blocks follow the active theme, and the workspace reaper gained a configurable cooldown before it collects a terminal workspace's worktree. ([#12288](https://github.com/paperclipai/paperclip/pull/12288), [#12179](https://github.com/paperclipai/paperclip/pull/12179), [#11626](https://github.com/paperclipai/paperclip/pull/11626), [#11591](https://github.com/paperclipai/paperclip/pull/11591), [#11642](https://github.com/paperclipai/paperclip/pull/11642))
+
+The onboarding-service fixes from this range (`npx` onboard leaving a crash-looping background service, the duplicate foreground-start prompt, onboarding ending without opening the dashboard) already shipped to stable users as [v2026.824.1](https://github.com/paperclipai/paperclip/releases/tag/v2026.824.1).
+
+## Upgrade Guide
+
+- **Node.js**: the minimum is now **24.11.0**. Docker users get Node 24 with the image. Source installs and custom base images must upgrade first. Managed installs refuse with an error on an older Node; npm installs and direct server startup on Node 22/23 warn and continue, which is easy to miss in service logs — check `node --version` before upgrading rather than relying on the warning.
+- **Migrations**: this release adds 8 database migrations (`0223` through `0230`): a secret-proposal → interaction link (`0223`), unified adapter auth sessions replacing the Claude-specific table (`0224`, `0225`), a disposition-repair dedup index (`0226`), the native-runner contract tables — inert while the flag is off (`0227`), durable question-answer deliveries (`0228`), dropping the company brand-color and attachment-limit columns (`0229`), and the Better Auth `issuer` column with backfill (`0230`). They run automatically on startup. Only `0229` discards data, and only those two removed fields.
+- **New optional environment variables** (defaults preserve current behavior):
+  - `PAPERCLIP_HIDDEN_SETTINGS` — comma-separated settings surfaces to hide, for operators hosting Paperclip for others; hiding `company.import` also floors the import API. ([#11823](https://github.com/paperclipai/paperclip/pull/11823), [#12199](https://github.com/paperclipai/paperclip/pull/12199))
+  - `PAPERCLIP_SETTING_DEFAULTS` — JSON object overriding the schema default of selected instance settings. ([#12285](https://github.com/paperclipai/paperclip/pull/12285))
+  - `SENTRY_DSN` — opt in to error monitoring; also install the `@sentry/node@10.71.0` optional peer for server-side capture. ([#12190](https://github.com/paperclipai/paperclip/pull/12190))
+  - `PAPERCLIP_WORKSPACE_REAPER_COOLDOWN_DAYS` — days a terminal workspace is left alone before its worktree is reaped (default 7, `0` disables the cooldown). ([#11642](https://github.com/paperclipai/paperclip/pull/11642))
+- **Removed API fields**: `brandColor` and `attachmentMaxBytes` are gone from the company create/update/branding APIs and the portability manifest. Clients still sending them get validation errors; exported bundles carrying them import fine.
+- **Behavior changes to note**: bad agent bearer tokens now 401 (see Breaking Changes), silent runs and stranded tasks no longer trigger automatic recovery actions, and Grok's implicit `--permission-mode dontAsk` is gone.
+
+## Contributors
+
+This release has 175 commits from 13 contributors. Thank you to everyone who contributed to this release!
+
+@aaymeloglu, @harjothkhara, @hawikk, @nearfolk, @tf00185077, @zach-hermes, @zannis