@ripla/godd-mcp 1.0.7-canary.9 → 1.0.7

package/templates/notes-docs/007_guides/bot-token-setup.md

@@ -0,0 +1,174 @@
+# GitHub App セットアップ
+
+> **管理者の方向けのページです。** GitHub App の作成には組織の管理権限が要ります。
+>
+> **開発を担当する方は読む必要がありません。** ここで作られた3つの値を受け取るだけです（[getting_started.md](./getting_started.md) の手順1）。
+
+GoDD Notes が GitHub の `docs/` を読み書きし、PR / Issue を作成するために必要な **GitHub App** の作成・設定手順です。
+
+> **PAT（Personal Access Token / `ghp_...`）は使用できません。** `GITHUB_TOKEN` を設定しても無視されます。GitHub 連携は GitHub App のみです。
+
+---
+
+## なぜ GitHub App なのか
+
+| | GitHub App | PAT |
+|---|---|---|
+| コミット / PR の作者 | Bot アカウント（例: `<app-name>[bot]`） | 個人アカウント |
+| トークンの寿命 | 自動ローテーション（短期） | 手動失効まで有効 |
+| 権限の範囲 | リポジトリ単位で限定 | 個人の全権限を継承 |
+| GoDD Notes での可否 | **必須** | **禁止（無視される）** |
+
+個人アカウントの権限で Notes が書き込むことを避け、権限を最小限に閉じるためです。
+
+---
+
+## 用意するもの
+
+| 項目 | 備考 |
+|---|---|
+| GitHub Organization の管理者権限 | App の作成とインストールに必要 |
+| 対象リポジトリ | GoDD Notes が読み書きする `docs/` を持つリポジトリ |
+
+**この手順で最終的に得られる3つの値**（GoDD Notes が必要とするもの）:
+
+| 値 | 環境変数名 |
+|---|---|
+| App ID | `GITHUB_APP_ID` |
+| Private Key（PEM） | `GITHUB_APP_PRIVATE_KEY` |
+| Installation ID | `GITHUB_APP_INSTALLATION_ID` |
+
+3つのうち1つでも欠けると Notes API は**モックモード**（GitHub API を呼ばない）で起動し、実際の読み書きは行われません。
+
+---
+
+## Step 1: GitHub App を作成する
+
+1. GitHub にログイン → **Settings** → **Developer settings** → **GitHub Apps** → **New GitHub App**
+2. 以下を入力する
+
+   | 項目 | 値 |
+   |---|---|
+   | App name | 任意（例: `<org>-notes-bot`）。ここで付けた名前が Bot の表示名になる |
+   | Homepage URL | 任意 |
+   | Webhook | **Active のチェックを外す**（GoDD Notes は Webhook を使わない） |
+
+3. **Permissions → Repository permissions** を設定する
+
+   | 権限 | レベル | 用途 |
+   |---|---|---|
+   | Contents | **Read & Write** | `docs/` のファイル読み書き |
+   | Pull requests | **Read & Write** | 編集内容の PR 作成 |
+   | Issues | **Read & Write** | Issue 起票・ラベル付与 |
+
+   Organization permissions は不要です。
+
+4. **Where can this GitHub App be installed?** → `Only on this account`
+5. **Create GitHub App** をクリック
+
+---
+
+## Step 2: App ID と Private Key を取得する
+
+1. 作成した App のページで **App ID**（数値。例: `123456`）を控える
+2. **Generate a private key** をクリックし、ダウンロードされる `.pem` ファイルを保管する
+
+> **Private Key は秘密情報です。** リポジトリにコミットしない、チャットに貼らない、Secrets 管理サービス経由で渡す、を徹底してください。
+
+---
+
+## Step 3: App をリポジトリにインストールする
+
+1. 左メニュー → **Install App** → 対象 Organization の横の **Install**
+2. **Only select repositories** を選び、対象リポジトリを指定する
+3. **Install** をクリック
+4. インストール後の URL 末尾の数字が **Installation ID** です
+
+   ```text
+   https://github.com/organizations/<org>/settings/installations/<INSTALLATION_ID>
+   ```
+
+> **リポジトリの追加を忘れやすいので注意。** 3変数が正しく設定されていても、対象リポジトリが未追加だと GitHub API が 401 / 403 を返し、Notes は**エラーになります**（モックモードにはなりません）。
+
+---
+
+## Step 4: 3つの値を GoDD Notes に渡す
+
+### ローカル（Docker Compose）
+
+`godd notes compose` のウィザードで3つの値を入力します。
+
+```shell
+godd notes compose
+```
+
+対話式の Private Key は**1行入力**です。複数行の PEM は改行を `\n` に置換して貼り付けるか、`--auto` / `--config` を使ってください。
+
+生成される `.env` では PEM の改行を `\n` に正規化します（Compose が1行値として読めるようにするため。API 側で復元します）。
+
+詳細は [setup_local_environment.template.md](./setup_local_environment.template.md) を参照してください。
+
+### クラウド（AWS）
+
+AWS Secrets Manager に登録します。`{env}` は環境名（例: `dev`）に読み替えてください。
+
+```bash
+aws secretsmanager put-secret-value \
+  --secret-id godd-notes/{env}/github-app-id \
+  --secret-string "<APP_ID>" \
+  --profile <PROFILE> --region <REGION>
+
+aws secretsmanager put-secret-value \
+  --secret-id godd-notes/{env}/github-app-installation-id \
+  --secret-string "<INSTALLATION_ID>" \
+  --profile <PROFILE> --region <REGION>
+```
+
+> **Private Key（PEM）の投入は管理者限定の手順です。** 手順とアクセス権については [setup_godd_notes.md](./setup_godd_notes.md) の「8-4. Private Key の設定を管理者に依頼」を参照してください。
+
+ECS タスク定義は `GITHUB_TOKEN` を注入しません。Secrets Manager から GitHub App の3変数のみを注入します。
+
+---
+
+## Step 5: 動作を確認する
+
+```bash
+godd notes status
+```
+
+**`github_write_author: bot`** かつ **installation token refresh が OK** であれば設定成功です。
+
+API に直接問い合わせる場合:
+
+```bash
+# 基本ヘルス
+curl -s http://localhost:3100/api/health | jq .
+# 期待: { "status": "ok", "github_app_configured": true, "github_write_author": "bot" }
+
+# installation token の refresh まで確認
+curl -s http://localhost:3100/api/health/github-app | jq .
+# 期待: { "status": "ok", "github_write_author": "bot", "token_refresh": "success" }
+```
+
+最後に、Notes App 上でファイルを編集して保存し、GitHub 側で PR の author が Bot アカウント（`<app-name>[bot]`）になっていることを確認します。
+
+---
+
+## うまくいかないとき
+
+| 症状 | 原因 | 対処 |
+|---|---|---|
+| `github_write_author: mock` | 3変数のいずれかが未設定 | 3つすべてが渡っているか確認。クラウドでは Secrets 登録後に ECS を再デプロイ |
+| 401 / 403 エラーになる | App が対象リポジトリに未インストール | Step 3 でリポジトリを追加 |
+| PAT を設定したのに動かない | PAT は仕様上無視される | GitHub App の3変数を設定する |
+| Private Key の読み込みに失敗する | PEM の改行が壊れている | `--auto` / `--config` で渡すか、改行を `\n` に正規化する |
+
+その他の症状は [troubleshooting.md](./troubleshooting.md) を参照してください。
+
+---
+
+## 関連ドキュメント
+
+- GoDD Notes の構築: [setup_godd_notes.md](./setup_godd_notes.md)
+- ローカル環境構築: [setup_local_environment.template.md](./setup_local_environment.template.md)
+- Notes の使い方: [godd_notes_usage.md](./godd_notes_usage.md)

package/templates/notes-docs/007_guides/getting_started.md

@@ -0,0 +1,112 @@
+# はじめかた
+
+**環境構築が終わった人が、最初の1件をやってみるページ**です。
+
+> **まだ環境構築が終わっていない場合**は、先に npm パッケージ `@ripla/godd-mcp` の README（「はじめて参加した方へ」）を進めてください。受け取るものの確認から、GoDD が使える状態になるまでが書かれています。
+
+エンジニア経験は前提としません。**上から順にそのとおり実行すれば進みます。**
+
+> 分からない言葉が出てきたら [glossary.md](./glossary.md)、途中で詰まったら [troubleshooting.md](./troubleshooting.md) を開いてください。
+
+---
+
+## 練習で1件やってみる
+
+### なぜやるの？
+
+明日から1人で回せるように、**今日のうちに一通り試しておきます。**
+
+### 先に用意するもの
+
+**練習用の Issue を1件もらいます。** PM に「**セットアップの練習用に、軽い Issue を1件割り当ててください**」と伝えてください。いきなり本番の作業でなくて構いません。
+
+> **Issue（イシュー）** = 「これをやってください」と書かれた作業の依頼書。1枚に1つの作業が書いてあり、`#1234` のような番号が付いています。
+>
+> **PM** = 作業の内容を決めて、誰がやるか割り振る人。**（このプロジェクトでの担当者名を書き足してください）**
+
+### やり方
+
+チャット欄に、上から順に打ちます。**打つのは左側の文字だけ**です。
+
+```text
+最新の状態にして
+```
+
+他の人が直した分を取り込みます。次に、もらった番号を打ちます。
+
+```text
+#1234 を実装して
+```
+
+あとは AI が作り終わるのを待ちます。**この時点ではまだ、作ったものは自分のパソコンの中だけ**にあります。
+
+最後までできたら、報告の終わりに「次にこれを実行してください」と書かれています。**そのとおりに、続けて2回打ちます。**
+
+```text
+ドキュメントを合わせて
+```
+
+```text
+PR を出して
+```
+
+これで **PR ができ、URL が報告されます。** その URL を開き、レビュアーに「見てください」と伝えれば完了です。
+
+> **PR** = 「この変更を入れていいか見てください」というお願いのこと。**最初から見てもらえる状態**で作られるので、切り替える操作は要りません。
+
+### 途中で終わったとき
+
+| 終わり方 | 次にすること |
+|---|---|
+| **質問があって進めなかった** | Issue のコメントに質問が書かれています。**PM に「この質問に答えてください」と伝える** |
+| **途中で止まった** | Issue のコメントに理由が書いてあります。**分からなければ、ブランチの名前を伝えて相談する** |
+
+どちらも失敗ではありません。詳しくは [../006_development_workflow/daily_flow.template.md](../006_development_workflow/daily_flow.template.md) を見てください。
+
+### これができていれば OK
+
+PR ができて、レビュアーに「見てください」まで伝わっている。
+
+**ここまでできれば、明日からは同じことの繰り返し**です。詳しい進め方は [../006_development_workflow/daily_flow.template.md](../006_development_workflow/daily_flow.template.md) にあります。
+
+---
+
+## GoDD Notes も使う場合（使わないなら読み飛ばして OK）
+
+**GoDD Notes** は、仕様書を Word や Excel のような画面で編集できるアプリです。使うかどうかはプロジェクトによります。
+
+| 使い方 | 手順 |
+|---|---|
+| **チームが既に立てている** | URL を教えてもらってブラウザで開くだけ。セットアップ不要 |
+| **自分のパソコンで動かす** | Docker Desktop を入れて [setup_local_environment.template.md](./setup_local_environment.template.md) を実行 |
+
+できることは [godd_notes_features.md](./godd_notes_features.md)、操作方法は [godd_notes_usage.md](./godd_notes_usage.md) を参照してください。
+
+---
+
+## セットアップが終わったら
+
+**明日からは [../006_development_workflow/daily_flow.template.md](../006_development_workflow/daily_flow.template.md) だけを見れば進められます。**
+
+| 場面 | 見るもの |
+|---|---|
+| 毎日の進め方 | [daily_flow.template.md](../006_development_workflow/daily_flow.template.md) |
+| 言葉が分からない | [glossary.md](./glossary.md) |
+| 詰まった | [troubleshooting.md](./troubleshooting.md) |
+| ツールを探す | [godd_tools.md](./godd_tools.md) |
+| Git のルールを確認する | [git.template.md](../006_development_workflow/git.template.md) |
+
+---
+
+## 途中で止まってしまったら
+
+**20分やって進まなかったら、遠慮なく聞いてください。** 最初の準備はパソコンごとに違いが出やすく、**聞いたほうが速い**部分です。自分で解決する必要はありません。
+
+聞くときに、この4つを伝えるとすぐ答えが返ってきます。
+
+```text
+1. どの手順で止まったか（例: README の Step 4）
+2. 何を打ったか
+3. 画面に出た文字（そのままコピーして貼る。まとめない）
+4. 使っているパソコン（Windows / Mac）
+```

package/templates/notes-docs/007_guides/glossary.md

@@ -0,0 +1,145 @@
+# 用語集
+
+**分からない言葉が出てきたときに引くページ**です。上から読む必要はありません。
+
+**全部を覚える必要はありません。** 現場では当たり前のように使われるが、初めての人には意味が分からない言葉だけを集めています。
+
+> 読み方のコツ: 「それが何か」よりも **「何のためにあるか」** を先に掴むと、手順の意味が分かります。
+
+---
+
+## このドキュメント群での言葉づかい
+
+同じものを別の言い方で呼ばないよう、次のとおりに揃えています。**他の資料で違う言い方を見かけたら、同じものを指しています。**
+
+| この資料で使う言葉 | 意味 | 同じものを指す別の言い方 |
+|---|---|---|
+| **作業** | Issue 1件で表される、やることの単位 | 仕事、タスク、チケット |
+| **PM** | 作業の内容を決めて、誰がやるか割り振る人 | 依頼元、プロダクトオーナー、PdM |
+| **レビュアー** | 作ったものの中身を見る人 | 先輩、レビュー担当 |
+| **AI エディタ** | AI と会話できるチャット欄が付いた、文章を書くソフト（Cursor / Claude Code / Codex） | IDE、エディタ |
+| **品質ゲート** | **自分のパソコンで**走る自動チェック | ローカルチェック |
+| **CI** | **GitHub 側で**走る同じ自動チェック | GitHub Actions、ビルド |
+
+> **品質ゲートと CI は同じ内容を別の場所で走らせています。** 手元で通っても GitHub 側で落ちることがあります（環境の違いのため）。
+
+---
+
+## まず押さえる5つ
+
+この5つが分かれば、日々の作業はほぼ読めます。
+
+| 用語 | 一言で | 何のためにあるか |
+|---|---|---|
+| **リポジトリ** | プロジェクトのファイル置き場 | チーム全員が同じファイルを共有し、変更の履歴を全部残すため |
+| **ブランチ** | 作業用のコピー | 他の人の作業を壊さずに、自分の変更だけを試すため |
+| **コミット** | 変更の記録 | 「いつ・誰が・何を・なぜ変えたか」を残し、後から戻せるようにするため |
+| **PR（プルリクエスト）** | 変更を取り込んでもらう申請 | 他の人にレビューしてもらってから本体に反映するため |
+| **Issue** | やることリストの1件 | 誰が何をやるかを見える化し、議論をそこに集約するため |
+
+---
+
+## パソコン・環境まわり
+
+| 用語 | 読み | 説明 |
+|---|---|---|
+| **ターミナル** | — | 文字でパソコンに命令する画面。macOS は「ターミナル」、Windows は「PowerShell」。GoDD の `godd ...` コマンドはここに打ち込む |
+| **コマンド** | — | ターミナルに打ち込む命令文。`godd init` など |
+| **PATH** | パス | 「コマンドを探しに行く場所のリスト」。`command not found` はここに登録されていないのが原因。**ターミナルを再起動すると直ることが多い** |
+| **環境変数** | かんきょうへんすう | パソコンやアプリが参照する設定値。パスワードのような秘密情報を、ファイルに直接書かずに渡すために使う |
+| **`.env`** | ドットエンブ | 環境変数をまとめて書いたファイル。**秘密情報が入るので絶対に共有・コミットしない** |
+| **Docker** | ドッカー | アプリを動かすのに必要な一式（DB・サーバーなど）を箱ごと用意する仕組み。自分のパソコンに個別インストールしなくて済む |
+| **Docker Compose** | — | Docker の箱を複数まとめて起動する仕組み。GoDD Notes はこれでローカル起動する |
+| **コンテナ** | — | Docker が作る「箱」1つ分。停止・削除しても、パソコン本体には影響しない |
+| **ポート** | — | パソコン内のサービスの窓口番号。`http://localhost:5175` の `5175` の部分。**「ポートが使用中」= 別のアプリが同じ番号を使っている** |
+
+---
+
+## Git・GitHub まわり
+
+| 用語 | 読み | 説明 |
+|---|---|---|
+| **Git** | ギット | 変更履歴を記録する仕組みそのもの |
+| **GitHub** | ギットハブ | Git のファイルをインターネット上に置いて共有するサービス |
+| **リポジトリ** | — | プロジェクト1つ分のファイル置き場。「リポ」と略されることも |
+| **クローン（clone）** | — | GitHub 上のリポジトリを自分のパソコンにコピーしてくること。最初に1回だけ行う |
+| **ブランチ** | — | 作業用の枝分かれ。`feat/#123-...` のような名前を付ける |
+| **`main`** | メイン | 全員の作業が最終的に集まる幹。**ここに直接書き込むのは禁止**（必ず PR を経由する） |
+| **コミット** | — | 変更に説明文を付けて記録すること。`add: ユーザー一覧画面を追加` のように書く |
+| **push** | プッシュ | 自分のパソコンの記録を GitHub に送ること |
+| **Squash merge** | スカッシュマージ | PR の複数のコミットを1つにまとめて取り込む方法。**取り込む操作はレビュアーが行う** |
+| **pull** | プル | GitHub の最新を自分のパソコンに取り込むこと |
+| **PR / プルリクエスト** | — | 「自分のブランチを `main` に取り込んでください」という申請。レビューはここで行われる |
+| **レビュー** | — | 他の人が変更内容を確認して、指摘・承認すること |
+| **マージ** | — | PR が承認されて `main` に取り込まれること |
+| **Squash merge** | スカッシュ | 複数のコミットを1つにまとめて `main` に取り込む方式。GoDD の標準 |
+| **コンフリクト** | — | 同じ場所を2人が別々に変えて、どちらを採用するか機械が決められない状態。**自分で判断できないときは人に聞いてよい場面** |
+| **Issue** | イシュー | やること・不具合・質問を書いた1件のチケット |
+| **ラベル** | — | Issue や PR の分類タグ（`bug` / `undecided` など） |
+
+---
+
+## 品質・テストまわり
+
+| 用語 | 読み | 説明 |
+|---|---|---|
+| **品質ゲート** | — | 提出前に**自分のパソコンで**走る一連のチェック（整形・lint・型チェック・ビルド）。**これが通らない状態で PR を出さない** |
+| **E2E テスト** | イーツーイー | 画面を実際に操作して、最初から最後まで動くか確かめるテスト |
+| **lint** | リント | 書き方のルール違反を機械的に指摘する仕組み |
+| **型チェック** | — | 「数値が入るはずの場所に文字が入っている」ような矛盾を、動かす前に見つける仕組み |
+| **ビルド** | — | 書いたコードを実際に動く形に組み立てること。失敗する = どこかが壊れている |
+| **テスト** | — | 「こう操作したらこうなるはず」を自動で確認する仕組み |
+| **unit テスト** | ユニット | 部品1つが正しく動くかの確認 |
+| **integration テスト** | インテグレーション | 部品同士のつなぎ目（API・DB）が正しく動くかの確認 |
+| **e2e テスト** | イーツーイー | 実際の画面操作を通しで再現する確認 |
+| **CI** | シーアイ | PR を出すと GitHub 側で自動的に走るチェック。**赤（失敗）のままではマージできない** |
+| **回帰テスト** | かいき | 直したバグが再発していないかを確認するテスト |
+
+---
+
+## GoDD 固有
+
+| 用語 | 説明 |
+|---|---|
+| **GoDD** | 開発の進め方（方法論）を AI に注入する仕組み。AI エディタから `godd-*` ツールとして呼び出す |
+| **GoDD Notes** | GitHub の `docs/` を、Word / Excel のような画面で編集できるようにした Web アプリ |
+| **MCP** | AI エディタに外部の道具を接続する共通規格。GoDD はこれで AI エディタに繋がる |
+| **AI エディタ** | GoDD の入口。**Cursor / Claude Code / Codex** に対応 |
+| **`/godd-dev`** | 開発の直接入口。Cursor / Claude Code は `/godd-dev`、Codex は `$godd-dev` |
+| **ライセンスキー** | GoDD を使ってよい人だと示す鍵。`godd-xxxx-...` の形式。管理者からもらう。**人に渡さない・ファイルに書いて共有しない** |
+| **Registry URL** | GoDD が設定を取りに行く先の住所。`https://` で始まる。管理者からもらい、`godd init` で1回だけ入力する |
+| **技術スタック** | そのプロジェクトで使っているプログラムの種類（React、Python など）。GoDD が作り方を合わせるために `godd init` で聞かれる。**分からなければチームに聞く** |
+| **`config.godd`** | 使っている技術（言語・フレームワーク・DB）を記録した設定ファイル。`godd init` が作る。**中を開いて編集する必要はない** |
+| **Spec / 仕様書** | 「何を作るか」を書いた文書。`docs/003_requirements/` にある |
+| **SSOT** | Single Source of Truth（唯一の正）。**迷ったら仕様書が正しい**、という原則 |
+| **SDD** | 仕様書を先に書いてから実装する進め方 |
+| **ATDD / TDD** | 「こうなったら合格」を先に決め、失敗するテストを書いてから実装する進め方 |
+| **ADR** | 「なぜこの作り方にしたか」を残す記録。後から理由を辿れるようにするためのもの |
+| **ADR** | 「なぜこの方法を選んだか」を残す記録。後から経緯を辿れるようにするため |
+| **起票モード** | `godd-dev` に資料を渡したときの動き。Issue を作るところから実装まで進む |
+| **実装モード** | `godd-dev` に `#Issue番号` を渡したときの動き。その1件だけを実装する |
+| **skipped / blocked** | `godd-dev` が実装を見送った状態。skipped = 質問の回答待ち、blocked = 途中で止まった。詳細は [../006_development_workflow/workflow.template.md](../006_development_workflow/workflow.template.md) |
+| **`undecided` ラベル** | 「未定」と回答された箇所を、仮の判断で実装したことを示す Issue のラベル |
+
+---
+
+## リリースまわり
+
+| 用語 | 説明 |
+|---|---|
+| **リリース** | 作ったものを実際に使える状態にすること |
+| **デプロイ** | 作ったものをサーバーに配置して動かすこと |
+| **Canary リリース** | カナリア。本番の前に、限定的な環境で先に動かして様子を見ること |
+| **タグ** | `v1.2.3` のような版数の目印 |
+| **ロールバック** | 問題が起きたときに、前の状態へ戻すこと |
+| **Secrets** | パスワードや鍵などの秘密情報。専用の保管場所に置き、コードには書かない |
+| **PAT** | Personal Access Token。個人用の GitHub の鍵。**GoDD Notes では使用禁止**（GitHub App を使う） |
+| **GitHub App** | アプリ専用の GitHub アカウント。個人の権限を使わずに済むため、こちらを使う |
+
+---
+
+## 関連ドキュメント
+
+- はじめての人: [getting_started.md](./getting_started.md)
+- 困ったとき: [troubleshooting.md](./troubleshooting.md)
+- 毎日の進め方: [../006_development_workflow/daily_flow.template.md](../006_development_workflow/daily_flow.template.md)

package/templates/notes-docs/007_guides/godd_notes_features.md

@@ -0,0 +1,105 @@
+# GoDD Notes 機能一覧
+
+**GoDD Notes で何ができるかを確かめるページ**です。上から読む必要はありません。
+
+> **GoDD Notes** = 仕様書を Word や Excel のような画面で読み書きできるアプリ。**使うかどうかはプロジェクトによります。**
+
+操作の仕方は [godd_notes_usage.md](./godd_notes_usage.md) にあります。
+
+---
+
+## 一言で
+
+GitHub の `docs/` を、**Word / Excel のような画面で編集できる Web アプリ**です。編集内容は自動で PR になるため、**Git を知らなくてもドキュメント作成に参加できます。**
+
+---
+
+## 機能一覧
+
+| 機能 | 概要 |
+|---|---|
+| **Markdown 閲覧・編集** | Word ライクな WYSIWYG エディタ。GFM 対応。Mermaid のコードブロックは図として自動表示 |
+| **CSV 閲覧・編集** | スプレッドシート UI でセル単位に編集 |
+| **XLSX 閲覧・編集** | `.xlsx` / `.xls` もスプレッドシート UI で編集可能 |
+| **drawio 閲覧・編集** | 図面をブラウザ上で編集。SVG 表示に対応 |
+| **自動 PR 作成** | 編集を保存すると `docs/<ユーザー名>/<業務日>` ブランチへコミットされ、PR が自動起票される |
+| **リアルタイム共同編集** | 複数人が同じドキュメントを同時に編集（Yjs + WebSocket） |
+| **文中コメント** | テキストを選択してコメント。スレッド返信・解決に対応 |
+| **ファイル情報パネル** | 詳細・変更履歴・ブランチ情報を表示 |
+| **GitHub Issues 管理** | Issue の一覧・詳細・作成・更新・ラベル管理を Notes 上で完結 |
+| **Issue / PR ステータス同期** | Issue と PR の状態を定期取得して UI に反映 |
+| **画像アップロード** | ドラッグ&ドロップでアップロード。認証付きで表示 |
+| **状態の復元** | URL パラメータと下書き保存により、閉じても編集途中から再開できる |
+| **パネル幅の調整** | 左ペイン・エディタの幅を自由に変更可能 |
+
+---
+
+## ファイル種別ごとの対応
+
+開いたファイルの拡張子に応じて、**エディタが自動で切り替わります。**
+
+| 拡張子 | 表示 | 編集 |
+|---|---|---|
+| `.md` / `.mdx` | WYSIWYG（Mermaid は図に変換） | Word ライクなエディタ |
+| `.csv` | テーブル表示 | スプレッドシート UI |
+| `.xlsx` / `.xls` | スプレッドシート形式プレビュー | スプレッドシート UI |
+| `.drawio` / `.dio` | SVG 表示 | drawio エディタ |
+| その他 | テキスト表示 | テキストエディタ |
+
+> **書式の保持について**: `.md` / `.csv` は `{ファイル名}.styles.json` というサイドカーファイルに書式情報を保存します。ファイルツリーには表示されません。本文だけを外部で書き換えるとサイドカーは無視され、素の Markdown として表示されます。
+
+---
+
+## サインイン方式
+
+| 方式 | 対象 |
+|---|---|
+| GitHub OAuth | GitHub アカウントを持つ人 |
+| 管理者発行アカウント | GitHub アカウントを持たないクライアント / PM |
+
+初回アクセスにはプロジェクトへの招待が必要です。
+
+---
+
+## ロールと権限
+
+| ロール | できること |
+|---|---|
+| 管理者（Admin） | プロジェクト設定変更・メンバー招待・GitHub App 設定 |
+| 編集者（Editor） | ドキュメント編集・Issue 起票・コメント |
+| 閲覧者（Viewer） | 閲覧・コメントのみ |
+
+---
+
+## 動作モード
+
+| モード | 条件 | 挙動 |
+|---|---|---|
+| 通常モード | GitHub App の3変数が **すべて** 設定済み | GitHub への読み書き・PR / Issue 作成が動作 |
+| モックモード | 3変数のうち **1つでも欠けている** | GitHub API を呼ばない。ローカル開発用 |
+
+> **`godd notes compose` は3変数が揃わないとエラーで終了します**（CLI 側の入力チェック）。Notes API を直接起動した場合は、欠けているとモックモードになります。
+>
+> 3変数が揃っていても、App が**対象リポジトリに未インストール**だと GitHub API が 401 / 403 を返し、モックモードではなく**エラー**になります。設定は [bot-token-setup.md](./bot-token-setup.md) を参照してください。
+
+---
+
+## できないこと
+
+期待とのズレを避けるため、明示しておきます。
+
+| できないこと | 代わりに |
+|---|---|
+| コードの編集 | Notes は `docs/` 配下のドキュメント専用。コードは Cursor で編集する |
+| PAT（`ghp_...`）での接続 | GitHub App のみ。PAT は設定しても無視される |
+| 同時編集の完全なマージ | 同じ箇所を同時に編集した場合は**後勝ち**（履歴は GitHub のコミットから復元可能） |
+| PR のマージ | レビューとマージは GitHub 上で行う |
+
+---
+
+## 関連ドキュメント
+
+- 操作方法: [godd_notes_usage.md](./godd_notes_usage.md)
+- ローカルで動かす: [setup_local_environment.template.md](./setup_local_environment.template.md)
+- 構築全体: [setup_godd_notes.md](./setup_godd_notes.md)
+- 用語が分からない: [glossary.md](./glossary.md)

package/templates/notes-docs/007_guides/godd_notes_usage.md

@@ -1,10 +1,14 @@
-# GoDD Notes 利用ガイド
+# GoDD Notes の使い方
 
-> **本ガイドは Optional です。** GoDD Notes を導入するプロジェクトのみ参照してください。Notes を使わない場合は、GitHub 上で `docs/` を直接編集する運用となります。
+**GoDD Notes の操作方法を調べるときに開くページ**です。上から読む必要はありません。
 
-GoDD Notes は、GitHub の `docs/` を **非エンジニアでも扱える Web UI** にするドキュメント共同編集アプリです。本ドキュメントは `box-series`（= GoDD Notes 自身）の利用方法をテンプレートサンプルとして示すものです。
+> **GoDD Notes** = 仕様書を Word や Excel のような画面で読み書きするためのアプリ。
 
-> 構築方法（ローカル / クラウド）は [setup_godd_notes.md](./setup_godd_notes.md) / [setup_local_environment.template.md](./setup_local_environment.template.md) / [setup_infra.template.md](./setup_infra.template.md) を参照してください。
+> **使うかどうかはプロジェクトによります。** チームが使っていなければ、このページは読まなくて構いません。その場合、仕様書は GitHub の画面で直接開きます。
+>
+> Notes を**立ち上げる**方法は [setup_godd_notes.md](./setup_godd_notes.md) と [setup_local_environment.template.md](./setup_local_environment.template.md) にあります（導入担当の作業です）。
+>
+> **何ができるか**の一覧は [godd_notes_features.md](./godd_notes_features.md) にあります。
 
 ---
 
@@ -19,7 +23,7 @@ GoDD Notes は、GitHub の `docs/` を **非エンジニアでも扱える Web
 | **自動 PR** | ブラウザでの編集は自動コミットされ、PR として起票される |
 | **共同編集** | 複数人が同じドキュメントを同時編集（リアルタイム同期） |
 | **Issue 起票** | テスト環境への FB を Issue として書き出し |
-| **インラインコメント** | テキスト選択ベースのコメント・スレッド返信 |
+| **文中コメント** | テキスト選択ベースのコメント・スレッド返信 |
 
 > **クライアント / PM は、Notes 上での要件確認・コメント・Issue 起票だけ** で開発に貢献できます。Git の知識は不要です。
 
@@ -78,20 +82,22 @@ sequenceDiagram
     participant GH as GitHub
     U->>N: 編集（保存）
     N->>API: 差分送信
-    API->>GH: docs/auto-YYYYMMDD-HHMM ブランチ作成 + コミット
+    API->>GH: docs/<ユーザー名>/<業務日> ブランチ作成 + コミット
     API->>GH: PR を起票
     GH-->>U: PR URL を返す
 ```
 
-- 編集すると **`docs/auto-YYYYMMDD-HHMM`** ブランチが自動作成されます
-- 一定時間ごとにコミットがまとめられ、**PR として GitHub に起票**されます
+- 編集すると **`docs/<ユーザー名>/<業務日>`** ブランチが自動作成されます（例: `docs/tanaka/2026-08-20`）
+- ブランチは **ユーザーごと・業務日ごとに1本**です。同じ日の編集は同じブランチにまとまります
+- 業務日の切り替わりは既定で **Asia/Tokyo の 6:00**（それより前の編集は前日扱い）。管理者が変更できます
+- コミットがまとめられ、**PR として GitHub に起票**されます
 - レビュアーは GitHub 上で PR を確認 → **Squash merge** で本体に反映
 
 ---
 
 ## コメントと議論
 
-### インラインコメント
+### 文中コメント
 
 1. テキストを範囲選択
 2. 表示されるコメントボタンをクリック
@@ -115,7 +121,7 @@ sequenceDiagram
 
 | ロール | 権限 |
 |---|---|
-| 管理者（Admin） | プロジェクト設定変更・メンバー招待・GitHub Token 設定 |
+| 管理者（Admin） | プロジェクト設定変更・メンバー招待・GitHub App 設定 |
 | 編集者（Editor） | ドキュメント編集・Issue 起票・コメント |
 | 閲覧者（Viewer） | 閲覧・コメントのみ |
 
@@ -128,15 +134,15 @@ sequenceDiagram
 | 保存 | `Cmd + S` / `Ctrl + S` |
 | 検索 | `Cmd + K` / `Ctrl + K` |
 | ブール検索 | `Cmd + Shift + F` / `Ctrl + Shift + F` |
-| インラインコメント | テキスト選択後 `Cmd + Shift + M` / `Ctrl + Shift + M` |
+| 文中コメント | テキスト選択後 `Cmd + Shift + M` / `Ctrl + Shift + M` |
 | undo / redo | `Cmd + Z` / `Cmd + Shift + Z` |
 
 ---
 
 ## 同期と競合
 
-- 編集は **CRDT** ベースでリアルタイム同期されます
-- 短時間に複数人が同じセル / 段落を編集した場合は **後勝ち**（履歴は GitHub のコミット履歴から復元可能）
+- 編集は **仕組みで、複数人の編集がその場で反映されます
+- 短時間に複数人が同じセル / 段落を編集した場合は **後から保存したほうが残ります**（前の内容は GitHub の履歴から戻せます）
 - **GitHub 側で先行する変更がある場合**: Notes は自動で取り込み、エディタ上で警告を表示
 
 ---
@@ -146,7 +152,7 @@ sequenceDiagram
 | 症状 | 対処 |
 |---|---|
 | 編集が保存されない | ネットワーク接続を確認。右下の同期インジケータが「同期中」のままの場合はリロード |
-| PR が起票されない | プロジェクト設定の GitHub Token / リポジトリ設定を管理者に確認 |
+| PR が起票されない | GitHub App の3変数とリポジトリアクセス権の設定を管理者に確認（PAT は使用不可） |
 | 画像が表示されない | リポジトリの `docs/_assets/` が PR でマージされているか確認 |
 | 共同編集者が見えない | プロジェクトに招待されているか確認 |
 
@@ -158,17 +164,20 @@ sequenceDiagram
 
 ローカルで Notes を使うだけの場合は以下を参照する。**AWS アカウント設定は不要**（Docker のみで完結する）。
 
+- **機能一覧**: [godd_notes_features.md](./godd_notes_features.md)
 - 構築方法: [setup_godd_notes.md](./setup_godd_notes.md)
 - ローカル環境: [setup_local_environment.template.md](./setup_local_environment.template.md)
 - GoDD 全体の利用: [godd_usage.md](./godd_usage.md)
+- 用語が分からない: [glossary.md](./glossary.md)
+- 困ったとき: [troubleshooting.md](./troubleshooting.md)
 
 ### 本番 AWS デプロイ（インフラ担当）
 
 `godd notes deploy` など **本番 AWS へデプロイする場合のみ** 必要。ローカル利用だけなら読み飛ばしてよい。
 
-推奨読了順: [accounts](setup_aws_accounts.md) → [guardduty](setup_aws_guard_duty.md) → [cost alert](setup_aws_cost_alert.md)
+推奨読了順: [accounts](./infra/setup_aws_accounts.md) → [guardduty](./infra/setup_aws_guard_duty.md) → [cost alert](./infra/setup_aws_cost_alert.md)
 
-- [setup_aws_accounts.md](./setup_aws_accounts.md) — 顧客向け AWS アカウント構成（Organizations）のセットアップ
-- [setup_aws_guard_duty.md](./setup_aws_guard_duty.md) — AWS Organizations 配下アカウントの GuardDuty 設定
-- [setup_aws_cost_alert.md](./setup_aws_cost_alert.md) — AWS コスト監視（Budgets / Cost Anomaly Detection）の設定
-- インフラ: [setup_infra.template.md](./setup_infra.template.md)
+- [setup_aws_accounts.md](./infra/setup_aws_accounts.md) — 顧客向け AWS アカウント構成（Organizations）のセットアップ
+- [setup_aws_guard_duty.md](./infra/setup_aws_guard_duty.md) — AWS Organizations 配下アカウントの GuardDuty 設定
+- [setup_aws_cost_alert.md](./infra/setup_aws_cost_alert.md) — AWS コスト監視（Budgets / Cost Anomaly Detection）の設定
+- インフラ: [setup_infra.template.md](./infra/setup_infra.template.md)