From 60637d0f53612a118920dc7ca1d99bdc58e7d081 Mon Sep 17 00:00:00 2001
From: ajianaz <ajianaz@users.noreply.github.com>
Date: Mon, 31 Aug 2026 11:36:01 +0700
Subject: [PATCH] =?UTF-8?q?docs(cli):=20document=20cora=20upgrade=20?=
 =?UTF-8?q?=E2=80=94=20self-upgrade=20was=20undocumented?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Add a Self-Upgrade section to docs/cli-reference.md (--check, default
flow with SHA-256 checksum verification, -y for CI), a README install/
upgrade note and a command-table row, per #541.

Correction vs the issue body: the background update check is disabled
via the CORA_NO_UPDATE_CHECK=1 environment variable — no
--no-update-check flag exists.

Closes #541
---
 README.md             |  3 +++
 docs/cli-reference.md | 13 +++++++++++++
 2 files changed, 16 insertions(+)

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