docs: add upgrade instructions to installation page (EN+VI+ZH) (#39)

Add "Updating to Latest Version" section covering all 4 installation
paths: binary re-install, bare metal git pull + build, Docker rebuild,
and upgrade overlay. Includes GOCLAW_AUTO_UPGRADE env var docs and
upgrade troubleshooting table.

Author: thieung

getting-started/installation.md

@@ -457,6 +457,84 @@ sudo mkdir -p /backup
 
 ---
 
+## Updating to Latest Version
+
+Already running GoClaw and want to upgrade? Follow the steps for your installation path.
+
+### Path 1: Quick Install (Binary)
+
+Re-run the install script — it downloads the latest release and overwrites the existing binary:
+
+```bash
+curl -fsSL https://raw.githubusercontent.com/nextlevelbuilder/goclaw/main/scripts/install.sh | bash
+```
+
+Then upgrade the database schema:
+
+```bash
+source .env.local && goclaw upgrade
+```
+
+> **Tip:** Run `goclaw upgrade --status` first to check if a schema upgrade is needed, or `goclaw upgrade --dry-run` to preview changes.
+
+### Path 2: Bare Metal
+
+```bash
+cd goclaw
+git pull origin main
+go build -o goclaw .
+./goclaw upgrade
+```
+
+The `goclaw upgrade` command applies pending SQL migrations and runs data hooks. It is safe to run multiple times (idempotent).
+
+### Path 3 & 4: Docker (Local / VPS)
+
+```bash
+cd /path/to/goclaw     # or /opt/goclaw on VPS
+git pull origin main
+docker compose \
+  -f docker-compose.yml \
+  -f docker-compose.postgres.yml \
+  -f docker-compose.selfservice.yml \
+  up -d --build
+```
+
+GoClaw automatically runs pending migrations on startup — no manual `goclaw upgrade` needed.
+
+**Alternative: use the upgrade overlay** for a one-shot database upgrade without restarting the gateway:
+
+```bash
+# Preview changes
+docker compose -f docker-compose.yml -f docker-compose.postgres.yml \
+  -f docker-compose.upgrade.yml run --rm upgrade --dry-run
+
+# Apply upgrade
+docker compose -f docker-compose.yml -f docker-compose.postgres.yml \
+  -f docker-compose.upgrade.yml run --rm upgrade
+```
+
+### Auto-upgrade on Startup
+
+Set the `GOCLAW_AUTO_UPGRADE` environment variable to automatically run migrations when the gateway starts — useful for CI/CD and Docker deployments:
+
+```bash
+# .env or .env.local
+GOCLAW_AUTO_UPGRADE=true
+```
+
+When enabled, GoClaw applies pending SQL migrations and data hooks inline during startup. If you prefer manual control, leave this unset and run `goclaw upgrade` yourself.
+
+### Troubleshooting Upgrades
+
+| Problem | Solution |
+|---------|----------|
+| `database schema is dirty` | A previous migration failed. Run `goclaw migrate force <version-1>` then `goclaw upgrade` |
+| `schema is newer than this binary` | Your binary is older than your database. Update the binary first |
+| `UPGRADE NEEDED` on gateway start | Run `goclaw upgrade` or set `GOCLAW_AUTO_UPGRADE=true` |
+
+---
+
 ## Verify Installation
 
 Works for all three paths:
@@ -491,4 +569,4 @@ docker compose logs goclaw
 - [Quick Start](#quick-start) — Run your first agent
 - [Configuration](#configuration) — Customize GoClaw settings
 
-<!-- goclaw-source: 0bce640 | updated: 2026-03-24 -->
+<!-- goclaw-source: 175e052 | updated: 2026-03-29 -->

vi/getting-started/installation.md

@@ -459,6 +459,84 @@ sudo mkdir -p /backup
 
 ---
 
+## Cập nhật lên phiên bản mới nhất
+
+Đã cài GoClaw rồi và muốn nâng cấp? Làm theo hướng dẫn cho cách cài đặt của bạn.
+
+### Cách 1: Cài nhanh (Binary)
+
+Chạy lại script cài đặt — nó tải bản mới nhất và ghi đè binary cũ:
+
+```bash
+curl -fsSL https://raw.githubusercontent.com/nextlevelbuilder/goclaw/main/scripts/install.sh | bash
+```
+
+Sau đó nâng cấp database schema:
+
+```bash
+source .env.local && goclaw upgrade
+```
+
+> **Mẹo:** Chạy `goclaw upgrade --status` trước để kiểm tra xem có cần nâng cấp schema không, hoặc `goclaw upgrade --dry-run` để xem trước thay đổi.
+
+### Cách 2: Cài trực tiếp
+
+```bash
+cd goclaw
+git pull origin main
+go build -o goclaw .
+./goclaw upgrade
+```
+
+Lệnh `goclaw upgrade` chạy các SQL migration đang chờ và data hooks. An toàn khi chạy nhiều lần (idempotent).
+
+### Cách 3 & 4: Docker (Local / VPS)
+
+```bash
+cd /path/to/goclaw     # hoặc /opt/goclaw trên VPS
+git pull origin main
+docker compose \
+  -f docker-compose.yml \
+  -f docker-compose.postgres.yml \
+  -f docker-compose.selfservice.yml \
+  up -d --build
+```
+
+GoClaw tự động chạy migration đang chờ khi khởi động — không cần chạy `goclaw upgrade` thủ công.
+
+**Cách khác: dùng upgrade overlay** để nâng cấp database một lần mà không cần restart gateway:
+
+```bash
+# Xem trước thay đổi
+docker compose -f docker-compose.yml -f docker-compose.postgres.yml \
+  -f docker-compose.upgrade.yml run --rm upgrade --dry-run
+
+# Chạy nâng cấp
+docker compose -f docker-compose.yml -f docker-compose.postgres.yml \
+  -f docker-compose.upgrade.yml run --rm upgrade
+```
+
+### Tự động nâng cấp khi khởi động
+
+Đặt biến môi trường `GOCLAW_AUTO_UPGRADE` để tự động chạy migration khi gateway khởi động — hữu ích cho CI/CD và Docker:
+
+```bash
+# .env hoặc .env.local
+GOCLAW_AUTO_UPGRADE=true
+```
+
+Khi bật, GoClaw chạy SQL migration và data hooks đang chờ trong quá trình khởi động. Nếu muốn kiểm soát thủ công, không đặt biến này và chạy `goclaw upgrade` riêng.
+
+### Xử lý lỗi khi nâng cấp
+
+| Vấn đề | Giải pháp |
+|--------|-----------|
+| `database schema is dirty` | Migration trước đó thất bại. Chạy `goclaw migrate force <version-1>` rồi `goclaw upgrade` |
+| `schema is newer than this binary` | Binary cũ hơn database. Cập nhật binary trước |
+| `UPGRADE NEEDED` khi khởi động gateway | Chạy `goclaw upgrade` hoặc đặt `GOCLAW_AUTO_UPGRADE=true` |
+
+---
+
 ## Kiểm tra cài đặt
 
 Áp dụng cho cả ba cách:
@@ -493,4 +571,4 @@ docker compose logs goclaw
 - [Quick Start](#quick-start) — Chạy agent đầu tiên của bạn
 - [Configuration](#configuration) — Tùy chỉnh cài đặt GoClaw
 
-<!-- goclaw-source: 0bce640 | cập nhật: 2026-03-24 -->
+<!-- goclaw-source: 175e052 | cập nhật: 2026-03-29 -->

zh/getting-started/installation.md

@@ -459,6 +459,84 @@ sudo mkdir -p /backup
 
 ---
 
+## 更新到最新版本
+
+已经在运行 GoClaw 并想升级？按照你的安装方式执行相应步骤。
+
+### 方式一：快速安装（二进制）
+
+重新运行安装脚本——它会下载最新版本并覆盖现有二进制文件：
+
+```bash
+curl -fsSL https://raw.githubusercontent.com/nextlevelbuilder/goclaw/main/scripts/install.sh | bash
+```
+
+然后升级数据库 schema：
+
+```bash
+source .env.local && goclaw upgrade
+```
+
+> **提示：** 先运行 `goclaw upgrade --status` 检查是否需要升级 schema，或 `goclaw upgrade --dry-run` 预览变更。
+
+### 方式二：裸机安装
+
+```bash
+cd goclaw
+git pull origin main
+go build -o goclaw .
+./goclaw upgrade
+```
+
+`goclaw upgrade` 命令执行待处理的 SQL 迁移和 data hooks。可安全多次运行（幂等）。
+
+### 方式三和四：Docker（本地 / VPS）
+
+```bash
+cd /path/to/goclaw     # VPS 上为 /opt/goclaw
+git pull origin main
+docker compose \
+  -f docker-compose.yml \
+  -f docker-compose.postgres.yml \
+  -f docker-compose.selfservice.yml \
+  up -d --build
+```
+
+GoClaw 启动时自动运行待处理的迁移——无需手动执行 `goclaw upgrade`。
+
+**替代方案：使用 upgrade overlay** 在不重启 gateway 的情况下一次性升级数据库：
+
+```bash
+# 预览变更
+docker compose -f docker-compose.yml -f docker-compose.postgres.yml \
+  -f docker-compose.upgrade.yml run --rm upgrade --dry-run
+
+# 执行升级
+docker compose -f docker-compose.yml -f docker-compose.postgres.yml \
+  -f docker-compose.upgrade.yml run --rm upgrade
+```
+
+### 启动时自动升级
+
+设置 `GOCLAW_AUTO_UPGRADE` 环境变量，在 gateway 启动时自动运行迁移——适用于 CI/CD 和 Docker 部署：
+
+```bash
+# .env 或 .env.local
+GOCLAW_AUTO_UPGRADE=true
+```
+
+启用后，GoClaw 在启动过程中自动执行待处理的 SQL 迁移和 data hooks。如果你希望手动控制，不设置此变量，自行运行 `goclaw upgrade`。
+
+### 升级故障排除
+
+| 问题 | 解决方案 |
+|------|----------|
+| `database schema is dirty` | 之前的迁移失败。运行 `goclaw migrate force <version-1>` 然后 `goclaw upgrade` |
+| `schema is newer than this binary` | 二进制文件比数据库旧，先更新二进制文件 |
+| 启动 gateway 时显示 `UPGRADE NEEDED` | 运行 `goclaw upgrade` 或设置 `GOCLAW_AUTO_UPGRADE=true` |
+
+---
+
 ## 验证安装
 
 适用于所有方式：
@@ -493,4 +571,4 @@ docker compose logs goclaw
 - [快速开始](#quick-start) — 运行你的第一个 agent
 - [配置](#configuration) — 自定义 GoClaw 设置
 
-<!-- goclaw-source: 0bce640 | 更新: 2026-03-24 -->
+<!-- goclaw-source: 175e052 | 更新: 2026-03-29 -->