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

[takemi-ohama]

概要

docs/ を執筆ルール（1 ファイルあたりの分量を抑える・図はインライン mermaid）に沿って整理し、外部リポジトリ連携プロジェクト向けの新ガイドを追加しました。ドキュメントのみの変更で、CLI の挙動には影響しません。

変更点

• CLI リファレンスの分割: 740 行の docs/user/cli-reference.md を docs/user/cli-reference/ 配下に再編
  • README.md（目次・コマンド体系）+ 01-toplevel.md / 02-project.md / 03-env.md / 04-plugin.md / 05-snapshot.md
  • 各ファイル 300 行以内。目的のコマンドへ辿りやすくなる
• repo 連携ガイドの新規追加: docs/plugin-dev/repo-backed-projects.md
  • アプリ本体のリポジトリを共有 work ボリュームへ取り込み、複数コンテナで動かすプロジェクト向けの pre-up populate パターンを解説
  • 初回のみ populate し、2 回目以降はコンテナ側のソース・環境ファイルを上書きしない冪等スキップの設計意図・更新運用・チェックリストを記載
• 参照リンクの更新: 分割に伴い docs/README.md（索引・構成ツリー）、container-operations.md、env-export-import.md、getting-started.md、plugin-registries.md、quickstart.md の参照リンクを新パスへ張り替え
• CHANGELOG: 上記 2 点を Unreleased に追記

動作確認

• 旧 cli-reference.md への残存参照が無いことを確認（grep -rn "cli-reference.md" docs/ → 0 件）
• 分割ファイル内の相対リンク・被リンクのアンカーが実在先へ解決することを確認
• docs/ 配下の全 Markdown が 500 行以下であることを確認
• GitHub 上でのレンダリング（mermaid 図・リンク遷移）を確認

補足

carmo-system-console の pre-up 本体（挙動変更）は別リポジトリ（volareinc/devbase-ext）にあり、この PR には含まれません。本 PR は devbase 本体リポジトリのドキュメントのみです。pre-up の実コード変更は devbase-ext 側で別途 PR が必要です。

[takemi-ohama]

🤖 cross-review | round 1 | codex | REQUEST_CHANGES

CLI リファレンス分割後の参照更新範囲と、repo-backed 構成のスケール時ボリューム前提を現行実装に合わせて修正してください。

[takemi-ohama]

🤖 cross-review | round 1 | gemini | REQUEST_CHANGES

リポジトリルートの README.md に旧 docs/user/cli-reference.md へのリンクが残っています。変更対象外となっていますが合わせて更新をお願いします。

[takemi-ohama]

🔧 cross-review round 1 — fix 対応完了

修正コミット: 8bad3f3

対応サマリ

区分	件数
対応済み	4 (major 3 / minor 1)
deferred	0
rejected	0

重要度は AI のラベルを鵜呑みにせず、lib/devbase/commands/container.py / lib/devbase/volume/compose.py / lib/devbase/volume/manager.py / lib/devbase/utils/config.py を読んで再判定しました。結果として 4 件すべて妥当と確認しています。

個別対応

[major] ルート README.md に旧 docs/user/cli-reference.md リンクが残存（codex #discussion_r3762475136 / gemini #discussion_r3762481254 — 重複指摘）

• 122 / 126 / 145 行の 3 箇所を docs/user/cli-reference/README.md へ更新（122 行のアンカー #ショートカットコマンド は分割後の目次ファイル側にあることを確認済み）。
• 追加で、リポジトリ全体の Markdown 相対リンクを検証するスクリプトを実行し、旧リリース項に残っていた CHANGELOG.md のリンク切れも解消。現在 *.md / docs/**/*.md の相対リンクはすべて解決します。
• CHANGELOG の記述も「ルート README.md（3 箇所）を含む」と明示。

[major] repo 連携ガイドの scale 前提が実装と不一致（codex #discussion_r3762475140）

実装確認の結果、指摘は正確でした。

• _run_pre_up_hook() は env=os.environ.copy() で pre-up を インデックスなしに 1 回だけ 実行。DEVBASE_INSTANCE_INDEX を注入するのは _run_deploy_script_for_instances() のみ。
• _build_dev_instance() → _replace_volumes_for_instance() は dev サービスの /work だけ を devbase_work_<index> へ差し替え、非 dev サービスは共有 work ボリュームを参照したまま。

対応として scale=1 制約を明記する方針を採用しました。

• 2 章末尾に「スケール前提: CONTAINER_SCALE=1」節を新設（既定が 2 である点、崩れる前提 2 点、複数インスタンス時の代替手段＝プロジェクト複製 + DEVBASE_WORK_VOLUME を記載）。
• 6 章 DEVBASE_INSTANCE_INDEX 行を「deploy フックにのみ渡る」へ訂正。
• 6 章 DEVBASE_WORK_VOLUME 行に「既定名以外を指定すると dev だけ別ボリュームを見る」注意を追記。
• 7 章チェックリストに CONTAINER_SCALE=1 項目を追加。
• 副次的に、5 章の再 populate 手順 docker volume rm <project>_devbase_work_1 を、external volume の実名 devbase_work_1（project 接頭辞なし）へ訂正（WORK_VOLUME_PREFIX = "devbase_work_"）。

[minor] projects/carmo-system-console が本リポジトリに存在しない（codex #discussion_r3762475144）

projects/* は .gitignore 対象のため妥当な指摘。公開 URL を提示できない社内 private レジストリ配布のプラグインであるため、「外部リポジトリにある旨を明記」方針で冒頭と参考節の 2 箇所を修正しました。

CI

push 前スナップショット時点で FAILURE なし（Python syntax check 3.10/3.11/3.12・Ruff lint・ShellCheck すべて SUCCESS）。docs 変更のみのため実行系への影響はありません。再レビューをお願いします。

[takemi-ohama]

🤖 cross-review | round 2 | codex | REQUEST_CHANGES

共有 work ボリュームの分離手順と削除手順を、現行の scale 生成・グローバル volume 命名に対して安全に成立する内容へ修正してください。

[takemi-ohama]

🤖 cross-review | round 2 | gemini | APPROVE

ドキュメントの分割と新規追加の内容に問題は見当たりませんでした。既存ドキュメント・関連ファイルからの参照リンクも漏れなく更新されており、各ファイルの内容や見出しレベルの階層も適切です。

[takemi-ohama]

🔧 cross-review round 2 — fix 対応完了

修正コミット: 11f9df0

対応サマリ

区分	件数
対応済み	2 (critical 0 / major 2 / minor 0 / nit 0)
deferred	0
rejected	0

round 1 で対応済みの 3 スレッドは Resolve 済みのため対象外とし、未 Resolve の open thread 2 件（いずれも codex round 2）のみを扱いました。gemini は round 2 で APPROVE です。

重要度は AI のラベルを鵜呑みにせず、lib/devbase/commands/container.py / lib/devbase/volume/compose.py / lib/devbase/volume/manager.py を読んで再判定しました。2 件とも major で妥当と確認しています（片方はドキュメント通りに操作すると他プロジェクトのデータを破壊しうる手順のため、実害の観点でも major 相当）。

個別対応

[major] 2 章の並行化手順が現行実装で成立しない（#discussion_r3762537770）

実装確認の結果、指摘は正確でした。

• cmd_up() は CONTAINER_SCALE の値によらず常に generate_scaled_compose(scale) を実行（container.py:558）。scale=1 でも scale 生成は走ります。
• _build_dev_instance() → _replace_volumes_for_instance() が dev の /work を devbase_work_<index> へ無条件に差し替え、DEVBASE_WORK_VOLUME は参照しません。さらに "Add missing mounts" により compose.yml に /work を書いていなくてもマウントが追加されます（compose.py:95-100）。
• work ボリュームは external: True かつ WORK_VOLUME_PREFIX = "devbase_work_" で COMPOSE_PROJECT_NAME 非依存。ensure_volumes() の project_name も未使用（All projects share the same volumes ... based on container index.）。

よって「複製 + DEVBASE_WORK_VOLUME」は、名前を分ければ app/nginx と dev が分裂し、分けなければ複製元と同じボリュームを共有する、どちらでも成立しない手順でした。未サポートを明記する方針に変更し、2 案がそれぞれなぜ成立しないかを示したうえで、分離が必要なら Docker ホスト（docker context）を分けること、別リポジトリ同士は /work/<GIT_REPO> で分かれるため共存可能であることを追記しました。6 章の DEVBASE_WORK_VOLUME 行も「非 dev サービスにのみ効く」へ訂正。

[major] 再 populate 手順の docker volume rm が他プロジェクトを巻き添えにする（#discussion_r3762537774）

同じく実装で裏付けが取れました。プロジェクトの分離単位はボリュームではなく /work/<GIT_REPO> サブディレクトリなので、手順を組み替えています。

• 5 章冒頭に Warning（グローバル external ボリューム / 全プロジェクト共有）を追加。
• 推奨手順を サブディレクトリ削除 へ変更（docker run --rm -v devbase_work_1:/work alpine ls -la /work で同居確認 → rm -rf /work/<GIT_REPO> → devbase up）。populate 済み判定が .git の有無なので再 populate が走ります。
• ボリュームごと削除する手順は副次的選択肢へ降格し、docker ps -a --filter volume=devbase_work_1 での事前確認を前置き。

あわせて修正した整合性の問題（指摘外）

この PR で参照リンクを更新している docs/user/container-operations.md のボリューム表が {project}_work_{index} /「各コンテナ専用」となっており、実装（devbase_work_{index} / プロジェクト間共有）とも上記の新しい警告とも矛盾していたため訂正し、削除時の注意を追記しました。CHANGELOG にも反映済みです。

検証

• リポジトリ全 53 件の Markdown について相対リンク + アンカーを検証し、リンク切れなしを確認。
• CI: push 前スナップショット時点で FAILURE なし（Python syntax check 3.10/3.11/3.12・Ruff lint・ShellCheck すべて SUCCESS）。docs のみの変更のため実行系への影響はありません。

再レビューをお願いします。

[takemi-ohama]

🤖 cross-review | round 3 | codex | APPROVE

新たに修正が必要な事項はありません。

[takemi-ohama]

🤖 cross-review | round 3 | gemini | APPROVE

ドキュメントの分割、参照リンクの更新、および新規ドキュメント（repo 連携プロジェクト）の追加について、矛盾やリンク切れなどの問題は見当たりませんでした。