pp-everbee

EverBee — Printing Press CLI

前提条件：CLI をインストールする

このスキルは everbee-pp-cli バイナリを使用します。このスキルのコマンドを実行する前に、CLI がインストールされていることを必ず確認してください。 インストールされていない場合は、先にインストールしてください。

1. Printing Press インストーラーでインストールします。バイナリの既定のインストール先は、macOS/Linux では $HOME/.local/bin、Windows では %LOCALAPPDATA%\Programs\PrintingPress\bin です。

   npx -y @mvanhorn/printing-press-library install everbee --cli-only
   

2. 確認します：everbee-pp-cli --version
3. このスキルを実行するエージェント／ランタイムの $PATH に、表示されたインストール先ディレクトリが含まれていることを確認します。

npx によるインストールに失敗した場合（Node がない、オフラインなど）は、Go を直接インストールする方法に切り替えてください（Go 1.26.6 以降が必要です）。この方法では $GOPATH/bin（既定では $HOME/go/bin）にインストールされるため、代わりにそのディレクトリを $PATH に追加してください。

go install github.com/mvanhorn/printing-press-library/library/marketing/everbee/cmd/everbee-pp-cli@latest

インストール後に --version で「command not found」と表示される場合、ランタイムから $PATH 上のバイナリディレクトリが見えていません。確認が成功するまで、スキルのコマンドを実行しないでください。

EverBee のデータは、利用可能な Etsy リサーチシグナルの中でも最良のものですが、API は尋ねていない質問にも平然と答えます。既定の候補フィードは、シードに関係なく、順位付けされていない埋め草を返します。この CLI は、EverBee 独自の検索ボックスが呼び出すエンドポイントに問い合わせ、返されたすべての行に関連度スコア、エビデンス件数、出所を付与します。信頼度はエビデンスの網羅状況を反映するため、キーワードによる裏付けがないニッチが、自信ありげな結果として返されることはありません。1 つのシードについて根拠ある判断を得るには「research niche」を、ニッチ群全体を順位付けするには「research subniches」を、バッチ実行を信頼する前にデータ経路の意味的な妥当性を確認するには「selftest」を使用してください。

この CLI を使用する場面

Etsy の販売者やリサーチエージェントが、ニッチへの参入価値を判断し、その判断の根拠を示す必要がある場合に、この CLI を使用してください。シードを指定したキーワードや商品のリサーチ、親テーマの下にあるサブニッチの順位付け、すでにニッチにいる競合の把握、ニッチの週ごとの動向追跡に適しています。各結果にエビデンス件数、出所、誠実な信頼度が付与されること、また「selftest」によって結果のバッチを信頼する前にデータ経路の意味的な妥当性をエージェントが確認できることから、エージェントのワークフローに特に適しています。

使用しない場面

次の用途には、この CLI を使用しないでください。

• Etsy 販売者自身の出品を一覧表示したり編集したりする用途には使用しないでください。これは読み取り専用の Etsy 市場調査ツールであり、Etsy への書き込み機能はありません。
• EverBee Store（コマース／ストアフロント製品）には使用しないでください。これは別個の公式 API であり、この CLI の対象外です。
• 売上高、販売数、検索ボリュームの数値を Etsy の確定値として扱わないでください。これらは EverBee による推定値であり、リサーチシグナルとして報告してください。
• 特定のニッチについての質問に答えるために、順位付けされていない閲覧フィード（「products」と「keyword-research list」）を使用しないでください。これらはシードを無視します。「research niche」または「products search」を使用してください。

独自の機能

これらの機能は、この API 用のほかのツールでは利用できません。

根拠に基づくリサーチ

• research niche — シードキーワードから Etsy のニッチをスコアリングし、数値だけでなく、そのスコアの根拠も取得します。

  競争が少ないという主張を裏付ける必要がある場合は、生のキーワード検索ではなくこちらを使ってください。各判定には、根拠の件数、出所、そして誠実な信頼度が付属します。

  everbee-pp-cli research niche "dad shirt" --agent
  

• research subniches — 親ニッチを子ニッチに展開し、比較可能な正規化済みスコアで順位付けします。

  「X について教えて」ではなく、「X の中で最も競争の少ない領域を見つけて」というタスクで使ってください。

  everbee-pp-cli research subniches --parent dad --product apparel --exclude-svg-png --agent
  

• research competitors — ニッチの市場状況を把握します。検索結果数、価格の中央値、レビューと売上の密度、出品年齢の四分位数を取得できます。

  デザイン作業を始める前に、「競合する相手は誰で、どの程度市場に定着しているのか」という疑問に答えます。

  everbee-pp-cli research competitors "dad shirt" --agent
  

• research tags — ニッチ内で売れている出品のタグとタイトルのトークンに共通する傾向や、EverBee がトレンドデータを提供している場合は、需要が季節性か通年性かを確認できます。

  出品ページを書く前に使ってください。ニッチで共通して使われている語彙がわかります。EverBee からトレンドデータが返されない場合、季節性の判定は「不明」と報告されます。これはよくあることで、推測することはありません。

  everbee-pp-cli research tags "dad shirt" --agent
  

蓄積されるローカル状態

• research drift — ニッチを保存済みのベースラインと比較し、前回から実際に変化した点を確認します。

  繰り返しのリサーチを、互いに関連のないスクリーンショットの羅列ではなく、トレンドとして捉えられるようにします。

  everbee-pp-cli research drift "dad shirt" --agent
  

• research listing — Etsy の出品 URL または ID から、実際に把握している情報を取得します。情報が何もない場合は、その旨を明確に伝えます。

  「この出品は存在しない」と「この出品についてまだデータがない」を区別します。この2つの失敗をエージェントが決して混同してはいけません。

  everbee-pp-cli research listing 4515173344 --agent
  

エージェント向けの基盤機能

• selftest — リサーチの経路に到達できるだけでなく、実際に関連性のあるデータが返されているかを確認します。

  自動化セッションでは、まずこれを実行してください。「API が応答した」ことと「その回答に意味がある」ことの違いを見極められます。

  everbee-pp-cli selftest --agent
  

コマンドリファレンス

account — EverBee アカウントのプランとリサーチ利用枠

• everbee-pp-cli account — EverBee アカウントの現在のプラン、リサーチ利用枠、使用状況を表示します。

keyword_research — Etsy のキーワードリサーチ — 検索数、競争率、スコア、CPC、トレンド

• everbee-pp-cli keyword-research list — EverBee のデフォルトのキーワードフィードを表示します（検索前に UI に表示される内容です）。
• everbee-pp-cli keyword-research search — シードキーワードを指定して検索します。

products — Etsy の商品／出品リサーチ — 売上、収益、タグ、価格、出品タイプ、出品年齢

• everbee-pp-cli products — EverBee のデフォルトの商品フィードを表示します（検索前に UI に表示される内容です）。

shops — Etsy の競合ショップのリサーチ — 収益、売上、出品数、コンバージョン、レビュー

• everbee-pp-cli shops resolve — Etsy のショップハンドルを EverBee の識別情報（shop_id、正確なショップ名、評価、レビュー数、作成年）に解決します。
• everbee-pp-cli shops search — EverBee の Etsy ショップデータベースを検索します。

鮮度に関する契約

この CLI は、登録済みのストアを利用する読み取りコマンドのパスに限り、鮮度を一定の範囲内で管理します。--data-source auto モードでは、これらのパスが sync_state を確認し、ローカルデータを読み取る前に範囲を限定した更新を実行する場合があります。--data-source local では更新しません。--data-source live では API を読み取り、ローカルストアを変更しません。ソース選択を変更せずに鮮度チェックをスキップするには、EVERBEE_NO_AUTO_REFRESH=1 を設定します。

対象となるパス：

• everbee-pp-cli keyword-research
• everbee-pp-cli keyword-research list
• everbee-pp-cli keyword-research search
• everbee-pp-cli products
• everbee-pp-cli products search
• everbee-pp-cli products search
• everbee-pp-cli shops
• everbee-pp-cli shops search
• everbee-pp-cli shops search

JSON 出力で生成された来歴エンベロープを使用する場合、鮮度メタデータは meta.freshness に表示されます。これは対象コマンドパスにおける現在のキャッシュの鮮度を示すものであり、過去のデータがすべてバックフィルされていることや、API 固有のエンリッチメントを保証するものではありません。

適切なコマンドを見つける

実行したいことは分かっているものの、どのコマンドを使うべきか分からない場合は、CLI に直接尋ねてください。

everbee-pp-cli which "<capability in your own words>"

which は、自然言語による機能の問い合わせを、この CLI の厳選された機能インデックスから最も適合するコマンドに対応付けます。終了コード 0 は少なくとも 1 件の一致があることを示し、終了コード 2 は確信度の高い一致がないことを示します。その場合は --help を使うか、より絞り込んだ問い合わせをしてください。

レシピ

競争が少ないという主張を裏付ける

everbee-pp-cli research niche "dad shirt" --agent

需要、競争、飽和度、価格帯、根拠の件数、機会スコアに加え、各指標の来歴を返します。そのため、判断を鵜呑みにせず監査できます。

テーマの中から最も競争の少ないニッチを見つける

everbee-pp-cli research subniches --parent dad --product apparel --exclude-svg-png --limit 20 --agent

EverBee 独自の提案エンジンを使って親テーマを子ニッチに展開し、何も除外せずに商品タイプをフラグ付けし、スコアを正規化することで、子ニッチ同士を実際に比較できるようにします。

エージェント向けに詳細な商品ペイロードを絞り込む

everbee-pp-cli products search --search-term "dad shirt" --agent --select results.title,results.price,results.listing_type,results.cached_est_mo_revenue

商品行にはそれぞれ 68 個のフィールドがあります。--select で判断に必要な 4 項目だけに絞り、エージェントのコンテキストを小さく保ちます。

デザインの前に競合状況を把握する

everbee-pp-cli research competitors "dad shirt" --agent

検索結果数、価格の中央値、レビューと売上の密度、出品経過期間の四分位数を報告します。統計を検証できるよう、生の行も併せて出力します。

ニッチを週ごとに追跡する

everbee-pp-cli research drift "dad shirt" --save-baseline --agent

スナップショットをローカルストアに保存します。後で再実行すると、そのスナップショットとの差分を取り、実際に変化した内容を、両方の取得時刻を含む来歴とともに報告します。

認証の設定

EverBee の認証には Google SSO で発行されるセッショントークンを使用します。API キーの発行ページはありません。トークンの取得手順を確認するには 'everbee-pp-cli auth setup' を実行し、取得したトークンを 'everbee-pp-cli auth set-token ' で保存するか、EVERBEE_ACCESS_TOKEN を直接設定してください。トークンには有効期限があります。401 が返された場合、CLI の故障ではなく、トークンの差し替えが必要です。リサーチの利用量は EverBee のプランによって制限されます。無料の Hobby プランではキーワード検索を月 10 回までしか実行できません。この CLI は、その上限を空の結果ではなく型付きエラーとして報告します。

設定を検証するには everbee-pp-cli doctor を実行してください。

エージェントモード

任意のコマンドに --agent を追加します。次のオプションが有効になります：--json --compact --no-input --no-color --yes。

• パイプ可能 — 標準出力には JSON、標準エラーにはエラーを出力します

• フィルター可能 — --select でフィールドを絞り込めます。ドット区切りのパスでネストした構造にアクセスでき、配列では各要素をたどります。詳細な API でコンテキストを小さく保つために重要です：

  everbee-pp-cli keyword-research list --agent --select results.title,results.price
  

• プレビュー可能 — --dry-run でリクエストを送信せずに確認できます

• オフラインに対応 — 同期／検索コマンドでは、利用可能な場合にローカルの SQLite ストアを使用できます

• 非対話型 — プロンプトは表示されず、すべての入力をフラグで指定します

• 読み取り専用 — 作成、更新、削除、公開、コメント、賛成票の付与、招待、注文、送信など、その他の変更を伴うリクエストにはこの CLI を使用しないでください

レスポンスエンベロープ

ローカルストアまたは API から読み取るコマンドは、出力を出所エンベロープでラップします。

{
  "meta": {"source": "live" | "local", "synced_at": "...", "reason": "..."},
  "results": <data>
}

データは .results から解析し、ライブデータかローカルデータかは .meta.source で確認します。人間が読みやすい N results (live) の概要が stderr に出力されるのは、stdout がターミナルであり、かつ機械形式のフラグ（--json、--csv、--compact、--quiet、--plain、--select）が設定されていない場合のみです。パイプ経由の利用者やエージェント、および形式を明示した実行では、stdout に純粋な JSON が出力されます。

パスと状態

エージェントは、CLI のパスリゾルバーをランタイム契約の一部として扱ってください。

• 1 回の呼び出しで指定するには --home <dir> を使うか、EVERBEE_HOME=<dir> を設定して、4 種類すべてのパスを 1 つのルート配下に移動します。

• 特定の種類のパスだけを別の場所にする必要がある場合に限り、種類ごとの環境変数 EVERBEE_CONFIG_DIR、EVERBEE_DATA_DIR、EVERBEE_STATE_DIR、EVERBEE_CACHE_DIR を使います。

• 解決順序は、種類ごとの環境変数、--home、EVERBEE_HOME、XDG（XDG_CONFIG_HOME、XDG_DATA_HOME、XDG_STATE_HOME、XDG_CACHE_HOME）、プラットフォームのデフォルトの順です。

• config には config.toml やプロファイルなどの設定が含まれます。data には credentials.toml、data.db、Cookie、認証用サイドカーが含まれます。state には永続化されたクエリ、ジョブ、teach.log が含まれます。cache には再生成可能な HTTP／キャッシュファイルが含まれます。

• 保存されたシークレットは、data ディレクトリ内の credentials.toml に格納されます。既存の従来形式の config.toml にあるシークレットは互換性のために読み込まれ、最初の認証書き込み時に config.toml から削除されます。

• everbee-pp-cli doctor --fail-on warn を実行して、パスや認証情報の場所に関する警告を確認します。agent-context は、解決済みディレクトリを必要とするエージェント向けに、スキーマ v4 の paths ブロックを公開します。

• MCP の場合は、MCP ホスト設定を通じてパスの変更を渡します。MCP バイナリは CLI のフラグを継承しません。

  {
    "mcpServers": {
      "everbee": {
        "command": "everbee-pp-mcp",
        "env": {
          "EVERBEE_HOME": "/srv/everbee"
        }
      }
    }
  }
  

フリートでの優先順位：継承された種類ごとの環境変数は、その種類について明示的な --home より優先されます。フリート全体で継続的に使う設定には EVERBEE_HOME または種類ごとの環境変数を使い、--home は 1 回の呼び出しに限って使います。環境変数を解除してもパスの変更は元に戻りません。EVERBEE_HOME を解除する前にファイルを手動で移動してください。そうしないと、doctor は旧ルートに残された認証情報を見つけられません。

自動学習

この CLI には、学習内容を自動的に記録するループが組み込まれています。CLI が記録を自動で管理します。呼び出しのたびにローカルでジャーナルに記録され、失敗したフラグの後に修正して再試行すると flag_alias 候補が自動生成され、プレイブックのないクエリファミリーに対して teach を実行すると、セッションのジャーナルから playbook_candidate が自動生成されます。あなたの役割は判断のみです。まず recall を実行し、見つかった候補に基づいて行動し、最終的な回答を teach し、修正に気づいたら playbook amend を実行します。失敗を手作業で記録する必要はありません。

Step 1：探索を始める前に recall を実行する

新しいユーザーの質問について、list／search／drill コマンドを実行する前に、次を実行します。

everbee-pp-cli recall "<user's question>" --agent

レスポンスエンベロープ：

{
  "query": "...",
  "normalized": "<normalized form>",
  "query_entities": ["..."],
  "found": true | false,
  "match_score": 0.0,
  "results": [
    { "resource_id": "...", "resource_type": "...", "venue": "...",
      "confidence": 2, "entity_match": "exact|partial|unknown",
      "source": "taught|preseed|pattern", "warnings": ["..."] }
  ],
  "mismatches": [ /* only when --debug-mismatches */ ],
  "warnings": [ /* top-level */ ],
  "candidates": [
    { "id": 12, "class": "flag_alias | playbook_candidate",
      "summary": "...", "sightings": 3, "last_seen": "...",
      "rationale": "...",
      "next_action": ["<trial command>", "everbee-pp-cli learnings confirm 12"] }
  ],
  "playbook": {
    "query_family": "...",
    "playbook": {
      "steps": [ { "cmd": "<command with {slot} substitution>", "purpose": "..." } ],
      "entity_slots": ["$ENTITY"],
      "expected_tool_calls": 3
    },
    "slots_resolved": { "$ENTITY": { "token": "<live token>", "canonical": "<canonical>" } },
    "notes": "<workarounds + gotchas for this query family>"
  },
  "notes": "<duplicate surface for non-playbook callers>"
}

ストアが空の場合の早期終了：ストアに学習内容、プレイブック、候補がまだない場合（recall で何も見つからず、learnings list と learnings candidates の結果も両方空の場合）、クエリのたびに負荷をかけないよう、このセッション中は以降の recall を省略します。何かを教えた後は、再び recall を最初に実行してください。

Step 2: 判断ツリー

次の順に candidates、playbook、notes、results[0]、警告を読みます。

if Candidates present (warnings include "candidates_present"):
    -> candidates are try-then-confirm, never facts. Follow each candidate's
       two-step next_action verbatim: run the trial command first, then run
       `learnings confirm <id>` only after the trial verified the behavior.
       Reject a wrong candidate with `learnings reject <id>`.
    -> NEVER re-teach something recall surfaced as a candidate; confirm or
       reject that candidate instead of teaching a duplicate.
    -> candidates ride alongside playbooks and resource hits, not instead of
       them; continue with the branches below after acting on them.

if Playbook present:
    -> READ Playbook.notes verbatim FIRST (workarounds + gotchas the CLI surface doesn't expose)
    -> replay Playbook.steps in order, substituting Playbook.slots_resolved entries
       for the entity slot tokens. If a step's slot is unresolved, fall back to
       discovery for that step only.
    -> the Playbook's expected_tool_calls is a budget; if you find yourself running
       materially more, record the divergence via `everbee-pp-cli playbook amend`
       at end-of-session.

elif Notes present (no Playbook):
    -> read Notes verbatim before any discovery step; they carry known gotchas
       for this query family even when no structured choreography exists yet.

elif Found AND Results[0].EntityMatch == "exact" AND Results[0].Confidence >= 2:
    -> skip discovery; fetch live data for Results[*].ResourceID in parallel

elif Found AND Results[0].EntityMatch == "partial":
    -> candidate hint, NOT a hit; read the resource title to validate before trusting

elif (any row in Mismatches[] when --debug-mismatches was passed):
    -> treat as cold start; the stored learning is for a different entity
       (different canonical resolved from query_entities)

else:  // Found == false, no playbook, no notes
    -> cold start; run discovery normally; teach the answer afterward (Step 4).
       If the family has no playbook yet, that teach auto-synthesizes a
       playbook candidate from this session's journal - you do not need to
       record one by hand.

Playbook と Notes は、リソースごとのパスとは別個のものです。recall の応答には、Playbook と Results[] のヒットの両方が含まれることがあります。両方を活用してください。Playbook は実行する手順を示し、リソースのヒットが特定のステップをスキップさせます。通常は mismatches をスキップし、コールドスタート時の予期しない動作を調査する場合に限り --debug-mismatches を渡します。

候補の判断について：learnings confirm <id> は候補を登録する前に、その完全なペイロードを出力します。出力されたペイロードが、確認した動作と一致するか確認してください。learnings reject <id> は導出シグネチャをトゥームストーン化し、同じ候補が再び表示されないようにします。エンベロープには、現時点で対応する価値のある少数の候補のみが含まれます。すべての未処理候補は everbee-pp-cli learnings candidates で確認できます。

グレースフルデグラデーション：learnings confirm が不明なコマンドの場合、古いバイナリを使用しています。候補に関するガイダンスは無視し、残りのプロトコルに従ってください。

Step 3: warnings は必ず読む

• low_confidence：confidence<2 の行が存在します。ヒントとして扱い、発見をスキップできるヒットとは見なさないでください。
• resource_not_in_store：ローカルストアに、学習内容が指すリソースがありません。一致検証でエンティティを分類できなかったため、直接取得して再評価してください。
• cross_alias_match（結果ごと）：行は別のエイリアスで学習されていましたが、entity_lookups を通じて、ライブクエリの正規エンティティと一致しました（例：「USA」での学習が「United States」の recall を満たす場合）。resource_id を信頼してください。
• similar_shape_different_entity:<canonical>（トップレベル）：構造的に一致する行はありますが、その正規エンティティはライブクエリのものとは異なります。コールドスタートとして扱います。この警告にはヒントとして競合する正規エンティティが含まれますが、その行は Results に昇格しません。
• ambiguous_alias（トップレベル）：単一のクエリエンティティが複数の正規エンティティに解決されました（例：「Cards」→ Arizona Cardinals + St. Louis Cardinals）。リソースを確定する前に、コンテキストから曖昧さを伝えてください。
• candidates_present（トップレベル）：エンベロープに candidates セクションが含まれています。他の作業より先に、Step 2 の候補分岐に従って処理してください。
• lookup_refresh_available（トップレベル）：クエリ内のエンティティに lookup 行がまだありませんが、同期済みデータで補完できる可能性があります。everbee-pp-cli sync を実行してエンティティ lookup を更新してください。
• トップレベルの no_learnings_for_query_family：Jaccard の下限を超える行がテーブルにありません。完全なコールドスタートです。

Step 4: 応答を確定した後に必ず teach & を実行する

学習は無条件で行います。ストアで回答できなかったクエリを解決した後、最終的なリソースの対応関係をバックグラウンドで学習させます。呼び出し回数のしきい値や、学習する価値が「ある」かどうかの判断は不要です。teach はループの要です。Playbook がないファミリーに対する Playbook の合成を開始し、同じ指示対象を表す言い回しはひとつのファミリーにまとめられるため、ほぼ重複する teach によってストアが分断されることはありません。ユーザー向けの応答を組み立てた後、出力する前に、シェルの & を付けて実行し、呼び出しがすぐに戻るようにします。

everbee-pp-cli teach --query "<user's question>" --resource-type <type> --resource <id1> --resource <id2>
# (append shell `&` to background it)

成功時は何も表示されません。エラーは、解決済みの状態ディレクトリ内にある teach.log にのみ記録されます。最も具体的なリソースを teach してください。ユーザーの質問が広範で、具体的な回答を見つけるために親レコードをたどった場合は、親ではなく末端の ID を teach します。CLI は recall 時にシード済みの entity_lookups を使ってエイリアス間の解決を行うため、あるエイリアス（例：「Niners」）での teach は、別のエイリアス（例：「49ers」、「San Francisco」）を使った今後のクエリも自動的に満たします。

PII に関するルール：識別子を取り除いた構造的な質問を teach してください。名前、メールアドレス、電話番号、アカウント ID、その他の個人識別子を、学習させるクエリやメモに含めてはいけません。CLI は明らかなメールアドレスや電話番号の形式を teach クエリからスキャンして警告しますが、ブロックはしません。警告に頼らず、teach の前に取り除いてください。

ステップ 5：プレイブック — オプションのフラグ、自動合成

セッションにプレイブックが「ふさわしい」かどうかを判断する必要はありません。プレイブックがないファミリーに対して teach を実行すると、セッションのジャーナルから playbook_candidate が自動合成され、次のセッションで確認または却下されます。明示的なプレイブックフラグを付けるのは、そのまま記録する価値のある手順をすでに把握している場合に限ります。CLI では見つからなかった回避策（気付かれずに破棄されるフラグ、未公開のパラメーター、ページネーションの工夫、ペイロードに関する注意点など）が該当します。統合された一度の呼び出し形式を優先してください。リソースに関する学習内容とプレイブックを、同じ teach 呼び出しで記録します。

# Common case: record both the resource learning AND the playbook in one call.
everbee-pp-cli teach \
  --query "<user's question>" \
  --resource <id> \
  --playbook-file ~/playbooks/<shape>.json \
  --playbook-notes-file ~/playbooks/<shape>-notes.md
# (append shell `&` to background it)

# Alternate: playbook-only (no resource to record alongside).
everbee-pp-cli teach-playbook \
  --query "<user's question>" \
  --playbook-file ~/playbooks/<shape>.json \
  --notes-file ~/playbooks/<shape>-notes.md

プレイブックファイルは steps、entity_slots、expected_tool_calls を含む JSON です。ノートファイルは注意点をそのまま記載した Markdown です。ファイルを扱わない呼び出し元（MCP のみのエージェント）は、同じ内容をインラインで渡します。統合された teach 形式では --playbook-json と --playbook-notes を、teach-playbook では --playbook-json と --notes を使用します。統合された teach 形式では、プレイブックのフラグはオプションです。リソースのみを教える場合は、フラグをすべて省略してください。単独の teach-playbook 形式では、プレイブックとノートのフラグの少なくとも一方を設定する必要があります。両方が空の場合は拒否されます。プレイブックは、構造上のクエリファミリー（エンティティを取り除いたもの）に基づいて管理されます。そのため、あるエンティティ形状のクエリから学習したレシピは、同じ形状を持つほかのすべてのクエリに適用されます。呼び出し時には slots_resolved が、実際のクエリの正規形を割り当てます。

今後の呼び出しでプレイブックが見つかった場合は、それを確かな情報源として扱ってください。slots_resolved による置換を適用して手順を再実行し、すでに手順書に記載されている探索は省略して、どの手順よりも先に notes を読んでください。

ステップ 6：デバッグ応答で修正点を特定した場合は、playbook amend & を実行する

デバッグプロトコルへの応答で、ノートやプレイブックに反映すべき具体的な修正点（回避策、未公開のエンドポイント形式、古いフィールド名、確認されたスキーマの変化、空のペイロードへのフォールバックなど）を特定した場合は、ユーザー向けの応答を出す前に playbook amend を実行してください。teach と同様に、実行後の完了を待たずに進めます。

everbee-pp-cli playbook amend \
  --query "<exact recall query string>" \
  --add-note "<your concrete correction>"
# (append shell `&` to background it)

修正する価値があるもの：このセッションで実際に確認した動作で、将来の自分が知っていると役立つものです。修正する価値がある例：

• フラグを気付かれずに破棄したり、順序を誤って処理したりする CLI の仕様に対する回避策。
• 未公開のエンドポイント形式（レスポンスが {meta, results} でラップされている、ペイロードがドキュメントの説明よりもさらに 2 階層深いなど）。
• 確認されたスキーマの変化（フィールド名の変更、シーズン間でのインデックスのずれ、API が返すカテゴリラベルの小文字化など）。

ノートに記載しないもの：

• ユーザーの質問に対する、年やエンティティに固有の回答。これは応答であり、学習内容ではありません。
• プレイブックが実行時にすでに取得するチーム、選手、行ごとのデータ。
• 既存のノートの内容を言い換えた記述。

amend コマンドは、ファミリーの既存のノートにタイムスタンプ付きのマーカー（[amend YYYY-MM-DDTHH:MMZ]: <text>）を追記します。複数の amend は蓄積され、監査履歴を確認できます。ファミリーにプレイブックがまだ存在しない場合、amend はノートのみのプレイブックを作成するため、コールドスタート時の修正も反映されます。

amend ノートにおける PII の取り扱い

将来の Printing Press のバージョンで、playbook amend のノートが共有知識として上流に提供される可能性があります。遡及的な削除を行わずに上流への提供を続けられるよう、ユーザーを特定できる情報を含めないでください。

• 含めてはいけないもの：ユーザーのファイルシステム上のパス、個人用の API キーやトークン、ユーザーのメールアドレス、ユーザーの GitHub ハンドル、単一ユーザーに紐付いた特定のクエリ履歴。
• 含めてもよいもの：エンドポイントの形式、未公開のフィールド名、API の注意点、確認されたスキーマの変化、CLI の仕様に対する回避策、汎用的なページネーションや再試行の方法。

修正点がユーザー固有のコンテキストでのみ意味を持つ場合は、プレイブックの amend ではなく、個人用のノートに記録してください。

ループの効果測定

everbee-pp-cli learnings stats は、ローカルの learn_events テーブルから再呼び出しのヒット率、教示内容の再利用率、プレイブックの解決率、候補の承認／却下件数を報告します。分母となる値がない場合、割合は null になります。データはすべてこのマシン内にとどまります。この CLI でループに価値があるかを確認するために使用してください。

学習の無効化

• 単一のコマンドに --no-learn を指定すると、recall と teach の書き込み処理の両方を短絡します。蓄積された学習内容の影響を受けてはならない、決定的なエージェントフローやテストに使用してください。
• 環境変数に EVERBEE_NO_LEARN=true を設定すると、パイプライン全体が無効になります。

エージェントのフィードバック

この CLI に問題があると気づいたら、あなた自身またはエージェントが、その内容を記録してください。

everbee-pp-cli feedback "the --since flag is inclusive but docs say exclusive"
everbee-pp-cli feedback --stdin < notes.txt
everbee-pp-cli feedback list --json --limit 10

エントリーは、解決済みのデータディレクトリ内の feedback.jsonl にローカル保存されます。EVERBEE_FEEDBACK_ENDPOINT が設定されており、さらに --send が指定されているか、EVERBEE_FEEDBACK_AUTO_SEND=true に設定されている場合を除き、POST されることはありません。デフォルトの動作はローカルのみです。

バグ報告ではなく、意外だったことを書いてください。短く、具体的に、1 行で記録してください。それが積み重なっていく内容です。

出力の配信

すべてのコマンドで --deliver <sink> を指定できます。出力は標準出力に加えて、または標準出力の代わりに、指定したシンクへ送られます。これにより、エージェントはコマンド結果を手作業でパイプ処理せずに振り分けられます。次の 3 つのシンクに対応しています。

シンク	動作
stdout	デフォルト。標準出力のみに書き込みます
file:<path>	出力を <path> にアトミックに書き込みます（一時ファイル＋リネーム）
webhook:<url>	出力本文を URL に POST します（--compact の場合は application/json または application/x-ndjson）

未対応のスキームは、対応しているスキームの一覧を示す構造化エラーとともに拒否されます。Webhook の失敗時はゼロ以外の終了コードを返し、URL と HTTP ステータスを標準エラー出力に記録します。

名前付きプロファイル

プロファイルは、保存したフラグ値のセットで、複数回の実行で再利用できます。定期実行または繰り返し実行するエージェントで、実行ごとに異なる入力を与えながら、同じ保存済みフラグを使用する場合に便利です。

everbee-pp-cli profile save briefing --json
everbee-pp-cli --profile briefing keyword-research list
everbee-pp-cli profile list --json
everbee-pp-cli profile show briefing
everbee-pp-cli profile delete briefing --yes

明示的に指定したフラグは常にプロファイルの値より優先され、プロファイルの値はデフォルトより優先されます。agent-context は、実行時に情報を調べるエージェントがプロファイルを検出できるよう、available_profiles に利用可能なすべてのプロファイルを一覧表示します。

終了コード

コード	意味
0	成功
2	使用方法エラー（引数が不正）
3	リソースが見つかりません
4	認証が必要です
5	API エラー（上流の問題）
7	レート制限中（待ってから再試行してください）
10	設定エラー

引数の解析

$ARGUMENTS を解析します。

1. 空、help、または --help → everbee-pp-cli --help の出力を表示
2. install で始まる → mcp で終わる場合は MCP のインストール。それ以外の場合は上記の前提条件を参照
3. それ以外 → 直接使用（--agent を付けて CLI コマンドとして実行）

MCP サーバーのインストール

1. MCP サーバーをインストールします。

   go install github.com/mvanhorn/printing-press-library/library/marketing/everbee/cmd/everbee-pp-mcp@latest
   

2. Claude Code に登録します。

   claude mcp add everbee-pp-mcp -- everbee-pp-mcp
   

3. 確認します：claude mcp list

直接使用

1. インストール済みか確認します：which everbee-pp-cli 見つからない場合は、インストールを提案してください（このスキルの冒頭にある前提条件を参照）。
2. ユーザーのクエリに最適なコマンドを、上記の独自機能とコマンドリファレンスから選びます。
3. --agent フラグを付けて実行します。

   everbee-pp-cli <command> [subcommand] [args] --agent
   

4. あいまいな場合は、サブコマンドのヘルプを確認します：everbee-pp-cli <command> --help。