🚀 START HERE — Cài đặt & vận hành CEO AI OS

Đọc file này ĐẦU TIÊN. Dành cho AI agent / assistant (và người vận hành) khi mở repo này để giúp user cài đặt một instance CEO AI OS.

0. CEO AI OS là gì (1 đoạn)

Một trợ lý AI chạy trên Hermes Agent (self-host, 1 instance/công ty, cả team): năng lực vận hành nền (làm hộ: brief, email, họp, KPI…) + hệ thống persona chuyên gia (AI Mentor dạy AI-BOS, Business Mentor cố vấn KD…). User chat qua Telegram. Chi tiết kiến trúc: README.md, CLAUDE.md, docs/architecture.html (+ docs/structure.html để xem bản đồ thư mục).

1. ⚠️ BƯỚC ĐẦU TIÊN BẮT BUỘC: DEPLOY LÊN VPS

Không có gì chạy được cho tới khi có 1 Hermes instance sống trên VPS. Trình tự:

Bước 1 — dựng nền Hermes (bộ operator/install-hermes-vps/): cài Hermes → config provider LLM → Telegram gateway (systemd 24/7) → GitHub CLI.
Bước 2 — nạp bundle CEO AI OS: symlink SOUL, skills.external_dirs → skills/, terminal.cwd → bundle, nạp personas/* vào agent.personalities, bật content-sync.
Bước 3 — chat-test qua Telegram: user nhắn bot → skill onboarding (chào → hồ sơ → chọn việc).

▶️ Để THỰC THI cài đặt từng bước (có bảng tiến trình + format thông báo ✅/❌/⏳ để user theo dõi): mở INSTALL.md và làm theo. File dưới đây là tổng quan; INSTALL.md là checklist chạy thật.

2. AGENT: làm theo đúng thứ tự này

Đọc hiểu: file này → README.md → AGENTS.md → operator/skills/provision_vps/SKILL.md → operator/install-hermes-vps/README.md + claude-command/install-hermes-vps.md (đọc kỹ bảng "Known Issues").
Tạo .env: cp operator/install-hermes-vps/.env.example operator/install-hermes-vps/.env (file .env đã gitignore). File này chỉ chứa placeholder rỗng → YÊU CẦU USER NHẬP các giá trị (xem bảng §3). KHÔNG tự bịa giá trị.
Cài deps: pip install paramiko (máy operator).
Chạy Bước 1 (lần lượt, kiểm marker mỗi phase): python operator/install-hermes-vps/vps_ssh.py --file operator/install-hermes-vps/scripts/_01_install.sh # DONE_INSTALL python operator/install-hermes-vps/vps_ssh.py --file operator/install-hermes-vps/scripts/_02_config_provider.sh # hermes_ok + DONE_PROVIDER python operator/install-hermes-vps/vps_ssh.py --file operator/install-hermes-vps/scripts/_03_gateway.sh # active + DONE_GATEWAY python operator/install-hermes-vps/vps_ssh.py --file operator/install-hermes-vps/scripts/_04_ghauth.sh # DONE_GHAUTH
Chạy Bước 2 (deploy bundle) — xem operator/skills/deploy_ceo_os/SKILL.md (đang hoàn thiện): clone bundle vào VPS, symlink SOUL, set skills.external_dirs+terminal.cwd, nạp personalities từ personas/.
Test (Bước 3): nhắn bot trên Telegram → kỳ vọng onboarding chạy.

3. 🔑 Credentials USER cần nhập vào `.env`

Agent tạo .env từ .env.example (placeholder rỗng) rồi xin user điền:

Biến	Bắt buộc	User lấy ở đâu
`VPS_IP_ADDRESS`	✅	IP VPS (provider bất kỳ: Contabo, Hetzner, Azure…)
`VPS_USER_NAME`	✅	user SSH (thường `root`)
`VPS_PASSWORD`	✅	mật khẩu SSH
`LLM_BASE_URL`	✅	base URL gateway LLM (OpenAI-compatible, `.../v1`)
`LLM_API_KEY`	✅	key gateway
`LLM_MODEL`	✅	model chạy `/v1/responses` (cho `api_mode: codex_responses`)
`TELEGRAM_BOT_TOKEN`	✅*	token bot riêng cho instance (từ @BotFather)
`TELEGRAM_OWNER_ID`	✅*	numeric user id của user (qua @userinfobot) — bot CHỈ nhận user này
`GITHUB_TOKEN`	tùy	PAT `repo`+`workflow` (để instance tự `git pull` content sau)

* Bắt buộc nếu dùng Telegram (mặc định có).

4. Quy tắc bắt buộc (đúc kết — đừng vi phạm)

Secrets chỉ trong .env; script .sh dùng {{ENV:VAR}} → vps_ssh.py thay trong RAM, không hardcode key.
Windows: luôn --file, KHÔNG inline &&.
Gateway: đã xử lý prompt (printf 'y\ny\n') + chạy root (--system --force --run-as-user root) trong _03.
Allowlist = TELEGRAM_ALLOWED_USERS (không phải _CHATS).
Gateway 400 khi có tools → api_mode: codex_responses.
KHÔNG restart gateway khi agent đang chạy task (drain ~180s).
Người duyệt cuối: bước nhạy cảm (nhập creds, systemd root, restart production) → DỪNG chờ user duyệt.

5. Bản đồ tài liệu

File	Cho ai / nội dung
`START_HERE.md` (đây)	Agent/operator — tổng quan cài đặt
`INSTALL.md`	Playbook agent THỰC THI — checklist + bảng tiến trình + format thông báo
`operator/install-hermes-vps/INSTALL_GUIDE_vi.md`	Bản hướng dẫn người đọc (chi tiết từng bước)
`README.md`	Tổng quan sản phẩm
`CLAUDE.md`	Kiến trúc + quy ước cho Claude khi sửa code
`HANDOFF.md`	Xây dựng sản phẩm (dev tiếp)
`docs/structure.html`	Bản đồ thư mục trực quan
`docs/architecture.html`	Kiến trúc + kế hoạch trực quan
`operator/`	Bộ deploy (install-hermes-vps, skills, playbooks, checklist)