mirror of
https://github.com/paperclipai/paperclip.git
synced 2026-10-28 20:21:50 +01:00
Nicky LeachandPaperclip
5ca7b4c1fe
## Thinking Path > - Paperclip is the open source app people use to manage AI agents for work. > - Paperclip provides CLI guidance to agents and operators through documentation and runtime messages. > - Content-bearing `pnpm paperclipai` examples send arguments through a shell. > - Shell evaluation can execute command substitutions in untrusted argument content. > - Runtime hostname guidance can also place request-derived content inside a shell command. > - This pull request uses `npx paperclipai` for content-bearing guidance and uses a static hostname placeholder. > - The benefit is safer copy-paste guidance for agents and operators. ## Linked Issues or Issue Description **Issue type** Incorrect information **Where is the issue?** CLI guidance in `doc/CLI.md`, `skills/paperclip/SKILL.md`, documentation, and runtime-generated hints. **What's wrong?** Content-bearing `pnpm paperclipai` commands can pass argument text through `/bin/sh`. Shell command substitution in an argument can execute before the CLI receives the value. **Suggested fix** Use `npx paperclipai` for content-bearing commands. Use a static `<host>` placeholder when runtime guidance displays the allowed-hostname command. ## What Changed - Replace content-bearing `pnpm paperclipai` examples with `npx paperclipai` across the documentation and agent-facing guidance. - Update runtime-generated CLI hints to use a static `<host>` placeholder. - Add safety notes to `doc/CLI.md` and `skills/paperclip/SKILL.md`. - Add scans and regression tests for unsafe invocation and hostile hostname headers. - Keep fixed lifecycle commands and `pnpm --filter @paperclipai/*` build commands unchanged. ## Verification - Run `tsc --noEmit` for the changed server files. - Run `cli-invocation-safety.test.ts`. - Run `private-hostname-guard.test.ts`. - Confirm that hostile hostname headers do not enter shown shell commands. - Confirm that the three commits contain the required Paperclip co-author trailer. ## Risks - This change updates documentation and diagnostic text across many surfaces. - Fixed lifecycle and setup commands remain unchanged. - The tests fail if content-bearing `pnpm paperclipai` guidance returns. - The change does not alter the CLI argument parser. ## Model Used OpenAI Codex, GPT-5, tool use, code execution, and repository review assistance. ## 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 - [x] All Paperclip CI gates are green - [x] 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>
54 lines
2.1 KiB
Markdown
54 lines
2.1 KiB
Markdown
---
|
|
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 exec 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 [Status Cards](/guides/board-operator/status-cards) for the watched-query summary experiment, refresh policies, and cost model.
|
|
- 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.
|