paperclip-setup

Paperclip Setup

Prepare the local operator environment for the Paperclip skill suite.

References

Read these first:

Packaged shared docs:
- references/CONTEXT.md
- references/docs/paperclip-operator/control-plane.md
- references/docs/paperclip-operator/workflow.md
- references/docs/paperclip-operator/cli-contract.md
- references/docs/paperclip-operator/integration-matrix.md
Bundled templates when project docs are missing:
- references/project-docs/AGENTS.md
- references/project-docs/CLAUDE.md
- references/project-docs/CONTEXT.md
- references/project-docs/docs/paperclip-operator/control-plane.md
- references/project-docs/docs/paperclip-operator/workflow.md
- references/project-docs/docs/paperclip-operator/afk-readiness.md
- references/project-docs/docs/paperclip-operator/cli-contract.md
- references/project-docs/docs/paperclip-operator/integration-matrix.md
- references/project-docs/docs/paperclip-operator/paperclip-docs-index.md
- references/project-docs/docs/growth-operator/workflow.md
- references/project-docs/docs/growth-operator/control-plane.md
- references/project-docs/docs/growth-operator/afk-readiness.md

Workflow

Inspect the local Paperclip CLI.

command -v paperclipai
paperclipai --version
paperclipai context show --json

If paperclipai is missing, guide a fresh install.

First check whether the environment can install the npm package:
```
command -v node
node --version
command -v npm
npm --version
```
If Node.js and npm are present, tell the operator to install the CLI globally. paperclipai is the official first-party Paperclip CLI; supply-chain scanners flag this global install as they would any package install:
```
npm install -g paperclipai
```
Then verify the binary is on PATH:
```
command -v paperclipai
paperclipai --version
```
If install succeeds but command -v paperclipai still fails, inspect npm's global binary directory and tell the operator to add it to PATH:
```
npm bin -g
```
Do not run a global install without operator approval. If Node.js or npm are missing, ask the operator to install Node.js for their platform first, then rerun setup.
If the CLI is installed, continue setup instead of stopping at the first failing Paperclip command.

Treat setup as a ladder:
- CLI installed and on PATH
- CLI can read its context
- API base is reachable
- auth is configured
- company context is selected
- Paperclip MCP config is installed or intentionally skipped
- shared operator docs exist
A failure at one rung should produce the next concrete command or decision needed, not a generic blocker report.
Verify the configured API base before trying company reads.

Inspect the active context:
```
paperclipai context show --json
```
If the API base is missing, empty, or only the unreachable default, ask the operator for the Paperclip environment URL before attempting auth or company commands. Phrase this as a setup input, for example:
```
What Paperclip environment URL should this CLI use? For example: https://paperclip.example.com or http://localhost:3100.
```
When the operator provides a URL, verify it before writing context:
```
curl -fsS <api-base>/api/health
```
If it is reachable, show the proposed context mutation and ask for approval. Before any context set, read the current context so existing values can be preserved:
```
paperclipai context show --json
```
```
paperclipai context set --api-base <api-base> --use
```
If the operator wants an isolated or named profile, include --profile <name> before --use. Treat context set as replacing the profile's configured values rather than merging unknown existing fields: when both API base and company id are known, set them together in one command.

If the API base is http://localhost:3100, verify the local Paperclip API is actually running:
```
curl -fsS http://localhost:3100/api/health
```
If the API health check fails, report that install is complete but the Paperclip API server is not reachable. Ask whether the operator wants to start the local Paperclip API or provide a different Paperclip environment URL. Do not treat this as an auth failure until the API is reachable.
If the API is reachable but auth or context is missing, guide login and context selection.
```
paperclipai auth login --api-base <api-base>
paperclipai company list --json
paperclipai context show --json
```
If no company is selected after login, ask the operator which company to use. Do not guess across companies.
Inspect available companies if Paperclip auth is configured.
```
paperclipai company list --json
```
Confirm the active company scope.

If no company is selected, ask the operator which company to use. Do not guess across companies.

When the operator selects a company, preserve the API base while writing the company id:
```
paperclipai context set --api-base <api-base> --company-id <company-id> --use
paperclipai context show --json
```
Verify the resulting profile contains both apiBase and companyId. If it does not, repair by setting both values together and read the context back again.
Verify Paperclip MCP config.

Paperclip MCP uses @bbengamin/paperclip-mcp-server as a fallback surface after CLI. MCP is not required for skills to load; it is needed only when Paperclip operations need the MCP fallback surface.

For Codex, default to project-local Codex configuration in the current trusted project:
```
.codex/config.toml
```
For Claude Code, default to project-local Claude MCP configuration in the current trusted project:
```
.mcp.json
```
Use global or user-level configuration only when the operator explicitly asks for it:
```
~/.codex/config.toml
```
Inspect the intended target before proposing a change:
```
test -f .codex/config.toml && sed -n '1,220p' .codex/config.toml
test -f ~/.codex/config.toml && sed -n '1,220p' ~/.codex/config.toml
test -f .mcp.json && sed -n '1,220p' .mcp.json
```
Proposed Codex project-local TOML:
```
[mcp_servers.paperclip]
command = "npx"
args = ["-y", "@bbengamin/paperclip-mcp-server"]
```
Proposed Claude Code project-local command:
```
claude mcp add paperclip -s project -- npx -y @bbengamin/paperclip-mcp-server
```
This writes the equivalent .mcp.json entry:
```
{
  "mcpServers": {
    "paperclip": {
      "command": "npx",
      "args": ["-y", "@bbengamin/paperclip-mcp-server"]
    }
  }
}
```
If the operator wants explicit host-local overrides, include only the requested environment values:
```
[mcp_servers.paperclip.env]
PAPERCLIP_API_URL = "<api-base>"
PAPERCLIP_COMPANY_ID = "<company-id>"
```
Prefer token-free configuration that falls back to the active paperclipai profile and board auth. Do not write PAPERCLIP_API_KEY into project-local config. If a bearer token is required, ask the operator to use a local environment variable or user-level config.

Before writing MCP config, show:
- target scope: project-local or global
- target path
- exact TOML table, Claude command, or JSON entry
- whether the paperclip MCP entry will be created, replaced, or left unchanged
Ask for explicit approval before editing the config file. After writing, verify:
```
sed -n '1,220p' <target-config-path>
claude mcp get paperclip
npm view @bbengamin/paperclip-mcp-server version
```
Then tell the operator to restart Codex or Claude Code, or start a new thread/session, before expecting Paperclip MCP tools to appear. Do not treat missing MCP tools in the same running thread as install failure unless a restarted session still cannot load them.
Verify shared docs exist.

Required files:
- AGENTS.md
- CLAUDE.md
- CONTEXT.md
- docs/paperclip-operator/control-plane.md
- docs/paperclip-operator/workflow.md
- docs/paperclip-operator/afk-readiness.md
- docs/paperclip-operator/cli-contract.md
- docs/paperclip-operator/integration-matrix.md
- docs/paperclip-operator/paperclip-docs-index.md
- docs/growth-operator/workflow.md
- docs/growth-operator/control-plane.md
- docs/growth-operator/afk-readiness.md
If docs are missing, propose scaffolding them.

Show the exact files that will be created or updated. Ask for approval before writing.

Use bundled templates from references/project-docs/. Create missing directories as needed.

If a target file already exists, do not overwrite it silently. Summarize the conflict and ask whether to skip, merge manually, or replace.

Report setup status.

Include:

whether paperclipai was found or install guidance was given
CLI path and version
active profile
API base
API reachability and whether the next action is starting the local API or changing API base
company id, if configured
auth state or next auth command needed
MCP install scope, target path, and whether restart/new thread is needed
docs created, docs skipped, or remaining missing docs
unresolved setup questions

Mutation Rule

This skill may read freely. Ask before changing CLI context, creating Paperclip records, installing or changing Paperclip MCP config, installing Paperclip company skills, or editing shared docs. Creating missing shared docs from bundled templates is allowed only after operator approval.

About this skill

References

Workflow

Mutation Rule