pp-flight-goat

Flight Goat — Printing Press CLI

前提条件：CLI のインストール

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

1. Printing Press インストーラーを使用してインストールします。バイナリのインストール先は、macOS/Linux では $HOME/.local/bin、Windows では %LOCALAPPDATA%\Programs\PrintingPress\bin がデフォルトです。

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

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

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

go install github.com/mvanhorn/printing-press-library/library/travel/flight-goat/cmd/flight-goat-pp-cli@latest

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

独自の機能：API キー不要の運賃検索

主要なコマンドは消費者向けの運賃情報ソースに直接アクセスするため、認証情報は不要です。この CLI を AeroAPI が必須であるかのように説明しないでください。FlightAware AeroAPI（以下に記載）は補助的で、オプションです。

• flight-goat-pp-cli flights <origin> <destination> <date> — Google Flights で運賃を検索します。実際の価格、区間、航空会社を取得できます。--return で往復、--segment の繰り返しで複数都市、--trip の繰り返しで一括検索に対応します。
• flight-goat-pp-cli dates <origin> <destination> — 旅行期間内の最安日をスキャンします。
• flight-goat-pp-cli explore <airport> / flight-goat-pp-cli longhaul <airport> — Kayak を使って直行便と長距離路線を検索します。
• flight-goat-pp-cli soar <origin> <destination> <date> — FlySoar（Duffel NDC/GDS）による第2の価格情報を取得し、予約へ引き継ぎます。
• flight-goat-pp-cli award <origin> <destination> — Seats.aero の特典航空券（マイル）空席状況を取得します。各客室クラスのマイルと税金による特典交換オプションを確認できます。空港のリストと --cabin のリストは、カンマ区切りで指定できます。**SEATS_AERO_API_KEY（利用資格のある Seats.aero Partner API キー）が必要です。**商用 API の利用には Seats.aero の書面による許可が必要です。読み取り専用です。
• flight-goat-pp-cli wifi flight <flightNumber> / wifi airline <IATA> / wifi airlines / wifi rollouts [IATA] / wifi speed <flight> / wifi airline-speed <IATA> / wifi search <query> — SeatWifi の機内 WiFi 予測、Starlink の導入状況、クラウドソーシングによる通信速度レポートを取得します。**API キーは不要です。**公開 JSON は https://seatwifi.com にあります。読み取り専用です。
• flight-goat-pp-cli assess — 遅延便や再予約に関する意思決定を支援します。

各結果の booking_urls に含まれる予約用ディープリンクには、検索時に使用したものと同じ --currency が反映されます。例外は award で、現金ではなくマイル／ポイントが表示され、予約用ディープリンクも生成されません。

運賃の一括検索：シェルループではなく、--pace とともに --trip を使用してください

Google は IP ごとに運賃検索の頻度を制限します。flights の呼び出しをシェルループで並列実行すると、15 分以上続くこともある HTTP 429 ブロックが発生します。代わりに、間隔を空けて実行する一度の呼び出しで一括検索してください。

# Three independent searches, 3s apart, one JSON envelope with per-trip rows
flight-goat-pp-cli flights \
  --trip "SEA>DEN@2026-09-14" \
  --trip "PDX>DEN@2026-09-15@2026-09-17" \
  --trip "SFO>DEN@2026-09-15" \
  --pace 3s --currency EUR --agent

--trip は ORIG>DEST@DEPART または ORIG>DEST@DEPART@RETURN（--segment と同じ形式）を受け取り、位置引数を置き換えます。すべてのフィルターフラグ（--currency、--stops、--class、--airlines、--time、--return-time、--passengers）は、すべての旅程に適用されます。各旅程の行は、エンベロープの results[] に status が ok／error／skipped のいずれかとして格納されます。

往復便では、各区間の出発時間帯を個別に指定できます。--time は往路の時間帯、--return-time は復路の時間帯を設定します（未設定の場合は --time を使用します）。どちらも同じ H-H 形式の24時間表記を受け取ります。たとえば、午前発の往路と夕方発の復路を指定するには、flight-goat-pp-cli flights SEA HNL 2026-08-01 --return 2026-08-10 --time 6-12 --return-time 17-23 を使用します。

往復：--return だけでは復路のオプションは返されません

--return だけを指定すると、往路の旅程のみが表示されます。それぞれの price には、Google が自動選択した「最安の復路」を含む合計金額がすでに含まれていますが、復路のフライト（時刻、航空会社、所要時間）は表示されません。往路の一覧に両方向が含まれていると解釈したり、価格が往路だけの金額だと想定したりしないでください。

実際の復路のオプションを確認して選択するには、Google 独自の UI と同じ正しい2段階のフローを実行します。ステップ1では、flight-goat-pp-cli flights LHR BCN 2027-03-01 --return 2027-03-18 --agent を実行すると、flights[0].direction == "outbound" となる往路のオプションが返されます。希望する便の位置を1始まりで控えておいてください。ステップ2では、flight-goat-pp-cli flights LHR BCN 2027-03-01 --return 2027-03-18 --select-outbound 1 --agent を実行すると、その特定の往路に対応する、実際の復路のオプションと価格が返されます。このとき flights[] は direction == "return" となり、それぞれ独立した価格を持ちます。また、エンベロープの selected_outbound には、どの往路と組み合わせられているかが示されます。

--select-outbound N は1始まりで、ステップ1で返された順に数えます。--return（往復のみ）が必須で、--trip または --segment（>=2）とは併用できません。往復の往路の各行には selection_token も含まれます。これは CLI がステップ2のリクエストを作成する際に内部で使用する値と同じで、固定インデックスではなく独自の選択フローを構築する呼び出し元向けです。

レート制限時の動作：

• 一時的な 429 は、コマンドが失敗する前に自動で再試行されます（2秒／5秒／12秒のバックオフ）。
• 429 が継続する場合、バッチは早期に停止します。処理を続けると IP ブロックが悪化するためです。部分的なエンベロープは引き続き出力され、終了コードは 7（レート制限）になります。
• Google がブロックされている間も、soar と explore／longhaul は別のバックエンドを使用するため、引き続き動作します。doctor には、同じ仕様が google_flights の項目に記載されています。

往復の最安日程：dates --round --duration

デフォルトでは、dates は片道の価格をスキャンします。往復の合計金額をスキャンするには、--round --duration N を追加します。各行には、その日に出発し N 泊後に帰着する場合の最安往復料金が表示されます。往路と復路の価格が別々に表示されるわけではありません。例：flight-goat-pp-cli dates SEA HNL --round --duration 7 --sort --agent。--round を指定する場合は --duration が必須で、値は0より大きくなければなりません。各結果行には return_date（departure_date + --duration）が price とともに含まれます。この price はすでに往復の合計金額です。

はじめに

AeroAPI は、ソフトウェア開発者が FlightAware のさまざまなフライトデータにアクセスできる、シンプルなクエリベースの API です。ユーザーは最新または過去のデータを取得できます。AeroAPI は、正確で実用的な航空データを提供する RESTful API です。Foresight™ の導入により、お客様は米国で予測される航空会社の到着予定時刻の半数以上を支えるデータにアクセスできます。

カテゴリ

AeroAPI は、必要な情報を見つけやすくするために、いくつかのカテゴリに分かれています。

• フライト：概要情報、予定ルート、位置情報など
• Foresight：FlightAware Foresight™ によって強化されたフライト位置情報
• 空港：空港情報および FIDS スタイルのリソース
• 運航会社：運航会社情報および保有機材の運航状況に関するリソース
• アラート：フライトアラートと配信先の設定
• 履歴：さまざまなエンドポイントでの過去のフライトデータへのアクセス
• その他：フライトの運航障害、将来のスケジュール情報、航空機の所有者情報

開発ツール

AeroAPI は OpenAPI Spec 3.0 を使用して定義されているため、Postman などのツールに簡単にインポートできます。まずは、 Postman の手順に従って API 仕様をインポートしてみてください。 コレクションとしてインポートした後は、呼び出しを行う前に、コレクションの「Authorization」タブにある「Value」フィールドだけを入力して保存する必要があります。

AeroAPI OpenAPI 仕様の場所：
https://flightaware.com/commercial/aeroapi/resources/aeroapi-openapi.yml

オープンソース AeroApps プロジェクトでは、 利用を開始するための小規模なサービスとサンプルアプリケーションを提供しています。

Flight Information Display System（FIDS）AeroApp は、複数の言語と Docker コンテナを使用する多層アプリケーションの例です。 接続、データのキャッシュ、フライトの表示、フライトマップの活用を実演します。

Alerts AeroApp は、Docker 化された Python バックエンドと React フロントエンドを備えたサンプルアプリケーションで、AeroAPI を使用してアラートを設定、編集、受信する方法を実演します。

AeroAPI プッシュ通知のテスト用インターフェースを使うと、AeroAPI プッシュを介してカスタマイズしたアラートの配信をすばやく簡単にテストできます。

コマンドリファレンス

aircraft — 航空機を管理します

• flight-goat-pp-cli aircraft <type> — ICAO 航空機型式指定文字列を指定して、航空機の型式に関する情報を返します。

airports — 空港を管理します

• flight-goat-pp-cli airports get — KLAX、KIAH、O07 などの ICAO または LID 空港コードを指定して、空港に関する情報を返します。
• flight-goat-pp-cli airports get-all — 既知のすべての空港の ICAO 識別子を返します。
• flight-goat-pp-cli airports get-delays-for-all — 遅延が発生している空港の一覧を返します。
• flight-goat-pp-cli airports get-nearby — 指定した場所から指定の距離内にある空港の一覧を返します。

alerts — AeroAPI のアラート機能を使用すると、主要なフライトイベントに関するリアルタイムアラートを設定して受信できます。アラートエンドポイントでカスタマイズ可能なアラートを利用することで、ユーザーは通知対象とするさまざまなイベントやフィルターを選択できます。これにより、フライトプランの提出、フライトの出発（out と off）、フライトの到着（on と in）などのイベントについて、ニーズに合わせたアラートを受信できます。

アラート機能を使い始めるには、まず PUT /alerts/endpoint エンドポイントを使用して、アラートの配信先となるアカウント全体のデフォルト URL を設定する必要があります。この手順は、アラートを設定する前に完了させる必要があります。特定のアラートに個別の配信 URL が指定されていない場合、アカウントのすべてのアラートがこの URL に送信されます。アラートを設定する前にこの手順を実行していない場合、POST /alerts エンドポイントを操作しようとすると、この手順を促すエラーメッセージとともに 400 エラーが返されます。PUT /alerts/endpoint エンドポイントで URL を設定すると、POST /alerts エンドポイントを使用してアラートを設定できます。また、GET /alerts エンドポイントを使用して、AeroAPI キーに関連付けられている設定済みのアラートをすべて取得できます。GET /alerts エンドポイントを使うと、アカウントに設定されている対象のアラートの ID を簡単に取得できます。その ID を使って、GET PUT および DELETE /alerts/{id} エンドポイントから、個別のアラートを取得、更新、削除できます。 個々のアラートを設定する際、target_url フィールドには、PUT /alerts/endpoint で設定したアカウント全体のターゲットエンドポイントとは異なる URL を指定できます。アラートに target_url フィールドが設定されている場合、そのアラートはデフォルトのアカウント全体のエンドポイントではなく、指定された target_url に配信されます。このフィールドがアラートに設定されていない場合、アラートはデフォルトのアカウント全体のエンドポイントに配信されます。このフィールドを設定することで、異なるアラートを異なるエンドポイントに簡単に振り分けられます。これは、アプリケーションごとにアラートを設定したり、本番環境のアラート設定を変更せずに、別の開発環境にアラートを送信したりする場合に便利です。

設定する各アラートには、配信する「イベント」を複数設定できます。ほとんどのイベントではアラートが1件配信されますが、arrival イベントと departure イベントでは複数のアラートが配信される場合があります（バンドルと呼ばれます）。departure イベントでは、出発（実際に離陸した）アラートに加え、提出済みのフライトプランのアラートと、出発ごとの最大5件の変更がバンドルされます。これには、30分を超える大幅な出発遅延、ゲート変更、空港の遅延に関するアラートが含まれる場合があります。FlightAware Global のお客様には、出発バンドルの一部として Power on と Ready to taxi のアラートも配信されます。arrival イベントでは、到着（実際に着陸した）アラートに加え、特定された最大5件の飛行中の変更（30分を超える遅延を含み、目的地変更は除く）がバンドルされます。FlightAware Global のお客様には、arrival バンドルの一部として taxi stop の時刻も配信されます。On/Off にバンドル形式と非バンドル形式の両方を設定した場合、イベントが重複するケースではアラートは1件だけ配信されます。

アラート設定を変更する必要がある場合は、追加のアラートを作成するのではなく、一意のアラート識別子（id）を使って PUT /alerts/{id} エンドポイントからアラートを更新することをお勧めします。これにより、不要になったアラートが配信されて無用なノイズが生じる可能性のある、重複アラートを避けられます。

アラートを削除する必要が生じた場合は、DELETE alerts/{id} エンドポイントを利用してアラートを削除すると、その後は配信されなくなります。特定のアラート ID は、GET /alerts エンドポイントから取得できます。

• flight-goat-pp-cli alerts create — 新しい AeroAPI フライトアラートを作成します。
• flight-goat-pp-cli alerts delete — 指定された ID のアラートを削除します
• flight-goat-pp-cli alerts delete-endpoint — 特定の URL が設定されていないアラートの POST 先となる、デフォルトのアカウント全体の URL を削除します。
• flight-goat-pp-cli alerts get — 指定された ID のアラート設定データを返します。
• flight-goat-pp-cli alerts get-all — FlightAware アカウントに設定されているすべてのアラートを返します（他の方法で設定されたアラートも含みます）
• flight-goat-pp-cli alerts get-endpoint — AeroAPI 経由で配信されるアラートの POST 先となる URL を返します。
• flight-goat-pp-cli alerts set-endpoint — AeroAPI 経由で配信されるアラートの POST 先となるデフォルト URL を更新します。
• flight-goat-pp-cli alerts update — 指定された ID のアラート設定を変更します。

disruption-counts — 運航障害件数を管理します

• flight-goat-pp-cli disruption-counts get — 指定した期間における、特定の航空会社または空港のフライトの欠航・遅延件数を返します。
• flight-goat-pp-cli disruption-counts get-all — 指定した期間における、すべての航空会社またはすべての空港のフライトの欠航・遅延件数の合計を返します。

flights — フライトを管理します

• flight-goat-pp-cli flights get — 登録記号、識別子、または fa_flight_id に基づいて、フライト情報のステータス概要を返します。
• flight-goat-pp-cli flights get-by-advanced-search — 地理空間検索パラメーターに基づいて、現在飛行中または最近飛行していたフライトを返します。
• flight-goat-pp-cli flights get-by-position-search — 地理空間検索パラメーターに基づいて、フライトの位置情報を返します。
• flight-goat-pp-cli flights get-by-search — 地理空間データなどのさまざまなパラメーターに一致する飛行中のフライトを検索します。
• flight-goat-pp-cli flights get-count-by-search — 検索クエリの詳細なドキュメントは、/flights/search エンドポイントで確認できます。

foresight — Foresight エンドポイントでは、FlightAware の Foresight 予測モデルと主要なイベントの予測を利用できます。高度な機械学習（ML）モデルが、フライトに影響を与える主要な要因を特定して将来のイベントをリアルタイムで予測することで、運航効率の向上と、空でも地上でもより適切な意思決定を可能にする、これまでにない洞察を提供します。Foresight の機能について詳しくは、https://www.flightaware.com/commercial/foresight/ をご覧ください。

各エンドポイントは、同様の機能を持つ Foresight 非対応のエンドポイントに対応しており、Foresight のレスポンスにはすべての ML「予測」値が追加されています。対応する Foresight 非対応のエンドポイントのレスポンスには、foresight_predictions_available フラグが含まれています。このフラグは、必要に応じて Foresight の予測を取得して活用し、コストを管理するためのトリガーとして任意で使用できます。Foresight は Premium ティアのお客様のみご利用いただけます。詳しい情報や料金について、またアカウントで Foresight を有効にするには、[email protected] までお問い合わせください。

• flight-goat-pp-cli foresight get-flight-position-with — Foresight データを含む、フライトの現在位置を取得します
• flight-goat-pp-cli foresight get-flight-with — 登録記号、識別子、または fa_flight_id に基づいて、フライト情報のステータス概要を返します
• flight-goat-pp-cli foresight get-flights-by-advanced-search-with — 地理空間検索パラメーターに基づいて、現在飛行中または最近飛行していたフライトを返します。

history — 履歴を管理します

• flight-goat-pp-cli history get-aircraft-last-flight — 登録記号に基づいて、航空機の最後に確認されたフライトの情報とステータスの概要を返します。
• flight-goat-pp-cli history get-flight — 登録記号、識別子、または fa_flight_id に基づいて、過去のフライト情報のステータス概要を返します。
• flight-goat-pp-cli history get-flight-map — 過去のフライトの航跡を base64 エンコードされた画像として返します。
• flight-goat-pp-cli history get-flight-route — 過去のフライトで提出されたルートに関する情報（座標、名称など）を返します
• flight-goat-pp-cli history get-flight-track — 過去のフライトの航跡を位置情報の配列として返します。

operators — 運航会社を管理します

• flight-goat-pp-cli operators get — 運航会社の名称、ICAO/IATA コード、本社所在地などの情報を返します。
• flight-goat-pp-cli operators get-all — 運航会社の参照情報（ICAO/IATA コードと詳細情報にアクセスするための URL）の一覧を返します。

schedules — スケジュールを管理します

• flight-goat-pp-cli schedules — 航空会社が公開している定期便を返します。

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

やりたいことは分かっていても、どのコマンドを使えばよいか分からない場合は、CLI に直接尋ねてください。

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

which は、自然言語で記述された機能に関する問い合わせを、この CLI の厳選された機能インデックスから最も適合するコマンドに対応付けます。終了コード 0 は少なくとも 1 件の候補が見つかったことを示し、終了コード 2 は確度の高い候補が見つからなかったことを示します。その場合は --help を使うか、検索内容をより具体的にしてください。

認証のセットアップ

flight-goat-pp-cli auth setup を実行すると、キーの取得に必要な URL と手順が表示されます（URL を開くには --launch を追加します）。次に、以下を設定します。

export FLIGHT_GOAT_API_KEY="<your-key>"

認証情報を永続化するには、flight-goat-pp-cli auth set-token <token> を使用します。保存されたシークレットは config.toml ではなく、データディレクトリ内の credentials.toml に格納されます。

flight-goat-pp-cli doctor を実行して、セットアップを確認します。

エージェントモード

任意のコマンドに --agent を追加します。次のオプションが適用されます：--json --compact --no-input --no-color --yes。

• パイプ処理可能 — stdout に JSON、stderr にエラーを出力します

• フィルタリング可能 — --select でフィールドを絞り込めます。ドット区切りのパスでネストされた構造をたどり、配列では各要素を走査します。冗長な API でコンテキストを小さく保つうえで重要です。

  flight-goat-pp-cli airports get mock-value --agent --select id,name,status
  

• プレビュー可能 — --dry-run で、送信せずにリクエストを表示します

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

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

• 明示的な再試行 — すでに存在する項目の作成を成功として扱う場合にのみ --idempotent を使用し、削除対象が見つからない場合を成功として扱う場合にのみ --ignore-missing を使用します

レスポンスエンベロープ

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

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

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

パスと状態

エージェントは、CLI のパス解決機能をランタイム契約の一部として扱う必要があります。

• 1 回の実行で使用するには --home <dir> を指定し、4 種類すべてのパスを 1 つのルート以下に移動するには FLIGHT_GOAT_HOME=<dir> を設定します。

• 特定の種類のパスだけを別の場所にする必要がある場合に限り、種類ごとの環境変数 FLIGHT_GOAT_CONFIG_DIR、FLIGHT_GOAT_DATA_DIR、FLIGHT_GOAT_STATE_DIR、FLIGHT_GOAT_CACHE_DIR を使用します。

• 解決の優先順位は、種類ごとの環境変数、--home、FLIGHT_GOAT_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／キャッシュファイルが格納されます。

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

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

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

  {
    "mcpServers": {
      "flight-goat": {
        "command": "flight-goat-pp-mcp",
        "env": {
          "FLIGHT_GOAT_HOME": "/srv/flight-goat"
        }
      }
    }
  }
  

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

自動学習

この CLI には、自動記録型の学習ループが組み込まれています。CLI が独自に記録を管理します。すべての実行はローカルにジャーナルとして記録され、フラグの指定に失敗した後、修正して再試行すると flag_alias 候補が自動的に導出され、プレイブックのないクエリファミリーで teach を実行すると、そのセッションのジャーナルから playbook_candidate が自動的に合成されます。必要なのは判断だけです。まず recall を実行し、提示された候補に基づいて操作し、最終的な回答を teach し、修正に気づいたら playbook amend を実行します。失敗を手動で記録する必要はありません。

ステップ 1：探索の前に必ず recall

新しいユーザーの質問に対して、一覧表示／検索／詳細確認のコマンドを実行する前に、次を実行します。

flight-goat-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>", "flight-goat-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 を最初に実行します。

ステップ 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 `flight-goat-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.

プレイブックとノートは、リソースごとの処理経路とは独立しています。recall のレスポンスには、プレイブックと Results[] のヒットの両方が含まれることがあります。その場合は両方を使います。プレイブックは実行する手順を示し、リソースのヒットは特定の手順をショートサーキットします。既定では mismatches をスキップし、コールドスタート時の予期しない挙動を調査する場合に限り --debug-mismatches を渡します。

候補の判断に関する詳細：learnings confirm <id> は候補を実体化する前に、その完全なペイロードを出力します。出力されたペイロードが、検証済みの挙動と一致することを確認してください。learnings reject <id> は派生シグネチャをトゥームストーン化し、同じ候補が再び表示されないようにします。エンベロープに含まれるのは、現時点で対応する価値のある候補だけです。未処理の候補全体は flight-goat-pp-cli learnings candidates で一覧表示できます。

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

ステップ 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 セクションが含まれています。他のことをする前に、ステップ 2 の候補分岐に従って処理してください。
• lookup_refresh_available（トップレベル）：クエリ内のエンティティにルックアップ行がありませんが、同期データから取得できる可能性があります。flight-goat-pp-cli sync を実行してエンティティのルックアップを更新してください。
• トップレベルの no_learnings_for_query_family：テーブルに Jaccard の下限値を超える行がありません。完全なコールドスタートです。

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

ティーチングは常に行います。ストアで回答できなかった問い合わせを解決したら、最終的なリソースの対応付けをバックグラウンドでティーチングしてください。呼び出し回数のしきい値はなく、学習する「価値」があるかどうかを判断する必要もありません。ティーチングはループの要です。プレイブックのないファミリーではプレイブックの合成を開始し、同じ対象を指す言い回しは1つのファミリーにまとめられるため、よく似たティーチングがストア内で分断されることはありません。ユーザー向けの応答を組み立てた後、出力する前に、シェルの & を付けて実行してください。これにより呼び出しはすぐに戻ります。

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

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

PII に関するルール：識別子を取り除いた構造上の質問をティーチングしてください。ティーチングする質問やメモには、名前、メールアドレス、電話番号、アカウント ID、その他の個人識別子を決して含めないでください。CLI は明らかなメールアドレスや電話番号の形式がティーチング対象の質問に含まれているかをスキャンして警告しますが、処理はブロックしません。警告に頼るのではなく、ティーチング前に取り除いてください。

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

セッションにプレイブックが「必要」かどうかを判断する必要はありません。プレイブックのないファミリーに対してティーチングを行うと、セッションのジャーナルから playbook_candidate が自動的に合成され、次のセッションで確定または却下されます。明示的なプレイブックフラグを付けるのは、逐語的に記録する価値のある手順をすでに把握している場合に限ってください。たとえば、CLI で明らかにならなかった回避策（黙って破棄されるフラグ、未文書化のパラメーター、ページネーションの工夫、ペイロードの注意点など）です。統合された1回の呼び出し形式を優先してください。リソースの学習とプレイブックを、同じ teach 呼び出しで記録します。

# Common case: record both the resource learning AND the playbook in one call.
flight-goat-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).
flight-goat-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 と同じく、実行結果を待たずに処理を進めます。

flight-goat-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 ノートでの PII の取り扱い

playbook amend のノートは、Printing Press の将来のバージョンで共有知識として上流に送られる可能性があります。上流への提供経路を、後からの情報削除なしで利用できるように、ユーザーを特定できる情報を含めないでください。

• 埋め込まないでください：ユーザーのファイルシステム上のパス、個人用 API キーやトークン、ユーザーのメールアドレス、ユーザーの GitHub ハンドル、または単一ユーザーに紐づく具体的なクエリ履歴。
• 記載してよいもの：エンドポイントの形式、文書化されていないフィールド名、API の注意点、確認されたスキーマのずれ、CLI の仕様に対する回避策、汎用的なページネーションや再試行の方法。

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

ループの効果測定

flight-goat-pp-cli learnings stats は、ローカルの learn_events テーブルから、再利用ヒット率、教示内容の再利用率、プレイブック解決率、候補の確認／却下数を報告します。分母となるデータが蓄積するまでは、各率は null です。データはすべてこのマシン内に保持されます。この CLI でループが役立っているかを確認するために使用してください。

学習の無効化

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

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

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

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

記録は、解決されたデータディレクトリ内の feedback.jsonl にローカル保存されます。FLIGHT_GOAT_FEEDBACK_ENDPOINT が設定され、さらに --send が指定されているか FLIGHT_GOAT_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 ステータスが標準エラーに記録されます。

名前付きプロファイル

プロファイルは、保存したフラグ値のセットで、複数回の実行で再利用できます。スケジュール実行されるエージェントや、定期的に実行されるエージェントが、実行ごとに異なる入力を受け取りながら同じ保存済みフラグを再利用する場合に使用します。

flight-goat-pp-cli profile save briefing --json
flight-goat-pp-cli --profile briefing airports get mock-value
flight-goat-pp-cli profile list --json
flight-goat-pp-cli profile show briefing
flight-goat-pp-cli profile delete briefing --yes

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

終了コード

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

引数の解析

$ARGUMENTS を解析します。

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

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

1. MCP サーバーと付属の CLI（同じバージョン）をインストールします。MCP サーバーは各ツールを実行する際に flight-goat-pp-cli を呼び出すため、CLI もインストールするまでは、すべてのツール呼び出しが「付属の CLI バイナリが見つかりません」というエラーで失敗します。

   go install github.com/mvanhorn/printing-press-library/library/travel/flight-goat/cmd/flight-goat-pp-mcp@latest
   go install github.com/mvanhorn/printing-press-library/library/travel/flight-goat/cmd/flight-goat-pp-cli@latest
   

   サーバーは、まず自身の実行ファイルと同じ場所で CLI を探し、次に FLIGHT_GOAT_CLI_PATH、最後に PATH を確認します。CLI が別の場所にある場合は、MCP ホストの env ブロックで FLIGHT_GOAT_CLI_PATH に絶対パスを設定してください。
2. Claude Code に登録します。

   claude mcp add flight-goat-pp-mcp -- flight-goat-pp-mcp
   

3. 確認します：claude mcp list

直接使用

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

   flight-goat-pp-cli <command> [subcommand] [args] --agent
   

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