diff --git a/Installation.md b/Installation.md
index 7edf3a2..95acae7 100644
--- a/Installation.md
+++ b/Installation.md
@@ -81,6 +81,63 @@ To use a binary from the releases page on Linux/MacOS, do the following:
 3. Extract the binary with `tar -C /usr/local/bin -xzf loki-<arch>.tar.gz` (Note: This may require `sudo`)
 4. Now you can run `loki`!
 
+# Updating Loki
+
+Loki can update itself in place. Running:
+
+```shell
+loki --update
+```
+
+downloads the latest release from GitHub for your operating system and
+architecture, replaces the running `loki` binary, and reports the new version.
+Restart Loki afterwards for the update to take effect.
+
+To update to a specific release instead of the latest, pass a version. Either pass
+the bare version or the `v`-prefixed tag:
+
+```shell
+loki --update v0.4.0
+# or
+loki --update 0.4.0
+```
+
+If Loki is already on the requested version, it reports that and makes no
+changes.
+
+## Package-manager installs
+
+If Loki was installed with Homebrew or `cargo install`, replacing the binary in
+place would leave your package manager's records out of sync with the file on
+disk. When `loki --update` detects one of these installs it prints a warning
+and:
+
+* in an interactive terminal, asks for confirmation before continuing;
+* in a non-interactive context (such as a script), refuses unless `--force` is
+  passed.
+
+```shell
+loki --update --force
+```
+
+For Homebrew and Cargo installs the recommended way to update remains your
+package manager:
+
+```shell
+brew upgrade loki                  # Homebrew
+cargo install --locked loki-ai     # Cargo
+```
+
+## Permissions
+
+`loki --update` replaces the binary at its current location. If that directory
+is not writable by your user (for example a `loki` placed in `/usr/local/bin`
+by `root`), the update stops before downloading anything and asks you to re-run
+with elevated permissions (e.g. with `sudo`) or to update through your package
+manager.
+
+Loki can also be updated from within the REPL using the
+[`.update` command](REPL).
 
 # Tab-Completions
 You can also enable tab completions to make using Loki easier. To do so, add the following to your shell profile:
diff --git a/REPL.md b/REPL.md
index bebcf70..f2a7149 100644
--- a/REPL.md
+++ b/REPL.md
@@ -255,6 +255,31 @@ Loki's own bundled assets are replaced.
 (your configured MCP servers and any secret references in them) with Loki's bundled template. The other categories
 only overwrite Loki's built-in assets and leave your custom ones alone.
 
+## `.update` - Update Loki
+
+The `.update` command updates the Loki binary itself to the latest release,
+without leaving the REPL to run a separate installer.
+
+| Command             | Description                                          |
+|---------------------|------------------------------------------------------|
+| `.update`           | Update to the latest release                         |
+| `.update latest`    | Update to the latest release                         |
+| `.update <version>` | Update to a specific release (e.g. `.update v0.4.0`) |
+
+A version may be given either bare (`0.4.0`) or `v`-prefixed (`v0.4.0`). If Loki
+is already on the requested version, it says so and makes no changes; otherwise
+it downloads the matching build, replaces the binary, and reports the new
+version. **Restart Loki** for the update to take effect.
+
+If Loki was installed via Homebrew or `cargo install`, `.update` prints a
+warning (updating in place desyncs your package manager) and asks for
+confirmation before continuing; for those installs, prefer `brew upgrade loki`
+or `cargo install --locked loki-ai`.
+
+`.update` cannot be run from inside a macro. The same operation is available on
+the command line as `loki --update`. For full CLI details, including the 
+`--force` flag for non-interactive updates, see the [Installation documentation](Installation).
+
 ## `.info` - Display information about the current mode
 The `.info` command provides useful information about different modes that Loki may be operating in. It's helpful if you
 want a quick understanding of the system info, a role's configuration, an agent's configuration, etc.