wayai

WayAI スキル

WayAI は、AI エージェントと人が協力して働き、顧客対応や業務運営を行う場所です。各ハブは AI エージェントと人間のチームで構成され、顧客を中心としたサポートや複数チャネルでの営業から、タスクを中心としたバックオフィス業務までを担います（ハブの種類）。このワークスペースでは、ハブをコードとして管理します。ハブごとに 1 つのフォルダー（hub.yaml + agents/*.{yaml,md} + evals/、journeys/、skills/）があり、wayai CLI を介してプラットフォームと双方向に同期されます。

プラットフォームが信頼できる唯一の情報源です。 ワークスペースのファイルは編集用の画面です。変更はファイル → wayai push → プラットフォームの順に反映されます。範囲外での変更を取り込めるよう、編集前には必ず wayai pull を実行してください。

このスキルの使い方： このファイルは概念の全体像を網羅したものです。WayAI のすべての基本要素を、何を構築し、どのファイルを編集するか判断できるだけの深さで説明しています。フィールドレベルのスキーマ、プロバイダーごとの詳細、仕組みについては references/ に記載しています。以下の各ドメインセクションの末尾に、詳しい説明があるファイルへのリンクがあります。そのドメインの作成やデバッグを始める際に開いてください。ハブ全体をゼロから生成する前に、references/canonical-example/README.md を一度読んでください。各要素の連携方法が示されています。ルーティング表全体は末尾のリファレンスドキュメントにあります。

エージェントのガイドライン

• 毎回のセッション開始時には、ほかのことより先に最新の状態にしてください。 簡単な作業でも毎回行います。まず CLI を更新し、次にこのスキルが古くなっていないか確認し、古くなっていれば更新してください。CLI やスキルが古いことは、以下の手順が機能しない最も一般的な原因です。ワークフロー → 既存のハブの手順 1～2 に記載された手順（コールドスタート：状態マシンの行 1～1c）を実行してください。スキルのインストールコマンドは再入力せず、行 1b から取得してください。その mkdir -p .claude のプレフィックスは Claude Code に必要です。また、インストールに失敗した場合の対応は行 1c に記載されています
• マニュアルではなく、人と話すように答えてください。 ユーザーは WayAI を初めて使うかもしれません。専門用語を避け、わかりやすく説明してください。回答は短く、要点を絞り、聞かれていないことを説明しないでください。困っている様子だったり、何かの意味を尋ねられたりした場合は、1 行で答えて先に進んでください。回答をチュートリアルにしないでください
• インターフェース： セットアップは wayai CLI とワークスペースのファイルで行います。これが唯一の自動化手段であり、ファイルシステムとシェルへのアクセスが必要です（コードハーネス型エージェント — Claude Code、Codex、Cursor、OpenCode）。以下のすべての操作はこれを通じて実行してください。シェルにアクセスできない場合（アプリハーネス型エージェント — Claude Desktop、ChatGPT など）、自分で WayAI を設定することはできません。その場合は、以下の OAuth 接続の引き継ぎと同じ形式（URL 1 つ、アクション 1 つ、完了の合図 1 つ）で作業をユーザーに引き継いでください。「https://app.wayai.pro を開いてください。そこでセットアップするか、シェルを使えるエージェントで実行してください。ワンプロンプトでのインストールは https://wayai.pro にあります。完了したら教えてください。」その後もこのスキルに基づいて回答し、自分が行っていない設定を行ったと報告しないでください
• このスキル、ツールの説明、またはリファレンスドキュメントに記載された情報だけを提供してください
• URL、パス、手順を作り出さないでください
• ハブの設定にはファイルと wayai CLI を使用します。一度限りのセットアップ（組織、OAuth）にはプラットフォーム UI を使用します。プレビューから本番環境への公開は、CLI（wayai publish）または UI で行えます
• 編集前には必ず wayai pull -y を実行してください。範囲外での変更を取り込めます
• 編集直後には必ず wayai push -y を実行してください。編集とプッシュは一連の操作です。ただし、コミュニティの場合は例外です。コミュニティのプッシュはプレビューを経由せず、稼働中のコミュニティを編集します。そのため、変更内容を表示し（wayai push communities/<folder> --dry-run）、ユーザーが指示した場合にのみプッシュしてください
• 自動でコミットしないでください。git diff を表示し、ユーザーの承認を待ってください

クイック判定：何ができますか？

エンティティ	方法
Hub の設定、エージェント、エージェントの指示、ツール、カンバン、状態、スキル、評価、ジャーニー、自動化、カスタムツール	CLI（wayai push）。自動化はアプリから一時停止できます
連絡先と組織のリスト（自動化の対象となる組織の連絡先一覧）	UI（組織の設定 → 連絡先）または API（/api/contact-book）。hub.yaml は使用しません。自動化を参照してください
ベース内の連絡先の顧客レコード（会話で連絡先が指定されたとき、顧客スコープのツールセットが提供するもの）	CLI（wayai contacts link-customer / unlink-customer。ブラウザーサインインのみ）または API（/api/contact-book/contacts/:id/customer）。連絡先とその顧客レコードのリンクを参照してください
Hub リスト（自動化の対象となる、連絡先一覧に対する Hub 独自のフィルター）	CLI（hub.yaml の contact_lists:、wayai push）または UI（Hub → 自動化 → リスト）
評価ジャーニー（Hub のコード管理）— journeys/<slug>.yaml、フラットなフォルダー	CLI（wayai push / wayai pull。初回作成後に pull してステップ ID を同期してください）
接続 — OAuth 以外（エージェントプロバイダー、STT/TTS、Tool API キー、MCP Bearer Token）	CLI（組織の認証情報から自動作成）
接続 — OAuth（WhatsApp、Instagram、MCP OAuth）	プラットフォーム UI
接続の認証情報を直接設定／ローテーション（本番環境を含む）	CLI（wayai set-connection-credential）または UI
組織の認証情報 — 作成／ローテーション／編集	CLI（wayai create-credential / wayai update-credential）または UI
組織レベルの共有スキル（組織のコード管理）	CLI（wayai org pull / push / diff）
ベース — スキーマ、レコード、リレーションシップ、ファイル、ツールセット（データのインターフェース）	CLI（wayai bases、wayai records、wayai record-types、…。wayai pull / push bases/<base> による設定のコード管理）。まず references/bases/README.md を開いてください
プロバイダーへのスキルの同期	CLI（wayai sync-skills）
会話のテスト	CLI（wayai send-message、wayai conversations、wayai delete-history）
Hub の不具合の診断（音声／TTS が配信されない、エージェントが応答しない、ツールが失敗する）— 最初に接続／認証情報の状態を確認してください	CLI（wayai alerts）— 有効な Status & Notices アラートを表示します（例：無効なプロバイダーキーは connection_auth として表示され、通常は 401 です）。コードを読む前、または問題を報告する前に実行してください
理由の分からないエージェントの応答の診断（誤った日付、無視されたルール、幻覚による値）— トランスクリプトから推測せず、エージェントが実際に受け取った内容（解決済みプロンプト、レンダリング済みコンテキスト、挿入されたタイムスタンプ、ツール呼び出し）を確認してください	CLI（wayai conversations <id> observability [--message-id <id>]）— 指示を編集する前に実行してください
終了した会話に、事後的にビジネス成果（例：顧客が購入した）を分析ディメンションとして記録	CLI（wayai conversations <id> annotate --set key=value [--type ...]）
分析	CLI（wayai analytics、wayai analytics query）
コスト／トークン消費の分析（メッセージ、モデル、エージェント、ロール、認証情報ごと）	CLI（message テーブルに対する wayai analytics sql）。references/analytics.mdを参照してください。data.* パスを実行するには明示的なキャストが必要です。また、合計を正しく計算するためのルールも確認してください
評価の実行と結果	CLI（wayai run-eval、wayai eval-results）
音声通話 — Realtime 接続、pilot_voice エージェント、call_utterance ステアリングモニター	CLI（wayai push）または UI。references/calls.mdを参照してください
通話の評価 — 通話モードのテキスト実行、採点対象のマシン通話	CLI（wayai run-eval --call-mode、wayai eval call）。references/evals.mdを参照してください
評価シナリオの一覧表示／評価結果に対する生 SQL	CLI（wayai evals、wayai evals sql）
本番環境の会話を評価としてキャプチャ	CLI（wayai eval capture <conversation_id>）
本番環境の会話をジャーニーとしてキャプチャ（複数ターンのトランスクリプト全体）	CLI（wayai eval journey capture <conversation_id>）
実行中の評価セッションを停止	CLI（wayai eval session stop <session_id>）
評価セッション／実行履歴を削除	CLI（wayai eval session delete <session_id>、または --all を指定して Hub 上のすべてのセッションを削除）
バグ報告	CLI（wayai report create）
ワークスペースの検出	CLI（wayai list）
コミュニティ — 組織のコミュニティ一覧、参加リンクの確認／ローテーション／無効化、統計の確認、招待制コミュニティのアクセスリストの確認	CLI（wayai communities。ブラウザーサインインのみ）または UI。references/communities.mdを参照してください
コミュニティ — 名前、設定（参加可能なユーザー：admission）、ルール、参加リンクの有効／無効状態、ルーム、コース（モジュール、レッスン）	CLI（wayai-ws/communities/<folder>/、wayai pull / push communities/<folder>。push でライブのコミュニティを編集）または UI。references/communities.mdを参照してください。モデレーション：UI
組織 — 作成	CLI（wayai org create）または UI
組織 — 更新、削除	UI
プレビューを本番環境に公開／同期	CLI（wayai publish、エイリアス wayai sync）または UI
Hub の削除	UI
プレビューの複製、プレビューのラベルの設定／解除	CLI（wayai replicate / wayai relabel）または UI
チーム、チームユーザー、Hub ユーザー、管理者、連絡先の承認	UI（Hub → ユーザータブ）
組織タグ（作成、表示名／色の編集 — スラッグは固定）	UI（hub.yaml の tags: からスラッグで参照）

エンティティ階層

Organization                ← CLI (`wayai org create`) or UI
├── Org Credentials         ← CLI (`wayai create-credential`/`update-credential`) or UI — API keys stored once, reused across hubs
├── Org Tags                ← UI — gate which credentials each hub can resolve and which contacts it sees
├── Org Skills              ← CLI (`wayai org pull/push`) — shared skills, fan out to linked hubs
├── Bases                   ← CLI (`wayai bases`) — the Data surface. Org-level, NOT inside a hub (see Bases)
├── Contact book            ← UI (Contacts) or API — contacts + org lists that automations target. Org-level, NOT in `hub.yaml`
└── Hub                     ← CLI (`wayai create`, or auto-creates on push) or UI; publish/sync via CLI (`wayai publish`) or UI
    ├── Connections         ← auto-created from org credentials on push (non-OAuth); OAuth via UI
    ├── Channels            ← auto-provisioned, never authored (see Channels)
    ├── Agents              ← CLI — `agents/<slug>.yaml` + `<slug>.md`
    │   ├── Tools           ← CLI — native, custom HTTP, MCP, delegation
    │   └── Skill links     ← CLI — `skills:` block in agent YAML
    ├── Kanban statuses     ← CLI — `hub.yaml` (workflow stages for conversations)
    ├── States              ← CLI — `hub.yaml` (JSON-schema data agents read/write)
    ├── Skills              ← CLI — `hub.yaml` `skills:` + `skills/` folder
    ├── Evals + Journeys    ← CLI — `evals/`, `journeys/`
    ├── Hub lists           ← CLI — `hub.yaml` `contact_lists:`; filters over the contact book (labels, scope tags)
    ├── Automations         ← CLI — `hub.yaml`; paused in the app; each targets a hub list or an org list by name
    └── Teams + Users       ← UI (Hub → Users) — teams, admins, team users, hub users

セットアップの順序：Organization（CLI wayai org create または UI）→ Org Credentials（CLI または UI）→ Hub（CLI wayai create、または push により自動作成、または UI）→ CLI でエージェント、ツール、接続を設定します。

wayai 接続（ネイティブツール）は Hub の作成時に自動作成されるため、セットアップは不要です。

Hub の種類

種類	会話	チャネル	用途
chat	エンドユーザーごとに 1 つ	WhatsApp、Instagram、Email、Telegram、App	人を中心とする用途：サポート、営業、ヘルプデスク
task	ユーザーごとに複数	App のみ	タスクを中心とする用途：請求書、在庫、承認

判断基準：外部チャネル（WhatsApp／Instagram／Email／Telegram）が必要 → chat。オブジェクト／タスクの処理 → task。

AI モードと会話モデル

Hub レベルの ai_mode で AI の動作を設定します。

モード	動作
pilot	AI がエンドユーザーに自律的に対応します
copilot	AI がサポートチームに返信案を提示します（チャネルへの配信はありません）
pilot+copilot	現在誰が対応しているかに応じて動的に切り替わります
turned_off	AI は無効になり、人間のみが対応します

会話とは、エンドユーザーと Hub 間の実行時セッションです（設定エンティティが動作を定義し、会話とメッセージがその動作の対象になります）。

• conversation_status：agent（AI が対応）｜team（人間のチームが対応）｜ended（終了し、アーカイブ済み）
• ステータスによってアクティブなエージェントのトラックが選択されます：ステータスが agent → Pilot トラックがチャネル経由でエンドユーザーに返信します。ステータスが team（copilot／pilot+copilot モードの場合）→ Copilot トラックが /support でチームに提示する返信案を作成します
• トラックの切り替え：transfer_to_team ツール（agent → team）、またはサポート UI でチームが引き継ぎます（team → agent）。transfer_to_agent／consult_agent は、トラック内でエージェント間を移動します
• 終了方法：エージェントの close_conversation ツール、isTerminalStatus のカンバンステータスへの遷移（エージェントまたはハーネスツール、チームによるドラッグ＆ドロップ、REST など、どの手段でも可）、チーム UI、または Hub の auto_close_inactive_days。終了した会話はアーカイブされ、「Ended」タブに表示されます。conversation_retention_days の期間内であれば、事後に wayai conversations <id> annotate を受け付けます
• エージェントの返信テキストは自動的に配信されます。メッセージ送信ツールはありません。ツールは返信以外のアクションに使用します

カンバンステータスはこれらとは独立しており、対応者ではなく、カスタムスラッグ（qualified など）でワークフローの段階を追跡します。

エージェントの役割

役割	トラック	ハブあたりの数	説明
pilot	Pilot	1	エンドユーザーに自律的に応答します
copilot	Copilot	1	サポートチームに応答を提案します
pilot_specialist / copilot_specialist	両方	複数	委譲先 — transfer_to_agent を介して完全に引き継ぎます
pilot_advisor / copilot_advisor	両方	各1	consult_agent を介して助言を提供し、制御を戻します。モデル接続上でのみ実行され、ホスト型エージェント接続では実行されません
monitor	バックグラウンド	トリガーの発火ごとに1	目立たない形で監視します。user_message では、そのルールにより、作成したメモで応答担当エージェントに状況を伝える、より詳しく確認するために別のモニターを実行する、会話を別のエージェントまたは人間のチームに引き継ぐ、といった処理を同じメッセージに対して実行できます。assistant_reply では返信ゲートとして、送信前の下書き返信を確認し、チームの確認用に保留したり、エージェントに一度だけ書き直させたりできます。call_utterance ではライブ音声通話を監視し、作成したメモで音声の応答を誘導できます。automation_fire では自動化のゲートとして、各実行の前に実行するか、別のエージェントで実行するか、スキップするかを判断します。automation_item では、リストの実行に含まれる各連絡先について、開始するか、別のエージェントで開始するか、スキップするかを判断します。manual（任意の数 — 別のモニターから呼び出されたときのみ実行されます）と2つの自動化ゲート（任意の数 — 各自動化がそれぞれ指定します）を除き、各トリガーで有効にできるモニターは最大1つです
conversation_evaluator / message_evaluator	バックグラウンド	各1	非同期の品質評価を行います。通常のルーティングからは除外されます。evaluation_variables は Analytics に渡され、message_evaluator は評価実行のスコアも付けます
summarizer	バックグラウンド	1	最初の pilot/copilot とともに自動プロビジョニングされます。その接続上で実行されますが、その接続がホスト型エージェント接続の場合は除きます（summarizer はモデル接続上でのみ実行されます）。古いメッセージのローリング JSON 要約を、予約済みスラッグ conversation_summary を使って会話状態として保存します。有効な入力トークン数が summarizer エージェントの summarization_threshold_tokens（既定値は120000。以下を参照）のしきい値を超えると、ターン後に非同期で実行されます。バックグラウンド以外のエージェントには、要約が <conversation_summary> ブロックとして表示され、expand_summary(section_id) を呼び出すことで元のメッセージを取得できます。スキーマはユーザーが編集できますが、アンカーの不変条件（sections[].id、message_id_start、message_id_end）を満たす必要があります
pilot_voice	Pilot（ライブ通話の音声）	複数（通話に応答するのは1つ）	ハブのライブ AI 音声通話を担当する音声エージェントです。通話相手と話し、その指示に従って質問を pilot に引き渡し、pilot が回答します。Realtime 接続のみをバインドします。テキストターン、評価実行、引き継ぎで実行されることはありません — 音声通話を参照してください
consultant	トラック非依存（オンデマンド）	複数	人やエージェントから、目に見える相談スレッドで相談を受けます。pilot/copilot の応答担当にはならず、自動実行もされず、引き継ぎ先やアドバイザーの対象にもなりません。アドバイザーはターンの途中で AI に助言し、目に見えません。consultant は目に見えるスレッドで人やエージェントから相談を受けます。 相談ターンは通常のフォアグラウンド処理として課金されます。サポートチームは、サポート用コンポーザーでタグ付けすることで相談できます（support-inbox.md）

transfer_to_agent の対象は同じトラックの任意のエージェントです。*_specialist だけでなく、エントリーポイントの pilot / copilot も対象となるため、pilot はハブアンドスポーク型ルーターとして機能できます（スペシャリストは、ドメインをまたぐリクエストを pilot に戻して再割り当てできます）。トラックをまたぐ役割、アドバイザー、consultant、バックグラウンドの役割は、引き継ぎ先にはなりません。

役割の流れ、委譲、設定の詳細については、references/agents/roles-and-settings.mdを参照してください。

ハンドオフコンテキストエンジニアリング

会話の担当が変わるとき（transfer_to_agent または transfer_to_team）、再開する担当者は履歴を一から再構築します。その際、以前のすべてのエージェントの発言は区別のない assistant メッセージとして扱われ、人間チームの発言には話者が割り当てられません（モデルは、どの発言を自分が作成し、どの発言を引き継いだのかを判別できません）。ランタイムはこのギャップを自動的に埋めるため、エージェントはそれと連携するように作成してください。

• ランタイムは、永続的な引き継ぎマーカー（This conversation was handed off from X to Y.）を各 transfer_to_agent と transfer_to_team で保存し、受け取る エージェント の最初のターンに 一度限りの継続メモ を送ります（エージェントからエージェントへの引き継ぎのみ。チームへの引き継ぎでは、説明を受ける AI の受け手はいません）。これらをあなたが記述する必要はありません。そのため、エージェントの指示に「この会話がたった今引き継がれた」といった前置きを書かないでください。この処理はランタイムが行うため、重複します。
• 各エージェントの指示は、必ずそのエージェントの役割から始めてください。「あなたは 、<role/purpose> を担うエージェントです……」のように記述します。ランタイムは引き継ぎの際に役割を補強しますが、システムプロンプトは最も強いシグナルであり、通常の各ターンに常に存在する唯一のものです。引き継ぎマーカー（「……Y へ」）が適切に機能するのは、エージェントが自分を Y だと認識している場合だけです。
• 専門エージェントは作業を行う必要があり、処理をたらい回しにしてはいけません。 ランタイムは、同じターン内で以前に会話を担当したエージェントへの再委任（A→B→A や、それより長い再訪）をブロックします。引き継ぎはエラーとともに拒否され、エージェントにはタスクの完了、別のエージェントへの引き継ぎ、またはユーザーへの制御の返却が求められます。そのため、指示に従って会話を委任元へ反射的に返す *_specialist は作成しないでください。ガードに阻止されるだけです。（チェーンはユーザーのターンごとにリセットされるため、後のターンで以前のエージェントに再度割り当てることは問題ありません。）

Summarizer エージェントの設定

Summarizer エージェントは、agents/summarizer.yaml のトップレベルキーとして summarization_threshold_tokens（デフォルトは 120000、最小値は 1000、最大値は 1000000）を公開します。テスト時は値を下げ、非常に長い会話では値を上げてください。Summarizer の connection は、パイロットの設定をデフォルトとして使用します（パイロットの接続がホステッドエージェント接続の場合は、設定されません。その場合はモデル接続に Summarizer を追加してください）。モデルまたはシステムプロンプトを変更するには、agents/summarizer.yaml を編集します。conversation_summary 状態のスキーマは、他の状態と同様にラウンドトリップできます。アンカー以外のフィールドを追加できますが、アンカーは必須です。（以前はハブレベルの hub.yaml 設定でしたが、Summarizer エージェントに移動しました。）

接続と認証情報

接続とは、コネクター（LLM プロバイダー、チャネル API、ツール API、音声サービスなどのカタログ項目）に認証情報を設定したインスタンスで、1 つのハブにスコープされます。組織の認証情報はシークレットを組織レベルで一度だけ保存し、接続は名前で参照します。生のシークレットが YAML に入ることはありません。

カテゴリ	例
エージェント	OpenAI、Anthropic、Google AI Studio、OpenRouter、xAI（AI に必須）
チャネル	WhatsApp、Instagram（OAuth — UI のみ）；Resend（メール）、Telegram（API Key — 自動作成）
ツール — ネイティブ	Wayai（自動作成）、External Resources（API Key）、Base Toolset（Bearer Token — ベースの 1 つのツールセットに紐付けられたトークン）
ツール — カスタム	ユーザー定義の HTTP エンドポイント（API Key、Bearer Token、Basic Auth）
ツール — MCP	外部 MCP サーバー（Streamable HTTP）— CLI 経由の Bearer Token；UI 経由の OAuth
音声	STT は受信した音声メモを書き起こします（Groq、OpenAI、ElevenLabs）。アプリの入力欄には、STT 接続が有効なハブでのみ、エンドユーザーとチームの両方に音声メッセージボタンが表示されます。TTS は音声の返信を合成します（OpenAI、Groq、ElevenLabs、Google）。いずれも音量は同じです
リアルタイム	OpenAI GPT-Live — ライブ AI 音声通話で使用される音声。pilot_voice エージェントのみで使用されます

自動作成ルール： OAuth 以外の接続（Agent、STT、TTS、Realtime、Tool — Custom、Bearer Token 経由の Tool — MCP）は、hub.yaml がプッシュされると、一致する組織の認証情報から自動作成されます。一致判定では組織タグ（タグなしの認証情報はグローバルで、すべてのハブが使用できます。タグ付きの認証情報は、1 つ以上のタグを共有するハブからのみ参照できます）と認証情報のenvironmentが考慮されます。OAuth 接続は、事前に UI で設定する必要があります。

OAuth 接続の引き継ぎ（いつでも可能 — 初回設定時に限りません）： OAuth 接続（WhatsApp、Instagram、MCP OAuth）は CLI から作成できず、一度だけ UI での操作が必要です。初回設定時でも後からでも、新しいチャネルや OAuth MCP サーバーなどが必要になった場合は、ユーザーに接続タブへのフルパスのディープリンク https://app.wayai.pro/settings/organizations/<orgId>/hubs/<hubId>/connections?connector=<slug>（<orgId>／<hubId> は wayai status --json から取得；<slug> ∈ whatsapp、instagram、mcp-server）を渡し、完了後に wayai pull -y を実行します。このディープリンクを開くと接続タブが表示されます（すでに接続がある場合は、再認証などのためにコネクターが強調表示されます）。接続を作成するには、ユーザーが接続を追加をクリックし、**<Connector>**カードを選択して、OAuthを選び、プロバイダーのフローを完了します。このタブ形式を使用してください。connector_id UUID を必要とし、最初の認証タイプをデフォルトで選択する /connections/new?connector=… は使用しないでください（MCP の場合は Bearer Token が選択されるため、MCP OAuth を利用できません。詳しくは navigation.md を参照）。

プロバイダーごとの設定、認証情報のバインド（credential:、no_auth:）、タグ、本番用認証情報の分離については、references/connections.md を参照してください。

チャネル

ハブ上の通信エンドポイントです。メッセージの受信先であり、返信の配信先です。チャネルを YAML で作成することはありません。

• app（アプリ内チャット）と system（内部）チャネルは、ハブとともに自動作成されます
• WhatsApp／Instagram／Email（Resend）／Telegram のチャネルは、それぞれのチャネル接続が作成されると自動的に設定されます

チャネルの一意性（電話番号／ページ／受信アドレス）は本番ハブ間でのみ適用されます。プレビューは本番環境とエンドポイントを共有でき、外部チャネルは #test CODE によるテスター登録でプレビュー上でもテストできます（ハブ環境を参照）。

音声通話

chat ハブでは、Web アプリのチャットビューからAI とリアルタイムの音声通話ができます。発信者が音声通話を開始を押すと、AI と話していることを知らせる案内（WayAI の案内、または音声エージェントがその言語で話す独自の冒頭メッセージ）が流れ、音声で会話できます。任意のハブを音声通話用に設定できます。WayAI はプラットフォーム全体で音声通話を無効にできます。無効になっている間は、wayai push は Realtime 接続や pilot_voice エージェントの作成、以下の要素のいずれかを有効にすることを拒否し、Voice calls are not enabled for this platform, so … と表示します。このメッセージが表示されたら作業を止めて、ユーザーに伝えてください。

• 音声は、（組織独自の OpenAI プロジェクトキーを使う）Realtime 接続上の pilot_voice エージェントです。設定項目は、音声、言語、通話制限、通話を録音するかどうか（デフォルトではオフ）、回答を待つ間に進捗を知らせるかどうか、固定の文言（あいさつ、案内、繰り返し、謝罪、タイムアウト）です。従うルールは指示のみです。話し方と、すべての質問をパイロットに渡す方法を設定します（設定例から始めてください）。
• 回答は、音声から質問を引き継いだときにハブのパイロットが行います。指示でそのように定めてください。パイロットは、音声から引き継いだ質問ごとに、ツール、モニター、返信ゲートを使った通常のターンを実行します。AI が回答してよいかどうかは、テキストの場合と同じルールで判断されます。ルール上回答できなくなった時点で通話は終了します（チームへの転送、テイクオーバー、終了など）。
• 副作用を伴うアクションは、発信者が口頭で「はい」と答えるまで実行されません。call_utterance モニターで、通話中に音声を誘導できます。wayai run-eval --call-mode と wayai eval call で通話を評価できます。
• **課金：**音声から引き継いだ質問ごとに 1 オペレーションが課金され、さらに通話の接続時間（分）に応じた料金がかかります。

セットアップ、通話の終了、チーム側の表示、録音、課金、制限については、references/calls.mdを参照してください。

ツール

エージェントごとの機能はagents/<slug>.yamlで割り当てます。テキストで返信するだけならツールは不要です。ツールは、それ以外のすべてに使います。

種類	ソース	方法
ネイティブ	プラットフォーム組み込み（例：update_kanban_status、get_state、send_files、close_conversation、read_file）	tools.nativeの下に名前を記載
カスタム	定義した HTTP エンドポイント	connection、method、path、configを指定してtools.customの下に定義
MCP	接続済み MCP サーバーのツール	2 つの割り当て元：エージェントごとにtools.mcpの下で宣言、またはプラットフォーム UI で割り当てます。wayai pushは 1 回の実行で検出と割り当てを行います。mcpキーが存在する場合（[]の場合も含む）はその設定が優先され、省略した場合は UI で割り当てたツールが保持されます。native-tools.mdを参照してください。
委譲	エージェント間（transfer_to_agent、consult_agent、start_consult_thread）、エージェントからチームへ（transfer_to_team）、またはエージェントからハブへ（delegate_to_hub、start_consult_thread）	target（エージェントの表示名、チーム名、またはハブ名）を指定してtools.delegationの下に宣言

メタツール（get_tool_schema、execute_tool）を使うと、インラインリストからスキーマが除外されたツールをエージェントが呼び出せます。ネイティブツールの全カタログとパラメーターについてはreferences/agents/native-tools.md、カスタムツールのスキーマについてはreferences/agents/custom-tools.md、公開するツールやパラメーターの設計についてはreferences/agents/tool-principles.mdを参照してください。

Hub への委任（delegate_to_hub）

別の Hub をコンサルタントとして扱います。このツールは対象 Hub でタスクの会話を開始し、その Hub の回答は、リクエスト元の consult スレッドにメッセージとして非同期で返されます。そのため、タグ付けエージェントのターンは直ちに終了し、結果を待ってはいけません。

- type: hub
  tool: delegate_to_hub
  target: Billing Hub        # a PRODUCTION (published) hub in the same organization
  context_boundary: summary  # instruction | summary | transcript

• target は、同じ組織内で公開済み（本番）の hub_type: task Hub である必要があります。分岐のセマンティクスに合致するため、本番環境が必要です。また、タスク Hub ではリクエストごとに独自の会話が作成されますが、chat Hub ではユーザーごとに会話が1つだけ作成されるため、委任のたびに1つのスレッドへリクエストが積み重なり、複数の顧客のやり取りが混在してしまいます。組織をまたぐ Hub、未公開の Hub、または chat タイプの Hub を対象にすると、プッシュ（実行時にはツール呼び出し）に失敗します。
• 対象 Hub は、開始された会話を必ずクローズする必要があります。クローズが完了シグナルになります。リクエスト文ではクローズするよう指示していますが、エージェントがクローズできない（close_conversation ツールがない、または終了状態となるカンバンステータスがない）対象 Hub では、依頼元が待ち続けることになります。（エージェントが開始する consult には有効期限があります（start_consult_thread を参照）。一方、チームが開始する Hub 委任には有効期限がないため、対象 Hub が完了できる方法を用意してください。）
• context_boundary はデータ機密性に関する判断であり、調整用のつまみではありません。Hub ごとにチームメンバーや閲覧できる情報が異なる場合があるため、慎重に選択してください。あらゆる Hub の組み合わせに適した安全なデフォルト値はありません。

値	対象 Hub に渡される情報
instruction	エージェント自身のリクエストのみ。会話からの情報は渡されません。
summary（デフォルト）	リクエストと、随時更新される会話の要約。
transcript	リクエストと、顧客との会話の完全なトランスクリプト。

内部の consult 通信はどの設定でも外部に渡されません。また、モデルは対象 Hub を選択することも、境界を広げることもできません。どちらも管理者の設定です。

• consult スレッド内でのみ利用できます。結果はそのスレッドに配信されるため、consultant ロールのエージェントに割り当ててください。会話がクローズされた後に結果が届いた場合は破棄されます（スレッドには cancelled_at_close として記録されます）。
• v1 では CI/YAML からのみ設定できます。Hub ピッカーと境界の設定機能が提供されるまでは、Platform UI のツール「Add」グリッドには表示されません。このツールの追加には、上記2つの選択が必要なためです。

エージェント起点の相談（start_consult_thread）

バックグラウンドではないエージェントが、設定済みの相談役（またはパートナーハブ）に、サポートチームが確認できる相談スレッドで質問できるようにします。人間が相談役にメンションする場合、エージェントがハブに委任する場合に続く、相談基盤を開始する3つ目の方法です。

- type: agent
  tool: start_consult_thread
  target: Billing Expert     # a `consultant`-role agent on this hub

• モードは対象によって決まります。 同じハブの相談役はツール呼び出し内で回答しますが、パートナーハブからの回答は非同期です。質問したエージェントはターンを終了し（「確認して折り返します」）、回答が届くと自動的に再開します。同期型の相談が長引くと自動的に非同期に切り替わるため、どの対象であっても「回答は後ほど届きます」と伝えられるよう、エージェントへの指示を設定する必要があります。パイロット、コパイロット、およびそのスペシャリストを除き、相談役を実行できるのはモデル接続のみであり、ホスト型エージェント接続（Claude Agent (Managed)）では実行できません。そのような接続で相談役を保存しようとすると拒否され、そこで相談しようとした場合や接続がない場合も、送信前に拒否されます。
• 相談役から相談役への連鎖はデフォルトで無効で、有効にしても同期のみです — ツールで allow_consultant_chain: true を設定すると、同じハブ内の相談役間で連鎖を許可できます。monitor、評価者、summarizer が相談を開始することはできません。
• 予算は厳格に適用されます：相談連鎖の深さに加え、両方向の循環（ハブ内のエージェント A → B → A、ハブ間のハブ A → B → A）を拒否し、LLM 呼び出しごとの上限と会話ごとの永続的な上限を設けています。相談の各ターンではフォアグラウンド操作の料金が発生するため、これらの上限によって、エージェントが監視されないままコストを増大させるのを防ぎます。
• 未回答のまま放置されることはありません：回答されない相談は期限切れとなり、タイムアウト通知とともに質問者が再開します。会話終了時に未完了の相談がある場合は、cancelled_at_close として記録されます。
• エージェント起点のスレッドにチームメンバーが投稿すると、担当は永久にチームへ移ります — そのスレッドで AI が再開することはなくなり、以降の相談には「チームが引き継ぎました」という固定メッセージが返されます。
• delegate_to_hub と同様、v1 では CI/YAML 経由でのみ設定できます。

すべてのパラメーターと YAML の形式については、references/agents/native-tools.md を参照してください。

カンバンとステート

カンバンのステータスは、会話のワークフロー段階です（サポート／タスクの各ビューに表示されます）。hub.yamlでハブごとに定義します。

• 識別情報：変更できない小文字のslug（会話、分析、ツールのパラメーターに保存されます。名前の変更はできません）と、自由に編集できる表示用のnameがあります。ツールが受け付けるのはスラッグのみです（表示名はラベルとして付随します）。指示ではステータスをスラッグで指定する必要があります
• 動作フラグ：isInitialStatus（ハブごとに必ず1つ）、triggersAgentResponse（遷移によってエージェントのターンを開始）、allowsAgentUpdate、isTerminalStatus（このステータスに入ると会話が終了します。ハブごとに最大1つ）、isSchedulingStatus（およびeventName）。一部の組み合わせは相互に排他的で、書き込みのたびにサーバー側で検証されます
• allowed_next_statuses — 任意の遷移許可リストです。すべての操作画面で実行時に適用されますが、次の2つは例外です。エージェント以外の呼び出し元が終端ステータスに遷移する場合（REST 操作画面。ボード経由とプログラム経由の両方。エージェントには引き続き制限が適用されます）、および、終端ステータスにある未終了の会話を再終了する場合（エージェント以外のREST呼び出し元は、プログラム経由も含めて対象です。エージェントは、保存済みの結果を再利用する場合、ステータスに結果が定義されていない場合、または選択した結果に制限がない場合に限ります）。省略すると制限なしです。[]は拒否されます（isTerminalStatusを使用してください）
• 結果 — 終端ステータスのみ、outcomes: [{slug, name, color?, from_statuses?}]を宣言できます（解決済み／キャンセル済みなどのクローズ時の処理）。from_statusesは空でない遷移元スラッグの許可リストです。省略すると、どの遷移元からの結果も受け付けます。終端カンバンステータスへの通常の遷移には、適用可能な結果が必要です。そのスラッグは分析用にdata.meta.outcomeとして保存されます。エージェントによる終了（close_conversation、ハーネスのend_conversation）もこの遷移を通り、同じ制限が適用されます。チームの「閉じる」ボタン（ウェブとモバイル）もこの遷移を通り、先に結果を選択するよう求めます。ただし、エージェント以外の呼び出し元には、前述のallowed_next_statusesの終端ステータスに関する例外が適用されます。会話の現在のステータスから選択できる結果がない場合は、会話が終了できなくなるのを避けるため、結果を指定しない通常の終了に切り替わります。非アクティブ状態による自動終了とPOST /:id/closeでは、結果は設定されません
• フォローアップ — ステータスごとに設定する時間指定メッセージです。inactivity（無応答後）、before_event（イベントまでのカウントダウン）、inactivity_after_event（訪問後のフォローアップ。最初のステップはイベントから、以降の各ステップは直前のフォローアップから起算）、またはinactivity_after_before_event（同じフォローアップですが、after_followup_idで指定した特定のbefore_eventの実行時に開始）を設定できます。最後の3種類にはisSchedulingStatusが必要です。また、会話にscheduled_event_dateが含まれていない限り、いずれも有効になりません。この値は遷移時に指定し、ステータス設定には含めません。しきい値／時間単位、静穏時間、祝日の除外を設定できます
• 遷移時の追加コンテキスト — triggersAgentResponseステータスには、additional_context_schema（チームが遷移時に入力するJSON Schema形式）とadditional_instructions（{{path.to.field}}／{{additional_data}}プレースホルダーを含む文章テンプレート。トリガーされたターンに挿入されます）を宣言できます
• レーン — 任意の表示上のボードグループ分けです。動作への影響はありません

すべてのフィールド仕様、制約マトリックス、警告、および完全な例については、references/kanban.mdを参照してください。

ステートは、エージェントが会話中に読み書きするJSON Schemaデータです。ネイティブツール（get_state、update_state、set_state_path、reset_state。いずれもslugでステートを指定します）と、指示のプレースホルダー{{state(scope, slug)}}を通じて利用します。各ステートにはconversationまたはuserのスコープ、json_schema、任意のinitial_valueがあります（初回の実際の書き込みまで表示される、事前入力済みの仮想レコードです。省略すると、書き込みがあるまでステートは表示されません）。

**カンバンとステートの違い：**カンバンはワークフローの進行状況を追跡し、ステートは構造化データを追跡します。両方を併用できます。スキーマとパターンについては、references/states.mdを参照してください。

スキル

エージェントに紐づけられるスキルです。コンテンツは skills/<skill_name>/ 配下の実ファイルとして保存されます（スキルのコンテンツの正本はファイルシステムです）。hub.yaml の skills: で宣言するのは、名前、skill_name、説明のみです。

種類	内容	実行時の動作
skill	バージョン管理された機能パッケージ — SKILL.md（frontmatter の name と description）と、任意の references/	エージェントは skills/<skill_name>/… にあるファイルを読み込みます（list_files、read_file、{{file_content(skills/…)}}）。エージェントが処理するテキスト（指示、設定、モニターのメモ、自動化、カンバンのフォローアップ、カスタムツール、スキルの説明）内で resources/ 配下のスキルが参照されている場合、保存とプッシュは拒否されます。呼び出し可能なツールとして注入されます（デフォルト。すべてのプロバイダーで動作）。または、プロバイダーコンテナでネイティブ実行されます（use_native_integration: true、Anthropic/OpenAI のみ。wayai push 時にプロバイダーへ自動同期され、失敗後や接続追加後の再同期には wayai sync-skills を使用します）。

ナレッジリソースは廃止されました。ドキュメント（FAQ、カタログ、ポリシー）は組織のナレッジベースに保存され、Base Toolset 接続を通じてエージェントが data/<file type>/… から読み込みます（Bases）。

エージェントは agents/<slug>.yaml の skills: ブロックで、名前と skill_id、priority を指定してスキルを紐づけます。複数のハブで共有する組織レベルのスキルは、wayai org pull/push を通じて wayai-ws/org/（skills.yaml と skills/<skill_name>/）に保存されます（プッシュすると、紐づけられたすべてのハブに配信されます）。プッシュは宣言的です。hub.yaml からスキルを削除すると（最後のスキルも含む）、そのスキルは削除されます。

スキルより前にプルされたフォルダーには、resources:（hub.yaml とエージェントファイル内）と resources/ フォルダー（組織の場合は org/resources.yaml）があります。wayai push、diff、publish（および org push／org diff）は、送信前にこれらを拒否します。wayai pull（wayai org pull）はこれらを変換し、resources/ 内で書き込み先のスキルフォルダーではないもの、またはすでに skills/ 内にあるものを検出すると、その名前を示して停止します（ナレッジのバックアップの場合は、ワークスペースの外へ移動してください）。この機能には @wayai/cli 0.3.234 以降が必要です（wayai update）。古い CLI で旧形式のフォルダーをプッシュすると、フォルダー名を示す 400 エラーで拒否されます。変換済みフォルダーをプッシュしてもスキルは変更されません。旧形式のフォルダーに対して wayai pull を実行すると、比較時に同じ 400 エラーが発生し、変更内容を一覧表示できません（プルする前に更新してください）。また、wayai org pull／push／diff と sync-skills は 404 エラーになります（旧パスは廃止されています）。詳細は references/skills.md を参照してください。

ファイルの取り扱い（テキストとバイナリ、上限 10 MB）、スキルの作成、実行モードについては、references/skills.md を参照してください。

Bases（データサーフェス）

ベースは、組織レベルのデータコンテナです。ハブを支える信頼できる情報源です。ハブには会話が保存され、ベースには会話が扱う構造化データが保存されます。同じ CLI、同じログイン、同じワークスペースを使いますが、独自のサブツリーと専用の昇格コマンドを持つ別のエンティティです。

• **プリミティブ：**レコードタイプ → レコード、リレーションシップタイプ → リレーションシップ、ファイルタイプ → ファイルに加え、アクションとツールセット（エージェントが呼び出す、厳選された MCP ツール）、トリガーと受信 Webhook（変更の送受信）、外部ソース（外部 API をレコードタイプのバックエンドにする）、シードフィクスチャ（隔離された評価用データ）
• 唯一のルール：設定の書き込み（レコードタイプ、リレーションシップタイプ、ファイルタイプ、トリガー、受信 Webhook、アクション、ツールセット、シード）が反映されるのはプレビューベースだけです。データの書き込みはどのベースでも機能します。昇格は人が実行します。wayai bases promote <prod> --from <preview> --dry-run を提示して、結果を待ちます
• **ID は不変です。**ベース、レコードタイプ、リレーションシップタイプ、アクション、ツールセットの id は、それぞれのアイデンティティそのものです。名前の変更はできず、新規作成と移行のみ可能です。最初に、安定した小文字のスラッグを選んでください
• ワークスペース：wayai-ws/bases/<base>/（base.yaml とエンティティごとに 1 つのファイル）です。wayai pull bases/<base> / wayai push bases/<base> でアクセスします。hubs/ と bases/ の両方に対象を指定する pull / push は拒否され、マージされることはありません
• コマンド：wayai bases と、トップレベルの records、record-types、relationships、relationship-types、query-relationships、files、file-types、attachments、toolsets、actions、triggers、inbound-webhooks、seed（それぞれ --base を指定）、および wayai bases tokens|secrets|sql|import|batch|providers
• **ハブへの接続：**Base Toolset 接続により、ネイティブエージェントはツールセットのツールと、list_files および read_file で参照できる data/<file-type>/ 配下のドキュメントを利用できます。これらは write_file と edit_file で書き込みます（references/connections.md）。ハーネスを使うエージェントは、ツールセットを参照する通常の MCP Server 接続を使います（get_url または put_url を持たないものです。URL tools and hub agents）。評価では target_base: を指定します。組織のドキュメントはここ、つまり組織のナレッジベースに保存されます（references/bases/files.md）。スキルはハブに残ります（Skills）

**ベースの作業を始める前に、references/bases/README.md をお読みください。**完全なオブジェクトモデルと、以下の各ドメインのファイルへの案内が記載されています。このセクションだけでは、スキーマを作成するには不十分です。

評価

実際のエージェントを実際のツールとともに実行し、結果を採点するテストシナリオです。基本要素は次のとおりです。

• シナリオ（evals/<name>.yaml または evals/<set>/<name>.yaml）— 任意の複数ターンの history、1つの input、期待される応答（テキストや tool_calls）、任意の evaluator_instructions を指定します。ハブの message_evaluator エージェントが採点します。必須のツール呼び出しがスキップされると、応答テキストに問題がなくても評価は失敗します
• シナリオセット — 最初の階層のサブフォルダー（1階層のみ）です。wayai run-eval はセッションごとにセットを1つだけ実行します。セット全体を実行することも、繰り返し指定できる --eval で選んだシナリオに絞ることもできます（選択したシナリオを繰り返すには --runs を指定します）。大規模なセットのうち、変更が一部のシナリオにしか影響しない場合に便利な、手軽な実行方法です
• ジャーニー（フラットなフォルダー内の journeys/<slug>.yaml）— 保存済みのハッピーパスの会話記録で、エージェントの各ターンから評価を1つずつ生成します。広範なリグレッションテストを構築するための標準的な方法です。wayai eval journey capture <conversation_id> の後に wayai pull を実行します（サーバーが発行したステップ ID を同期します）
• 実行ごとの variables と runs: N — 信頼性は1/1のサンプルではなく、分布で評価します。各実行では、それぞれ異なる行を使って {{var(name)}} を解決します
• シード fixture: — 書き込みを行う評価では、ベースのフィクスチャを指定します。プラットフォームはセッション中にそのフィクスチャのリースを取得し、取得時にリセット、解放時にクリアします。これにより、各実行は前回の実行の残留データではなく、既知の初期状態から開始します。プレビュー用ベースで同時に実行できる評価セッションは1つだけです。2つ目の起動は、最初のセッションのデータを破損させるのではなく、fixture_target_in_use（409）で拒否されます。また、run-eval はデフォルトで処理を待機します。ベースが書き込みのバックプレッシャーにより一時的にリースを拒否した場合の fixture_seed_unavailable（409）についても同様です
• シード initial_state: — input の実行前に、ユーザースコープの WayAI 状態（リピーター顧客の記録や保存済みプロフィールなど）を事前に設定します。これにより、過去の会話の記憶に依存する動作をテストできます。fixture: と同様に、セッションごとに分離され、終了時に破棄されます
• 顧客を customer_contact_id: で指定 — シナリオの実行やジャーニーのステップが対象とする連絡先を指定します。顧客スコープのツールセットが評価内で呼び出されると、その顧客の記録のみを読み取ります。プレビュー用ハブでのみ適用されます（references/evals.md）
• キャプチャ — wayai eval capture <conversation_id> を実行すると、本番環境の会話から最後のやり取りをシナリオ YAML に保存します
• 通話評価（音声通話）— wayai run-eval --call-mode と wayai eval call を使います。詳細は references/evals.md を参照してください

ツールに依存する評価では、再現可能な並列実行のために ジャーニー + fixture: + variables を組み合わせるのがおすすめです。また、evaluator_instructions は、生の呼び出し回数ではなく、機能上の成果として記述してください（「予約を1件正常に完了する」であり、「book_appointment を正確に1回呼び出す」ではありません）。ツールは一時的に失敗することがあり、正しいエージェントは再試行します。YAML の全形式、シード接続の設定、実行のペース配分、作成と解釈の原則については、references/evals.md を参照してください。

自動化

自動化は、ハブ内で自動的に処理を開始します。トリガー（このハブの schedule — 5 フィールドの cron + タイムゾーン。タスクハブでは event — conversation.flagged または conversation.closed も指定でき、イベントごとに 1 つのタスクが作成され、会話はフェンスで囲まれたデータとして渡されます。自動化自身のタスクではトリガーされず、自動化がループしないよう 3 階層までに制限されます： references/automations.md — または、組織内の別の本番ハブの source_hub を指定します。本番環境のみで、そのハブの会話を読み取れる公開者が必要です： references/automations.md — または、外部システムから自動化専用 URL への署名付き配信を受け取る webhook： references/automations.md）、ターゲット（list で指定するハブ独自のリスト、または org_list で指定する組織リストのいずれかである contact_list。タスクハブでは none も指定できます）、およびトリガーが到達した各連絡先に対して実行されるアクションです。

• send_message（チャットハブのみ） — whatsapp では WhatsApp メッセージテンプレート、email では text メール（接続から送信されます。マーケティングメールには配信停止リンクが含まれます）、app では text
• run_agent — agent（pilot または pilot_specialist）と、管理者が作成した instructions。チャットハブでは、channel（whatsapp／instagram／email／app。app 以外の各チャンネルでは接続を指定し、whatsapp ではさらに、24 時間のウィンドウが終了した会話を開始する承認済みテンプレートを指定します）上で、指定したエージェントが各連絡先自身の会話で指示に従って応答し、その会話内で返信します。タスクハブでは、保存できるアクションはこれだけで、チャンネルは指定しません。実行ごとにタスクが作成されます（target: { type: none } の場合は 1 件、連絡先ごとの場合は各連絡先に 1 件）。各タスクには担当者が割り当てられず、指定したエージェント（pilot または pilot_specialist）が指示に従って実行します。連絡先のレコードはフェンスで囲まれたデータとしてタスクに渡され、指示の中には含まれません。 references/automations.md
• instructions は記述されたとおりに送信されます。{{…}} プレースホルダーはそこで置換されません（エージェント固有の指示では機能します）。
• Webhook トリガー（タスクハブのみ）：trigger: { type: webhook, auth: hmac } — 各配信は、ベースの受信 Webhook と同じ方法で署名されます（X-Data-Signature／-Timestamp／-Id。公開 SDK の signRequest で署名できます）。または、シークレットを含む header を指定する auth: static_header。受け入れられた各配信によってタスクが作成され、そのタスクは配信の本文から始まります。本文は指示の外部にある、フェンスで囲まれたデータとして扱われます。シークレットは、自動化をアプリまたは API で作成したときと、ローテーションするたびに 1 回だけ表示されます（本番環境ではハブ管理者が実行します）。プッシュまたは公開ではシークレットは作成されません。 references/automations.md

連絡先と組織リストはハブ設定ではなく、組織データです。組織の連絡先帳に保存され、組織の設定（「連絡先」タブ）と API（/api/contact-book）で管理します。hub.yaml には保存されません。自動化では、組織リスト（target: { type: contact_list, org_list: <list-name> }）か、ハブ独自のリスト（target: { type: contact_list, list: <list-name> }）を指定します。後者は、連絡先帳のラベルとスコープタグを対象にするフィルターで、hub.yaml の contact_lists: に保存されます。トリガーが発生するたびに、実行元のハブから見える、そのリストのメンバーに処理が行われます。連絡先帳を管理できるのは、組織管理者、または組織全体に対する contacts:write 権限を持つトークンです。ハブ管理者は、自身のハブから見える連絡先を表示できます。連絡先の可視性（作成／インポート時に選択するスコープタグ、または全ハブへの公開範囲、および環境。既定値は production なので、プレビューハブには preview と all の連絡先のみ表示されます）、組織リスト、CSV インポートについては、references/automations.md を参照してください。

• 未設定と空の違い： automations:（または contact_lists:）キーがなければ何も変更されませんが、[] を指定するとすべてのオートメーション（またはハブリスト）が削除されます。オートメーションが対象にしているハブリストは削除されません。また、ハブリストの名前を変更すると、オートメーション内の参照も変更されます（別のリストが以前の名前を引き継ぐ場合を除きます）。以前の outbound_schedules: キーと、コンタクトブックに置き換えられたハブのコンタクトおよびリストのブロックは、もう読み込まれません
• 保存時に組織リストは検索されません（ハブの list は検索されます。ハブのリストのいずれかを指定する必要があります）。オートメーションが指定する組織リストは削除または名前変更できます。その場合、次回の実行時に list_not_found が記録され、ハブにアラートが表示されます。実行時にはリストから一度に100件ずつコンタクトを読み込むため、コンタクトブックが保持できる規模のリストであれば最後まで処理され、各コンタクトは最大1回だけ処理されます。実行中は処理されたコンタクトが順次表示され、一時停止すると次のページに進む前に停止します
• 配信停止： コンタクトブックには、オートメーションの配信を希望しない人の電話番号、メールアドレス、Instagram IDが、marketing または all のスコープとともに保持されます。コンタクトが削除された後も情報は残ります。各オートメーションの purpose（デフォルトは marketing、または operational）によって、配信を停止する対象が決まります。マーケティング配信はどちらのスコープでもスキップされ、運用上の配信（リマインダーなど）は all の場合のみスキップされます。マネージャーは「Contacts」タブまたは API で配信停止情報を追加、削除できます。メールの配信停止リンクは all を記録し、マーケティングメッセージの受信を停止した人への WhatsApp 配信が拒否された場合は marketing を記録します。references/automations.md
• 実行時に配信される対象： ハブによってブロックされたコンタクトには配信されません。コンタクトブックに登録されたコンタクトは、新しいコンタクトに許可を求めるハブでそのコンタクトを承認します。そのためアクセス要求は発生せず、返信はエージェントに届きます（すでにアクセス要求が保留中のコンタクトは承認され、チームに残ります。また、run_agent はチームが保持する会話をスキップします）。アプリでは、すでにハブへのアクセス権を持つ WayAI アカウントにリンクされたコンタクトのみが対象です。オートメーションがアクセス権を付与することはありません
• 有効で、一時停止されておらず、実行可能な間の実行： hub.yaml の enabled:（またはアプリのトグル）をオンにすると実行されます。スケジュールは次回の実行がキューに入り、イベントオートメーションはイベント発生時に実行され、Webhook オートメーションは配信を受け付けます。これはプレビューハブと本番ハブの両方で有効ですが、source_hub を指定したイベントオートメーションは本番のみで実行されます。アプリで「Pause」を選ぶと一時停止し、公開後も本番環境での一時停止状態は維持されます。一時停止、再開、今すぐ実行、Webhook オートメーションのシークレットローテーション（ハブ管理者による操作）を除き、本番環境は公開によってのみ変更されます。「今すぐ実行」は1回だけ実行します
• ゲート： 省略可能な gate: { monitor: <agent name> } は、判断モデル上のモニターによって、実行開始前に各実行を判定します（trigger: automation_fire：実行する、別のエージェントで実行する、またはスキップする）。または、コンタクトリスト上で、対象に対して何かを開始する前に各コンタクトを判定します（trigger: automation_item：開始する、別のエージェントで開始する、またはスキップする）。ゲートが失敗した場合、またはタイムアウトした場合、ゲートの対象は実行されません。references/automations.md
• 保存時にオートメーション名を示して拒否される条件： 不明なキー、アクションで使用されないフィールド（タスクハブでの channel または connection）、チャットハブでの none ターゲット、チャットハブまたはリストターゲットでのイベントトリガー、チャットハブでの Webhook トリガー、判断モデル上の automation_fire（またはコンタクトリストの場合は automation_item）モニターではないモニターを指定したゲート、および Instagram での send_message（まだ利用できません）

Instagram で配信できるのは、過去24時間以内にメッセージを送信したコンタクトのみです。結果を約束する前に、それぞれの実行内容を確認してください。設定形式、例、リファレンス、各実行の内容、メッセージテンプレート、制限については、references/automations.md を参照してください。

アナリティクス

すべての会話は、5 つの由来から取得した変数とともにアナリティクスストアに格納されます。

由来	パス	設定元
システムメトリクス	data.system.*	プラットフォーム — メッセージ数、応答時間、継続時間、トークン（約 25 種類のメトリクス）
エージェント定義変数	data.variables.*	conversation_evaluator / message_evaluator エージェントで宣言された evaluation_variables
メタデータ	data.meta.*	プラットフォーム — subject、kanban_status、hub_type
事後アノテーション	data.annotations.*	wayai conversations <id> annotate --set key=value — 実際のビジネス成果（購入、解約）を会話終了後に記録し、予測と実績を照合します
評価スコア	data.eval_scores.*	評価実行のみ（is_eval = true の行。本番アナリティクスからは除外されます）

会話テーブルの粒度は会話単位です。2 つ目のテーブルである message では、会話ごとの費用をメッセージ単位（トークン、USD のコスト、オペレーション）に分解し、モデル、エージェント、認証情報ごとのコスト分析を行えます。

wayai analytics（概要と変数ごとの集計。--metric、--filter、--period）、wayai analytics query（複数変数、group_by、相関を扱う構造化クエリ）、wayai analytics sql（conversation と message に対する生 SQL。コスト分析に使用）、または wayai evals sql（評価行に対する同じ SQL）でクエリを実行します。適切な変数の定義は評価エージェントで行います（roles-and-settings.md → Evaluation Variables）。フィルター、集計、コストクエリ、ワークフローについては、references/analytics.md を参照してください。

チーム、ユーザー、アクセス権

ユーザーエンティティは UI で管理します（Hub → Users タブ：/settings/organizations/<orgId>/hubs/<hubId>/users）。YAML では設定しません。

• Hub User — AI が会話するエンドユーザー（顧客／見込み顧客／従業員）です。/chat（モバイルアプリの Chat タブ）を使用します。そこで可能な操作については、references/using-the-app.md を参照してください。
• Hub Team User — /support（受信トレイ、担当者の割り当て、転送、終了、ボード。詳細は references/support-inbox.md）で会話を処理するサポートチームのメンバーです。Teams（例：「Tier 2 Support」）にグループ化され、transfer_to_team はチーム名を指定します。未知の target は実行時にエラーになります。
• Hub Admin — Hub の全設定にアクセスできます。Org Owner/Admin — 組織レベル（請求、認証情報、Hub）にアクセスできます。アクセス権はレベルごとに設定され、継承されません（組織管理者が自動的に Hub 管理者になるわけではありません）。
• 連絡先アクセス制御 — non_app_permission: require_permission を設定すると、未知のチャネル連絡先は pending として保留されます（ローカライズされた自動返信が送信されます。access_request_message で上書きできます）。access_approval_role で指定されたロールによって承認またはブロックされるまで保留されます。

Hub 環境

環境	説明
preview	デフォルト。設定とテスト用の編集可能なワークスペース
production	読み取り専用。ライブトラフィックを処理します。変更は公開／同期によって preview から反映されます

ライフサイクル：

1. 新しいハブは preview として開始します。自由に編集できます。wayai create --label <l>（または自動作成時の wayai push --label <l>）を使うと、作成時に最初の preview に名前を付けられます。API トークンがハブを作成できるのは、組織内の preview 環境にあるすべてのハブに対する hub:write を含む権限がある場合に限られます。そうでない場合は 403 になります。ハブの作成時、wayai create／wayai push はタグを送信しないため、タグで制限されたトークンでは CLI 経由でハブを作成できません。組織全体に適用されるトークンまたは UI を使用してください
2. 公開（CLI の wayai publish、または UI）— 最初の昇格時に、preview のクローンとして production ハブが作成されます
3. 同期（CLI の wayai publish／エイリアスの wayai sync、または UI）— 以降の preview の変更を、リンク先の production に反映します。このコマンドは初回公開か同期かを自動検出します。デフォルトでは確認が求められ（preview→production の差分が表示されます）、-y を指定すると確認を省略します。プッシュされた preview の状態を昇格するため、先に wayai push を実行してください
4. Preview の複製（CLI の wayai replicate [hub] --label <l>、または UI）— 実験用に、新しい兄弟 preview を作成します（preview または production から作成できます）
5. ラベルの変更（CLI の wayai relabel <label>／--clear、または UI）— preview の preview_label（兄弟ハブを区別するための値）を設定／解除します。hub.yaml ＋ push では編集できません。これはサーバー側で管理されます

Production は読み取り専用です。すべての設定変更は preview を経由します。複数の preview を同じ production にリンクできます（多対 1）。チャンネルの一意性は production でのみ強制されます。preview では、production と電話番号／メールアドレス／SID を共有できます。

公開と同期では production ハブに書き込むため、API トークン（wayai login --token）で公開できるのは、そのハブに対する hub:write を含む権限がある場合に限られます。preview を公開した後、wayai publish が表示する preview→production の差分を取得する際に、まずそのハブを読み取ります。そのため、トークンにはそのハブに対する hub:read も必要です。ハブ単位、または preview 環境に限定されたトークンは 403 で拒否されます。初回公開では production ハブが作成されるため、トークンには組織内の production 環境にあるすべてのハブへのアクセスが必要です（タグで制限されている場合は、preview のタグへのアクセスも必要です）。サインイン済みのユーザーは、これまでどおり公開できます。

WhatsApp／Instagram／Telegram チャンネルは、公開前に preview 上でテストできます。#test CODE クレームコードを使ってテスターを登録してください（references/connections.md → Channel → 「公開前に preview 上でチャンネルをテストする」を参照）。

編集できるのは preview ハブのみです。wayai pull は、リンクされた production ハブも読み取り専用のミラーフォルダーとして書き込みます（ベアスラッグを使用し、--<label> サフィックスは付きません。hub.yaml にはマーカーコメントが含まれます）。これにより、ライブの production 設定を preview と並べて確認できます。wayai push はこのフォルダーへの書き込みを拒否し、自動選択の対象からも除外します。preview と production を正確に比較するには、wayai diff --production を使用してください。

ハブの設定

設定	値	デフォルト	説明
non_app_permission	everyone、require_permission、not_allowed	everyone	外部チャネル経由でハブにアクセスできるユーザー
timezone	IANA タイムゾーン	—	スケジュール設定と表示に使用します
language	en、pt、es	en	ハブから送信されるテキストの言語（例：require_permission チャネルでのアクセス承認待ち通知）
access_approval_role	admin、team	admin	承認待ちの連絡先を承認またはブロックできるユーザー：ハブ管理者のみ、またはサポートチームメンバーも含む
access_request_message	文字列	—	「アクセスは承認待ちです」という自動返信の任意の上書き（指定しない場合は language に応じたローカライズ済みのデフォルトを使用）
display_names	en / pt / es → 文字列のマップ（最大120文字）	—	アプリの言語ごとに、エンドユーザーに表示されるハブの名前。チームと管理者のビューでは name を使用します
welcome_messages	en / pt / es → 文字列のマップ（最大1000文字）	—	アプリの言語ごとに、エンドユーザーが最初のメッセージを送る前に表示される挨拶
starter_questions	en / pt / es → 最大4個の文字列のリスト（各最大120文字）	—	アプリの言語ごとに、エンドユーザーがタップして送信できる最初のメッセージの候補
auto_close_inactive_days	1～180	7	会話が強制終了されるまでの無操作日数（ユーザーまたはチームからのメッセージがない状態）。各ハブに設定されています
conversation_retention_days	1～30	7	終了した会話の DO が、事後の annotate と評価呼び出しのページ（evals.md → Call evals）のために保持されてからクリーンアップされるまでの日数（アーカイブは終了時に行われます）
ended_index_retention_days	1～730	365	終了した会話がハブのインデックスに表示され続ける日数。「終了」タブの範囲と {{previous_conversations(N)}} が遡る範囲を決定します
eval_retention_days	0～3650、または null	プラットフォームのデフォルト（90）	完了した評価セッション（実行、結果、評価会話）が廃止されるまで保持される日数。0 にするとセッションは永久に保持されます。フィールドを省略すると現在の値が維持されます — 上書きを解除してプラットフォームのデフォルトに戻すには、eval_retention_days: null を指定してください。廃止されると文字起こしは完全に削除されます — Analytics の評価スコアは保持されます
end_user_daily_message_limit	1～10000、または null	制限なし	WayAI アプリでエンドユーザー1人が24時間内にハブへ送信できるメッセージ数。この期間は、最初にカウント対象となるメッセージを送信した時点から始まります。上限を超えると、期間が終了するまで送信は拒否され、その理由がアプリに表示されます。カウント対象はエンドユーザーのみです — チームのメッセージ、組織のメンバー、ハブの管理者は対象になりません。他のチャネルには制限はありません。フィールドを省略すると現在の値が維持されます。null を指定すると制限が解除されます

エンドユーザーへの表示（display_names、welcome_messages、starter_questions）：各閲覧者には、アプリの言語に対応するエントリーが表示されます。該当するエントリーがない場合は、ハブの language に対応するもの、さらにそれもない場合はマップに含まれる任意の言語のエントリーが表示されます。そのため、エンドユーザーが使用するすべての言語を設定してください。設定がない言語では、別の言語のエントリーが表示されます。名前が name にフォールバックするのは、display_names が空の場合のみです。en、pt、es 以外のロケールは拒否されます。マップを省略すると現在の値が維持されます。null または {} を指定するとマップがクリアされます。これらによって変わるのは、アプリでエンドユーザーに表示される内容のみです。エージェントへの指示、name、ai_* 通知は翻訳されません。ウェブアプリとモバイルアプリでは、エンドユーザーのチャット一覧（検索ではどちらの名前も検索できます）とスレッドヘッダーに名前が表示されます。また、メッセージがまだないスレッドにはウェルカムメッセージとスターター質問が表示されます。質問をタップすると、最初のメッセージとして送信されます。サポート、カンバン、チームまたは管理者向けのすべてのビューでは name が表示されます。ハブ管理者は、ウェブアプリのハブ設定（Overview → End-user presentation）で、言語ごとに3項目すべてを編集することもできます。

初回セットアップ（コールドスタート）

ユーザーの入口は wayai.pro です。オンボーディングセクションには、インストールコマンドとプロンプトの例が記載されています。スキルが読み込まれた後（ここ）、このセクションに従って「スキルの読み込み完了」から「ハブがテストメッセージに応答する」まで進めます。エージェントはこのセクションだけをもとに自力でセットアップする必要があります。再訪ユーザー（2つ目のハブ、新しいプロジェクト）はこのページをスキップします。

必ず最初に wayai status --json を実行してください。 単一の状態スナップショットが返されます。結果に応じて分岐し、次に進む前に各ステップの完了を確認するため、間に再実行してください（冪等です）。

文言テンプレート（そのまま使用）

• エージェントの操作 — 1行で説明してから実行し、その後、完了を1行で伝えます。
  • 「CLI をインストールしています…」→ コマンドを実行 → 「完了しました — wayai 2.4.1 をインストールしました。」
• ユーザーへの引き継ぎ — URLを1つ、操作を1つ、完了時の連絡方法を1つだけ示します。
  • 「<URL> を開いてください。<1つの操作>を行ってください。完了したら教えてください。」

状態遷移図

#	検出条件（status --json または環境変数から）	アクション
1	CLI がない（wayai --version が見つからない）	エージェントが npm i -g @wayai/cli@latest を実行します。
1b	プロジェクトルートにハーネススキルのインストールがない（<root>/.claude/skills/wayai/SKILL.md、<root>/.opencode/skills/wayai/SKILL.md、<root>/.agents/skills/wayai/SKILL.md のいずれも存在しない。ここで <root> は git rev-parse --show-toplevel の結果、または Git リポジトリ内にない場合は cwd）	Claude Code を使用している場合は、まず mkdir -p <root>/.claude を実行してください — skills インストーラーは、.claude/ がすでに存在する場合にのみ Claude Code の .claude/skills/wayai をリンクします。存在しない場合は、"symlinked: Claude Code" と表示しながら、何も知らせずにスキップします。その後、<root> から npx skills add wayai-pro/wayai-skill -y を実行します。完了後、使用しているハーネス自身のパスが解決されることを確認します（Claude Code → シンボリックリンクをたどった <root>/.claude/skills/wayai/SKILL.md、その他のハーネス → <root>/.agents/skills/wayai/SKILL.md）。解決される場合は終了します（ハーネスが次のターンにスキルを読み込みます）。解決されず、<root>/.agents/skills/wayai/SKILL.md が存在する場合は、自己修復します：mkdir -p <root>/.claude/skills && ln -sfn ../../.agents/skills/wayai <root>/.claude/skills/wayai を実行してから、再確認します。それでも何も見つからない場合は、インストールエラーを提示して停止します — 何も知らせずに終了しないでください（再エントリー時にループするためです）。
1c	skill.installed: true で、skill.latest が設定されており、skill.latest が skill.version より新しい（CLI の nightly チェックで skill.latest が設定されます）	エージェントが <root> から npx skills add wayai-pro/wayai-skill -y を実行してインストールをその場で更新し、終了します（更新されたスキルは次のターンに読み込まれます）。インストールに失敗した場合は、エラーをユーザーに提示し、既存のスキルで続行します。
2	auth.logged_in: false	エージェントが wayai login を実行します（ブラウザーが開きます）。ユーザーへの引き継ぎ：「開いたページを開いてください。サインインするか、アカウントを登録してください。完了したら教えてください。」
3	auth.logged_in: true、orgs: []	1 回だけ質問します：「組織の名前を何にしますか？（通常は会社名です）」。その後、エージェントが wayai org create "<name>" を実行し、新しい組織を取得するため status --json を再実行します。（CLI での作成がエラーになった場合のみ、手動での代替手段として https://app.wayai.pro/settings/organizations/new を開きます。）
3b	git rev-parse --show-toplevel が失敗する（cwd が Git リポジトリ内にない）	CLI はワークスペースの検出に Git を必要とします。操作する前に、解決された cwd を提示してユーザーに確認してください — 引き継ぎ：「<cwd> に Git リポジトリを初期化します。確認するか、別のフォルダーを指定してください。」これにより、~ やその他の意図しないディレクトリに誤ってリポジトリを初期化するのを防ぎます。確認後、エージェントが cwd で git init を実行します。次に git config --global user.name と git config --global user.email を確認します。どちらかが空の場合、ユーザーに名前とメールアドレスを 1 回だけ尋ね、git config --global user.name "<name>" / git config --global user.email "<email>" を実行します。オンボーディングの手順では GitHub リモートは不要です — GitOps/CI のワークフローをユーザーが希望する場合にのみ、後で設定してください。
4	workspace.scoped: false かつ repo_scope_blocker: null	エージェントが wayai init --org <active_org.id> を実行します — 組織との紐付けを、リポジトリでコミットする唯一のワークスペースマニフェストである wayai-ws/wayai.yaml に書き込みます。
4b	workspace.scoped: false かつ repo_scope_blocker が設定されている	wayai init を実行しないでください — wayai-ws/wayai.yaml を書き換えますが、2 つの設定ファイルの内容が一致しないリポジトリは修復できません。kind: "conflict" の場合は、両方の組織 ID をユーザーに伝え、このリポジトリがどちらに属するか尋ねてから、ルートの .wayai.yaml を削除または修正します。kind: "invalid" の場合は、指定されたファイルとその detail を示し、修正をユーザーに依頼します。その後、status --json を再実行します。
5	ワークスペースのスコープ設定済み、ハブの目的がまだ不明	ユーザーへの引き継ぎ：「このハブには何をさせますか？目的、利用者、主なユースケースを説明してください。」
6	選択したプロバイダーの LLM 認証情報がない	ユーザーへの引き継ぎ：「OpenAI/Anthropic/Google の API キーをここに貼り付けてください。」その後、エージェントが wayai create-credential --name <name> --type "Bearer Token" --stdin を実行します。
7	ハブに OAuth 接続が必要（WhatsApp / Instagram / MCP OAuth）	OAuth 接続の引き継ぎ（接続と認証情報 → OAuth 接続の引き継ぎ）を適用します：コネクターの完全なパスを含む接続ディープリンクを送り、完了を待ってから wayai pull -y を実行します。同じ引き継ぎは、ここだけでなく、後から OAuth 接続が必要になった場合にも適用されます。
8	前提条件を満たしている	エンドツーエンドの配線を確認するため、references/canonical-example/README.md を 1 回読みます。その後、ユーザーの説明をもとに wayai-ws/hubs/<hub>/hub.yaml + agents/*.yaml + agents/*.md を生成します（個々の形式については、以下のドメイン別リファレンスを参照）。続けて wayai create -y を実行し、新しいハブを作成してプッシュします（ワークスペースにこの新しいフォルダーしかない場合、wayai push -y でも自動作成されます）。
9	プッシュに成功	エージェントが wayai send-message "Hi" を実行し、応答を表示します。ユーザーへの引き継ぎ：「調整、ツールの追加、または公開を行いますか？」
10	ユーザーが公開を確認	エージェントが wayai publish を実行し、プレビューから本番への差分を表示してから確認します（プロンプトを省略するには wayai publish -y を実行します）。初回の公開では、プレビューをクローンして新しい本番ハブを作成します。以降の実行では同期します。有料プランのみ — CLI が公開には有料プランが必要と報告した場合の手動での代替手段：以下の公開ディープリンクを開いてアップグレードし、UI から公開します。

ディープリンク（正規 URL — パンくずリストは使用しない）

状態	URL
3（組織の作成 — 手動での代替手段）	https://app.wayai.pro/settings/organizations/new
6（認証情報の事前入力）	https://app.wayai.pro/settings/organizations/<org_id>/credentials?type=bearer&name=<key-name>&prefill=true
7（OAuth 接続）	https://app.wayai.pro/settings/organizations/<org_id>/hubs/<hub_id>/connections?connector=<whatsapp|instagram|mcp-server>
10（公開 — 手動での代替手段）	https://app.wayai.pro/settings/organizations/<org_id>/hubs/<hub_id>/overview?action=publish

ルール

• 推測せず、検出してください。各ステップは必ず新しい wayai status --json から開始します。
• エージェントの操作には1行の実行記録を付けます。ユーザーへの引き継ぎでは URL 1つ、操作1つ、復帰の合図1つを提示します。
• 上記の表以外の URL を決して作らないでください。「Settings → … に移動してください」と指示せず、必ずディープリンクを使用します。オンボーディング以外の URL については、references/navigation.md を参照してください。
• ハブの範囲を確認する際（状態5）は、一度に質問を1つだけにします。目的、次にチャネル、最後に LLM プロバイダーの順です。
• オンボーディング中に作成したものを自動でコミットしないでください。git diff を表示し、コミットの前にユーザーの承認を待ちます。

ワークフロー

既存のハブ

1. CLI を更新 — wayai update（操作の前に必ず実行します。CLI がまだインストールされていない場合は、npm i -g @wayai/cli@latest でセットアップします）
2. スキルが古い場合は更新 — wayai status --json を実行します。skill.latest が設定されていて skill.version より新しい場合は、npx skills add wayai-pro/wayai-skill -y を実行して終了します（更新されたスキルは次のターンで読み込まれます）。それ以外の場合は続行します。（初回起動時のオンボーディングでも、状態マシンの行1cと同じ確認を行います。）
3. プル — wayai pull -y（プラットフォームからローカルファイルを同期し、別経路で行われた変更も反映します）
4. コンテキストを読む — このハブのメモ（目的、決定事項、進行中の作業）として wayai-ws/hubs/<hub>/AGENTS.md を読みます。ベースも作業している場合は、wayai-ws/bases/<base>/AGENTS.md も読みます。AGENTS.md に対応したハーネス（Claude Code、Codex、Cursor、OpenCode、Aider）はネイティブに AGENTS.md を自動読み込みしますが、それに依存しないでください。Hub-Folder Memory を参照してください。ここで古くなったルートのブートストラップも削除してください — 古いルートの AGENTS.md を削除する を参照してください。
5. 編集 — hub.yaml、agents/*.yaml、agents/*.md を変更します。
6. プッシュ — wayai push -y（プレビュー用ハブに適用し、サーバーが割り当てた ID を自動的に取得します）
7. テスト — wayai send-message "Hello"
8. レビュー — git diff を実行し、ユーザーに確認を求めます。自動でコミットしてはいけません。 ユーザーが main にコミットしてプッシュします。
9. 公開 — 準備ができたら wayai publish（またはプラットフォームの UI）を実行します。プレビューと本番環境の差分が表示され、確認後、初回は公開します（プレビューを複製して新しい本番用ハブを作成）。2回目以降は変更を同期します。先に push を実行してください。公開されるのはプッシュ済みのプレビュー状態であり、プッシュされていないローカル編集内容ではありません。

新しいハブ（ゼロから作成）

1. 認証情報 — wayai create-credential --name "openai-key" --type "Bearer Token"（認証情報ごとに、組織ごとに1回実行します）
2. 初期化 — wayai init（対話形式）または wayai init --org <uuid>
3. ファイルを作成 — wayai-ws/hubs/<hub>/hub.yaml + agents/*.yaml + agents/*.md
4. 作成 — wayai create -y でハブと OAuth 以外の接続を作成し、すべての設定を適用します（ワークツリーを自動的にバインドします）。ワークスペースにハブのフォルダーが複数ある場合は create <folder> を使用します。（wayai push -y も、単一の新しいフォルダーに解決される場合は自動的に作成します。複数ハブのワークスペースでは --hub が必要になるため、明確で曖昧さのない動詞として create を使用します。）
5. テスト — wayai send-message "Hello"

ハブの作成後は、既存のハブのワークフローに従ってください。

ハブフォルダーのメモリ

wayai-ws/hubs/<hub>/AGENTS.md は、このハブ固有のメモリです。設定ファイル（hub.yaml、agents/）では記述できない、目的、重要な決定事項とその理由、進行中の作業、このハブだけに適用されるビジネスルール、用語、インテグレーション固有の注意点などのコンテキストを記録します。ハブに関するタスクを始めるときは、毎回これを読んでください。wayai pull／push は、フォルダーに AGENTS.md がない場合に限り、プレースホルダーの AGENTS.md を作成します。AGENTS.md に対応したハーネス（Claude Code、Codex、Cursor、OpenCode、Aider）は、エージェントの作業ディレクトリがハブフォルダー内にある場合、ネイティブに自動読み込みします。ただし Claude Code でそうなるかどうかは、バージョン、設定、そのフォルダーまたは親フォルダーにある CLAUDE.md 系ファイルによって異なります（Claude Code のドキュメント）。そのため、自動読み込みをあてにしないでください。ハブの AGENTS.md がすでに読み込み済みの指示に含まれていない場合は、自分で読んでください。古い CLI では、隣に @AGENTS.md を記述した1行だけの CLAUDE.md も作成されていました。これはそのまま残して問題ありません。

積極的にメンテナンスしてください：

• 重要な変更（新しいエージェントやツールの追加、ビジネスルールの更新など）の後は、AGENTS.md を更新し、今後のセッションにコンテキストが引き継がれるようにします
• ハブフォルダーに AGENTS.md がない場合（または作成されたプレースホルダーしかない場合）は、把握している内容（目的、現在のエージェント、最近の決定事項など）を記入し、ユーザーに確認または情報の追加を依頼します
• 決定の理由と、このハブならではの特徴を中心に記載します。プラットフォームの仕組みは繰り返し記載しないでください。そうした情報はこのスキルに記載されています
• 合意したスコープは、任意の ## Build plan セクションに記録できます。見出しはこの表記のままにし、その下に任意で Goal: <one sentence> を置き、GitHub のタスクリスト項目（- [ ]／- [x]）を記載します。ネストは1階層までにします。項目は約30件以内に抑え、それを超える場合はフェーズに分け、完了したフェーズをリストの上に文章としてアーカイブします。項目は完了したらチェックを付けます。YAML が存在するだけでは完了ではなく、プッシュされて動作する状態になったときに完了です。AGENTS.md のほかの内容と同様、これはプラットフォームに同期されません
• ベースも同様に扱います。 ベースも作業対象の場合は、設定だけでは記録できないコンテキストを、ベースフォルダーの wayai-ws/bases/<base-id>/AGENTS.md に記録します（存在しない場合は作成してください）

あふれた内容は wayai-ws/hubs/<hub>/references/ に記録します：

• AGENTS.md が約200行を超えた場合や、複数のトピックが混在し始めた場合は、詳しい内容を wayai-ws/hubs/<hub>/references/ 以下の、トピックに特化したファイルに分けます
• 例：references/business-rules.md、references/integrations.md、references/glossary.md、references/<api-name>-spec.md、references/<persona>-tone.md
• AGENTS.md は常時参照する入り口として維持し、各参照ファイルへの簡潔な案内を記載します。例：「料金ルールの詳細：references/pricing-rules.md」
• ハブフォルダーの references/ はプラットフォームに同期されません。AGENTS.md と同様、エージェントのコンテキスト専用です

古いルート AGENTS.md の廃止

以前の CLI は、セッションのブートストラップとしてリポジトリルートに AGENTS.md（および @AGENTS.md を含む CLAUDE.md）を配置していました。最新の状態に更新してから、このスキルを読み込むためのものです。現在はこれを書き込んだり更新したりするものはないため、記載内容は配置されたリリース時点のまま凍結される一方、実際の手順は変わり続けています。このスキルで変更済みのインストールコマンドや起動手順が記載されたコピーは、気付かないうちに誤った手順へ誘導してしまいます。内容も、今ではすべて冗長です。そこに書かれていることはすべて、このスキルに記載されています。まだこのファイルが残っているリポジトリで初めて作業するときに、廃止してください。対象はリポジトリルートのみです。ハブとベースフォルダーの AGENTS.md はメモなので、そのまま残してください。

対象を特定します。配置されたファイルのタイトルは # Working with WayAI で、本文全体が「更新を確認してから WayAI スキルを読み込む」というブートストラップと、ユーザーとのやりとりに関する数行で構成されており、プロジェクト固有の内容はありません。古いリリースのコピーでは、インストールして読み込むスキルが2つ記載されている場合があります。WayAI と Data の各サーフェスはこの1つのスキルに統合されたため、そのコピーは二重に古くなっています。次に進んでください。

まず、このファイルが今回の作業のきっかけになったか確認してください。 ハーネスによって異なり、対応が変わります。

• 自分のスキルディレクトリからスキルを読み込む（Claude Code → .claude/skills/、OpenCode → .opencode/skills/）→ ルートのファイルは何の役割も果たしていません。削除してください。CLAUDE.md が1行だけの @AGENTS.md シムであれば、これも削除してください。

• 代わりに AGENTS.md を自動的に読み込む（Codex、Cursor、Aider）→ ルートのファイルだけがこのスキルの存在を知らせている可能性があり、削除すると次のセッションに入口がなくなります。ファイルは残して古いブートストラップをポインターに置き換え、内容が凍結されないようにしつつ、引き継ぎを維持してください。

  # Working with WayAI
  
  Load the WayAI skill at the start of every session, before anything else:
  `.agents/skills/wayai/SKILL.md`. It holds the real instructions.
  

いずれの場合も、ファイルに独自のメモが含まれているなら、それらは残してください。置換または削除するのは、配置されたブートストラップ部分だけです。ルートの AGENTS.md がすべて独自の内容であれば、そもそも CLI が配置したものではありません。そのままにしてください。

ブートストラップに記載されていた内容は、すべてこのスキルに引き継がれています。更新の方針は Agent Guidelines に、手順は Workflow → Existing hub にあります。

CLI の一般的なコマンド

wayai update            # Update CLI (run before any operation)
wayai login             # OAuth — or `wayai login --token` for headless/CI
wayai logout            # Sign out and clear stored credentials
wayai whoami            # Show the authenticated identity
wayai org create        # Create a new organization (you become its owner): `wayai org create "<name>"` [--region <r>] [--json]
wayai org pull          # Org-as-code: fetch org-level shared skills → wayai-ws/org/
wayai org push          # Org-as-code: apply local org skills to the platform (fans out to linked hubs); `wayai org diff` previews
wayai create-credential # Create org credential (--name, --type "API Key"|"Bearer Token"|"Basic Auth", --org, --stdin)
wayai update-credential # Rotate/edit an org credential (--name <cred>; --stdin/--secret rotates the secret, --rename, --description, --tag, --environment)
wayai set-connection-credential  # Set a connection's credential directly — --connection <name> + either --org-credential <name> (link) or --field <f> --stdin (raw secret: unlinks only that field's org credential). Works on preview + production (the sanctioned production-credential write)
wayai init              # Scope this repo to an org in wayai-ws/wayai.yaml (interactive — creates an org inline if you have none); --org <uuid> to skip prompt
wayai migrate           # Move a legacy workspace/ + root org/ layout to wayai-ws/, and copy a root .wayai.yaml org binding into wayai-ws/wayai.yaml (the root file is KEPT — older CLIs still need it)
wayai pull              # Pull hub config from platform (-y skips confirmation; auto-binds worktree on first pull). Also writes the linked production hub as a read-only mirror folder
wayai push              # Push local changes (-y skips confirmation; auto-pulls IDs back). Auto-creates a lone new folder; a multi-hub workspace needs --hub or `wayai create`
# `pull`/`push` are ONE verb each, routing by workspace subtree: `hubs/<hub>` (above), `bases/<base>` (the Data surface)
#   or `communities/<community>` (references/communities.md) — a community only by the flag, a positional or its folder as cwd.
# The target resolves in this order: the `--hub`/`--base`/`--community` flag → a positional → the folder you are cd'd into →
#   `wayai-ws/wayai.yaml`'s `default_hub`/`default_base` → the sole folder across the hubs and bases subtrees.
# So in a workspace holding BOTH a hub folder and a base folder, a bare `wayai pull` is refused as ambiguous.
# Name the subtree — `wayai pull bases/crm`, `wayai push hubs/support` — or declare ONE default in wayai-ws/wayai.yaml.
# An invocation naming a target in BOTH subtrees is refused, never merged; run the two it prints, one at a time.
wayai pull bases/<base> # Pull a base's config into wayai-ws/bases/<base>/ (-y skips the overwrite confirm; auto-binds; mirrors a production origin read-only)
wayai push bases/<base> # Push a base folder to its PREVIEW base (--dry-run to stop after the diff; --prune to apply removals). Production is `wayai bases promote`, never push
wayai create [folder]   # Explicitly create a new hub from an idless folder, then push (--label names the preview). The discoverable verb when a workspace has more than one hub folder
wayai diff              # Dry-run diff of local files vs preview (read-only); --production diffs vs the linked production hub
wayai replicate [hub]   # Clone a hub (preview or production) into a new sibling preview; --label <l> names it. Pulls the new preview into its own folder
wayai relabel <label>   # Set a preview hub's label (--clear removes it; --hub to target). Renames the local folder. The server-owned way to change preview_label
wayai publish           # Promote the preview to production (alias: wayai sync). Auto-detects first-publish (clones preview → new production) vs sync (pushes changes to the linked production); shows the preview→production diff and confirms (-y skips). Paid plans only. `wayai push` first — promotes the pushed preview state
wayai use <selector>    # Scope this worktree to a hub, base or community (UUID, folder name, hubs/<n>, bases/<n>, communities/<n>, --hub/--base/--community). Replaces that axis; `--add` widens it instead
wayai unbind [<sel>]    # Drop one entry from the worktree scope; bare, it clears the whole scope (every axis)
wayai send-message      # Test message to a hub (preview or production). -c <id> continues a conversation
                        # `-f, --file <path>` attaches a file (repeatable, max 20, ~7 MB/request) delivered exactly as a real channel does — this is how image/document behaviour gets exercised in the dev loop. Message text is optional when a file is attached (an attachment-only send mirrors a photo with no caption). Images reach the model as a signed URL, not base64
wayai alerts            # Active connection/credential alerts for a hub (Status & Notices). RUN THIS FIRST when a hub misbehaves (audio/TTS not delivered, agent not replying, a tool failing) — an invalid/expired provider key shows as `connection_auth` (usually 401) here instead of forcing a guess from code. --hub <uuid|name>, --json
wayai conversations     # List or inspect conversations (default text view omits message_id — use --json or `observability` to discover ids)
                        # `--status <agent|team|ended>` combines with `--period 7d` / `--from` / `--to`, which bound LAST ACTIVITY: `--status team --to <date>` is the idle human-queue check ("waiting on a person, nothing since <date>"). Without `--status` AND without `--org`/`--all`, a bare `--period`/`--from`/`--to` reads the analytics history instead, which bounds conversation START and covers ended conversations only
                        # `--org <organization_id>` / `--all` list across the hubs `wayai list` enumerates plus the production hubs those name as parents — one command instead of a loop. These always read the live listing (open + ended, windowed on LAST ACTIVITY), with or without `--status`. A production PARENT you cannot read is named as skipped and does not fail the run. A production hub whose PREVIEW you cannot see is not enumerable anywhere, so it is NOT covered and NOT reported at all — reach it with `--hub <id>`. `--limit`/`--offset` are per hub; a hub in scope that refuses is named and the command exits non-zero rather than reporting a smaller queue, and an empty scope is reported as such, never as an empty queue
                        # `wayai conversations <id> observability` — list LLM turns with message_id, latency, tool_calls (assistant turns only)
                        # `wayai conversations <id> observability --message-id <id>` — full record for one turn (prompt, completion, tool calls, tokens; --json for raw)
                        # `wayai conversations <id> annotate --set key=value [--type numeric|categorical|text]` — set a post-hoc business outcome (e.g. customer_purchased=true) on an ended conversation as an analytics dimension; repeat --set for multiple keys (needs the hub within its conversation_retention_days window)
wayai delete-history    # Clear conversation history (testing). Full history (no --conversation-id) ALSO clears the user's user-scoped hub state, so the next send-message is a true cold-open; --conversation-id <id> deletes just one conversation and never touches state
wayai sync-skills       # Sync skills to provider connections; --connection-id <uuid> to scope
wayai sync-mcp          # Re-discover an MCP or Base Toolset connection's tools (refresh stale schemas); --connection <name|uuid>; --check reports drift read-only (CI, exit 1 on drift)
wayai analytics         # Summary + per-variable aggregates; --metric, --filter, --period, --json
wayai analytics query   # Structured ClickHouse query (multi-variable, group_by, correlations)
wayai analytics sql     # Raw single-SELECT SQL over `conversation` (one row per conversation) and `message` (per-message tokens/cost/operations — the surface for cost analysis); --schema prints both catalogs + the message-grain rules (`data.*` paths need `toFloat64OrNull(toString(...))` for numerics, `toString(...)` for grouping); --limit, --json
wayai evals             # List eval scenarios for the hub (--enabled / --disabled)
wayai evals sql         # Raw single-SELECT SQL over the hub's eval result rows ("SELECT …"; --schema prints the column + eval-score-path catalog; --limit, --json)
wayai run-eval          # Run a scenario set's enabled evals (sole set by default; --set to pick on multi-set hubs; repeatable --eval <name> runs ONLY those scenarios and --runs 2,6 only those repetitions of one; --pacing conservative|balanced|fast|<ms> to throttle run dispatch; --call-mode runs every turn the way a live voice call runs it; waits inside --timeout for a fixture held by another session or for transient base write backpressure — --no-queue fails fast and --no-wait implies it; exits 1 if --timeout expires with the session still running)
wayai eval-results      # Inspect eval results (--session <id> or --eval <name>; --runs for per-run detail, --json for raw)
wayai eval capture      # Capture production conversation as eval YAML (<conversation_id> [--set <name>])
wayai eval journey capture  # Capture a conversation's FULL transcript as a journey (<conversation_id> [--name <n>]); then `wayai pull` to sync it to journeys/<slug>.yaml
wayai eval session stop     # Cancel a running eval session (<session_id>) — recovery when a run-eval died without cancelling its own session
wayai eval session delete   # Delete an eval session + its run history (<session_id>, or --all for every session on the hub; -y to skip confirm)
wayai eval call         # Place scored voice calls for a journey whose responder is the pilot_voice agent (--journey <name|id>, --runs, --clips <dir> or OPENAI_API_KEY, cost caps); needs `npm install -g @roamhq/[email protected]` once — see references/evals.md
# Journeys are hub-as-code: edit journeys/<slug>.yaml and `wayai push` (pull after first create to sync step ids)
wayai list              # List organizations and hubs
wayai communities       # An organization's communities (owners and admins; browser `wayai login` only): list, join-link get|rotate|off <community>, stats <community>, access list|add|remove <community> [<email>…] (an invite-only community's access list; remove takes out the members the email admitted); --org, --json, -y. See references/communities.md
wayai contacts          # A contact's customer record in a base (organization admins; browser `wayai login` only): link-customer <contact_id> --base <base_id> --record <record_id>, unlink-customer <contact_id> --base <base_id>; --org, --json. See references/bases/toolsets.md#linking-a-contact-to-its-customer-record
wayai pull communities/<community_id|folder>   # A community's settings, rules, join link state, rooms and courses as files (named explicitly, never by a bare pull); push applies them to the LIVE community (asks first; --dry-run, --theirs on pull)
wayai status            # Show workspace status
wayai report create     # Create platform bug report (--title, --description, --hub, --conversation, --error). With --hub, auto-attaches the hub's active alerts so triage sees a credential/connection cause up front — check `wayai alerts` yourself first, it's often not a platform bug
wayai report edit       # Amend your own pending report (<id> --title/--description/--error/--steps/--context)
wayai report list       # List your reports (newest first; --status <s>, --json)
wayai report get        # Show a report's status + message thread (<id>, --json)
wayai report accept     # Accept a shipped fix (<id>) → addressed
wayai report contest    # Contest a shipped fix or a dismissal (<id> --reason "...") → back to triage

# Bases — the Data surface. A base is org-level and a separate entity from a hub.
# `use`/`unbind` are local (this worktree's scope file) and DEPRECATED — prefer
# `wayai use bases/<id>` / `wayai unbind bases/<id>`; every other command below
# reaches the platform. Full grammar: references/bases/.
wayai bases list        # List bases (--tag to filter)
wayai bases get <id>    # Show one base
wayai bases create <id> --name "<name>"        # Create (--environment preview|production)
wayai bases update <id> --name/--tags/--timezone/--settings/--integrations
wayai bases rename <id> --name "<name>"        # Display name only — the id/slug is immutable
wayai bases tag <id> --tags a,b                # Replaces the existing tags; names must exist as organization tags
wayai bases delete <id>                        # Tombstone; --purge (preview only) destroys storage
wayai bases create-preview <origin-id> --name "<name>"   # Clone config into a new preview
wayai bases list-previews <origin-id>
wayai bases promote <production-id> --from <preview-id>  # NOT `wayai publish`, which promotes a HUB
wayai bases rollback <production-id> --promotion <id>
wayai bases promotions <production-id>
wayai bases use <base>  # Deprecated alias of `wayai use bases/<id>` (see Worktree scope)
wayai bases unbind      # Deprecated alias — clears only the base axis of the worktree scope
wayai bases tokens|secrets|sql|import|batch|providers ...   # namespaced — each names a concept WayAI already owns

# Everything INSIDE a base is its own top-level namespace, each taking --base <id>:
wayai records | record-types | relationships | relationship-types | query-relationships
wayai files | file-types | attachments | toolsets | actions | triggers | inbound-webhooks | seed
wayai files pull|push <file_type> --base <id> [--folder <path>]   # A file type's files as a local folder (knowledge as code). DATA, not config: writes any base, production included. Push shows the diff; a file changed, deleted or created on the base since your pull is a conflict, not written (a new file is sent create-only — references/bases/files.md)
wayai knowledge refresh-preview --org <id> --base <knowledge base>   # Copy the knowledge base's production files into its preview, after creating it and whenever it should be current again (references/bases/files.md)

wayai bases --help（および wayai <namespace> --help）を実行すると、コマンドツリー全体が表示されます。上記の各コマンドの構文は references/bases/ に記載されています。覚えておくべき注意点が2つあります。wayai use／wayai unbind は、ハブ、ベース、コミュニティを対象とする1つのワークツリースコープを管理します。セレクターで対象を指定するため、wayai use bases/crm と wayai use <hub-uuid> のように使い分けます。そのため、wayai bases use／wayai bases unbind はベース軸のみを対象とする非推奨のエイリアスです。また、wayai publish はハブを昇格させ、wayai bases promote はベースを昇格させます。ハブとベースは異なるエンティティです。互いに置き換えてはいけません。

提出した報告の対応を完了する。 トリアージでエスカレーションされ、修正がリリースされると、報告のステータスは shipped に変わります。メールが届き、wayai login／wayai status から一度だけ通知されます（または wayai report list --status shipped で確認できます）。wayai report get <id> を実行し（ステータスとスレッド内の修正担当者のメモを確認し）、問題が解決していれば accept、解決していなければ contest --reason "..." を実行してください。本当の問題だと考える場合は、dismissed の報告にも contest を実行できます。その場合、トリアージに差し戻されます。 異議申し立てには上限があり、トリアージによって却下が最終と判断される場合もあります。それ以上の対応については、サポートにお問い合わせください。

複数のハブが wayai-ws/hubs/ にある場合、ほとんどのコマンドでは --hub <uuid|folder> を指定して対象を明確にできます。

ワークツリーのスコープ

各 Git チェックアウト（メインまたはリンクされたワークツリー）には、1 つのファイル <git-dir>/wayai-scope に記録されたスコープがあります。これは、ハブ、ベース、コミュニティの各セットで構成されます（チェックアウトごとに設定され、追跡対象にはなりません）。

hubs: [11111111-1111-1111-1111-111111111111]
bases: [crm, billing]
communities: [6b1e0000-0000-4000-8000-000000000001]

これはルーティングの誤操作を防ぐためのものであり、同時実行ロック（同時編集を調整するもの）でも、認可（セキュリティ境界となるのは許可設定です）でもありません。また、対象を選択することはなく、対象を拒否するだけです。

スコープの設定方法。 各軸は独立してシードされます。該当する軸のセットが空のチェックアウトに対して、最初の pull／push／create が成功すると、そのセットに値が設定されます。その後は意図的にのみ拡張され、自動バインドで空でないセットに値が追加されることはありません。

適用方法。 wayai pull、wayai push、wayai publish、wayai relabel は、空でない hubs セットに含まれないハブに対して実行しようとすると拒否されます。wayai pull bases/<base> と wayai push bases/<base> は、空でない bases セットに含まれないベースに対して実行しようとすると拒否されます。wayai pull communities/<x> と wayai push communities/<x> は、空でない communities セットに含まれないコミュニティに対して実行しようとすると拒否されます。その軸のスコープがすでに設定されているチェックアウトで新しいハブまたはベースを作成しようとした場合も、同様に拒否されます。

変更方法。

wayai use <selector>          # replace that axis with this one target
wayai use --add <selector>    # widen: add one target to that axis
wayai unbind <selector>       # drop one entry
wayai unbind                  # clear the whole scope, every axis

セレクターは pull／push と同じ方法で軸を指定します。UUID のみの場合はハブ、bases/<id> と --base <id> はベース、hubs/<name> と --hub <x> はハブ、communities/<folder|id> と --community <x> はコミュニティです。フォルダー名のみの場合は、ハブとベースのサブツリーから検索されます（両方に存在する場合は拒否され、推測されることはありません。コミュニティは検索対象になりません）。wayai status には現在のスコープが表示され、status --json では worktree_scope として格納されます。

複数のエンティティが正当にスコープに含まれるワークツリーは一般的です。たとえば、複数のハブにサービスを提供するベースや、ハブ A をハブ B に接続する委任設定などです。このような場合は --add でスコープを広げてください。対象を通すためにトリップワイヤをクリアしないでください。

push／pull がスコープによって拒否された場合は、そこで止めて、ほかのことをする前にユーザーに確認してください。通常、プロンプトが別のワークツリー向けだったことを意味します。現在のセッションでユーザーから明示的な指示がない限り、wayai unbind、wayai use（--add の有無を問わず）、wayai bases unbind、wayai bases use を実行したり、スコープファイルを編集したりしないでください。スコープの拡張もクリアと同様にセッションのルーティングに関わる操作であり、どちらも、ユーザーが作業中だと考えているハブ、ベース、コミュニティを変更します。

リポジトリ構成

.wayai.yaml                              # DEPRECATED org binding — read as a fallback, never written.
                                         #   `wayai migrate` copies it into wayai-ws/wayai.yaml and
                                         #   KEEPS it (older CLIs still require it). Delete it only
                                         #   once every environment running this repo is current.
AGENTS.md / CLAUDE.md                    # STALE if present — an older CLI's root bootstrap; nothing
                                         #   writes or refreshes these now. Delete it, or (on a harness
                                         #   that auto-loads AGENTS.md) replace its body with a pointer
                                         #   to the skill — see "Retiring the old root AGENTS.md".
                                         #   Hub- and base-folder AGENTS.md are memory and are unaffected.
.claude/skills/wayai/                    # Claude Code skill install (provisioned by `npx skills add wayai-pro/wayai-skill -y`)
├── SKILL.md
└── references/                          # On-demand deep-dive references (see index below)
.opencode/skills/wayai/                  # OpenCode skill install (same provisioner; same SKILL.md + references/ layout)
.agents/skills/wayai/                    # Neutral skill install (same provisioner; same SKILL.md + references/ layout)
wayai-ws/                                # All WayAI config-as-code (init creates wayai-ws/hubs/)
├── wayai.yaml                           # Workspace manifest — the repo's ONE committed config file
│                                        #   `organization_id:` / `organization_name:` — which org this
│                                        #   repo is scoped to. Written by `wayai init`; required.
│                                        #   `default_hub:` / `default_base:` — OPTIONAL, which subtree a
│                                        #   bare `wayai pull`/`push` targets. Declare AT MOST ONE:
│                                        #   declaring both is a mixed invocation and is refused.
│                                        #   Write these two by hand — no command creates them.
│                                        #   `wayai init` keeps their VALUES when it rewrites the file,
│                                        #   but YAML comments in it are not preserved.
├── org/                                 # Org-as-code — shared skills (wayai org pull/push)
│   ├── skills.yaml
│   └── skills/<skill_name>/
├── communities/                         # One folder per community — `wayai pull communities/<community_id>`
│   └── <community-slug>/                #   (see references/communities.md; push edits the LIVE community)
│       ├── community.yaml               # Identity, settings, join link state, rooms, course folders in order — with ids and revs
│       ├── rules.md                     # The rules members see (Markdown); empty = none
│       └── courses/<course>/            # course.yaml (the course, its modules, each module's lessons in order)
│           └── lessons/<lesson>.md      #   and one file per lesson: its fields, then its text
├── bases/                               # One folder per preview base (Data surface) — `wayai pull bases/<base>`
│   └── <base-id>/
│       ├── base.yaml                    # Base identity; `wayai use bases/<folder>` reads it
│       ├── record-types/<id>.yaml       # One file per entity, per kind. Secrets are never written
│       ├── relationship-types/<id>.yaml
│       ├── file-types/<id>.yaml
│       ├── inbound-webhooks/<id>.yaml
│       ├── triggers/<id>.yaml
│       ├── toolsets/<id>.yaml
│       ├── actions/<id>.yaml
│       └── seeds/<id>.yaml
└── hubs/
    └── <hub-slug>--<label>/             # One folder per preview hub (disambiguated)
        ├── hub.yaml                     # Hub config + states + connections + automations + skills
        ├── agents/
        │   ├── <slug>.yaml              # Agent config (one per agent, slugified name)
        │   └── <slug>.md                # Agent instructions (one per agent)
        ├── evals/                       # Eval scenarios (synced)
        │   ├── <name>.yaml
        │   └── <set>/<name>.yaml
        ├── journeys/                    # Eval journeys (synced; flat folder, one file per journey)
        │   └── <slug>.yaml
        ├── attachments/                 # Eval/journey turn attachment files (synced; hub-root, shared by evals + journeys)
        ├── call-openings/               # Voice agents' own call opening audio (synced; `call_openings` in agents/<slug>.yaml)
        ├── skills/<skill_name>/         # Skill files (synced)
        ├── AGENTS.md                    # Hub-specific memory — scaffold seeded on pull/push (NOT synced; fill it in)
        └── references/                  # Hub-specific supporting files (NOT synced)
    └── <hub-slug>/                      # Linked production hub: READ-ONLY mirror (bare slug, no --label). Refreshed each pull; never pushed

プレビュー用ハブのフォルダーには、区別のため hub-slug--<preview_label> または hub-slug--<hub_id_prefix> を使用します。リンクされた本番ハブは、サフィックスのない hub-slug にミラーリングされます。workspace/ とルートの org/ というレガシーなレイアウトを引き続き使用している既存のリポジトリも動作します（CLI はどちらのレイアウトも読み取ります）。wayai migrate を実行すると wayai-ws/ に移行できます。

hub.yaml の形式

version: 1
hub_id: "abc-123-def"           # set by `wayai pull` — do not edit
hub_environment: preview         # set by `wayai pull` — do not edit
preview_label: experiment-a      # server-owned, set by `wayai pull` — do not edit (only on previews; sets the hub folder's `--<label>` suffix). Editing here is IGNORED on push (push warns); change it with `wayai relabel <label>` / `--clear`, or set it at creation with `wayai create --label` / `wayai replicate --label` / `wayai push --label`

hub:
  name: Customer Support
  # description: Handles refunds, order status, and billing questions   # optional, human-facing
  hub_type: chat                 # chat | task
  ai_mode: pilot+copilot         # pilot | copilot | pilot+copilot | turned_off
  timezone: America/New_York
  non_app_permission: everyone
  # tags: [retail, vip]          # org tag slug names (create in UI first); gate which org credentials this hub can resolve. Omit to leave unchanged; [] clears; only an org admin may change them. See references/connections.md#organization-tags
  # auto_close_inactive_days: 7  # force-close a conversation after N days of inactivity (see Hub Settings)
  # conversation_retention_days: 7  # keep an ended conversation's DO alive N days for post-hoc `annotate` (see Hub Settings)
  # display_names: { en: Customer Support, pt: Atendimento ao Cliente, es: Atención al Cliente }   # end-user name per app language (see Hub Settings)
  # welcome_messages: { en: "Hi! How can I help?", pt: "Olá! Como posso ajudar?", es: "¡Hola! ¿Cómo puedo ayudar?" }
  # starter_questions: { en: ["Where is my order?"], pt: ["Onde está meu pedido?"], es: ["¿Dónde está mi pedido?"] }   # up to 4 per language
  # end_user_daily_message_limit: 50   # messages one end user may send in the app per 24 hours; null removes it (see Hub Settings)
  kanban_statuses:               # full field specs + constraints: references/kanban.md
    - slug: new
      name: New
      order: 0
      color: "#22c55e"
      isInitialStatus: true
      allowed_next_statuses: [in_progress, waiting_for_customer, resolved]
    - slug: in_progress
      name: In Progress
      order: 1
      color: "#3b82f6"
      triggersAgentResponse: true   # transition fires an agent turn; can carry additional_context_schema + additional_instructions (see references/kanban.md)
      allowed_next_statuses: [waiting_for_customer, resolved]
    - slug: waiting_for_customer
      name: Waiting for Customer
      order: 2
      color: "#f59e0b"
      allowed_next_statuses: [resolved]
      followups:
        - order: 0
          type: inactivity
          threshold: 30
          timeUnit: minutes
          instructions: "Hi! Just checking in — do you still need help?"
    - slug: resolved
      name: Resolved
      order: 3
      color: "#ef4444"
      isTerminalStatus: true         # at most one terminal status per hub
      outcomes:                      # terminal-transition policy; selected slug → data.meta.outcome
        - { slug: resolved, name: Resolved, color: "#22c55e", from_statuses: [in_progress, waiting_for_customer] }
        - { slug: canceled, name: Canceled, color: "#ef4444" }
        - { slug: abandoned, name: Abandoned, color: "#a0aec0" }

states:
  - id: "state-uuid-789"          # set by pull
    slug: order_tracking           # immutable identifier; auto-derived from name if omitted
    name: order_tracking
    scope: conversation            # conversation | user
    description: Tracks current order
    json_schema:
      type: object
      properties:
        order_id: { type: string }
        status: { type: string, enum: [pending, shipped, delivered] }
    initial_value: { status: pending }  # must validate against json_schema

connections:
  - name: anthropic
    type: Agent
    service: Anthropic
    # sync_credentials_to_production: true   # default; false keeps production's credential separate (set it via `wayai set-connection-credential`). See references/connections.md#credential-propagation-to-production-sync_credentials_to_production
  - name: my-api-connection
    type: Tool
    service: REST API
    base_url: https://api.example.com   # Its credential is only sent to this origin: required for custom tools while it holds one
  - name: elevenlabs-tts
    type: TTS
    service: ElevenLabs TTS
    settings:            # Per-connection params (voice/model/language, etc.); keys = connector_settings_schema. See references/connections.md
      voiceId: pNInz6obpgDQGcFmaJgB
      modelId: eleven_multilingual_v2

hub.yaml には skills:、automations:、contact_lists: ブロックも含まれます。完全なスキーマについては、ドメインごとのリファレンスを参照してください。

agents/<slug>.yaml の形式

id: "agent-uuid-123"               # set by pull
name: Pilot Agent
role: pilot
connection: anthropic              # connection display name
# instructions resolved by convention from agents/<slug>.md
# additional_context_template:     # per-turn context, emitted as an <additional_context> tag on the last user message (same {{...}} syntax as instructions). Put high-churn placeholders ({{now()}}, {{state()}}) HERE, not in instructions, to keep the system prompt cache-stable (see references/agents/instructions.md#additional-context-cache-friendly)
# response_format:                 # {schema_name, schema_json} — force structured JSON output instead of free text (see references/agents/roles-and-settings.md#response-format-structured-output)
# enabled: true                    # default; omitted
# include_message_timestamps: false  # default; when true, appends [timestamp, weekday, daypart] to user messages
# previous_conversations_count: 3  # off by default (max 20); this user's N most recent ended conversations, prepended to the FIRST user message and frozen at the first agent turn that uses it. Foreground roles only; `0` clears it (omitting the key on update leaves it as-is); summaries come from the conversation_evaluator (see references/agents/roles-and-settings.md#previous-conversations-context)
settings:
  model: claude-sonnet-5-5
  max_tokens: 4096
  # temperature (only sampling knob): Sonnet 5+ / Haiku 5.5 / Opus 4.7+ / Fable strip a non-default value — set it only on Opus 4.6 / Sonnet 4.6 & older
  # reasoning per provider: Anthropic thinking_enabled + effort · OpenAI/OpenRouter/xAI reasoning_effort · Gemini reasoning_level (see roles-and-settings.md)
  # file_handling_mode: no longer changes what the model receives (earlier files are always announced by path, never re-attached); metadata_only still auto-enables read_file. max_attachment_size_mb is inert (see roles-and-settings.md#file-handling-all-llm-connectors)
  # deliver_preamble: true           # default; pre-tool "let me check…" text is delivered as its own message (voice: own TTS clip; ignored on email). false = only the final reply (see roles-and-settings.md#pre-tool-preamble-delivery-all-llm-connectors)
  # copilot_trigger: every_message   # copilot-track only; on_demand suppresses the automatic per-message suggestion — the team pulls one via the "Suggest reply" button (cost/noise lever; see roles-and-settings.md)
tools:
  native:
    - update_kanban_status
    - get_state
    - update_state
  delegation:
    - type: agent
      tool: transfer_to_agent
      target: Specialist - Billing
    - type: team
      tool: transfer_to_team
      target: Tier 2 Support
    # Hub-as-agent: hand a self-contained request to ANOTHER hub in this org.
    # `target` is a PRODUCTION (published) hub name. context_boundary is required
    # reading — see "Hub delegation" below.
    - type: hub
      tool: delegate_to_hub
      target: Billing Hub
      context_boundary: summary   # instruction | summary | transcript
  custom:
    - name: check_order_status
      description: Check order status by email
      method: post
      path: /api/orders/status
      body_format: json
      connection: my-api-connection
      config:
        name: check_order_status
        description: Check order status by email
        parameters:
          type: object
          properties:
            email: { type: string, description: Customer email }
          required: [email]
skills:
  - name: Order Management         # links a hub skill by name (see Skills)
    skill_id: "skill-uuid"         # set by pull
    priority: 0

エージェントの全オプション（コネクターごとの設定、additional_context_template、response_format、ファイル処理、ネイティブツールのパラメーター、カスタムツールのフィールド、composed_tools、プレースホルダー）については、references/agents/ を参照してください。

評価変数 — conversation_evaluator／message_evaluator エージェントには evaluation_variables リストが含まれます。これは、会話／メッセージごとに出力される構造化フィールドで、Analytics では data.variables.* になります。これらは pull／push でラウンドトリップされます。references/agents/roles-and-settings.md を参照してください。monitor は、flag_conditions と rules が読み取るフィールドを同じリストで宣言します。これらはそのモニターの条件にのみ使われ、Analytics には送られません（モニターの設定）。

主要なルール

• 読み取り専用フィールド： hub_id、hub_environment、id — wayai pull によって設定されます。編集しないでください
• 接続の自動作成： hub.yaml 内の非 OAuth 接続は、service と authentication_type の一致によって組織の認証情報に紐付けられます。同じ認証タイプを持つ組織の認証情報が複数ある場合は、credential フィールドで対象を指定してください。OAuth 接続（WhatsApp、Instagram、MCP OAuth）は事前に作成しておく必要があります（UI で設定 — OAuth 接続の引き継ぎを参照）。名前のみで参照します
• 本番環境の認証情報： 接続はデフォルトで、公開／同期時に認証情報を本番環境へコピーします。本番環境の認証情報を別に保つには、sync_credentials_to_production: false を設定し、wayai set-connection-credential で直接設定してください（それ以外の場合、本番環境は読み取り専用です）。Base Toolset 接続のトークンは、フラグの値にかかわらずコピーされません。必ず本番環境用のトークンを設定してください。また、ホストされたエージェント接続の Webhook 署名シークレット（Claude Agent (Managed)）もコピーされません。各ハブはそれぞれ独自のエンドポイントを登録し、独自のシークレットを設定します。references/connections.md を参照してください
• 組織タグ： hub.tags（スラッグ名。先に UI で作成します）によって、ハブが解決できる組織の認証情報が制限されます（上記の「接続と認証情報」の一致ルールを参照）。変更できるのは組織管理者のみです。タグを変更しないプッシュであれば、誰でも実行できます。タグのスラッグは固定されており、UI で編集できるのは表示名と色だけなので、これらのリストを書き換える必要はありません。references/connections.md を参照してください
• ツールグループ： native（名前で指定するプラットフォーム組み込み機能）、delegation（エージェント間／チームへの引き継ぎ）、custom（接続を使用する HTTP エンドポイント）、mcp（MCP Server 接続のツール。name と connection で指定 — プッシュ時に検出して割り当てます。references/agents/native-tools.md を参照）。公開するパラメーター／ツールの設計については、references/agents/tool-principles.md を参照してください
• 名前は外部キーです： エンティティ間の参照は、プッシュ時／実行時に表示名で解決されます — エージェントの connection:、委任の target:（エージェント名または UI で管理するチーム名）、エージェントの skills[].name、評価の agent:、カスタムツールの connection:。参照先のない名前があると、プッシュまたは実行時の呼び出しが失敗します。名前を変更する場合は、同じ編集で参照元も更新してください
• 名前の変更： name フィールドを変更してください。安定した id により、削除＋作成ではなく名前変更として検出されます。エージェントの場合、wayai push が .yaml ファイルと .md ファイルの名前を自動で変更します
• デフォルト値の省略： デフォルト値と一致するフィールドは省略されます（例：enabled: true、カンバンのフラグはデフォルトで false、excludeHolidays はデフォルトで true）
• エンティティの照合（同期／差分）： まず id（安定した UUID）で照合し、次に代替ルールを使用します。例外：状態は name で照合（スコープに関係なくハブごとに一意）。評価は name + path で照合。ネイティブツールはエージェントごとに tool_name で照合

スラッグ化とエンティティの照合

名前 → ファイル名に使用できる URL セーフなスラッグ：

1. 小文字に変換
2. アクセントを正規化（NFD + ダイアクリティカルマークを除去）
3. 英数字以外を - に置換
4. 連続する - をまとめる
5. 先頭と末尾の - を削除
6. 50 文字に制限

例：Mario's Pizza → marios-pizza、Suporte Nível 2 → suporte-nivel-2、Specialist - Billing → specialist-billing。

エージェントの指示の編集

• ファイル：対応する .yaml と同じ場所にある agents/<slugified-agent-name>.md
• 必ず wayai-ws/hubs/<hub>/agents/ に保存してください。/tmp やその他のパスには保存しないでください
• 外部での変更を上書きしないよう、編集前に必ず wayai pull を実行してください
• 指示では、動的なプレースホルダー（{{now()}}、{{user_name()}}、{{state()}} など）を使用できます。詳しくは references/agents/instructions.md を参照してください
• 信頼性を高めるための構成： 各 .md を 手順 → ガードレール → 文体 の順に構成してください。避けることではなく、実行することを記述してください。それぞれのアクションを、名前付きのツール呼び出しにしてください。モデルが適切なアクションを最初に、最も簡単に実行できるようにプロンプトを構成してください。原則の全容については、references/agents/prompt-principles.md を参照してください

リファレンスドキュメント

ハブのナビゲーション順に従い、ドメインごとに1つのリファレンスを用意します。概念はこのファイルに記載します。YAML を作成する際、フィールド単位のスキーマやプロバイダーごとの詳細が必要な場合、またはそのドメインの動作をデバッグする場合は、該当するドメインのリファレンスを開いてください。

ドメイン	リファレンス	読むタイミング
接続	references/connections.md	チャネル、エージェントプロバイダー、ツール API、音声コネクターの接続、認証情報のバインド、組織タグ、本番環境の認証情報を設定するとき
エージェント	references/agents/roles-and-settings.md	エージェントの役割、委任フロー、コネクター固有の設定、評価変数、応答形式を選ぶとき
エージェント	references/agents/native-tools.md	ネイティブツールのカタログとパラメーター、メタツール（get_tool_schema、execute_tool）、MCP ツールの割り当て
エージェント	references/agents/custom-tools.md	カスタム HTTP ツールの形式、OpenAI の関数スキーマ、composed_tools の副作用
エージェント	references/agents/tool-principles.md	信頼性の高い呼び出しができない場合のあるエージェント向けにツールの表面を設計するとき — 表面の厳選 > 検証 > プロンプト、1 ツール 1 意図、失敗を明示する、ガード付きのアトミック操作
エージェント	references/agents/instructions.md	agents/<slug>.md のプレースホルダー構文（{{now()}}、{{state()}} など）
エージェント	references/agents/prompt-principles.md	信頼性の高い実行のためにコンテキストを配置、構成するとき — コンテキストとスロットのライフタイム、キャッシュの衛生状態、状態とツール履歴、スタイルよりフロー、肯定的な表現、独立したセクションとしての声
カンバン	references/kanban.md	カンバンフィールドの仕様：フラグ、遷移、フォローアップ、追加コンテキストのスキーマと指示、レーン、制約マトリックス、警告
状態	references/states.md	状態の JSON Schema、スコープ、エージェントによる読み書き、初期値
スキル	references/skills.md	スキル（skills:、skills/<skill_name>/）、エージェントとの連携、スキル導入前に取得したフォルダーの変換、プロバイダーの同期（wayai sync-skills）
音声通話	references/calls.md	ライブ AI 音声通話用のハブの設定：Realtime 接続、pilot_voice エージェント、ウェブ通話とその冒頭（AI による通知、WayAI または独自の通知）、AI が応答できる相手、引き継ぎ、音声での確認、終了、チームに表示される情報、通話の録音、料金、制限
評価	references/evals.md	評価シナリオの YAML、シナリオセット、コードとしてのジャーニー、シードフィクスチャと変数、wayai eval capture / wayai eval journey capture、実行間隔、通話評価（run-eval --call-mode、wayai eval call）、作成と解釈の原則
自動化	references/automations.md	自動化（スケジュール、イベントまたは Webhook トリガー、連絡先リストまたは対象なし、send_message / run_agent）、Webhook 配信（署名、シークレット、ローテーション）、ハブの種類ごとの有効な組み合わせ、タスクハブのタスク、ゲート、キーなしと [] の違い、有効化、一時停止、今すぐ実行、メッセージテンプレート、制限、ハブのリスト（contact_lists:）、組織の連絡先帳（連絡先、表示範囲、組織のリスト、CSV インポート）
コミュニティ	references/communities.md	wayai communities：組織のコミュニティ一覧、参加リンクの表示、ローテーション、無効化、ソースタグ、統計、招待制コミュニティのアクセスリスト、実行できるユーザー（オーナーと管理者、ブラウザーでのサインインのみ）とエラー。コードとしてのコミュニティ：community.yaml（その admission）、rules.md とコース（course.yaml、レッスンファイル）、ルームキー、名前とリビジョン、一覧の順序、pull と push の判定方法、競合、制限、--dry-run / --theirs
分析	references/analytics.md	変数のカテゴリと型、フィルター演算子、時間分析、クエリのワークフロー
ベース	references/bases/README.md	ベースに関する作業では、まずこれを読んでください — Data オブジェクトモデル、プレビュー／プロモートのルール、以下のファイルへのルーティングマップ
ベース	references/bases/records.md	レコード型のスキーマ、レコード、Filter DSL と search、日時、部分更新、キャンセル／アーカイブ、x-fk、レビュー済みレコード（x-review）とエージェントノートのレシピ、リレーションシップの型、リレーションシップ、バッチ、一括インポート
ベース	references/bases/querying.md	wayai bases sql — テーブル、必須のスコープ指定述語、JSON サブカラム、サンプル集、x-search の調整とタイムゾーン設定
ベース	references/bases/files.md	ファイルの種類、バージョン管理されパスで指定されるファイル、履歴／差分、S3 マウント、レコードへの添付
ベース	references/bases/config-as-code.md	wayai-ws/bases/<base>/、サブツリーのルーティングと混在呼び出しの拒否、base.yaml、プロモート／ロールバック、評価モード、シードフィクスチャとリース
ベース	references/bases/integrations.md	正規データを優先するモデリングとパターンカタログ、外部ソース、受信 Webhook、トリガー、プロバイダーアダプター
ベース	references/bases/toolsets.md	アクションとツールセット（エージェント向けの MCP サーフェス）、filterable_fields / writable_fields / base_filter / precondition、ベース API トークン、ベースの認証情報、モデリングとツール設計の原則
ベース	references/bases/executors.md	トリガーまたは外部ソースに代わって外部の世界に働きかける HTTP サービスの構築
正準例	references/canonical-example/README.md	hub.yaml + agents/* + evals/ + journeys/ の相互参照と、エージェントがナレッジベースから組織のドキュメントを読み込む方法を示すエンドツーエンドのハブ。新しいハブをゼロから生成する前に一度読んでください
リポジトリーエージェントのテンプレート	references/repository-agent/README.md	1 つの GitHub リポジトリーで作業するホスト型エージェント：最初にその AGENTS.md を読み込み、ブランチまたはコミット（repo_checkout）から作業を開始し、自分専用のブランチのみを push します。ハブの agents/ にコピーするファイル
アプリの使い方	references/using-the-app.md	エンドユーザー（ハブユーザー）への対応：エージェント一覧、チャットエージェントとタスクエージェント、書き込みと添付、ファイル、担当者が応答するタイミング、アカウント、通知、モバイルアプリとデスクトップアプリ
サポート受信トレイ	references/support-inbox.md	サポートチームのメンバーまたはハブ管理者への対応：受信トレイとタブ、ボード、割り当て／引き継ぎ、転送、クローズ、返信と 24 時間の制限、Copilot の提案、相談、連絡先の承認、通知、モバイルアプリの Support
ナビゲーション	references/navigation.md	アプリの URL 構造（/chat、/support、/settings/...）、ハブ詳細のタブ、クエリ文字列によるディープリンク — ユーザーに URL を渡すときはいつでも参照してください。モバイルアプリでのリンクの開き方と、デスクトップアプリ（入手先、ブラウザー版との違い、設定）
AGENTS.md ファイル	references/agents-md-template.md	ハブ／ベースごとのフォルダーメモリパターン — AGENTS.md に記述する内容と、CLI がシードする 2 つのファイルのどちらか