feat: documented the new .install commands

MCP-Servers.md

@@ -134,6 +134,12 @@ Loki ships with a `functions/mcp.json` file that includes some useful MCP server
 * [slack](https://github.com/korotovsky/slack-mcp-server) - Interact with Slack
 * [ddg-search](https://github.com/nickclyde/duckduckgo-mcp-server) - Perform web searches with the DuckDuckGo search engine
 
+The `mcp.json` file is created from a bundled template on first run and is never overwritten afterward. It is your own
+configuration to edit freely. To discard your changes and restore the bundled template (for example, to pick up new
+default servers after a Loki update), run `loki --install mcp_config` (or `.install mcp_config` in the REPL). **This is
+destructive:** it replaces your entire `mcp.json`, including your configured servers and any secret references in them,
+with the bundled template.
+
 # Loki Configuration
 MCP servers, like tools, can be used in a handful of contexts:
 * Inside a session

Macros.md

@@ -92,3 +92,7 @@ on how to make your own macros, so be sure to check out the [built-in macro defi
 looking for more examples.
 
 * `generate-commit-message` - Generate a Git commit message based on the staged changes in the current directory
+
+Built-in macros are written to your macros directory on first run and never overwritten afterward, so your edits are
+preserved across Loki updates. To discard local changes and reinstall the built-in macros from the current Loki build,
+run `loki --install macros` (or `.install macros` in the REPL). Macros you created yourself are not affected.

REPL.md

@@ -232,6 +232,28 @@ directory or file corresponding to the target entity. You can use it to delete t
 * `.delete rag` - Delete select RAGs
 * `.delete agent-data` - Delete select agent's configurations and all tools
 
+## `.install` - Reinstall bundled assets
+Loki's built-in agents, macros, and tool functions (and an MCP config template) are written to your configuration
+directory on first run and are **not** overwritten afterward, so your local edits survive Loki updates. The `.install`
+command force-overwrites a category of bundled assets with the versions packaged in the current Loki build. This is useful
+when an update ships improved built-ins you want to adopt.
+
+| Command               | Description                                                          |
+|-----------------------|----------------------------------------------------------------------|
+| `.install agents`     | Reinstall the built-in agents                                        |
+| `.install macros`     | Reinstall the built-in macros                                        |
+| `.install functions`  | Reinstall the built-in tool functions (leaves your `mcp.json` alone) |
+| `.install mcp_config` | Replace `mcp.json` with the bundled template (see warning below)     |
+
+The same operation is available from the command line: `loki --install <category>` (e.g. `loki --install agents`).
+
+`.install` prompts for confirmation before overwriting anything. Assets you created yourself are never touched. Only
+Loki's own bundled assets are replaced.
+
+**Warning:** `.install mcp_config` is destructive in a way the others are not. It replaces your entire `mcp.json`
+(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.
+
 ## `.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.

Tools.md

@@ -47,6 +47,11 @@ be enabled/disabled can be found in the [Configuration](#configuration) section
 
 Details on what configuration, if any, is necessary for each tool can be found inside the tool file definition itself.
 
+Built-in tools are written to your functions directory on first run and never overwritten afterward, so your edits are
+preserved across Loki updates. To discard local changes and reinstall the built-in tools from the current Loki build,
+run `loki --install functions` (or `.install functions` in the REPL). Tools you created yourself are not affected, and
+your `mcp.json` is left untouched. Use `loki --install mcp_config` to reset that separately.
+
 # Configuration
 Tools can be used in a handful of contexts:
 * Inside a session