feat(cli): add self-update mechanism (MR-612)

- New `omnigraph update` subcommand: GitHub Releases API → archive download
  → SHA256 verification → atomic POSIX rename of both binaries.
- Detects Homebrew installs and short-circuits with a hint to run
  `brew upgrade ModernRelay/tap/omnigraph`.
- Channels: `--channel stable` (default) or `edge`. `--check` for
  check-only, `--yes` to skip the confirmation prompt.
- Best-effort startup version check (24h cached at
  `~/.cache/omnigraph/update-check.json`) with one-line stderr notice.
  Cache is refreshed via a detached `__refresh-update-cache` subprocess so
  the foreground command never blocks on the network. Suppression: CI,
  `OMNIGRAPH_NO_UPDATE_CHECK=1`, non-TTY stdout, and `version`/`update`
  subcommands.
- Integration tests use an in-process raw-TCP HTTP fixture (no extra
  dev-deps) and override `OMNIGRAPH_UPDATE_API_BASE` /
  `OMNIGRAPH_UPDATE_DOWNLOAD_BASE` to keep the suite hermetic.
- Docs: `install.md`, `cli.md`, `cli-reference.md` updated.

Co-Authored-By: Ragnor Comerford <ragnor.comerford@gmail.com>

docs/cli-reference.md

@@ -24,6 +24,7 @@ A reference for the `omnigraph` binary's command surface and `omnigraph.yaml` sc
 | `cleanup --keep N --older-than 7d --confirm` | destructive version GC |
 | `embed` | offline JSONL embedding pipeline |
 | `policy validate \| test \| explain` | Cedar tooling |
+| `update` | self-update both binaries from GitHub Releases (`--channel stable\|edge`, `--check`, `--yes`) |
 | `version` / `-v` | print `omnigraph 0.3.x` |
 
 ## `omnigraph.yaml` schema

docs/cli.md

@@ -98,3 +98,20 @@ The config file can also define:
 
 When policy is enabled, `schema apply` is authorized through the
 `schema_apply` action and is typically limited to admins on protected `main`.
+
+## Updating
+
+Update both binaries in place from the latest GitHub Release:
+
+```bash
+omnigraph update              # default: stable channel, prompts for confirmation
+omnigraph update --check      # only check; do not install
+omnigraph update --yes        # skip prompt
+omnigraph update --channel edge
+```
+
+Homebrew installs are detected and short-circuited with a hint to run
+`brew upgrade ModernRelay/tap/omnigraph` instead. Each invocation of
+`omnigraph` also performs a best-effort cached check (24-hour TTL) for newer
+releases and prints a one-line stderr notice; suppress with
+`OMNIGRAPH_NO_UPDATE_CHECK=1`. Full details: [install.md](install.md).

docs/install.md

@@ -92,3 +92,35 @@ Each archive contains both binaries:
 omnigraph version
 omnigraph-server --help
 ```
+
+## Updating
+
+After installing via the script (or a manual binary install) you can update both
+`omnigraph` and `omnigraph-server` in place:
+
+```bash
+omnigraph update            # update from the latest stable release
+omnigraph update --check    # only check for a newer version
+omnigraph update --yes      # skip the confirmation prompt
+omnigraph update --channel edge  # follow the rolling `edge` channel
+```
+
+`omnigraph update`:
+
+- detects the platform automatically (Linux x86_64 / macOS arm64),
+- downloads the matching `omnigraph-<platform>.tar.gz` and `.sha256`,
+- verifies the SHA256 digest before touching anything,
+- replaces both binaries in the install directory atomically (POSIX rename), and
+- detects Homebrew installs and asks you to run `brew upgrade ModernRelay/tap/omnigraph` instead.
+
+Each invocation of `omnigraph` also performs a best-effort, cached check
+(once every 24 hours) for newer stable releases and prints a one-line stderr
+notice if one is available. The notice is suppressed when:
+
+- `OMNIGRAPH_NO_UPDATE_CHECK=1` is set,
+- `CI` is set,
+- stdout is not a TTY (pipes, scripts), or
+- the running subcommand is `version` or `update`.
+
+The cache lives at `$XDG_CACHE_HOME/omnigraph/update-check.json` (default
+`~/.cache/omnigraph/update-check.json`).