docs: ホームボリュームのマウント先を /persistent/ai に修正し AI 設定永続化を明文化 (#78)

ドキュメントが実装と乖離していた点を是正する。

## 修正内容

1. マウント先の誤り訂正 (/home/ubuntu → /persistent/ai)
   - devbase_home_ubuntu ボリュームは /persistent/ai にマウントされる
     (lib/devbase/volume/compose.py:13-14 で /home/ubuntu は _DEPRECATED_TARGET
     として除去、/persistent/ai にマップ)。
   - /home/ubuntu 直下はコンテナ層(揮発)で、永続化されるのは entrypoint が
     /persistent/ai 配下へ symlink する設定のみ。「シェル履歴等も永続」という
     記述は誤りだったため訂正。
   - 対象: container-operations.md / compose-yml-guidelines.md /
     quickstart.md / snapshot-guide.md / troubleshooting.md / README.md

2. AI 設定の永続化を明文化 (container-operations.md に新セクション)
   - symlink 機構と対象一覧 (.claude / .codex / .gemini / .serena / .ssh /
     .kiro / share) を記載。PR #77 で追加した .kiro / share を反映。
   - share が全コンテナ共有のファイル置き場であること、DEVBASE_WORKSPACE との
     関連を追記。

3. rebuild / --no-cache の説明訂正 (README.md)
   - 「devbase rebuild で docker compose build --no-cache 相当」は誤り。
     rebuild は build --expires=7 で齢ゲート付き。無条件 no-cache は
     devbase build --no-cache であることを明記。

4. entrypoint/Dockerfile 変更時の再ビルド注記 (cli-reference.md)
   - devbase up はイメージ齢 7 日未満だと再ビルドをスキップするため、
     entrypoint 変更は build --no-cache が必要な旨を追記。

Co-authored-by: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Author: takemi-ohama

README.md

@@ -13,10 +13,10 @@ devbaseは、Docker Composeを使った再現性の高い開発環境を提供
 - **豊富なツールセット**: Docker CLI、AWS CLI、gcloud SDK、Terraform、Node.js、AI CLIツールがプリインストール
 - **複数コンテナの並行開発**: `devbase project scale`で既存コンテナを再起動せずにスケール可能
 - **データ永続化**: 名前付きボリュームでコンテナ再起動後もデータを保持
-- **スナップショット管理**: `/home/ubuntu` 共通ボリュームの増分バックアップ・復元・世代管理
+- **スナップショット管理**: 共通ボリューム `devbase_home_ubuntu`（コンテナ内 `/persistent/ai`。AI 設定・共有ファイル）の増分バックアップ・復元・世代管理
 - **環境変数の自動収集**: `devbase env init`でAWS/Git/GCP認証情報を対話的に設定
 - **階層メニュー TUI**: `devbase list` のプロジェクト一覧（矢印キー移動・名前絞り込み対応）から起動・操作（up / down / login / ps / logs / scale / build / rebuild）を選択。画面最下部の常設メニュー（環境変数 / プラグイン / スナップショット / ステータス）へは ←→ キーで移動できます
-- **キャッシュ無効リビルド**: `devbase rebuild [name]` で `docker compose build --no-cache` 相当のイメージ再ビルドができます
+- **イメージ再ビルド**: `devbase build [name] --no-cache` でキャッシュ無効の完全再ビルド。`devbase rebuild [name]`（= `build --expires=7`）はイメージが既定 7 日より古いときのみ再ビルドします
 
 ## クイックスタート
 

docs/plugin-dev/compose-yml-guidelines.md

@@ -103,15 +103,19 @@ devbaseでは2種類のボリュームパターンを使い分けます。
 
 ```yaml
 volumes:
-  - devbase_home_ubuntu:/home/ubuntu                              # 全コンテナ共有
+  - devbase_home_ubuntu:/persistent/ai                            # 全コンテナ共有（AI設定）
   - ${COMPOSE_PROJECT_NAME}_work_${CONTAINER_INDEX:-1}:/work      # コンテナ専用
 ```
 
 | ボリューム | マウント先 | 共有範囲 | 用途 |
 |-----------|-----------|----------|------|
-| `devbase_home_ubuntu` | `/home/ubuntu` | 全コンテナ | シェル設定、SSH鍵、Git設定 |
+| `devbase_home_ubuntu` | `/persistent/ai` | 全コンテナ | AI CLI 設定（`.claude` 等）、SSH鍵、共有ファイル置き場（`share`）。`~/.claude` 等は entrypoint が symlink |
 | `${COMPOSE_PROJECT_NAME}_work_${CONTAINER_INDEX:-1}` | `/work` | コンテナ専用 | ソースコード、ビルド成果物 |
 
+> **Note:** マウント先は **`/persistent/ai`** です（旧 `/home/ubuntu` 直接マウントは廃止）。
+> これらの標準ボリュームは compose.yml に明記しなくても devbase がスケール用 compose 生成時に
+> 自動注入します。明記する場合も必ず `/persistent/ai` を使ってください。
+
 ### 3.2 Docker Socketのマウント
 
 コンテナ内からDockerコマンドを使用する場合は、Docker Socketをマウントし、`group_add` でDockerグループに追加します。

docs/plugin-dev/quickstart.md

@@ -252,12 +252,12 @@ flowchart LR
 
 ### 5.3 ボリューム設計
 
-| 用途 | ボリューム名パターン | 共有範囲 |
-|------|---------------------|----------|
-| ホームディレクトリ | `devbase_home_ubuntu` | 全コンテナ共有 |
-| 作業ディレクトリ | `${COMPOSE_PROJECT_NAME}_work_${CONTAINER_INDEX:-1}` | コンテナ専用 |
+| 用途 | ボリューム名パターン | マウント先 | 共有範囲 |
+|------|---------------------|-----------|----------|
+| AI 設定・共有ファイル | `devbase_home_ubuntu` | `/persistent/ai` | 全コンテナ共有 |
+| 作業ディレクトリ | `${COMPOSE_PROJECT_NAME}_work_${CONTAINER_INDEX:-1}` | `/work` | コンテナ専用 |
 
-- ホームディレクトリボリュームはシェル設定やSSH鍵など、コンテナ横断で共有したい設定の永続化に使用
+- `devbase_home_ubuntu`（`/persistent/ai`）は AI CLI 設定・SSH 鍵・共有ファイルなど、コンテナ横断で共有したい設定の永続化に使用（`~/.claude` 等は entrypoint が symlink。旧 `/home/ubuntu` 直接マウントは廃止）
 - 作業ディレクトリボリュームはプロジェクトごと・コンテナインデックスごとに独立
 
 ### 5.4 コンテナイメージの選択

docs/user/cli-reference.md

@@ -180,6 +180,12 @@ devbase up [name]
     （前回 pull 日時は `${DEVBASE_ROOT}/.cache/pulls/<image>` の touch-file mtime で判定）
   - 閾値は `DEVBASE_IMAGE_MAX_AGE_DAYS` 環境変数で上書き可能（既定 7、不正値は警告して既定値）
 
+> **Note (entrypoint / Dockerfile を変更したとき):** `containers/` 配下の `entrypoint.sh` や
+> Dockerfile はビルド時にイメージへ焼き込まれます。これらを変更しても、上記のとおり
+> `devbase up` はイメージが 7 日より新しいと再ビルドをスキップするため、変更が反映されない
+> ことがあります。確実に反映するには **`devbase build [name] --no-cache`** で再ビルドしてから
+> `devbase up` してください（`--no-cache` は `build` のオプションで、`rebuild` にはありません）。
+
 ### `devbase project down`
 
 コンテナを停止・削除します。

docs/user/container-operations.md

@@ -117,7 +117,7 @@ graph LR
     subgraph devbase
         C[コンテナ 1<br/>/work 専用]
         D[コンテナ 2<br/>/work 専用]
-        E[共有ホーム<br/>/home/ubuntu]
+        E[共有AI設定<br/>/persistent/ai]
     end
     A --> C
     B --> D
@@ -126,7 +126,7 @@ graph LR
 ```
 
 - 各コンテナは独立した `/work` ボリュームを持つ
-- `/home/ubuntu` は全コンテナで共有される
+- `/persistent/ai`（AI 設定・共有ファイル）は全コンテナで共有される（`/home/ubuntu` 直下のうち永続化されるのは symlink 対象のみ。下記「AI 設定の永続化」参照）
 - 異なるブランチでの並行作業に便利
 
 ## ボリューム構造
@@ -135,9 +135,11 @@ devbase のコンテナは 2 種類のボリュームを使用します。
 
 | ボリューム名 | マウント先 | 共有範囲 | 用途 |
 |-------------|-----------|---------|------|
-| `devbase_home_ubuntu` | `/home/ubuntu` | 全コンテナで共有 | ユーザー設定、SSH 鍵、シェル履歴等 |
+| `devbase_home_ubuntu` | `/persistent/ai` | 全コンテナで共有 | AI CLI 設定（`.claude` / `.codex` / `.gemini` 等）、SSH 鍵、共有ファイル置き場（`share`）。詳細は「AI 設定の永続化」参照 |
 | `{project}_work_{index}` | `/work` | 各コンテナ専用 | プロジェクトのソースコード、作業ファイル |
 
+> **Note:** `devbase_home_ubuntu` は **`/persistent/ai`** にマウントされます（`/home/ubuntu` への直接マウントは廃止）。`/home/ubuntu` 直下はコンテナ層（揮発）で、永続化されるのは entrypoint が `/persistent/ai` 配下へ symlink する設定ファイルのみです。シェル履歴など symlink 対象外のファイルは再生成で失われます。
+
 ### ボリュームの永続性
 
 - ボリュームは `devbase down` でもコンテナが削除されても保持されます
@@ -154,7 +156,32 @@ docker volume ls | grep devbase
 docker volume inspect devbase_home_ubuntu
 ```
 
-> **Warning:** `devbase_home_ubuntu` ボリュームは全プロジェクトで共有されます。ここにプロジェクト固有のファイルを置くと、他のプロジェクトにも影響します。プロジェクト固有のファイルは `/work` に配置してください。
+> **Warning:** `devbase_home_ubuntu` ボリューム（`/persistent/ai`、および symlink 経由でアクセスする `~/.claude` / `~/share` 等）は全プロジェクトで共有されます。ここにプロジェクト固有のファイルを置くと、他のプロジェクトにも影響します。プロジェクト固有のファイルは `/work` に配置してください。
+
+## AI 設定の永続化
+
+AI CLI ツールの設定や認証情報は、コンテナを再生成しても保持されるよう
+`devbase_home_ubuntu` ボリューム（`/persistent/ai`）に永続化されます。
+
+仕組みは **symlink** です。コンテナ起動時、entrypoint（`containers/base/entrypoint.sh`）が
+以下の各エントリについて `/home/ubuntu/<name> -> /persistent/ai/<name>` の symlink を作成します。
+
+| エントリ | 内容 |
+|---------|------|
+| `.claude.json` / `.claude` | Claude Code の設定・認証 |
+| `.codex` | Codex CLI の設定 |
+| `.gemini` | Gemini CLI の設定 |
+| `.serena` | Serena MCP の設定 |
+| `.kiro` | Kiro CLI の設定 |
+| `.ssh` | SSH 鍵 |
+| `share` | 全コンテナ共有のファイル置き場（任意用途） |
+
+- `/persistent/ai` は全コンテナ共通の `devbase_home_ubuntu` ボリュームなので、**どのコンテナからも同じ実体**を参照します（例: `~/share` は全コンテナで共有）。
+- symlink **対象外**のホーム配下ファイル（シェル履歴など）はコンテナ層に置かれ、再生成で失われます。永続化したいものは `/persistent/ai` 配下（= 上記 symlink 先）か `/work` に置いてください。
+- `share` 配下に置いた VS Code ワークスペースファイルは `DEVBASE_WORKSPACE` で開けます（[環境変数](environment-variables.md) 参照）。
+
+> **Note:** symlink 対象は entrypoint にビルド時 `COPY` で焼き込まれます。エントリを増減した場合は
+> イメージの再ビルドが必要です（`devbase up` 単体では反映されない場合があります。[CLI リファレンス](cli-reference.md) の `devbase project up` の注記参照）。
 
 ## コンテナイメージ階層
 
@@ -265,7 +292,7 @@ devbase status
 
 ## ベストプラクティス
 
-1. **プロジェクト固有のファイルは `/work` に配置する** -- `/home/ubuntu` は全コンテナで共有されるため
+1. **プロジェクト固有のファイルは `/work` に配置する** -- `/persistent/ai`（`~/.claude` 等の symlink 先・`~/share`）は全コンテナで共有されるため
 2. **`CONTAINER_SCALE` は必要最小限に設定する** -- リソース消費を抑制
 3. **作業終了後は `devbase down` を実行する** -- 自動ローテーションでディスク容量を管理
 4. **`devbase ps` で状態を確認してからログインする** -- 異常終了したコンテナへのログイン試行を避ける

docs/user/environment-variables.md

@@ -148,7 +148,7 @@ devbase はホストマシンの認証情報を自動収集し、コンテナ内
 |------|------|
 | `DEVBASE_OPEN_EDITOR` | 真（`1`/`true`/`yes`/`on`）で `up` 後にエディタを開く（既定: OFF） |
 | `DEVBASE_EDITOR` | 起動コマンド（既定: `code`）。`cursor` / `code-insiders` 等も可 |
-| `DEVBASE_WORKSPACE` | 開く `*.code-workspace` ファイルの**コンテナ内絶対パス**（例 `/home/ubuntu/share/work/uttarov2-doc.workspace`）。指定時はフォルダではなくワークスペースを開く。未設定なら従来どおり `/work/$GIT_REPO` フォルダ。共有マウント `/home/ubuntu/share` 配下に置けば全コンテナで共用可 |
+| `DEVBASE_WORKSPACE` | 開く `*.code-workspace` ファイルの**コンテナ内絶対パス**（例 `/home/ubuntu/share/work/uttarov2-doc.workspace`）。指定時はフォルダではなくワークスペースを開く。未設定なら従来どおり `/work/$GIT_REPO` フォルダ。`~/share`（= 全コンテナ共有ボリューム `/persistent/ai/share` への symlink）配下に置けば全コンテナで共用可 |
 | `DEVBASE_OPEN_INDEX` | scale 時に開く dev インスタンス番号（既定: `1`） |
 | `DEVBASE_EDITOR_SSH_HOST` | Remote-SSH 跨ホスト構成での ssh-remote ホスト名（例 `mac2`）。**通常は `~/.vscode-server` から自動検出**され不要。検出が外れる場合のみ明示。下記「跨ホスト」参照 |
 | `DEVBASE_EDITOR_DOCKER_CONTEXT` | 跨ホスト時に ssh 先で使う docker context（既定: ホストの `docker context show`） |

docs/user/snapshot-guide.md

@@ -1,6 +1,6 @@
 # スナップショットガイド
 
-devbase のスナップショット機能は、コンテナの `/home/ubuntu` 共通ボリューム (`devbase_home_ubuntu`) を増分バックアップし、世代管理と復元を提供します。`/work` 配下のプロジェクト作業ファイルはバックアップ対象外なので、重要なファイルは Git に push するか別途バックアップを取ってください。
+devbase のスナップショット機能は、共通ボリューム `devbase_home_ubuntu`（コンテナ内では `/persistent/ai` にマウント。AI CLI 設定や共有ファイルを保持）を増分バックアップし、世代管理と復元を提供します。`/work` 配下のプロジェクト作業ファイルはバックアップ対象外なので、重要なファイルは Git に push するか別途バックアップを取ってください。
 
 ## 仕組み
 
@@ -20,7 +20,7 @@ graph LR
     style D fill:#e8f4e8
 ```
 
-- **フルバックアップ**: `/home/ubuntu` 共通ボリューム全体をアーカイブ
+- **フルバックアップ**: 共通ボリューム `devbase_home_ubuntu`（`/persistent/ai`）全体をアーカイブ
 - **差分バックアップ**: 前回からの変更分のみをアーカイブ
 - **圧縮**: zstd `-1 -T0`（圧縮レベル 1、全 CPU コア使用）で高速圧縮
 
@@ -200,7 +200,7 @@ graph LR
 
 #### 復元の安全性
 
-復元を実行する前に、現在の `/home/ubuntu` 共通ボリュームの状態が `pre-restore-<timestamp>` という名前で自動バックアップされます。
+復元を実行する前に、現在の共通ボリューム `devbase_home_ubuntu`（`/persistent/ai`）の状態が `pre-restore-<timestamp>` という名前で自動バックアップされます。
 
 ```bash
 # 復元前に自動作成されるバックアップ

docs/user/troubleshooting.md

@@ -373,10 +373,10 @@ devbase snapshot delete <name>
 
 **原因と解決策:**
 
-フルバックアップは `/home/ubuntu` 共通ボリューム全体を圧縮するため、データ量に比例して時間がかかります。
+フルバックアップは共通ボリューム `devbase_home_ubuntu`（コンテナ内 `/persistent/ai`）全体を圧縮するため、データ量に比例して時間がかかります。
 
 - 差分バックアップ（`--full` なし）を使用すると、変更分のみのため高速です
-- 大きな一時ファイルや不要なファイルを `/home/ubuntu` から削除してからバックアップしてください
+- 大きな一時ファイルや不要なファイルを `/persistent/ai` 配下（`~/.claude` 等の symlink 先・`~/share`）から削除してからバックアップしてください
 
 ## 6. ボリューム関連