nextlevelbuilder · thieung · May 2, 2026 · Apr 29, 2026
diff --git a/deployment/upgrading.md b/deployment/upgrading.md
@@ -9,7 +9,7 @@ A GoClaw upgrade has two parts:
 1. **SQL migrations** — schema changes applied by `golang-migrate` (idempotent, versioned)
 2. **Data hooks** — optional Go-based data transformations that run after schema migrations (e.g. backfilling a new column)
 
-The `./goclaw upgrade` command handles both in the correct order. It is safe to run multiple times — it is fully idempotent. The current required schema version is **56**.
+The `./goclaw upgrade` command handles both in the correct order. It is safe to run multiple times — it is fully idempotent. The current required schema version is **57**.
 
 ```mermaid
 graph LR
@@ -210,6 +210,19 @@ Only do this if you understand what the failed migration was doing. When in doub
 
 ### v3.11.x — Highlights and Breaking Changes
 
+#### v3.11.3
+
+- fix(migrations): `000057_heartbeat_provider_fk_set_null` — defensive orphan cleanup; drops existing FK by constraint-name lookup (handles auto-generated name drift), re-adds with `ON DELETE SET NULL`. Brief `ACCESS EXCLUSIVE` lock on `agent_heartbeats` during `ALTER TABLE` (sub-second on small tables; heartbeat workers may pause briefly).
+- SQLite: schema v25 → v26 — full table rebuild for `agent_heartbeats` with updated FK clause; explicit 25-column `INSERT … SELECT` preserves all existing rows. `idx_heartbeats_due` recreated.
+
+**Docker users:** MUST pull `ghcr.io/nextlevelbuilder/goclaw:v3.11.3` AND run `goclaw upgrade`. A stale v3.11.2 image fails on boot with:
+
+```
+schema version mismatch: required 57, current 56
+```
+
+**Bare-metal users:** rebuild binary and run `./goclaw upgrade`.
+
 #### v3.11.2
 
 - fix(migrations): drop scope-consistency check before backfill UPDATEs — migration #56 follow-up; prevents constraint errors when backfilling over legacy data
@@ -359,4 +372,4 @@ Before each upgrade, check the release notes for:
 - [Database Setup](/deploy-database) — PostgreSQL and pgvector setup
 - [Observability](/deploy-observability) — monitor your gateway post-upgrade
 
-<!-- goclaw-source: 29457bb3 | updated: 2026-04-25 -->
+<!-- goclaw-source: 364d2d34 | updated: 2026-04-29 -->
diff --git a/reference/api-endpoints-catalog.md b/reference/api-endpoints-catalog.md
@@ -2,7 +2,7 @@
 
 > Auto-generated complete index of all REST endpoints. For request/response details, examples, and authentication, see [REST API Reference](rest-api.md).
 
-**Total endpoints:** 260 — generated from goclaw `29457bb3` on `2026-04-25`.
+**Total endpoints:** 260 — generated from goclaw `364d2d34` on `2026-04-29`.
 
 ## How to use this page
 
@@ -460,6 +460,6 @@
 
 ---
 
-<!-- goclaw-source: 29457bb3 -->
-<!-- last-updated: 2026-04-25 -->
+<!-- goclaw-source: 364d2d34 -->
+<!-- last-updated: 2026-04-29 -->
 <!-- total-endpoints: 260 -->
diff --git a/reference/cli-commands.md b/reference/cli-commands.md
@@ -286,6 +286,8 @@ goclaw doctor
 
 Checks: binary version, config file, database connectivity, schema version, providers, channels, external binaries (docker, curl, git), workspace directory. Prints a pass/fail summary for each check.
 
+Provider rows with an empty `display_name` now render the canonical `name` instead of a blank line.
+
 ---
 
 ## `pairing`
@@ -449,18 +451,71 @@ Output columns: `CHANNEL`, `ENABLED`, `CREDENTIALS` (ok/missing).
 
 ## `providers`
 
-List configured LLM providers and their status.
+Manage LLM providers (requires running gateway).
+
+### `providers list`
+
+List configured providers.
 
 ```bash
 goclaw providers list
 goclaw providers list --json
+goclaw providers list --models
 ```
 
 | Flag | Description |
 |------|-------------|
 | `--json` | Output as JSON |
+| `--models` | Also show available models per provider |
+
+Shows provider name, type, enabled status, and whether an API key is configured.
+
+### `providers add`
+
+Add a new provider (interactive).
+
+```bash
+goclaw providers add
+```
+
+Interactive prompts for provider type, name, API key, and base URL. Offers to verify connectivity after creation.
+
+### `providers update <id>`
+
+Update a provider's name or API key.
+
+```bash
+goclaw providers update <id>
+```
+
+### `providers delete <id>`
+
+Delete a provider.
+
+```bash
+goclaw providers delete <id>
+goclaw providers delete <id> --force
+```
+
+| Flag | Description |
+|------|-------------|
+| `--force` | Skip confirmation prompt |
+
+### `providers verify <id>`
+
+Verify provider connectivity or a specific model.
+
+```bash
+goclaw providers verify <id>
+goclaw providers verify <id> --model anthropic/claude-sonnet-4
+```
+
+| Flag | Description |
+|------|-------------|
+| `--model <alias>` | Model alias to verify (omit for connectivity ping) |
 
-Shows provider name, type, default model, and whether an API key is configured.
+Without `--model`: pings the provider (registered + reachable check) — no LLM call is made.
+With `--model`: sends a small chat request to validate the model alias.
 
 ---
 
@@ -597,4 +652,4 @@ goclaw tui setup     # TUI-based setup wizard
 - [REST API](/rest-api) — HTTP API endpoint listing
 - [Config Reference](/config-reference) — full `config.json` schema
 
-<!-- goclaw-source: 050aafc9 | updated: 2026-04-09 -->
+<!-- goclaw-source: 364d2d34 | updated: 2026-04-29 -->
diff --git a/reference/database-schema.md b/reference/database-schema.md
@@ -13,7 +13,7 @@ CREATE EXTENSION IF NOT EXISTS "vector";    -- pgvector for embeddings
 
 A custom `uuid_generate_v7()` function provides time-ordered UUIDs. All primary keys use this function by default.
 
-Schema versions are tracked by `golang-migrate`. Run `goclaw migrate up` or `goclaw upgrade` to apply all migrations. Current schema version: **56**.
+Schema versions are tracked by `golang-migrate`. Run `goclaw migrate up` or `goclaw upgrade` to apply all migrations. Current schema version: **57**.
 
 ### v3 Store Unification
 
@@ -885,7 +885,7 @@ Per-agent heartbeat configuration for periodic proactive check-ins. (migration 0
 | `enabled` | BOOLEAN | NOT NULL DEFAULT false | Whether heartbeat is active |
 | `interval_sec` | INT | NOT NULL DEFAULT 1800 | Run interval in seconds |
 | `prompt` | TEXT | | Message sent to the agent each heartbeat |
-| `provider_id` | UUID FK → llm_providers (nullable) | | Override LLM provider |
+| `provider_id` | UUID FK → llm_providers (nullable) | ON DELETE SET NULL (migration 057) | Override LLM provider; set to NULL if provider is deleted |
 | `model` | VARCHAR(200) | | Override model |
 | `isolated_session` | BOOLEAN | NOT NULL DEFAULT true | Run in a dedicated session |
 | `light_context` | BOOLEAN | NOT NULL DEFAULT false | Inject minimal context |
@@ -1032,6 +1032,7 @@ Centralized key-value store for per-tenant system settings. Falls back to master
 | 54 | Adds `name VARCHAR(255)` column to `agent_hooks`; creates `agent_hook_agents` N:M junction table; migrates existing `agent_id` FK to junction; renames `agent_hooks` → `hooks` and `agent_hook_agents` → `hook_agents`; drops deprecated `agent_id` column from `hooks` |
 | 55 | Adds `vault_documents_scope_consistency` CHECK constraint (NOT VALID) on `vault_documents` enforcing scope/agent_id/team_id coherence: `personal` requires `agent_id NOT NULL`, `team` requires `team_id NOT NULL`, `shared` requires both NULL, `custom` is unconstrained |
 | 56 | `vault_chat_id` — adds `chat_id TEXT NULL` column to `vault_documents` and index `(tenant_id, chat_id, agent_id)` for chat-scoped vault isolation. Migration 056 follow-up (v3.11.2): drops scope-consistency check before backfill UPDATEs to prevent constraint errors on legacy data |
+| 57 | `heartbeat_provider_fk_set_null` (PG) — defensive orphan cleanup, drops existing FK by constraint-name lookup, re-adds as `agent_heartbeats_provider_id_fkey` with `ON DELETE SET NULL`. Brief `ACCESS EXCLUSIVE` lock on `agent_heartbeats` during ALTER (sub-second on small tables). SQLite: schema v25 → v26, full table rebuild for `agent_heartbeats` with updated FK clause; 25-column `INSERT … SELECT` preserves existing rows; `idx_heartbeats_due` recreated. |
 
 ---
 
@@ -1397,4 +1398,4 @@ Per-tenant monthly prompt-handler token/cost budget. One row per tenant tracks m
 - [Config Reference](/config-reference) — how database config maps to `config.json`
 - [Glossary](/glossary) — Session, Compaction, Lane, and other key terms
 
-<!-- goclaw-source: 29457bb3 | updated: 2026-04-25 -->
+<!-- goclaw-source: 364d2d34 | updated: 2026-04-29 -->
diff --git a/reference/rest-api.md b/reference/rest-api.md
@@ -356,7 +356,25 @@ List models available from the provider (proxied to the upstream API).
 
 ### `POST /v1/providers/{id}/verify`
 
-Pre-flight check — verify the API key and model are reachable.
+Verify provider connectivity or a specific model. Request body is optional (`requestBody.required: false`).
+
+**Ping mode** — omit body (or send `{}`). Returns `{"valid": true}` if the provider is registered and reachable. Equivalent to a `/healthz` check; no LLM call is made.
+
+```bash
+curl -X POST http://localhost:18790/v1/providers/{id}/verify \
+  -H "Authorization: Bearer TOKEN"
+```
+
+**Chat-verify mode** — include `model` to perform an actual chat completion against a specific model alias.
+
+```bash
+curl -X POST http://localhost:18790/v1/providers/{id}/verify \
+  -H "Authorization: Bearer TOKEN" \
+  -H "Content-Type: application/json" \
+  -d '{"model": "anthropic/claude-sonnet-4"}'
+```
+
+**Response shape** — `{"valid": true}` on success, `{"valid": false, "error": "<msg>"}` on failure. The legacy `{success, models}` shape is no longer returned.
 
 ### `POST /v1/providers/{id}/verify-embedding`
 
@@ -1603,4 +1621,4 @@ The following are **only available via WebSocket RPC**, not HTTP:
 - [Config Reference](/config-reference) — full `config.json` schema
 - [Database Schema](/database-schema) — table definitions and relationships
 
-<!-- goclaw-source: 29457bb3 | updated: 2026-04-25 -->
+<!-- goclaw-source: 364d2d34 | updated: 2026-04-29 -->
diff --git a/troubleshooting/database.md b/troubleshooting/database.md
@@ -214,10 +214,14 @@ To check whether your build uses SQLite:
 # SQLite builds will show: storage=sqlite
 ```
 
+## Migration #057 — Heartbeat FK Lock Note
+
+Migration `000057_heartbeat_provider_fk_set_null` drops the existing `RESTRICT` foreign key on `agent_heartbeats.provider_id` and re-adds it with `ON DELETE SET NULL`. The `ALTER TABLE` takes a brief `ACCESS EXCLUSIVE` lock on `agent_heartbeats` during this change. On typical tables the lock is sub-second, but heartbeat workers may pause momentarily while it is held. If you have a very large `agent_heartbeats` table, plan the upgrade window accordingly and monitor for lock-wait timeouts.
+
 ## What's Next
 
 - [Common Issues](/troubleshoot-common)
 - [Provider issues](/troubleshoot-providers)
 - [Channel issues](/troubleshoot-channels)
 
-<!-- goclaw-source: 050aafc9 | updated: 2026-04-09 -->
+<!-- goclaw-source: 364d2d34 | updated: 2026-04-29 -->
diff --git a/troubleshooting/providers.md b/troubleshooting/providers.md
@@ -141,10 +141,28 @@ GoClaw v3 introduces a unified `SSEScanner` (`providers/sse_reader.go`) shared b
 
 Provider credentials added at runtime (dashboard) are stored in `llm_providers` with AES-256-GCM encryption and resolved at request time via the credential resolver. Per-agent overrides in agent config take precedence over global provider settings.
 
+## Provider Creation Prints "FAILED" but It Actually Succeeded
+
+**Affected versions:** < v3.11.3
+
+The onboard auto-verify path used the stale `{success, models}` response shape to check whether a newly created provider was valid. The provider was created correctly in the database, but the post-create verify step read the wrong fields and printed `FAILED` to the console even when the provider was healthy.
+
+**Fix in v3.11.3:** The verify path now uses the `{valid, error}` response shape and triggers ping mode when the request body is empty, so an empty-body verify returns `{valid:true}` on success. Upgrade to v3.11.3+ to resolve this.
+
+## `goclaw providers delete` Fails with Foreign Key Error on `agent_heartbeats`
+
+**Affected versions:** < v3.11.3
+
+Before v3.11.3, the foreign key from `agent_heartbeats` to `llm_providers` was defined as `RESTRICT`. Deleting a provider that was referenced by any heartbeat row would fail with a foreign key constraint error.
+
+**Fix in v3.11.3:** Migration `000057_heartbeat_provider_fk_set_null` changes the FK to `ON DELETE SET NULL`. The `DeleteProvider` function (PostgreSQL and SQLite) now wraps the delete in a transaction that first disables all affected heartbeat rows, so the next scheduler tick cannot fire with a stale provider config. A `slog.Warn("heartbeat.provider_cleared")` log line is emitted with the count of disabled heartbeats.
+
+Requires migration #057 to be applied (`./goclaw migrate up`). Check logs for `heartbeat.provider_cleared` after deletion to confirm how many heartbeats were cleared.
+
 ## What's Next
 
 - [Database issues](/troubleshoot-database)
 - [Common Issues](/troubleshoot-common)
 - [Channel issues](/troubleshoot-channels)
 
-<!-- goclaw-source: 050aafc9 | updated: 2026-04-09 -->
+<!-- goclaw-source: 364d2d34 | updated: 2026-04-29 -->
diff --git a/vi/deployment/upgrading.md b/vi/deployment/upgrading.md
@@ -11,7 +11,7 @@ Một lần upgrade GoClaw có hai phần:
 1. **SQL migrations** — thay đổi schema áp dụng bởi `golang-migrate` (idempotent, có phiên bản)
 2. **Data hooks** — Go-based data transformation tùy chọn chạy sau schema migrations (ví dụ backfill cột mới)
 
-Lệnh `./goclaw upgrade` xử lý cả hai theo đúng thứ tự. An toàn khi chạy nhiều lần — hoàn toàn idempotent. Phiên bản schema hiện tại yêu cầu là **56**.
+Lệnh `./goclaw upgrade` xử lý cả hai theo đúng thứ tự. An toàn khi chạy nhiều lần — hoàn toàn idempotent. Phiên bản schema hiện tại yêu cầu là **57**.
 
 ```mermaid
 graph LR
@@ -212,6 +212,19 @@ Chỉ làm điều này nếu bạn hiểu migration lỗi đã làm gì. Khi kh
 
 ### v3.11.x — Highlights và Breaking Changes
 
+#### v3.11.3
+
+- fix(migrations): `000057_heartbeat_provider_fk_set_null` — dọn sạch orphan phòng thủ; drop FK hiện có bằng cách tra tên constraint (xử lý tên tự sinh bị lệch), thêm lại với `ON DELETE SET NULL`. Khóa `ACCESS EXCLUSIVE` ngắn trên `agent_heartbeats` trong `ALTER TABLE` (dưới một giây với bảng nhỏ; heartbeat worker có thể tạm dừng ngắn).
+- SQLite: schema v25 → v26 — rebuild toàn bộ bảng `agent_heartbeats` với mệnh đề FK mới; `INSERT … SELECT` tường minh 25 cột giữ nguyên toàn bộ dữ liệu hiện có. `idx_heartbeats_due` được tạo lại.
+
+**Docker users:** BẮT BUỘC pull `ghcr.io/nextlevelbuilder/goclaw:v3.11.3` VÀ chạy `goclaw upgrade`. Image v3.11.2 cũ sẽ lỗi khi khởi động với:
+
+```
+schema version mismatch: required 57, current 56
+```
+
+**Bare-metal users:** rebuild binary và chạy `./goclaw upgrade`.
+
 #### v3.11.2
 
 - fix(migrations): drop scope-consistency check trước backfill UPDATEs — migration #56 follow-up; tránh lỗi constraint khi backfill trên data cũ
@@ -360,4 +373,4 @@ Trước mỗi lần upgrade, kiểm tra release notes về:
 - [Database Setup](/deploy-database) — cài đặt PostgreSQL và pgvector
 - [Observability](/deploy-observability) — theo dõi gateway sau khi upgrade
 
-<!-- goclaw-source: 29457bb3 | cập nhật: 2026-04-25 -->
+<!-- goclaw-source: 364d2d34 | cập nhật: 2026-04-29 -->
diff --git a/vi/reference/api-endpoints-catalog.md b/vi/reference/api-endpoints-catalog.md
@@ -2,7 +2,7 @@
 
 > Danh sách auto-gen đầy đủ tất cả REST endpoint. Để xem chi tiết request/response, ví dụ và xác thực, xem [REST API Reference](rest-api.md).
 
-**Total endpoints:** 260 — generated from goclaw `29457bb3` on `2026-04-25`.
+**Total endpoints:** 260 — generated from goclaw `364d2d34` on `2026-04-29`.
 
 ## Cách sử dụng trang này
 
@@ -460,6 +460,6 @@
 
 ---
 
-<!-- goclaw-source: 29457bb3 -->
-<!-- last-updated: 2026-04-25 -->
+<!-- goclaw-source: 364d2d34 -->
+<!-- last-updated: 2026-04-29 -->
 <!-- total-endpoints: 260 -->
diff --git a/vi/reference/cli-commands.md b/vi/reference/cli-commands.md
@@ -288,6 +288,8 @@ goclaw doctor
 
 Kiểm tra: phiên bản binary, config file, kết nối database, phiên bản schema, providers, channels, binary bên ngoài (docker, curl, git), thư mục workspace. In tóm tắt pass/fail cho mỗi mục kiểm tra.
 
+Provider có `display_name` rỗng nay hiển thị `name` chính thức thay vì dòng trống.
+
 ---
 
 ## `pairing`
@@ -451,18 +453,71 @@ Các cột output: `CHANNEL`, `ENABLED`, `CREDENTIALS` (ok/missing).
 
 ## `providers`
 
-Liệt kê LLM provider đã cấu hình và trạng thái.
+Quản lý LLM provider (yêu cầu gateway đang chạy).
+
+### `providers list`
+
+Liệt kê provider đã cấu hình.
 
 ```bash
 goclaw providers list
 goclaw providers list --json
+goclaw providers list --models
 ```
 
 | Flag | Mô tả |
 |------|-------|
 | `--json` | Output dạng JSON |
+| `--models` | Hiển thị thêm model khả dụng của mỗi provider |
+
+Hiển thị tên provider, loại, trạng thái enabled, và trạng thái API key.
+
+### `providers add`
+
+Thêm provider mới (tương tác).
+
+```bash
+goclaw providers add
+```
+
+Nhập tương tác: loại provider, tên, API key, base URL. Hỏi xác minh kết nối sau khi tạo.
+
+### `providers update <id>`
+
+Cập nhật tên hoặc API key của provider.
+
+```bash
+goclaw providers update <id>
+```
+
+### `providers delete <id>`
+
+Xóa provider.
+
+```bash
+goclaw providers delete <id>
+goclaw providers delete <id> --force
+```
+
+| Flag | Mô tả |
+|------|-------|
+| `--force` | Bỏ qua xác nhận |
+
+### `providers verify <id>`
+
+Xác minh kết nối provider hoặc một model cụ thể.
+
+```bash
+goclaw providers verify <id>
+goclaw providers verify <id> --model anthropic/claude-sonnet-4
+```
+
+| Flag | Mô tả |
+|------|-------|
+| `--model <alias>` | Model alias cần xác minh (bỏ qua để ping kết nối) |
 
-Hiển thị tên provider, loại, model mặc định, và trạng thái API key.
+Không có `--model`: ping provider (kiểm tra đã đăng ký và có thể kết nối) — không thực hiện LLM call.
+Có `--model`: gửi chat request nhỏ để xác minh model alias.
 
 ---
 
@@ -599,4 +654,4 @@ goclaw tui setup     # wizard setup dạng TUI
 - [REST API](/rest-api) — danh sách HTTP API endpoint
 - [Config Reference](/config-reference) — schema đầy đủ `config.json`
 
-<!-- goclaw-source: 050aafc9 | updated: 2026-04-09 -->
+<!-- goclaw-source: 364d2d34 | updated: 2026-04-29 -->