refactor(deploy): consolidate install scripts and INSTALL.md into deploy/

- Move scripts/install_mam.sh → deploy/install_mam.sh (local-clone installer)
- Move scripts/generate-env.sh → deploy/generate-env.sh (env helper)
- Move .agents/INSTALL.md → deploy/INSTALL.md (user manual)
- Update install_mam.sh to copy INSTALL.md + generate-env.sh from new paths
- Ship INSTALL.md via deploy/install.sh remote path too (manifest-tracked)
- Update README/BOOTSTRAP generate-env.sh references & repository ASCII layout
- Extend deploy/README.md structure section; extend gitea-ci.yml lint list
- Remove now-empty scripts/ directory
- Fix duplicate ### 2. subsection headers in deploy/README.md (address B-2)
- Correct deploy/INSTALL.md dependency description to match actual checks (address M-1)
- Add local-clone lifecycle caveat (no update.sh/remove.sh) (address M-2)

Closes the deploy consolidation plan and addresses Planner / Reviewer feedback.

.agents/skills/lib.sh

@@ -797,7 +797,7 @@ provision_isolation() {
       if [ -d "$HOME/.claude/plugins" ]; then ln -sfn "$HOME/.claude/plugins" "$root/plugins"; seeded="$seeded,plugins"; fi
       ;;
     cline)
-      # Phase 0 실측: --config 공유 지정만으론 auth 미공유 — settings/* + globalState.json 시딩 필수
+      # CLI 가 --data-dir <root> 를 읽을 때 최상위 루트 하위에서 설정을 찾으므로 다이렉트 맵핑
       mkdir -p "$root/settings"
       for f in "$HOME/.cline/data/settings/"*; do
         [ -e "$f" ] || continue
@@ -807,6 +807,15 @@ provision_isolation() {
       if [ -e "$HOME/.cline/data/globalState.json" ]; then
         ln -sfn "$HOME/.cline/data/globalState.json" "$root/globalState.json"; seeded="${seeded:+$seeded,}globalState.json"
       fi
+      # 인증과 DB 바인딩을 연계하여 Welcome Screen 튕김 방지
+      mkdir -p "$root/db"
+      for f in "$HOME/.cline/data/db/"*; do
+        [ -e "$f" ] || continue
+        base="$(basename "$f")"
+        # DB 락 경쟁 크래시 방지를 위해 물리 복사(cp -p)로 직접 주입
+        cp -p "$f" "$root/db/$base"
+        seeded="${seeded:+$seeded,}db/$base"
+      done
       ;;
     agy)
       mkdir -p "$root/.gemini/antigravity-cli"
@@ -1017,7 +1026,7 @@ wait_for_tui_ready() {
     local_tmux="tmux -L $TMUX_SERVER_NAME"
   fi
   
-  for i in {1..15}; do
+  for i in {1..30}; do
     if _pane_dialog_open "$sess"; then
       sleep 1
       continue
@@ -1045,7 +1054,7 @@ wait_for_tui_ready() {
           fi
           ;;
         cline)
-          if echo "$content" | grep -E -q "Cline|history|Chat" 2>/dev/null; then
+          if echo "$content" | grep -E -q "Cline|history|Chat|What can I do|slash commands" 2>/dev/null; then
             echo "✅ Cline TUI detected ready."
             return 0
           fi

.agents/skills/multi-agent-mux-create/scripts/create_session.sh

@@ -35,8 +35,8 @@ Options:
   --tmux-server NAME  specify isolated tmux server name
   --submit-job PROMPT submit a job to multi-agent-mux-delegate-job registry with the given prompt
   --onboard           automatically submit a project alignment/orientation job to the new agent
-  --isolate           provision an isolated per-session state home (.mam/agent_homes/<uuid>)
+  --no-isolate        disable state isolation (shares global configuration/history)
-                      so same-CLI multi-role sessions never share a conversation id
+                      [default: isolated mode is always active]
   -h, --help          this help
 EOF
 }
@@ -50,7 +50,7 @@ DRY_RUN=0
 TMUX_SERVER_OPT=""
 SUBMIT_JOB_PROMPT=""
 ONBOARD=0
-ISOLATE=0
+ISOLATE=1
 
 while [ $# -gt 0 ]; do
   case "$1" in
@@ -63,7 +63,8 @@ while [ $# -gt 0 ]; do
     --tmux-server) TMUX_SERVER_OPT="$2"; shift 2 ;;
     --submit-job) SUBMIT_JOB_PROMPT="$2"; shift 2 ;;
     --onboard)   ONBOARD=1; shift ;;
-    --isolate)   ISOLATE=1; shift ;;
+    --isolate)   ISOLATE=1; shift ;; # legacy compatibility
+    --no-isolate) ISOLATE=0; shift ;;
     -h|--help)   usage; exit 0 ;;
     *) echo "ERROR: unknown arg: $1" >&2; usage; exit 2 ;;
   esac

BOOTSTRAP.ko.md

@@ -58,10 +58,10 @@ curl -fsSL https://git.godopu.com/tmpl/multi-agent-mux/raw/branch/main/deploy/in
 
 ```bash
 # .env.example를 .env로 자동 복제 (이미 존재하면 덮어쓰지 않고 보호됨)
-./scripts/generate-env.sh
+./deploy/generate-env.sh
 
 # 만약 강제로 덮어쓰고 백업을 생성하고 싶은 경우:
-./scripts/generate-env.sh --force
+./deploy/generate-env.sh --force
 ```
 
 ### 단계 3.2: 환경 변수 수정 및 설정

BOOTSTRAP.md

@@ -58,10 +58,10 @@ Run the environment template copy script provided in the project root:
 
 ```bash
 # Automatically copy .env.example to .env (does not overwrite if it already exists)
-./scripts/generate-env.sh
+./deploy/generate-env.sh
 
 # To force overwrite and create a backup of the existing .env:
-./scripts/generate-env.sh --force
+./deploy/generate-env.sh --force
 ```
 
 ### Step 3.2: Modify Environment Variables

README.ko.md

@@ -154,8 +154,13 @@ sequenceDiagram
 │   ├── agent-sessions.db        # SQLite WAL 세션 데이터베이스
 │   ├── agent-sessions.yaml      # 텍스트 형식의 세션 레지스트리 스냅샷
 │   └── jobs/                    # 비동기 잡 메타데이터 JSON 파일들
-├── scripts/
+├── deploy/                      # 배포 및 설치 도구 패키지 폴더
-│   └── generate-env.sh          # 환경 파일(.env) 템플릿 복사 스크립트
+│   ├── INSTALL.md               # 설치 가이드 및 퀵스타트 매뉴얼
+│   ├── install_mam.sh           # 로컬/클론 인스톨러 스크립트
+│   ├── generate-env.sh          # 환경 파일(.env) 템플릿 복사 스크립트
+│   ├── install.sh               # 원격/네트워크 인스톨러 스크립트
+│   ├── update.sh                # 업데이트 헬퍼 스크립트
+│   └── remove.sh                # 삭제/언인스톨 헬퍼 스크립트
 ├── BOOTSTRAP.ko.md              # 프로젝트 초기 설치 가이드 (한국어 백업)
 ├── BOOTSTRAP.md                 # 프로젝트 초기 설치 및 검증 상세 가이드
 ├── MESSAGING.md                 # MQTT 메시징 프로토콜 와이어 규격서
@@ -170,7 +175,7 @@ sequenceDiagram
 
 1.  **환경 설정 파일(.env) 생성:**
     ```bash
-    ./scripts/generate-env.sh
+    ./deploy/generate-env.sh
     ```
 2.  **가상환경 생성 및 의존성 패키지 설치:**
     ```bash

README.md

@@ -172,8 +172,13 @@ To ensure communication integrity across public MQTT brokers, the backplane inte
 │   ├── agent-sessions.db        # SQLite WAL session database
 │   ├── agent-sessions.yaml      # Human-readable session registry
 │   └── jobs/                    # Asynchronous job metadata files
-├── scripts/
+├── deploy/                      # Distribution and installation package
-│   └── generate-env.sh          # Environment bootstrap helper
+│   ├── INSTALL.md               # User manual for installation and quick-start
+│   ├── install_mam.sh           # Local/Clone installer script
+│   ├── generate-env.sh          # Environment bootstrap helper
+│   ├── install.sh               # Remote/Network installer script
+│   ├── update.sh                # Updater script
+│   └── remove.sh                # Uninstaller script
 ├── BOOTSTRAP.md                 # Detailed installation and verification guide
 ├── MESSAGING.md                 # MQTT wire protocol specification
 └── README.md                    # Project introduction and overview (this file)
@@ -187,7 +192,7 @@ For detailed setup instructions, please consult the **[BOOTSTRAP.md](./BOOTSTRAP
 
 1.  **Initialize Environment Config:**
     ```bash
-    ./scripts/generate-env.sh
+    ./deploy/generate-env.sh
     ```
 2.  **Create Virtual Environment and Install Dependencies:**
     ```bash

deploy/INSTALL.md

@@ -11,27 +11,30 @@ MAM 스킬 및 스크립트들은 호스트 시스템의 다음 도구들에 의
 *   **tmux**: 에이전트를 백그라운드 격리 Pane에서 구동하기 위한 프로세스 컨테이너
 *   **python3**: 세션 레지스트리(YAML/SQLite DB) 파싱 및 유효성 검사 (내장 `sqlite3` 모듈 필수)
 *   **uuidgen**: 격리 세션 생성 시 고유의 UUID 할당
-*   **rsync**: 인스톨러(`install_mam.sh`)가 `.agents/` 오케스트레이터 및 스킬 폴더를 타겟 프로젝트에 복제하는 데 사용 (설치 시 필요)
+*   **rsync**: 인스톨러(`deploy/install_mam.sh`)가 `.agents/` 오케스트레이터 및 스킬 폴더를 타겟 프로젝트에 복제하는 데 사용 (설치 시 필요)
 *   **python3-yaml (pyyaml)**: 세션 데이터 YAML 저장 및 로드 의존성 (`pip install pyyaml`)
 
 ---
 
 ## 2. 🚀 자동 설치 방법
 
-MAM의 자동 설치 스크립트(`install_mam.sh`)를 사용하여 10초 만에 필요한 규칙과 라이프사이클 툴킷을 타겟 프로젝트에 이식할 수 있습니다. 스크립트는 실행 시 자동으로 시스템의 `tmux`, `python3`, `rsync`, `uuidgen` 및 필수 파이썬 모듈들을 진단합니다.
+MAM의 자동 설치 스크립트(`deploy/install_mam.sh`)를 사용하여 10초 만에 필요한 규칙과 라이프사이클 툴킷을 타겟 프로젝트에 이식할 수 있습니다. 스크립트는 실행 시 자동으로 시스템의 `tmux`, `python3`, `rsync`, `uuidgen` 및 필수 파이썬 모듈들을 진단합니다.
+
+> [!IMPORTANT]
+> **설치 전제조건**: MAM 스킬을 타겟 프로젝트에 설치하려면 **먼저 MAM 레포지토리가 로컬 머신에 clone 되어 있어야 합니다.**
 
 ### 설치 스크립트 실행
-MAM 레포지토리 루트에서 다음 명령어를 실행합니다.
+MAM 레포지토리 루트 디렉토리로 이동한 후 다음 명령어를 실행합니다.
 ```bash
 # 기본 사용법 (타겟 프로젝트 경로 지정)
-$ bash scripts/install_mam.sh --target /path/to/your/project
+$ bash deploy/install_mam.sh --target /path/to/your/project
 
 # 만약 이미 타겟에 AGENTS.md 가 존재하여 강제로 덮어쓰고 싶다면:
-$ bash scripts/install_mam.sh --target /path/to/your/project --force
+$ bash deploy/install_mam.sh --target /path/to/your/project --force
 ```
 
 ### 설치 스크립트가 수행하는 작업:
-1.  **의존성 진단**: 시스템에 `tmux`, `python3`, `sqlite3` 가 설치되어 있는지 확인합니다.
+1.  **의존성 진단**: 시스템에 `tmux`, `python3`, `rsync`, `uuidgen` CLI 바이너리와 파이썬 `pyyaml`/`sqlite3` 모듈이 설치되어 있는지 확인합니다.
 2.  **규칙 및 스킬 복제**: 오케스트레이션 가이드(`.agents/` 하위 전체)를 타겟 프로젝트 하위로 이식합니다.
 3.  **지침 전파**: 에이전트가 로드하고 복종할 행동 지침 문서(`AGENTS.md`)를 프로젝트 루트에 복사합니다.
 4.  **형상 제외 설정**: 세션 DB 및 격리 캐시 저장소인 `.mam/` 디렉토리를 타겟 프로젝트의 `.gitignore` 에 자동 주입하여 불필요한 형상 관리를 방지합니다.
@@ -65,7 +68,7 @@ $ tmux -L multi-agent-mux attach -t my-project-dev-claude
 ### 3) 에이전트 상태 복원 (Resume)
 세션이 중지되었거나, 호스트 재기동으로 tmux가 소멸한 경우에도 이전 대화 ID 및 격리 디렉토리를 원자적으로 이어받아 다시 기동할 수 있습니다.
 ```bash
-# 1단계: resume/SKILL.md를 참고하여 복원 스크립트 실행 (YAML/DB의 UUID 자동 로드 및 T4 격리 재바인딩)
+# 1단계: 복원 대상 세션의 UUID 자동 조회 (DB/YAML 레지스트리 기반)
 $ WORKSPACE="/path/to/your/project"
 $ AGENT="claude"
 $ SESSION_NAME="my-project-dev-claude"
@@ -76,8 +79,14 @@ $ UUID=$(bash .agents/skills/multi-agent-mux-resume/scripts/resolve_session_id.s
 # 복원 대상 세션의 유효성 검사 (M-1)
 $ [ -n "$UUID" ] || { echo "[ERROR] 매칭되는 활성 세션 이력이 없습니다. create_session.sh를 통해 먼저 세션을 생성해 주세요."; exit 1; }
  
-# 2단계: 동적 격리 인자 주입 스폰 수행 후 레지스트리 상태 running 복구
+# 2단계: 세션 재기동 (이전 대화 컨텍스트 복원 기동)
-# (상세 쉘 명령어는 .agents/skills/multi-agent-mux-resume/SKILL.md 참조)
+# (주의: 만약 create 시 격리(--isolate) 세션으로 생성했다면, CLAUDE_CONFIG_DIR 환경변수를 YAML에 기록된 isolation.root 경로로 지정하여 띄워야 합니다. 상세 격리 복원 커맨드는 .agents/skills/multi-agent-mux-resume/SKILL.md 문서를 필독해 주세요.)
+$ tmux -L multi-agent-mux new-session -d -s "$SESSION_NAME" -x 140 -y 40 -c "$WORKSPACE" \
+    "claude --dangerously-skip-permissions -r $UUID; echo 'CLAUDE EXIT'; bash"
+ 
+# 3단계: 레지스트리 세션 상태를 running 으로 동기화 갱신
+$ bash .agents/skills/multi-agent-mux-resume/scripts/update_yaml_resumed.sh \
+    --session "$SESSION_NAME" --uuid "$UUID" --agent "$AGENT"
 ```
 
 ### 4) 세션 종료 및 정리 (Stop / Purge)

deploy/README.md

@@ -6,7 +6,10 @@ This directory contains packaging templates and installation scripts to deploy t
 
 ## 📁 Deployment Directory Structure
 
-*   **`install.sh`**: A self-contained, idempotent shell installer that checks system requirements (`tmux`, `python3`, `pip3`), detects NFS/network filesystem mounts, sets up a local python virtual environment (`.venv`), and initializes environment configuration (`.env`).
+*   **`install.sh`**: A self-contained, idempotent remote shell installer (via curl) that checks system requirements (`tmux`, `python3`), detects NFS/network filesystem mounts, sets up a local python virtual environment (`.venv`), and initializes environment configuration (`.env`).
+*   **`install_mam.sh`**: A local-clone installer that copies rules/skills (`.agents/`), `AGENTS.md`, and sets up environment bootstrap on target projects.
+*   **`generate-env.sh`**: Environment configuration bootstrap helper.
+*   **`INSTALL.md`**: Detailed installation and quick-start user manual.
 *   **`plugin.json`**: Metadata declaration file to register MAM as an installable plugin for AI Agent coding platforms (such as Claude Code, Antigravity, or other TUI clients).
 *   **`gitea-ci.yml`**: CI/CD pipeline definition template for Gitea Actions (running ShellCheck linting on bash scripts, validation on python scripts, and compilation tests).
 
@@ -26,7 +29,17 @@ Alternatively, if they have cloned the repository, they can execute:
 bash deploy/install.sh
 ```
 
-### 2. Custom Fork / Private Mirror Installations
+### 2. Local-Clone Installation
+If you already have cloned this repository locally, you can port MAM to other local target projects:
+```bash
+bash deploy/install_mam.sh --target /path/to/your/project
+```
+Refer to **`INSTALL.md`** inside this directory for the full instructions and workflows.
+
+> [!NOTE]
+> The local-clone installer does not ship `update.sh`/`remove.sh` to targets. To enable in-place updates, re-run the remote installer (`curl ... | bash`) or copy `deploy/update.sh` + `deploy/remove.sh` manually.
+
+### 3. Custom Fork / Private Mirror Installations
 If you run a private mirror or fork, you can override the source URLs during installation using environment variables:
 
 ```bash
@@ -40,7 +53,7 @@ curl -fsSL https://my-mirror.example.com/.../install.sh \
 MAM_INSTALLER_URL=https://my-mirror.example.com/.../install.sh bash deploy/update.sh
 ```
 
-### 2. Registering as a Workspace Plugin
+### 4. Registering as a Workspace Plugin
 To register these skills globally or for a specific workspace:
 *   **Workspace Level**: Copy the `.agents/` folder into your project root.
 *   **Global Level (Gemini/Antigravity)**: Register the plugin path in your global config file at `~/.gemini/config/skills.json`:

deploy/generate-env.sh

@@ -6,10 +6,10 @@
 #   - .env present         → no-op (leaves your edits intact), exit 0.
 #   - .env present --force  → overwrite .env from .env.example (backs up to .env.bak).
 #
-# Paths are resolved relative to this script (repo root = parent of scripts/),
+# Paths are resolved relative to this script (repo root = parent of deploy/),
 # so it works regardless of the caller's cwd.
 #
-# Usage: scripts/generate-env.sh [--force] [-h|--help]
+# Usage: deploy/generate-env.sh [--force] [-h|--help]
 set -euo pipefail
 
 REPO_ROOT="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"

deploy/gitea-ci.yml

@@ -33,6 +33,10 @@ jobs:
           shellcheck .agents/skills/multi-agent-mux-stop/scripts/stop_session.sh
           shellcheck .agents/skills/multi-agent-mux-monitor/scripts/reconcile.sh
           shellcheck deploy/install.sh
+          shellcheck deploy/install_mam.sh
+          shellcheck deploy/generate-env.sh
+          shellcheck deploy/update.sh
+          shellcheck deploy/remove.sh
           echo "✅ ShellCheck completed successfully."
 
   lint-python:

deploy/install.sh

@@ -152,6 +152,15 @@ if ! check_assets_present "."; then
     echo ".env.example" >> "$MANIFEST_FILE"
   fi
 
+  # Ship the user manual into the target's .agents/ (consistent with install_mam.sh)
+  if [ -f "$STAGE_DIR/deploy/INSTALL.md" ]; then
+    mkdir -p .agents
+    if [ ! -e ".agents/INSTALL.md" ]; then
+      cp "$STAGE_DIR/deploy/INSTALL.md" .agents/INSTALL.md || { echo "❌ Error: Failed to copy INSTALL.md" >&2; exit 1; }
+      echo ".agents/INSTALL.md" >> "$MANIFEST_FILE"
+    fi
+  fi
+
   rm -rf "$STAGE_DIR"
   trap - EXIT
   echo "✅ Skills staged into workspace (existing files preserved)."

deploy/install_mam.sh

@@ -119,11 +119,16 @@ if [ -f "$SRC_DIR/.env.example" ]; then
   cp "$SRC_DIR/.env.example" "$TARGET_DIR/.env.example"
   log_ok "Copied .env.example configuration template"
 fi
-if [ -f "$SRC_DIR/scripts/generate-env.sh" ]; then
+if [ -f "$SRC_DIR/deploy/generate-env.sh" ]; then
   mkdir -p "$TARGET_DIR/scripts"
-  cp "$SRC_DIR/scripts/generate-env.sh" "$TARGET_DIR/scripts/generate-env.sh"
+  cp "$SRC_DIR/deploy/generate-env.sh" "$TARGET_DIR/scripts/generate-env.sh"
   chmod +x "$TARGET_DIR/scripts/generate-env.sh"
-  log_ok "Copied scripts/generate-env.sh helper tool"
+  log_ok "Copied deploy/generate-env.sh helper tool"
+fi
+# Copy the user manual into the target's .agents/ (previously came via rsync of .agents/)
+if [ -f "$SRC_DIR/deploy/INSTALL.md" ]; then
+  cp "$SRC_DIR/deploy/INSTALL.md" "$TARGET_DIR/.agents/INSTALL.md"
+  log_ok "Copied INSTALL.md user manual into target .agents/"
 fi
 
 # 3. Copy AGENTS.md to root or inject guidelines pointer