pp-seats-aero

Seats.aero — Printing Press CLI

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

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

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

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

2. バージョンを確認します：seats-aero-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/travel/seats-aero/cmd/seats-aero-pp-cli@latest

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

seats-aero-pp-cli は、エージェント向けの出力形式で 7 つすべての Partner API エンドポイント（キャッシュ検索、一括空席状況、トリップ、ルート、目的地、更新、ライブ）をラップし、その後、ルートと空席状況を型付きの SQLite テーブルに同期します。このローカルストアを使うことで、薄いラッパーやウェブアプリでは実現できない new-since、calendar、direct-scan、reach、そしてクォータで制限された recheck を利用できます。

この CLI を使う場面

エージェントがマイレージプログラム別の特典航空券の空席状況を必要とする場合は、いつでも seats-aero-pp-cli を使用してください。たとえば、ある路線で最も少ないマイル数で利用できる特典航空券、プログラムのカレンダー、空港から直行便で行ける範囲、予約前のキャッシュ済み空席の確認などに使えます。マイルやポイントの特典交換を調べる場合や、オフラインで検索できる特典航空券の空席状況データをローカルに蓄積する場合にも適したツールです。

使用しない場面

以下の場合は、この CLI を使用しないでください。

• フライトの予約や発券には使用しないでください。空席状況を報告するだけで、予約は行いません。
• 現金で購入する航空券、ホテルの特典、ポイントの価値評価、移行パートナーの計算には使用しないでください。Partner API にはこれらの情報は含まれていません。
• プッシュ通知アラートの設定には使用しないでください。Seats.aero のアラートはウェブアプリの機能です。代わりに new-since を定期実行してください。
• Pro キーでのライブ検索は想定しないでください。このエンドポイントの利用には商業契約が必要です。

独自の機能

この API 向けに、ほかのツールでは利用できない機能です。

積み重ねて活用できるローカル状態

• new-since — 同期済みのローカルデータを使って、前回確認してから路線に新たに追加された特典航空券の空席を確認します。

  ユーザーが路線の変更点や新着情報を尋ねた場合は、検索全体を再実行して目視で差分を確認する代わりに、この機能を使ってください。

  seats-aero-pp-cli new-since --origin JFK --destination NRT --cabin business --since 24h --agent
  

• direct-scan — 同期済みのすべてのプログラムを一度に調べ、マイル数の上限以下で利用できる直行便の特典航空券を見つけます。

  ユーザーが同期済みデータから、API 呼び出しなしでプログラム横断の直行便のみの結果を求めている場合は、特典航空券の検索よりこちらを選んでください。

  seats-aero-pp-cli direct-scan --origin JFK --destination NRT --cabin business --max-mileage 90000 --sources united,virginatlantic,aeroplan --agent
  

• calendar — ある路線の同期済み空席状況を、一覧しやすい日付別・客室クラス別のマトリックスに変換します。

  ユーザーがある路線でビジネスクラスまたはファーストクラスの空席がある日付を尋ねた場合は、ローカルストアから一度の操作で回答できるこの機能を使ってください。

  seats-aero-pp-cli calendar --origin JFK --destination NRT --source united --start 2026-10-01 --end 2026-12-31 --agent
  

クォータ対応の仕組み

• recheck — 予約の直前に、古くなった特典航空券の行がまだ有効か再確認します。1回の実行につきライブクォータを1回確認し（1日あたり1回の呼び出し）、クォータが不明な場合は、--ignore-quota を指定しない限り --apply は拒否されます。

  デフォルトでは表示のみです。更新対象となる古い行、その経過時間、残りの日次クォータ（クォータ確認の呼び出し1回）を一覧表示します。更新クレジットを消費するには --apply を追加してください。クォータが不明な場合は、--ignore-quota を指定しない限り --apply は拒否されます。

  seats-aero-pp-cli recheck --origin JFK --destination NRT --cabin business --max-mileage 90000 --agent
  

• reach — ある空港から直行便で行ける目的地を探し、料金順に並べ、実際の日付の空席状況と照合します。

  マイルはあるものの、行き先が決まっていないユーザーにはこちらをお使いください。ローカルモードはなく、results は配列ではなく {origin, cabin, max_mileage, source, destinations[]} というオブジェクトです。--confirm-live を指定すると、追加で最大10回のライブ /search 呼び出しが行われます（オプトイン。テストハーネスの実行中は行われません）。

  seats-aero-pp-cli reach --origin JFK --cabin business --max-mileage 90000 --top 10 --agent
  

コマンドリファレンス

2026.8.1 からのアップグレード

seats-aero-partner-search は awards に名称変更されました。旧コマンドは、1回のリリースに限り、非表示の非推奨エイリアスとして引き続き使用できます。その --cabin フラグは --cabins に変更され、カンマ区切りの値を受け付けます。既存のストアは、sync など最初に実行される読み書きコマンドによって移行されます。doctor は読み取り専用で、ストアを変更せずに migration_pending を報告します。

認証情報の環境変数は SEATS_AERO_API_KEY に変更されました。SEATS_AERO_PARTNER_PARTNER_AUTHORIZATION と TOML キー aero_partner_partner_authorization は引き続き有効です。doctor は、選択された credentials_location を報告します。

ストアは、最初の読み書きコマンド（sync または doctor）でインプレース移行されます。一方、レガシーの seats_aero_partner_search テーブルは変更されません。sync --concurrency のデフォルトは 1（以前は 4）になり、--timeout のデフォルトは 1m（以前は 30s）になりました。MCP ツールは awards_cached-search になりました。

availability — 空席状況を管理

• seats-aero-pp-cli availability — 特定のマイレージプログラムから、大量の空席状況オブジェクトを取得します。

awards — 特典航空券を管理

• seats-aero-pp-cli awards — 1つ以上のマイレージプログラムを対象に、1つ以上の出発空港と到着空港の間にある Seats.aero のキャッシュ済み特典航空券の空席状況を検索します。

destinations — 目的地を管理

• seats-aero-pp-cli destinations — 1つの空港から（または1つの空港へ）行ける空港を返します。

live — ライブ検索を管理

• seats-aero-pp-cli live — 商用契約の API キー専用です。Pro キーでは 403 が返されるため、再試行しないでください。レイテンシは5～15秒です。

refresh — 更新を管理

• seats-aero-pp-cli refresh — 古いキャッシュデータの更新に使用します。クレジットが消費され、レスポンスのクォータブロックに残りの更新回数が表示されます。Pro キー専用です。

reach — マイル上限内で直行便の目的地を検索

• seats-aero-pp-cli reach — ローカルモードはなく、results は配列ではなく {origin, cabin, max_mileage, source, destinations[]} というオブジェクトです。--confirm-live を指定すると、追加で最大10回のライブ /search 呼び出しが行われます（オプトイン。テストハーネスの実行中は行われません）。

recheck — 予約前に古くなった特典航空券の行を再確認

• seats-aero-pp-cli recheck — デフォルトでは表示のみです。1回の実行につきライブクォータを1回確認します（1日あたり1回の呼び出し）。クォータが不明な場合は、--ignore-quota を指定しない限り --apply は拒否されます。

routes — 路線を管理

• seats-aero-pp-cli routes — マイレージプログラムについて追跡されている、すべての出発地・目的地間の路線を取得します。

trips — 旅行を管理

• seats-aero-pp-cli trips <id> — 検索結果または空席状況の結果に含まれる再検証 ID／旅行 ID を指定して、空席状況オブジェクトからフライト単位の情報を取得します。

Freshness Contract

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

sync と sync --resources availability では、エンドポイントに source が必要なため、availability を登録できません。各プログラムについて、seats-aero-pp-cli sync --resources availability --resource-param availability:source=<program> --since 7d を一度実行してください。routes リソースにパラメーターは不要です。

対象となるパス：

• seats-aero-pp-cli availability
• seats-aero-pp-cli availability get
• seats-aero-pp-cli availability list
• seats-aero-pp-cli availability search
• seats-aero-pp-cli awards
• seats-aero-pp-cli awards get
• seats-aero-pp-cli awards list
• seats-aero-pp-cli awards search
• seats-aero-pp-cli destinations
• seats-aero-pp-cli destinations get
• seats-aero-pp-cli destinations list
• seats-aero-pp-cli destinations search
• seats-aero-pp-cli routes
• seats-aero-pp-cli routes get
• seats-aero-pp-cli routes list
• seats-aero-pp-cli routes search

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

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

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

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

which は、自然言語による機能の問い合わせを、この CLI の厳選された機能インデックスから最も適したコマンドに対応付けます。終了コード 0 は一致するものが少なくとも 1 つあることを示し、終了コード 2 は確かな一致がないことを示します。その場合は --help に戻るか、より絞り込んだ問い合わせを使用してください。--json（およびその他の機械処理向け形式）でもこの終了コード 2 の仕様は変わらず、stdout に {"matches":[]} を出力します。そのため、エージェントは見つからなかった場合を成功として扱わずに、エンベロープを確認できます。

レシピ

すべてのプログラムを対象に、エージェント向けに絞り込んだ最安のビジネスクラス特典航空券

seats-aero-pp-cli awards --origin-airport SFO --destination-airport NRT --cabins business --order-by lowest_mileage --take 10 --agent --select data.Date,data.Route.Source,data.JMileageCost,data.JDirect

すべてのプログラムを対象にキャッシュ済み検索を一度実行し、--select で幅の広い availability 行から重要な 4 つのフィールドだけを取り出します。

昨日から新たに表示されたもの

seats-aero-pp-cli new-since --origin JFK --destination NRT --cabin business --since 24h --agent

ローカルの availability テーブルを first_seen_at で差分比較し、本当に新しい行だけを返します。

クレジットを消費せず、予約前に確認する

seats-aero-pp-cli recheck --origin JFK --destination NRT --cabin business --max-mileage 90000 --agent

デフォルトでは表示のみです。更新対象となる古い行、その経過時間、残りの 1 日あたりのクォータ（プローブ呼び出し 1 回）を一覧表示します。更新クレジットを消費するには --apply を追加してください。

3 つのプログラムを対象に、90,000 マイル未満の直行便のみを検索

seats-aero-pp-cli direct-scan --origin JFK --destination NRT --cabin business --max-mileage 90000 --sources united,virginatlantic,aeroplan --agent

1 回の呼び出しで 1 つのプログラムしか扱えない一括エンドポイントでは回答できない、同期済みデータを対象とするプログラム横断の結合処理です。

90,000 マイルで、乗り継ぎなしでどこへ行けるか

seats-aero-pp-cli reach --origin JFK --cabin business --max-mileage 90000 --top 10 --agent

destinations を通じて複数の検索を行い、候補ごとに日付指定の座席を照合します。reach にはローカルモードがありません。また、results は単純な配列ではなく、{origin, cabin, max_mileage, source, destinations[]} というオブジェクトです。--confirm-live を指定すると、ライブの /search 呼び出しを最大 10 回追加で実行します（オプトイン方式。テストハーネスでは実行されません）。

認証の設定

Seats.aero Pro のサブスクライバーは、Settings で Partner API キーを作成し、SEATS_AERO_API_KEY としてエクスポートします。キーには Pro ティア（1 日あたり 1,000 回の呼び出しが可能。UTC の午前 0 時にリセットされ、残り回数は X-RateLimit-Remaining ヘッダーで確認できます）と、商用契約キーがあります。Pro キーではライブ検索を呼び出せず、商用キーでは更新を呼び出せません。doctor は 1 日あたりの残り呼び出し回数と、キーがどのティアに該当すると思われるかを報告します。

設定を確認するには、seats-aero-pp-cli doctor を実行してください。

エージェントモード

任意のコマンドに --agent を追加できます。次のフラグに展開されます：--json --compact --no-input --no-color。

グローバル形式フラグは、promoted、novel、sync、および --deliver の各パスで共通の契約を適用します。

• --json — 標準出力に JSON ドキュメントを 1 つ出力します（sync の進捗イベントは標準エラー出力に送られます）

• --compact — ID／ステータス／タイムスタンプの各フィールドを保持します。ドキュメント形式とストリーム形式は変わりません

• --csv / --plain — 表形式の行を出力します（コレクションのエンベロープは行配列に展開されます）

• --quiet — エンベロープなしで、各行につき ID 値を 1 つ出力します

• パイプ処理可能 — 標準出力には JSON、標準エラー出力にはエラーが出力されます

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

  seats-aero-pp-cli destinations --agent --select airport,business,economy
  

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

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

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

• 明示的な確認 — --agent を指定しても --yes は暗黙的に指定されません。対象、引数、副作用を明確に把握した後に限り、別途 --yes を指定してください

• 明示的な再試行 — すでに存在するものの作成を成功として扱う場合に限り、--idempotent を使用してください

レスポンスエンベロープ

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

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

データには .results を、ライブかローカルかの判定には .meta.source を解析してください。人が読める N results (live) の概要が標準エラー出力に表示されるのは、標準出力が端末であり、機械形式フラグ（--json、--csv、--compact、--quiet、--plain、--select）が指定されていない場合のみです。パイプ接続された利用者やエージェント、および形式を明示した実行では、標準出力には JSON のみが出力されます。

パスと状態

エージェントは、CLI のパス解決機能をランタイム契約の一部として扱ってください。

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

• 特定の種類のパスだけを別の場所にする必要がある場合に限り、種類別の環境変数 SEATS_AERO_CONFIG_DIR、SEATS_AERO_DATA_DIR、SEATS_AERO_STATE_DIR、SEATS_AERO_CACHE_DIR を使用します。

• 解決順序は、種類別の環境変数、--home、SEATS_AERO_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 から取り除かれます。

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

• MCP では、MCP ホストの設定を通じてパスの移動先を指定してください。MCP バイナリは CLI フラグを継承しません：

  {
    "mcpServers": {
      "seats-aero": {
        "command": "seats-aero-pp-mcp",
        "env": {
          "SEATS_AERO_HOME": "/srv/seats-aero"
        }
      }
    }
  }
  

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

自動学習

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

Step 1: 新しい質問では、何かを調べる前にrecallを実行します

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

seats-aero-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>", "seats-aero-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 `seats-aero-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>は導出シグネチャをトゥームストーン化し、同じ候補が再び表示されないようにします。エンベロープには、今対処する価値がある少数の候補のみが含まれます。seats-aero-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（トップレベル）：1つのクエリエンティティが複数の正規名に解決されました（例：「Cards」→ Arizona Cardinals + St. Louis Cardinals）。リソースを確定する前に、コンテキストから曖昧さを明示してください。
• candidates_present（トップレベル）：エンベロープにcandidatesセクションが含まれています。他の処理を行う前に、Step 2の候補分岐に従って処理してください。
• lookup_refresh_available（トップレベル）：クエリ内のエンティティにはまだlookup行がありませんが、同期データから取得できる可能性があります。seats-aero-pp-cli syncを実行して、エンティティのlookupを更新してください。
• トップレベルのno_learnings_for_query_family：テーブルには、Jaccardの下限を超える行がありません。完全なコールドスタートです。

ステップ 4: 最終回答の作成後に teach & を実行 - 必ず

教示は無条件です。ストアが回答できなかった問い合わせを解決したら、最終的なリソースマッピングをバックグラウンドで教示してください。呼び出し回数のしきい値はなく、「学習する価値があったか」を判断する必要もありません。教示はこのループの要です。プレイブックのないファミリーではプレイブックの合成がトリガーされ、同じ対象を指す表現は1つのファミリーにまとめられるため、ほぼ重複する教示によってストアが断片化することはありません。ユーザー向けの回答を組み立てた後、出力する前に、シェルの & を付けて実行し、呼び出しがすぐに戻るようにしてください。

seats-aero-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 を使用します。そのため、あるエイリアス（例：「Niners」）で教示すれば、別のエイリアス（例：「49ers」、「San Francisco」）での今後の問い合わせにも自動的に対応できます。

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

ステップ 5: プレイブック - フラグは任意、合成は自動

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

# Common case: record both the resource learning AND the playbook in one call.
seats-aero-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).
seats-aero-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 と同様に、実行後は結果を待たずに先へ進めます。

seats-aero-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 インターフェースに対する回避策、汎用的なページネーションや再試行の方法。

修正点がユーザー固有のコンテキストがなければ意味をなさない場合は、プレイブックへの追記ではなく、個人用メモに記録してください。

ループの測定

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

学習の無効化

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

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

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

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

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

バグ報告ではなく、意外だったことを書いてください。簡潔で具体的な一行が、積み重ねるうえで大切です。

出力の配信

すべてのコマンドで --deliver <sink> を指定できます。出力は、標準出力に加えて（または標準出力の代わりに）指定したシンクに送られるため、エージェントはコマンドの結果を手作業でパイプに渡さずに振り分けられます。利用できるシンクは3種類です。

doctor、agent-context、learnings、feedback の出力には、ローカルパスや自由記述のテキストが含まれる場合があるため、サードパーティの Webhook には送信しないでください。

シンク	動作
stdout	デフォルト。標準出力のみに書き込みます
file:<path>	出力を <path> にアトミックに書き込みます（tmp + rename）。バイナリレスポンスを返すコマンドは、デコード済みのペイロードバイト（base64 の JSON エンベロープではありません）を書き込み、標準出力に小さな JSON レシートを出力します。このシンクが設定されている場合、--json/--csv は拒否されません。
webhook:<url>	出力本文を URL に POST します（application/json）

不明なスキームは、サポートされているスキームを示す構造化エラーとともに拒否されます。Webhook の送信に失敗すると、ゼロ以外の終了コードが返され、URL と HTTP ステータスが標準エラーに記録されます。

名前付きプロファイル

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

seats-aero-pp-cli profile save briefing --json
seats-aero-pp-cli --profile briefing destinations
seats-aero-pp-cli profile list --json
seats-aero-pp-cli profile show briefing
seats-aero-pp-cli profile delete briefing --yes

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

終了コード

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

引数の解析

$ARGUMENTS を解析します。

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

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

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

   go install github.com/mvanhorn/printing-press-library/library/travel/seats-aero/cmd/seats-aero-pp-mcp@latest
   

2. Claude Code に登録します。

   claude mcp add seats-aero-pp-mcp -- seats-aero-pp-mcp
   

3. 確認します：claude mcp list

直接使用

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

   seats-aero-pp-cli <command> [subcommand] [args] --agent
   

4. 判断に迷う場合は、サブコマンドのヘルプを確認します：seats-aero-pp-cli <command> --help。