docs: CLI リファレンスをグループ別に分割し repo 連携ガイドを追加

CHANGELOG.md

@@ -20,8 +20,29 @@
   DAYS 日（既定 7、`DEVBASE_IMAGE_MAX_AGE_DAYS` で上書き可）以上のときのみ no-cache で
   再ビルドし、未満なら再ビルドしません（既存イメージを使用）。親イメージ（`FROM devbase-*`）の
   作成日は独立して判定します。`devbase build` の `--no-cache` も明示フラグとして整理しました。
+- **外部リポジトリ連携プロジェクト向けドキュメント (`docs/plugin-dev/repo-backed-projects.md`)**
+  を追加しました。アプリ本体のリポジトリを共有 work ボリュームへ取り込み、複数コンテナで動かす
+  プロジェクトのための `pre-up` populate パターン（初回のみ populate し、2 回目以降はコンテナ側の
+  ソース・環境ファイルを上書きしない冪等スキップ）と、その設計意図・更新運用・チェックリストを
+  解説しています。あわせて、本パターンが `CONTAINER_SCALE=1` 前提である理由（`pre-up` は
+  インデックスなしで 1 回しか実行されず、scale 生成で `/work` が差し替わるのは dev サービス
+  のみ）と、同一リポジトリの複数インスタンス分離が現行実装では未サポートである点、
+  work ボリュームが全プロジェクト共有のグローバル external ボリュームであることを踏まえた
+  安全な再 populate 手順（ボリュームごとではなく `/work/<GIT_REPO>` サブディレクトリを削除）
+  も明記しています。
 
 ### Changed
+- **CLI リファレンス (`docs/user/cli-reference.md`) をコマンドグループ別ディレクトリ
+  (`docs/user/cli-reference/`) に分割**しました。目次 (`README.md`) とトップレベル / project /
+  env / plugin / snapshot の各ファイルに再編し、1 ファイルあたりの分量を抑えて目的のコマンドへ
+  辿りやすくしました。ルート `README.md`（3 箇所）を含む他ドキュメントからの参照リンクも
+  新パス (`docs/user/cli-reference/README.md`) へ更新しています。
+- **コンテナ操作ガイドの work ボリューム記述を実装に合わせて訂正**しました。
+  `docs/user/container-operations.md` のボリューム表が `{project}_work_{index}` /
+  「各コンテナ専用」となっていましたが、実際は project 接頭辞の付かない external ボリューム
+  `devbase_work_{index}` で、同じ index を使う限り**別プロジェクトからも同じ実体**を参照します。
+  表記を訂正し、`docker volume rm` が他プロジェクトの作業ファイルを巻き添えにする旨の注意も
+  追記しました。
 - **`build` / `rebuild` / `up` の再ビルド仕様を統一**しました (i07)。キャッシュの
   扱いを 3 モード（既定=キャッシュビルド / `--no-cache`=無条件 no-cache / `--expires=N`=
   期限切れ時のみ no-cache・期限内は再ビルドしない）に整理し、`devbase rebuild` を
@@ -81,7 +102,7 @@
   - `devbase project list` で `$DEVBASE_ROOT/projects/` 配下を `NAME` / `PLUGIN` / `STATUS` の一覧表示します。`PLUGIN` 列はシンボリックリンク先から解決するため、PLAN04 の同名衝突 suffix（例 `carmo.takemi`）が付いていても正しいプラグイン名を表示します。**TTY ではデフォルトで対話選択**になり、一覧から番号で選んだプロジェクトを `project up` で起動します。`--no-interactive`（`--plain` / `-P`）で一覧表示のみに切り替えられ、パイプ・リダイレクト・CI などの非 TTY 環境では自動的に一覧表示へフォールバックします（`--interactive` / `-i` は後方互換として引き続き受け付けます）。
   - トップレベルシノニム `devbase up/down/ps/scale [name]` / `devbase build [image]` / `devbase login [index]` / `devbase list` を整備しました（`logs` はシノニムを持たず `devbase project logs` のみ）。
   - bash / zsh のシェル補完に `project` グループとプロジェクト名補完（`$DEVBASE_ROOT/projects/` 配下を列挙）を追加しました。
-  - 利用者向けドキュメント [`docs/user/cli-reference.md`](docs/user/cli-reference.md) / [`docs/user/container-operations.md`](docs/user/container-operations.md) を `project` 体系に更新しました。
+  - 利用者向けドキュメント `docs/user/cli-reference.md`（現 [`docs/user/cli-reference/`](docs/user/cli-reference/README.md)） / [`docs/user/container-operations.md`](docs/user/container-operations.md) を `project` 体系に更新しました。
 - `devbase env export` / `devbase env import` で **S3 URI (`s3://bucket/key`) を入出力先として指定**できるようになりました (PLAN03-1 PR3)。
   - 既定でオブジェクト単位の SSE (`aws:kms` または `AES256`) を強制し、export 時はバケット側のデフォルト暗号化も `GetBucketEncryption` で事前確認します。
   - 暗号化が未設定のバケットへ export する場合は `--unsafe-allow-unencrypted-bucket` の明示が必要です (オブジェクト単位の SSE はこのフラグに関係なく常に付与されます)。

README.md

@@ -119,11 +119,11 @@ devbaseのコマンドは4つのグループにまとめられています。
 
 > **`container`（略記 `ct`）グループは非推奨です。** `devbase project <sub>` のエイリアスとして当面動作しますが、非推奨警告を表示します。新しいコマンドは `project` を使用してください。
 
-- **ショートカット**: `up [name]`, `down [name]`, `login [index]`, `build [image]`, `ps [name]`, `scale [name] <num>`, `rebuild [name]`, `list` はトップレベルから直接使用可能（`project` グループへ自動転送。`logs` はシノニムを持ちません）。なお `build` のみ挙動が一部異なります（詳細は [CLI リファレンス](docs/user/cli-reference.md#ショートカットコマンド)）
+- **ショートカット**: `up [name]`, `down [name]`, `login [index]`, `build [image]`, `ps [name]`, `scale [name] <num>`, `rebuild [name]`, `list` はトップレベルから直接使用可能（`project` グループへ自動転送。`logs` はシノニムを持ちません）。なお `build` のみ挙動が一部異なります（詳細は [CLI リファレンス](docs/user/cli-reference/README.md#ショートカットコマンド)）
 - **プレフィックス略記**: `devbase p l` → `devbase plugin list`
 - **トップレベルコマンド**: `init`, `status`
 
-全コマンドの構文・オプション・使用例は [CLIリファレンス](docs/user/cli-reference.md) を参照してください。
+全コマンドの構文・オプション・使用例は [CLIリファレンス](docs/user/cli-reference/README.md) を参照してください。
 
 ## 前提条件
 
@@ -142,7 +142,7 @@ devbaseのコマンドは4つのグループにまとめられています。
 | ドキュメント | 内容 |
 |-------------|------|
 | [はじめに](docs/user/getting-started.md) | 前提条件、初回セットアップ、日常ワークフロー |
-| [CLIリファレンス](docs/user/cli-reference.md) | 全コマンドの構文・オプション・使用例 |
+| [CLIリファレンス](docs/user/cli-reference/README.md) | 全コマンドの構文・オプション・使用例（コマンドグループ別） |
 | [プラグインレジストリ](docs/user/plugin-registries.md) | 公開・社内レジストリの一覧と追加方法 |
 | [環境変数ガイド](docs/user/environment-variables.md) | 3レベル構造、コレクター、ソース同期 |
 | [環境変数の export/import ガイド](docs/user/env-export-import.md) | バンドル形式・age 暗号化・S3 連携・merge/replace の運用 |

docs/README.md

@@ -43,7 +43,7 @@ graph TD
 | ドキュメント | 内容 |
 |-------------|------|
 | [はじめに](user/getting-started.md) | 前提条件、初回セットアップ、日常ワークフロー |
-| [CLI リファレンス](user/cli-reference.md) | 全コマンドの構文・オプション・使用例 |
+| [CLI リファレンス](user/cli-reference/README.md) | 全コマンドの構文・オプション・使用例 |
 | [プラグインレジストリ](user/plugin-registries.md) | 公開・社内レジストリの一覧と追加方法 |
 | [環境変数ガイド](user/environment-variables.md) | 3レベル構造、コレクター、ソース同期 |
 | [コンテナ操作ガイド](user/container-operations.md) | ライフサイクル、並行開発、ボリューム構造 |
@@ -73,6 +73,7 @@ graph LR
 | [プラグイン開発クイックスタート](plugin-dev/quickstart.md) | 最小構成プラグインの作成手順 |
 | [plugin.yml リファレンス](plugin-dev/plugin-yml-reference.md) | プラグイン定義ファイルの全フィールド |
 | [compose.yml ガイドライン](plugin-dev/compose-yml-guidelines.md) | Docker Compose 設定のベストプラクティス |
+| [repo 連携プロジェクトと pre-up populate](plugin-dev/repo-backed-projects.md) | 外部リポジトリを共有 work ボリュームへ populate する `pre-up` パターンと冪等スキップ |
 
 ### devbase 開発者（devbase 本体を改善したい方）
 
@@ -91,7 +92,13 @@ docs/
 ├── README.md                          ← このファイル（ドキュメント索引）
 ├── user/                              ← 利用者向け
 │   ├── getting-started.md             ← はじめに
-│   ├── cli-reference.md               ← CLI リファレンス
+│   ├── cli-reference/                 ← CLI リファレンス（コマンドグループ別）
+│   │   ├── README.md                  ← 目次・コマンド体系
+│   │   ├── 01-toplevel.md             ← init / status / rc
+│   │   ├── 02-project.md              ← project グループ
+│   │   ├── 03-env.md                  ← env グループ
+│   │   ├── 04-plugin.md               ← plugin グループ
+│   │   └── 05-snapshot.md             ← snapshot グループ
 │   ├── plugin-registries.md           ← プラグインレジストリ
 │   ├── environment-variables.md       ← 環境変数ガイド
 │   ├── container-operations.md        ← コンテナ操作ガイド
@@ -100,7 +107,8 @@ docs/
 ├── plugin-dev/                        ← プラグイン開発者向け
 │   ├── quickstart.md                  ← クイックスタート
 │   ├── plugin-yml-reference.md        ← plugin.yml リファレンス
-│   └── compose-yml-guidelines.md      ← compose.yml ガイドライン
+│   ├── compose-yml-guidelines.md      ← compose.yml ガイドライン
+│   └── repo-backed-projects.md        ← repo 連携 / pre-up populate パターン
 └── developer/                         ← devbase 開発者向け
     ├── architecture.md                ← アーキテクチャ
     ├── contributing.md                ← コントリビューション
@@ -114,7 +122,7 @@ docs/
 | やりたいこと | 参照先 |
 |-------------|--------|
 | devbase を初めてインストールする | [はじめに](user/getting-started.md#セットアップ手順) |
-| コマンドの使い方を調べる | [CLI リファレンス](user/cli-reference.md) |
+| コマンドの使い方を調べる | [CLI リファレンス](user/cli-reference/README.md) |
 | 環境変数を設定する | [環境変数ガイド](user/environment-variables.md#環境変数の操作) |
 | 複数コンテナで並行開発する | [コンテナ操作ガイド](user/container-operations.md#並行開発) |
 | データをバックアップ・復元する | [スナップショットガイド](user/snapshot-guide.md) |

docs/plugin-dev/quickstart.md

@@ -148,6 +148,8 @@ fi
 
 > **Note:** どちらのフックも `bash` で実行されます。`chmod +x` で実行可能ビットを立てておいてください。`pre-up` が非ゼロ終了すると `devbase up` は中断します。`deploy` は各インスタンスに対して `DEVBASE_INSTANCE_INDEX` を環境変数として渡しますが、失敗してもデプロイは続行されます。
 
+> **応用:** 外部リポジトリを共有 work ボリュームへ取り込み、app / nginx / db など複数コンテナで動かすプロジェクトでは、`pre-up` で clone/pull と work ボリュームへの populate を行い、2 回目以降はコンテナ側を上書きしないよう冪等にスキップするのが定石です。詳細は [repo 連携プロジェクトと pre-up populate パターン](repo-backed-projects.md) を参照してください。
+
 ---
 
 ## 3. ローカルでの開発・テスト