SCHEMA=$(jq -r '."$schema" // empty' "$BUNDLE_PATH" 2>/dev/null)
[[ "$SCHEMA" =~ ^openclaw-workshop-bundle@ ]] \
  || { say "Это не похоже на workshop-bundle от организатора. Проверь, что прислали правильный файл."; stop; }

# Required fields
for f in cloud_id folder_id zone endpoint key; do
  jq -er ".${f}" "$BUNDLE_PATH" >/dev/null \
    || { say "В bundle не хватает поля ${f}. Попроси у организатора новый файл."; stop; }
done

# Wizard-owned profile so we don't disturb the user's other yc setups
yc config profile create openclaw-workshop 2>/dev/null || true
yc config profile activate openclaw-workshop

# Carve the SA key into the shape `yc config set service-account-key` expects
KEY_FILE="$(mktemp -t openclaw-sa-key.XXXXXX.json)"
jq '.key' "$BUNDLE_PATH" > "$KEY_FILE"
chmod 600 "$KEY_FILE"

yc config set service-account-key "$KEY_FILE"
yc config set endpoint            "$(jq -r '.endpoint'  "$BUNDLE_PATH")"
yc config set cloud-id            "$(jq -r '.cloud_id'  "$BUNDLE_PATH")"
yc config set folder-id           "$(jq -r '.folder_id' "$BUNDLE_PATH")"
yc config set compute-default-zone "$(jq -r '.zone'      "$BUNDLE_PATH")"

# Verify it actually works — one read call against the configured folder
yc compute zone list --format json | jq -e '.[] | select(.id=="kz1-a")' >/dev/null \
  || { say "Ключ от организатора не работает (или истёк). Напиши организатору: попроси новый bundle."; stop; }

PROFILE_NAME=openclaw-kz
CURRENT_PROFILE=$(yc config profile list 2>/dev/null | awk '/ACTIVE/{print $1}')

# If the user is already on a profile pointing at KZ, just use it.
if [[ "$CURRENT_PROFILE" != "$PROFILE_NAME" ]]; then
  if [[ "$(yc config get endpoint 2>/dev/null)" != "api.yandexcloud.kz:443" ]]; then
    # Create/activate our own profile rather than mutating the user's active one
    yc config profile list 2>/dev/null | grep -qE "^${PROFILE_NAME}\b" \
      || yc config profile create "$PROFILE_NAME"
    yc config profile activate "$PROFILE_NAME"
  fi
fi

yc config set endpoint api.yandexcloud.kz:443
yc config set compute-default-zone kz1-a

CLOUD_ID=$(yc config get cloud-id 2>/dev/null || true)
if [[ -z "$CLOUD_ID" ]]; then
  CLOUD_ID=$(yc resource-manager cloud list --format json | jq -r '.[0].id // empty')
  [[ -n "$CLOUD_ID" ]] && yc config set cloud-id "$CLOUD_ID"
fi

FOLDER_ID=$(yc config get folder-id 2>/dev/null || true)
if [[ -z "$FOLDER_ID" ]]; then
  FOLDER_ID=$(yc resource-manager folder list --cloud-id "$CLOUD_ID" --format json | jq -r '.[0].id // empty')
  [[ -n "$FOLDER_ID" ]] && yc config set folder-id "$FOLDER_ID"
fi

case "$LLM_INPUT" in
  sk-ant-*)
    LLM_PROVIDER=anthropic ;;
  sk-or-*)
    LLM_PROVIDER=openrouter ;;
  Codex|codex|CODEX|ChatGPT|chatgpt|OpenAI*|"openai codex"|OAuth|oauth)
    LLM_PROVIDER=openai-codex
    LLM_API_KEY=""   # OAuth flow — no key at this stage
    ;;
  *)
    say "Не распознал — это Anthropic-ключ (начинается на sk-ant-), OpenRouter-ключ (sk-or-) или слово 'Codex'?" && reprompt
    ;;
esac

# Telegram token — always validate, confirms format + that the bot actually exists
BOT_USERNAME=$(curl -fsS "https://api.telegram.org/bot${TELEGRAM_BOT_TOKEN}/getMe" \
  | jq -er '.result.username') \
  || (say "Telegram токен не прошёл проверку. Скопируй его ещё раз из @BotFather." && stop)

case "$LLM_PROVIDER" in
  anthropic)
    # Minimal completion call confirms key + at least some credit
    curl -fsS https://api.anthropic.com/v1/messages \
      -H "x-api-key: ${LLM_API_KEY}" \
      -H "anthropic-version: 2023-06-01" \
      -H "content-type: application/json" \
      -d '{"model":"claude-haiku-4-5","max_tokens":1,"messages":[{"role":"user","content":"ok"}]}' \
      | jq -er '.content' >/dev/null \
      || (say "Anthropic ключ не работает или нет кредита. Проверь на console.anthropic.com." && stop)
    ;;
  openrouter)
    # OpenRouter exposes /api/v1/auth/key as a free credit check
    curl -fsS https://openrouter.ai/api/v1/auth/key \
      -H "Authorization: Bearer ${LLM_API_KEY}" \
      | jq -er '.data.usage != null' >/dev/null \
      || (say "OpenRouter ключ не прошёл проверку. Перепроверь на openrouter.ai/keys." && stop)
    # Optional: warn if balance below $1
    BAL=$(curl -fsS https://openrouter.ai/api/v1/auth/key -H "Authorization: Bearer ${LLM_API_KEY}" \
      | jq -r '.data.limit_remaining // 0')
    [[ "$BAL" == "0" ]] && say "На OpenRouter $0 кредита. Бот не сможет отвечать. Пополни на openrouter.ai/credits."
    ;;
  openai-codex)
    # Can't validate before OAuth — defer to Step 4.5 after VM is up.
    # Just confirm the user understands they'll need to do one extra step.
    say "Хорошо, после установки бота на VM покажу 8-символьный код для https://auth.openai.com/codex/device. Это разовое действие."
    ;;
esac

NETWORK_ID=$(yc vpc network get --name default --format json 2>/dev/null | jq -r .id 2>/dev/null)
if [[ -z "$NETWORK_ID" ]]; then
  NETWORK_ID=$(yc vpc network create --name default --format json | jq -r .id)
fi

SUBNET_ID=$(yc vpc subnet get --name default-kz1-a --format json 2>/dev/null | jq -r .id 2>/dev/null)
if [[ -z "$SUBNET_ID" ]]; then
  # Pick a /24 from 10.130.x.x that doesn't collide with the user's other subnets
  SUBNET_ID=$(yc vpc subnet create \
    --name default-kz1-a \
    --network-id "$NETWORK_ID" \
    --zone kz1-a \
    --range 10.130.0.0/24 \
    --format json | jq -r .id)
fi

MY_IP=$(curl -fsS --max-time 5 https://api.ipify.org 2>/dev/null \
  || curl -fsS --max-time 5 https://icanhazip.com 2>/dev/null \
  || echo "")  # empty → fall back to 0.0.0.0/0 (fail2ban catches the rest)

SSH_CIDR="${MY_IP:+${MY_IP}/32}"
SSH_CIDR="${SSH_CIDR:-0.0.0.0/0}"

SG_ID=$(yc vpc security-group create \
  --name "${VM_NAME}-sg" \
  --network-id "$NETWORK_ID" \
  --rule "direction=ingress,port=22,protocol=tcp,v4-cidrs=[${SSH_CIDR}]" \
  --rule "direction=egress,from-port=0,to-port=65535,protocol=any,v4-cidrs=[0.0.0.0/0]" \
  --format json | jq -r .id)

PLATFORM=standard-v3
yc compute instance create \
  --name "${VM_NAME}" \
  --zone kz1-a \
  --platform "$PLATFORM" \
  --cores 2 --memory 4 \
  --network-interface "subnet-id=${SUBNET_ID},nat-ip-version=ipv4,security-group-ids=${SG_ID}" \
  --create-boot-disk "type=network-ssd,size=30,image-folder-id=standard-images,image-family=ubuntu-2404-lts" \
  --ssh-key ~/.ssh/id_ed25519.pub \
  --metadata-from-file user-data=/tmp/openclaw-cloud-init.yaml \
  --hostname "${VM_NAME}" \
  --format json > /tmp/openclaw-vm.json 2>/tmp/openclaw-vm.err

# If v3 not available in this folder, retry with v2.
if grep -qiE "platform.*not.*found|unsupported platform" /tmp/openclaw-vm.err; then
  yc compute instance create --platform standard-v2 ...   # same flags
fi

ssh -o StrictHostKeyChecking=accept-new -o ConnectTimeout=5 openclaw@$IP \
  'test -f /var/lib/openclaw-bootstrap-done && echo READY || echo PENDING'

ssh -tt -o ServerAliveInterval=30 openclaw@$IP \
  "openclaw models auth login --provider openai-codex --device-code" \
  | tee /tmp/openclaw-oauth.log

# Probe what models the user's subscription unlocks
HAS_GPT55=$(ssh openclaw@$IP "openclaw models list --provider openai-codex --format json" \
  | jq -r '.[] | select(.id=="gpt-5.5") | .id // empty')

if [[ "$HAS_GPT55" == "gpt-5.5" ]]; then
  # Pro subscription
  ssh openclaw@$IP "openclaw config set agents.defaults.model.primary 'openai-codex/gpt-5.5' \
    && openclaw config set agents.defaults.model.fallbacks '[\"openai-codex/gpt-4o\"]'"
else
  # Plus subscription — gpt-4o is the best available
  ssh openclaw@$IP "openclaw config set agents.defaults.model.primary 'openai-codex/gpt-4o' \
    && openclaw config set agents.defaults.model.fallbacks '[]'"
fi

ssh openclaw@$IP "systemctl --user restart openclaw-gateway"

# Empty getUpdates returns until the user actually presses /start
for i in $(seq 1 150); do  # 150 × 2s = 5 minutes
  CHAT_ID=$(curl -fsS "https://api.telegram.org/bot${TELEGRAM_BOT_TOKEN}/getUpdates?timeout=2" \
    | jq -r '.result[0].message.chat.id // empty')
  [[ -n "$CHAT_ID" ]] && break
  sleep 2
done
[[ -z "$CHAT_ID" ]] && fail "Пользователь не нажал /start за 5 минут"

# Give the gateway up to 10s to record the pending request after /start arrives
APPROVE_TOKEN=""
for i in $(seq 1 5); do
  APPROVE_TOKEN=$(ssh openclaw@$IP "openclaw pairing list telegram --format json 2>/dev/null" \
    | jq -r --arg cid "$CHAT_ID" '
        .[]
        | select(
            (.senderId|tostring) == $cid
            or (.chatId|tostring) == $cid
            or (.sender // empty | tostring) == $cid
          )
        | (.requestId // .code // empty)
      ' \
    | head -n1)
  [[ -n "$APPROVE_TOKEN" ]] && break
  sleep 2
done

[[ -z "$APPROVE_TOKEN" ]] && fail "Запрос на pairing не появился в openclaw pairing list — посмотри journalctl на VM"

ssh openclaw@$IP "openclaw pairing approve telegram '$APPROVE_TOKEN'" \
  || fail "openclaw pairing approve failed (token=$APPROVE_TOKEN)"

ssh openclaw@$IP "
  openclaw config set channels.telegram.dmPolicy allowlist
  openclaw config set channels.telegram.allowFrom '[${CHAT_ID}]'
  echo 'TELEGRAM_CHAT_ID=${CHAT_ID}' >> /home/openclaw/.openclaw/gateway.env
  systemctl --user restart openclaw-gateway
"

for i in $(seq 1 30); do
  ssh openclaw@$IP 'curl -fsS -m 3 http://127.0.0.1:18789/health' >/dev/null 2>&1 && break
  sleep 2
done

# Language-matched probe text
case "$USER_LANGUAGE" in
  ru) PROBE="Скажи 'привет', чтобы я убедился, что ты отвечаешь." ;;
  kk) PROBE="Сәлем деп жаз — жауап беретіндігіңе көз жеткізейін." ;;
  *)  PROBE="Say 'hi' so I can confirm you're alive." ;;
esac

curl -fsS "https://api.telegram.org/bot${TELEGRAM_BOT_TOKEN}/sendMessage" \
  -d "chat_id=${CHAT_ID}" \
  -d "text=${PROBE}"

ssh openclaw@$IP "
  timeout 90 journalctl --user -u openclaw-gateway -f --no-pager 2>/dev/null \
    | grep -m1 -E 'telegram.*sent|outgoing.*telegram|sendMessage.*ok'
"

LAST_OFFSET=$(curl -fsS "https://api.telegram.org/bot${TELEGRAM_BOT_TOKEN}/getUpdates?offset=-1" \
  | jq -r '.result[-1].update_id // 0')

for i in $(seq 1 45); do
  REPLY=$(curl -fsS "https://api.telegram.org/bot${TELEGRAM_BOT_TOKEN}/getUpdates?offset=$((LAST_OFFSET+1))&timeout=2" \
    | jq -r '.result[]? | select(.message.from.is_bot==true) | .message.text' \
    | head -n1)
  [[ -n "$REPLY" ]] && break
  sleep 2
done

[[ -z "$REPLY" ]] && fail "Не вижу ответа бота в getUpdates через 90с"

LOCALE_PACK="/usr/local/share/openclaw-locale-${USER_LANGUAGE}.md"
ssh openclaw@$IP "
  test -f $LOCALE_PACK && cat $LOCALE_PACK >> ~/.openclaw/workspace/USER.md
  # Trigger session reset so the bot re-reads USER.md
  openclaw sessions reset --channel telegram --to ${CHAT_ID} 2>/dev/null || true
"

OpenClaw запущен в Yandex Cloud Kazakhstan.

  VM           : openclaw-bot  (kz1-a, 2 vCPU / 4 GB / 30 GB SSD)
  IP           : 84.x.x.x
  Бот          : @your_bot_name
  LLM          : <one of three lines below>
  Workspace    : CEO AI OS (48 CEO-скиллов)
  Стоимость    : ~3–5 ₸/час, ~100 ₸/день (VM) + LLM по тарифу провайдера

If the verification ping doesn't get a reply within 60 seconds, run `references/04-troubleshooting.md` §4 silently — don't claim success.

## Auto-recovery (what the wizard does without asking)

These are the things the wizard fixes on its own if it sees them during the run. The user is told only the end result, not the diagnostic steps.

| Detected condition | Silent fix |
|---|---|
| `yc` CLI missing | Install to `$HOME/yandex-cloud/bin`, add to PATH for this session. |
| Active `yc` profile points at RU but user has a KZ cloud | Create/activate a dedicated `openclaw-kz` profile, set token + endpoint + cloud-id + folder-id. Don't touch the user's existing profiles. |
| User opens with "у меня workshop-ключ" but no bundle path | Ask once: "Где лежит файл? Можешь перетащить в чат". Then validate `$schema`. Don't auto-fall-back to Plan A — the user already told us they have a key, asking for OAuth would be wrong. |
| Plan B bundle has `$schema` newer than `openclaw-workshop-bundle@1` | Warn once: "Bundle от организатора новее, чем я умею. Попробую как есть." Try the standard Plan B steps. Surface any `yc` error plainly. |
| Plan B `yc compute zone list` returns empty (key revoked / folder gone) | Tell the user: "Кажется, организатор свернул облако. Напиши ему." Don't retry. |
| Endpoint set to KZ but cloud-id/folder-id are empty or RU-flavoured | Re-resolve via `yc resource-manager cloud list` / `folder list` on the active profile, then `yc config set`. |
| Multiple clouds returned by `cloud list` | Use the first; tell the user one line "использую облако `<NAME>`". |
| `yc vpc network get --name default` returns nothing | Create the default network silently, then create `default-kz1-a` subnet with range `10.130.0.0/24`. |
| Subnet `default-kz1-a` missing | Create it under the (existing or fresh) default network. |
| `--platform standard-v3` rejected as "not supported in folder" | Retry once with `--platform standard-v2`. |
| `--network-name default` silently picks the wrong network | Always use `--network-id`/`--subnet-id` (resolved earlier), never the `-name` variant. |
| `~/.ssh/id_ed25519.pub` missing | Generate a new one with no passphrase. |
| Caller IP can't be detected | Fall back to `0.0.0.0/0` ingress with fail2ban defense (one-line note to user). |
| `npm install -g openclaw` failed once | Retry once after 30 seconds. If still fails, escalate. |
| Gateway `/health` returns non-200 for first 90 seconds | Keep polling — composio plugin can take that long. Only escalate after 4 minutes. |
| Pairing approval returns "code not found" | Wait 3 seconds, re-list pairing requests. Telegram sometimes lags. |
| `openclaw pairing list` returns entries but jq filter on `.chatId` returns empty | The schema field is `.senderId` / `.requestId`, not `.chatId` / `.code`. The wizard's Step 4 uses a defensive filter that tries both — don't simplify it. |
| Bot replies in wrong language after locale pack applied | `cat` the locale pack again over SSH + `openclaw sessions reset --channel telegram --to <CHAT_ID>` to force USER.md re-read. See Step 5c. |
| Bot doesn't reply to verification ping within 30s | Restart adapter once before declaring failure. |

## Yandex Cloud Kazakhstan — common trip points (read before debugging)

If anything fails during the wizard run, check these first — most YC KZ issues come from one of these five mistakes:

1. **Endpoint vs cloud-id mismatch.** Setting `endpoint=api.yandexcloud.kz:443` does NOT auto-update `cloud-id` or `folder-id`. If you only flip the endpoint, every subsequent `yc compute / vpc / resource-manager` call sees an empty result because it's looking up RU IDs against the KZ realm. **Always update all three together** — endpoint, cloud-id, folder-id — or use a separate profile.
2. **`yc billing` doesn't exist on KZ endpoint.** Calling `yc billing account list` errors with `Unknown command 'billing account list'`. Don't use it for any pre-flight check. Detect billing problems from the actual `yc compute instance create` error message, not by trying to list accounts.
3. **`yc resource-manager cloud list` returning empty.** When the OAuth token doesn't match the realm (RU token on KZ endpoint, or vice versa), the call succeeds with an empty array — not an auth error. If empty, the answer is "wrong token", not "no cloud".
4. **`--network-name default` lookup is fragile.** When the folder has multiple networks (common after the user experiments), the named lookup can pick the wrong one or fail silently. Always resolve to a network-id first (`yc vpc network get --name default`) and pass `--network-id` to subsequent commands.
5. **Subnet not auto-provisioned.** Default subnet `default-kz1-a` is created with the default network in most cases, but not all. New empty folders sometimes lack it. Always check before referencing it in instance create.

## Failure modes (when the silent fixes aren't enough)

| Symptom | Where to look |
|---|---|
| `yc compute zone list` returns `ru-central1-*` or empty after the wizard's profile setup | `references/04-troubleshooting.md` §1a — endpoint still RU |
| `yc resource-manager cloud list` returns `[]` even though the cloud is visible in https://kz.console.yandex.cloud | `references/04-troubleshooting.md` §1b — cloud-id/folder-id still RU, or §1c — OAuth token from wrong realm |
| `yc compute instance create` errors with `billing account is not active` | `references/04-troubleshooting.md` §1d — billing genuinely missing |
| `yc compute instance create` errors with `quota_exceeded` | `references/01-prerequisites.md` §5 |
| `yc compute instance create` errors with `platform … not supported` | Already handled by auto-recovery (retry with `standard-v2`). If it still fails, `references/04-troubleshooting.md` §2 |
| Cloud-init log shows `npm install -g openclaw` failed twice | `references/04-troubleshooting.md` §2 |
| `openclaw gateway status` shows `RPC probe: failed` after 4 min | `references/04-troubleshooting.md` §3 |
| User pressed `/start` but `getUpdates` returns no chat | `references/04-troubleshooting.md` §4a-b |
| Bot pairs but doesn't reply | `references/04-troubleshooting.md` §4c-e (key, credit, model) |
| SSH `Permission denied (publickey)` | `references/04-troubleshooting.md` §5 |

For everything else: dump `/var/log/openclaw-bootstrap.log` and `journalctl --user -u openclaw-gateway -n 200` from the VM, surface to the user as "вот что я вижу, давай разбираться", do not guess.

## References

- `references/01-prerequisites.md` — yc CLI install, KZ endpoint init, SSH key, billing checks (most are silent now; only OAuth login and missing billing surface to the user)
- `references/02-network-and-security.md` — security-group rules, public-IP rationale, hardening choices
- `references/03-openclaw-config.md` — Telegram pairing flow, Anthropic auth, workspace seeding
- `references/04-troubleshooting.md` — 7 failure modes with copy-paste fixes
- `references/05-workshop-key-mode.md` — Plan B (workshop bundle) end-to-end: schema check, profile carve-out, what NOT to do, organizer hand-off
- `scripts/cloud-init.yaml` — the full VM bootstrap (Node, OpenClaw, hardening, ceo-ai-os workspace, systemd user service)

## Companion skills

| Skill | Required? | Role |
|---|---|---|
| `openclaw-guide` | **required** | Loaded by Step 0a; owns all post-install consultation (channels, use cases, debugging). |
| `openclaw-user-onboarding` | recommended | Auto-invoked at Step 5.5 to collect five user facts and write USER.md. If missing, Step 5.5 falls back to a placeholder USER.md and surfaces "поставь openclaw-user-onboarding и скажи 'онбординг'" in the final summary. |
| `prepare-yc-workshop` | organizer-only | Matching organizer-side skill that produces the bundle files consumed by this skill's Plan B. Participants don't need it. |

### About `openclaw-guide` (required)

`openclaw-guide` (sibling) — **must be installed alongside this one**. The wizard refuses to start without it loaded. Two reasons:

1. **During install** — if cloud-init logs surface something this skill doesn't know about, the agent reads `openclaw-guide/references/06-troubleshooting.md` instead of guessing.
2. **After install** — when the user asks "how do I add Slack?", "how do I make the bot wake me up at 8am?", "what skills should I install?", the agent reads `openclaw-guide/references/use-cases.md` and `openclaw-guide/references/channels.md` to advise. This wizard is silent after Step 5; the guide owns ongoing consultation.

Joint install:

```bash
npx skills add CodeAlive-AI/ceo-ai-os@install-openclaw-to-yc -g
npx skills add CodeAlive-AI/ceo-ai-os@openclaw-guide -g

npx skills add CodeAlive-AI/ceo-ai-os@<skill-name> -g