From 5ca7b4c1fefbf9afd5d4e1018c3ac728fc29a0ac Mon Sep 17 00:00:00 2001
From: Nicky Leach <nicky@paperclip.ing>
Date: Thu, 13 Aug 2026 16:43:21 -0700
Subject: [PATCH] fix(security): standardize paperclipai CLI guidance on safe
 npx path (#11343)

## 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>
---
 .agents/skills/paperclip-page/README.md       |   8 +-
 doc/CLI.md                                    | 792 ++++++++++--------
 doc/DATABASE.md                               |   2 +-
 doc/DEVELOPING.md                             |  14 +-
 doc/HERMES_GATEWAY_ONBOARDING.md              |  14 +-
 docs/adapters/claude-local.md                 |   2 +-
 docs/adapters/codex-local.md                  |   2 +-
 docs/api/secrets.md                           |   4 +-
 docs/cli/control-plane-commands.md            |  76 +-
 docs/cli/overview.md                          |  14 +-
 docs/cli/setup-commands.md                    |   2 +-
 docs/deploy/deployment-modes.md               |   2 +-
 docs/deploy/local-development.md              |   2 +-
 docs/deploy/secrets.md                        |   8 +-
 docs/deploy/tailscale-private-access.md       |   2 +-
 docs/feedback-voting.md                       |   4 +-
 .../board-operator/experimental-features.md   |   2 +-
 docs/guides/openclaw-docker-setup.md          |   4 +-
 .../__tests__/cli-invocation-safety.test.ts   | 345 ++++++++
 .../__tests__/private-hostname-guard.test.ts  |  28 +-
 server/src/adapters/hermes-gateway-doc.ts     |   2 +-
 .../src/middleware/private-hostname-guard.ts  |  20 +-
 server/src/routes/access.ts                   |  12 +-
 server/src/services/company-export-readme.ts  |   2 +-
 skills/paperclip/SKILL.md                     |   2 +
 ui/src/lib/agent-onboarding-prompt.ts         |   4 +-
 ui/src/pages/CompanyExport.tsx                |   2 +-
 27 files changed, 899 insertions(+), 472 deletions(-)
 create mode 100644 server/src/__tests__/cli-invocation-safety.test.ts

diff --git a/.agents/skills/paperclip-page/README.md b/.agents/skills/paperclip-page/README.md
index cfe2d87882..47cf6d0f1e 100644
--- a/.agents/skills/paperclip-page/README.md
+++ b/.agents/skills/paperclip-page/README.md
@@ -493,12 +493,12 @@ Create secrets from environment variables so values do not land in shell history
 export PAPERCLIP_PAGE_AWS_ACCESS_KEY_ID="$(jq -r '.AccessKey.AccessKeyId' /tmp/paperclip-page-uploader-key.json)"
 export PAPERCLIP_PAGE_AWS_SECRET_ACCESS_KEY="$(jq -r '.AccessKey.SecretAccessKey' /tmp/paperclip-page-uploader-key.json)"
 
-pnpm paperclipai secrets create \
+pnpm exec paperclipai secrets create \
   --company-id <company-id> \
   --name paperclip-page-aws-access-key-id \
   --value-env PAPERCLIP_PAGE_AWS_ACCESS_KEY_ID
 
-pnpm paperclipai secrets create \
+pnpm exec paperclipai secrets create \
   --company-id <company-id> \
   --name paperclip-page-aws-secret-access-key \
   --value-env PAPERCLIP_PAGE_AWS_SECRET_ACCESS_KEY
@@ -532,7 +532,7 @@ host `AWS_PROFILE` identity for the entire agent run:
 Create or update the company skill from this package:
 
 ```bash
-pnpm paperclipai skills create \
+pnpm exec paperclipai skills create \
   --company-id <company-id> \
   --name "Paperclip Page" \
   --slug paperclip-page \
@@ -543,7 +543,7 @@ pnpm paperclipai skills create \
 Attach it to an agent:
 
 ```bash
-pnpm paperclipai skills agent sync <agent-id-or-shortname> \
+pnpm exec paperclipai skills agent sync <agent-id-or-shortname> \
   --company-id <company-id> \
   --skill paperclip-page
 ```
diff --git a/doc/CLI.md b/doc/CLI.md
index 5c75aeb4e8..c5eff04686 100644
--- a/doc/CLI.md
+++ b/doc/CLI.md
@@ -6,6 +6,56 @@ Paperclip CLI now supports both:
 - instance setup/diagnostics (`onboard`, `doctor`, `configure`, `env`, `allowed-hostname`, `env-lab`)
 - control-plane client operations (issues, approvals, agents, activity, dashboard)
 
+## Security: safe invocation for content-bearing arguments
+
+Use `pnpm exec paperclipai` for any command whose argument can hold untrusted or
+semi-trusted content. Untrusted content includes issue text, comment bodies,
+Markdown, pasted snippets, and model output. `pnpm exec` runs the installed
+binary directly. It passes the argument as an inert `argv` value. It does not
+run a shell over the value.
+
+Do not use `pnpm paperclipai` for a content-bearing argument. The safe form and
+the unsafe form differ only by the `exec` keyword, so read the command with
+care. `pnpm paperclipai` is a `package.json` script. `pnpm` runs the argument
+through `/bin/sh` first. The shell interprets these metacharacters before the
+CLI starts:
+
+- command substitution: a backtick pair or `$( )`
+- variable expansion: `$NAME` or `${NAME}` (this can leak a secret value into the persisted argument)
+- other shell syntax: `; | & < >`
+
+A crafted value can run an arbitrary command as the invoking user. A crafted
+value can also expand an environment variable into the stored argument. No
+CLI-side check stops this, because the shell runs before `cli/src` starts.
+
+Safe forms:
+
+- `pnpm exec paperclipai <command> <args>` — the documented default
+- `npx paperclipai <command> <args>` — also injection-safe; use it when no local
+  install is present. `npx` fetches the package from the npm registry when the
+  binary is not installed locally, so a mistyped name can start a network
+  fetch. `pnpm exec` never does this; it runs only the locally installed binary.
+- `node <cli>/dist/index.js <command> <args>` — trusted direct-binary call
+
+Unsafe forms for a content-bearing argument:
+
+- `pnpm paperclipai <command> <args>`
+- `pnpm run <script> -- <args>`
+- any `package.json` script that wraps the CLI
+
+`pnpm paperclipai` stays acceptable only for local lifecycle and setup commands
+that take fixed, trusted arguments (for example `run`, `onboard`, `doctor`,
+`configure --section <name>`, `connect`, `env-lab up`, `worktree ensure-seeded`).
+A command is content-bearing, and needs `pnpm exec`, when it takes a non-fixed
+value: a hostname (`allowed-hostname`), an import URL or folder (`company
+import`), an identifier or secret (`--company-id`, `--agent-id`,
+`--claim-secret`), a payload (`--payload-json`), or free text (`--body`,
+`--title`, `--comment`). A runtime value counts as non-fixed even when it looks
+safe: the private-hostname guard builds `allowed-hostname <value>` from the
+request Host header, so it must use `pnpm exec`. The `pnpm --filter
+@paperclipai/*` build and test commands are not CLI invocation. They do not
+change.
+
 ## Base Usage
 
 Use repo script in development:
@@ -116,7 +166,7 @@ Canonical behavior is documented in `doc/DEPLOYMENT-MODES.md`.
 Allow an authenticated/private hostname (for example custom Tailscale DNS):
 
 ```sh
-pnpm paperclipai allowed-hostname dotta-macbook-pro
+pnpm exec paperclipai allowed-hostname dotta-macbook-pro
 ```
 
 Bring up the default local SSH fixture for environment testing:
@@ -174,8 +224,8 @@ pnpm paperclipai issue list --data-dir ./tmp/paperclip-dev
 Store local defaults in `~/.paperclip/context.json`:
 
 ```sh
-pnpm paperclipai context set --api-base http://localhost:3100 --company-id <company-id>
-pnpm paperclipai context set --persona agent --agent-id <agent-id> --api-key-env-var-name PAPERCLIP_API_KEY
+pnpm exec paperclipai context set --api-base http://localhost:3100 --company-id <company-id>
+pnpm exec paperclipai context set --persona agent --agent-id <agent-id> --api-key-env-var-name PAPERCLIP_API_KEY
 pnpm paperclipai context show
 pnpm paperclipai context list
 pnpm paperclipai context use default
@@ -184,35 +234,35 @@ pnpm paperclipai context use default
 To avoid storing secrets in context, set `apiKeyEnvVarName` and keep the key in env:
 
 ```sh
-pnpm paperclipai context set --api-key-env-var-name PAPERCLIP_API_KEY
+pnpm exec paperclipai context set --api-key-env-var-name PAPERCLIP_API_KEY
 export PAPERCLIP_API_KEY=...
 ```
 
 ## Company Commands
 
 ```sh
-pnpm paperclipai company list
-pnpm paperclipai company get <company-id>
-pnpm paperclipai company current [--company-id <company-id>]
-pnpm paperclipai company stats
-pnpm paperclipai company create --payload-json '{...}'
-pnpm paperclipai company update <company-id> --payload-json '{...}'
-pnpm paperclipai company branding:update <company-id> --payload-json '{...}'
-pnpm paperclipai company archive <company-id>
-pnpm paperclipai company export <company-id> --out ./company --include company,agents,projects,issues,skills
-pnpm paperclipai company export:preview <company-id> --payload-json '{...}'
-pnpm paperclipai company export:api <company-id> --payload-json '{...}'
-pnpm paperclipai company import ./company --target new --new-company-name "Imported Company"
-pnpm paperclipai company import:preview <company-id> --payload-json '{...}'
-pnpm paperclipai company import:apply <company-id> --payload-json '{...}'
-pnpm paperclipai company delete <company-id-or-prefix> --yes --confirm <same-id-or-prefix>
+pnpm exec paperclipai company list
+pnpm exec paperclipai company get <company-id>
+pnpm exec paperclipai company current [--company-id <company-id>]
+pnpm exec paperclipai company stats
+pnpm exec paperclipai company create --payload-json '{...}'
+pnpm exec paperclipai company update <company-id> --payload-json '{...}'
+pnpm exec paperclipai company branding:update <company-id> --payload-json '{...}'
+pnpm exec paperclipai company archive <company-id>
+pnpm exec paperclipai company export <company-id> --out ./company --include company,agents,projects,issues,skills
+pnpm exec paperclipai company export:preview <company-id> --payload-json '{...}'
+pnpm exec paperclipai company export:api <company-id> --payload-json '{...}'
+pnpm exec paperclipai company import ./company --target new --new-company-name "Imported Company"
+pnpm exec paperclipai company import:preview <company-id> --payload-json '{...}'
+pnpm exec paperclipai company import:apply <company-id> --payload-json '{...}'
+pnpm exec paperclipai company delete <company-id-or-prefix> --yes --confirm <same-id-or-prefix>
 ```
 
 Examples:
 
 ```sh
-pnpm paperclipai company delete PAP --yes --confirm PAP
-pnpm paperclipai company delete 5cbe79ee-acb3-4597-896e-7662742593cd --yes --confirm 5cbe79ee-acb3-4597-896e-7662742593cd
+pnpm exec paperclipai company delete PAP --yes --confirm PAP
+pnpm exec paperclipai company delete 5cbe79ee-acb3-4597-896e-7662742593cd --yes --confirm 5cbe79ee-acb3-4597-896e-7662742593cd
 ```
 
 Notes:
@@ -229,149 +279,149 @@ Notes:
 ## Issue Commands
 
 ```sh
-pnpm paperclipai issue list --company-id <company-id> [--status todo,in_progress] [--assignee-agent-id <agent-id>] [--match text]
-pnpm paperclipai issue get <issue-id-or-identifier>
-pnpm paperclipai issue create --company-id <company-id> --title "..." [--description "..."] [--status todo] [--priority high]
-pnpm paperclipai issue update <issue-id> [--status in_progress] [--comment "..."]
-pnpm paperclipai issue delete <issue-id> --yes
-pnpm paperclipai issue comment <issue-id> --body "..." [--reopen]
-pnpm paperclipai issue comments <issue-id> [--limit 50]
-pnpm paperclipai issue comment:get <issue-id> <comment-id>
-pnpm paperclipai issue comment:delete <issue-id> <comment-id>
-pnpm paperclipai issue runs <issue-id-or-identifier>
-pnpm paperclipai issue live-runs <issue-id-or-identifier>
-pnpm paperclipai issue active-run <issue-id-or-identifier>
-pnpm paperclipai issue heartbeat-context <issue-id>
-pnpm paperclipai issue checkout <issue-id> --agent-id <agent-id> [--expected-statuses todo,backlog,blocked]
-pnpm paperclipai issue release <issue-id>
-pnpm paperclipai issue force-release <issue-id>
+pnpm exec paperclipai issue list --company-id <company-id> [--status todo,in_progress] [--assignee-agent-id <agent-id>] [--match text]
+pnpm exec paperclipai issue get <issue-id-or-identifier>
+pnpm exec paperclipai issue create --company-id <company-id> --title "..." [--description "..."] [--status todo] [--priority high]
+pnpm exec paperclipai issue update <issue-id> [--status in_progress] [--comment "..."]
+pnpm exec paperclipai issue delete <issue-id> --yes
+pnpm exec paperclipai issue comment <issue-id> --body "..." [--reopen]
+pnpm exec paperclipai issue comments <issue-id> [--limit 50]
+pnpm exec paperclipai issue comment:get <issue-id> <comment-id>
+pnpm exec paperclipai issue comment:delete <issue-id> <comment-id>
+pnpm exec paperclipai issue runs <issue-id-or-identifier>
+pnpm exec paperclipai issue live-runs <issue-id-or-identifier>
+pnpm exec paperclipai issue active-run <issue-id-or-identifier>
+pnpm exec paperclipai issue heartbeat-context <issue-id>
+pnpm exec paperclipai issue checkout <issue-id> --agent-id <agent-id> [--expected-statuses todo,backlog,blocked]
+pnpm exec paperclipai issue release <issue-id>
+pnpm exec paperclipai issue force-release <issue-id>
 ```
 
 Issue subresources are exposed as Paperclip API wrappers. Commands that map to broad server schemas accept JSON payloads and validate them with shared schemas before sending.
 
 ```sh
-pnpm paperclipai issue child:create <issue-id> --payload-json '{"title":"Child task"}'
-pnpm paperclipai issue approvals <issue-id>
-pnpm paperclipai issue approval:link <issue-id> <approval-id>
-pnpm paperclipai issue approval:unlink <issue-id> <approval-id>
-pnpm paperclipai issue read <issue-id>
-pnpm paperclipai issue unread <issue-id>
-pnpm paperclipai issue archive <issue-id>
-pnpm paperclipai issue unarchive <issue-id>
-pnpm paperclipai issue recovery-actions <issue-id>
-pnpm paperclipai issue recovery:resolve <issue-id> --outcome restored --source-issue-status todo
+pnpm exec paperclipai issue child:create <issue-id> --payload-json '{"title":"Child task"}'
+pnpm exec paperclipai issue approvals <issue-id>
+pnpm exec paperclipai issue approval:link <issue-id> <approval-id>
+pnpm exec paperclipai issue approval:unlink <issue-id> <approval-id>
+pnpm exec paperclipai issue read <issue-id>
+pnpm exec paperclipai issue unread <issue-id>
+pnpm exec paperclipai issue archive <issue-id>
+pnpm exec paperclipai issue unarchive <issue-id>
+pnpm exec paperclipai issue recovery-actions <issue-id>
+pnpm exec paperclipai issue recovery:resolve <issue-id> --outcome restored --source-issue-status todo
 ```
 
 ```sh
-pnpm paperclipai issue documents <issue-id> [--include-system]
-pnpm paperclipai issue document:get <issue-id> <key>
-pnpm paperclipai issue document:put <issue-id> <key> --body-file ./plan.md [--title Plan]
-pnpm paperclipai issue document:lock <issue-id> <key>
-pnpm paperclipai issue document:unlock <issue-id> <key>
-pnpm paperclipai issue document:revisions <issue-id> <key>
-pnpm paperclipai issue document:restore <issue-id> <key> <revision-id>
-pnpm paperclipai issue document:delete <issue-id> <key>
+pnpm exec paperclipai issue documents <issue-id> [--include-system]
+pnpm exec paperclipai issue document:get <issue-id> <key>
+pnpm exec paperclipai issue document:put <issue-id> <key> --body-file ./plan.md [--title Plan]
+pnpm exec paperclipai issue document:lock <issue-id> <key>
+pnpm exec paperclipai issue document:unlock <issue-id> <key>
+pnpm exec paperclipai issue document:revisions <issue-id> <key>
+pnpm exec paperclipai issue document:restore <issue-id> <key> <revision-id>
+pnpm exec paperclipai issue document:delete <issue-id> <key>
 ```
 
 ```sh
-pnpm paperclipai issue work-products <issue-id>
-pnpm paperclipai issue work-product:create <issue-id> --payload-json '{"type":"pull_request","provider":"github","title":"PR"}'
-pnpm paperclipai issue work-product:update <work-product-id> --payload-json '{"status":"archived"}'
-pnpm paperclipai issue work-product:delete <work-product-id>
-pnpm paperclipai issue interactions <issue-id>
-pnpm paperclipai issue interaction:create <issue-id> --payload-json '{"kind":"request_confirmation","payload":{"version":1,"prompt":"Continue?"}}'
-pnpm paperclipai issue interaction:accept <issue-id> <interaction-id> [--selected-client-keys key1,key2]
-pnpm paperclipai issue interaction:reject <issue-id> <interaction-id> [--reason "..."]
-pnpm paperclipai issue interaction:respond <issue-id> <interaction-id> --answers-json '[{"questionId":"q1","optionIds":["yes"]}]'
-pnpm paperclipai issue interaction:cancel <issue-id> <interaction-id> [--reason "..."]
+pnpm exec paperclipai issue work-products <issue-id>
+pnpm exec paperclipai issue work-product:create <issue-id> --payload-json '{"type":"pull_request","provider":"github","title":"PR"}'
+pnpm exec paperclipai issue work-product:update <work-product-id> --payload-json '{"status":"archived"}'
+pnpm exec paperclipai issue work-product:delete <work-product-id>
+pnpm exec paperclipai issue interactions <issue-id>
+pnpm exec paperclipai issue interaction:create <issue-id> --payload-json '{"kind":"request_confirmation","payload":{"version":1,"prompt":"Continue?"}}'
+pnpm exec paperclipai issue interaction:accept <issue-id> <interaction-id> [--selected-client-keys key1,key2]
+pnpm exec paperclipai issue interaction:reject <issue-id> <interaction-id> [--reason "..."]
+pnpm exec paperclipai issue interaction:respond <issue-id> <interaction-id> --answers-json '[{"questionId":"q1","optionIds":["yes"]}]'
+pnpm exec paperclipai issue interaction:cancel <issue-id> <interaction-id> [--reason "..."]
 ```
 
 ```sh
-pnpm paperclipai issue tree-state <issue-id>
-pnpm paperclipai issue tree-preview <issue-id> --payload-json '{"mode":"pause"}'
-pnpm paperclipai issue tree-holds <issue-id> [--status active] [--include-members]
-pnpm paperclipai issue tree-hold:create <issue-id> --payload-json '{"mode":"pause","reason":"review"}'
-pnpm paperclipai issue tree-hold:get <issue-id> <hold-id>
-pnpm paperclipai issue tree-hold:release <issue-id> <hold-id> [--payload-json '{"reason":"done"}']
-pnpm paperclipai issue attachments <issue-id>
-pnpm paperclipai issue attachment:upload <issue-id> --company-id <company-id> --file ./artifact.txt
-pnpm paperclipai issue attachment:download <attachment-id> [--out ./artifact.txt]
-pnpm paperclipai issue attachment:delete <attachment-id>
-pnpm paperclipai issue label:list --company-id <company-id>
-pnpm paperclipai issue label:create --company-id <company-id> --name bug --color '#ff0000'
-pnpm paperclipai issue label:delete <label-id>
-pnpm paperclipai issue feedback:votes <issue-id>
-pnpm paperclipai issue feedback:vote <issue-id> --payload-json '{"targetType":"issue_comment","targetId":"...","vote":"up"}'
+pnpm exec paperclipai issue tree-state <issue-id>
+pnpm exec paperclipai issue tree-preview <issue-id> --payload-json '{"mode":"pause"}'
+pnpm exec paperclipai issue tree-holds <issue-id> [--status active] [--include-members]
+pnpm exec paperclipai issue tree-hold:create <issue-id> --payload-json '{"mode":"pause","reason":"review"}'
+pnpm exec paperclipai issue tree-hold:get <issue-id> <hold-id>
+pnpm exec paperclipai issue tree-hold:release <issue-id> <hold-id> [--payload-json '{"reason":"done"}']
+pnpm exec paperclipai issue attachments <issue-id>
+pnpm exec paperclipai issue attachment:upload <issue-id> --company-id <company-id> --file ./artifact.txt
+pnpm exec paperclipai issue attachment:download <attachment-id> [--out ./artifact.txt]
+pnpm exec paperclipai issue attachment:delete <attachment-id>
+pnpm exec paperclipai issue label:list --company-id <company-id>
+pnpm exec paperclipai issue label:create --company-id <company-id> --name bug --color '#ff0000'
+pnpm exec paperclipai issue label:delete <label-id>
+pnpm exec paperclipai issue feedback:votes <issue-id>
+pnpm exec paperclipai issue feedback:vote <issue-id> --payload-json '{"targetType":"issue_comment","targetId":"...","vote":"up"}'
 ```
 
 ## Project Commands
 
 ```sh
-pnpm paperclipai project list --company-id <company-id>
-pnpm paperclipai project get <project-id-or-shortname> [--company-id <company-id>]
-pnpm paperclipai project create --company-id <company-id> --name "Launch Site" [--goal-ids <id1,id2>] [--lead-agent-id <id>]
-pnpm paperclipai project update <project-id-or-shortname> [--status in_progress] [--company-id <company-id>]
-pnpm paperclipai project delete <project-id-or-shortname> --yes [--company-id <company-id>]
+pnpm exec paperclipai project list --company-id <company-id>
+pnpm exec paperclipai project get <project-id-or-shortname> [--company-id <company-id>]
+pnpm exec paperclipai project create --company-id <company-id> --name "Launch Site" [--goal-ids <id1,id2>] [--lead-agent-id <id>]
+pnpm exec paperclipai project update <project-id-or-shortname> [--status in_progress] [--company-id <company-id>]
+pnpm exec paperclipai project delete <project-id-or-shortname> --yes [--company-id <company-id>]
 ```
 
 Advanced project fields accept JSON:
 
 ```sh
-pnpm paperclipai project create --company-id <company-id> --name "Ops" --env-json '{"OPENAI_API_KEY":{"kind":"secret","secretName":"openai-api-key"}}'
-pnpm paperclipai project update <project-id> --execution-workspace-policy-json '{"enabled":true,"defaultMode":"shared_workspace"}'
+pnpm exec paperclipai project create --company-id <company-id> --name "Ops" --env-json '{"OPENAI_API_KEY":{"kind":"secret","secretName":"openai-api-key"}}'
+pnpm exec paperclipai project update <project-id> --execution-workspace-policy-json '{"enabled":true,"defaultMode":"shared_workspace"}'
 ```
 
 ## Goal Commands
 
 ```sh
-pnpm paperclipai goal list --company-id <company-id>
-pnpm paperclipai goal get <goal-id>
-pnpm paperclipai goal create --company-id <company-id> --title "Grow revenue" [--level company] [--status active]
-pnpm paperclipai goal update <goal-id> [--title "..."] [--status achieved]
-pnpm paperclipai goal delete <goal-id> --yes
+pnpm exec paperclipai goal list --company-id <company-id>
+pnpm exec paperclipai goal get <goal-id>
+pnpm exec paperclipai goal create --company-id <company-id> --title "Grow revenue" [--level company] [--status active]
+pnpm exec paperclipai goal update <goal-id> [--title "..."] [--status achieved]
+pnpm exec paperclipai goal delete <goal-id> --yes
 ```
 
 ## Agent Commands
 
 ```sh
-pnpm paperclipai agent list --company-id <company-id>
-pnpm paperclipai agent get <agent-id>
-pnpm paperclipai agent create --company-id <company-id> --payload-json '{"name":"Builder","adapterType":"codex_local"}'
-pnpm paperclipai agent hire --company-id <company-id> --payload-json '{...}'
-pnpm paperclipai agent update <agent-id> --payload-json '{"title":"Senior Builder"}'
-pnpm paperclipai agent delete <agent-id> --yes
-pnpm paperclipai agent me
-pnpm paperclipai agent inbox
-pnpm paperclipai agent inbox-mine --user-id <board-user-id>
-pnpm paperclipai agent wake <agent-id-or-shortname> [--company-id <company-id>] [--reason "..."] [--payload '{"issueId":"..."}']
-pnpm paperclipai agent pause <agent-id>
-pnpm paperclipai agent resume <agent-id>
-pnpm paperclipai agent approve <agent-id>
-pnpm paperclipai agent terminate <agent-id>
-pnpm paperclipai agent heartbeat:invoke <agent-id>
-pnpm paperclipai agent claude-login <agent-id>
-pnpm paperclipai agent local-cli <agent-id-or-shortname> --company-id <company-id>
+pnpm exec paperclipai agent list --company-id <company-id>
+pnpm exec paperclipai agent get <agent-id>
+pnpm exec paperclipai agent create --company-id <company-id> --payload-json '{"name":"Builder","adapterType":"codex_local"}'
+pnpm exec paperclipai agent hire --company-id <company-id> --payload-json '{...}'
+pnpm exec paperclipai agent update <agent-id> --payload-json '{"title":"Senior Builder"}'
+pnpm exec paperclipai agent delete <agent-id> --yes
+pnpm exec paperclipai agent me
+pnpm exec paperclipai agent inbox
+pnpm exec paperclipai agent inbox-mine --user-id <board-user-id>
+pnpm exec paperclipai agent wake <agent-id-or-shortname> [--company-id <company-id>] [--reason "..."] [--payload '{"issueId":"..."}']
+pnpm exec paperclipai agent pause <agent-id>
+pnpm exec paperclipai agent resume <agent-id>
+pnpm exec paperclipai agent approve <agent-id>
+pnpm exec paperclipai agent terminate <agent-id>
+pnpm exec paperclipai agent heartbeat:invoke <agent-id>
+pnpm exec paperclipai agent claude-login <agent-id>
+pnpm exec paperclipai agent local-cli <agent-id-or-shortname> --company-id <company-id>
 ```
 
 Agent configuration and runtime endpoints:
 
 ```sh
-pnpm paperclipai agent permissions:update <agent-id> --payload-json '{"canCreateAgents":true,"canCreateSkills":true,"canAssignTasks":true}'
-pnpm paperclipai agent configuration <agent-id>
-pnpm paperclipai agent config-revisions <agent-id>
-pnpm paperclipai agent config-revision:get <agent-id> <revision-id>
-pnpm paperclipai agent config-revision:rollback <agent-id> <revision-id>
-pnpm paperclipai agent runtime-state <agent-id>
-pnpm paperclipai agent runtime-state:reset-session <agent-id> [--task-key <key>]
-pnpm paperclipai agent task-sessions <agent-id>
-pnpm paperclipai agent skills <agent-id>
-pnpm paperclipai agent skills:sync <agent-id> --desired-skills paperclip,github --mode add
-pnpm paperclipai agent instructions-path:update <agent-id> --payload-json '{"path":"/path/to/AGENTS.md"}'
-pnpm paperclipai agent instructions-bundle <agent-id>
-pnpm paperclipai agent instructions-bundle:update <agent-id> --payload-json '{"mode":"managed"}'
-pnpm paperclipai agent instructions-file:get <agent-id> --path AGENTS.md
-pnpm paperclipai agent instructions-file:put <agent-id> --path AGENTS.md --content-file ./AGENTS.md
-pnpm paperclipai agent instructions-file:delete <agent-id> --path AGENTS.md
+pnpm exec paperclipai agent permissions:update <agent-id> --payload-json '{"canCreateAgents":true,"canCreateSkills":true,"canAssignTasks":true}'
+pnpm exec paperclipai agent configuration <agent-id>
+pnpm exec paperclipai agent config-revisions <agent-id>
+pnpm exec paperclipai agent config-revision:get <agent-id> <revision-id>
+pnpm exec paperclipai agent config-revision:rollback <agent-id> <revision-id>
+pnpm exec paperclipai agent runtime-state <agent-id>
+pnpm exec paperclipai agent runtime-state:reset-session <agent-id> [--task-key <key>]
+pnpm exec paperclipai agent task-sessions <agent-id>
+pnpm exec paperclipai agent skills <agent-id>
+pnpm exec paperclipai agent skills:sync <agent-id> --desired-skills paperclip,github --mode add
+pnpm exec paperclipai agent instructions-path:update <agent-id> --payload-json '{"path":"/path/to/AGENTS.md"}'
+pnpm exec paperclipai agent instructions-bundle <agent-id>
+pnpm exec paperclipai agent instructions-bundle:update <agent-id> --payload-json '{"mode":"managed"}'
+pnpm exec paperclipai agent instructions-file:get <agent-id> --path AGENTS.md
+pnpm exec paperclipai agent instructions-file:put <agent-id> --path AGENTS.md --content-file ./AGENTS.md
+pnpm exec paperclipai agent instructions-file:delete <agent-id> --path AGENTS.md
 ```
 
 Agent config, instructions, skills, project env, environment, secret, and workspace edits affect the next run. Active runs finish with the config they started with. When a saved session, reused workspace, or sandbox lease no longer matches the effective next-run config, Paperclip may start fresh execution and records non-sensitive freshness categories in run result JSON and workspace operation logs.
@@ -385,8 +435,8 @@ Agent config, instructions, skills, project env, environment, secret, and worksp
 Example for shortname-based local setup:
 
 ```sh
-pnpm paperclipai agent local-cli codexcoder --company-id <company-id>
-pnpm paperclipai agent local-cli claudecoder --company-id <company-id>
+pnpm exec paperclipai agent local-cli codexcoder --company-id <company-id>
+pnpm exec paperclipai agent local-cli claudecoder --company-id <company-id>
 ```
 
 ## Token Commands
@@ -394,18 +444,18 @@ pnpm paperclipai agent local-cli claudecoder --company-id <company-id>
 Agent API keys are scoped to one company and one agent. Plaintext tokens are printed once at creation.
 
 ```sh
-pnpm paperclipai token agent create --company-id <company-id> --agent <agent-id-or-name> --name external-worker
-pnpm paperclipai token agent list --company-id <company-id> --agent <agent-id-or-name>
-pnpm paperclipai token agent revoke --company-id <company-id> --agent <agent-id-or-name> <key-id>
+pnpm exec paperclipai token agent create --company-id <company-id> --agent <agent-id-or-name> --name external-worker
+pnpm exec paperclipai token agent list --company-id <company-id> --agent <agent-id-or-name>
+pnpm exec paperclipai token agent revoke --company-id <company-id> --agent <agent-id-or-name> <key-id>
 ```
 
 Named board API keys use the board authorization model, support revocation and expiration metadata, and are audited server-side.
 
 ```sh
-pnpm paperclipai token board create --company-id <company-id> --name external-admin
-pnpm paperclipai token board create --name short-lived --ttl-days 7
-pnpm paperclipai token board list
-pnpm paperclipai token board revoke <key-id>
+pnpm exec paperclipai token board create --company-id <company-id> --name external-admin
+pnpm exec paperclipai token board create --name short-lived --ttl-days 7
+pnpm exec paperclipai token board list
+pnpm exec paperclipai token board revoke <key-id>
 ```
 
 ## Run Commands
@@ -413,16 +463,16 @@ pnpm paperclipai token board revoke <key-id>
 `paperclipai run` without a subcommand still bootstraps and starts a local Paperclip instance. The subcommands below inspect and control API heartbeat runs.
 
 ```sh
-pnpm paperclipai run list --company-id <company-id> [--agent-id <agent-id>] [--limit 50]
-pnpm paperclipai run live --company-id <company-id> [--limit 50] [--min-count 0]
-pnpm paperclipai run get <run-id>
-pnpm paperclipai run events <run-id> [--after-seq 0] [--limit 200]
-pnpm paperclipai run log <run-id> [--offset 0] [--limit-bytes 16384] [--text]
-pnpm paperclipai run cancel <run-id>
-pnpm paperclipai run issues <run-id>
-pnpm paperclipai run workspace-operations <run-id>
-pnpm paperclipai run workspace-log <operation-id> [--offset 0] [--limit-bytes 16384] [--text]
-pnpm paperclipai run watchdog-decision <run-id> --decision continue [--reason "..."]
+pnpm exec paperclipai run list --company-id <company-id> [--agent-id <agent-id>] [--limit 50]
+pnpm exec paperclipai run live --company-id <company-id> [--limit 50] [--min-count 0]
+pnpm exec paperclipai run get <run-id>
+pnpm exec paperclipai run events <run-id> [--after-seq 0] [--limit 200]
+pnpm exec paperclipai run log <run-id> [--offset 0] [--limit-bytes 16384] [--text]
+pnpm exec paperclipai run cancel <run-id>
+pnpm exec paperclipai run issues <run-id>
+pnpm exec paperclipai run workspace-operations <run-id>
+pnpm exec paperclipai run workspace-log <operation-id> [--offset 0] [--limit-bytes 16384] [--text]
+pnpm exec paperclipai run watchdog-decision <run-id> --decision continue [--reason "..."]
 ```
 
 ## Routine Commands
@@ -430,19 +480,19 @@ pnpm paperclipai run watchdog-decision <run-id> --decision continue [--reason ".
 `paperclipai routines disable-all` remains the local maintenance command. The singular `routine` group maps to the REST API.
 
 ```sh
-pnpm paperclipai routine list --company-id <company-id> [--project-id <project-id>]
-pnpm paperclipai routine create --company-id <company-id> --payload-json '{...}'
-pnpm paperclipai routine get <routine-id>
-pnpm paperclipai routine update <routine-id> --payload-json '{...}'
-pnpm paperclipai routine revisions <routine-id>
-pnpm paperclipai routine revision:restore <routine-id> <revision-id>
-pnpm paperclipai routine runs <routine-id> [--limit 50]
-pnpm paperclipai routine run <routine-id> [--payload-json '{...}']
-pnpm paperclipai routine trigger:create <routine-id> --payload-json '{...}'
-pnpm paperclipai routine trigger:update <trigger-id> --payload-json '{...}'
-pnpm paperclipai routine trigger:delete <trigger-id>
-pnpm paperclipai routine trigger:rotate-secret <trigger-id>
-pnpm paperclipai routine trigger:fire <public-id> [--payload-json '{...}']
+pnpm exec paperclipai routine list --company-id <company-id> [--project-id <project-id>]
+pnpm exec paperclipai routine create --company-id <company-id> --payload-json '{...}'
+pnpm exec paperclipai routine get <routine-id>
+pnpm exec paperclipai routine update <routine-id> --payload-json '{...}'
+pnpm exec paperclipai routine revisions <routine-id>
+pnpm exec paperclipai routine revision:restore <routine-id> <revision-id>
+pnpm exec paperclipai routine runs <routine-id> [--limit 50]
+pnpm exec paperclipai routine run <routine-id> [--payload-json '{...}']
+pnpm exec paperclipai routine trigger:create <routine-id> --payload-json '{...}'
+pnpm exec paperclipai routine trigger:update <trigger-id> --payload-json '{...}'
+pnpm exec paperclipai routine trigger:delete <trigger-id>
+pnpm exec paperclipai routine trigger:rotate-secret <trigger-id>
+pnpm exec paperclipai routine trigger:fire <public-id> [--payload-json '{...}']
 ```
 
 ## Prompt Handoff
@@ -450,10 +500,10 @@ pnpm paperclipai routine trigger:fire <public-id> [--payload-json '{...}']
 Prompt handoff creates Paperclip work. It does not create a chat session.
 
 ```sh
-pnpm paperclipai agent-prompt <agent-name-or-id> <agent-api-key> "Prompt here"
-pnpm paperclipai agent prompt --agent <agent-name-or-id> --api-key-env PAPERCLIP_API_KEY "Prompt here"
-pnpm paperclipai agent prompt --profile my-agent "Prompt here"
-pnpm paperclipai board prompt --company-id <company-id> --agent <agent-name-or-id> "Prompt here"
+pnpm exec paperclipai agent-prompt <agent-name-or-id> <agent-api-key> "Prompt here"
+pnpm exec paperclipai agent prompt --agent <agent-name-or-id> --api-key-env PAPERCLIP_API_KEY "Prompt here"
+pnpm exec paperclipai agent prompt --profile my-agent "Prompt here"
+pnpm exec paperclipai board prompt --company-id <company-id> --agent <agent-name-or-id> "Prompt here"
 ```
 
 By default the command creates a `todo` issue assigned to the target agent and wakes the agent. Use `--issue <issue-id>` to add a comment to existing work, and `--no-wake` to skip the wakeup.
@@ -490,10 +540,10 @@ Browse and inspect commands never mutate company state; `install` adds a catalog
 skill to the company library.
 
 ```sh
-pnpm paperclipai skills browse [--kind bundled|optional] [--category <slug>] [--query <text>]
-pnpm paperclipai skills search "<text>" [--kind bundled|optional] [--category <slug>]
-pnpm paperclipai skills inspect <catalog-id-or-key-or-slug>
-pnpm paperclipai skills install <catalog-id-or-key-or-slug> [--as <slug>] [--force] --company-id <company-id>
+pnpm exec paperclipai skills browse [--kind bundled|optional] [--category <slug>] [--query <text>]
+pnpm exec paperclipai skills search "<text>" [--kind bundled|optional] [--category <slug>]
+pnpm exec paperclipai skills inspect <catalog-id-or-key-or-slug>
+pnpm exec paperclipai skills install <catalog-id-or-key-or-slug> [--as <slug>] [--force] --company-id <company-id>
 ```
 
 Catalog semantics:
@@ -514,11 +564,11 @@ Catalog semantics:
 Examples:
 
 ```sh
-pnpm paperclipai skills browse --kind bundled --company-id <company-id>
-pnpm paperclipai skills search "pull request" --kind bundled
-pnpm paperclipai skills inspect github-pr-workflow
-pnpm paperclipai skills install github-pr-workflow --company-id <company-id>
-pnpm paperclipai skills install paperclipai:optional:browser:agent-browser --company-id <company-id>
+pnpm exec paperclipai skills browse --kind bundled --company-id <company-id>
+pnpm exec paperclipai skills search "pull request" --kind bundled
+pnpm exec paperclipai skills inspect github-pr-workflow
+pnpm exec paperclipai skills install github-pr-workflow --company-id <company-id>
+pnpm exec paperclipai skills install paperclipai:optional:browser:agent-browser --company-id <company-id>
 ```
 
 External GitHub, skills.sh, local-path, and URL sources still go through
@@ -527,18 +577,18 @@ External GitHub, skills.sh, local-path, and URL sources still go through
 ### Company library
 
 ```sh
-pnpm paperclipai skills list --company-id <company-id>
-pnpm paperclipai skills show <skill-id-or-key-or-slug> --company-id <company-id>
-pnpm paperclipai skills file <skill-id-or-key-or-slug> [--path SKILL.md] --company-id <company-id>
-pnpm paperclipai skills import <source> --company-id <company-id>
-pnpm paperclipai skills create --name "Review PRs" [--slug review-prs] [--description "..."] [--body-file SKILL.md] --company-id <company-id>
-pnpm paperclipai skills scan-projects [--project-id <id>...] [--workspace-id <id>...] --company-id <company-id>
-pnpm paperclipai skills check [skill-id-or-key-or-slug] --company-id <company-id>
-pnpm paperclipai skills update <skill-id-or-key-or-slug> [--force] --company-id <company-id>
-pnpm paperclipai skills update --all [--force] --company-id <company-id>
-pnpm paperclipai skills audit [skill-id-or-key-or-slug] --company-id <company-id>
-pnpm paperclipai skills reset <skill-id-or-key-or-slug> [--yes] [--force] --company-id <company-id>
-pnpm paperclipai skills remove <skill-id-or-key-or-slug> --yes --company-id <company-id>
+pnpm exec paperclipai skills list --company-id <company-id>
+pnpm exec paperclipai skills show <skill-id-or-key-or-slug> --company-id <company-id>
+pnpm exec paperclipai skills file <skill-id-or-key-or-slug> [--path SKILL.md] --company-id <company-id>
+pnpm exec paperclipai skills import <source> --company-id <company-id>
+pnpm exec paperclipai skills create --name "Review PRs" [--slug review-prs] [--description "..."] [--body-file SKILL.md] --company-id <company-id>
+pnpm exec paperclipai skills scan-projects [--project-id <id>...] [--workspace-id <id>...] --company-id <company-id>
+pnpm exec paperclipai skills check [skill-id-or-key-or-slug] --company-id <company-id>
+pnpm exec paperclipai skills update <skill-id-or-key-or-slug> [--force] --company-id <company-id>
+pnpm exec paperclipai skills update --all [--force] --company-id <company-id>
+pnpm exec paperclipai skills audit [skill-id-or-key-or-slug] --company-id <company-id>
+pnpm exec paperclipai skills reset <skill-id-or-key-or-slug> [--yes] [--force] --company-id <company-id>
+pnpm exec paperclipai skills remove <skill-id-or-key-or-slug> --yes --company-id <company-id>
 ```
 
 `skills import <source>` accepts a skills.sh URL, the equivalent
@@ -564,9 +614,9 @@ maintenance loop for catalog-installed skills:
 ### Agent attach
 
 ```sh
-pnpm paperclipai skills agent list <agent-id-or-shortname> --company-id <company-id>
-pnpm paperclipai skills agent sync <agent-id-or-shortname> --skill <skill-id-or-key-or-slug> [--skill <skill-id-or-key-or-slug>...] --mode <add|remove|replace> --company-id <company-id>
-pnpm paperclipai skills agent clear <agent-id-or-shortname> --yes --company-id <company-id>
+pnpm exec paperclipai skills agent list <agent-id-or-shortname> --company-id <company-id>
+pnpm exec paperclipai skills agent sync <agent-id-or-shortname> --skill <skill-id-or-key-or-slug> [--skill <skill-id-or-key-or-slug>...] --mode <add|remove|replace> --company-id <company-id>
+pnpm exec paperclipai skills agent clear <agent-id-or-shortname> --yes --company-id <company-id>
 ```
 
 `skills agent sync` requires a merge mode and returns the resulting adapter
@@ -594,11 +644,11 @@ change company state. `preview` runs the company import planner, and `install`
 imports the catalog team into an existing company.
 
 ```sh
-pnpm paperclipai teams browse [--kind bundled|optional] [--category <slug>] [--query <text>]
-pnpm paperclipai teams search "<text>" [--kind bundled|optional] [--category <slug>]
-pnpm paperclipai teams inspect <catalog-id-or-key-or-slug> [--file TEAM.md]
-pnpm paperclipai teams preview <catalog-id-or-key-or-slug> --company-id <company-id>
-pnpm paperclipai teams install <catalog-id-or-key-or-slug> --company-id <company-id>
+pnpm exec paperclipai teams browse [--kind bundled|optional] [--category <slug>] [--query <text>]
+pnpm exec paperclipai teams search "<text>" [--kind bundled|optional] [--category <slug>]
+pnpm exec paperclipai teams inspect <catalog-id-or-key-or-slug> [--file TEAM.md]
+pnpm exec paperclipai teams preview <catalog-id-or-key-or-slug> --company-id <company-id>
+pnpm exec paperclipai teams install <catalog-id-or-key-or-slug> --company-id <company-id>
 ```
 
 Preview/install options:
@@ -626,22 +676,22 @@ Preview/install options:
 ## Secrets Commands
 
 ```sh
-pnpm paperclipai secrets list --company-id <company-id>
-pnpm paperclipai secrets declarations --company-id <company-id> [--include agents,projects] [--kind secret]
-pnpm paperclipai secrets create --company-id <company-id> --name anthropic-api-key --value-env ANTHROPIC_API_KEY
-pnpm paperclipai secrets link --company-id <company-id> --name prod-stripe-key --provider aws_secrets_manager --external-ref <provider-ref>
-pnpm paperclipai secrets doctor --company-id <company-id>
-pnpm paperclipai secrets provider-configs --company-id <company-id>
-pnpm paperclipai secrets provider-config:create --company-id <company-id> --payload-json '{...}'
-pnpm paperclipai secrets provider-config:discovery-preview --company-id <company-id> --payload-json '{...}'
-pnpm paperclipai secrets provider-config:get <config-id>
-pnpm paperclipai secrets provider-config:update <config-id> --payload-json '{...}'
-pnpm paperclipai secrets provider-config:default <config-id>
-pnpm paperclipai secrets provider-config:health <config-id>
-pnpm paperclipai secrets provider-config:delete <config-id>
-pnpm paperclipai secrets remote-import:preview --company-id <company-id> --payload-json '{...}'
-pnpm paperclipai secrets remote-import --company-id <company-id> --payload-json '{...}'
-pnpm paperclipai secrets migrate-inline-env --company-id <company-id> [--apply]
+pnpm exec paperclipai secrets list --company-id <company-id>
+pnpm exec paperclipai secrets declarations --company-id <company-id> [--include agents,projects] [--kind secret]
+pnpm exec paperclipai secrets create --company-id <company-id> --name anthropic-api-key --value-env ANTHROPIC_API_KEY
+pnpm exec paperclipai secrets link --company-id <company-id> --name prod-stripe-key --provider aws_secrets_manager --external-ref <provider-ref>
+pnpm exec paperclipai secrets doctor --company-id <company-id>
+pnpm exec paperclipai secrets provider-configs --company-id <company-id>
+pnpm exec paperclipai secrets provider-config:create --company-id <company-id> --payload-json '{...}'
+pnpm exec paperclipai secrets provider-config:discovery-preview --company-id <company-id> --payload-json '{...}'
+pnpm exec paperclipai secrets provider-config:get <config-id>
+pnpm exec paperclipai secrets provider-config:update <config-id> --payload-json '{...}'
+pnpm exec paperclipai secrets provider-config:default <config-id>
+pnpm exec paperclipai secrets provider-config:health <config-id>
+pnpm exec paperclipai secrets provider-config:delete <config-id>
+pnpm exec paperclipai secrets remote-import:preview --company-id <company-id> --payload-json '{...}'
+pnpm exec paperclipai secrets remote-import --company-id <company-id> --payload-json '{...}'
+pnpm exec paperclipai secrets migrate-inline-env --company-id <company-id> [--apply]
 ```
 
 Secret listing and declarations never print secret values. `create` accepts
@@ -661,78 +711,78 @@ commands above. See the
 ## Approval Commands
 
 ```sh
-pnpm paperclipai approval list --company-id <company-id> [--status pending]
-pnpm paperclipai approval get <approval-id>
-pnpm paperclipai approval create --company-id <company-id> --type hire_agent --payload '{"name":"..."}' [--issue-ids <id1,id2>]
-pnpm paperclipai approval approve <approval-id> [--decision-note "..."]
-pnpm paperclipai approval reject <approval-id> [--decision-note "..."]
-pnpm paperclipai approval request-revision <approval-id> [--decision-note "..."]
-pnpm paperclipai approval resubmit <approval-id> [--payload '{"...":"..."}']
-pnpm paperclipai approval comment <approval-id> --body "..."
+pnpm exec paperclipai approval list --company-id <company-id> [--status pending]
+pnpm exec paperclipai approval get <approval-id>
+pnpm exec paperclipai approval create --company-id <company-id> --type hire_agent --payload '{"name":"..."}' [--issue-ids <id1,id2>]
+pnpm exec paperclipai approval approve <approval-id> [--decision-note "..."]
+pnpm exec paperclipai approval reject <approval-id> [--decision-note "..."]
+pnpm exec paperclipai approval request-revision <approval-id> [--decision-note "..."]
+pnpm exec paperclipai approval resubmit <approval-id> [--payload '{"...":"..."}']
+pnpm exec paperclipai approval comment <approval-id> --body "..."
 ```
 
 ## Activity Commands
 
 ```sh
-pnpm paperclipai activity list --company-id <company-id> [--agent-id <agent-id>] [--entity-type issue] [--entity-id <id>]
-pnpm paperclipai activity create --company-id <company-id> --payload-json '{...}'
-pnpm paperclipai activity issue <issue-id>
+pnpm exec paperclipai activity list --company-id <company-id> [--agent-id <agent-id>] [--entity-type issue] [--entity-id <id>]
+pnpm exec paperclipai activity create --company-id <company-id> --payload-json '{...}'
+pnpm exec paperclipai activity issue <issue-id>
 ```
 
 ## Dashboard Commands
 
 ```sh
-pnpm paperclipai dashboard get --company-id <company-id>
+pnpm exec paperclipai dashboard get --company-id <company-id>
 ```
 
 ## Org And Agent Config Commands
 
 ```sh
-pnpm paperclipai whoami
-pnpm paperclipai openapi
-pnpm paperclipai org get --company-id <company-id>
-pnpm paperclipai org svg --company-id <company-id> [--out org.svg]
-pnpm paperclipai org png --company-id <company-id> [--out org.png]
-pnpm paperclipai agent-config list --company-id <company-id>
+pnpm exec paperclipai whoami
+pnpm exec paperclipai openapi
+pnpm exec paperclipai org get --company-id <company-id>
+pnpm exec paperclipai org svg --company-id <company-id> [--out org.svg]
+pnpm exec paperclipai org png --company-id <company-id> [--out org.png]
+pnpm exec paperclipai agent-config list --company-id <company-id>
 ```
 
 ## Access, Profile, And Instance Commands
 
 ```sh
-pnpm paperclipai profile session
-pnpm paperclipai profile get
-pnpm paperclipai profile update --payload-json '{...}'
-pnpm paperclipai profile company-user <user-slug> --company-id <company-id>
-pnpm paperclipai invite list --company-id <company-id>
-pnpm paperclipai invite create --company-id <company-id> --payload-json '{...}'
-pnpm paperclipai invite revoke <invite-id>
-pnpm paperclipai invite show <token>
-pnpm paperclipai invite accept <token> [--payload-json '{...}']
-pnpm paperclipai invite onboarding:text <token>
-pnpm paperclipai join list --company-id <company-id> [--status pending_approval]
-pnpm paperclipai join approve <request-id> --company-id <company-id>
-pnpm paperclipai join reject <request-id> --company-id <company-id>
-pnpm paperclipai join claim-key <request-id> --claim-secret <secret>
-pnpm paperclipai member list --company-id <company-id>
-pnpm paperclipai member update <member-id> --company-id <company-id> --payload-json '{...}'
-pnpm paperclipai member role-and-grants <member-id> --company-id <company-id> --payload-json '{...}'
-pnpm paperclipai member permissions <member-id> --company-id <company-id> --payload-json '{...}'
-pnpm paperclipai member archive <member-id> --company-id <company-id> [--payload-json '{...}']
-pnpm paperclipai admin user list [--query <text>]
-pnpm paperclipai admin user promote <user-id>
-pnpm paperclipai admin user demote <user-id>
-pnpm paperclipai admin user company-access <user-id>
-pnpm paperclipai admin user company-access:update <user-id> --payload-json '{...}'
+pnpm exec paperclipai profile session
+pnpm exec paperclipai profile get
+pnpm exec paperclipai profile update --payload-json '{...}'
+pnpm exec paperclipai profile company-user <user-slug> --company-id <company-id>
+pnpm exec paperclipai invite list --company-id <company-id>
+pnpm exec paperclipai invite create --company-id <company-id> --payload-json '{...}'
+pnpm exec paperclipai invite revoke <invite-id>
+pnpm exec paperclipai invite show <token>
+pnpm exec paperclipai invite accept <token> [--payload-json '{...}']
+pnpm exec paperclipai invite onboarding:text <token>
+pnpm exec paperclipai join list --company-id <company-id> [--status pending_approval]
+pnpm exec paperclipai join approve <request-id> --company-id <company-id>
+pnpm exec paperclipai join reject <request-id> --company-id <company-id>
+pnpm exec paperclipai join claim-key <request-id> --claim-secret <secret>
+pnpm exec paperclipai member list --company-id <company-id>
+pnpm exec paperclipai member update <member-id> --company-id <company-id> --payload-json '{...}'
+pnpm exec paperclipai member role-and-grants <member-id> --company-id <company-id> --payload-json '{...}'
+pnpm exec paperclipai member permissions <member-id> --company-id <company-id> --payload-json '{...}'
+pnpm exec paperclipai member archive <member-id> --company-id <company-id> [--payload-json '{...}']
+pnpm exec paperclipai admin user list [--query <text>]
+pnpm exec paperclipai admin user promote <user-id>
+pnpm exec paperclipai admin user demote <user-id>
+pnpm exec paperclipai admin user company-access <user-id>
+pnpm exec paperclipai admin user company-access:update <user-id> --payload-json '{...}'
 ```
 
 CLI auth challenge endpoints are also exposed for tooling that needs the raw challenge lifecycle:
 
 ```sh
-pnpm paperclipai auth challenge create --payload-json '{...}'
-PAPERCLIP_CHALLENGE_SECRET=<challenge-secret> pnpm paperclipai auth challenge get <challenge-id> --token-env PAPERCLIP_CHALLENGE_SECRET
-PAPERCLIP_CHALLENGE_SECRET=<challenge-secret> pnpm paperclipai auth challenge approve <challenge-id> --token-env PAPERCLIP_CHALLENGE_SECRET
-PAPERCLIP_CHALLENGE_SECRET=<challenge-secret> pnpm paperclipai auth challenge cancel <challenge-id> --token-env PAPERCLIP_CHALLENGE_SECRET
-pnpm paperclipai auth revoke-current
+pnpm exec paperclipai auth challenge create --payload-json '{...}'
+PAPERCLIP_CHALLENGE_SECRET=<challenge-secret> pnpm exec paperclipai auth challenge get <challenge-id> --token-env PAPERCLIP_CHALLENGE_SECRET
+PAPERCLIP_CHALLENGE_SECRET=<challenge-secret> pnpm exec paperclipai auth challenge approve <challenge-id> --token-env PAPERCLIP_CHALLENGE_SECRET
+PAPERCLIP_CHALLENGE_SECRET=<challenge-secret> pnpm exec paperclipai auth challenge cancel <challenge-id> --token-env PAPERCLIP_CHALLENGE_SECRET
+pnpm exec 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.
@@ -740,33 +790,33 @@ pnpm paperclipai auth revoke-current
 ## Instance Settings Commands
 
 ```sh
-pnpm paperclipai instance scheduler-heartbeats
-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 '{...}'
-pnpm paperclipai instance database-backup
+pnpm exec paperclipai instance scheduler-heartbeats
+pnpm exec paperclipai instance settings:general
+pnpm exec paperclipai instance settings:general:update --payload-json '{...}'
+pnpm exec paperclipai instance settings:experimental
+pnpm exec paperclipai instance settings:experimental:update --payload-json '{...}'
+pnpm exec 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>
-pnpm paperclipai sidebar project-preferences:update --company-id <company-id> --payload-json '{...}'
-pnpm paperclipai sidebar badges --company-id <company-id>
-pnpm paperclipai inbox dismissals --company-id <company-id>
-pnpm paperclipai inbox dismiss --company-id <company-id> --payload-json '{"itemKey":"run:<run-id>"}'
-pnpm paperclipai board-claim show <token>
-pnpm paperclipai board-claim claim <token> [--payload-json '{...}']
-pnpm paperclipai openclaw invite-prompt --company-id <company-id> --payload-json '{...}'
-pnpm paperclipai available-skill list
-pnpm paperclipai available-skill index
-pnpm paperclipai available-skill get <skill-name>
-pnpm paperclipai llm agent-configuration
-pnpm paperclipai llm agent-configuration:adapter <adapter-type>
-pnpm paperclipai llm agent-icons
+pnpm exec paperclipai sidebar preferences
+pnpm exec paperclipai sidebar preferences:update --payload-json '{...}'
+pnpm exec paperclipai sidebar project-preferences --company-id <company-id>
+pnpm exec paperclipai sidebar project-preferences:update --company-id <company-id> --payload-json '{...}'
+pnpm exec paperclipai sidebar badges --company-id <company-id>
+pnpm exec paperclipai inbox dismissals --company-id <company-id>
+pnpm exec paperclipai inbox dismiss --company-id <company-id> --payload-json '{"itemKey":"run:<run-id>"}'
+pnpm exec paperclipai board-claim show <token>
+pnpm exec paperclipai board-claim claim <token> [--payload-json '{...}']
+pnpm exec paperclipai openclaw invite-prompt --company-id <company-id> --payload-json '{...}'
+pnpm exec paperclipai available-skill list
+pnpm exec paperclipai available-skill index
+pnpm exec paperclipai available-skill get <skill-name>
+pnpm exec paperclipai llm agent-configuration
+pnpm exec paperclipai llm agent-configuration:adapter <adapter-type>
+pnpm exec paperclipai llm agent-icons
 ```
 
 Hermes gateway uses the generic invite/join commands above rather than
@@ -779,101 +829,101 @@ commands. See [HERMES_GATEWAY_ONBOARDING.md](./HERMES_GATEWAY_ONBOARDING.md).
 ## Adapter, Asset, And Skill Commands
 
 ```sh
-pnpm paperclipai adapter list
-pnpm paperclipai adapter install --payload-json '{"packageName":"@scope/adapter","version":"1.2.3"}'
-pnpm paperclipai adapter get <adapter-type>
-pnpm paperclipai adapter update <adapter-type> --payload-json '{"disabled":true}'
-pnpm paperclipai adapter override <adapter-type> --payload-json '{"paused":true}'
-pnpm paperclipai adapter reload <adapter-type>
-pnpm paperclipai adapter reinstall <adapter-type>
-pnpm paperclipai adapter delete <adapter-type>
-pnpm paperclipai adapter config-schema <adapter-type>
-pnpm paperclipai adapter ui-parser <adapter-type>
-pnpm paperclipai adapter models <adapter-type> --company-id <company-id> [--refresh] [--environment-id <id>]
-pnpm paperclipai adapter model-profiles <adapter-type> --company-id <company-id>
-pnpm paperclipai adapter detect-model <adapter-type> --company-id <company-id>
-pnpm paperclipai adapter test-environment <adapter-type> --company-id <company-id> --payload-json '{...}'
+pnpm exec paperclipai adapter list
+pnpm exec paperclipai adapter install --payload-json '{"packageName":"@scope/adapter","version":"1.2.3"}'
+pnpm exec paperclipai adapter get <adapter-type>
+pnpm exec paperclipai adapter update <adapter-type> --payload-json '{"disabled":true}'
+pnpm exec paperclipai adapter override <adapter-type> --payload-json '{"paused":true}'
+pnpm exec paperclipai adapter reload <adapter-type>
+pnpm exec paperclipai adapter reinstall <adapter-type>
+pnpm exec paperclipai adapter delete <adapter-type>
+pnpm exec paperclipai adapter config-schema <adapter-type>
+pnpm exec paperclipai adapter ui-parser <adapter-type>
+pnpm exec paperclipai adapter models <adapter-type> --company-id <company-id> [--refresh] [--environment-id <id>]
+pnpm exec paperclipai adapter model-profiles <adapter-type> --company-id <company-id>
+pnpm exec paperclipai adapter detect-model <adapter-type> --company-id <company-id>
+pnpm exec paperclipai adapter test-environment <adapter-type> --company-id <company-id> --payload-json '{...}'
 ```
 
 ```sh
-pnpm paperclipai asset image:upload --company-id <company-id> --file ./image.png [--namespace docs] [--alt "..."]
-pnpm paperclipai asset logo:upload --company-id <company-id> --file ./logo.svg
-pnpm paperclipai asset content <asset-id> --out ./asset.bin
+pnpm exec paperclipai asset image:upload --company-id <company-id> --file ./image.png [--namespace docs] [--alt "..."]
+pnpm exec paperclipai asset logo:upload --company-id <company-id> --file ./logo.svg
+pnpm exec paperclipai asset content <asset-id> --out ./asset.bin
 ```
 
 ```sh
-pnpm paperclipai skill list --company-id <company-id>
-pnpm paperclipai skill get <skill-id> --company-id <company-id>
-pnpm paperclipai skill file <skill-id> --company-id <company-id> [--path SKILL.md]
-pnpm paperclipai skill create --company-id <company-id> --payload-json '{...}'
-pnpm paperclipai skill file:update <skill-id> --company-id <company-id> --payload-json '{...}'
-pnpm paperclipai skill import --company-id <company-id> --payload-json '{"source":"github:owner/repo/path"}'
-pnpm paperclipai skill scan-projects --company-id <company-id> --payload-json '{...}'
-pnpm paperclipai skill update-status <skill-id> --company-id <company-id>
-pnpm paperclipai skill install-update <skill-id> --company-id <company-id>
-pnpm paperclipai skill delete <skill-id> --company-id <company-id>
+pnpm exec paperclipai skill list --company-id <company-id>
+pnpm exec paperclipai skill get <skill-id> --company-id <company-id>
+pnpm exec paperclipai skill file <skill-id> --company-id <company-id> [--path SKILL.md]
+pnpm exec paperclipai skill create --company-id <company-id> --payload-json '{...}'
+pnpm exec paperclipai skill file:update <skill-id> --company-id <company-id> --payload-json '{...}'
+pnpm exec paperclipai skill import --company-id <company-id> --payload-json '{"source":"github:owner/repo/path"}'
+pnpm exec paperclipai skill scan-projects --company-id <company-id> --payload-json '{...}'
+pnpm exec paperclipai skill update-status <skill-id> --company-id <company-id>
+pnpm exec paperclipai skill install-update <skill-id> --company-id <company-id>
+pnpm exec paperclipai skill delete <skill-id> --company-id <company-id>
 ```
 
 ## Cost, Finance, And Budget Commands
 
 ```sh
-pnpm paperclipai cost summary --company-id <company-id>
-pnpm paperclipai cost by-agent --company-id <company-id>
-pnpm paperclipai cost by-agent-model --company-id <company-id>
-pnpm paperclipai cost by-provider --company-id <company-id>
-pnpm paperclipai cost by-biller --company-id <company-id>
-pnpm paperclipai cost by-project --company-id <company-id>
-pnpm paperclipai cost window-spend --company-id <company-id>
-pnpm paperclipai cost quota-windows --company-id <company-id>
-pnpm paperclipai cost issue <issue-id>
-pnpm paperclipai cost event:create --company-id <company-id> --payload-json '{...}'
+pnpm exec paperclipai cost summary --company-id <company-id>
+pnpm exec paperclipai cost by-agent --company-id <company-id>
+pnpm exec paperclipai cost by-agent-model --company-id <company-id>
+pnpm exec paperclipai cost by-provider --company-id <company-id>
+pnpm exec paperclipai cost by-biller --company-id <company-id>
+pnpm exec paperclipai cost by-project --company-id <company-id>
+pnpm exec paperclipai cost window-spend --company-id <company-id>
+pnpm exec paperclipai cost quota-windows --company-id <company-id>
+pnpm exec paperclipai cost issue <issue-id>
+pnpm exec paperclipai cost event:create --company-id <company-id> --payload-json '{...}'
 ```
 
 ```sh
-pnpm paperclipai finance event:create --company-id <company-id> --payload-json '{...}'
-pnpm paperclipai finance events --company-id <company-id>
-pnpm paperclipai finance summary --company-id <company-id>
-pnpm paperclipai finance by-biller --company-id <company-id>
-pnpm paperclipai finance by-kind --company-id <company-id>
-pnpm paperclipai budget overview --company-id <company-id>
-pnpm paperclipai budget policy:upsert --company-id <company-id> --payload-json '{...}'
-pnpm paperclipai budget company:update --company-id <company-id> --payload-json '{...}'
-pnpm paperclipai budget agent:update <agent-id> --payload-json '{...}'
-pnpm paperclipai budget incident:resolve <incident-id> --company-id <company-id> [--payload-json '{...}']
+pnpm exec paperclipai finance event:create --company-id <company-id> --payload-json '{...}'
+pnpm exec paperclipai finance events --company-id <company-id>
+pnpm exec paperclipai finance summary --company-id <company-id>
+pnpm exec paperclipai finance by-biller --company-id <company-id>
+pnpm exec paperclipai finance by-kind --company-id <company-id>
+pnpm exec paperclipai budget overview --company-id <company-id>
+pnpm exec paperclipai budget policy:upsert --company-id <company-id> --payload-json '{...}'
+pnpm exec paperclipai budget company:update --company-id <company-id> --payload-json '{...}'
+pnpm exec paperclipai budget agent:update <agent-id> --payload-json '{...}'
+pnpm exec paperclipai budget incident:resolve <incident-id> --company-id <company-id> [--payload-json '{...}']
 ```
 
 ## Workspace And Environment Commands
 
 ```sh
-pnpm paperclipai workspace list --company-id <company-id>
-pnpm paperclipai workspace get <execution-workspace-id>
-pnpm paperclipai workspace close-readiness <execution-workspace-id>
-pnpm paperclipai workspace operations <execution-workspace-id>
-pnpm paperclipai workspace update <execution-workspace-id> --payload-json '{...}'
-pnpm paperclipai workspace runtime-service <execution-workspace-id> start --payload-json '{...}'
-pnpm paperclipai workspace runtime-command <execution-workspace-id> run --payload-json '{...}'
+pnpm exec paperclipai workspace list --company-id <company-id>
+pnpm exec paperclipai workspace get <execution-workspace-id>
+pnpm exec paperclipai workspace close-readiness <execution-workspace-id>
+pnpm exec paperclipai workspace operations <execution-workspace-id>
+pnpm exec paperclipai workspace update <execution-workspace-id> --payload-json '{...}'
+pnpm exec paperclipai workspace runtime-service <execution-workspace-id> start --payload-json '{...}'
+pnpm exec paperclipai workspace runtime-command <execution-workspace-id> run --payload-json '{...}'
 ```
 
 ```sh
-pnpm paperclipai environment list --company-id <company-id>
-pnpm paperclipai environment capabilities --company-id <company-id>
-pnpm paperclipai environment create --company-id <company-id> --payload-json '{...}'
-pnpm paperclipai environment get <environment-id>
-pnpm paperclipai environment leases <environment-id>
-pnpm paperclipai environment lease <lease-id>
-pnpm paperclipai environment update <environment-id> --payload-json '{...}'
-pnpm paperclipai environment delete <environment-id>
-pnpm paperclipai environment probe <environment-id>
-pnpm paperclipai environment probe-config --company-id <company-id> --payload-json '{...}'
+pnpm exec paperclipai environment list --company-id <company-id>
+pnpm exec paperclipai environment capabilities --company-id <company-id>
+pnpm exec paperclipai environment create --company-id <company-id> --payload-json '{...}'
+pnpm exec paperclipai environment get <environment-id>
+pnpm exec paperclipai environment leases <environment-id>
+pnpm exec paperclipai environment lease <lease-id>
+pnpm exec paperclipai environment update <environment-id> --payload-json '{...}'
+pnpm exec paperclipai environment delete <environment-id>
+pnpm exec paperclipai environment probe <environment-id>
+pnpm exec paperclipai environment probe-config --company-id <company-id> --payload-json '{...}'
 ```
 
 ```sh
-pnpm paperclipai project-workspace list <project-id>
-pnpm paperclipai project-workspace create <project-id> --payload-json '{...}'
-pnpm paperclipai project-workspace update <project-id> <workspace-id> --payload-json '{...}'
-pnpm paperclipai project-workspace delete <project-id> <workspace-id>
-pnpm paperclipai project-workspace runtime-service <project-id> <workspace-id> restart --payload-json '{...}'
-pnpm paperclipai project-workspace runtime-command <project-id> <workspace-id> run --payload-json '{...}'
+pnpm exec paperclipai project-workspace list <project-id>
+pnpm exec paperclipai project-workspace create <project-id> --payload-json '{...}'
+pnpm exec paperclipai project-workspace update <project-id> <workspace-id> --payload-json '{...}'
+pnpm exec paperclipai project-workspace delete <project-id> <workspace-id>
+pnpm exec paperclipai project-workspace runtime-service <project-id> <workspace-id> restart --payload-json '{...}'
+pnpm exec paperclipai project-workspace runtime-command <project-id> <workspace-id> run --payload-json '{...}'
 ```
 
 ## Plugin Commands
@@ -881,36 +931,36 @@ pnpm paperclipai project-workspace runtime-command <project-id> <workspace-id> r
 Existing plugin lifecycle commands remain available: `plugin init`, `list`, `install`, `uninstall`, `enable`, `disable`, `inspect`, and `examples`.
 
 ```sh
-pnpm paperclipai plugin ui-contributions
-pnpm paperclipai plugin tools
-pnpm paperclipai plugin tool:execute --payload-json '{...}'
-pnpm paperclipai plugin health <plugin-id>
-pnpm paperclipai plugin logs <plugin-id>
-pnpm paperclipai plugin upgrade <plugin-id>
-pnpm paperclipai plugin config <plugin-id> --company-id <company-id>
-pnpm paperclipai plugin config:set <plugin-id> --company-id <company-id> --payload-json '{"configJson":{...}}'
-pnpm paperclipai plugin config:test <plugin-id> --company-id <company-id> --payload-json '{"configJson":{...}}'
-pnpm paperclipai plugin jobs <plugin-id>
-pnpm paperclipai plugin job:runs <plugin-id> <job-id>
-pnpm paperclipai plugin job:trigger <plugin-id> <job-id> [--payload-json '{...}']
-pnpm paperclipai plugin webhook <plugin-id> <endpoint-key> [--payload-json '{...}']
-pnpm paperclipai plugin dashboard <plugin-id>
-pnpm paperclipai plugin bridge:data <plugin-id> --payload-json '{...}'
-pnpm paperclipai plugin bridge:action <plugin-id> --payload-json '{...}'
-pnpm paperclipai plugin bridge:stream <plugin-id> <channel> [--duration-ms 10000]
-pnpm paperclipai plugin data <plugin-id> <key> --payload-json '{...}'
-pnpm paperclipai plugin action <plugin-id> <key> --payload-json '{...}'
-pnpm paperclipai plugin local-folders <plugin-id> --company-id <company-id>
-pnpm paperclipai plugin local-folder:status <plugin-id> <folder-key> --company-id <company-id>
-pnpm paperclipai plugin local-folder:validate <plugin-id> <folder-key> --company-id <company-id> [--payload-json '{...}']
-pnpm paperclipai plugin local-folder:set <plugin-id> <folder-key> --company-id <company-id> --payload-json '{...}'
+pnpm exec paperclipai plugin ui-contributions
+pnpm exec paperclipai plugin tools
+pnpm exec paperclipai plugin tool:execute --payload-json '{...}'
+pnpm exec paperclipai plugin health <plugin-id>
+pnpm exec paperclipai plugin logs <plugin-id>
+pnpm exec paperclipai plugin upgrade <plugin-id>
+pnpm exec paperclipai plugin config <plugin-id> --company-id <company-id>
+pnpm exec paperclipai plugin config:set <plugin-id> --company-id <company-id> --payload-json '{"configJson":{...}}'
+pnpm exec paperclipai plugin config:test <plugin-id> --company-id <company-id> --payload-json '{"configJson":{...}}'
+pnpm exec paperclipai plugin jobs <plugin-id>
+pnpm exec paperclipai plugin job:runs <plugin-id> <job-id>
+pnpm exec paperclipai plugin job:trigger <plugin-id> <job-id> [--payload-json '{...}']
+pnpm exec paperclipai plugin webhook <plugin-id> <endpoint-key> [--payload-json '{...}']
+pnpm exec paperclipai plugin dashboard <plugin-id>
+pnpm exec paperclipai plugin bridge:data <plugin-id> --payload-json '{...}'
+pnpm exec paperclipai plugin bridge:action <plugin-id> --payload-json '{...}'
+pnpm exec paperclipai plugin bridge:stream <plugin-id> <channel> [--duration-ms 10000]
+pnpm exec paperclipai plugin data <plugin-id> <key> --payload-json '{...}'
+pnpm exec paperclipai plugin action <plugin-id> <key> --payload-json '{...}'
+pnpm exec paperclipai plugin local-folders <plugin-id> --company-id <company-id>
+pnpm exec paperclipai plugin local-folder:status <plugin-id> <folder-key> --company-id <company-id>
+pnpm exec paperclipai plugin local-folder:validate <plugin-id> <folder-key> --company-id <company-id> [--payload-json '{...}']
+pnpm exec paperclipai plugin local-folder:set <plugin-id> <folder-key> --company-id <company-id> --payload-json '{...}'
 ```
 
 Feedback traces can be fetched directly by ID when automating export workflows:
 
 ```sh
-pnpm paperclipai feedback trace <trace-id>
-pnpm paperclipai feedback bundle <trace-id>
+pnpm exec paperclipai feedback trace <trace-id>
+pnpm exec paperclipai feedback bundle <trace-id>
 ```
 
 ## Heartbeat Command
@@ -918,7 +968,7 @@ pnpm paperclipai feedback bundle <trace-id>
 `heartbeat run` now also supports context/api-key options and uses the shared client stack:
 
 ```sh
-pnpm paperclipai heartbeat run --agent-id <agent-id> [--api-base http://localhost:3100] [--api-key <token>]
+pnpm exec paperclipai heartbeat run --agent-id <agent-id> [--api-base http://localhost:3100] [--api-key <token>]
 ```
 
 ## Local Storage Defaults
diff --git a/doc/DATABASE.md b/doc/DATABASE.md
index 6c80f1f500..18a7208f20 100644
--- a/doc/DATABASE.md
+++ b/doc/DATABASE.md
@@ -267,7 +267,7 @@ pnpm paperclipai configure --section secrets
 Inline secret migration command:
 
 ```sh
-pnpm paperclipai secrets migrate-inline-env --company-id <company-id> --apply
+pnpm exec paperclipai secrets migrate-inline-env --company-id <company-id> --apply
 
 # direct database maintenance fallback
 pnpm secrets:migrate-inline-env --apply
diff --git a/doc/DEVELOPING.md b/doc/DEVELOPING.md
index ac53ac1b4f..d446e818a8 100644
--- a/doc/DEVELOPING.md
+++ b/doc/DEVELOPING.md
@@ -230,7 +230,7 @@ pnpm dev --authenticated-private
 Allow additional private hostnames (for example custom Tailscale hostnames):
 
 ```sh
-pnpm paperclipai allowed-hostname dotta-macbook-pro
+pnpm exec paperclipai allowed-hostname dotta-macbook-pro
 ```
 
 ## Test Commands
@@ -537,7 +537,7 @@ Repair an already-created repo-managed worktree and reseed its isolated instance
 
 ```sh
 cd /path/to/paperclip/.paperclip/worktrees/PAP-884-ai-commits-component
-pnpm paperclipai worktree init --force --seed-mode minimal \
+pnpm exec paperclipai worktree init --force --seed-mode minimal \
   --name PAP-884-ai-commits-component \
   --from-config ~/.paperclip/instances/default/config.json
 ```
@@ -869,15 +869,15 @@ Paperclip CLI now includes client-side control-plane commands in addition to set
 Quick examples:
 
 ```sh
-pnpm paperclipai issue list --company-id <company-id>
-pnpm paperclipai issue create --company-id <company-id> --title "Investigate checkout conflict"
-pnpm paperclipai issue update <issue-id> --status in_progress --comment "Started triage"
+pnpm exec paperclipai issue list --company-id <company-id>
+pnpm exec paperclipai issue create --company-id <company-id> --title "Investigate checkout conflict"
+pnpm exec paperclipai issue update <issue-id> --status in_progress --comment "Started triage"
 ```
 
 Set defaults once with context profiles:
 
 ```sh
-pnpm paperclipai context set --api-base http://localhost:3100 --company-id <company-id>
+pnpm exec paperclipai context set --api-base http://localhost:3100 --company-id <company-id>
 ```
 
 Then run commands without repeating flags:
@@ -961,4 +961,4 @@ Networking behavior for this smoke script:
 
 - auto-detects and prints a Paperclip host URL reachable from inside OpenClaw Docker
 - default container-side host alias is `host.docker.internal` (override with `PAPERCLIP_HOST_FROM_CONTAINER` / `PAPERCLIP_HOST_PORT`)
-- if Paperclip rejects container hostnames in authenticated/private mode, allow `host.docker.internal` via `pnpm paperclipai allowed-hostname host.docker.internal` and restart Paperclip
+- if Paperclip rejects container hostnames in authenticated/private mode, allow `host.docker.internal` via `pnpm exec paperclipai allowed-hostname host.docker.internal` and restart Paperclip
diff --git a/doc/HERMES_GATEWAY_ONBOARDING.md b/doc/HERMES_GATEWAY_ONBOARDING.md
index 58b9dfc5b0..29d9385516 100644
--- a/doc/HERMES_GATEWAY_ONBOARDING.md
+++ b/doc/HERMES_GATEWAY_ONBOARDING.md
@@ -79,9 +79,9 @@ The UI prompt points Hermes at the same machine-readable onboarding endpoints:
 For CLI-driven setup, create and inspect the invite directly:
 
 ```sh
-pnpm paperclipai invite create --company-id <company-id> --payload-json '{"requestType":"agent"}'
-pnpm paperclipai invite show <token>
-pnpm paperclipai invite onboarding:text <token>
+pnpm exec paperclipai invite create --company-id <company-id> --payload-json '{"requestType":"agent"}'
+pnpm exec paperclipai invite show <token>
+pnpm exec paperclipai invite onboarding:text <token>
 ```
 
 Hermes should submit a join request with `requestType: "agent"` and
@@ -119,14 +119,14 @@ After Hermes submits the join request:
 2. Approve it from the board UI, or use:
 
    ```sh
-   pnpm paperclipai join list --company-id <company-id> --status pending_approval
-   pnpm paperclipai join approve <request-id> --company-id <company-id>
+   pnpm exec paperclipai join list --company-id <company-id> --status pending_approval
+   pnpm exec paperclipai join approve <request-id> --company-id <company-id>
    ```
 
 3. Hermes claims the one-time agent API key:
 
    ```sh
-   pnpm paperclipai join claim-key <request-id> --claim-secret <secret>
+   pnpm exec paperclipai join claim-key <request-id> --claim-secret <secret>
    ```
 
 4. Store the claimed Paperclip key in Hermes runtime state or secrets. The claim
@@ -182,7 +182,7 @@ Use these entry points depending on who is driving setup:
   onboarding prompt.
 - Invite API: `GET /api/invites/:token/onboarding.txt` for the generated
   llm.txt-style setup instructions.
-- CLI invite flow: `pnpm paperclipai invite create`, `invite show`,
+- CLI invite flow: `pnpm exec paperclipai invite create`, `invite show`,
   `invite onboarding:text`, `join approve`, and `join claim-key`.
 - Smoke helpers: `pnpm smoke:hermes-gateway-e2e` for fresh-state Docker
   verification and `pnpm smoke:hermes-gateway-join` for an already-running
diff --git a/docs/adapters/claude-local.md b/docs/adapters/claude-local.md
index 1a13d0459c..a154327f5d 100644
--- a/docs/adapters/claude-local.md
+++ b/docs/adapters/claude-local.md
@@ -102,7 +102,7 @@ therefore shadows any Codex login already present inside the sandbox image.
 For manual local CLI usage outside heartbeat runs (for example running as `claudecoder` directly), use:
 
 ```sh
-pnpm paperclipai agent local-cli claudecoder --company-id <company-id>
+pnpm exec paperclipai agent local-cli claudecoder --company-id <company-id>
 ```
 
 This installs Paperclip skills in `~/.claude/skills`, creates an agent API key, and prints shell exports to run as that agent.
diff --git a/docs/adapters/codex-local.md b/docs/adapters/codex-local.md
index 5a539f150e..526ce11013 100644
--- a/docs/adapters/codex-local.md
+++ b/docs/adapters/codex-local.md
@@ -141,7 +141,7 @@ change.
 For manual local CLI usage outside heartbeat runs (for example running as `codexcoder` directly), use:
 
 ```sh
-pnpm paperclipai agent local-cli codexcoder --company-id <company-id>
+pnpm exec paperclipai agent local-cli codexcoder --company-id <company-id>
 ```
 
 This installs any missing skills, creates an agent API key, and prints shell exports to run as that agent.
diff --git a/docs/api/secrets.md b/docs/api/secrets.md
index 0369922928..2e4a9c017e 100644
--- a/docs/api/secrets.md
+++ b/docs/api/secrets.md
@@ -114,7 +114,7 @@ credentials must not be stored in Paperclip `company_secrets`.
 The equivalent CLI check is:
 
 ```sh
-pnpm paperclipai secrets doctor --company-id {companyId}
+pnpm exec paperclipai secrets doctor --company-id {companyId}
 ```
 
 ## Provider Vaults
@@ -485,7 +485,7 @@ as declarations in the package manifest. Exports omit secret values, secret IDs,
 provider references, and encrypted provider material. Use:
 
 ```sh
-pnpm paperclipai secrets declarations --company-id {companyId}
+pnpm exec paperclipai secrets declarations --company-id {companyId}
 ```
 
 to inspect the declarations that an export would emit before moving a package.
diff --git a/docs/cli/control-plane-commands.md b/docs/cli/control-plane-commands.md
index 70adf99ad2..f2ac4908f0 100644
--- a/docs/cli/control-plane-commands.md
+++ b/docs/cli/control-plane-commands.md
@@ -9,39 +9,39 @@ Client-side commands for managing issues, agents, approvals, and more.
 
 ```sh
 # List issues
-pnpm paperclipai issue list [--status todo,in_progress] [--assignee-agent-id <id>] [--match text]
+pnpm exec paperclipai issue list [--status todo,in_progress] [--assignee-agent-id <id>] [--match text]
 
 # Get issue details
-pnpm paperclipai issue get <issue-id-or-identifier>
+pnpm exec paperclipai issue get <issue-id-or-identifier>
 
 # Create issue
-pnpm paperclipai issue create --title "..." [--description "..."] [--status todo] [--priority high]
+pnpm exec paperclipai issue create --title "..." [--description "..."] [--status todo] [--priority high]
 
 # Update issue
-pnpm paperclipai issue update <issue-id> [--status in_progress] [--comment "..."]
+pnpm exec paperclipai issue update <issue-id> [--status in_progress] [--comment "..."]
 
 # Add comment
-pnpm paperclipai issue comment <issue-id> --body "..." [--reopen]
+pnpm exec paperclipai issue comment <issue-id> --body "..." [--reopen]
 
 # Checkout task
-pnpm paperclipai issue checkout <issue-id> --agent-id <agent-id>
+pnpm exec paperclipai issue checkout <issue-id> --agent-id <agent-id>
 
 # Release task
-pnpm paperclipai issue release <issue-id>
+pnpm exec paperclipai issue release <issue-id>
 ```
 
 ## Company Commands
 
 ```sh
-pnpm paperclipai company list
-pnpm paperclipai company get <company-id>
-pnpm paperclipai company current [--company-id <company-id>]
+pnpm exec paperclipai company list
+pnpm exec paperclipai company get <company-id>
+pnpm exec paperclipai company current [--company-id <company-id>]
 
 # Export to portable folder package (writes manifest + markdown files)
-pnpm paperclipai company export <company-id> --out ./exports/acme --include company,agents
+pnpm exec paperclipai company export <company-id> --out ./exports/acme --include company,agents
 
 # Preview import (no writes)
-pnpm paperclipai company import \
+pnpm exec paperclipai company import \
   <owner>/<repo>/<path> \
   --target existing \
   --company-id <company-id> \
@@ -50,7 +50,7 @@ pnpm paperclipai company import \
   --dry-run
 
 # Apply import
-pnpm paperclipai company import \
+pnpm exec paperclipai company import \
   ./exports/acme \
   --target new \
   --new-company-name "Acme Imported" \
@@ -67,80 +67,80 @@ command.
 ## Agent Commands
 
 ```sh
-pnpm paperclipai agent list
-pnpm paperclipai agent get <agent-id>
+pnpm exec paperclipai agent list
+pnpm exec paperclipai agent get <agent-id>
 ```
 
 ## Skills Commands
 
 ```sh
 # Browse app-shipped catalog skills without changing company state
-pnpm paperclipai skills browse [--kind bundled|optional] [--category software-development] [--query github]
-pnpm paperclipai skills search "pull request" [--json]
+pnpm exec paperclipai skills browse [--kind bundled|optional] [--category software-development] [--query github]
+pnpm exec paperclipai skills search "pull request" [--json]
 
 # Inspect catalog metadata and file inventory before install
-pnpm paperclipai skills inspect github-pr-workflow
+pnpm exec paperclipai skills inspect github-pr-workflow
 
 # Install a catalog skill into the company skill library
 # This does not attach the skill to any agent.
-pnpm paperclipai skills install github-pr-workflow --company-id <company-id>
-pnpm paperclipai skills install github-pr-workflow --as pr-flow --force --company-id <company-id>
+pnpm exec paperclipai skills install github-pr-workflow --company-id <company-id>
+pnpm exec paperclipai skills install github-pr-workflow --as pr-flow --force --company-id <company-id>
 
 # External sources still use import instead of catalog install
-pnpm paperclipai skills import ./skills/my-skill --company-id <company-id>
-pnpm paperclipai skills import owner/repo/path/to/skill --company-id <company-id>
+pnpm exec paperclipai skills import ./skills/my-skill --company-id <company-id>
+pnpm exec paperclipai skills import owner/repo/path/to/skill --company-id <company-id>
 
 # Attach desired company skills to an agent after install/import
-pnpm paperclipai skills agent sync <agent-id> --skill github-pr-workflow --mode add --company-id <company-id>
+pnpm exec paperclipai skills agent sync <agent-id> --skill github-pr-workflow --mode add --company-id <company-id>
 ```
 
 ## Approval Commands
 
 ```sh
 # List approvals
-pnpm paperclipai approval list [--status pending]
+pnpm exec paperclipai approval list [--status pending]
 
 # Get approval
-pnpm paperclipai approval get <approval-id>
+pnpm exec paperclipai approval get <approval-id>
 
 # Create approval
-pnpm paperclipai approval create --type hire_agent --payload '{"name":"..."}' [--issue-ids <id1,id2>]
+pnpm exec paperclipai approval create --type hire_agent --payload '{"name":"..."}' [--issue-ids <id1,id2>]
 
 # Approve
-pnpm paperclipai approval approve <approval-id> [--decision-note "..."]
+pnpm exec paperclipai approval approve <approval-id> [--decision-note "..."]
 
 # Reject
-pnpm paperclipai approval reject <approval-id> [--decision-note "..."]
+pnpm exec paperclipai approval reject <approval-id> [--decision-note "..."]
 
 # Request revision
-pnpm paperclipai approval request-revision <approval-id> [--decision-note "..."]
+pnpm exec paperclipai approval request-revision <approval-id> [--decision-note "..."]
 
 # Resubmit
-pnpm paperclipai approval resubmit <approval-id> [--payload '{"..."}']
+pnpm exec paperclipai approval resubmit <approval-id> [--payload '{"..."}']
 
 # Comment
-pnpm paperclipai approval comment <approval-id> --body "..."
+pnpm exec paperclipai approval comment <approval-id> --body "..."
 ```
 
 ## Activity Commands
 
 ```sh
-pnpm paperclipai activity list [--agent-id <id>] [--entity-type issue] [--entity-id <id>]
+pnpm exec paperclipai activity list [--agent-id <id>] [--entity-type issue] [--entity-id <id>]
 ```
 
 ## Dashboard
 
 ```sh
-pnpm paperclipai dashboard get
+pnpm exec 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 '{...}'
+pnpm exec paperclipai instance settings:general
+pnpm exec paperclipai instance settings:general:update --payload-json '{...}'
+pnpm exec paperclipai instance settings:experimental
+pnpm exec 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.
@@ -148,5 +148,5 @@ Experimental features are opt-in and are provided without compatibility guarante
 ## Heartbeat
 
 ```sh
-pnpm paperclipai heartbeat run --agent-id <agent-id> [--api-base http://localhost:3100]
+pnpm exec paperclipai heartbeat run --agent-id <agent-id> [--api-base http://localhost:3100]
 ```
diff --git a/docs/cli/overview.md b/docs/cli/overview.md
index f160832b8f..e580d5d4ba 100644
--- a/docs/cli/overview.md
+++ b/docs/cli/overview.md
@@ -38,7 +38,7 @@ Store defaults to avoid repeating flags:
 
 ```sh
 # Set defaults
-pnpm paperclipai context set --api-base http://localhost:3100 --company-id <id>
+pnpm exec paperclipai context set --api-base http://localhost:3100 --company-id <id>
 
 # View current context
 pnpm paperclipai context show
@@ -53,18 +53,18 @@ pnpm paperclipai context use default
 To avoid storing secrets in context, use an env var:
 
 ```sh
-pnpm paperclipai context set --api-key-env-var-name PAPERCLIP_API_KEY
+pnpm exec paperclipai context set --api-key-env-var-name PAPERCLIP_API_KEY
 export PAPERCLIP_API_KEY=...
 ```
 
 Secret operations are available under `paperclipai secrets`:
 
 ```sh
-pnpm paperclipai secrets declarations --company-id <company-id> --kind secret
-pnpm paperclipai secrets create --company-id <company-id> --name anthropic-api-key --value-env ANTHROPIC_API_KEY
-pnpm paperclipai secrets link --company-id <company-id> --name prod-stripe-key --provider aws_secrets_manager --external-ref <provider-ref>
-pnpm paperclipai secrets doctor --company-id <company-id>
-pnpm paperclipai secrets migrate-inline-env --company-id <company-id> --apply
+pnpm exec paperclipai secrets declarations --company-id <company-id> --kind secret
+pnpm exec paperclipai secrets create --company-id <company-id> --name anthropic-api-key --value-env ANTHROPIC_API_KEY
+pnpm exec paperclipai secrets link --company-id <company-id> --name prod-stripe-key --provider aws_secrets_manager --external-ref <provider-ref>
+pnpm exec paperclipai secrets doctor --company-id <company-id>
+pnpm exec paperclipai secrets migrate-inline-env --company-id <company-id> --apply
 ```
 
 Context is stored at `~/.paperclip/context.json`.
diff --git a/docs/cli/setup-commands.md b/docs/cli/setup-commands.md
index f6284aba01..bf0dfca636 100644
--- a/docs/cli/setup-commands.md
+++ b/docs/cli/setup-commands.md
@@ -104,7 +104,7 @@ This now includes bind-oriented deployment settings such as `PAPERCLIP_BIND` and
 Allow a private hostname for authenticated/private mode:
 
 ```sh
-pnpm paperclipai allowed-hostname my-tailscale-host
+pnpm exec paperclipai allowed-hostname my-tailscale-host
 ```
 
 ## Local Storage Paths
diff --git a/docs/deploy/deployment-modes.md b/docs/deploy/deployment-modes.md
index 7d5e6032f6..b346d7f462 100644
--- a/docs/deploy/deployment-modes.md
+++ b/docs/deploy/deployment-modes.md
@@ -42,7 +42,7 @@ pnpm paperclipai onboard
 Allow custom Tailscale hostnames:
 
 ```sh
-pnpm paperclipai allowed-hostname my-machine
+pnpm exec paperclipai allowed-hostname my-machine
 ```
 
 ### `authenticated` + `public`
diff --git a/docs/deploy/local-development.md b/docs/deploy/local-development.md
index 950b572e03..e8c257601b 100644
--- a/docs/deploy/local-development.md
+++ b/docs/deploy/local-development.md
@@ -64,7 +64,7 @@ pnpm dev --authenticated-private
 Allow additional private hostnames:
 
 ```sh
-pnpm paperclipai allowed-hostname dotta-macbook-pro
+pnpm exec paperclipai allowed-hostname dotta-macbook-pro
 ```
 
 For full setup and troubleshooting, see [Tailscale Private Access](/deploy/tailscale-private-access).
diff --git a/docs/deploy/secrets.md b/docs/deploy/secrets.md
index e557086ebf..7fdb3f0c16 100644
--- a/docs/deploy/secrets.md
+++ b/docs/deploy/secrets.md
@@ -203,7 +203,7 @@ Validate secrets config:
 
 ```sh
 pnpm paperclipai doctor
-pnpm paperclipai secrets doctor --company-id <company-id>
+pnpm exec paperclipai secrets doctor --company-id <company-id>
 ```
 
 ### Environment Overrides
@@ -475,8 +475,8 @@ store.
 If you have existing agents with inline API keys in their config, migrate them to encrypted secret refs:
 
 ```sh
-pnpm paperclipai secrets migrate-inline-env --company-id <company-id>
-pnpm paperclipai secrets migrate-inline-env --company-id <company-id> --apply
+pnpm exec paperclipai secrets migrate-inline-env --company-id <company-id>
+pnpm exec paperclipai secrets migrate-inline-env --company-id <company-id> --apply
 
 # low-level script for direct database maintenance
 pnpm secrets:migrate-inline-env         # dry run
@@ -493,7 +493,7 @@ Company exports include only environment declarations. They do not include
 secret IDs, provider references, encrypted material, or plaintext values.
 
 ```sh
-pnpm paperclipai secrets declarations --company-id <company-id> --kind secret
+pnpm exec paperclipai secrets declarations --company-id <company-id> --kind secret
 ```
 
 Before importing a package into another instance, use those declarations to
diff --git a/docs/deploy/tailscale-private-access.md b/docs/deploy/tailscale-private-access.md
index bb40fa305a..3a86f9f28c 100644
--- a/docs/deploy/tailscale-private-access.md
+++ b/docs/deploy/tailscale-private-access.md
@@ -58,7 +58,7 @@ http://my-macbook.tailnet.ts.net:3100
 If you access Paperclip with a custom private hostname, add it to the allowlist:
 
 ```sh
-pnpm paperclipai allowed-hostname my-macbook.tailnet.ts.net
+pnpm exec paperclipai allowed-hostname my-macbook.tailnet.ts.net
 ```
 
 ## 5. Verify the server is reachable
diff --git a/docs/feedback-voting.md b/docs/feedback-voting.md
index 41b17201c8..4c3a56c047 100644
--- a/docs/feedback-voting.md
+++ b/docs/feedback-voting.md
@@ -36,7 +36,7 @@ Shows a color-coded summary: vote counts, per-trace details with reasons, and ex
 paperclipai feedback report
 
 # Point to a different server or company
-pnpm paperclipai feedback report --api-base http://127.0.0.1:3000 --company-id <company-id>
+pnpm exec paperclipai feedback report --api-base http://127.0.0.1:3000 --company-id <company-id>
 
 # Include raw payload dumps in the report
 pnpm paperclipai feedback report --payloads
@@ -112,7 +112,7 @@ Exports are full by default. `traces/` keeps the Paperclip envelope, while `full
 
 ```bash
 # Custom server and output directory
-pnpm paperclipai feedback export --api-base http://127.0.0.1:3000 --company-id <company-id> --out ./my-export
+pnpm exec paperclipai feedback export --api-base http://127.0.0.1:3000 --company-id <company-id> --out ./my-export
 ```
 
 ### Reading an exported trace
diff --git a/docs/guides/board-operator/experimental-features.md b/docs/guides/board-operator/experimental-features.md
index 20b4631d54..f6ebcf84fe 100644
--- a/docs/guides/board-operator/experimental-features.md
+++ b/docs/guides/board-operator/experimental-features.md
@@ -23,7 +23,7 @@ The CLI exposes the same surface:
 
 ```sh
 pnpm paperclipai instance settings:experimental
-pnpm paperclipai instance settings:experimental:update --payload-json '{...}'
+pnpm exec paperclipai instance settings:experimental:update --payload-json '{...}'
 ```
 
 Those commands change the same opt-in settings that the UI manages.
diff --git a/docs/guides/openclaw-docker-setup.md b/docs/guides/openclaw-docker-setup.md
index bf8d149690..c91fb722ba 100644
--- a/docs/guides/openclaw-docker-setup.md
+++ b/docs/guides/openclaw-docker-setup.md
@@ -82,7 +82,7 @@ PAPERCLIP_COOKIE="your_session_cookie=..." pnpm smoke:openclaw-join
 - If Paperclip rejects the container-visible host with a hostname error, allow it from host:
 
 ```bash
-pnpm paperclipai allowed-hostname host.docker.internal
+pnpm exec paperclipai allowed-hostname host.docker.internal
 ```
 
 Then restart Paperclip and rerun the smoke script.
@@ -90,7 +90,7 @@ Then restart Paperclip and rerun the smoke script.
 - Authenticated/private mode: ensure hostnames are in the allowed list when required:
 
 ```bash
-pnpm paperclipai allowed-hostname <host>
+pnpm exec paperclipai allowed-hostname <host>
 ```
 
 ## Prerequisites
diff --git a/server/src/__tests__/cli-invocation-safety.test.ts b/server/src/__tests__/cli-invocation-safety.test.ts
new file mode 100644
index 0000000000..0b05feab47
--- /dev/null
+++ b/server/src/__tests__/cli-invocation-safety.test.ts
@@ -0,0 +1,345 @@
+import { readdirSync, readFileSync } from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { describe, expect, it } from "vitest";
+import { generateReadme } from "../services/company-export-readme.js";
+
+// The Paperclip CLI is unsafe when an operator or agent runs it through
+// `pnpm paperclipai <sub> <arg>` with a content-bearing argument. `pnpm` treats
+// `paperclipai` as a `package.json` script and wraps the argument in a
+// double-quoted `/bin/sh` string. The shell then runs command substitution (a
+// backtick pair or `$( )`) and variable expansion (`$NAME`) before the CLI
+// starts. `pnpm exec paperclipai` runs the installed binary directly. It passes
+// the argument as an inert argv value and does not run a shell. The safe form
+// and the unsafe form differ only by the `exec` keyword.
+//
+// This guard has two parts. First, it asserts that the runtime surfaces which
+// build a CLI instruction from a non-fixed value emit the safe `pnpm exec` form.
+// Second, it scans the guidance surfaces across the repository for any
+// content-bearing `pnpm paperclipai` example that returned to the docs.
+
+const here = path.dirname(fileURLToPath(import.meta.url));
+const repoRoot = path.resolve(here, "../../..");
+
+function read(relPath: string): string {
+  return readFileSync(path.join(repoRoot, relPath), "utf8");
+}
+
+// ── Content-bearing detection ─────────────────────────────────────────────
+//
+// A `pnpm paperclipai` line is content-bearing when it carries an argument that
+// an agent or operator can fill from untrusted or semi-trusted content: an
+// issue body, a comment, Markdown, a pasted snippet, model output, a hostname
+// from a request header, an import URL, an identifier, or a secret reference.
+
+// Flags that carry free text, an identifier, a payload, a file, or a secret.
+const CONTENT_FLAGS = [
+  "--body",
+  "--body-file",
+  "--title",
+  "--comment",
+  "--message",
+  "--description",
+  "--reason",
+  "--goal",
+  "--alt",
+  "--color",
+  "--content",
+  "--content-file",
+  "--summary",
+  "--note",
+  "--text",
+  "--name",
+  "--slug",
+  "--payload",
+  "--payload-json",
+  "--env-json",
+  "--company-id",
+  "--agent-id",
+  "--claim-secret",
+  "--api-key-env-var-name",
+  "--out",
+  "--file",
+];
+
+// Subcommands whose value is a hostname or an import source. A request header or
+// an external URL can supply that value, so it is never fixed.
+const CONTENT_SUBCOMMANDS = ["allowed-hostname", "company import"];
+
+// Placeholders that name an untrusted value type. A bare local placeholder such
+// as `<name>` or `<plugin-id>` on a local lifecycle command is not listed here.
+const UNTRUSTED_PLACEHOLDERS = [
+  "<token>",
+  "<secret>",
+  "<request-id>",
+  "this-github-url-or-folder",
+];
+
+// A note or warning line names the unsafe form on purpose. Skip it so the
+// security note itself does not trip the scan.
+function isNoteLine(line: string): boolean {
+  const lower = line.toLowerCase();
+  return (
+    line.includes("pnpm exec paperclipai") ||
+    line.includes("npx paperclipai") ||
+    lower.includes("do not use") ||
+    lower.includes("acceptable only")
+  );
+}
+
+function isContentBearing(line: string): boolean {
+  const commandStart = line.indexOf("pnpm paperclipai");
+  if (commandStart < 0) return false;
+  if (isNoteLine(line)) return false;
+  // Inspect only the command tail. Wrapping code before the command, such as a
+  // `${pc.dim(...)}` template call in TypeScript, is not part of the argument.
+  const command = line.slice(commandStart);
+  if (command.includes("${")) return true;
+  if (command.includes("url-or-folder>") || command.toLowerCase().includes("<url")) return true;
+  if (UNTRUSTED_PLACEHOLDERS.some((token) => command.includes(token))) return true;
+  if (CONTENT_SUBCOMMANDS.some((sub) => command.includes(sub))) return true;
+  return CONTENT_FLAGS.some(
+    (flag) => command.includes(`${flag} `) || command.includes(`${flag}=`),
+  );
+}
+
+// ── Repository walk ───────────────────────────────────────────────────────
+//
+// The scan covers guidance the reader follows now: documentation, skills, and
+// the runtime source that emits CLI instructions. It skips historical records
+// and internal automation, because a reader does not copy a command from them:
+// `doc/logs` holds past verification logs, `doc/plans` holds dated design
+// plans, and `scripts` holds trusted automation with fixed arguments. It skips
+// test files, because a test names the unsafe form to assert against it.
+
+const SKIP_DIRS = new Set([
+  "node_modules",
+  ".git",
+  "dist",
+  "build",
+  ".next",
+  "coverage",
+  ".paperclip",
+  "tmp",
+]);
+
+const SKIP_PATH_PREFIXES = ["doc/logs/", "doc/plans/", "scripts/"];
+
+const SCAN_EXTENSIONS = new Set([
+  ".md",
+  ".mdx",
+  ".ts",
+  ".tsx",
+  ".js",
+  ".jsx",
+  ".sh",
+  ".json",
+]);
+
+function isTestFile(relPath: string): boolean {
+  return (
+    relPath.includes("__tests__/") ||
+    /\.(test|spec)\.[tj]sx?$/.test(relPath)
+  );
+}
+
+function listGuidanceFiles(): string[] {
+  const found: string[] = [];
+
+  function walk(absDir: string, relDir: string): void {
+    for (const entry of readdirSync(absDir, { withFileTypes: true })) {
+      if (entry.isSymbolicLink()) continue;
+      const relPath = relDir ? `${relDir}/${entry.name}` : entry.name;
+      if (entry.isDirectory()) {
+        if (SKIP_DIRS.has(entry.name)) continue;
+        walk(path.join(absDir, entry.name), relPath);
+        continue;
+      }
+      if (!SCAN_EXTENSIONS.has(path.extname(entry.name))) continue;
+      if (isTestFile(relPath)) continue;
+      if (SKIP_PATH_PREFIXES.some((prefix) => relPath.startsWith(prefix))) continue;
+      found.push(relPath);
+    }
+  }
+
+  walk(repoRoot, "");
+  return found;
+}
+
+// ── Backslash line continuation ───────────────────────────────────────────
+//
+// A shell reads a backslash at the end of a line as a line join. So one
+// command can spread its content-bearing arguments across many physical
+// lines. The scan must see the whole command, not one physical line. If it
+// checks each physical line alone, a `pnpm paperclipai` command whose unsafe
+// argument sits on a later line passes undetected.
+//
+// `toLogicalLines` joins each backslash-continued physical line to the next
+// one. It returns the joined text and the line number of the first physical
+// line, so an offender report still points to the start of the command.
+
+interface LogicalLine {
+  text: string;
+  lineNumber: number;
+}
+
+function toLogicalLines(source: string): LogicalLine[] {
+  const physicalLines = source.split("\n");
+  const logicalLines: LogicalLine[] = [];
+  let buffer: string | null = null;
+  let startLine = 0;
+  physicalLines.forEach((physicalLine, index) => {
+    const continues = /\\\s*$/.test(physicalLine);
+    const body = physicalLine.replace(/\\\s*$/, "");
+    if (buffer === null) {
+      startLine = index + 1;
+      buffer = body;
+    } else {
+      buffer += body;
+    }
+    if (!continues) {
+      logicalLines.push({ text: buffer, lineNumber: startLine });
+      buffer = null;
+    }
+  });
+  if (buffer !== null) {
+    logicalLines.push({ text: buffer, lineNumber: startLine });
+  }
+  return logicalLines;
+}
+
+function scanText(relPath: string, source: string): string[] {
+  const offenders: string[] = [];
+  for (const { text, lineNumber } of toLogicalLines(source)) {
+    if (isContentBearing(text)) {
+      offenders.push(`${relPath}:${lineNumber}: ${text.trim()}`);
+    }
+  }
+  return offenders;
+}
+
+function scanForOffenders(): string[] {
+  const offenders: string[] = [];
+  for (const relPath of listGuidanceFiles()) {
+    offenders.push(...scanText(relPath, read(relPath)));
+  }
+  return offenders;
+}
+
+describe("paperclipai CLI invocation safety", () => {
+  it("keeps content-bearing pnpm paperclipai examples out of every guidance surface", () => {
+    const offenders = scanForOffenders();
+    expect(
+      offenders,
+      `Use \`pnpm exec paperclipai\` for content-bearing arguments:\n${offenders.join("\n")}`,
+    ).toEqual([]);
+  });
+
+  // ── Direct assertions on the runtime-generated instruction surfaces ──────
+
+  it("emits a static, non-interpolated safe form from the private-hostname guard messages", () => {
+    const source = read("server/src/middleware/private-hostname-guard.ts");
+    // The blocked-host and missing-host messages must never interpolate the
+    // request Host header into the guidance command. An operator or an agent
+    // can paste the guidance into a shell, and that outer shell evaluates a
+    // metacharacter span in the host before any CLI receives argv. `pnpm exec`
+    // does not stop the outer shell. Emit a static `<host>` placeholder only.
+    expect(source).toContain("run pnpm exec paperclipai allowed-hostname <host>");
+    expect(source).not.toContain("allowed-hostname ${hostname}");
+    expect(source).not.toContain("pnpm paperclipai allowed-hostname");
+  });
+
+  it("emits a static, non-interpolated safe form from the onboarding access diagnostics", () => {
+    const source = read("server/src/routes/access.ts");
+    expect(source).not.toMatch(/pnpm paperclipai allowed-hostname/);
+    expect(source).toContain("pnpm exec paperclipai allowed-hostname <host>");
+    // The onboarding host comes from the request base URL, so a requester
+    // controls it. The emitted command must carry a static `<host>` placeholder
+    // and never interpolate that value.
+    expect(source).not.toMatch(/allowed-hostname \$\{/);
+  });
+
+  it("emits the safe form from the agent onboarding prompt", () => {
+    const source = read("ui/src/lib/agent-onboarding-prompt.ts");
+    expect(source).not.toContain("pnpm paperclipai allowed-hostname");
+    expect(source).toContain("pnpm exec paperclipai allowed-hostname <host>");
+  });
+
+  it("emits the safe form in the generated company-export README", () => {
+    const readme = generateReadme(
+      { agents: [], projects: [], skills: [], issues: [] } as never,
+      { companyName: "Acme", companyDescription: null },
+    );
+    expect(readme).toContain("pnpm exec paperclipai company import this-github-url-or-folder");
+    expect(readme).not.toContain("pnpm paperclipai company import");
+  });
+
+  it("emits the safe form in the company-export preview builder", () => {
+    const source = read("ui/src/pages/CompanyExport.tsx");
+    expect(source).not.toContain("pnpm paperclipai company import");
+    expect(source).toContain("pnpm exec paperclipai company import");
+  });
+
+  // ── The safe-invocation note ─────────────────────────────────────────────
+
+  it("documents the safe form in doc/CLI.md", () => {
+    const cli = read("doc/CLI.md");
+    expect(cli).toContain("Security: safe invocation for content-bearing arguments");
+    expect(cli).toContain("pnpm exec paperclipai");
+    expect(cli).toContain("inert `argv`");
+  });
+
+  it("documents the safe form in the agent-facing skill", () => {
+    const skill = read("skills/paperclip/SKILL.md");
+    expect(skill).toContain("CLI safety");
+    expect(skill).toContain("pnpm exec paperclipai");
+    expect(skill).toContain("Do not use `pnpm paperclipai`");
+  });
+
+  // ── Backslash line continuation ──────────────────────────────────────────
+
+  it("flags a content-bearing pnpm paperclipai command split across continued lines", () => {
+    const source = [
+      "```sh",
+      "pnpm paperclipai issue create \\",
+      '  --company-id <company-id> \\',
+      '  --title "$(cat /etc/passwd)"',
+      "```",
+    ].join("\n");
+    const offenders = scanText("doc/EXAMPLE.md", source);
+    expect(offenders).toHaveLength(1);
+    // The report points to the first physical line of the command.
+    expect(offenders[0]).toContain("doc/EXAMPLE.md:2:");
+    expect(offenders[0]).toContain("--title");
+  });
+
+  it("flags a continued command whose only content-bearing flag sits on the last line", () => {
+    const source = [
+      "pnpm paperclipai worktree init \\",
+      "  --force \\",
+      "  --name PAP-000-example",
+    ].join("\n");
+    const offenders = scanText("doc/EXAMPLE.md", source);
+    expect(offenders).toHaveLength(1);
+    expect(offenders[0]).toContain("doc/EXAMPLE.md:1:");
+    expect(offenders[0]).toContain("--name");
+  });
+
+  it("does not flag a continued npx paperclipai command", () => {
+    const source = [
+      "npx paperclipai issue create \\",
+      "  --company-id <company-id> \\",
+      '  --title "Investigate checkout conflict"',
+    ].join("\n");
+    expect(scanText("doc/EXAMPLE.md", source)).toEqual([]);
+  });
+
+  it("does not flag a continued pnpm paperclipai command without content-bearing arguments", () => {
+    const source = [
+      "pnpm paperclipai worktree reseed \\",
+      "  --from current \\",
+      "  --seed-mode full",
+    ].join("\n");
+    expect(scanText("doc/EXAMPLE.md", source)).toEqual([]);
+  });
+});
diff --git a/server/src/__tests__/private-hostname-guard.test.ts b/server/src/__tests__/private-hostname-guard.test.ts
index 96d7aeb9a4..ce280b5c44 100644
--- a/server/src/__tests__/private-hostname-guard.test.ts
+++ b/server/src/__tests__/private-hostname-guard.test.ts
@@ -42,14 +42,17 @@ describe("privateHostnameGuard", () => {
     expect(res.status).toBe(200);
   });
 
-  it("blocks unknown hostnames with remediation command", async () => {
+  it("blocks unknown hostnames with a static remediation command", async () => {
     const app = createApp({ enabled: true, allowedHostnames: ["some-other-host"] });
     const res = await request(app).get("/api/health").set("Host", `${unknownHostname}:3100`);
     expect(res.status).toBe(403);
-    expect(res.body?.error).toContain(`please run pnpm paperclipai allowed-hostname ${unknownHostname}`);
+    // The remediation command carries a static `<host>` placeholder. It never
+    // interpolates the request Host header into the command.
+    expect(res.body?.error).toContain("run pnpm exec paperclipai allowed-hostname <host>");
+    expect(res.body?.error).not.toContain(unknownHostname);
   });
 
-  it("blocks unknown hostnames on page routes with plain-text remediation command", async () => {
+  it("blocks unknown hostnames on page routes with a static plain-text remediation command", async () => {
     const middleware = privateHostnameGuard({
       enabled: true,
       allowedHostnames: ["some-other-host"],
@@ -73,7 +76,24 @@ describe("privateHostnameGuard", () => {
     expect(next).not.toHaveBeenCalled();
     expect(res.status).toHaveBeenCalledWith(403);
     expect(res.send).toHaveBeenCalledWith(
-      expect.stringContaining(`please run pnpm paperclipai allowed-hostname ${unknownHostname}`),
+      expect.stringContaining("run pnpm exec paperclipai allowed-hostname <host>"),
     );
+    expect(res.send).not.toHaveBeenCalledWith(expect.stringContaining(unknownHostname));
   }, 20_000);
+
+  it("does not reflect a hostile Host header into the remediation command", async () => {
+    // An unauthenticated requester can send an invalid Host header that holds
+    // shell metacharacters. `extractHostname` falls back to the raw header when
+    // URL parsing fails. The 403 guidance must not echo that value, so an
+    // operator or an agent cannot paste an attacker-controlled span into a
+    // shell. Use a harmless, nonexistent command name inside the span.
+    const hostileHost = "evil$(echo marker)host";
+    const app = createApp({ enabled: true, allowedHostnames: ["some-other-host"] });
+    const res = await request(app).get("/api/health").set("Host", hostileHost);
+    expect(res.status).toBe(403);
+    expect(res.body?.error).toContain("run pnpm exec paperclipai allowed-hostname <host>");
+    expect(res.body?.error).not.toContain("evil");
+    expect(res.body?.error).not.toContain("$(");
+    expect(res.body?.error).not.toContain("marker");
+  });
 });
diff --git a/server/src/adapters/hermes-gateway-doc.ts b/server/src/adapters/hermes-gateway-doc.ts
index 75538fce9e..fb32c9d565 100644
--- a/server/src/adapters/hermes-gateway-doc.ts
+++ b/server/src/adapters/hermes-gateway-doc.ts
@@ -47,7 +47,7 @@ Network examples:
 - Local loopback on one host: agentDefaultsPayload.apiBaseUrl = "http://127.0.0.1:8642"; agentDefaultsPayload.paperclipApiUrl = "http://127.0.0.1:3100".
 - Local dashboard root or chat URL on one host: agentDefaultsPayload.apiBaseUrl = "http://127.0.0.1:9119" or "http://127.0.0.1:9119/chat"; Paperclip maps it to "http://127.0.0.1:9119/api".
 - LAN/private network: agentDefaultsPayload.apiBaseUrl = "http://192.168.1.25:8642"; agentDefaultsPayload.paperclipApiUrl = "http://192.168.1.10:3100". Use private IPs or hostnames reachable from both machines.
-- Private overlay: agentDefaultsPayload.apiBaseUrl = "http://hermes-host.tailnet-name.ts.net:8642"; agentDefaultsPayload.paperclipApiUrl = "http://paperclip-host.tailnet-name.ts.net:3100". Add the Paperclip hostname with pnpm paperclipai allowed-hostname <host> when authenticated/private mode requires it.
+- Private overlay: agentDefaultsPayload.apiBaseUrl = "http://hermes-host.tailnet-name.ts.net:8642"; agentDefaultsPayload.paperclipApiUrl = "http://paperclip-host.tailnet-name.ts.net:3100". Add the Paperclip hostname with pnpm exec paperclipai allowed-hostname <host> when authenticated/private mode requires it.
 - Docker: if Hermes runs on the host and Paperclip runs in Docker, use agentDefaultsPayload.apiBaseUrl = "http://host.docker.internal:8642". If Hermes runs in another container, use the Compose service DNS name such as "http://hermes:8642".
 - Reverse proxy/TLS: publish Hermes behind HTTPS and set agentDefaultsPayload.apiBaseUrl = "https://hermes-gateway.example"; set agentDefaultsPayload.paperclipApiUrl = "https://paperclip.example". Keep API_SERVER_KEY required at the origin or proxy.
 
diff --git a/server/src/middleware/private-hostname-guard.ts b/server/src/middleware/private-hostname-guard.ts
index a5d743dcca..f64d92c62c 100644
--- a/server/src/middleware/private-hostname-guard.ts
+++ b/server/src/middleware/private-hostname-guard.ts
@@ -42,12 +42,16 @@ export function resolvePrivateHostnameAllowSet(opts: { allowedHostnames: string[
   return allowSet;
 }
 
-function blockedHostnameMessage(hostname: string): string {
-  return (
-    `Hostname '${hostname}' is not allowed for this Paperclip instance. ` +
-    `If you want to allow this hostname, please run pnpm paperclipai allowed-hostname ${hostname}`
-  );
-}
+// The hostname comes from the request Host header, so an unauthenticated
+// requester controls it. Never put that value into the guidance command. An
+// operator or an agent can paste the guidance into a shell, and that outer
+// shell evaluates a backtick, `$( )`, or `$NAME` span in the host before any
+// CLI receives argv. A direct-exec form such as `pnpm exec` does not stop the
+// outer shell. Emit a static `<host>` placeholder and do not echo the raw request
+// value. The operator supplies the real hostname.
+const BLOCKED_HOSTNAME_MESSAGE =
+  "This hostname is not allowed for this Paperclip instance. " +
+  "If you want to allow a hostname, run pnpm exec paperclipai allowed-hostname <host>.";
 
 export function privateHostnameGuard(opts: {
   enabled: boolean;
@@ -68,7 +72,7 @@ export function privateHostnameGuard(opts: {
     const wantsJson = req.path.startsWith("/api") || req.accepts(["json", "html", "text"]) === "json";
 
     if (!hostname) {
-      const error = "Missing Host header. If you want to allow a hostname, run pnpm paperclipai allowed-hostname <host>.";
+      const error = "Missing Host header. If you want to allow a hostname, run pnpm exec paperclipai allowed-hostname <host>.";
       if (wantsJson) {
         res.status(403).json({ error });
       } else {
@@ -82,7 +86,7 @@ export function privateHostnameGuard(opts: {
       return;
     }
 
-    const error = blockedHostnameMessage(hostname);
+    const error = BLOCKED_HOSTNAME_MESSAGE;
     if (wantsJson) {
       res.status(403).json({ error });
     } else {
diff --git a/server/src/routes/access.ts b/server/src/routes/access.ts
index ea1ce6a183..5b29d2dac0 100644
--- a/server/src/routes/access.ts
+++ b/server/src/routes/access.ts
@@ -1642,7 +1642,13 @@ function buildOnboardingDiscoveryDiagnostics(input: {
       code: "openclaw_onboarding_private_host_not_allowed",
       level: "warn",
       message: `Onboarding host "${apiHost}" is not in allowed hostnames for authenticated/private mode.`,
-      hint: `Run pnpm paperclipai allowed-hostname ${apiHost}`
+      // `apiHost` comes from the request base URL, so a requester controls it.
+      // Never put that value into the guidance command. An operator or an agent
+      // can paste the command into a shell, and that outer shell evaluates a
+      // metacharacter span in the host before any CLI receives argv. A
+      // direct-exec form such as `pnpm exec` does not stop the outer shell. Emit
+      // a static `<host>` placeholder and keep the raw host in the message only.
+      hint: `Run pnpm exec paperclipai allowed-hostname <host>`
     });
   }
 
@@ -1776,7 +1782,7 @@ function buildInviteOnboardingManifest(
         guidance:
           opts.deploymentMode === "authenticated" &&
           opts.deploymentExposure === "private"
-            ? "If OpenClaw runs on another machine, ensure the Paperclip hostname is reachable and allowed via `pnpm paperclipai allowed-hostname <host>`."
+            ? "If OpenClaw runs on another machine, ensure the Paperclip hostname is reachable and allowed via `pnpm exec paperclipai allowed-hostname <host>`."
             : "Ensure OpenClaw can reach this Paperclip API base URL for invite, claim, and skill bootstrap calls."
       },
       textInstructions: {
@@ -1999,7 +2005,7 @@ export function buildInviteOnboardingTextDocument(
 
       If none are reachable: ask your human operator for a reachable hostname/address and help them update network configuration.
       For authenticated/private mode, they may need:
-      - pnpm paperclipai allowed-hostname <host>
+      - pnpm exec paperclipai allowed-hostname <host>
       - then restart Paperclip and retry onboarding.
     `);
   }
diff --git a/server/src/services/company-export-readme.ts b/server/src/services/company-export-readme.ts
index df8766e18b..f352828886 100644
--- a/server/src/services/company-export-readme.ts
+++ b/server/src/services/company-export-readme.ts
@@ -157,7 +157,7 @@ export function generateReadme(
   lines.push("## Getting Started");
   lines.push("");
   lines.push("```bash");
-  lines.push("pnpm paperclipai company import this-github-url-or-folder");
+  lines.push("pnpm exec paperclipai company import this-github-url-or-folder");
   lines.push("```");
   lines.push("");
   lines.push("See [Paperclip](https://paperclip.ing) for more information.");
diff --git a/skills/paperclip/SKILL.md b/skills/paperclip/SKILL.md
index cf1a97cd5f..3988713700 100644
--- a/skills/paperclip/SKILL.md
+++ b/skills/paperclip/SKILL.md
@@ -23,6 +23,8 @@ Some adapters also inject `PAPERCLIP_WAKE_PAYLOAD_JSON` on comment-driven wakes.
 
 Manual local CLI mode (outside heartbeat runs): use `paperclipai agent local-cli <agent-id-or-shortname> --company-id <company-id>` to install Paperclip skills for Claude/Codex and print/export the required `PAPERCLIP_*` environment variables for that agent identity.
 
+**CLI safety — use `pnpm exec paperclipai` for content-bearing arguments.** When you run the Paperclip CLI, use `pnpm exec paperclipai` for any argument that can hold untrusted content. Untrusted content includes issue text, comment bodies, Markdown, pasted snippets, and model output. `pnpm exec` runs the installed binary directly and passes the argument as an inert `argv` value. Do not use `pnpm paperclipai` for such an argument. The safe form and the unsafe form differ only by the `exec` keyword, so read the command with care. `pnpm paperclipai` is a `package.json` script; `pnpm` runs the argument through `/bin/sh` first. The shell then interprets a backtick pair, `$( )`, `$NAME`, and `; | & < >` before the CLI starts. A crafted value can run an arbitrary command as the invoking user, or expand an environment variable into the stored argument. `npx paperclipai` is also injection-safe; use it when no local install is present. See `doc/CLI.md` for the full safe/unsafe matrix.
+
 **Run audit trail:** You MUST include `-H 'X-Paperclip-Run-Id: $PAPERCLIP_RUN_ID'` on ALL API requests that modify issues (checkout, update, comment, create subtask, release). This links your actions to the current heartbeat run for traceability.
 
 ## The Heartbeat Procedure
diff --git a/ui/src/lib/agent-onboarding-prompt.ts b/ui/src/lib/agent-onboarding-prompt.ts
index 4d3f6f06fa..2bbdd5c792 100644
--- a/ui/src/lib/agent-onboarding-prompt.ts
+++ b/ui/src/lib/agent-onboarding-prompt.ts
@@ -18,13 +18,13 @@ export function buildAgentOnboardingPrompt(input: AgentOnboardingPromptInput) {
       ? `No candidate URLs are available. Ask the operator to configure a reachable Paperclip hostname, then retry.
 Suggested steps for the operator:
 - choose a hostname that resolves to the Paperclip host from your runtime
-- run: pnpm paperclipai allowed-hostname <host>
+- run: pnpm exec paperclipai allowed-hostname <host>
 - restart Paperclip
 - verify with: curl -fsS http://<host>:3100/api/health
 - regenerate this agent onboarding prompt`
       : `If none are reachable, ask the operator to add a reachable Paperclip hostname, restart, and retry.
 Suggested command for the operator:
-- pnpm paperclipai allowed-hostname <host>
+- pnpm exec paperclipai allowed-hostname <host>
 Then verify with: curl -fsS <base-url>/api/health`;
 
   const resolutionLine = resolutionTestUrl
diff --git a/ui/src/pages/CompanyExport.tsx b/ui/src/pages/CompanyExport.tsx
index 27f82642f7..365a5721bc 100644
--- a/ui/src/pages/CompanyExport.tsx
+++ b/ui/src/pages/CompanyExport.tsx
@@ -484,7 +484,7 @@ function generateReadmeFromSelection(
   lines.push("## Getting Started");
   lines.push("");
   lines.push("```bash");
-  lines.push("pnpm paperclipai company import this-github-url-or-folder");
+  lines.push("pnpm exec paperclipai company import this-github-url-or-folder");
   lines.push("```");
   lines.push("");
   lines.push("See [Paperclip](https://paperclip.ing) for more information.");