@ripla/godd-mcp 1.0.7-canary.2 → 1.0.7-canary.20

package/README.md

@@ -12,7 +12,7 @@
 | Node.js 20 以上 | `node -v` で確認 |
 | Cursor IDE | 最新版推奨 |
 | ライセンスキー | 管理者から受領 |
-| Registry URL | 管理者から受領 |
+| プロジェクトURL（Registry API URL） | GoDD Admin Console と連携してプロンプトを取得する接続先。管理者から受領 |
 
 ---
 
@@ -44,59 +44,70 @@ cd /path/to/your-project
 godd init
 ```
 
-対話形式で以下を入力していきます:
+実行前に、対話で聞かれる項目を準備しておきます:
 
-1. **ライセンスキー** — 管理者から受領したキーを入力
-2. **言語** — `ja`（日本語）など
-3. **Registry URL** — 管理者から指定された URL を入力
-4. **技術スタック** — 使用する言語・フレームワーク・DB を選択
+1. **ライセンスキー** — 管理者から受領したキーを入力（必須）
+2. **使用言語** — `ja` / `en` / `zh` / `ru` / `kz` / `tr` から選択（default: `ja`）
+3. **プロジェクトURL（Registry API URL）** — GoDD Admin Console と連携してプロンプトを取得する接続先。何も入力せず Enter を押すと、表示されたデフォルト値（`https://dev.api.godd.ripla-inc.com`）を使用します。適用後は使用した URL が表示されます
+4. **リポジトリ登録** — `origin` の Git リモート URL を Registry API に登録（`origin` がない場合は中断）
+5. **技術スタック選択** — `1,3,5` で複数選択、`all` で全選択。Step 2 以降は Enter でスキップ可（Step 1 は不可）
+6. **`config.godd` の保存先** — default はプロジェクトルートの `config.godd`
+7. **対応媒体の MCP 設定生成** — `[Y/n]`（`Y` のとき `.cursor/mcp.json` / `.mcp.json` / `.codex/config.toml` と `/godd-dev` コマンドファイルを生成します）
+8. **任意 MCP の追加登録** — 順番 7 で `Y` のときのみ、Headroom / agent-browser / TypeUI を個別に opt-in
 
-```
-ライセンスキーを入力してください: godd-xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
-使用言語を選択 [ja/en/zh/ru/kz/tr] (default: ja): ja
-Registry API URL (default: http://localhost:8100): https://godd-registry.example.com
-
-【言語】
-  1. Python
-  2. TypeScript
-  3. JavaScript
-  ...
-  選択 (例: 1,2): 1,2
-
-【フロントエンド】
-  1. React
-  2. Next.js
-  ...
-  選択 (例: 1): 1
-
-【バックエンド】
-  1. FastAPI
-  2. Django
-  ...
-  選択 (例: 1): 1
-```
+技術スタック選択は以下の 5 ステップで進みます。**Step 1（プログラミング言語）のみ Enter ではスキップできません**（1 言語以上必須。未選択だとエラーで終了）。Step 2 以降は Enter でスキップでき、選んだ言語に対応する技術だけが表示されます。設計パターン（`DDD / Clean Architecture`）は質問されず、自動設定されます。
+
+| Step | 質問カテゴリ | 表示される選択肢 |
+|------|--------------|------------------|
+| 1 | プログラミング言語（必須・Enter スキップ不可） | `Python` / `TypeScript` / `JavaScript` / `Go` / `PHP` / `Ruby` / `C` / `HTML` / `CSS` |
+| 2 | フレームワーク / ライブラリ | `React` / `Next.js` / `Vue.js` / `Angular` / `Svelte` / `Electron`、`FastAPI` / `Django` / `Flask` / `Express` / `Fastify` / `NestJS` / `Gin` / `Echo` / `Fiber` / `Laravel` / `Symfony` / `WordPress` / `Ruby on Rails` / `Sinatra` / `Koa` |
+| 3 | 関連ツール（CSS / ビルド / ORM / タスクキュー / ランタイム） | `Tailwind CSS` / `Sass` / `Vite` / `SQLAlchemy` / `Celery` / `Node.js` / `Agent Stdio` |
+| 4 | データベース | `PostgreSQL` / `MySQL` / `MongoDB` / `Redis` |
+| 5 | インフラ | `Docker` / `Terraform` |
 
-完了すると、以下の 3 ファイルが自動生成されます:
+順番 7 で `Y`（既定）を選んだ場合のみ、追加で以下を聞かれます（`n` だと `.cursor/mcp.json` / `.mcp.json` は生成されません）:
+
+| 質問 | 既定 | 前提 |
+|------|------|------|
+| Headroom（コンテキスト圧縮 MCP）も登録しますか？ | `N` | 事前に `pip install "headroom-ai[mcp]"` が必要 |
+| agent-browser（ブラウザ操作 MCP）も登録しますか？ | `N` | 事前に `npm install -g agent-browser && agent-browser install` が必要。`core` profile には JavaScript 実行（eval）が含まれます |
+| TypeUI（デザインスキル / UI プロンプト MCP）も登録しますか？ | `N` | ホスト型サーバー（`https://mcp.typeui.sh`）。初回利用時に TypeUI アカウントのサインインが必要 |
+| TypeUI Bearer トークン（TypeUI を `y` にしたときのみ） | 空 Enter | 通常は空 Enter で OAuth 対話サインイン。独自ホスト/トークン認証のときだけ入力 |
+
+完了すると、以下のファイルが生成されます:
 
 | ファイル | 内容 |
 |---------|------|
-| `config.godd` | 技術スタックコンポーネントの設定 |
-| `.env` | ライセンスキー・言語・Registry URL（GoDD 管理値） |
-| `.cursor/mcp.json` | Cursor IDE への MCP サーバー登録 |
-
-> **`.env` にはライセンスキーが含まれます。`.gitignore` に追加してください。**
+| `config.godd` | 技術スタックコンポーネントの設定（常に生成） |
+| `.env` | ライセンスキー・言語・プロジェクトURL（Registry API URL、GoDD 管理値。常に更新） |
+| `.cursor/mcp.json` | Cursor IDE への MCP サーバー登録（順番 7 で `Y` を選んだ場合のみ） |
+| `.mcp.json` | Claude Code への MCP サーバー登録（プロジェクトルート。順番 7 で `Y` を選んだ場合のみ、`.cursor/mcp.json` と同一構成。TypeUI 等の url エントリのみ `type: "http"` 付き） |
+| `.codex/config.toml` | Codex のプロジェクト MCP 設定（順番 7 で `Y` を選んだ場合のみ・Git 管理外） |
+| `.cursor/commands/godd-dev.md` / `.claude/commands/godd-dev.md` | Cursor / Claude Code 共通の直接コマンド `/godd-dev` |
+| `.agents/skills/godd-dev/SKILL.md` | Codex が自動検出する GoDD スキル（`$godd-dev`） |
+
+> **ライセンスキーは `config.godd`（手動設定・旧形式・互換読み込み）、`.env`、`.cursor/mcp.json`、`.mcp.json`、`.codex/config.toml` で扱われます。`.gitignore` への除外は必須です。**
+> `godd init` / `godd notes compose` が自動追記します（#1159 / #1216）。実行後は `git status` で除外を確認してください。
 >
 > ```gitignore
+> config.godd
 > .env
+> .cursor/mcp.json
+> .cursor/mcp.json.bak
+> .mcp.json
+> .mcp.json.bak
+> .codex/config.toml
 > ```
 
 ---
 
-### Step 3: Cursor IDE を再起動する
+### Step 3: IDE で MCP を有効化する
 
-設定後、Cursor IDE を再起動してください。
+- **Cursor**: Cursor IDE を再起動してください。`.cursor/mcp.json` が読み込まれ、godd MCP ツールが利用可能になります
+- **Claude Code**: 対象プロジェクトで `claude` を起動すると、プロジェクトスコープ MCP（`.mcp.json`）の**承認ダイアログ**が表示されるので godd を承認してください。**初回は承認するまで有効化されません**（ファイルを置いただけ・再起動しただけでは使えません）。承認状態は `claude mcp list` で確認できます（承認前は `⏸ Pending approval` と表示されます）
+- **Codex**: `.codex/config.toml` を読み込んで再起動し、`/mcp` で godd が接続済みになっていることを確認してください。開発入口は `$godd-dev` です。
 
-再起動後、Settings > MCP で `godd` サーバーのステータスが **Running** になっていれば完了です。
+Cursor では再起動後、Settings > MCP で `godd` サーバーのステータスが **Running** になっていれば完了です。Claude Code では承認後に `claude mcp list` で `godd` が接続済みと表示されれば完了です。
 
 ---
 
@@ -106,9 +117,9 @@ Registry API URL (default: http://localhost:8100): https://godd-registry.example
 
 ### 技術スタックを変更したい場合
 
-プロジェクトディレクトリで `godd init` を再実行してください。コンポーネントは `config.godd` を直接編集することもできます。ライセンスキー・言語・Registry URL は `.env` の `GODD_LICENSE_KEY` / `GODD_LANGUAGE` / `GODD_REGISTRY_URL` を編集してください。Cursor のチャットで `godd_config` ツールを使って更新することもできます。変更後は Cursor IDE を再起動してください。
+プロジェクトディレクトリで `godd init` を再実行してください。コンポーネントは `config.godd` を直接編集することもできます。ライセンスキー・言語・プロジェクトURL（Registry API URL）は `.env` の `GODD_LICENSE_KEY` / `GODD_LANGUAGE` / `GODD_REGISTRY_URL` を編集してください。Cursor のチャットで `godd-config` ツールを使って更新することもできます。変更後は Cursor IDE を再起動してください。
 
-> **再実行時の既存設定保護**: `config.godd` や `.env` が既に存在する場合、`godd init` は現在の設定をデフォルト値として表示します。Enter を押すだけで既存設定を保持できます。コンポーネントを再選択したい場合は、コンポーネント引き継ぎの質問で `n` を入力してください。
+> **再実行時**: 既存の `config.godd` があると検出メッセージが表示され、ライセンスキー・使用言語・プロジェクトURL（Registry API URL）・保存先は Enter で既存値を保持できます。コンポーネントは「既存のコンポーネント設定を引き継ぎますか？ `[Y/n]`」で引き継ぎ（既定 `Y`）か、ウィザードで再選択（`n`）を選べます。再選択時も Step 1（プログラミング言語）は 1 つ以上必須です。
 
 ### バイナリ（ZIP）でのインストール
 
@@ -141,7 +152,7 @@ chmod +x godd
 | コマンド | 短縮形 | 説明 |
 |---------|--------|------|
 | `godd install` | `godd i` | GoDD をシステムにインストール |
-| `godd init` | — | プロジェクトのセットアップ（config.godd + .cursor/mcp.json 生成） |
+| `godd init` | — | プロジェクトのセットアップ（config.godd + .cursor/mcp.json + .mcp.json 生成） |
 | `godd server` | `godd s` | MCP サーバーを起動（Cursor が自動実行） |
 | `godd notes compose` | `godd n compose` | GoDD Notes をローカル Docker Compose で起動（`--auto` で自動実行） |
 | `godd notes deploy` | `godd n deploy` | GoDD Notes をクラウドにデプロイ（infra の provider に従う、`-y` で確認スキップ） |
@@ -155,7 +166,7 @@ chmod +x godd
 
 ---
 
-## 利用可能なツール（29 件）
+## 利用可能なツール（31 件）
 
 Cursor のチャットで以下のツールが使えます。ツール名を指定しなくても、AI が自動的に適切なツールを選択します。
 全ツールの入力は optional — 引数なしで呼び出し可能で、Chat の文脈から AI が自動補完します。
@@ -166,60 +177,59 @@ Cursor のチャットで以下のツールが使えます。ツール名を指
 
 | ツール | 説明 | 呼び出し例 |
 |--------|------|-----------|
-| `godd_dev` | 開発ワークフローのメインエントリ。Spec 確認→影響調査→実装→品質ゲート→PR 本文生成まで一貫実行。デフォルトブランチ上では `feat/<slug>-<YYYYMMDD>` ブランチを自動作成 | 「ユーザー登録 API を実装して」 |
-| `godd_review` | CTO レベルのコードレビュー。アーキテクチャ一貫性・スケーラビリティ・技術的負債・ビジネスインパクトの観点でフィードバック。重大度分類（CRITICAL/MAJOR/MINOR/SUGGESTION）付き | 「この PR をレビューして」 |
-| `godd_check` | 品質チェック。Spec 整合・影響範囲・テスト計画・互換性・セキュリティの観点で提出前チェック | 「品質チェックして」 |
-| `godd_commit` | 責務単位コミット。1 コミット = 1 責務で分割し、Conventional Commits 準拠のメッセージで実行 | 「コミットして」 |
-| `godd_submit` | 提出一括実行。品質チェック → push → PR 作成を一括実行 | 「PR 出して」 |
-| `godd_notes_deploy` | GoDD Notes のデプロイ案内（compose / deploy / infra） | 「Notes をデプロイして」 |
+| `godd-dev` | 開発ワークフローのメインエントリ。**2モード制** — 受領資料や依頼を渡すと起票モード（仕様突合 → タスク分解 → 起票〔単一ユニットは実装Issue 1件のみ / 複数なら親Issue + 子Issue〕→ 質問投稿 → 実ファイル受領時のみ資料保管 → Issue を番号昇順に1件ずつ実装）、`#<Issue番号>` を渡すと実装モード（回答記録 → ATDD実装 → 品質ゲート → 責務別コミット、`feat/#<Issue>-...` ブランチを自動作成） | 「この議事録の内容で起票して」 / 「#1234 を実装して」 |
+| `godd-review` | CTO レベルのコードレビュー。アーキテクチャ一貫性・スケーラビリティ・技術的負債・ビジネスインパクトの観点でフィードバック。重大度分類（CRITICAL/MAJOR/MINOR/SUGGESTION）付き | 「この PR をレビューして」 |
+| `godd-check` | 品質チェック。Spec 整合・影響範囲・テスト計画・互換性・セキュリティの観点で提出前チェック | 「品質チェックして」 |
+| `godd-commit` | 責務単位コミット。1 コミット = 1 責務で分割し、Conventional Commits 準拠のメッセージで実行 | 「コミットして」 |
+| `godd-submit` | 提出一括実行。品質チェック → push → PR 作成を一括実行 | 「PR 出して」 |
+| `godd-notes-deploy` | GoDD Notes のデプロイ案内（compose / deploy / infra） | 「Notes をデプロイして」 |
 
 ### サブコマンド — Git 系
 
 | ツール | 説明 |
 |--------|------|
-| `godd_sync` | main ブランチの最新を取り込み。コンフリクトは SSOT 準拠側を優先 |
-| `godd_new_branch` | 変更を退避し、最新 main からブランチ作成して復元 |
-| `godd_git_workflow` | sync → new-branch → commit を一括実行 |
-| `godd_push` | 提出前チェック。品質ゲート・Spec 整合・機密情報チェック |
-| `godd_push_execute` | 提出前チェック後に git push 実行 |
-| `godd_pr_create` | 変更分析と PR テンプレート準拠の本文生成、GitHub 上で PR 作成 |
+| `godd-sync` | main ブランチの最新を取り込み。コンフリクトは SSOT 準拠側を優先 |
+| `godd-new-branch` | 変更を退避し、最新 main からブランチ作成して復元 |
+| `godd-git-workflow` | sync → new-branch → commit を一括実行 |
+| `godd-push` | 提出前チェック。品質ゲート・Spec 整合・機密情報チェック |
+| `godd-push-execute` | 提出前チェック後に git push 実行 |
+| `godd-pr-create` | 変更分析と PR テンプレート準拠の本文生成、GitHub 上で PR 作成 |
 
 ### サブコマンド — 設計・仕様系
 
 | ツール | 説明 |
 |--------|------|
-| `godd_spec` | 要求を仕様に変換。API/UI/DB/Feature/Usecase の粒度で Spec 化 |
-| `godd_impact` | 影響分析。変更の影響範囲を洗い出し |
-| `godd_test_plan` | テスト計画。unit/integration/e2e の必要性とテスト項目を策定 |
-| `godd_adr` | ADR 作成。設計判断をトレードオフ・ロールバック含めて記録 |
+| `godd-spec` | 要求を仕様に変換。API/UI/DB/Feature/Usecase の粒度で Spec 化 |
+| `godd-impact` | 影響分析。変更の影響範囲を洗い出し |
+| `godd-test-plan` | テスト計画。unit/integration/e2e の必要性とテスト項目を策定 |
+| `godd-adr` | ADR 作成。設計判断をトレードオフ・ロールバック含めて記録 |
 
 ### サブコマンド — ドキュメント系
 
 | ツール | 説明 |
 |--------|------|
-| `godd_documentation` | ドキュメント更新。Spec/README/設定説明/技術スタックの更新を洗い出し |
-| `godd_docs_init` | docs/ フォルダ構造をテンプレートから生成 |
-| `godd_docs_update` | コード変更に合わせて docs/ 内の関連ドキュメントを同期・更新 |
-| `godd_release_notes` | リリースノート作成。変更点・互換性・既知の問題を整理 |
+| `godd-docs-init` | docs/ フォルダ構造をテンプレートから生成。既存 docs/ が旧構成の場合は最新構成へ再配置 |
+| `godd-docs` | コード変更に合わせて docs/・README・設定・技術スタック・運用ドキュメントを同期・更新。`docs/` 未作成時は `godd-docs-init` を案内 |
+| `godd-release-notes` | リリースノート作成。変更点・互換性・既知の問題を整理 |
 
 ### サブコマンド — 分析・変換系
 
 | ツール | 説明 |
 |--------|------|
-| `godd_pr_analyze` | PR 分析。差分からレビュー観点・リスク・追加情報を整理 |
-| `godd_report` | 完了報告。変更概要・影響範囲・検証結果・残リスクを整理 |
-| `godd_req_to_flow` | 要求 → ビジネスフロー変換 |
-| `godd_req_to_tickets` | 要求 → チケット分解 |
-| `godd_spec_to_tickets` | 仕様 → チケット変換 |
+| `godd-pr-analyze` | PR 分析。差分からレビュー観点・リスク・追加情報を整理 |
+| `godd-report` | 完了報告。変更概要・影響範囲・検証結果・残リスクを整理 |
+| `godd-req-to-flow` | 要求 → ビジネスフロー変換 |
+| `godd-req-to-tickets` | 要求 → チケット分解 |
+| `godd-spec-to-tickets` | 仕様 → チケット変換 |
 
 ### サブコマンド — 環境・セットアップ系
 
 | ツール | 説明 |
 |--------|------|
-| `godd_setup` | 環境構築。config.godd / .env / .cursor/mcp.json 生成、依存導入 |
-| `godd_config` | 設定の表示・更新（components は config.godd、license_key 等は .env） |
-| `godd_install` | ツール/MCP サーバーインストール案内 |
-| `godd_dev_workflow` | 開発ワークフロー全体。環境構築→実装→テスト→コミット→PR |
+| `godd-setup` | 環境構築。config.godd / .env / .cursor/mcp.json 生成、依存導入 |
+| `godd-config` | 設定の表示・更新（components は config.godd、license_key 等は .env） |
+| `godd-install` | ツール/MCP サーバーインストール案内 |
+| `godd-dev-workflow` | 開発ワークフロー全体。環境構築→実装→テスト→コミット→PR |
 
 ---
 
@@ -231,14 +241,16 @@ Cursor のチャットで `/` を入力すると、GoDD の MCP ツールをス
 
 チャット入力欄で `/` を入力するとコマンド候補が表示されます。キーワードを続けて入力すると候補が絞り込まれます。
 
-**コマンド形式**: `/{サーバー名}/{ツール名}`
+**コマンド形式**: `/{サーバー名}/{ツール名}`（クライアントによってはツール名だけを表示）
 
-`godd init` で生成される `.cursor/mcp.json` のサーバーキー名（デフォルト: `godd`）がプレフィックスになります。例えばサーバー名が `godd` なら `/godd/dev`、`godd-a` なら `/godd-a/dev` のように表示されます。
+開発入口の正式なツール名は `godd-dev` です。`godd init` は Cursor / Claude Code 用のプロジェクトコマンド `.cursor/commands/godd-dev.md` / `.claude/commands/godd-dev.md` を生成するため、両媒体ではサーバー名に依存せず `/godd-dev` で呼び出せます。MCPツールを直接表示するクライアントでは、サーバーキーを付けた `/godd/godd-dev` や `/godd-a/godd-dev` になる場合があります。
+
+Codex はリポジトリ内の `.agents/skills/godd-dev/SKILL.md` を自動検出し、`$godd-dev` で同じ開発フローを起動できます。Codex の公式なプロジェクト共有スキル経路は `$` メンションであり、MCP由来の `/godd-dev` を全クライアントで強制する仕組みではありません。
 
 ```
 例 1: ツールを明示して依頼
 
-  /godd/dev ユーザー登録 API を実装して
+  /godd-dev ユーザー登録 API を実装して
 
 例 2: 複数ツールの組み合わせ
 
@@ -247,16 +259,16 @@ Cursor のチャットで `/` を入力すると、GoDD の MCP ツールをス
 例 3: ツールを指定しなくても AI が自動選択
 
   コミットメッセージを作って
-  → AI が自動的に godd_commit を選択
+  → AI が自動的に godd-commit を選択
 ```
 
 > **ヒント**: ツールを明示しなくても AI が自動的に最適なツールを選びます。特定のツールを確実に使いたい場合にスラッシュコマンドを活用してください。
 
-#### スラッシュコマンド一覧（29 件）
+#### スラッシュコマンド一覧（31 件）
 
 | コマンド（サーバー名 `godd` の場合） | 用途 |
 |--------------------------------------|------|
-| `/godd/dev` | 開発ワークフロー（ブランチ自動管理・分割コミット付き） |
+| `/godd-dev` | 開発ワークフロー（ブランチ自動管理・分割コミット付き） |
 | `/godd/review` | CTO レベルコードレビュー |
 | `/godd/check` | 品質チェック |
 | `/godd/commit` | 責務分割コミット |
@@ -273,8 +285,8 @@ Cursor のチャットで `/` を入力すると、GoDD の MCP ツールをス
 | `/godd/test_plan` | テスト計画作成 |
 | `/godd/adr` | ADR（設計判断記録）作成 |
 | `/godd/documentation` | ドキュメント更新支援 |
-| `/godd/docs_init` | docs/ フォルダ構造生成 |
-| `/godd/docs_update` | docs/ ドキュメント同期 |
+| `/godd/godd-docs-init` | docs/ フォルダ構造生成 |
+| `/godd/godd-docs` | docs/ ドキュメント同期 |
 | `/godd/release_notes` | リリースノート作成 |
 | `/godd/pr_analyze` | PR 分析 |
 | `/godd/report` | 完了報告作成 |
@@ -387,12 +399,15 @@ Notes のクラウドデプロイで pnpm 10+ 関連のエラーが出る場合
 
 ## GoDD Notes ライフサイクル
 
-GoDD Notes は GoDD のドキュメント閲覧・編集 Web アプリです。以下のステップで構築・デプロイします。
+GoDD Notes は GoDD のドキュメント閲覧・編集 Web アプリです。初回オンボーディングでは、まずローカル Docker Compose で動かし、AWS などのクラウドインフラ構築は後から必要なタイミングで実行します。ローカル利用だけなら AWS アカウント設定は不要です。
+
+> **初回の推奨順**: GoDD をインストール → プロジェクトで `godd init` → IDE で MCP 接続を確認 → `godd-docs-init` で `docs/` を初期化 → ローカルの `godd notes compose`（AWS 不要）→ 必要な場合のみ `godd notes infra` / `godd notes deploy`。
 
 ### 1. GoDD をインストール
 
 ```bash
 npm install -g @ripla/godd-mcp
+godd version
 ```
 
 Notes をクラウドデプロイする場合（ローカルに pnpm 10+ がある環境）は、pnpm 10+ 向けの Notes App ビルド対応が `@latest` に含まれるまで canary の利用を推奨します:
@@ -409,9 +424,45 @@ cd /path/to/your-project
 godd init
 ```
 
-プロジェクトごとに実行が必要です（2人目以降のメンバーも各自実行）。
+プロジェクトごとに実行が必要です（2人目以降のメンバーも各自実行）。`godd init` が生成した `.cursor/mcp.json` を Cursor に読み込ませるため、この後に Cursor IDE を再起動します。
+
+### 3. MCP 接続を確認
+
+1. Cursor IDE を再起動する
+2. Settings > MCP で `godd` サーバーが **Running** であることを確認する（これが主確認）
+3. 任意で、チャットから `godd-check` を呼ぶか、MCP ツール一覧に GoDD ツールが並ぶことを確認する
+
+### 4. docs/ 構造を初期化
 
-### 3. クラウドインフラ構築（初回のみ）
+GoDD Notes は GitHub リポジトリの `docs/` を表示・編集対象にします。まだ `docs/` がないプロジェクトでは、Cursor のチャットから `godd-docs-init`（MCP ツールのサーバー名付き表示例: `/godd/godd-docs-init`）を実行して、標準のドキュメント構造を作成します。
+
+```text
+Cursor IDE で: godd-docs-init を使って docs/ を初期化して
+```
+
+### 5. ローカルで Notes を起動
+
+前提: Docker Desktop が起動済みであること。加えて、GitHub App 用の以下3つの値をOrg管理者から事前に受け取っていること（AWS アカウントは不要でも、これらは必要です）。
+- App ID
+- Installation ID
+- Private Key
+
+```bash
+godd notes compose --auto
+```
+
+Docker Compose でローカルに Notes 環境を立ち上げます。起動後は以下のエンドポイントを確認します。
+
+| 種別 | URL |
+|------|-----|
+| API | `http://localhost:8000` |
+| App | `http://localhost:5173` |
+
+`--auto` を省略すると、AI による自動実行ではなく手動確認しながら進められます。ローカル利用の詳細は [GoDD Notes 使い始め方ガイド](../docs/007_guides/godd_notes_getting_started.md) を参照してください。
+
+### 6. 後でクラウドインフラを構築（必要な場合のみ）
+
+本番 AWS などへデプロイする段階で、インフラ担当者が `godd notes infra` を実行します。ローカル利用だけならこの手順は不要です。
 
 ```bash
 godd notes infra
@@ -428,7 +479,7 @@ godd notes infra
 既存環境で旧ブランド名の出力先や設定ファイルを生成済みの場合は、
 `godd notes infra` を再実行して `godd-notes/` と `.godd-notes-*.json` を再生成してください。
 
-### 4. デプロイ
+### 7. クラウドへデプロイ（必要な場合のみ）
 
 ```bash
 godd notes deploy      # 対話形式
@@ -442,6 +493,45 @@ godd notes deploy -y   # 確認スキップ（CI 向け）
 
 > `godd notes deploy` 実行時に `@ripla/godd-mcp` の新しいバージョンが利用可能な場合、警告が表示されます。
 
+### 8. 既存環境を最新化する（CLI 更新の反映）
+
+すでにデプロイ済みの環境に、新しい `@ripla/godd-mcp` バージョン（Terraform テンプレート変更を含む）を反映する場合の手順です。手順 1〜7（新規オンボーディング）は不要です。
+
+```bash
+# 1. CLI を更新（インフラ変更を検証する場合は canary を明示。安定版のみなら不要）
+npm install -g @ripla/godd-mcp@canary
+godd version
+
+# 2. AWS CLI 認証を確認
+export AWS_PROFILE=<PROFILE>          # PowerShell: $env:AWS_PROFILE = "<PROFILE>"
+aws sts get-caller-identity
+
+# 3. Terraform ファイル・同梱ソースを最新テンプレートで再生成（保存済み設定を非対話で再利用）
+godd notes infra --yes
+
+# 4. Terraform テンプレートに変更がある場合のみ、{env}-iam → {env} の順で適用（apply 前に plan で差分確認）
+cd terraform/godd-notes/{env}-iam
+terraform init
+cd ../{env}
+terraform init
+
+cd ../{env}-iam
+terraform plan
+cd ../{env}
+terraform plan
+
+cd ../{env}-iam
+terraform apply
+cd ../{env}
+terraform apply
+
+# 5. アプリを再デプロイ
+cd /path/to/your-project
+godd notes deploy -y
+```
+
+> **`{env}-iam` を先に適用する**: `{env}` モジュール（ECS/RDS/ALB 等）は `{env}-iam` が作成する IAM ロール（ECS 実行ロール、GitHub Actions OIDC 等）を参照するため、`{env}-iam` → `{env}` の順を守ってください。`godd notes infra --yes` は `.tf` を毎回無条件で再生成しますが、**テンプレート自体に変更がある場合のみ** `terraform apply` の再適用が必要です（同梱ソース [`notes-api`/`notes-app`] の変更だけなら手順 4 は不要）。
+
 ### Notes デプロイで `esbuild` の build script が拒否される
 
 pnpm 10+ で `[ERR_PNPM_IGNORED_BUILDS] Ignored build scripts: esbuild` や `pnpm install` 失敗が出る場合:
@@ -450,15 +540,9 @@ pnpm 10+ で `[ERR_PNPM_IGNORED_BUILDS] Ignored build scripts: esbuild` や `pnp
 2. `notes-app` を再 scaffold する: プロジェクトで `godd notes infra` を再実行（`pnpm-workspace.yaml` を含む同梱ソースで上書き更新）
 3. 再デプロイする: `godd notes deploy -y`
 
-ローカルで `notes-app` を直接ビルドする場合は、同梱の `notes-app/README.md` を参照してください。
+Terraform テンプレートの変更も反映する必要がある場合は、上記「8. 既存環境を最新化する」の手順4（`terraform apply`）も実行してください。
 
-### ローカル開発（Docker Compose）
-
-```bash
-godd notes compose
-```
-
-Docker Compose でローカルに Notes 環境を立ち上げます。
+ローカルで `notes-app` を直接ビルドする場合は、同梱の `notes-app/README.md` を参照してください。
 
 ---