diff --git a/README.md b/README.md
index f0445a5..63b0d9e 100644
--- a/README.md
+++ b/README.md
@@ -58,6 +58,8 @@ cargo install --git https://github.com/codecoradev/cora-code
 
 > Pin a version: `CORA_VERSION=v0.6.1 curl -fsSL ... | sh`
 
+**Upgrading:** run `cora upgrade` (downloads the latest release, verifies its SHA-256 checksum, replaces the binary) or `cora upgrade --check` to just see if one is available. If you installed via `cargo install --path .`, re-run that instead.
+
 **Verify which `cora` you're running** — `which -a cora` will reveal stale copies from other channels:
 
 ```bash
@@ -213,6 +215,7 @@ Works on **all CI platforms** — [Gitea, GitLab, Bitbucket →](https://codecor
 | `cora serve` | Start MCP server + auto-reindex on startup |
 | `cora install` | Auto-detect and configure AI coding agents |
 | `cora hook install` | Install pre-commit hook |
+| `cora upgrade` | Self-upgrade from GitHub Releases (checksum-verified) |
 
 See **[CLI Reference →](https://codecora.dev/cora/docs/cli-reference)** for all flags and examples.
 
diff --git a/docs/cli-reference.md b/docs/cli-reference.md
index c23df1e..a731a2a 100644
--- a/docs/cli-reference.md
+++ b/docs/cli-reference.md
@@ -166,6 +166,19 @@ See [Code Intelligence](./code-intelligence) for detailed usage.
 | `cora mcp` | Start MCP server for AI coding agents (Claude Code, Cursor, Windsurf) |
 | `cora serve` | Start MCP server with auto-reindex on startup |
 
+### Self-Upgrade
+
+| Command | Description |
+|---------|-------------|
+| `cora upgrade --check` | Check for a newer release; no download |
+| `cora upgrade` | Detect OS/arch, download the latest GitHub release asset, verify its SHA-256 checksum, and replace the running binary |
+| `cora upgrade -y` | Same, but skip the confirmation prompt (CI/automation) |
+
+Notes:
+
+- Background update notification: a non-blocking check runs on startup, cached for 24 h at `~/.codecora/cora-code/update-cache.json`. Notices go to stderr only. Disable with the `CORA_NO_UPDATE_CHECK=1` environment variable.
+- If the running binary came from `cargo install --path .`, prefer re-running that instead of `cora upgrade` (the release asset would shadow your source build).
+
 ## Quick Examples
 
 ```bash