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}