paperclip-setup

Paperclip のセットアップ

Paperclip スキルスイート用のローカルオペレーター環境を準備します。

参照資料

最初に以下をお読みください。

• パッケージに含まれる共有ドキュメント：
  • 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
• プロジェクトのドキュメントがない場合に使用する同梱テンプレート：
  • 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

ワークフロー

1. ローカルの Paperclip CLI を確認します。

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

2. paperclipai が見つからない場合は、新規インストールを案内します。

   まず、環境に npm パッケージをインストールできるか確認します。

   command -v node
   node --version
   command -v npm
   npm --version
   

   Node.js と npm がある場合は、オペレーターに CLI をグローバルインストールするよう伝えます。 paperclipai は Paperclip 公式のファーストパーティ CLI です。他のパッケージのインストールと同様に、このグローバルインストールもサプライチェーンスキャナーによって警告されます。

   npm install -g paperclipai
   

   次に、バイナリが PATH 上にあることを確認します。

   command -v paperclipai
   paperclipai --version
   

   インストールに成功しても command -v paperclipai が失敗する場合は、npm のグローバルバイナリディレクトリを確認し、PATH に追加するようオペレーターに伝えます。

   npm bin -g
   

   オペレーターの承認なしにグローバルインストールを実行しないでください。Node.js または npm がない場合は、まずオペレーターに使用しているプラットフォーム向けの Node.js をインストールしてもらい、その後セットアップを再実行してください。

3. CLI がインストールされている場合は、最初の Paperclip コマンドが失敗した時点で中止せず、セットアップを続行します。

   セットアップを段階的に進めます。

   • CLI がインストールされ、PATH 上にある
   • CLI がコンテキストを読み取れる
   • API ベースに到達できる
   • 認証が設定されている
   • 会社のコンテキストが選択されている
   • Paperclip MCP 設定がインストール済み、または意図的にスキップされている
   • 共有オペレーター向けドキュメントが存在する

   いずれかの段階で失敗した場合は、一般的なブロッカー報告ではなく、次に必要となる具体的なコマンドまたは判断を提示します。

4. 会社の情報を読み取る前に、設定済みの API ベースを確認します。

   アクティブなコンテキストを確認します。

   paperclipai context show --json
   

   API ベースが未設定、空、または到達できない既定値のみの場合は、認証や会社のコマンドを試す前に、Paperclip 環境の URL をオペレーターに尋ねます。たとえば、セットアップに必要な情報として次のように尋ねます。

   What Paperclip environment URL should this CLI use? For example: https://paperclip.example.com or http://localhost:3100.
   

   オペレーターから URL の提示を受けたら、コンテキストに書き込む前に、その URL を確認します。

   curl -fsS <api-base>/api/health
   

   到達可能な場合は、予定しているコンテキストの変更内容を提示し、承認を求めます。context set を実行する前に、既存の値を保持できるよう、現在のコンテキストを読み取ります。

   paperclipai context show --json
   

   paperclipai context set --api-base <api-base> --use
   

   オペレーターが分離したプロファイルまたは名前付きプロファイルを希望する場合は、--use の前に --profile <name> を含めます。context set はプロファイルの設定値をマージするのではなく置き換えるものとして扱います。API ベースと会社 ID の両方が判明している場合は、1 つのコマンドでまとめて設定します。

   API ベースが http://localhost:3100 の場合は、ローカルの Paperclip API が実際に稼働していることを確認します。

   curl -fsS http://localhost:3100/api/health
   

   API のヘルスチェックに失敗した場合は、インストールは完了しているものの、Paperclip API サーバーに到達できないと報告します。ローカルの Paperclip API を起動するか、別の Paperclip 環境 URL を指定するか、オペレーターに確認します。API に到達できるようになるまでは、認証の失敗として扱わないでください。

5. API に到達できるものの、認証またはコンテキストが設定されていない場合は、ログインとコンテキストの選択を案内します。

   paperclipai auth login --api-base <api-base>
   paperclipai company list --json
   paperclipai context show --json
   

   ログイン後に会社が選択されていない場合は、使用する会社をオペレーターに確認してください。会社をまたいで推測してはいけません。

6. Paperclip の認証が設定されている場合は、利用可能な会社を確認します。

   paperclipai company list --json
   

7. アクティブな会社スコープを確認します。

   会社が選択されていない場合は、使用する会社をオペレーターに確認してください。会社をまたいで推測してはいけません。

   オペレーターが会社を選択したら、会社 ID を書き込む際に API ベースを維持してください。

   paperclipai context set --api-base <api-base> --company-id <company-id> --use
   paperclipai context show --json
   

   生成されたプロファイルに apiBase と companyId の両方が含まれていることを確認します。含まれていない場合は、両方の値をまとめて設定して修復し、コンテキストを再度読み取ります。

8. Paperclip MCP の設定を確認します。

   Paperclip MCP は、CLI のフォールバックとして @bbengamin/paperclip-mcp-server を使用します。スキルの読み込みに MCP は必須ではありません。Paperclip の操作で MCP のフォールバックを使用する場合にのみ必要です。

   Codex では、現在の信頼済みプロジェクト内のプロジェクトローカルな Codex 設定をデフォルトにします。

   .codex/config.toml
   

   Claude Code では、現在の信頼済みプロジェクト内のプロジェクトローカルな Claude MCP 設定をデフォルトにします。

   .mcp.json
   

   グローバルまたはユーザーレベルの設定は、オペレーターから明示的に依頼された場合にのみ使用します。

   ~/.codex/config.toml
   

   変更を提案する前に、対象となる設定を確認します。

   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
   

   提案する Codex プロジェクトローカルの TOML：

   [mcp_servers.paperclip]
   command = "npx"
   args = ["-y", "@bbengamin/paperclip-mcp-server"]
   

   提案する Claude Code プロジェクトローカルのコマンド：

   claude mcp add paperclip -s project -- npx -y @bbengamin/paperclip-mcp-server
   

   これにより、同等の .mcp.json エントリが書き込まれます。

   {
     "mcpServers": {
       "paperclip": {
         "command": "npx",
         "args": ["-y", "@bbengamin/paperclip-mcp-server"]
       }
     }
   }
   

   オペレーターがホストローカルの明示的なオーバーライドを希望する場合は、依頼された環境変数のみを含めます。

   [mcp_servers.paperclip.env]
   PAPERCLIP_API_URL = "<api-base>"
   PAPERCLIP_COMPANY_ID = "<company-id>"
   

   アクティブな paperclipai プロファイルとボード認証にフォールバックする、トークンを含まない設定を優先します。プロジェクトローカルの設定に PAPERCLIP_API_KEY を書き込んではいけません。ベアラートークンが必要な場合は、ローカル環境変数またはユーザーレベルの設定を使うようオペレーターに依頼してください。

   MCP の設定を書き込む前に、次の項目を提示します。

   • 対象スコープ：プロジェクトローカルまたはグローバル
   • 対象パス
   • 正確な TOML テーブル、Claude コマンド、または JSON エントリ
   • paperclip MCP エントリを作成、置換、または変更せずに残すかどうか

   設定ファイルを編集する前に、明示的な承認を求めてください。書き込み後、次の項目を確認します。

   sed -n '1,220p' <target-config-path>
   claude mcp get paperclip
   npm view @bbengamin/paperclip-mcp-server version
   

   次に、Paperclip MCP ツールが表示されることを期待する前に、Codex または Claude Code を再起動するか、新しいスレッド／セッションを開始するようオペレーターに伝えてください。同じ実行中のスレッドで MCP ツールが見つからない場合でも、再起動したセッションで読み込めないことが確認されるまでは、インストール失敗と判断してはいけません。

9. 共有ドキュメントが存在することを確認します。

   必須ファイル：

   • 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

10. ドキュメントが不足している場合は、ひな形の作成を提案します。

作成または更新する正確なファイルを提示します。書き込む前に承認を求めてください。

references/project-docs/ にある同梱テンプレートを使用します。必要に応じて、不足しているディレクトリを作成します。

対象ファイルがすでに存在する場合は、黙って上書きしてはいけません。競合の概要を伝え、スキップ、手動でのマージ、または置換のいずれにするか確認してください。

11. セットアップ状況を報告します。

次の項目を含めます。

• paperclipai が見つかったか、インストール方法を案内したか
• CLI のパスとバージョン
• アクティブなプロファイル
• API ベース
• API に到達可能か、次の操作がローカル API の起動か API ベースの変更か
• 設定されている場合は会社 ID
• 認証状態、または次に必要な認証コマンド
• MCP のインストールスコープ、対象パス、再起動／新しいスレッドが必要かどうか
• 作成したドキュメント、スキップしたドキュメント、または残っている不足ドキュメント
• 未解決のセットアップに関する質問

ミューテーションルール

このスキルでは自由に読み取りできます。CLI コンテキストの変更、Paperclip レコードの作成、Paperclip MCP 設定のインストールまたは変更、Paperclip の会社スキルのインストール、共有ドキュメントの編集を行う前に、必ず確認してください。不足している共有ドキュメントを同梱テンプレートから作成する場合も、オペレーターの承認後に限り許可されます。