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 <noreply@paperclip.ing>

doc/CLI.md

@@ -651,6 +651,8 @@ pnpm paperclipai auth revoke-current
 
 `--token <challenge-secret>` 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 <company-id>

docs/cli/control-plane-commands.md

@@ -134,6 +134,17 @@ pnpm paperclipai activity list [--agent-id <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

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",

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.

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();
 

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() {
         </p>
       </div>
 
+      <div
+        role="alert"
+        className="rounded-lg border border-amber-500/30 bg-amber-500/5 px-4 py-3"
+      >
+        <div className="flex items-start gap-3">
+          <AlertTriangle className="mt-0.5 h-4 w-4 shrink-0 text-amber-700" />
+          <div className="space-y-1 text-sm">
+            <p className="font-medium text-foreground">Experimental features may break at any time.</p>
+            <p className="text-muted-foreground">
+              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.
+            </p>
+          </div>
+        </div>
+      </div>
+
       {actionError && (
         <div className="rounded-md border border-destructive/40 bg-destructive/5 px-3 py-2 text-sm text-destructive">
           {actionError}