@tyhld/conductor 0.3.0

package/sales-template/settings.json

@@ -0,0 +1,161 @@
+{
+  "_note": "采配くん販売用テンプレート — プロジェクトの .claude/settings.json に配置する。<PLACEHOLDER> を顧客環境に合わせて差し替えること。差し替え箇所は README.md の「プレースホルダ一覧」を参照。",
+  "permissions": {
+    "defaultMode": "default",
+    "disableBypassPermissionsMode": "disable",
+    "allow": [
+      "Read",
+      "Edit(<PROJECT_DIR>/**)",
+      "Write(<PROJECT_DIR>/**)",
+
+      "Bash(npm run build:*)",
+      "Bash(npm run dev:*)",
+      "Bash(npm run lint:*)",
+      "Bash(npm run test:*)",
+      "Bash(npm install:*)",
+      "Bash(npm ci:*)",
+      "Bash(npx tsc:*)",
+      "Bash(npx tsc --noEmit:*)",
+      "Bash(npx eslint:*)",
+      "Bash(npx next lint:*)",
+      "Bash(npx next build:*)",
+      "Bash(npx vitest:*)",
+      "Bash(npx prettier:*)",
+      "Bash(pnpm install:*)",
+      "Bash(pnpm build:*)",
+      "Bash(pnpm lint:*)",
+      "Bash(pnpm test:*)",
+      "Bash(pnpm typecheck:*)",
+      "Bash(pnpm format:*)",
+      "Bash(pnpm run build:*)",
+      "Bash(pnpm run lint:*)",
+      "Bash(pnpm run test:*)",
+      "Bash(pnpm run typecheck:*)",
+      "Bash(tsc:*)",
+
+      "Bash(git status:*)",
+      "Bash(git log:*)",
+      "Bash(git diff:*)",
+      "Bash(git show:*)",
+      "Bash(git branch:*)",
+      "Bash(git fetch:*)",
+      "Bash(git add:*)",
+      "Bash(git commit:*)",
+      "Bash(git checkout -b:*)",
+      "Bash(git switch -c:*)",
+      "Bash(git stash list:*)",
+      "Bash(git rev-parse:*)",
+      "Bash(git ls-files:*)",
+      "Bash(git remote -v:*)",
+      "Bash(git push:*)",
+
+      "Bash(grep:*)",
+      "Bash(find:*)",
+      "Bash(cat:*)",
+      "Bash(ls:*)",
+      "Bash(head:*)",
+      "Bash(tail:*)",
+      "Bash(wc:*)",
+      "Bash(which:*)",
+      "Bash(pwd:*)",
+      "Bash(ps:*)",
+
+      "Bash(gh pr view:*)",
+      "Bash(gh pr checks:*)",
+      "Bash(gh pr diff:*)",
+      "Bash(gh pr list:*)",
+      "Bash(gh pr status:*)",
+      "Bash(gh run list:*)",
+      "Bash(gh run view:*)",
+      "Bash(gh repo view:*)"
+    ],
+    "ask": [
+      "Bash(gh pr merge:*)",
+      "Bash(gh pr create:*)",
+      "Bash(git push origin main:*)",
+      "Bash(git push -u origin main:*)",
+      "Bash(git push --set-upstream origin main:*)",
+      "Bash(git merge:*)",
+      "Bash(vercel --prod:*)",
+      "Bash(vercel deploy --prod:*)",
+      "Bash(npx vercel --prod:*)",
+      "Bash(npm publish:*)",
+      "Bash(pnpm publish:*)",
+      "Bash(supabase functions deploy:*)",
+      "Bash(npx supabase functions deploy:*)"
+    ],
+    "deny": [
+      "Bash(git push --force:*)",
+      "Bash(git push -f:*)",
+      "Bash(git push --force-with-lease:*)",
+      "Bash(git push * --force:*)",
+      "Bash(git push * -f:*)",
+      "Bash(git push * --force-with-lease:*)",
+      "Bash(rm -rf:*)",
+      "Bash(rm -fr:*)",
+      "Bash(rm -r -f:*)",
+      "Bash(rm -f -r:*)",
+      "Bash(rm -R:*)",
+      "Bash(rm --recursive:*)",
+      "Bash(rm --force --recursive:*)",
+      "Bash(supabase db push:*)",
+      "Bash(npx supabase db push:*)",
+      "Bash(supabase db reset:*)",
+      "Bash(npx supabase db reset:*)",
+      "Bash(supabase migration up:*)",
+      "Bash(npx supabase migration up:*)",
+      "Bash(prisma migrate deploy:*)",
+      "Bash(npx prisma migrate deploy:*)",
+      "Bash(prisma migrate reset:*)",
+      "Bash(npx prisma migrate reset:*)",
+      "Bash(prisma db push:*)",
+      "Bash(npx prisma db push:*)",
+      "Bash(drizzle-kit push:*)",
+      "Bash(npx drizzle-kit push:*)",
+      "Bash(npm run migrate:*)",
+      "Bash(pnpm migrate:*)",
+      "Bash(pnpm run migrate:*)",
+      "Bash(*DROP TABLE*)",
+      "Bash(*TRUNCATE*)",
+      "Bash(*rest/v1/rpc/exec_sql*)",
+      "Bash(cat .env:*)",
+      "Bash(cat .env.*:*)",
+      "Bash(cat *.env:*)",
+      "Bash(printenv:*)",
+      "Bash(echo $DATABASE_URL:*)",
+      "Bash(echo $DIRECT_URL:*)",
+      "mcp__claude_ai_Supabase__execute_sql",
+      "mcp__claude_ai_Supabase__apply_migration",
+      "mcp__claude_ai_Supabase__deploy_edge_function"
+    ]
+  },
+  "sandbox": {
+    "enabled": true,
+    "failIfUnavailable": true,
+    "autoAllowBashIfSandboxed": true,
+    "network": {
+      "allowedDomains": [
+        "<SUPABASE_PROJECT_ID>.supabase.co",
+        "api.supabase.com",
+        "supabase.com",
+        "registry.npmjs.org",
+        "npm.pkg.github.com",
+        "github.com",
+        "api.github.com",
+        "codeload.github.com",
+        "objects.githubusercontent.com",
+        "raw.githubusercontent.com",
+        "vercel.com",
+        "api.vercel.com",
+        "localhost",
+        "127.0.0.1",
+        "::1"
+      ],
+      "deniedDomains": [
+        "db.<SUPABASE_PROJECT_ID>.supabase.co",
+        "aws-0-ap-northeast-1.pooler.supabase.com",
+        "aws-1-ap-northeast-1.pooler.supabase.com"
+      ]
+    }
+  }
+}

package/sales-template/setup.sh

@@ -0,0 +1,350 @@
+#!/usr/bin/env bash
+#
+# setup.sh — 采配くん一式を顧客PCに1コマンドでインストールする統合インストーラ。
+#
+# 使い方:
+#   bash setup.sh <プロジェクト名> [プロジェクトディレクトリ]
+#
+# 例:
+#   bash setup.sh my-app                          # ~/projects/my-app を想定
+#   bash setup.sh my-app /home/user/work/my-app   # ディレクトリを明示指定
+#
+# やること（順番に・冪等・失敗時は止めて報告）:
+#   ① 前提チェック（node>=18 / tmux / git / python3>=3.8 / systemd / sudo）
+#   ② conductor 本体インストール（npm i -g @tyhld/conductor）
+#   ③ node symlink（/usr/local/bin/node → 実体・sudo）
+#   ④ .conductor.env 作成（対話入力・chmod 600）
+#   ⑤ .claude/ 配置（cc2_guard.py + settings.json + hooks 設定）
+#   ⑥ systemd install（enable + linger）
+#   ⑦ 職人起動の案内表示
+#
+set -euo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+
+# ─── 引数チェック ─────────────────────────────────────────────────────────────
+if [[ $# -lt 1 || -z "${1:-}" ]]; then
+  cat >&2 <<'USAGE'
+采配くんセットアップ
+
+使い方: bash setup.sh <プロジェクト名> [プロジェクトディレクトリ]
+
+例:
+  bash setup.sh my-app                          # ~/projects/my-app を想定
+  bash setup.sh my-app /home/user/work/my-app   # ディレクトリを明示指定
+USAGE
+  exit 1
+fi
+
+SITE="$1"
+PROJECT_DIR="${2:-$HOME/projects/$SITE}"
+
+# ─── ヘルパ ───────────────────────────────────────────────────────────────────
+fail() { echo; echo "[setup] エラー: $1" >&2; exit 1; }
+warn() { echo "[setup] warn: $1" >&2; }
+step() { echo; echo "══════════════════════════════════════════════════════════"; echo "[setup] $1"; echo "══════════════════════════════════════════════════════════"; }
+
+# ─── ① 前提チェック ──────────────────────────────────────────────────────────
+step "① 前提チェック"
+
+errors=()
+
+# node >= 18
+if command -v node >/dev/null 2>&1; then
+  NODE_VER="$(node --version 2>/dev/null || echo 'v0')"
+  NODE_MAJOR="${NODE_VER#v}"
+  NODE_MAJOR="${NODE_MAJOR%%.*}"
+  if [[ "$NODE_MAJOR" -lt 18 ]] 2>/dev/null; then
+    errors+=("node $NODE_VER が古すぎます。18 以上が必要です。")
+  else
+    echo "[setup] node: $NODE_VER OK"
+  fi
+else
+  errors+=("node が見つかりません。Node.js 18 以上をインストールしてください（fnm / nvm / volta / apt）。")
+fi
+
+# tmux
+if command -v tmux >/dev/null 2>&1; then
+  echo "[setup] tmux: $(tmux -V 2>/dev/null || echo 'OK')"
+else
+  errors+=("tmux が見つかりません。sudo apt install tmux でインストールしてください。")
+fi
+
+# git
+if command -v git >/dev/null 2>&1; then
+  echo "[setup] git: $(git --version 2>/dev/null)"
+else
+  errors+=("git が見つかりません。sudo apt install git でインストールしてください。")
+fi
+
+# python3 >= 3.8
+if command -v python3 >/dev/null 2>&1; then
+  PY_VER="$(python3 --version 2>/dev/null || echo 'Python 0')"
+  PY_MINOR="$(echo "$PY_VER" | sed -E 's/Python ([0-9]+)\.([0-9]+).*/\2/')"
+  PY_MAJOR="$(echo "$PY_VER" | sed -E 's/Python ([0-9]+)\..*/\1/')"
+  if [[ "$PY_MAJOR" -lt 3 ]] 2>/dev/null || { [[ "$PY_MAJOR" -eq 3 ]] && [[ "$PY_MINOR" -lt 8 ]]; } 2>/dev/null; then
+    errors+=("$PY_VER が古すぎます。Python 3.8 以上が必要です。")
+  else
+    echo "[setup] python3: $PY_VER OK"
+  fi
+else
+  errors+=("python3 が見つかりません。sudo apt install python3 でインストールしてください。")
+fi
+
+# systemd
+if command -v systemctl >/dev/null 2>&1; then
+  if systemctl --user show-environment >/dev/null 2>&1; then
+    echo "[setup] systemd: ユーザーセッション OK"
+  else
+    errors+=("systemd ユーザーセッションに接続できません。WSL の場合: /etc/wsl.conf に [boot] systemd=true を設定し wsl --shutdown で再起動してください。")
+  fi
+else
+  errors+=("systemctl が見つかりません。systemd が有効か確認してください。")
+fi
+
+# sudo
+if command -v sudo >/dev/null 2>&1; then
+  echo "[setup] sudo: OK"
+else
+  errors+=("sudo が見つかりません。node symlink の作成（③）で必要です。")
+fi
+
+# プロジェクトディレクトリ
+if [[ -d "$PROJECT_DIR" ]]; then
+  echo "[setup] プロジェクトディレクトリ: $PROJECT_DIR OK"
+else
+  errors+=("プロジェクトディレクトリが存在しません: $PROJECT_DIR")
+fi
+
+if [[ ${#errors[@]} -gt 0 ]]; then
+  echo
+  echo "[setup] 前提チェックに失敗しました:" >&2
+  for e in "${errors[@]}"; do
+    echo "  - $e" >&2
+  done
+  exit 1
+fi
+
+# ─── ② conductor 本体インストール ────────────────────────────────────────────
+step "② conductor 本体インストール"
+
+# @tyhld/conductor は公開 npm (registry.npmjs.org) で配布されるため、
+# PAT や .npmrc の設定は不要。無認証で npm i -g できる。
+if command -v conductor >/dev/null 2>&1; then
+  echo "[setup] conductor は既にインストール済みです。更新します..."
+  npm update -g @tyhld/conductor || warn "npm update に失敗しました。続行します。"
+else
+  echo "[setup] @tyhld/conductor をグローバルインストールします..."
+  npm install -g @tyhld/conductor || fail "npm install -g @tyhld/conductor に失敗しました。ネットワーク接続を確認してください。"
+fi
+
+# conductor コマンドの存在を再確認
+if ! command -v conductor >/dev/null 2>&1; then
+  fail "conductor コマンドが見つかりません。npm グローバルインストールの PATH を確認してください。"
+fi
+echo "[setup] conductor: $(conductor --version 2>/dev/null || command -v conductor)"
+
+# ─── ③ node symlink ──────────────────────────────────────────────────────────
+step "③ node symlink（systemd PATH 対応）"
+
+NODE_PATH="$(readlink -f "$(command -v node)")"
+SYMLINK_PATH="/usr/local/bin/node"
+
+need_symlink=true
+if [[ -f "$SYMLINK_PATH" || -L "$SYMLINK_PATH" ]]; then
+  existing="$(readlink -f "$SYMLINK_PATH" 2>/dev/null || echo '')"
+  if [[ "$existing" == "$NODE_PATH" ]]; then
+    echo "[setup] $SYMLINK_PATH は既に正しいリンクです → スキップ"
+    need_symlink=false
+  fi
+fi
+
+if $need_symlink; then
+  echo "[setup] $SYMLINK_PATH → $NODE_PATH のシンボリックリンクを作成します（sudo）"
+  if [[ -w "$(dirname "$SYMLINK_PATH")" ]]; then
+    ln -sf "$NODE_PATH" "$SYMLINK_PATH"
+  else
+    sudo ln -sf "$NODE_PATH" "$SYMLINK_PATH"
+  fi
+  echo "[setup] symlink 作成完了"
+fi
+
+# ─── ④ .conductor.env 作成 ───────────────────────────────────────────────────
+step "④ .conductor.env（管制サーバ接続情報）"
+
+ENV_FILE="$HOME/.conductor.env"
+if [[ -f "$ENV_FILE" ]]; then
+  echo "[setup] $ENV_FILE は既に存在します → スキップ"
+  echo "[setup] 内容を変更する場合は手動で編集してください。"
+else
+  echo "[setup] 管制サーバへの接続情報を入力してください。"
+  echo
+
+  read -r -p "  CONDUCTOR_URL（例: https://your-conductor.vercel.app）: " input_url
+  [[ -z "$input_url" ]] && fail "CONDUCTOR_URL が空です。"
+
+  read -r -p "  CONDUCTOR_SHARED_SECRET: " input_secret
+  [[ -z "$input_secret" ]] && fail "CONDUCTOR_SHARED_SECRET が空です。"
+
+  cat > "$ENV_FILE" <<ENVEOF
+CONDUCTOR_URL=${input_url}
+CONDUCTOR_SHARED_SECRET=${input_secret}
+ENVEOF
+  chmod 600 "$ENV_FILE"
+  echo "[setup] $ENV_FILE を作成しました（chmod 600）"
+fi
+
+# ─── ⑤ .claude/ 配置（PERM ルール + Hook） ──────────────────────────────────
+step "⑤ .claude/ 配置（権限ルール + Hook）"
+
+CLAUDE_DIR="$PROJECT_DIR/.claude"
+HOOKS_DIR="$CLAUDE_DIR/hooks"
+mkdir -p "$HOOKS_DIR"
+
+# --- cc2_guard.py ---
+GUARD_SRC="$SCRIPT_DIR/cc2_guard.py"
+GUARD_DST="$HOOKS_DIR/cc2_guard.py"
+if [[ -f "$GUARD_SRC" ]]; then
+  cp -f "$GUARD_SRC" "$GUARD_DST"
+  chmod +x "$GUARD_DST"
+  echo "[setup] 配置: $GUARD_DST"
+else
+  warn "cc2_guard.py が見つかりません: $GUARD_SRC（スキップ）"
+fi
+
+# --- settings.json ---
+SETTINGS_SRC="$SCRIPT_DIR/settings.json"
+SETTINGS_DST="$CLAUDE_DIR/settings.json"
+if [[ -f "$SETTINGS_SRC" ]]; then
+  if [[ -f "$SETTINGS_DST" ]]; then
+    echo "[setup] $SETTINGS_DST は既に存在します。上書きしますか？"
+    read -r -p "  上書き (y/N): " overwrite
+    if [[ "${overwrite,,}" != "y" ]]; then
+      echo "[setup] settings.json をスキップしました。"
+    else
+      cp -f "$SETTINGS_SRC" "$SETTINGS_DST"
+      echo "[setup] 配置: $SETTINGS_DST（上書き）"
+    fi
+  else
+    cp -f "$SETTINGS_SRC" "$SETTINGS_DST"
+    echo "[setup] 配置: $SETTINGS_DST"
+  fi
+
+  # <PROJECT_DIR> をプロジェクトの絶対パスに置換
+  if [[ -f "$SETTINGS_DST" ]] && grep -q '<PROJECT_DIR>' "$SETTINGS_DST"; then
+    ABS_PROJECT_DIR="$(cd "$PROJECT_DIR" && pwd)"
+    sed -i "s|<PROJECT_DIR>|${ABS_PROJECT_DIR}|g" "$SETTINGS_DST"
+    echo "[setup] <PROJECT_DIR> → $ABS_PROJECT_DIR に置換"
+  fi
+
+  # Supabase 設定
+  if [[ -f "$SETTINGS_DST" ]] && grep -q '<SUPABASE_PROJECT_ID>' "$SETTINGS_DST"; then
+    echo
+    read -r -p "[setup] Supabase を使いますか？ (y/N): " use_supabase
+    if [[ "${use_supabase,,}" == "y" ]]; then
+      read -r -p "  Supabase Project Reference ID: " supabase_id
+      if [[ -n "$supabase_id" ]]; then
+        sed -i "s|<SUPABASE_PROJECT_ID>|${supabase_id}|g" "$SETTINGS_DST"
+        echo "[setup] <SUPABASE_PROJECT_ID> → $supabase_id に置換"
+      else
+        warn "Supabase ID が空のため、sandbox 設定にプレースホルダが残ります。"
+      fi
+    else
+      # sandbox セクションを削除（Supabase 不使用）
+      # JSON から "sandbox" キー全体を除去するのは sed では困難なため、
+      # python3 で安全に処理する。
+      if python3 -c "
+import json, sys
+with open('$SETTINGS_DST') as f:
+    d = json.load(f)
+d.pop('sandbox', None)
+with open('$SETTINGS_DST', 'w') as f:
+    json.dump(d, f, indent=2, ensure_ascii=False)
+    f.write('\n')
+" 2>/dev/null; then
+        echo "[setup] Supabase 不使用のため sandbox セクションを削除しました"
+      else
+        warn "sandbox セクションの自動削除に失敗しました。手動で .claude/settings.json を編集してください。"
+      fi
+    fi
+  fi
+else
+  warn "settings.json が見つかりません: $SETTINGS_SRC（スキップ）"
+fi
+
+# --- hooks 設定を settings.json に注入 ---
+if [[ -f "$SETTINGS_DST" ]]; then
+  # hooks キーが既に存在するか確認
+  if ! python3 -c "
+import json
+with open('$SETTINGS_DST') as f:
+    d = json.load(f)
+print('has_hooks' if 'hooks' in d else 'no_hooks')
+" 2>/dev/null | grep -q 'has_hooks'; then
+    # hooks セクションを追加
+    python3 -c "
+import json
+with open('$SETTINGS_DST') as f:
+    d = json.load(f)
+d['hooks'] = {
+    'PreToolUse': [
+        {
+            'matcher': 'Bash',
+            'hooks': [
+                {
+                    'type': 'command',
+                    'command': 'python3 .claude/hooks/cc2_guard.py'
+                }
+            ]
+        }
+    ]
+}
+with open('$SETTINGS_DST', 'w') as f:
+    json.dump(d, f, indent=2, ensure_ascii=False)
+    f.write('\n')
+" 2>/dev/null && echo "[setup] hooks 設定を settings.json に注入しました" \
+              || warn "hooks 設定の注入に失敗しました。手動で追加してください。"
+  else
+    echo "[setup] hooks 設定は既に存在します → スキップ"
+  fi
+fi
+
+# ─── ⑥ systemd install ──────────────────────────────────────────────────────
+step "⑥ systemd 常駐サービスの設定"
+
+SYSTEMD_INSTALL="$SCRIPT_DIR/systemd/install.sh"
+if [[ -f "$SYSTEMD_INSTALL" ]]; then
+  bash "$SYSTEMD_INSTALL" "$SITE" "$PROJECT_DIR"
+else
+  warn "systemd/install.sh が見つかりません: $SYSTEMD_INSTALL（スキップ）"
+  echo "[setup] 手動で systemd を設定する場合は sales-template/systemd/README.md を参照してください。"
+fi
+
+# ─── ⑦ 職人起動の案内 ────────────────────────────────────────────────────────
+step "⑦ 完了！ 職人（Claude Code）の起動方法"
+
+cat <<GUIDE
+
+采配くんのセットアップが完了しました。
+
+次のステップ: Claude Code（職人）を起動してください。
+
+  # 1. tmux セッションを作成
+  tmux new-session -d -s "$SITE" -c "$PROJECT_DIR"
+
+  # 2. ANTHROPIC_API_KEY を無効化して Claude Code を起動
+  tmux send-keys -t "$SITE" "unset ANTHROPIC_API_KEY && claude" C-m
+
+  # 3. セッションに接続
+  tmux attach -t "$SITE"
+
+Claude Code が起動したら、管制サーバから指示を送ることができます。
+relay が15秒ごとに指示をポーリングし、Claude Code がアイドル状態のときに自動で流し込みます。
+
+--- 管理コマンド ---
+  状態確認:  systemctl --user status conductor@${SITE}
+  ログ確認:  journalctl --user -u conductor@${SITE} -f
+  再起動:    systemctl --user restart conductor@${SITE}
+  停止:      systemctl --user disable --now conductor@${SITE}
+
+GUIDE

package/sales-template/systemd/README.md

@@ -0,0 +1,169 @@
+# 采配くん常駐サービス（systemd テンプレート）
+
+PC の起動時に采配くんの relay（指示の自動流し込み）と heartbeat（生存報告）を自動で常駐させるための systemd ユーザーサービスです。
+
+## これは何をするか
+
+```
+PC起動
+  │
+  ▼
+systemd が conductor@<プロジェクト> を自動起動
+  │
+  ├── heartbeat: 管制サーバに「このPCは生きている」を定期報告
+  │
+  └── relay: 管制サーバから指示をポーリング
+       └── tmux セッション内の Claude Code がアイドルなら指示を流し込む
+           （ビジー・セッションなしならスキップ＝誤爆なし）
+```
+
+- **落ちても自動復活**: `Restart=always` で5秒後に再起動
+- **ログオフしても常駐**: `enable-linger` で SSH 切断後も動き続ける
+- **CC1B（LLM判断層）は不要**: 権限制御は cc2_guard.py + settings.json で行う（ADR-001）
+
+## ファイル一覧
+
+| ファイル | 役割 |
+|----------|------|
+| `conductor@.service` | systemd ユニットファイル（テンプレート） |
+| `install.sh` | インストーラ（node検出→symlink→配置→enable→linger） |
+| `README.md` | このファイル |
+
+**conductor-orchestrator.service は含まない**: ADR-001 の決定により CC1B（LLM判断層）は撤去。orchestrator サービスは販売構成では不要。
+
+## セットアップ手順
+
+### 前提条件
+
+- Linux（WSL 含む）で systemd が有効
+- Node.js 18 以上がインストール済み（fnm / nvm / volta / apt いずれでも可）
+- `~/.conductor.env` が用意済み
+- conductor リポで `npm run build` 済み
+
+### 1. 鍵ファイルを用意
+
+```bash
+cat > "$HOME/.conductor.env" <<'EOF'
+CONDUCTOR_URL=https://<采配くん管制サーバURL>
+CONDUCTOR_SHARED_SECRET=<シークレット>
+EOF
+chmod 600 "$HOME/.conductor.env"
+```
+
+### 2. インストール実行
+
+```bash
+# プロジェクトが ~/projects/<名前> にある場合（既定パス）
+bash install.sh my-app
+
+# プロジェクトが別の場所にある場合
+bash install.sh my-app /home/user/work/my-app
+```
+
+### 3. 動作確認
+
+```bash
+# サービスの状態を確認
+systemctl --user status conductor@my-app
+
+# ログをリアルタイムで確認
+journalctl --user -u conductor@my-app -f
+```
+
+### 複数プロジェクトの場合
+
+プロジェクトごとに install.sh を実行してください:
+
+```bash
+bash install.sh project-a
+bash install.sh project-b /home/user/work/project-b
+```
+
+## node PATH 問題とその対処
+
+### 問題
+
+systemd ユーザーサービスはシェルの PATH を継承しません。既定 PATH は:
+
+```
+/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin
+```
+
+fnm / nvm / volta でインストールした node はこのパス上にないため、
+ユニットの `ExecStart` で `node` が見つからず起動に失敗します。
+`Restart=always` と組み合わさると**無限再起動ループ**になります。
+
+### 対処（install.sh が自動で行う）
+
+install.sh はシェルで使っている node の実体パスを検出し、
+`/usr/local/bin/node` にシンボリックリンクを作成します。
+
+```
+/usr/local/bin/node → /home/user/.local/share/fnm/node-versions/v22.x.x/bin/node
+```
+
+これにより systemd の既定 PATH で node が解決されます。
+
+| node 管理方式 | 検出される実体パス | 対応状況 |
+|--------------|-------------------|----------|
+| fnm | `~/.local/share/fnm/node-versions/vXX/installation/bin/node` | OK |
+| nvm | `~/.nvm/versions/node/vXX/bin/node` | OK |
+| volta | `~/.volta/tools/image/node/XX/bin/node` | OK |
+| apt / システム | `/usr/bin/node` | OK（既に PATH 上にあるが symlink も作成） |
+
+**注意**: node のバージョンを fnm/nvm で切り替えた場合、symlink が旧バージョンを指したままになります。
+その場合は `install.sh` を再実行してください（冪等に動作します）。
+
+## 顧客が用意するもの
+
+| 項目 | 説明 | 例 |
+|------|------|-----|
+| `~/.conductor.env` | 管制サーバへの接続情報 | `CONDUCTOR_URL=https://...` / `CONDUCTOR_SHARED_SECRET=...` |
+| プロジェクト名 | install.sh の第1引数 | `my-app` |
+| プロジェクトディレクトリ | install.sh の第2引数（既定は `~/projects/<名前>`） | `/home/user/work/my-app` |
+| sudo パスワード | symlink 作成時に必要（初回のみ） | — |
+
+## 管理コマンド
+
+```bash
+# 状態確認
+systemctl --user status conductor@my-app
+
+# ログ確認
+journalctl --user -u conductor@my-app -f
+
+# 再起動
+systemctl --user restart conductor@my-app
+
+# 停止（常駐を解除）
+systemctl --user disable --now conductor@my-app
+
+# 完全削除
+systemctl --user disable --now conductor@my-app
+rm ~/.config/systemd/user/conductor@.service
+rm -rf ~/.config/systemd/user/conductor@my-app.service.d
+systemctl --user daemon-reload
+```
+
+## トラブルシューティング
+
+### サービスが起動しない
+
+```bash
+# ログで原因を確認
+journalctl --user -u conductor@my-app --no-pager -n 50
+
+# よくある原因:
+# - node not found → install.sh を再実行
+# - dist/cli.js が無い → cd ~/projects/conductor && npm run build
+# - .conductor.env が無い → 上記の手順で作成
+```
+
+### WSL で systemd が動かない
+
+`/etc/wsl.conf` に以下を追加し、`wsl --shutdown` で再起動:
+
+```ini
+[boot]
+systemd=true
+```