From fce3b439af99ba022b43a7972c57e332627c8bba Mon Sep 17 00:00:00 2001 From: Devin Foley Date: Sat, 20 Jun 2026 10:14:58 -0700 Subject: [PATCH] fix: warn operators that experimental features may break (#8382) ## Thinking Path > - Paperclip is the control plane operators use to manage AI-agent companies. > - Board operators rely on the settings UI and CLI docs to understand which product surfaces are stable to depend on. > - Experimental features already existed in the product, but the operator-facing contract around them was too soft and too fragmented. > - That created a risk that users would enable experiments without being told clearly that they can break, change, or disappear. > - The docs and the in-product settings page both needed the same explicit warning language so the contract is visible at the moment of decision. > - This pull request adds that warning to the board-operator guide, CLI references, and the experimental settings page. > - The benefit is clearer operator expectations without changing the underlying feature flags or rollout behavior. ## Linked Issues or Issue Description No public GitHub issue exists for this docs/polish gap. Problem description: - Board operators could enable experimental features without a clear operator-facing statement that those features are opt-in and come without compatibility guarantees. - The docs site, repo CLI reference, and in-product experimental settings page did not present one consistent warning contract. - This PR closes that gap by documenting the risk explicitly where operators discover and enable those settings. Related public search: - Searched public issues/PRs for related work with `gh search issues --repo paperclipai/paperclip 'experimental features warning'` and `gh search prs --repo paperclipai/paperclip 'experimental features warning'`. - Reviewed open PR #6165 during that search and found it unrelated; it changes experimental auth/routing flags rather than documenting experimental-feature risk. ## What Changed - Added a new board-operator guide at `docs/guides/board-operator/experimental-features.md` that defines the Paperclip contract for experimental features. - Registered that guide in `docs/docs.json` so it appears in the public docs navigation. - Added matching caveat language next to `instance settings:experimental` in `docs/cli/control-plane-commands.md`. - Added the same caveat to `doc/CLI.md` so the repo CLI reference does not drift from the published docs. - Added a single page-level warning banner to `ui/src/pages/InstanceExperimentalSettings.tsx` stating that experimental features are opt-in, carry no compatibility guarantees, and may change, break, or be removed. - Added a targeted UI test in `ui/src/pages/InstanceExperimentalSettings.test.tsx` that asserts exactly one page-level warning renders with the new risk language. ## Verification - `jq empty docs/docs.json` - `git diff --check` - `cd ui && pnpm vitest run src/pages/InstanceExperimentalSettings.test.tsx` - Manual review of the warning contract across: - `docs/guides/board-operator/experimental-features.md` - `docs/cli/control-plane-commands.md` - `doc/CLI.md` - `ui/src/pages/InstanceExperimentalSettings.tsx` UI note: - This is a copy-level warning addition rather than a layout rework. I did not attach before/after screenshots in this PR body. ## Risks - Low risk: this changes operator-facing documentation and warning copy, not feature-flag behavior. - The main failure mode is wording drift across docs and UI in future edits, which is why this PR adds the same contract to all relevant operator-facing surfaces. > I checked `ROADMAP.md` before opening this PR. This is docs/UI polish around an existing experimental surface, not overlapping roadmap-level core feature work. ## Model Used - OpenAI Codex Local using `gpt-5.4` with high reasoning and tool use for coordination, review, docs changes, and PR preparation. - Anthropic Claude Local using `claude-opus-4-8` with high reasoning and tool use for the in-product warning and targeted UI test. ## 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 - [ ] If this change affects the UI, I have included before/after screenshots - [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: Paperclip --- doc/CLI.md | 7 +++ docs/cli/control-plane-commands.md | 11 ++++ docs/docs.json | 1 + .../board-operator/experimental-features.md | 52 +++++++++++++++++++ .../InstanceExperimentalSettings.test.tsx | 10 ++++ ui/src/pages/InstanceExperimentalSettings.tsx | 18 ++++++- 6 files changed, 98 insertions(+), 1 deletion(-) create mode 100644 docs/guides/board-operator/experimental-features.md diff --git a/doc/CLI.md b/doc/CLI.md index 3e31af63..052cfb6b 100644 --- a/doc/CLI.md +++ b/doc/CLI.md @@ -651,6 +651,8 @@ pnpm paperclipai auth revoke-current `--token ` is still supported for compatibility, but `--token-env` avoids putting challenge secrets in shell history or process arguments. +## Instance Settings Commands + ```sh pnpm paperclipai instance scheduler-heartbeats pnpm paperclipai instance settings:general @@ -658,6 +660,11 @@ pnpm paperclipai instance settings:general:update --payload-json '{...}' pnpm paperclipai instance settings:experimental pnpm paperclipai instance settings:experimental:update --payload-json '{...}' pnpm paperclipai instance database-backup +``` + +Experimental features are opt-in and are provided without compatibility guarantees. They may break, change, or be removed at any time. Use them at your own risk. + +```sh pnpm paperclipai sidebar preferences pnpm paperclipai sidebar preferences:update --payload-json '{...}' pnpm paperclipai sidebar project-preferences --company-id diff --git a/docs/cli/control-plane-commands.md b/docs/cli/control-plane-commands.md index 29e1101d..406b3190 100644 --- a/docs/cli/control-plane-commands.md +++ b/docs/cli/control-plane-commands.md @@ -134,6 +134,17 @@ pnpm paperclipai activity list [--agent-id ] [--entity-type issue] [--entity pnpm paperclipai dashboard get ``` +## Instance Settings + +```sh +pnpm paperclipai instance settings:general +pnpm paperclipai instance settings:general:update --payload-json '{...}' +pnpm paperclipai instance settings:experimental +pnpm paperclipai instance settings:experimental:update --payload-json '{...}' +``` + +Experimental features are opt-in and are provided without compatibility guarantees. They may break, change, or be removed at any time. Use them at your own risk. + ## Heartbeat ```sh diff --git a/docs/docs.json b/docs/docs.json index 42fd463c..5787bda0 100644 --- a/docs/docs.json +++ b/docs/docs.json @@ -50,6 +50,7 @@ "guides/board-operator/delegation", "guides/board-operator/execution-workspaces-and-runtime-services", "guides/board-operator/delegation", + "guides/board-operator/experimental-features", "guides/board-operator/approvals", "guides/board-operator/costs-and-budgets", "guides/board-operator/activity-log", diff --git a/docs/guides/board-operator/experimental-features.md b/docs/guides/board-operator/experimental-features.md new file mode 100644 index 00000000..eff357c7 --- /dev/null +++ b/docs/guides/board-operator/experimental-features.md @@ -0,0 +1,52 @@ +--- +title: Experimental Features +summary: What Paperclip experimental features mean for board operators +--- + +Experimental features are opt-in and are provided without compatibility guarantees. They may break, change, or be removed at any time. Use them at your own risk. + +## What "experimental" means + +When a feature is marked experimental, Paperclip is still evaluating the product shape and implementation details. + +- The feature is not part of the stable operator contract yet. +- UI, API, CLI, behavior, and stored configuration may change as the feature evolves. +- Paperclip does not promise compatibility, rollback, migration, or long-term support for experimental features. + +If you need stable behavior for an important workflow, do not rely on an experimental feature. + +## Where you enable them + +Board operators enable or disable experiments from **Instance Settings > Experimental** in the app. + +The CLI exposes the same surface: + +```sh +pnpm paperclipai instance settings:experimental +pnpm paperclipai instance settings:experimental:update --payload-json '{...}' +``` + +Those commands change the same opt-in settings that the UI manages. + +## When to use them + +Experimental features are best used when you are: + +- evaluating a new capability before wider rollout +- testing a non-critical workflow +- comfortable with behavior changes between releases +- prepared to stop using the feature if it changes or disappears + +## Operator expectations + +Before enabling an experimental feature: + +- decide whether the workflow can tolerate breakage or churn +- avoid making the feature a dependency for stable production processes +- keep the scope small until you understand how the feature behaves in your company +- watch release notes and docs for changes to the feature contract + +## Related references + +- See the CLI caveat in [Control-Plane Commands](/cli/control-plane-commands). +- See the repo CLI reference in [`doc/CLI.md`](https://github.com/paperclipai/paperclip/blob/master/doc/CLI.md) when working from the repository. diff --git a/ui/src/pages/InstanceExperimentalSettings.test.tsx b/ui/src/pages/InstanceExperimentalSettings.test.tsx index fe8d1bb5..6e6247e7 100644 --- a/ui/src/pages/InstanceExperimentalSettings.test.tsx +++ b/ui/src/pages/InstanceExperimentalSettings.test.tsx @@ -101,6 +101,16 @@ describe("InstanceExperimentalSettings — Conference Room Chat card (PAP-11233) vi.clearAllMocks(); }); + it("renders a page-level warning about instability and lack of guarantees", async () => { + await renderPage(); + + const warning = [...container.querySelectorAll('[role="alert"]')].find((alert) => + alert.textContent?.includes("Experimental features may break at any time."), + ); + expect(warning?.textContent).toContain("Experimental features may break at any time."); + expect(warning?.textContent).toContain("no compatibility guarantees"); + }); + it("does not render the Conference Room Chat experimental setting for now", async () => { await renderPage(); diff --git a/ui/src/pages/InstanceExperimentalSettings.tsx b/ui/src/pages/InstanceExperimentalSettings.tsx index 78fdd8ca..0e39845a 100644 --- a/ui/src/pages/InstanceExperimentalSettings.tsx +++ b/ui/src/pages/InstanceExperimentalSettings.tsx @@ -1,6 +1,6 @@ import { useEffect, useState } from "react"; import { useMutation, useQuery, useQueryClient } from "@tanstack/react-query"; -import { Clock, FlaskConical, Play, Search } from "lucide-react"; +import { AlertTriangle, Clock, FlaskConical, Play, Search } from "lucide-react"; import type { InstanceExperimentalSettings, IssueGraphLivenessAutoRecoveryPreview, @@ -292,6 +292,22 @@ export function InstanceExperimentalSettings() {

+
+
+ +
+

Experimental features may break at any time.

+

+ These features are opt-in and come with no compatibility guarantees. They may change, break, or be + removed without notice. Avoid relying on them for critical or production workflows. +

+
+
+
+ {actionError && (
{actionError}