Updated docs again

Home.md

@@ -1,5 +1,3 @@
-# Home
-
 Welcome to the Loki wiki!
 
 A helpful way to use this wiki is to create a RAG from it and then ask questions about Loki, with Loki! Here's an example
@@ -19,13 +17,14 @@ in as little time as possible.
 
 Coming from [AIChat](https://github.com/sigoden/aichat)? Follow the [migration guide](AICHAT-MIGRATION) to get started.
 
-## Documentation Index
+---
+
 * [AIChat Migration Guide](AICHAT-MIGRATION): Coming from AIChat? Follow the migration guide to get started.
 * [Installation](docs/Installation.md): Install Loki
 * [Getting Started](docs/Getting-Started.md): Get started with Loki by doing first-run setup steps, and learn the basics.
 * [REPL](REPL): Interactive Read-Eval-Print Loop for conversational interactions with LLMs and Loki.
   * [Custom REPL Prompt](REPL-PROMPT): Customize the REPL prompt to provide useful contextual information.
-* [Vault](VAULT): Securely store and manage sensitive information such as API keys and credentials.
+* [Vault](docs/VAULT.md): Securely store and manage sensitive information such as API keys and credentials.
 * [Shell Integrations](SHELL-INTEGRATIONS): Seamlessly integrate Loki with your shell environment for enhanced command-line assistance.
 * [Function Calling](TOOLS#Tools): Leverage function calling capabilities to extend Loki's functionality with custom tools
     * [Creating Custom Tools](CUSTOM-TOOLS): You can create your own custom tools to enhance Loki's capabilities.

docs/Getting-Started.md

@@ -1,5 +1,3 @@
-# Getting Started
-
 After installation, you can generate the configuration files and directories by simply running:
 
 ```sh
@@ -13,7 +11,7 @@ guide you through the process when you first attempt to access the vault. So, to
 loki --list-secrets
 ```
 
-### Authentication
+# Authentication
 Each client in your configuration needs authentication (with a few exceptions; e.g. ollama). Most clients use an API key
 (set via `api_key` in the config or through the [vault](./docs/VAULT.md)). For providers that support OAuth (e.g. Claude Pro/Max 
 subscribers, Google Gemini), you can authenticate with your existing subscription instead:
@@ -33,7 +31,7 @@ loki --authenticate my-claude-oauth
 
 For full details, see the [authentication documentation](./docs/clients/CLIENTS.md#authentication).
 
-## Configuration
+# Configuration
 The location of the global Loki configuration varies between systems, so you can use the following command to find your
 `config.yaml` file:
 
@@ -44,7 +42,7 @@ loki --info | grep 'config_file' | awk '{print $2}'
 The configuration file consists of a number of settings. To see a full example configuration file with every setting
 defined, refer to the [example configuration file](./config.example.yaml).
 
-### Default LLM
+## Default LLM
 The following settings are available to configure the default LLM that is used when you start Loki, and its
 hyperparameters:
 
@@ -54,7 +52,7 @@ hyperparameters:
 | `temperature` | The default `temperature` parameter for all models (0,1); Used unless explicitly overridden                                                             |
 | `top_p`       | The default `top_p` hyperparameter value to use for all models, with a range of (0,1) (or (0,2) for some models); <br>Used unless explicitly overridden |
 
-### CLI Behavior
+## CLI Behavior
 You can use the following settings to modify the behavior of Loki:
 
 | Setting       | Default Value | Description                                                                                                                         |
@@ -66,7 +64,7 @@ You can use the following settings to modify the behavior of Loki:
 | `wrap`        | `no`          | Controls whether text is wrapped (can be `no`, `auto`, or some `<max_width>`                                                        |
 | `wrap_code`   | `false`       | Enables or disables the wrapping of code blocks                                                                                     |
 
-### Preludes
+## Preludes
 Preludes let you define the default behavior for the different operating modes of Loki. The available settings are
 shown below:
 
@@ -76,7 +74,7 @@ shown below:
 | `cmd_prelude`   | This setting lets you specify a default `session` or `role` to use when running one-off queries in Loki via the CLI. <br>Values can be <ul><li>`role:<name>` to define a role</li><li>`session:<name>` to define a session</li><li>`<session>:<role>` to define both a session and a role to use</li></ul>  |
 | `agent_session` | This setting is used to specify a default session that all agents should start into, unless otherwise specified in the agent configuration. (e.g. `temp`, `default`)                                                                                                                                        |
 
-### Appearance
+## Appearance
 The appearance of Loki can be modified using the following settings:
 
 | Setting       | Default Value | Description                                          |
@@ -84,7 +82,7 @@ The appearance of Loki can be modified using the following settings:
 | `highlight`   | `true`        | This setting enables or disables syntax highlighting |
 | `light_theme` | `false`       | This setting toggles light mode in Loki              |
 
-### Miscellaneous Settings
+## Miscellaneous Settings
 | Setting              | Default Value | Description                                                                                                      |
 |----------------------|---------------|------------------------------------------------------------------------------------------------------------------|
 | `user_agent`         | `null`        | The name of the `User-Agent` that should be passed in the `User-Agent` header on all requests to model providers |

docs/Installation.md

@@ -1,6 +1,4 @@
-# Installation
+# Prerequisites
-
-## Prerequisites
 Loki requires the following tools to be installed on your system:
 * [jq](https://github.com/jqlang/jq)
     * `brew install jq`
@@ -13,9 +11,9 @@ Loki requires the following tools to be installed on your system:
 These tools are used to provide various functionalities within Loki, such as document processing, JSON manipulation,
 and they are used within agents and tools.
 
-## Install
+# Install
 
-### Cargo
+## Cargo
 If you have Cargo installed, then you can install `loki` from Crates.io:
 
 ```shell
@@ -25,7 +23,7 @@ cargo install loki-ai # Binary name is `loki`
 cargo install --locked loki-ai
 ```
 
-### Homebrew (Mac/Linux)
+## Homebrew (Mac/Linux)
 To install Loki from Homebrew, install the `loki` tap. Then you'll be able to install `loki`:
 
 ```shell
@@ -42,8 +40,8 @@ To upgrade `loki` using Homebrew:
 brew upgrade loki
 ```
 
-### Scripts
+## Scripts
-#### Linux/MacOS (`bash`)
+### Linux/MacOS (`bash`)
 You can use the following command to run a bash script that downloads and installs the latest version of `loki` for your
 OS (Linux/MacOS) and architecture (x86_64/arm64):
 
@@ -51,7 +49,7 @@ OS (Linux/MacOS) and architecture (x86_64/arm64):
 curl -fsSL https://raw.githubusercontent.com/Dark-Alex-17/loki/main/install_loki.sh | bash
 ```
 
-#### Windows/Linux/MacOS (`PowerShell`)
+### Windows/Linux/MacOS (`PowerShell`)
 You can use the following command to run a PowerShell script that downloads and installs the latest version of `loki`
 for your OS (Windows/Linux/MacOS) and architecture (x86_64/arm64):
 
@@ -59,7 +57,7 @@ for your OS (Windows/Linux/MacOS) and architecture (x86_64/arm64):
 powershell -NoProfile -ExecutionPolicy Bypass -Command "iwr -useb https://raw.githubusercontent.com/Dark-Alex-17/loki/main/scripts/install_loki.ps1 | iex"
 ```
 
-### Manual
+## Manual
 Binaries are available on the [releases](https://github.com/Dark-Alex-17/loki/releases) page for the following platforms:
 
 | Platform       | Architecture(s) |
@@ -68,14 +66,14 @@ Binaries are available on the [releases](https://github.com/Dark-Alex-17/loki/re
 | Linux GNU/MUSL | x86_64, aarch64 |
 | Windows        | x86_64, aarch64 |
 
-#### Windows Instructions
+### Windows Instructions
 To use a binary from the releases page on Windows, do the following:
 
 1. Download the latest [binary](https://github.com/Dark-Alex-17/loki/releases) for your OS.
 2. Use 7-Zip or TarTool to unpack the Tar file.
 3. Run the executable `loki.exe`!
 
-#### Linux/MacOS Instructions
+### Linux/MacOS Instructions
 To use a binary from the releases page on Linux/MacOS, do the following:
 
 1. Download the latest [binary](https://github.com/Dark-Alex-17/loki/releases) for your OS.
@@ -84,7 +82,7 @@ To use a binary from the releases page on Linux/MacOS, do the following:
 4. Now you can run `loki`!
 
 
-## Tab-Completions
+# Tab-Completions
 You can also enable tab completions to make using Loki easier. To do so, add the following to your shell profile:
 ```shell
 # Bash
@@ -109,9 +107,9 @@ $env:COMPLETE = "powershell"
 loki | Out-String | Invoke-Expression
 ```
 
-## Shell Integration
+# Shell Integration
 You can integrate Loki's Shell Assistant into your shell for enhanced command-line assistance. Add the code in the
-corresponding [shell integration script](./scripts/shell-integration) to your shell. Then, you can invoke Loki to convert natural language to 
+corresponding [shell integration script](https://github.com/Dark-Alex-17/loki/tree/main/scripts/shell-integration) to your shell. Then, you can invoke Loki to convert natural language to 
 shell commands by pressing `Alt-e`. For example:
 
 ```shell

docs/Vault.md

@@ -0,0 +1,160 @@
+The Loki vault lets users store sensitive secrets and credentials securely so that there's no plaintext secrets
+anywhere in your configurations. 
+
+It's based on the [G-Man library](https://github.com/Dark-Alex-17/gman) (which also comes in a binary format) which
+functions as a universal secret management tool.
+
+![Vault Demo](https://raw.githubusercontent.com/Dark-Alex-17/loki/main/docs/images/vault/vault-demo.gif)
+
+# Quick Links
+<!--toc:start-->
+- [Usage](#usage)
+  - [CLI Usage](#cli-usage)
+  - [REPL Usage](#repl-usage)
+- [Motivation](#motivation)
+- [How it works](#how-it-works)
+- [Supported Files](#supported-files)
+- [Environment Variable Secret Injection in Agents](#environment-variable-secret-injection-in-agents)
+<!--toc:end-->
+
+---
+
+# Usage
+The Loki vault can be used in one of two ways: via the CLI or via the REPL for interactive usage.
+
+## CLI Usage
+The vault is utilized from the CLI with the following flags:
+
+```bash
+--add-secret <SECRET_NAME>       Add a secret to the Loki vault
+--get-secret <SECRET_NAME>       Decrypt a secret from the Loki vault and print the plaintext
+--update-secret <SECRET_NAME>    Update an existing secret in the Loki vault
+--delete-secret <SECRET_NAME>    Delete a secret from the Loki vault
+--list-secrets                   List all secrets stored in the Loki vault
+```
+(The above is also documented in `loki --help`)
+
+Loki will guide you through manipulating your secrets to make usage easier.
+
+## REPL Usage
+The vault can be access from within the Loki REPL using the `.vault` commands:
+
+![Loki Vault REPL](https://raw.githubusercontent.com/Dark-Alex-17/loki/main/docs/images/vault/vault-repl.png)
+![Loki Vault REPL Commands](https://raw.githubusercontent.com/Dark-Alex-17/loki/main/docs/images/vault/vault-repl-commands.png)
+
+The manipulation of your vault is guided in the same way as the CLI usage, ensuring ease of use.
+
+# Motivation
+Loki is intended to be highly configurable and adaptable to many different use cases. This means that users of Loki
+should be able to share configurations for agents, tools, roles, etc. with other users or even entire teams.
+
+My objective is to encourage this, and to make it so that users can easily version their configurations using version
+control. Good VCS hygiene dictates that one *never* commits secrets or sensitive information to a repository.
+
+Since a number of files and configurations in Loki may contain sensitive information, the vault exists to solve this problem.
+
+Users can either share the vault password with a team, making it so a single configuration can be pulled from VCS and used
+by said team. Alternatively, each user can maintain their own vault password and expect other users to replace secret values
+with their user-specific secrets.
+
+# How it works
+When you first start Loki, if you don't already have a vault password file, it will prompt you to create one. This file
+houses the password that is used to encrypt and decrypt secrets within Loki. This file exists so that you are not prompted
+for a password every time Loki attempts to decrypt a secret.
+
+When you encrypt a secret, it uses the local provider for `gman` to securely store those secrets in the Loki vault file.
+This file is typically located at your Loki configuration directory under `vault.yml`. If you open this file, you'll see a
+bunch of gibberish. This is because all secrets are encrypted using the password you provided, meaning only you can decrypt them.
+
+Secrets are specified in Loki configurations using the same variable templating as the [Jinja templating engine](https://jinja.palletsprojects.com/en/stable/):
+
+```
+{{some_variable}}
+```
+
+So whenever you want Loki to use a secret from the vault, you simply specify the secret name in this format in the applicable
+file.
+
+**Example:**
+Suppose my vault has a secret called `GITHUB_TOKEN` in it, and I want to use that in the MCP configuration. Then, I simply replace
+the expected value in my `mcp.json` with the templated secret:
+
+```json
+{
+  "mcpServers": {
+    "atlassian": {
+      "command": "npx",
+      "args": ["-y", "mcp-remote", "https://mcp.atlassian.com/v1/sse"]
+    },
+    "github": {
+      "command": "docker",
+      "args": [
+        "run",
+        "-i",
+        "--rm",
+        "-e",
+        "GITHUB_PERSONAL_ACCESS_TOKEN",
+        "ghcr.io/github/github-mcp-server"
+      ],
+      "env": {
+        "GITHUB_PERSONAL_ACCESS_TOKEN": "{{GITHUB_TOKEN}}"
+      }
+    }
+  }
+}
+```
+
+At runtime, Loki will detect the templated secret and replace it with the decrypted value from the vault before executing.
+
+# Supported Files
+At the time of writing, the following files support Loki secret injection:
+
+| File Type               | Description                       | Limitations                                                                                                                               |
+|-------------------------|-----------------------------------|-------------------------------------------------------------------------------------------------------------------------------------------|
+| `config.yaml`           | The main Loki configuration file  | Cannot use secret injection on the `vault_password_file` field                                                                            |
+| `functions/mcp.json`    | The MCP server configuration file |                                                                                                                                           |
+| `<agent>/tools.<py/sh>` | Tool files for agents             | Specific configuration and only supported for Agents, not all global tools ([see below](#environment-variable-secret-injection-in-agents)) |
+
+
+Note that all paths are relative to the Loki configuration directory. The directory varies by system, so you can find yours by
+running
+
+```shell
+loki --info | grep config_dir | awk '{print $2}'
+```
+
+# Environment Variable Secret Injection in Agents
+Secrets from the Loki vault can be injected into agent `tools.sh/tools.py` as environment variables. This is done as 
+follows:
+
+1. Ensure a secret named `MY_USERNAME` is in your Loki vault.
+2. Set the name of the secret as the default value for a variable
+   `<agent>/config.yaml`
+   ```yaml
+   name: Username
+   description: An AI agent that demonstrates agent capabilities
+   instructions: |
+     You are a AI agent designed to demonstrate agent capabilities.
+   variables:
+     - name: username
+       description: Your user name
+       # Configure the secret you want to inject using the same templating mentioned above; i.e. wrap the 
+       # case-sensitive name in '{{}}'
+       default: '{{MY_USERNAME}}'
+   ```
+3. Reference the variable in your `<agent>/tools.<py/sh>` file using the familiar variable injection name; that is, 
+   since the name of the variable is `username`, the environment variable that will be provided to the tool call will
+   be named `LLM_AGENT_VAR_USERNAME`
+   `tools.sh`
+   ```bash
+   #!/usr/bin/env bash
+   # @env LLM_OUTPUT=/dev/stdout The output path
+   
+   # @cmd Get my username
+   get_my_username() {
+      echo "$LLM_AGENT_VAR_USERNAME" >> "$LLM_OUTPUT"        
+   }
+   ```
+
+For more information about variable usage within agents, refer to the [Variables section](./AGENTS.md#user-defined-variables) of the [Agents README](./AGENTS.md)
+