fw-setup

エントリー契約

• 呼び出し元： ツールチェーンが不足している場合、またはユーザーが FDK／Node のセットアップを依頼した場合のコントローラー
• 前提条件： インストール／アップグレード／ダウングレードなど、システムを変更する操作についてユーザーの同意を得ていること
• 戻り値： done（fdk と node がグローバルに利用できることを確認済み）｜blocked（ユーザーがインストールを拒否）｜escalate（再試行後も確認に失敗）
• 完了時： 制御をコントローラーに戻します。コントローラーは以前のインテントチェーン（例：fw-app-dev）を再開します。
• セッション： 開始時に session-read.sh を実行します。成功時は、アプリのディレクトリがある場合に session-write.sh <app-dir> progress.phase=setup を実行します。

FDK セットアップ

最重要事項 — 例外なく厳守：FDK がグローバルに利用でき、新しいシェルでも引き続き利用できることを確認するまで、FDK のインストールは決して完了ではありません。確認に少しでも失敗がある状態で「インストール完了」と言ってはいけません。

必須の徹底事項： システムを変更するすべての操作（インストール、アップグレード、ダウングレード、アンインストール、および /fw-setup-troubleshoot --fix）を、実際のシェルテストで確認してください。/fw-setup-status、/fw-setup-troubleshoot（--fix なし）、および /fw-setup-use は Task を使用しないフローです（/fw-setup-use で .nvmrc を追加できるのは、ユーザーが --write-nvmrc を指定した場合のみです）。確認が通るまで繰り返してください。例外はありません。

あなたは、Freshworks FDK のインストールとバージョン管理を徹底するレイヤーです。

段階的な情報開示： 正式な FDK／Node／Platform のバージョン固定情報は docs/engine-matrix.md にあります（唯一の信頼できる情報源です。バージョン情報に異論がある場合は読み込んでください）。プロジェクトごとに Node／FDK スタックを切り替える場合は、まず commands/fw-setup-use.md を使用し、次に .nvmrc のパターンについて references/macos.md／references/cross-scenarios.md を確認してください。複雑な複数 Node のシナリオ、PATH の競合、OS 固有のインストール問題については、references/cross-scenarios.md を読み込んでください。macOS 固有の問題については、references/macos.md を読み込んでください。Windows 固有の問題については、references/windows.md を読み込んでください（PowerShell 5.1 の &&、where と where.exe の違い、nvm use 後の PATH の更新）。fdk: command not found エラーについては、references/error-command-not-found.md を読み込んでください。自動の --fix が失敗した場合に、対話形式で手動トラブルシューティングを行う場合は、references/interactive-troubleshooting-guide.md を読み込み、手順に沿った SOP プロトコルに従ってください（一度に実行するコマンドは 1 つだけにし、人間からの出力を待ち、結果に応じて対応してください）。ローカルの fdk run をブロックせずに実行する場合は、アプリのルートから scripts/fw-setup-run-background.sh を実行してください（スラッシュコマンドではなくシェルスクリプトです）。一致する fdk run／fdk tunnel プロセスに終了シグナルを送るには、scripts/fw-setup-stop-shell-tasks.sh を使用してください。

ルーティング

ユーザーのリクエストを解析し、適切な操作を実行します。

トリガー	操作
"install fdk", "setup fdk", /fw-setup-install, /fdk-install（レガシー）；バージョン X.Y.Z または --version X.Y.Z は任意	FDK 10.x（デフォルト）または非推奨の通知を付けて FDK 9.x をインストールします（commands/fw-setup-install.md を参照）。--both を追加すると、FDK 10 と FDK 9 の両方のスタックをインストールします。冪等性があり、両方がすでにインストールされている場合はスキップします。
"upgrade fdk", "update fdk", /fw-setup-upgrade, /fdk-upgrade（レガシー）；--to X.Y.Z は任意	最新の FDK 10.x 系列、または指定した semver にアップグレードします（commands/fw-setup-upgrade.md を参照）。
"migrate fdk 9 to 10", "fdk 9 to 10"	/fw-setup-install（Node 24 に FDK 10.x をインストール）または /fw-setup-upgrade を使用します。
"downgrade fdk", "use fdk 9", /fw-setup-downgrade 9.6.0, /fdk-downgrade（レガシー）	FDK 10.x → 10.0.y、または 10.x → 9.x にダウングレードします（commands/fw-setup-downgrade.md を参照）。バージョンを指定せずに "downgrade fdk" と入力した場合は、デフォルトで最新の FDK 9.x（Node 18）にします。開発者に対象バージョンを尋ねる必要はありません。
"uninstall fdk", "remove fdk", /fw-setup-uninstall, /fdk-uninstall（レガシー）	FDK のみをアンインストールします（Node/nvm は保持し、--all は使用しません）。
"check fdk", "fdk status", /fw-setup-status, /fdk-status（レガシー）；--verbose は任意	ステータスをインラインで表示します。verbose を指定すると、PATH/nvm/rc の診断情報を追加します。
"fdk broken", "fdk not found", /fw-setup-troubleshoot；--fix はユーザーが求めた場合のみ	インラインで診断します。--fix はシェル Task を起動します（commands/fw-setup-troubleshoot.md を参照）。
"use fdk for this repo", "switch node for fdk", アプリの cd 後に誤った fdk を実行、/fw-setup-use	ワークスペースのスタック： .nvmrc または明示的な 10/9 に基づいて nvm use を実行します（Node 24.11 対 18）。--write-nvmrc は任意です（インラインのみ — commands/fw-setup-use.md を参照）。

FDK 9.x の非推奨（9.x のインストール／ダウングレード時）： references/templates/fdk9-deprecation-warning.txt の内容をそのまま表示します。

コア規則 - 全般に適用

• Platform 3.0 のみ - Platform 2.3 は非推奨です（Node 18 のサポート終了日は 2026 年 5 月 31 日）。2.x を生成または延長することは絶対に禁止します。新たな 2.x の作業は一切認めません。
• FDK 10.x + Node 24 を推奨 - Platform 3.0 の開発および公開に使用する主要なスタックです。
• FDK 9.x + Node 18 は使用可能 - 非推奨ですが、2026 年 5 月 31 日まで Platform 3.0 の開発でサポートされます。
• 公開には FDK 10.x が必要 - Marketplace への提出には Node 24 + FDK 10.x が必要です。
• 必ず nvm を使用 - Node をグローバルにインストールしてはならず、sudo npm も使用してはなりません。
• FDK CLI のみ - Freshworks の公式ドキュメントに記載されたコマンドを使用します。
• サブエージェントの実行 - インストール、アップグレード、ダウングレード、アンインストール、および /fw-setup-troubleshoot --fix の変更を伴うフローでは、shell Task を起動します。/fw-setup-status（--verbose の有無を問わず）、--fix を付けない /fw-setup-troubleshoot、および /fw-setup-use はインラインで実行します（Task は使用しません）。
• スラッシュコマンドの終了処理 - /fw-setup-install、/fw-setup-upgrade、/fw-setup-downgrade、/fw-setup-uninstall、および /fw-setup-troubleshoot --fix（該当する場合はレガシーの /fdk-* エイリアスも含む）のシェル Task は、検証と最終 REPORT が完了した時点（または中止した時点）で直ちに終了しなければなりません。これらの Task から fdk run、fdk tunnel、ウォッチャー、その他の長時間実行プロセスを起動してはなりません。
• 完全なクリーンアップ - ダウングレード／アンインストールでは ~/.fdk ディレクトリを必ず削除します。
• グローバルな永続化 - すべての操作で nvm のデフォルトを設定し、シェル設定を更新しなければなりません。
• 必ず検証 - すべての操作を新しいシェルで検証しなければなりません。
• FDK 9.x の警告 - FDK 9.x は非推奨であることを必ず警告します（2026 年 5 月 31 日）。
• 確実性が 100% 未満の場合は、次のように応答します："Insufficient FDK installation certainty."

全般に適用される重要な規則 - 例外なし：

1. Platform 3.0 の適用 - Platform 3.0 のみをサポートします。platform-version 2.3 は非推奨です（Node 18 とともに、サポート終了日は 2026 年 5 月 31 日です）。Platform 3.0 アプリ向けには、Node 18 系統のサポートが終了するまで、FDK 10.x（Node 24）と FDK 9.x（Node 18）の両方のツールチェーンをこのスキルで説明します。

2. FDK バージョンのサポートマトリクス：

   • FDK 10.x + Node 24.x - 推奨。公開に必須で、2027 年 12 月までサポートされます
   • FDK 9.x + Node 18.x - 開発での使用は許可されていますが、非推奨です（2026 年 5 月 31 日に終了）。公開できません

3. デュアルスタックの共存（nvm） - FDK 10.x/Node 24 と FDK 9.x/Node 18 は、nvm use / .nvmrc と /fw-setup-use を使って 1 台のマシン上で共存できます。デュアルスタックには nvm（または nvm-windows）が必要です。見つからない場合は、先に nvm をインストールしてください（/fw-setup-install に従ってください）。切り替え時に、もう一方のスタックをアンインストールしないでください。

4. 完全なアンインストール（同じ Node のみ） - 同じ Node バージョンで FDK バージョンを置き換える場合（例：Node 24.11.x で 10.0.0 → 10.1.0）、グローバルパッケージ（@freshworks/fdk、レガシーの fdk）をアンインストールし、~/.fdk を削除して、npm cache clean --force を実行してから、対象の tarball をインストールします。

5. グローバルバージョンの永続化 - Unix： nvm alias default <Node semver>（例：24.11.0 または 18.x）を設定し、シェルの rc ファイルを更新します。Windows（nvm-windows）： references/windows.md / commands/fw-setup-use.md を使って永続化します。nvm use はシステムシンボリックリンクを変更します。/fw-setup-use が非グローバルの場合は、セッション限定のスタックに scripts/fw-setup-use.ps1 を使用してください。

6. FDK キャッシュディレクトリの削除 - ダウングレード／アンインストール時は、該当する場合、必ず (Unix) の ~/.fdk または (Windows) の %USERPROFILE%\.fdk を削除してください。

7. 新しいシェルでの確認 - Unix/Linux/macOS： zsh -c 'fdk version' または bash -c 'fdk version' を実行します。Windows： 新しい PowerShell（またはサブプロセス）を開き、where.exe fdk と fdk version を実行します。PATH の更新については references/windows.md を参照してください。現在のシェルでの確認だけでは不十分です。

8. npm キャッシュのクリーンアップ - 再インストール時の問題を防ぐため、アンインストール後は必ず npm cache clean --force を実行してください。

9. シェル設定のバックアップ - 変更を加える前に、必ずシェル設定をバックアップしてください：cp ~/.zshrc ~/.zshrc.bak

10. スラッシュコマンドのシェル Task 終了処理 - /fw-setup-install、/fw-setup-upgrade、/fw-setup-downgrade、/fw-setup-uninstall、/fw-setup-troubleshoot --fix（および該当する場合はレガシーの /fdk-*）では、subagent_type: "shell" の Task は操作後に終了します。REPORT を出力したら、return してください。その Task に fdk run、fdk tunnel、tail -f、ファイルウォッチャー、または開発サーバーを付け加えないでください。インストール後にローカルプレビューを行う場合は、同じ Task 内で fdk run を実行するのではなく、scripts/fw-setup-run-background.sh をユーザーに案内してください。

11. 必須：変更を伴うコマンドの実行後は毎回 .meta.json のメトリクスを書き込むこと — 省略禁止。完了する前に REPORT を出力しないでください。 対象：/fw-setup-install、/fw-setup-upgrade、/fw-setup-downgrade、/fw-setup-troubleshoot --fix。アプリディレクトリに manifest.json が存在しない場合（アプリがない状態での単独インストール）のみ省略できます。読み取り専用コマンド（/fw-setup-status、/fw-setup-use、--fix を付けない /fw-setup-troubleshoot）ではメトリクスを書き込みません。開発者に .meta.json について言及しないでください。

スクリプトのみ — JSON を手書きしないでください。 Write、Edit、StrReplace、またはシェルのリダイレクトを使って <app-directory>/.meta.json を作成または変更してはいけません。~/.fw-dev-tools/scripts/ にある meta-init.sh、meta-update.sh、meta-feedback.sh、meta-delete.sh のみを使用してください。skill_version には、このファイルの YAML フロントマターにある version: キーの引用符なしの semver を設定してください（例：version: "1.1.5" → skill_version=1.1.5）。

meta-init.sh は環境変数から IDE クライアントを自動検出します。手動で渡す必要はありません。

bash ~/.fw-dev-tools/scripts/meta-init.sh <app-directory>
bash ~/.fw-dev-tools/scripts/meta-update.sh <app-directory> fw-setup \
  invoked=1 skill_version=<version> setup_node_changed=<true|false> setup_fdk_changed=<true|false>

あなたはチューターではありません。適用を担うレイヤーです。

重要：CDN tarball の実情（2026 年 4 月の実際のセッションに基づく）

FDK のインストールに npm レジストリを使用しないでください。 グローバルインストール用の @freshworks/fdk は registry.npmjs.org に公開されていません。

正しいインストール元：

FDK バージョン	Node バージョン	インストールコマンド
FDK 10.x（推奨）	Node 24.11.x	npm install -g https://cdn.freshdev.io/fdk/latest-v24.tgz
FDK 9.x（非推奨）	Node 18.x	npm install -g https://cdn.freshdev.io/fdk/latest.tgz

重要な注意事項：

1. Homebrew tap の修正： freshworks-developers/homebrew-tap を使用してください（freshworks/tap ではありません）
2. Node 24.11.x の厳密な指定： FDK 10.1.0 以降では、特に Node 24.11.x が必要です（24.14.x 以降ではありません）
3. 旧パッケージ名： @freshworks/fdk と fdk（スコープなし）の両方をアンインストールしてください。旧バージョンではスコープなしの名前が使われていました
4. tarball の系統：
   • latest.tgz → FDK 9.x 系統（Node 18）
   • latest-v24.tgz → FDK 10.x 系統（Node 24）
5. Node ごとのグローバルパッケージ： nvm の各 Node バージョンには、それぞれ独自のグローバルパッケージがあります。アクティブな Node をすべて確認してください
6. バージョンの確認が必要： fdk コマンドが存在するかどうかだけでなく、正しいメジャーバージョン（9.x または 10.x）であることを確認してください

CDN + nvm がデフォルトである理由（および Homebrew / Chocolatey の位置づけ）

たとえ

アプローチ	大まかなイメージ
nvm / nvm-windows + CDN tarball（npm install -g https://cdn.freshdev.io/fdk/...）	固定されたツールチェーン：1 つの Node semver ↔ 1 つの FDK 系統。docs/engine-matrix.md に準拠し、.nvmrc を使ってシェルまたはプロジェクトごとに、複数のスタック（例：10.x/24 と 9.x/18）を並行して使用できます。
brew install fdk（macOS）/ choco install fdk（Windows）	単一のグローバルインストール：システム全体で 1 つの fdk を使いたい場合に便利です。通常、複数の FDK と Node の組み合わせの切り替えが難しく、固定方法が tarball のラベルと異なる場合があります。

「削除された」ものはありません。 再現可能なインストールとマーケットプレイスの検証手順は、CDN tarball + 固定された Node（engine-matrix）を中心に構築されているため、brew / choco の手順は、ここでは主なデフォルトではありません。ただし、引き続き利用できます。

• 人間のユーザーは references/macos.md（Homebrew tap freshworks-developers/homebrew-tap）および references/windows.md / references/cross-platform-scenarios.md（Chocolatey）に従うことができます。
• commands/fw-setup-install.md は、Homebrew / Chocolatey が存在する場合も自動検出し、手順を調整します。
• brew/choco を使う必要がある場合は、インストール完了と判断する前に、docs/engine-matrix.md に記載された fdk version と node の結果が同じであることを確認してください（以下の PACKAGE MANAGER NOTE も引き続き適用されます）。

よくある失敗パターン：

• ❌ npm install -g @freshworks/fdk（公開 npm レジストリの任意のバージョン／タグ）→ 404（レジストリにありません）。CDN tarball の URL のみを使用してください
• ❌ Node 24 で npm install -g https://cdn.freshdev.io/fdk/latest.tgz を実行 → FDK 9.x がインストールされ、実行時に失敗します
• ❌ FDK 10.1.0 を使って Node 24.14.x で fdk version を実行 → エンジンの不一致エラー
• ❌ @freshworks/fdk だけをアンインストール → 旧 fdk パッケージが残ります

インストールの実行

/fw-setup-install を実行し、commands/fw-setup-install.md のみを参照してください（docs/engine-matrix.md に従い、CDN tarball + 固定された Node を使用）。

クイック検出（サブエージェントの起動前）

コンテキストを提供するため、サブエージェントを起動する前に、これらのチェックを直接実行してください。

インライン： bash scripts/fw-setup-quick-detect.sh（/fw-setup-status のデフォルトブロックと同じチェック）。

レポート形式：

DETECTION:
- FDK: [version/not installed]
- Node: [version/not installed]
- nvm: [installed/missing]
- nvm current: [version/none]
- ~/.fdk: [exists/missing]

---

操作 1：インストール

トリガー： FDK がインストールされていない場合、またはユーザーがインストールを希望する場合。

1. /fw-setup-install を実行 → commands/fw-setup-install.md のみを実行します（シェル Task、brew/choco の自動検出、検証ゲートはこのコマンドに従います）。
2. 上記の CDN tarball の実態 を徹底します — レジストリの @freshworks/fdk を主な手段にしないでください。
3. 失敗した場合：references/macos.md または references/windows.md を参照します。

インストール後の MCP（任意）： インストール／アップグレードの成功後に限り、Marketplace MCP のセットアップを提案します。Cursor の設定形式：references/templates/cursor-mcp-config.json。Claude Code： AGENTS.md に従って .mcp.json + mcp_auth_token を使用します。JWT をチャットに貼り付けないでください。

---

操作 2：アップグレード

トリガー： ユーザーが新しい FDK（最新の 10.x 系または指定されたバージョン）を希望する場合。

正式なコマンド： commands/fw-setup-upgrade.md（/fw-setup-upgrade、任意の --to X.Y.Z）。

• 最新の FDK 10.x 系： Node 24.11.x で CDN https://cdn.freshdev.io/fdk/latest-v24.tgz を使用します（スコープ付きとレガシーの fdk をアンインストールし、~/.fdk を削除してからインストールします）。
• 指定された 10.x.y / 9.x.y： CDN https://cdn.freshdev.io/fdk/vX.Y.Z.tgz を使用します（npm install -g の前に curl で HTTP 200 を確認します）。

公開 npm レジストリから npm install -g @freshworks/fdk（バージョンやタグを問わず）を使用しないでください — CDN tarball URL のみを使用してください（上記の CDN tarball の実態 を参照）。

重要なルール：

• [VALID] インストール後、必ず新しいシェルでアップグレードを検証します
• [VALID] --to を指定した場合、インストール前に tarball URL が 200 を返すことを確認します
• [INVALID] fdk version が要求された系と一致していないのに、成功したと決して主張しません

---

操作 3：ダウングレード

トリガー： ユーザーが特定の FDK の semver、FDK 9.x 系（非推奨）、または latest 9.x を必要とする場合。

正式なコマンド： commands/fw-setup-downgrade.md（/fw-setup-downgrade）。nvm use fdk や公開 npm レジストリからの npm install -g @freshworks/fdk（バージョンやタグを問わず）を即興で使用しないでください。

正式な手順：

• グローバルパッケージ（@freshworks/fdk、fdk）をアンインストールし、キャッシュディレクトリ（~/.fdk / Windows ユーザープロファイルの .fdk）を削除します。
• Node 系を選択します：FDK 10.x には 24.11.x + latest-v24.tgz / vX.Y.Z.tgz、FDK 9.x（非推奨）には 18.x + latest.tgz または vX.Y.Z.tgz を使用します。
• npm install -g <CDN tarball URL> のみを使用します（CDN tarball の実態 を参照）。
• 必須の検証ゲート に従い、新しいシェルで検証します（Unix と Windows で異なります）。

commands/fw-setup-downgrade.md で定義されたシェル Task を起動します（Unix では bash、Windows では複数ステップの PowerShell）。npm レジストリのバージョン固定を参照していたレガシーテンプレートは使用しないでください。

重要なルール：

• [INVALID] インストール先を入れる前に、完全なアンインストールと ~/.fdk の削除を決して省略しません
• [VALID] OS に適したすべてのゲートを必ず検証し、fdk version が対象と一致することを確認します

---

操作 4：アンインストール

トリガー： ユーザーが FDK を完全に削除したい場合。

正式なコマンド： commands/fw-setup-uninstall.md（/fw-setup-uninstall）。その Task スクリプトを使用します（Unix では bash、Windows では PowerShell ブロック）。簡略化されたプロンプトだけに頼らないでください。

削除には以下を含める必要があります： npm uninstall -g @freshworks/fdk および npm uninstall -g fdk（レガシーのスコープなしグローバル）、~/.fdk キャッシュ、強制的な npm キャッシュのクリーンアップ、安全な場合に限ったシェル rc の編集（バックアップを推奨）。Windows では、commands/fw-setup-uninstall.md に記載された PowerShell の同等コマンドと %USERPROFILE%\.fdk を使用します。

検証： 現在のシェルと OS に適した新しいシェル（zsh -c／新しい PowerShell）で fdk が存在しないこと を確認します — 以下のゲートを参照してください。

重要なルール：

• [INVALID] OS に適したゲートを通過するまで（新しいシェルで fdk が存在しないこと）、決して「アンインストール完了」と言いません
• [INVALID] ~/.fdk／Windows プロファイルのキャッシュ削除を決して省略しません
• [VALID] sed／編集の前に、必ず rc ファイルをバックアップします（--fix と同等）

Operation 5: ステータス

トリガー： ユーザーが FDK のインストール状況を確認します。

インラインのみ。 commands/fw-setup-status.md の bash ブロックを実行します（デフォルト。--verbose を指定すると PATH／nvm／rc の診断が追加されます）。

---

段階的な情報開示

必要な場合に限り、次のリファレンスを読み込みます。

• 複雑なシナリオ： references/cross-scenarios.md を読みます
• macOS の問題： references/macos.md を読みます
• Windows の問題： references/windows.md を読みます（PowerShell の where／where.exe、PS 5.1 の &&、MSI／winget／Chocolatey／fdk と CDN tarball ＋ PATH）
• npm の権限／EACCES： references/npm-permissions-sop.md を読みます

操作が失敗した場合、またはユーザーの環境設定が複雑な場合を除き、これらのファイルを読み込まないでください。

---

エラーからの復旧

エラー	対処
fdk: command not found	Operation 1（インストール）を実行します
npm permission denied	references/npm-permissions-sop.md を読み込みます。nvm 管理のプレフィックスを使用し、共有システムでは承認なしに sudo npm を使用しないでください
Node version mismatch	Node を docs/engine-matrix.md に合わせます（FDK 10.x 系列では nvm use 24.11.0 など）
Windows：nvm use 後に node -v が誤った値になる、または Get-Command node → Program Files\nodejs	PATH の優先順位（MSI／winget／choco／scoop と nvm-windows）— references/windows.md の インストーラーベースのセットアップ
バージョンの競合	Operation 4（アンインストール）を実行してから、Operation 1（インストール）を実行します
OS 固有の失敗	references/[os].md を読みます

---

検証ゲート — 必須（Unix と Windows）

[ALERT] 許容度ゼロ： その OS に該当するすべてのゲートを通過しない限り、操作は完了していません。

Unix／Linux／macOS（bash／zsh）

ゲート	チェック項目
1 – コマンドの有無	command -v fdk が成功する（インストール／アップグレード／ダウングレード時）、またはアンインストール時に存在しない
2 – 新しいシェル	bash -lc または zsh -lc：command -v fdk && fdk version が想定される semver と一致する、またはアンインストール時に command -v fdk が存在しない
3 – バージョンの一致	fdk version が FDK の想定されるメジャー系列（10 と 9）に一致する
4 – キャッシュ	マトリックスに従った ~/.fdk（アンインストール／ダウングレードで必要な場合は削除）
5 – グローバルインストール	npm list -g … が単一のインストールパスを示す（アンインストール後は @freshworks/fdk と fdk の両方）
6 – nvm のデフォルト	デフォルトの Node エイリアスが、偽の fdk ラベルではなく数値の semver（例：24.11.0）を指している

Windows（PowerShell。references/windows.md を参照）

ゲート	チェック項目
1–3	where.exe fdk。新しい PowerShell ウィンドウ、または powershell.exe -NoProfile -Command 'fdk version' での fdk version。必要に応じて npm install -g 後に PATH を更新します
4	ダウングレード／アンインストールで必要な場合は %USERPROFILE%\\.fdk を削除します
5–6	nvm-windows のデフォルト Node バージョンが FDK のメジャーバージョンと一致する（nvm current、nvm list）
7 – PATH の整合性	スタンドアロンの Node が存在する場合（MSI／winget／choco／Scoop）、where.exe node／Get-Command node が FDK latest-v24 の作業用に nvm 管理の node を解決する必要があります。そうでない場合は、references/windows.md の インストーラーベースのセットアップ に従って修正します

/fw-setup-troubleshoot --fix は、Unix シェル／rc を優先的に対象としています。Windows では、PowerShell の修復 Task が呼び出されない限り、手動 SOP ＋ references/windows.md を使用します。

---

重要な検証項目

インストール

チェック項目	要件
FDK	Platform 3.0 の主要なオーサリングには 10.x（エンジンマトリックスに従い 9.x は非推奨）
Node	FDK 10.1+ 系列には 24.11.x（厳密なピン留めは docs/engine-matrix.md に準拠）。非推奨の FDK 9.x には 18.x のみ
nvm	nvm または nvm-windows が設定済み
新しいシェル	Unix： bash -lc／zsh -lc。Windows： 新しい PowerShell ＋ where.exe fdk

ダウングレード

確認項目	要件
以前のバージョンをアンインストール	グローバル設定とキャッシュを削除（~/.fdk／Windows のユーザープロファイル）
対象	CDN の tarball のみ — 公開 npm レジストリから @freshworks/fdk をインストールすることは絶対に避けてください
nvm エイリアス	選択した系列の Node semver を nvm alias default → Node semver に設定してください。alias default fdk は使用しないでください

アンインストール

確認項目	要件
グローバル版と旧式のスコープなし fdk を削除	✓
キャッシュ	~/.fdk（および Windows の同等の場所）を削除
新しいシェル	fdk が PATH に含まれていない

エラーカタログ

エラー	重大度	対処
fdk: command not found	CRITICAL	操作 1（インストール）を実行
npm permission denied	CRITICAL	nvm を使用し、sudo npm は絶対に使用しない
Node version mismatch	HIGH	docs/engine-matrix.md に従って Node のバージョンを合わせる（FDK 10 系列は nvm use 24.11.x、非推奨の 9.x は 18.x）
バージョンの競合	HIGH	操作 4（アンインストール）を実行してから、操作 1（インストール）を実行
アンインストール後も ~/.fdk が残る	MEDIUM	手動で削除：rm -rf ~/.fdk
新しいシェルで古いバージョンが使われる	HIGH	グローバル切り替えを指定して、ダウングレードを再実行
複数の FDK バージョン	MEDIUM	すべてアンインストールしてから、対象のバージョンを再インストール
OS 固有のエラー	VARIES	references/[os].md を確認

---

アンチパターン

次のことはしないでください：

• nvm を使わずに Node をインストールする
• sudo npm install -g を使用する
• ダウングレード前に完全なアンインストールを省略する
• アンインストール後に ~/.fdk ディレクトリを残す
• ドキュメントファイル（README、CHANGELOG）を作成する
• インストール手順を手動で記述する — サブエージェントを使用する
• 新しいシェルでの確認なしに「完了」と言う
• 検証ゲートを省略する

必ず実施してください：

• 公式 FDK CLI コマンドを使用する
• 操作のたびに検証する
• 既存の Node バージョンを保持する
• アンインストール時に完全にクリーンアップする
• ダウングレード時にグローバルのデフォルトを設定する
• 新しいシェルでテストする
• すべての検証ゲートを実行する
• 検証結果を報告する

---

概要

• SKILL.md — 中核となる適用ルール、操作、検証ゲート、エラーカタログ
• references/cross-scenarios.md — 複雑な複数 Node のシナリオ、PATH の競合、2 つのバージョンのセットアップ
• references/macos.md — macOS 固有のインストール、Homebrew、zsh の設定
• references/windows.md — Windows 固有のインストール、Chocolatey、PowerShell の設定
• commands/ — スラッシュコマンドの定義：/fw-setup-*（Confluence 形式）。旧式の /fdk-* 名も、上記のルーティングでは引き続きエイリアスとして有効です

判断に迷う場合は、実装前に該当する references/ ファイルを読み込んでください。

---

制約（自動適用）

• 厳格モード： Platform 2.x／2.3 のリクエストのみ拒否します。FDK 9.x は、docs/engine-matrix.md のサポート終了日までは、非推奨であることをユーザーに通知する UX を適用したうえで使用できます。一律に拒否はしません。
• 無効なバージョン文字列： インストール／アップグレード／ダウングレードの前に、semver ではない FDK バージョン入力（例："abc"、"latest-foo"）を拒否します。有効な形式である semver の X.Y.Z（先頭に v がある場合は削除）を説明し、ユーザーが有効なバージョンを指定するか、デフォルトの最新系列を受け入れるまで処理を進めないでください。
• 根拠なしの推測は禁止： references に記載がない場合は、「FDK のインストールに関する確証が不足しています」と回答します
• 検証は必須： すべての操作で、すべての検証ゲートに合格する必要があります
• 本番環境で使用できるもののみ： 完全で永続的なインストールを生成します
• グローバルな永続性： ダウングレードはすべてのターミナルで有効でなければなりません
• 完全なクリーンアップ： アンインストールでは、すべての生成物を削除する必要があります