diff --git a/.loki-project.json b/.loki-project.json
new file mode 100644
index 0000000..165f4c7
--- /dev/null
+++ b/.loki-project.json
@@ -0,0 +1 @@
+{"type":"rust","build":"cargo build","test":"cargo test","check":"cargo check","_detected_by":"heuristic","_cached_at":"2026-04-13T13:36:33-06:00"}
diff --git a/Cargo.lock b/Cargo.lock
index a52948f..0db1cee 100644
--- a/Cargo.lock
+++ b/Cargo.lock
@@ -23,7 +23,7 @@ version = "0.5.2"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "d122413f284cf2d62fb1b7db97e02edb8cda96d769b16e443a4f6195e35662b0"
 dependencies = [
- "crypto-common",
+ "crypto-common 0.1.7",
  "generic-array",
 ]
 
@@ -65,9 +65,9 @@ dependencies = [
 
 [[package]]
 name = "anndists"
-version = "0.1.4"
+version = "0.1.5"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "8238f99889a837cd6641360f9f3ead18f70b07bf6ce1f04a319bc6bd8a2f48f1"
+checksum = "9a8396b473aa0bceed68fb32462505387ea39fa47c7029417e0a49f10592b036"
 dependencies = [
  "anyhow",
  "cfg-if",
@@ -145,6 +145,15 @@ version = "1.0.102"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "7f202df86484c868dbad7eaa557ef785d5c66295e41b460ef922eca0723b842c"
 
+[[package]]
+name = "arbitrary"
+version = "1.4.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "c3d036a3c4ab069c7b410a2ce876bd74808d2d0888a82667669f8e783a898bf1"
+dependencies = [
+ "derive_arbitrary",
+]
+
 [[package]]
 name = "arboard"
 version = "3.6.1"
@@ -165,25 +174,25 @@ dependencies = [
 
 [[package]]
 name = "arc-swap"
-version = "1.9.0"
+version = "1.9.1"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "a07d1f37ff60921c83bdfc7407723bdefe89b44b98a9b772f225c8f9d67141a6"
+checksum = "6a3a1fd6f75306b68087b831f025c712524bcb19aad54e557b1129cfa0a2b207"
 dependencies = [
  "rustversion",
 ]
 
 [[package]]
 name = "argc"
-version = "1.23.0"
+version = "1.24.0"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "ed45b16ecde78101a90574aeeac8e61749203b7dba72a4abb70a870e92af0047"
+checksum = "17060e608fbc0809d62a996a65cdee9e7c441a979f40f2d1d2fbdce9eef60dad"
 dependencies = [
  "anyhow",
  "base64",
- "convert_case 0.8.0",
+ "convert_case 0.11.0",
  "dirs",
  "either",
- "indexmap 2.13.0",
+ "indexmap 2.14.0",
  "natord",
  "nom 8.0.0",
  "num_cpus",
@@ -194,6 +203,7 @@ dependencies = [
  "shell-words",
  "textwrap",
  "threadpool",
+ "unicode-width",
  "which",
 ]
 
@@ -205,15 +215,15 @@ checksum = "3c3610892ee6e0cbce8ae2700349fcf8f98adb0dbfbee85aec3c9179d29cc072"
 dependencies = [
  "base64ct",
  "blake2",
- "cpufeatures",
+ "cpufeatures 0.2.17",
  "password-hash",
 ]
 
 [[package]]
 name = "async-compression"
-version = "0.4.41"
+version = "0.4.42"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "d0f9ee0f6e02ffd7ad5816e9464499fba7b3effd01123b515c41d1697c43dad1"
+checksum = "e79b3f8a79cccc2898f31920fc69f304859b3bd567490f75ebf51ae1c792a9ac"
 dependencies = [
  "compression-codecs",
  "compression-core",
@@ -262,15 +272,15 @@ checksum = "1505bd5d3d116872e7271a6d4e16d81d0c8570876c8de68093a09ac269d8aac0"
 
 [[package]]
 name = "autocfg"
-version = "1.5.0"
+version = "1.5.1"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "c08606f8c3cbf4ce6ec8e28fb0014a2c086708fe954eaa885384a6165172e7e8"
+checksum = "f2032f911046de80f0a198e0901378627c33f59ea0ac00e363d481118bd70a53"
 
 [[package]]
 name = "aws-config"
-version = "1.8.13"
+version = "1.8.17"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "c456581cb3c77fafcc8c67204a70680d40b61112d6da78c77bd31d945b65f1b5"
+checksum = "517aa062d8bd9015ee23d6daa5e1c1372328412fdae4e6c4c1be9b69c6ad37a2"
 dependencies = [
  "aws-credential-types",
  "aws-runtime",
@@ -282,13 +292,14 @@ dependencies = [
  "aws-smithy-json",
  "aws-smithy-runtime",
  "aws-smithy-runtime-api",
+ "aws-smithy-schema",
  "aws-smithy-types",
  "aws-types",
  "bytes",
  "fastrand",
  "hex",
  "http 1.4.0",
- "ring",
+ "sha1",
  "time",
  "tokio",
  "tracing",
@@ -298,9 +309,9 @@ dependencies = [
 
 [[package]]
 name = "aws-credential-types"
-version = "1.2.11"
+version = "1.2.14"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "3cd362783681b15d136480ad555a099e82ecd8e2d10a841e14dfd0078d67fee3"
+checksum = "8f20799b373a1be121fe3005fba0c2090af9411573878f224df44b42727fcaf7"
 dependencies = [
  "aws-smithy-async",
  "aws-smithy-runtime-api",
@@ -310,19 +321,19 @@ dependencies = [
 
 [[package]]
 name = "aws-lc-rs"
-version = "1.16.2"
+version = "1.17.0"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "a054912289d18629dc78375ba2c3726a3afe3ff71b4edba9dedfca0e3446d1fc"
+checksum = "5ec2f1fc3ec205783a5da9a7e6c1509cc69dedf09a1949e412c1e18469326d00"
 dependencies = [
- "aws-lc-sys 0.39.1",
+ "aws-lc-sys 0.41.0",
  "zeroize",
 ]
 
 [[package]]
 name = "aws-lc-sys"
-version = "0.37.1"
+version = "0.39.1"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "b092fe214090261288111db7a2b2c2118e5a7f30dc2569f1732c4069a6840549"
+checksum = "83a25cf98105baa966497416dbd42565ce3a8cf8dbfd59803ec9ad46f3126399"
 dependencies = [
  "bindgen",
  "cc",
@@ -333,9 +344,9 @@ dependencies = [
 
 [[package]]
 name = "aws-lc-sys"
-version = "0.39.1"
+version = "0.41.0"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "83a25cf98105baa966497416dbd42565ce3a8cf8dbfd59803ec9ad46f3126399"
+checksum = "1a2f9779ce85b93ab6170dd940ad0169b5766ff848247aff13bb788b832fe3f4"
 dependencies = [
  "cc",
  "cmake",
@@ -345,9 +356,9 @@ dependencies = [
 
 [[package]]
 name = "aws-runtime"
-version = "1.6.0"
+version = "1.7.4"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "c635c2dc792cb4a11ce1a4f392a925340d1bdf499289b5ec1ec6810954eb43f5"
+checksum = "77ed8e8c52d2dc2390ad9f15647fe663f71e9780b4262c190fbb823a32721566"
 dependencies = [
  "aws-credential-types",
  "aws-sigv4",
@@ -358,6 +369,7 @@ dependencies = [
  "aws-smithy-types",
  "aws-types",
  "bytes",
+ "bytes-utils",
  "fastrand",
  "http 1.4.0",
  "http-body 1.0.1",
@@ -369,9 +381,9 @@ dependencies = [
 
 [[package]]
 name = "aws-sdk-secretsmanager"
-version = "1.99.0"
+version = "1.105.0"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "81f5e5b4f5612dc147e56bf2c1c436e8e098dc3433fb525cfd7562128a78b53f"
+checksum = "1c4e56ac810211dc33810c7aa3612eda29a8b1e8c7e2db6e960c8657e3d95e42"
 dependencies = [
  "aws-credential-types",
  "aws-runtime",
@@ -393,9 +405,9 @@ dependencies = [
 
 [[package]]
 name = "aws-sdk-sso"
-version = "1.93.0"
+version = "1.99.0"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "9dcb38bb33fc0a11f1ffc3e3e85669e0a11a37690b86f77e75306d8f369146a0"
+checksum = "9f4055e6099b2ec264abdc0d9bbfffce306c1601809275c861594779a0b04b45"
 dependencies = [
  "aws-credential-types",
  "aws-runtime",
@@ -417,9 +429,9 @@ dependencies = [
 
 [[package]]
 name = "aws-sdk-ssooidc"
-version = "1.95.0"
+version = "1.101.0"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "2ada8ffbea7bd1be1f53df1dadb0f8fdb04badb13185b3321b929d1ee3caad09"
+checksum = "02f009ba0284c5d696425fd7b4dcc5b189f5726f4041b7a5794daecb3a68d598"
 dependencies = [
  "aws-credential-types",
  "aws-runtime",
@@ -441,9 +453,9 @@ dependencies = [
 
 [[package]]
 name = "aws-sdk-sts"
-version = "1.97.0"
+version = "1.104.0"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "e6443ccadc777095d5ed13e21f5c364878c9f5bad4e35187a6cdbd863b0afcad"
+checksum = "6aa6622798e19e6a76b690562085dd4771c736cd48343464a53ab4ae2f2c9f84"
 dependencies = [
  "aws-credential-types",
  "aws-runtime",
@@ -466,9 +478,9 @@ dependencies = [
 
 [[package]]
 name = "aws-sigv4"
-version = "1.3.8"
+version = "1.4.4"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "efa49f3c607b92daae0c078d48a4571f599f966dce3caee5f1ea55c4d9073f99"
+checksum = "b7083fb918b38474ac65ffbf8a69fc8792d36879f4ac5f1667b43aec61efe9a5"
 dependencies = [
  "aws-credential-types",
  "aws-smithy-http",
@@ -477,20 +489,20 @@ dependencies = [
  "bytes",
  "form_urlencoded",
  "hex",
- "hmac",
+ "hmac 0.13.0",
  "http 0.2.12",
  "http 1.4.0",
  "percent-encoding",
- "sha2",
+ "sha2 0.11.0",
  "time",
  "tracing",
 ]
 
 [[package]]
 name = "aws-smithy-async"
-version = "1.2.11"
+version = "1.2.14"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "52eec3db979d18cb807fc1070961cc51d87d069abe9ab57917769687368a8c6c"
+checksum = "2ffcaf626bdda484571968400c326a244598634dc75fd451325a54ad1a59acfc"
 dependencies = [
  "futures-util",
  "pin-project-lite",
@@ -499,9 +511,9 @@ dependencies = [
 
 [[package]]
 name = "aws-smithy-eventstream"
-version = "0.60.18"
+version = "0.60.20"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "35b9c7354a3b13c66f60fe4616d6d1969c9fd36b1b5333a5dfb3ee716b33c588"
+checksum = "faf09d74e5e32f76b8762da505a3cd59303e367a664ca67295387baa8c1d7548"
 dependencies = [
  "aws-smithy-types",
  "bytes",
@@ -510,9 +522,9 @@ dependencies = [
 
 [[package]]
 name = "aws-smithy-http"
-version = "0.63.3"
+version = "0.63.6"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "630e67f2a31094ffa51b210ae030855cb8f3b7ee1329bdd8d085aaf61e8b97fc"
+checksum = "ba1ab2dc1c2c3749ead27180d333c42f11be8b0e934058fb4b2258ee8dbe5231"
 dependencies = [
  "aws-smithy-runtime-api",
  "aws-smithy-types",
@@ -531,26 +543,26 @@ dependencies = [
 
 [[package]]
 name = "aws-smithy-http-client"
-version = "1.1.9"
+version = "1.1.12"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "12fb0abf49ff0cab20fd31ac1215ed7ce0ea92286ba09e2854b42ba5cabe7525"
+checksum = "6a2f165a7feee6f263028b899d0a181987f4fa7179a6411a32a439fba7c5f769"
 dependencies = [
  "aws-smithy-async",
  "aws-smithy-runtime-api",
  "aws-smithy-types",
  "h2 0.3.27",
- "h2 0.4.13",
+ "h2 0.4.14",
  "http 0.2.12",
  "http 1.4.0",
  "http-body 0.4.6",
  "hyper 0.14.32",
  "hyper 1.9.0",
  "hyper-rustls 0.24.2",
- "hyper-rustls 0.27.7",
+ "hyper-rustls 0.27.9",
  "hyper-util",
  "pin-project-lite",
  "rustls 0.21.12",
- "rustls 0.23.37",
+ "rustls 0.23.40",
  "rustls-native-certs",
  "rustls-pki-types",
  "tokio",
@@ -561,27 +573,29 @@ dependencies = [
 
 [[package]]
 name = "aws-smithy-json"
-version = "0.62.3"
+version = "0.62.6"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "3cb96aa208d62ee94104645f7b2ecaf77bf27edf161590b6224bfbac2832f979"
+checksum = "517089205f18ab4adc5a3e02888cb139bbbbb2e168eac9f396216925d1fbeaf5"
 dependencies = [
+ "aws-smithy-runtime-api",
+ "aws-smithy-schema",
  "aws-smithy-types",
 ]
 
 [[package]]
 name = "aws-smithy-observability"
-version = "0.2.4"
+version = "0.2.6"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "c0a46543fbc94621080b3cf553eb4cbbdc41dd9780a30c4756400f0139440a1d"
+checksum = "a06c2315d173edbf1920da8ba3a7189695827002e4c0fc961973ab1c54abca9c"
 dependencies = [
  "aws-smithy-runtime-api",
 ]
 
 [[package]]
 name = "aws-smithy-query"
-version = "0.60.13"
+version = "0.60.15"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "0cebbddb6f3a5bd81553643e9c7daf3cc3dc5b0b5f398ac668630e8a84e6fff0"
+checksum = "1a56d79744fb3edb5d722ef79d86081e121d3b9422cb209eb03aea6aa4f21ebd"
 dependencies = [
  "aws-smithy-types",
  "urlencoding",
@@ -589,15 +603,16 @@ dependencies = [
 
 [[package]]
 name = "aws-smithy-runtime"
-version = "1.10.0"
+version = "1.11.3"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "f3df87c14f0127a0d77eb261c3bc45d5b4833e2a1f63583ebfb728e4852134ee"
+checksum = "b8e6f5caf6fea86f8c2206541ab5857cfcda9013426cdbe8fa0098b9e2d32182"
 dependencies = [
  "aws-smithy-async",
  "aws-smithy-http",
  "aws-smithy-http-client",
  "aws-smithy-observability",
  "aws-smithy-runtime-api",
+ "aws-smithy-schema",
  "aws-smithy-types",
  "bytes",
  "fastrand",
@@ -614,11 +629,12 @@ dependencies = [
 
 [[package]]
 name = "aws-smithy-runtime-api"
-version = "1.11.3"
+version = "1.12.1"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "49952c52f7eebb72ce2a754d3866cc0f87b97d2a46146b79f80f3a93fb2b3716"
+checksum = "dc117c179ecf39a62a0a3f49f600e9ac26a7ad7dd172177999f83933af776c32"
 dependencies = [
  "aws-smithy-async",
+ "aws-smithy-runtime-api-macros",
  "aws-smithy-types",
  "bytes",
  "http 0.2.12",
@@ -630,10 +646,32 @@ dependencies = [
 ]
 
 [[package]]
-name = "aws-smithy-types"
-version = "1.4.3"
+name = "aws-smithy-runtime-api-macros"
+version = "1.0.0"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "3b3a26048eeab0ddeba4b4f9d51654c79af8c3b32357dc5f336cee85ab331c33"
+checksum = "8d7396fd9500589e62e460e987ecb671bad374934e55ec3b5f498cc7a8a8a7b7"
+dependencies = [
+ "proc-macro2",
+ "quote",
+ "syn",
+]
+
+[[package]]
+name = "aws-smithy-schema"
+version = "0.1.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "7442cb268338f0eb8278140a107c046756aa01093d8ef5e99628d34ae09c94f5"
+dependencies = [
+ "aws-smithy-runtime-api",
+ "aws-smithy-types",
+ "http 1.4.0",
+]
+
+[[package]]
+name = "aws-smithy-types"
+version = "1.4.8"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "056b66dbce2f81cc0c1e2b05bb402eb58f8a3530479d650efadd5bbae9a4050b"
 dependencies = [
  "base64-simd",
  "bytes",
@@ -657,22 +695,23 @@ dependencies = [
 
 [[package]]
 name = "aws-smithy-xml"
-version = "0.60.13"
+version = "0.60.15"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "11b2f670422ff42bf7065031e72b45bc52a3508bd089f743ea90731ca2b6ea57"
+checksum = "0ce02add1aa3677d022f8adf81dcbe3046a95f17a1b1e8979c145cd21d3d22b3"
 dependencies = [
  "xmlparser",
 ]
 
 [[package]]
 name = "aws-types"
-version = "1.3.11"
+version = "1.3.16"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "1d980627d2dd7bfc32a3c025685a033eeab8d365cc840c631ef59d1b8f428164"
+checksum = "d16bf10b03a3c01e6b3b7d47cd964e873ffe9e7d4e80fad16bd4c077cb068531"
 dependencies = [
  "aws-credential-types",
  "aws-smithy-async",
  "aws-smithy-runtime-api",
+ "aws-smithy-schema",
  "aws-smithy-types",
  "rustc_version",
  "tracing",
@@ -680,9 +719,9 @@ dependencies = [
 
 [[package]]
 name = "axum"
-version = "0.8.8"
+version = "0.8.9"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "8b52af3cb4058c895d37317bb27508dccc8e5f2d39454016b297bf4a400597b8"
+checksum = "31b698c5f9a010f6573133b09e0de5408834d0c82f8d7475a89fc1867a71cd90"
 dependencies = [
  "axum-core",
  "bytes",
@@ -859,7 +898,7 @@ dependencies = [
  "proc-macro2",
  "quote",
  "regex",
- "rustc-hash 2.1.2",
+ "rustc-hash",
  "shlex",
  "syn",
 ]
@@ -881,9 +920,9 @@ checksum = "5e764a1d40d510daf35e07be9eb06e75770908c27d411ee6c92109c9840eaaf7"
 
 [[package]]
 name = "bitflags"
-version = "2.11.0"
+version = "2.11.1"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "843867be96c8daad0d758b57df9392b6d8d271134fce549de6ce169ff98a92af"
+checksum = "c4512299f36f043ab09a583e57bceb5a5aab7a73db1805848e8fef3c9e8c78b3"
 dependencies = [
  "serde_core",
 ]
@@ -894,7 +933,7 @@ version = "0.10.6"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "46502ad458c9a52b69d4d4d32775c788b7a1b85e8bc9d482d92250fc0e3f8efe"
 dependencies = [
- "digest",
+ "digest 0.10.7",
 ]
 
 [[package]]
@@ -906,6 +945,15 @@ dependencies = [
  "generic-array",
 ]
 
+[[package]]
+name = "block-buffer"
+version = "0.12.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "cdd35008169921d80bc60d3d0ab416eecb028c4cd653352907921d95084790be"
+dependencies = [
+ "hybrid-array",
+]
+
 [[package]]
 name = "block2"
 version = "0.6.2"
@@ -931,10 +979,19 @@ dependencies = [
 ]
 
 [[package]]
-name = "bumpalo"
-version = "3.20.2"
+name = "bs58"
+version = "0.5.1"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "5d20789868f4b01b2f2caec9f5c4e0213b41e3e5702a50157d699ae31ced2fcb"
+checksum = "bf88ba1141d185c399bee5288d850d63b8369520c1eafc32a0430b5b6c287bf4"
+dependencies = [
+ "tinyvec",
+]
+
+[[package]]
+name = "bumpalo"
+version = "3.20.3"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "72f5acc6cb2ba439de613abc23857ec3d78374d8ed5ac84e9d11336e87da8649"
 
 [[package]]
 name = "bytemuck"
@@ -999,9 +1056,9 @@ checksum = "ade8366b8bd5ba243f0a58f036cc0ca8a2f069cff1a2351ef1cac6b083e16fc0"
 
 [[package]]
 name = "cc"
-version = "1.2.58"
+version = "1.2.62"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "e1e928d4b69e3077709075a938a05ffbedfa53a84c8f766efbf8220bb1ff60e1"
+checksum = "a1dce859f0832a7d088c4f1119888ab94ef4b5d6795d1ce05afb7fe159d79f98"
 dependencies = [
  "find-msvc-tools",
  "jobserver",
@@ -1038,7 +1095,18 @@ checksum = "c3613f74bd2eac03dad61bd53dbe620703d4371614fe0bc3b9f04dd36fe4e818"
 dependencies = [
  "cfg-if",
  "cipher",
- "cpufeatures",
+ "cpufeatures 0.2.17",
+]
+
+[[package]]
+name = "chacha20"
+version = "0.10.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "6f8d983286843e49675a4b7a2d174efe136dc93a18d69130dd18198a6c167601"
+dependencies = [
+ "cfg-if",
+ "cpufeatures 0.3.0",
+ "rand_core 0.10.1",
 ]
 
 [[package]]
@@ -1048,7 +1116,7 @@ source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "10cd79432192d1c0f4e1a0fef9527696cc039165d729fb41b3f4f4f354c2dc35"
 dependencies = [
  "aead",
- "chacha20",
+ "chacha20 0.9.1",
  "cipher",
  "poly1305",
  "zeroize",
@@ -1074,7 +1142,7 @@ version = "0.4.4"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "773f3b9af64447d2ce9850330c473515014aa235e6a783b02db81ff39e4a3dad"
 dependencies = [
- "crypto-common",
+ "crypto-common 0.1.7",
  "inout",
  "zeroize",
 ]
@@ -1092,9 +1160,9 @@ dependencies = [
 
 [[package]]
 name = "clap"
-version = "4.6.0"
+version = "4.6.1"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "b193af5b67834b676abd72466a96c1024e6a6ad978a1f484bd90b85c94041351"
+checksum = "1ddb117e43bbf7dacf0a4190fef4d345b9bad68dfc649cb349e7d17d28428e51"
 dependencies = [
  "clap_builder",
  "clap_derive",
@@ -1115,9 +1183,9 @@ dependencies = [
 
 [[package]]
 name = "clap_complete"
-version = "4.6.0"
+version = "4.6.5"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "19c9f1dde76b736e3681f28cec9d5a61299cbaae0fce80a68e43724ad56031eb"
+checksum = "e0a7a9bfdb35811f9e59832f0f05975114d2251b415fb534108e6f34060fd772"
 dependencies = [
  "clap",
  "clap_lex",
@@ -1137,9 +1205,9 @@ dependencies = [
 
 [[package]]
 name = "clap_derive"
-version = "4.6.0"
+version = "4.6.1"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "1110bd8a634a1ab8cb04345d8d878267d57c3cf1b38d91b71af6686408bbca6a"
+checksum = "f2ce8604710f6733aa641a2b3731eaa1e8b3d9973d5e3565da11800813f997a9"
 dependencies = [
  "heck",
  "proc-macro2",
@@ -1171,6 +1239,12 @@ dependencies = [
  "cc",
 ]
 
+[[package]]
+name = "cmov"
+version = "0.5.3"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "3f88a43d011fc4a6876cb7344703e297c71dda42494fee094d5f7c76bf13f746"
+
 [[package]]
 name = "colorchoice"
 version = "1.0.5"
@@ -1198,9 +1272,9 @@ dependencies = [
 
 [[package]]
 name = "compression-codecs"
-version = "0.4.37"
+version = "0.4.38"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "eb7b51a7d9c967fc26773061ba86150f19c50c0d65c887cb1fbe295fd16619b7"
+checksum = "ce2548391e9c1929c21bf6aa2680af86fe4c1b33e6cea9ac1cfeec0bd11218cf"
 dependencies = [
  "compression-core",
  "flate2",
@@ -1209,9 +1283,9 @@ dependencies = [
 
 [[package]]
 name = "compression-core"
-version = "0.4.31"
+version = "0.4.32"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "75984efb6ed102a0d42db99afb6c1948f0380d1d91808d5529916e6c08b49d8d"
+checksum = "cc14f565cf027a105f7a44ccf9e5b424348421a1d8952a8fc9d499d313107789"
 
 [[package]]
 name = "concurrent-queue"
@@ -1248,13 +1322,16 @@ dependencies = [
 ]
 
 [[package]]
-name = "convert_case"
-version = "0.8.0"
+name = "const-oid"
+version = "0.9.6"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "baaaa0ecca5b51987b9423ccdc971514dd8b0bb7b4060b983d3664dad3f1f89f"
-dependencies = [
- "unicode-segmentation",
-]
+checksum = "c2459377285ad874054d797f3ccebf984978aa39129f6eafde5cdc8315b612f8"
+
+[[package]]
+name = "const-oid"
+version = "0.10.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "a6ef517f0926dd24a1582492c791b6a4818a4d94e789a334894aa15b0d12f55c"
 
 [[package]]
 name = "convert_case"
@@ -1265,6 +1342,44 @@ dependencies = [
  "unicode-segmentation",
 ]
 
+[[package]]
+name = "convert_case"
+version = "0.11.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "affbf0190ed2caf063e3def54ff444b449371d55c58e513a95ab98eca50adb49"
+dependencies = [
+ "unicode-segmentation",
+]
+
+[[package]]
+name = "cookie"
+version = "0.18.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "4ddef33a339a91ea89fb53151bd0a4689cfce27055c291dfa69945475d22c747"
+dependencies = [
+ "percent-encoding",
+ "time",
+ "version_check",
+]
+
+[[package]]
+name = "cookie_store"
+version = "0.22.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "15b2c103cf610ec6cae3da84a766285b42fd16aad564758459e6ecf128c75206"
+dependencies = [
+ "cookie",
+ "document-features",
+ "idna",
+ "indexmap 2.14.0",
+ "log",
+ "serde",
+ "serde_derive",
+ "serde_json",
+ "time",
+ "url",
+]
+
 [[package]]
 name = "core-foundation"
 version = "0.10.1"
@@ -1300,6 +1415,15 @@ dependencies = [
  "libc",
 ]
 
+[[package]]
+name = "cpufeatures"
+version = "0.3.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "8b2a41393f66f16b0823bb79094d54ac5fbd34ab292ddafb9a0456ac9f87d201"
+dependencies = [
+ "libc",
+]
+
 [[package]]
 name = "crc32c"
 version = "0.6.8"
@@ -1343,24 +1467,6 @@ version = "0.8.21"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "d0a5c400df2834b80a4c3327b3aad3a4c4cd4de0629063962b03235697506a28"
 
-[[package]]
-name = "crossterm"
-version = "0.28.1"
-source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "829d955a0bb380ef178a640b91779e3987da38c9aea133b20614cfed8cdea9c6"
-dependencies = [
- "bitflags",
- "crossterm_winapi",
- "filedescriptor",
- "mio",
- "parking_lot",
- "rustix 0.38.44",
- "serde",
- "signal-hook",
- "signal-hook-mio",
- "winapi",
-]
-
 [[package]]
 name = "crossterm"
 version = "0.29.0"
@@ -1371,9 +1477,11 @@ dependencies = [
  "crossterm_winapi",
  "derive_more 2.1.1",
  "document-features",
+ "filedescriptor",
  "mio",
  "parking_lot",
- "rustix 1.1.4",
+ "rustix",
+ "serde",
  "signal-hook",
  "signal-hook-mio",
  "winapi",
@@ -1388,12 +1496,6 @@ dependencies = [
  "winapi",
 ]
 
-[[package]]
-name = "crunchy"
-version = "0.2.4"
-source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "460fbee9c2c2f33933d720630a6a0bac33ba7053db5344fac858d4b8952d77d5"
-
 [[package]]
 name = "crypto-common"
 version = "0.1.7"
@@ -1405,6 +1507,15 @@ dependencies = [
  "typenum",
 ]
 
+[[package]]
+name = "crypto-common"
+version = "0.2.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "ce6e4c961d6cd6c9a86db418387425e8bdeaf05b3c8bc1411e6dca4c252f1453"
+dependencies = [
+ "hybrid-array",
+]
+
 [[package]]
 name = "cssparser"
 version = "0.34.0"
@@ -1428,6 +1539,42 @@ dependencies = [
  "syn",
 ]
 
+[[package]]
+name = "ctutils"
+version = "0.4.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "7d5515a3834141de9eafb9717ad39eea8247b5674e6066c404e8c4b365d2a29e"
+dependencies = [
+ "cmov",
+]
+
+[[package]]
+name = "curve25519-dalek"
+version = "4.1.3"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "97fb8b7c4503de7d6ae7b42ab72a5a59857b4c937ec27a3d4539dba95b5ab2be"
+dependencies = [
+ "cfg-if",
+ "cpufeatures 0.2.17",
+ "curve25519-dalek-derive",
+ "digest 0.10.7",
+ "fiat-crypto",
+ "rustc_version",
+ "subtle",
+ "zeroize",
+]
+
+[[package]]
+name = "curve25519-dalek-derive"
+version = "0.1.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "f46882e17999c6cc590af592290432be3bce0428cb0d5f8b6715e4dc7b383eb3"
+dependencies = [
+ "proc-macro2",
+ "quote",
+ "syn",
+]
+
 [[package]]
 name = "darling"
 version = "0.20.11"
@@ -1497,6 +1644,16 @@ dependencies = [
  "syn",
 ]
 
+[[package]]
+name = "der"
+version = "0.7.10"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "e7c1832837b905bbfb5101e07cc24c8deddf52f93225eee6ead5f4d63d53ddcb"
+dependencies = [
+ "const-oid 0.9.6",
+ "zeroize",
+]
+
 [[package]]
 name = "deranged"
 version = "0.5.8"
@@ -1507,6 +1664,17 @@ dependencies = [
  "serde_core",
 ]
 
+[[package]]
+name = "derive_arbitrary"
+version = "1.4.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "1e567bd82dcff979e4b03460c307b3cdc9e96fde3d73bed1496d2bc75d9dd62a"
+dependencies = [
+ "proc-macro2",
+ "quote",
+ "syn",
+]
+
 [[package]]
 name = "derive_more"
 version = "0.99.20"
@@ -1518,34 +1686,13 @@ dependencies = [
  "syn",
 ]
 
-[[package]]
-name = "derive_more"
-version = "1.0.0"
-source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "4a9b99b9cbbe49445b21764dc0625032a89b145a2642e67603e1c936f5458d05"
-dependencies = [
- "derive_more-impl 1.0.0",
-]
-
 [[package]]
 name = "derive_more"
 version = "2.1.1"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "d751e9e49156b02b44f9c1815bcb94b984cdcc4396ecc32521c739452808b134"
 dependencies = [
- "derive_more-impl 2.1.1",
-]
-
-[[package]]
-name = "derive_more-impl"
-version = "1.0.0"
-source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "cb7330aeadfbe296029522e6c40f315320aba36fc43a5b3632f3795348f3bd22"
-dependencies = [
- "proc-macro2",
- "quote",
- "syn",
- "unicode-xid",
+ "derive_more-impl",
 ]
 
 [[package]]
@@ -1598,11 +1745,23 @@ version = "0.10.7"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "9ed9a281f7bc9b7576e61468ba615a66a5c8cfdff42420a70aa82701a3b1e292"
 dependencies = [
- "block-buffer",
- "crypto-common",
+ "block-buffer 0.10.4",
+ "crypto-common 0.1.7",
  "subtle",
 ]
 
+[[package]]
+name = "digest"
+version = "0.11.3"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "f1dd6dbb5841937940781866fa1281a1ff7bd3bf827091440879f9994983d5c2"
+dependencies = [
+ "block-buffer 0.12.0",
+ "const-oid 0.10.2",
+ "crypto-common 0.2.2",
+ "ctutils",
+]
+
 [[package]]
 name = "dirs"
 version = "6.0.0"
@@ -1699,6 +1858,31 @@ version = "1.0.20"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "d0881ea181b1df73ff77ffaaf9c7544ecc11e82fba9b5f27b262a3c73a332555"
 
+[[package]]
+name = "ed25519"
+version = "2.2.3"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "115531babc129696a58c64a4fef0a8bf9e9698629fb97e9e40767d235cfbcd53"
+dependencies = [
+ "pkcs8",
+ "signature",
+]
+
+[[package]]
+name = "ed25519-dalek"
+version = "2.2.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "70e796c081cee67dc755e1a36a0a172b897fab85fc3f6bc48307991f64e4eca9"
+dependencies = [
+ "curve25519-dalek",
+ "ed25519",
+ "serde",
+ "sha2 0.10.9",
+ "signature",
+ "subtle",
+ "zeroize",
+]
+
 [[package]]
 name = "ego-tree"
 version = "0.10.0"
@@ -1707,9 +1891,9 @@ checksum = "b2972feb8dffe7bc8c5463b1dacda1b0dfbed3710e50f977d965429692d74cd8"
 
 [[package]]
 name = "either"
-version = "1.15.0"
+version = "1.16.0"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "48c757948c5ede0e46177b7add2e67155f70e33c07fea8284df6576da70b3719"
+checksum = "91622ff5e7162018101f2fea40d6ebf4a78bbe5a49736a2020649edf9693679e"
 
 [[package]]
 name = "encode_unicode"
@@ -1717,6 +1901,15 @@ version = "1.0.0"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "34aa73646ffb006b8f5147f3dc182bd4bcb190227ce861fc4a4844bf8e3cb2c0"
 
+[[package]]
+name = "encoding_rs"
+version = "0.8.35"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "75030f3c4f45dafd7586dd6780965a8c7e8e285a5ecb86713e63a79c5b2766f3"
+dependencies = [
+ "cfg-if",
+]
+
 [[package]]
 name = "enum-as-inner"
 version = "0.6.1"
@@ -1830,9 +2023,9 @@ dependencies = [
 
 [[package]]
 name = "fastrand"
-version = "2.3.0"
+version = "2.4.1"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "37909eebbb50d72f9059c3b6d82c0463f2ff062c9e95845c43a6c9c0355411be"
+checksum = "9f1f227452a390804cdb637b74a86990f2a7d7ba4b7d5693aac9b4dd6defd8d6"
 
 [[package]]
 name = "fd-lock"
@@ -1841,10 +2034,16 @@ source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "0ce92ff622d6dadf7349484f42c93271a0d49b7cc4d466a936405bacbe10aa78"
 dependencies = [
  "cfg-if",
- "rustix 1.1.4",
+ "rustix",
  "windows-sys 0.59.0",
 ]
 
+[[package]]
+name = "fiat-crypto"
+version = "0.2.9"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "28dea519a9695b9977216879a3ebfddf92f1c08c05d984f8996aecd6ecdc811d"
+
 [[package]]
 name = "filedescriptor"
 version = "0.8.3"
@@ -1856,6 +2055,16 @@ dependencies = [
  "winapi",
 ]
 
+[[package]]
+name = "filetime"
+version = "0.2.29"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "5c287a33c7f0a620c38e641e7f60827713987b3c0f26e8ddc9462cc69cf75759"
+dependencies = [
+ "cfg-if",
+ "libc",
+]
+
 [[package]]
 name = "find-msvc-tools"
 version = "0.1.9"
@@ -1876,6 +2085,7 @@ checksum = "843fba2746e448b37e26a819579957415c8cef339bf08564fe8b7ddbd959573c"
 dependencies = [
  "crc32fast",
  "miniz_oxide",
+ "zlib-rs",
 ]
 
 [[package]]
@@ -2001,12 +2211,6 @@ version = "0.3.32"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "037711b3d59c33004d3856fbdc83b99d4ff37a24768fa1be9ce3538a1cde4393"
 
-[[package]]
-name = "futures-timer"
-version = "3.0.3"
-source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "f288b0a4f20f9a56b5d1da57e2227c661b7b16168e2f72365f57b63326e29b24"
-
 [[package]]
 name = "futures-util"
 version = "0.3.32"
@@ -2057,7 +2261,7 @@ dependencies = [
  "once_cell",
  "prost",
  "prost-types",
- "reqwest",
+ "reqwest 0.12.28",
  "secret-vault-value",
  "serde",
  "serde_json",
@@ -2070,21 +2274,6 @@ dependencies = [
  "url",
 ]
 
-[[package]]
-name = "generator"
-version = "0.8.8"
-source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "52f04ae4152da20c76fe800fa48659201d5cf627c5149ca0b707b69d7eef6cf9"
-dependencies = [
- "cc",
- "cfg-if",
- "libc",
- "log",
- "rustversion",
- "windows-link",
- "windows-result",
-]
-
 [[package]]
 name = "generic-array"
 version = "0.14.7"
@@ -2101,19 +2290,10 @@ version = "1.1.0"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "1bd49230192a3797a9a4d6abe9b3eed6f7fa4c8a8a4947977c6f80025f92cbd8"
 dependencies = [
- "rustix 1.1.4",
+ "rustix",
  "windows-link",
 ]
 
-[[package]]
-name = "getopts"
-version = "0.2.24"
-source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "cfe4fbac503b8d1f88e6676011885f34b7174f46e59956bba534ba83abded4df"
-dependencies = [
- "unicode-width",
-]
-
 [[package]]
 name = "getrandom"
 version = "0.2.17"
@@ -2150,6 +2330,7 @@ dependencies = [
  "cfg-if",
  "libc",
  "r-efi 6.0.0",
+ "rand_core 0.10.1",
  "wasip2",
  "wasip3",
 ]
@@ -2168,15 +2349,15 @@ checksum = "0cc23270f6e1808e30a928bdc84dea0b9b4136a8bc82338574f23baf47bbd280"
 
 [[package]]
 name = "gman"
-version = "0.3.0"
+version = "0.4.1"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "c7c3a428900217107275faf709b30c00f37e1112ec2b75742987b5ca88700eaa"
+checksum = "742225eb41061a0938aa0924ce8d08a1ec48875789b72ce3f0cb02eda52ab1db"
 dependencies = [
  "anyhow",
  "argon2",
  "async-trait",
  "aws-config",
- "aws-lc-sys 0.37.1",
+ "aws-lc-sys 0.39.1",
  "aws-sdk-secretsmanager",
  "azure_core",
  "azure_identity",
@@ -2189,7 +2370,7 @@ dependencies = [
  "clap_complete",
  "confy",
  "crc32c",
- "crossterm 0.29.0",
+ "crossterm",
  "dialoguer",
  "dirs",
  "futures",
@@ -2226,7 +2407,7 @@ dependencies = [
  "futures-sink",
  "futures-util",
  "http 0.2.12",
- "indexmap 2.13.0",
+ "indexmap 2.14.0",
  "slab",
  "tokio",
  "tokio-util",
@@ -2235,9 +2416,9 @@ dependencies = [
 
 [[package]]
 name = "h2"
-version = "0.4.13"
+version = "0.4.14"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "2f44da3a8150a6703ed5d34e164b875fd14c2cdab9af1252a9a1020bde2bdc54"
+checksum = "171fefbc92fe4a4de27e0698d6a5b392d6a0e333506bc49133760b3bcf948733"
 dependencies = [
  "atomic-waker",
  "bytes",
@@ -2245,7 +2426,7 @@ dependencies = [
  "futures-core",
  "futures-sink",
  "http 1.4.0",
- "indexmap 2.13.0",
+ "indexmap 2.14.0",
  "slab",
  "tokio",
  "tokio-util",
@@ -2258,15 +2439,6 @@ version = "0.12.3"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "8a9ee70c43aaf417c914396645a0fa852624801b24ebb7ae78fe8272889ac888"
 
-[[package]]
-name = "hashbrown"
-version = "0.14.5"
-source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "e5274423e17b7c9fc20b6e7e208532f9b19825d82dfd615708b70edd83df41f1"
-dependencies = [
- "ahash",
-]
-
 [[package]]
 name = "hashbrown"
 version = "0.15.5"
@@ -2280,9 +2452,9 @@ dependencies = [
 
 [[package]]
 name = "hashbrown"
-version = "0.16.1"
+version = "0.17.1"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "841d1cc9bed7f9236f321df977030373f4a4163ae1a7dbfe1a51a2c1a51d9100"
+checksum = "ed5909b6e89a2db4456e54cd5f673791d7eca6732202bbf2a9cc504fe2f9b84a"
 
 [[package]]
 name = "heck"
@@ -2308,7 +2480,16 @@ version = "0.12.1"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "6c49c37c09c17a53d937dfbb742eb3a961d65a994e6bcdcf37e7399d0cc8ab5e"
 dependencies = [
- "digest",
+ "digest 0.10.7",
+]
+
+[[package]]
+name = "hmac"
+version = "0.13.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "6303bc9732ae41b04cb554b844a762b4115a61bfaa81e3e83050991eeb56863f"
+dependencies = [
+ "digest 0.11.3",
 ]
 
 [[package]]
@@ -2324,14 +2505,14 @@ dependencies = [
  "cpu-time",
  "env_logger",
  "hashbrown 0.15.5",
- "indexmap 2.13.0",
+ "indexmap 2.14.0",
  "lazy_static",
  "log",
  "mmap-rs",
  "num-traits",
  "num_cpus",
  "parking_lot",
- "rand 0.9.2",
+ "rand 0.9.4",
  "rayon",
  "serde",
 ]
@@ -2472,6 +2653,15 @@ version = "2.3.0"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "135b12329e5e3ce057a9f972339ea52bc954fe1e9358ef27f95e89716fbc5424"
 
+[[package]]
+name = "hybrid-array"
+version = "0.4.12"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "9155a582abd142abc056962c29e3ce5ff2ad5469f4246b537ed42c5deba857da"
+dependencies = [
+ "typenum",
+]
+
 [[package]]
 name = "hyper"
 version = "0.14.32"
@@ -2506,7 +2696,7 @@ dependencies = [
  "bytes",
  "futures-channel",
  "futures-core",
- "h2 0.4.13",
+ "h2 0.4.14",
  "http 1.4.0",
  "http-body 1.0.1",
  "httparse",
@@ -2535,20 +2725,18 @@ dependencies = [
 
 [[package]]
 name = "hyper-rustls"
-version = "0.27.7"
+version = "0.27.9"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "e3c93eb611681b207e1fe55d5a71ecf91572ec8a6705cdb6857f7d8d5242cf58"
+checksum = "33ca68d021ef39cf6463ab54c1d0f5daf03377b70561305bb89a8f83aab66e0f"
 dependencies = [
  "http 1.4.0",
  "hyper 1.9.0",
  "hyper-util",
- "rustls 0.23.37",
+ "rustls 0.23.40",
  "rustls-native-certs",
- "rustls-pki-types",
  "tokio",
  "tokio-rustls 0.26.4",
  "tower-service",
- "webpki-roots",
 ]
 
 [[package]]
@@ -2734,9 +2922,9 @@ dependencies = [
 
 [[package]]
 name = "idna_adapter"
-version = "1.2.1"
+version = "1.2.2"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "3acae9609540aa318d1bc588455225fb2085b9ed0c4f6bd0d9d5bcd86f1a0344"
+checksum = "cb68373c0d6620ef8105e855e7745e18b0d00d3bdb07fb532e434244cdb9a714"
 dependencies = [
  "icu_normalizer",
  "icu_properties",
@@ -2755,16 +2943,29 @@ dependencies = [
 
 [[package]]
 name = "indexmap"
-version = "2.13.0"
+version = "2.14.0"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "7714e70437a7dc3ac8eb7e6f8df75fd8eb422675fc7678aff7364301092b1017"
+checksum = "d466e9454f08e4a911e14806c24e16fba1b4c121d1ea474396f396069cf949d9"
 dependencies = [
  "equivalent",
- "hashbrown 0.16.1",
+ "hashbrown 0.17.1",
  "serde",
  "serde_core",
 ]
 
+[[package]]
+name = "indicatif"
+version = "0.18.4"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "25470f23803092da7d239834776d653104d551bc4d7eacaf31e6837854b8e9eb"
+dependencies = [
+ "console",
+ "portable-atomic",
+ "unicode-width",
+ "unit-prefix",
+ "web-time",
+]
+
 [[package]]
 name = "indoc"
 version = "2.0.7"
@@ -2790,7 +2991,7 @@ source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "6654738b8024300cf062d04a1c13c10c8e2cea598ec1c47dc9b6641159429756"
 dependencies = [
  "bitflags",
- "crossterm 0.29.0",
+ "crossterm",
  "dyn-clone",
  "fuzzy-matcher",
  "unicode-segmentation",
@@ -2803,16 +3004,6 @@ version = "2.12.0"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "d98f6fed1fde3f8c21bc40a1abb88dd75e67924f9cffc3ef95607bad8017f8e2"
 
-[[package]]
-name = "iri-string"
-version = "0.7.12"
-source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "25e659a4bb38e810ebc252e53b5814ff908a8c58c2a9ce2fae1bbec24cbf4e20"
-dependencies = [
- "memchr",
- "serde",
-]
-
 [[package]]
 name = "is-docker"
 version = "0.2.0"
@@ -2822,18 +3013,6 @@ dependencies = [
  "once_cell",
 ]
 
-[[package]]
-name = "is-macro"
-version = "0.3.7"
-source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "1d57a3e447e24c22647738e4607f1df1e0ec6f72e16182c4cd199f647cdfb0e4"
-dependencies = [
- "heck",
- "proc-macro2",
- "quote",
- "syn",
-]
-
 [[package]]
 name = "is-terminal"
 version = "0.4.17"
@@ -2870,15 +3049,6 @@ version = "1.70.2"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "a6cb138bb79a146c1bd460005623e142ef0181e3d0219cb493e02f7d08a35695"
 
-[[package]]
-name = "itertools"
-version = "0.11.0"
-source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "b1c173a5686ce8bfa551b3563d0c2170bf24ca44da99c7ca4bfdab5418c3fe57"
-dependencies = [
- "either",
-]
-
 [[package]]
 name = "itertools"
 version = "0.13.0"
@@ -2905,9 +3075,9 @@ checksum = "8f42a60cbdf9a97f5d2305f08a87dc4e09308d1276d28c869c684d7777685682"
 
 [[package]]
 name = "jiff"
-version = "0.2.23"
+version = "0.2.24"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "1a3546dc96b6d42c5f24902af9e2538e82e39ad350b0c766eb3fbf2d8f3d8359"
+checksum = "f00b5dbd620d61dfdcb6007c9c1f6054ebd75319f163d886a9055cec1155073d"
 dependencies = [
  "jiff-static",
  "log",
@@ -2918,15 +3088,64 @@ dependencies = [
 
 [[package]]
 name = "jiff-static"
-version = "0.2.23"
+version = "0.2.24"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "2a8c8b344124222efd714b73bb41f8b5120b27a7cc1c75593a6ff768d9d05aa4"
+checksum = "e000de030ff8022ea1da3f466fbb0f3a809f5e51ed31f6dd931c35181ad8e6d7"
 dependencies = [
  "proc-macro2",
  "quote",
  "syn",
 ]
 
+[[package]]
+name = "jni"
+version = "0.22.4"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "5efd9a482cf3a427f00d6b35f14332adc7902ce91efb778580e180ff90fa3498"
+dependencies = [
+ "cfg-if",
+ "combine",
+ "jni-macros",
+ "jni-sys",
+ "log",
+ "simd_cesu8",
+ "thiserror 2.0.18",
+ "walkdir",
+ "windows-link",
+]
+
+[[package]]
+name = "jni-macros"
+version = "0.22.4"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "a00109accc170f0bdb141fed3e393c565b6f5e072365c3bd58f5b062591560a3"
+dependencies = [
+ "proc-macro2",
+ "quote",
+ "rustc_version",
+ "simd_cesu8",
+ "syn",
+]
+
+[[package]]
+name = "jni-sys"
+version = "0.4.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "c6377a88cb3910bee9b0fa88d4f42e1d2da8e79915598f65fb0c7ee14c878af2"
+dependencies = [
+ "jni-sys-macros",
+]
+
+[[package]]
+name = "jni-sys-macros"
+version = "0.4.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "38c0b942f458fe50cdac086d2f946512305e5631e720728f2a61aabcd47a6264"
+dependencies = [
+ "quote",
+ "syn",
+]
+
 [[package]]
 name = "jobserver"
 version = "0.1.34"
@@ -2939,9 +3158,9 @@ dependencies = [
 
 [[package]]
 name = "js-sys"
-version = "0.3.94"
+version = "0.3.99"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "2e04e2ef80ce82e13552136fabeef8a5ed1f985a96805761cbb9a2c34e7664d9"
+checksum = "142bc4740e452c1e57ade0cbc129f139c9093e354346f0872ef985f4f5cf5f11"
 dependencies = [
  "cfg-if",
  "futures-util",
@@ -2951,14 +3170,14 @@ dependencies = [
 
 [[package]]
 name = "json-patch"
-version = "4.1.0"
+version = "4.2.0"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "f300e415e2134745ef75f04562dd0145405c2f7fd92065db029ac4b16b57fe90"
+checksum = "7421438de105a0827e44fadd05377727847d717c80ce29a229f85fd04c427b72"
 dependencies = [
  "jsonptr",
  "serde",
  "serde_json",
- "thiserror 1.0.69",
+ "thiserror 2.0.18",
 ]
 
 [[package]]
@@ -2973,9 +3192,9 @@ dependencies = [
 
 [[package]]
 name = "jsonwebtoken"
-version = "10.3.0"
+version = "10.4.0"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "0529410abe238729a60b108898784df8984c87f6054c9c4fcacc47e4803c1ce1"
+checksum = "eba32bfb4ffdeaca3e34431072faf01745c9b26d25504aa7a6cf5684334fc4fc"
 dependencies = [
  "base64",
  "getrandom 0.2.17",
@@ -2985,14 +3204,9 @@ dependencies = [
  "serde_json",
  "signature",
  "simple_asn1",
+ "zeroize",
 ]
 
-[[package]]
-name = "lalrpop-util"
-version = "0.20.2"
-source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "507460a910eb7b32ee961886ff48539633b788a36b65692b95f225b844c82553"
-
 [[package]]
 name = "lazy_static"
 version = "1.5.0"
@@ -3007,9 +3221,9 @@ checksum = "09edd9e8b54e49e587e4f6295a7d29c3ea94d469cb40ab8ca70b288248a81db2"
 
 [[package]]
 name = "libc"
-version = "0.2.184"
+version = "0.2.186"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "48f5d2a454e16a5ea0f4ced81bd44e4cfc7bd3a507b61887c99fd3538b28e4af"
+checksum = "68ab91017fe16c622486840e4c83c9a37afeff978bd239b5293d61ece587de66"
 
 [[package]]
 name = "libloading"
@@ -3021,27 +3235,15 @@ dependencies = [
  "windows-link",
 ]
 
-[[package]]
-name = "libm"
-version = "0.2.16"
-source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "b6d2cec3eae94f9f509c767b45932f1ada8350c4bdb85af2fcab4a3c14807981"
-
 [[package]]
 name = "libredox"
-version = "0.1.15"
+version = "0.1.16"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "7ddbf48fd451246b1f8c2610bd3b4ac0cc6e149d89832867093ab69a17194f08"
+checksum = "e02f3bb43d335493c96bf3fd3a321600bf6bd07ed34bc64118e9293bdffea46c"
 dependencies = [
  "libc",
 ]
 
-[[package]]
-name = "linux-raw-sys"
-version = "0.4.15"
-source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "d26c52dbd32dccf2d10cac7725f8eae5296885fb5703b261f7d0a0739ec807ab"
-
 [[package]]
 name = "linux-raw-sys"
 version = "0.12.1"
@@ -3101,7 +3303,7 @@ dependencies = [
  "log-mdc",
  "mock_instant",
  "parking_lot",
- "rand 0.9.2",
+ "rand 0.9.4",
  "serde",
  "serde-value",
  "serde_json",
@@ -3134,21 +3336,20 @@ dependencies = [
  "clap_complete",
  "clap_complete_nushell",
  "colored",
- "crossterm 0.28.1",
+ "crossterm",
  "dirs",
  "duct",
+ "dunce",
+ "eventsource-stream",
  "fancy-regex",
  "futures-util",
  "fuzzy-matcher",
  "gman",
- "hmac",
+ "hmac 0.12.1",
  "hnsw_rs",
  "html_to_markdown",
  "http 1.4.0",
- "http-body-util",
- "hyper 1.9.0",
- "hyper-util",
- "indexmap 2.13.0",
+ "indexmap 2.14.0",
  "indoc",
  "inquire",
  "is-terminal",
@@ -3162,31 +3363,28 @@ dependencies = [
  "parking_lot",
  "path-absolutize",
  "pretty_assertions",
- "rand 0.9.2",
- "rayon",
+ "rand 0.10.1",
  "reedline",
- "reqwest",
- "reqwest-eventsource",
+ "reqwest 0.13.3",
  "rmcp",
  "rust-embed",
- "rustpython-ast",
- "rustpython-parser",
  "scraper",
+ "self_update",
  "serde",
  "serde_json",
  "serde_yaml",
- "sha2",
+ "serial_test",
+ "sha2 0.10.9",
  "shell-words",
- "strum_macros 0.27.2",
+ "strum_macros",
  "syntect",
  "sys-locale",
  "terminal-colorsaurus",
  "textwrap",
- "time",
  "tokio",
- "tokio-graceful",
- "tokio-stream",
- "unicode-segmentation",
+ "tree-sitter",
+ "tree-sitter-python",
+ "tree-sitter-typescript",
  "unicode-width",
  "url",
  "urlencoding",
@@ -3194,22 +3392,6 @@ dependencies = [
  "which",
 ]
 
-[[package]]
-name = "loom"
-version = "0.7.2"
-source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "419e0dc8046cb947daa77eb95ae174acfbddb7673b4151f56d1eed8e93fbfaca"
-dependencies = [
- "cfg-if",
- "generator",
- "pin-utils",
- "scoped-tls",
- "serde",
- "serde_json",
- "tracing",
- "tracing-subscriber",
-]
-
 [[package]]
 name = "lru-slab"
 version = "0.1.2"
@@ -3231,64 +3413,6 @@ dependencies = [
  "libc",
 ]
 
-[[package]]
-name = "malachite"
-version = "0.4.22"
-source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "2fbdf9cb251732db30a7200ebb6ae5d22fe8e11397364416617d2c2cf0c51cb5"
-dependencies = [
- "malachite-base",
- "malachite-nz",
- "malachite-q",
-]
-
-[[package]]
-name = "malachite-base"
-version = "0.4.22"
-source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "5ea0ed76adf7defc1a92240b5c36d5368cfe9251640dcce5bd2d0b7c1fd87aeb"
-dependencies = [
- "hashbrown 0.14.5",
- "itertools 0.11.0",
- "libm",
- "ryu",
-]
-
-[[package]]
-name = "malachite-bigint"
-version = "0.2.3"
-source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "d149aaa2965d70381709d9df4c7ee1fc0de1c614a4efc2ee356f5e43d68749f8"
-dependencies = [
- "derive_more 1.0.0",
- "malachite",
- "num-integer",
- "num-traits",
- "paste",
-]
-
-[[package]]
-name = "malachite-nz"
-version = "0.4.22"
-source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "34a79feebb2bc9aa7762047c8e5495269a367da6b5a90a99882a0aeeac1841f7"
-dependencies = [
- "itertools 0.11.0",
- "libm",
- "malachite-base",
-]
-
-[[package]]
-name = "malachite-q"
-version = "0.4.22"
-source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "50f235d5747b1256b47620f5640c2a17a88c7569eebdf27cd9cb130e1a619191"
-dependencies = [
- "itertools 0.11.0",
- "malachite-base",
- "malachite-nz",
-]
-
 [[package]]
 name = "markup5ever"
 version = "0.12.1"
@@ -3340,15 +3464,6 @@ dependencies = [
  "syn",
 ]
 
-[[package]]
-name = "matchers"
-version = "0.2.0"
-source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "d1525a2a28c7f4fa0fc98bb91ae755d1e2d1505079e05539e35bc876b5d65ae9"
-dependencies = [
- "regex-automata",
-]
-
 [[package]]
 name = "matchit"
 version = "0.8.4"
@@ -3471,9 +3586,9 @@ dependencies = [
 
 [[package]]
 name = "nix"
-version = "0.31.2"
+version = "0.31.3"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "5d6d0705320c1e6ba1d912b5e37cf18071b6c2e9b7fa8215a1e8a7651966f5d3"
+checksum = "cf20d2fde8ff38632c426f1165ed7436270b44f199fc55284c38276f9db47c3d"
 dependencies = [
  "bitflags",
  "cfg-if",
@@ -3530,9 +3645,9 @@ dependencies = [
 
 [[package]]
 name = "num-conv"
-version = "0.2.1"
+version = "0.2.2"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "c6673768db2d862beb9b39a78fdcb1a69439615d5794a1be50caa9bc92c81967"
+checksum = "521739c6d2bac4aa25192232afe6841231376b2b26d4d9fae5ecf8ca5772e441"
 
 [[package]]
 name = "num-integer"
@@ -3766,9 +3881,9 @@ checksum = "384b8ab6d37215f3c5301a95a4accb5d64aa607f1fcb26a11b5303878451b4fe"
 
 [[package]]
 name = "onig"
-version = "6.5.1"
+version = "6.5.3"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "336b9c63443aceef14bea841b899035ae3abe89b7c486aaf4c5bd8aafedac3f0"
+checksum = "0cc3cbf698f9438986c11a880c90a6d04b9de27575afd28bbf45b154b6c709e2"
 dependencies = [
  "bitflags",
  "libc",
@@ -3778,9 +3893,9 @@ dependencies = [
 
 [[package]]
 name = "onig_sys"
-version = "69.9.1"
+version = "69.9.3"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "c7f86c6eef3d6df15f23bcfb6af487cbd2fed4e5581d58d5bf1f5f8b7f6727dc"
+checksum = "1e68317604e77e53b85896388e1a803c1d21b74c899ec9e5e1112db90735edd7"
 dependencies = [
  "cc",
  "pkg-config",
@@ -3794,9 +3909,9 @@ checksum = "c08d65885ee38876c4f86fa503fb49d7b507c2b62552df7c70b2fce627e06381"
 
 [[package]]
 name = "open"
-version = "5.3.3"
+version = "5.3.5"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "43bb73a7fa3799b198970490a51174027ba0d4ec504b03cd08caf513d40024bc"
+checksum = "2fbaa89d2ddc8473c78a3adf69eea8cffa28c483b8e02a971ef31527cd0fc92c"
 dependencies = [
  "is-wsl",
  "libc",
@@ -3805,15 +3920,14 @@ dependencies = [
 
 [[package]]
 name = "openssl"
-version = "0.10.76"
+version = "0.10.80"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "951c002c75e16ea2c65b8c7e4d3d51d5530d8dfa7d060b4776828c88cfb18ecf"
+checksum = "a45fa2aa886c42762255da344f0a0d313e254066c46aad76f300c3d3da62d967"
 dependencies = [
  "bitflags",
  "cfg-if",
  "foreign-types",
  "libc",
- "once_cell",
  "openssl-macros",
  "openssl-sys",
 ]
@@ -3837,18 +3951,18 @@ checksum = "7c87def4c32ab89d880effc9e097653c8da5d6ef28e6b539d313baaacfbafcbe"
 
 [[package]]
 name = "openssl-src"
-version = "300.5.5+3.5.5"
+version = "300.6.0+3.6.2"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "3f1787d533e03597a7934fd0a765f0d28e94ecc5fb7789f8053b1e699a56f709"
+checksum = "a8e8cbfd3a4a8c8f089147fd7aaa33cf8c7450c4d09f8f80698a0cf093abeff4"
 dependencies = [
  "cc",
 ]
 
 [[package]]
 name = "openssl-sys"
-version = "0.9.112"
+version = "0.9.116"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "57d55af3b3e226502be1526dfdba67ab0e9c96fc293004e79576b2b9edb0dbdb"
+checksum = "f28a22dc7140cda5f096e5e7724a6962ca81a7f8bfd2979f9b18c11af56318c4"
 dependencies = [
  "cc",
  "libc",
@@ -3874,13 +3988,13 @@ dependencies = [
 
 [[package]]
 name = "os_info"
-version = "3.14.0"
+version = "3.15.0"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "e4022a17595a00d6a369236fdae483f0de7f0a339960a53118b818238e132224"
+checksum = "9cf20a545b305cf1da722b236b5155c9bb35f1d5ceb28c048bd96ca842f41b5b"
 dependencies = [
  "android_system_properties",
  "log",
- "nix 0.30.1",
+ "nix 0.31.3",
  "objc2",
  "objc2-foundation",
  "objc2-ui-kit",
@@ -3943,17 +4057,11 @@ dependencies = [
  "subtle",
 ]
 
-[[package]]
-name = "paste"
-version = "1.0.15"
-source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "57c0d7b74b563b49d38dae00a0c37d4d6de9b432382b2892f0574ddcae73fd0a"
-
 [[package]]
 name = "pastey"
-version = "0.2.1"
+version = "0.2.3"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "b867cad97c0791bbd3aaa6472142568c6c9e8f71937e98379f584cfb0cf35bec"
+checksum = "2ee67f1008b1ba2321834326597b8e186293b049a023cdef258527550b9935b4"
 
 [[package]]
 name = "path-absolutize"
@@ -4003,7 +4111,7 @@ checksum = "8701b58ea97060d5e5b155d383a69952a60943f0e6dfe30b04c287beb0b27455"
 dependencies = [
  "fixedbitset",
  "hashbrown 0.15.5",
- "indexmap 2.13.0",
+ "indexmap 2.14.0",
 ]
 
 [[package]]
@@ -4033,7 +4141,7 @@ source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "3c80231409c20246a13fddb31776fb942c38553c51e871f8cbd687a4cfb5843d"
 dependencies = [
  "phf_shared",
- "rand 0.8.5",
+ "rand 0.8.6",
 ]
 
 [[package]]
@@ -4060,18 +4168,18 @@ dependencies = [
 
 [[package]]
 name = "pin-project"
-version = "1.1.11"
+version = "1.1.13"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "f1749c7ed4bcaf4c3d0a3efc28538844fb29bcdd7d2b67b2be7e20ba861ff517"
+checksum = "2466b2336ed02bcdca6b294417127b90ec92038d1d5c4fbeac971a922e0e0924"
 dependencies = [
  "pin-project-internal",
 ]
 
 [[package]]
 name = "pin-project-internal"
-version = "1.1.11"
+version = "1.1.13"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "d9b20ed30f105399776b9c883e68e536ef602a16ae6f596d2c473591d6ad64c6"
+checksum = "c96395f0a926bc13b1c17622aaddda1ecb55d49c8f1bf9777e4d877800a43f8b"
 dependencies = [
  "proc-macro2",
  "quote",
@@ -4091,20 +4199,30 @@ source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "8b870d8c151b6f2fb93e84a13146138f05d02ed11c7e7c54f8826aaaf7c9f184"
 
 [[package]]
-name = "pkg-config"
-version = "0.3.32"
+name = "pkcs8"
+version = "0.10.2"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "7edddbd0b52d732b21ad9a5fab5c704c14cd949e5e9a1ec5929a24fded1b904c"
+checksum = "f950b2377845cebe5cf8b5165cb3cc1a5e0fa5cfa3e1f7f55707d8fd82e0a7b7"
+dependencies = [
+ "der",
+ "spki",
+]
+
+[[package]]
+name = "pkg-config"
+version = "0.3.33"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "19f132c84eca552bf34cab8ec81f1c1dcc229b811638f9d283dceabe58c5569e"
 
 [[package]]
 name = "plist"
-version = "1.8.0"
+version = "1.9.0"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "740ebea15c5d1428f910cd1a5f52cebf8d25006245ed8ade92702f4943d91e07"
+checksum = "092791278e026273c1b65bbdcfbba3a300f2994c896bd01ab01da613c29c46f1"
 dependencies = [
  "base64",
- "indexmap 2.13.0",
- "quick-xml 0.38.4",
+ "indexmap 2.14.0",
+ "quick-xml 0.39.4",
  "serde",
  "time",
 ]
@@ -4115,7 +4233,7 @@ version = "0.8.0"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "8159bd90725d2df49889a078b54f4f79e87f1f8a8444194cdca81d38f5393abf"
 dependencies = [
- "cpufeatures",
+ "cpufeatures 0.2.17",
  "opaque-debug",
  "universal-hash",
 ]
@@ -4128,9 +4246,9 @@ checksum = "c33a9471896f1c69cecef8d20cbe2f7accd12527ce60845ff44c153bb2a21b49"
 
 [[package]]
 name = "portable-atomic-util"
-version = "0.2.6"
+version = "0.2.7"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "091397be61a01d4be58e7841595bd4bfedb15f1cd54977d79b8271e94ed799a3"
+checksum = "c2a106d1259c23fac8e543272398ae0e3c0b8d33c88ed73d0cc71b0f1d902618"
 dependencies = [
  "portable-atomic",
 ]
@@ -4223,8 +4341,8 @@ source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "2e842efad9119158434d193c6682e2ebee4b44d6ad801d7b349623b3f57cdf55"
 dependencies = [
  "futures",
- "indexmap 2.13.0",
- "nix 0.31.2",
+ "indexmap 2.14.0",
+ "nix 0.31.3",
  "tokio",
  "tracing",
  "windows 0.62.2",
@@ -4273,9 +4391,9 @@ dependencies = [
 
 [[package]]
 name = "quick-xml"
-version = "0.39.2"
+version = "0.39.4"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "958f21e8e7ceb5a1aa7fa87fab28e7c75976e0bfe7e23ff069e0a260f894067d"
+checksum = "cdcc8dd4e2f670d309a5f0e83fe36dfdc05af317008fea29144da1a2ac858e5e"
 dependencies = [
  "memchr",
 ]
@@ -4291,8 +4409,8 @@ dependencies = [
  "pin-project-lite",
  "quinn-proto",
  "quinn-udp",
- "rustc-hash 2.1.2",
- "rustls 0.23.37",
+ "rustc-hash",
+ "rustls 0.23.40",
  "socket2 0.6.3",
  "thiserror 2.0.18",
  "tokio",
@@ -4306,13 +4424,14 @@ version = "0.11.14"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "434b42fec591c96ef50e21e886936e66d3cc3f737104fdb9b737c40ffb94c098"
 dependencies = [
+ "aws-lc-rs",
  "bytes",
  "getrandom 0.3.4",
  "lru-slab",
- "rand 0.9.2",
+ "rand 0.9.4",
  "ring",
- "rustc-hash 2.1.2",
- "rustls 0.23.37",
+ "rustc-hash",
+ "rustls 0.23.40",
  "rustls-pki-types",
  "slab",
  "thiserror 2.0.18",
@@ -4358,33 +4477,32 @@ checksum = "f8dcc9c7d52a811697d2151c701e0d08956f92b0e24136cf4cf27b57a6a0d9bf"
 
 [[package]]
 name = "rand"
-version = "0.8.5"
+version = "0.8.6"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "34af8d1a0e25924bc5b7c43c079c942339d8f0a8b57c39049bef581b46327404"
+checksum = "5ca0ecfa931c29007047d1bc58e623ab12e5590e8c7cc53200d5202b69266d8a"
 dependencies = [
- "libc",
- "rand_chacha 0.3.1",
  "rand_core 0.6.4",
 ]
 
 [[package]]
 name = "rand"
-version = "0.9.2"
+version = "0.9.4"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "6db2770f06117d490610c7488547d543617b21bfa07796d7a12f6f1bd53850d1"
+checksum = "44c5af06bb1b7d3216d91932aed5265164bf384dc89cd6ba05cf59a35f5f76ea"
 dependencies = [
- "rand_chacha 0.9.0",
+ "rand_chacha",
  "rand_core 0.9.5",
 ]
 
 [[package]]
-name = "rand_chacha"
-version = "0.3.1"
+name = "rand"
+version = "0.10.1"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "e6c10a63a0fa32252be49d21e7709d4d4baf8d231c2dbce1eaa8141b9b127d88"
+checksum = "d2e8e8bcc7961af1fdac401278c6a831614941f6164ee3bf4ce61b7edb162207"
 dependencies = [
- "ppv-lite86",
- "rand_core 0.6.4",
+ "chacha20 0.10.0",
+ "getrandom 0.4.2",
+ "rand_core 0.10.1",
 ]
 
 [[package]]
@@ -4416,10 +4534,16 @@ dependencies = [
 ]
 
 [[package]]
-name = "rayon"
-version = "1.11.0"
+name = "rand_core"
+version = "0.10.1"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "368f01d005bf8fd9b1206fb6fa653e6c4a81ceb1466406b81792d87c5677a58f"
+checksum = "63b8176103e19a2643978565ca18b50549f6101881c443590420e4dc998a3c69"
+
+[[package]]
+name = "rayon"
+version = "1.12.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "fb39b166781f92d482534ef4b4b1b2568f42613b53e5b6c160e24cfbfa30926d"
 dependencies = [
  "either",
  "rayon-core",
@@ -4457,20 +4581,20 @@ dependencies = [
 
 [[package]]
 name = "reedline"
-version = "0.40.0"
+version = "0.47.0"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "b5cdfab7494d13ebfb6ce64828648518205d3ce8541ef1f94a27887f29d2d50b"
+checksum = "2066729dce9fecd28d1c6850a159ee68719130f149b22467c362353e16994e90"
 dependencies = [
  "chrono",
- "crossterm 0.28.1",
+ "crossterm",
  "fd-lock",
  "itertools 0.13.0",
  "nu-ansi-term",
  "serde",
  "strip-ansi-escapes",
  "strum",
- "strum_macros 0.26.4",
  "thiserror 2.0.18",
+ "unicase",
  "unicode-segmentation",
  "unicode-width",
 ]
@@ -4544,7 +4668,7 @@ dependencies = [
  "http-body 1.0.1",
  "http-body-util",
  "hyper 1.9.0",
- "hyper-rustls 0.27.7",
+ "hyper-rustls 0.27.9",
  "hyper-tls",
  "hyper-util",
  "js-sys",
@@ -4553,8 +4677,7 @@ dependencies = [
  "native-tls",
  "percent-encoding",
  "pin-project-lite",
- "quinn",
- "rustls 0.23.37",
+ "rustls 0.23.40",
  "rustls-native-certs",
  "rustls-pki-types",
  "serde",
@@ -4571,25 +4694,55 @@ dependencies = [
  "url",
  "wasm-bindgen",
  "wasm-bindgen-futures",
- "wasm-streams",
+ "wasm-streams 0.4.2",
  "web-sys",
- "webpki-roots",
 ]
 
 [[package]]
-name = "reqwest-eventsource"
-version = "0.6.0"
+name = "reqwest"
+version = "0.13.3"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "632c55746dbb44275691640e7b40c907c16a2dc1a5842aa98aaec90da6ec6bde"
+checksum = "62e0021ea2c22aed41653bc7e1419abb2c97e038ff2c33d0e1309e49a97deec0"
 dependencies = [
- "eventsource-stream",
+ "base64",
+ "bytes",
+ "futures-channel",
  "futures-core",
- "futures-timer",
- "mime",
- "nom 7.1.3",
+ "futures-util",
+ "h2 0.4.14",
+ "http 1.4.0",
+ "http-body 1.0.1",
+ "http-body-util",
+ "hyper 1.9.0",
+ "hyper-rustls 0.27.9",
+ "hyper-tls",
+ "hyper-util",
+ "js-sys",
+ "log",
+ "mime_guess",
+ "native-tls",
+ "percent-encoding",
  "pin-project-lite",
- "reqwest",
- "thiserror 1.0.69",
+ "quinn",
+ "rustls 0.23.40",
+ "rustls-pki-types",
+ "rustls-platform-verifier",
+ "serde",
+ "serde_json",
+ "serde_urlencoded",
+ "sync_wrapper",
+ "tokio",
+ "tokio-native-tls",
+ "tokio-rustls 0.26.4",
+ "tokio-util",
+ "tower",
+ "tower-http",
+ "tower-service",
+ "url",
+ "wasm-bindgen",
+ "wasm-bindgen-futures",
+ "wasm-streams 0.5.0",
+ "web-sys",
 ]
 
 [[package]]
@@ -4617,21 +4770,24 @@ dependencies = [
 
 [[package]]
 name = "rmcp"
-version = "0.16.0"
+version = "1.7.0"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "cc4c9c94680f75470ee8083a0667988b5d7b5beb70b9f998a8e51de7c682ce60"
+checksum = "0810a9f717d9828f475fe1f629f4c305c8464b7f496c3a854b58d29e65f4058e"
 dependencies = [
  "async-trait",
  "base64",
  "chrono",
  "futures",
+ "http 1.4.0",
  "pastey",
  "pin-project-lite",
  "process-wrap",
+ "reqwest 0.13.3",
  "rmcp-macros",
  "schemars 1.2.1",
  "serde",
  "serde_json",
+ "sse-stream",
  "thiserror 2.0.18",
  "tokio",
  "tokio-stream",
@@ -4641,9 +4797,9 @@ dependencies = [
 
 [[package]]
 name = "rmcp-macros"
-version = "0.16.0"
+version = "1.7.0"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "90c23c8f26cae4da838fbc3eadfaecf2d549d97c04b558e7bd90526a9c28b42a"
+checksum = "6aefac48c364756e97f04c0401ba3231e8607882c7c1d92da0437dc16307904d"
 dependencies = [
  "darling 0.23.0",
  "proc-macro2",
@@ -4654,29 +4810,29 @@ dependencies = [
 
 [[package]]
 name = "roff"
-version = "0.2.2"
+version = "1.1.1"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "88f8660c1ff60292143c98d08fc6e2f654d722db50410e3f3797d40baaf9d8f3"
+checksum = "323c417e1d9665a65b263ec744ba09030cfb277e9daa0b018a4ab62e57bc8189"
 
 [[package]]
 name = "rpassword"
-version = "7.4.0"
+version = "7.5.3"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "66d4c8b64f049c6721ec8ccec37ddfc3d641c4a7fca57e8f2a89de509c73df39"
+checksum = "835a57a69104632d64deb0df2e09a69945cd7a6eab4070fc9b1d7e50cf6c3edc"
 dependencies = [
  "libc",
  "rtoolbox",
- "windows-sys 0.59.0",
+ "windows-sys 0.61.2",
 ]
 
 [[package]]
 name = "rtoolbox"
-version = "0.0.3"
+version = "0.0.5"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "a7cc970b249fbe527d6e02e0a227762c9108b2f49d81094fe357ffc6d14d7f6f"
+checksum = "50a0e551c1e27e1731aba276dbeaeac73f53c7cd34d1bda485d02bd1e0f36844"
 dependencies = [
  "libc",
- "windows-sys 0.52.0",
+ "windows-sys 0.59.0",
 ]
 
 [[package]]
@@ -4709,7 +4865,7 @@ version = "8.11.0"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "5bcdef0be6fe7f6fa333b1073c949729274b05f123a0ad7efcb8efd878e5c3b1"
 dependencies = [
- "sha2",
+ "sha2 0.10.9",
  "walkdir",
 ]
 
@@ -4729,12 +4885,6 @@ version = "0.1.27"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "b50b8869d9fc858ce7266cce0194bd74df58b9d0e3f6df3a9fc8eb470d95c09d"
 
-[[package]]
-name = "rustc-hash"
-version = "1.1.0"
-source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "08d43f7aa6b08d49f382cde6a7982047c3426db949b1424bc4b7ec9ae12c6ce2"
-
 [[package]]
 name = "rustc-hash"
 version = "2.1.2"
@@ -4750,19 +4900,6 @@ dependencies = [
  "semver",
 ]
 
-[[package]]
-name = "rustix"
-version = "0.38.44"
-source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "fdb5bc1ae2baa591800df16c9ca78619bf65c0488b41b96ccec5d11220d8c154"
-dependencies = [
- "bitflags",
- "errno",
- "libc",
- "linux-raw-sys 0.4.15",
- "windows-sys 0.59.0",
-]
-
 [[package]]
 name = "rustix"
 version = "1.1.4"
@@ -4772,7 +4909,7 @@ dependencies = [
  "bitflags",
  "errno",
  "libc",
- "linux-raw-sys 0.12.1",
+ "linux-raw-sys",
  "windows-sys 0.61.2",
 ]
 
@@ -4790,16 +4927,16 @@ dependencies = [
 
 [[package]]
 name = "rustls"
-version = "0.23.37"
+version = "0.23.40"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "758025cb5fccfd3bc2fd74708fd4682be41d99e5dff73c377c0646c6012c73a4"
+checksum = "ef86cd5876211988985292b91c96a8f2d298df24e75989a43a3c73f2d4d8168b"
 dependencies = [
  "aws-lc-rs",
  "log",
  "once_cell",
  "ring",
  "rustls-pki-types",
- "rustls-webpki 0.103.10",
+ "rustls-webpki 0.103.13",
  "subtle",
  "zeroize",
 ]
@@ -4818,14 +4955,41 @@ dependencies = [
 
 [[package]]
 name = "rustls-pki-types"
-version = "1.14.0"
+version = "1.14.1"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "be040f8b0a225e40375822a563fa9524378b9d63112f53e19ffff34df5d33fdd"
+checksum = "30a7197ae7eb376e574fe940d068c30fe0462554a3ddbe4eca7838e049c937a9"
 dependencies = [
  "web-time",
  "zeroize",
 ]
 
+[[package]]
+name = "rustls-platform-verifier"
+version = "0.7.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "26d1e2536ce4f35f4846aa13bff16bd0ff40157cdb14cc056c7b14ba41233ba0"
+dependencies = [
+ "core-foundation",
+ "core-foundation-sys",
+ "jni",
+ "log",
+ "once_cell",
+ "rustls 0.23.40",
+ "rustls-native-certs",
+ "rustls-platform-verifier-android",
+ "rustls-webpki 0.103.13",
+ "security-framework",
+ "security-framework-sys",
+ "webpki-root-certs",
+ "windows-sys 0.61.2",
+]
+
+[[package]]
+name = "rustls-platform-verifier-android"
+version = "0.1.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "f87165f0995f63a9fbeea62b64d10b4d9d8e78ec6d7d51fb2125fda7bb36788f"
+
 [[package]]
 name = "rustls-webpki"
 version = "0.101.7"
@@ -4838,9 +5002,9 @@ dependencies = [
 
 [[package]]
 name = "rustls-webpki"
-version = "0.103.10"
+version = "0.103.13"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "df33b2b81ac578cabaf06b89b0631153a3f416b0a886e8a7a1707fb51abbd1ef"
+checksum = "61c429a8649f110dddef65e2a5ad240f747e85f7758a6bccc7e5777bd33f756e"
 dependencies = [
  "aws-lc-rs",
  "ring",
@@ -4848,63 +5012,6 @@ dependencies = [
  "untrusted",
 ]
 
-[[package]]
-name = "rustpython-ast"
-version = "0.4.0"
-source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "4cdaf8ee5c1473b993b398c174641d3aa9da847af36e8d5eb8291930b72f31a5"
-dependencies = [
- "is-macro",
- "malachite-bigint",
- "rustpython-parser-core",
- "static_assertions",
-]
-
-[[package]]
-name = "rustpython-parser"
-version = "0.4.0"
-source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "868f724daac0caf9bd36d38caf45819905193a901e8f1c983345a68e18fb2abb"
-dependencies = [
- "anyhow",
- "is-macro",
- "itertools 0.11.0",
- "lalrpop-util",
- "log",
- "malachite-bigint",
- "num-traits",
- "phf",
- "phf_codegen",
- "rustc-hash 1.1.0",
- "rustpython-ast",
- "rustpython-parser-core",
- "tiny-keccak",
- "unic-emoji-char",
- "unic-ucd-ident",
- "unicode_names2",
-]
-
-[[package]]
-name = "rustpython-parser-core"
-version = "0.4.0"
-source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "b4b6c12fa273825edc7bccd9a734f0ad5ba4b8a2f4da5ff7efe946f066d0f4ad"
-dependencies = [
- "is-macro",
- "memchr",
- "rustpython-parser-vendored",
-]
-
-[[package]]
-name = "rustpython-parser-vendored"
-version = "0.4.0"
-source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "04fcea49a4630a3a5d940f4d514dc4f575ed63c14c3e3ed07146634aed7f67a6"
-dependencies = [
- "memchr",
- "once_cell",
-]
-
 [[package]]
 name = "rustversion"
 version = "1.0.22"
@@ -4926,6 +5033,15 @@ dependencies = [
  "winapi-util",
 ]
 
+[[package]]
+name = "scc"
+version = "2.4.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "46e6f046b7fef48e2660c57ed794263155d713de679057f2d0c169bfc6e756cc"
+dependencies = [
+ "sdd",
+]
+
 [[package]]
 name = "schannel"
 version = "0.1.29"
@@ -4973,12 +5089,6 @@ dependencies = [
  "syn",
 ]
 
-[[package]]
-name = "scoped-tls"
-version = "1.0.1"
-source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "e1cf6437eb19a8f4a6cc0f7dca544973b0b78843adbfeb3683d1a94a0024a294"
-
 [[package]]
 name = "scopeguard"
 version = "1.2.0"
@@ -4994,7 +5104,7 @@ dependencies = [
  "cssparser",
  "ego-tree",
  "html5ever 0.29.1",
- "indexmap 2.13.0",
+ "indexmap 2.14.0",
  "precomputed-hash",
  "selectors",
  "tendril",
@@ -5010,6 +5120,12 @@ dependencies = [
  "untrusted",
 ]
 
+[[package]]
+name = "sdd"
+version = "3.0.10"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "490dcfcbfef26be6800d11870ff2df8774fa6e86d047e3e8c8a76b25655e41ca"
+
 [[package]]
 name = "secrecy"
 version = "0.10.3"
@@ -5073,10 +5189,47 @@ dependencies = [
 ]
 
 [[package]]
-name = "semver"
-version = "1.0.27"
+name = "self-replace"
+version = "1.5.0"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "d767eb0aabc880b29956c35734170f26ed551a859dbd361d140cdbeca61ab1e2"
+checksum = "03ec815b5eab420ab893f63393878d89c90fdd94c0bcc44c07abb8ad95552fb7"
+dependencies = [
+ "fastrand",
+ "tempfile",
+ "windows-sys 0.52.0",
+]
+
+[[package]]
+name = "self_update"
+version = "0.44.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "2e79722b5a505d4ddc77527455a97244e9e8c4c07533ff44cf4421cce7bb6d17"
+dependencies = [
+ "either",
+ "flate2",
+ "http 1.4.0",
+ "indicatif",
+ "log",
+ "quick-xml 0.38.4",
+ "regex",
+ "reqwest 0.13.3",
+ "self-replace",
+ "semver",
+ "serde",
+ "serde_json",
+ "tar",
+ "tempfile",
+ "ureq",
+ "urlencoding",
+ "zip",
+ "zipsign-api",
+]
+
+[[package]]
+name = "semver"
+version = "1.0.28"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "8a7852d02fc848982e0c167ef163aaff9cd91dc640ba85e263cb1ce46fae51cd"
 
 [[package]]
 name = "serde"
@@ -5131,11 +5284,11 @@ dependencies = [
 
 [[package]]
 name = "serde_json"
-version = "1.0.149"
+version = "1.0.150"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "83fc039473c5595ace860d8c4fafa220ff474b3fc6bfdb4293327f1a37e94d86"
+checksum = "e8014e44b4736ed0538adeecded0fce2a272f22dc9578a7eb6b2d9993c74cfb9"
 dependencies = [
- "indexmap 2.13.0",
+ "indexmap 2.14.0",
  "itoa",
  "memchr",
  "serde",
@@ -5166,15 +5319,16 @@ dependencies = [
 
 [[package]]
 name = "serde_with"
-version = "3.18.0"
+version = "3.20.0"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "dd5414fad8e6907dbdd5bc441a50ae8d6e26151a03b1de04d89a5576de61d01f"
+checksum = "e72c1c2cb7b223fafb600a619537a871c2818583d619401b785e7c0b746ccde2"
 dependencies = [
  "base64",
+ "bs58",
  "chrono",
  "hex",
  "indexmap 1.9.3",
- "indexmap 2.13.0",
+ "indexmap 2.14.0",
  "schemars 0.9.0",
  "schemars 1.2.1",
  "serde_core",
@@ -5185,9 +5339,9 @@ dependencies = [
 
 [[package]]
 name = "serde_with_macros"
-version = "3.18.0"
+version = "3.20.0"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "d3db8978e608f1fe7357e211969fd9abdcae80bac1ba7a3369bb7eb6b404eb65"
+checksum = "b90c488738ecb4fb0262f41f43bc40efc5868d9fb744319ddf5f5317f417bfac"
 dependencies = [
  "darling 0.23.0",
  "proc-macro2",
@@ -5201,13 +5355,39 @@ version = "0.9.34+deprecated"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "6a8b1a1a2ebf674015cc02edccce75287f1a0130d394307b36743c2f5d504b47"
 dependencies = [
- "indexmap 2.13.0",
+ "indexmap 2.14.0",
  "itoa",
  "ryu",
  "serde",
  "unsafe-libyaml",
 ]
 
+[[package]]
+name = "serial_test"
+version = "3.4.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "911bd979bf1070a3f3aa7b691a3b3e9968f339ceeec89e08c280a8a22207a32f"
+dependencies = [
+ "futures-executor",
+ "futures-util",
+ "log",
+ "once_cell",
+ "parking_lot",
+ "scc",
+ "serial_test_derive",
+]
+
+[[package]]
+name = "serial_test_derive"
+version = "3.4.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "0a7d91949b85b0d2fb687445e448b40d322b6b3e4af6b44a29b21d9a5f33e6d9"
+dependencies = [
+ "proc-macro2",
+ "quote",
+ "syn",
+]
+
 [[package]]
 name = "servo_arc"
 version = "0.4.3"
@@ -5217,6 +5397,17 @@ dependencies = [
  "stable_deref_trait",
 ]
 
+[[package]]
+name = "sha1"
+version = "0.10.6"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "e3bf829a2d51ab4a5ddf1352d8470c140cadc8301b2ae1789db023f01cedd6ba"
+dependencies = [
+ "cfg-if",
+ "cpufeatures 0.2.17",
+ "digest 0.10.7",
+]
+
 [[package]]
 name = "sha2"
 version = "0.10.9"
@@ -5224,17 +5415,19 @@ source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "a7507d819769d01a365ab707794a4084392c824f54a7a6a7862f8c3d0892b283"
 dependencies = [
  "cfg-if",
- "cpufeatures",
- "digest",
+ "cpufeatures 0.2.17",
+ "digest 0.10.7",
 ]
 
 [[package]]
-name = "sharded-slab"
-version = "0.1.7"
+name = "sha2"
+version = "0.11.0"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "f40ca3c46823713e0d4209592e8d6e826aa57e928f09752619fc696c499637f6"
+checksum = "446ba717509524cb3f22f17ecc096f10f4822d76ab5c0b9822c5f9c284e825f4"
 dependencies = [
- "lazy_static",
+ "cfg-if",
+ "cpufeatures 0.3.0",
+ "digest 0.11.3",
 ]
 
 [[package]]
@@ -5314,6 +5507,7 @@ version = "2.2.0"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "77549399552de45a898a580c1b41d445bf730df867cc44e6c0233bbc4b8329de"
 dependencies = [
+ "digest 0.10.7",
  "rand_core 0.6.4",
 ]
 
@@ -5323,6 +5517,22 @@ version = "0.3.9"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "703d5c7ef118737c72f1af64ad2f6f8c5e1921f818cdcb97b8fe6fc69bf66214"
 
+[[package]]
+name = "simd_cesu8"
+version = "1.1.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "94f90157bb87cddf702797c5dadfa0be7d266cdf49e22da2fcaa32eff75b2c33"
+dependencies = [
+ "rustc_version",
+ "simdutf8",
+]
+
+[[package]]
+name = "simdutf8"
+version = "0.1.5"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "e3a9fe34e3e7a50316060351f37187a3f546bce95496156754b601a5fa71b76e"
+
 [[package]]
 name = "simple_asn1"
 version = "0.6.4"
@@ -5337,9 +5547,9 @@ dependencies = [
 
 [[package]]
 name = "siphasher"
-version = "1.0.2"
+version = "1.0.3"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "b2aa850e253778c88a04c3d7323b043aeda9d3e30d5971937c1855769763678e"
+checksum = "8ee5873ec9cce0195efcb7a4e9507a04cd49aec9c83d0389df45b1ef7ba2e649"
 
 [[package]]
 name = "slab"
@@ -5379,18 +5589,46 @@ dependencies = [
  "windows-sys 0.61.2",
 ]
 
+[[package]]
+name = "socks"
+version = "0.3.4"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "f0c3dbbd9ae980613c6dd8e28a9407b50509d3803b57624d5dfe8315218cd58b"
+dependencies = [
+ "byteorder",
+ "libc",
+ "winapi",
+]
+
+[[package]]
+name = "spki"
+version = "0.7.3"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "d91ed6c858b01f942cd56b37a94b3e0a1798290327d1236e4d9cf4eaca44d29d"
+dependencies = [
+ "base64ct",
+ "der",
+]
+
+[[package]]
+name = "sse-stream"
+version = "0.2.3"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "f3962b63f038885f15bce2c6e02c0e7925c072f1ac86bb60fd44c5c6b762fb72"
+dependencies = [
+ "bytes",
+ "futures-util",
+ "http-body 1.0.1",
+ "http-body-util",
+ "pin-project-lite",
+]
+
 [[package]]
 name = "stable_deref_trait"
 version = "1.2.1"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "6ce2be8dc25455e1f91df71bfa12ad37d7af1092ae736f3a6cd0e37bc7810596"
 
-[[package]]
-name = "static_assertions"
-version = "1.1.0"
-source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "a2eb9349b6444b326872e140eb1cf5e7c522154d69e7a0ffb0fb81c06b37543f"
-
 [[package]]
 name = "stop-words"
 version = "0.9.0"
@@ -5400,6 +5638,12 @@ dependencies = [
  "serde_json",
 ]
 
+[[package]]
+name = "streaming-iterator"
+version = "0.1.9"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "2b2231b7c3057d5e4ad0156fb3dc807d900806020c5ffa3ee6ff2c8c76fb8520"
+
 [[package]]
 name = "string_cache"
 version = "0.8.9"
@@ -5442,21 +5686,11 @@ checksum = "7da8b5736845d9f2fcb837ea5d9e2628564b3b043a70948a3f0b778838c5fb4f"
 
 [[package]]
 name = "strum"
-version = "0.26.3"
+version = "0.27.2"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "8fec0f0aef304996cf250b31b5a10dee7980c85da9d759361292b8bca5a18f06"
-
-[[package]]
-name = "strum_macros"
-version = "0.26.4"
-source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "4c6bee85a5a24955dc440386795aa378cd9cf82acd5f764469152d2270e581be"
+checksum = "af23d6f6c1a224baef9d3f61e287d2761385a5b88fdab4eb4c6f11aeb54c4bcf"
 dependencies = [
- "heck",
- "proc-macro2",
- "quote",
- "rustversion",
- "syn",
+ "strum_macros",
 ]
 
 [[package]]
@@ -5565,6 +5799,17 @@ dependencies = [
  "windows 0.62.2",
 ]
 
+[[package]]
+name = "tar"
+version = "0.4.46"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "3f6221d9a6003c78398e3b239969f352578258df48c8eb051caadae0015bc840"
+dependencies = [
+ "filetime",
+ "libc",
+ "xattr",
+]
+
 [[package]]
 name = "tempfile"
 version = "3.27.0"
@@ -5574,7 +5819,7 @@ dependencies = [
  "fastrand",
  "getrandom 0.4.2",
  "once_cell",
- "rustix 1.1.4",
+ "rustix",
  "windows-sys 0.61.2",
 ]
 
@@ -5621,7 +5866,7 @@ version = "0.4.4"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "230a1b821ccbd75b185820a1f1ff7b14d21da1e442e22c0863ea5f08771a8874"
 dependencies = [
- "rustix 1.1.4",
+ "rustix",
  "windows-sys 0.61.2",
 ]
 
@@ -5736,15 +5981,6 @@ dependencies = [
  "time-core",
 ]
 
-[[package]]
-name = "tiny-keccak"
-version = "2.0.2"
-source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "2c9d3793400a45f954c52e73d068316d76b6f4e36977e3fcebb13a2721e80237"
-dependencies = [
- "crunchy",
-]
-
 [[package]]
 name = "tinystr"
 version = "0.8.3"
@@ -5772,9 +6008,9 @@ checksum = "1f3ccbac311fea05f86f61904b462b55fb3df8837a366dfc601a0161d0532f20"
 
 [[package]]
 name = "tokio"
-version = "1.50.0"
+version = "1.52.3"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "27ad5e34374e03cfffefc301becb44e9dc3c17584f414349ebe29ed26661822d"
+checksum = "8fc7f01b389ac15039e4dc9531aa973a135d7a4135281b12d7c1bc79fd57fffe"
 dependencies = [
  "bytes",
  "libc",
@@ -5787,24 +6023,11 @@ dependencies = [
  "windows-sys 0.61.2",
 ]
 
-[[package]]
-name = "tokio-graceful"
-version = "0.2.2"
-source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "45740b38b48641855471cd402922e89156bdfbd97b69b45eeff170369cc18c7d"
-dependencies = [
- "loom",
- "pin-project-lite",
- "slab",
- "tokio",
- "tracing",
-]
-
 [[package]]
 name = "tokio-macros"
-version = "2.6.1"
+version = "2.7.0"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "5c55a2eff8b69ce66c84f85e1da1c233edc36ceb85a2058d11b0d6a3c7e7569c"
+checksum = "385a6cb71ab9ab790c5fe8d67f1645e6c450a7ce006a33de03daa956cf70a496"
 dependencies = [
  "proc-macro2",
  "quote",
@@ -5837,7 +6060,7 @@ version = "0.26.4"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "1729aa945f29d91ba541258c8df89027d5792d85a8841fb65e8bf0f4ede4ef61"
 dependencies = [
- "rustls 0.23.37",
+ "rustls 0.23.40",
  "tokio",
 ]
 
@@ -5850,7 +6073,6 @@ dependencies = [
  "futures-core",
  "pin-project-lite",
  "tokio",
- "tokio-util",
 ]
 
 [[package]]
@@ -5895,15 +6117,15 @@ checksum = "756daf9b1013ebe47a8776667b466417e2d4c5679d441c26230efd9ef78692db"
 
 [[package]]
 name = "tonic"
-version = "0.14.5"
+version = "0.14.6"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "fec7c61a0695dc1887c1b53952990f3ad2e3a31453e1f49f10e75424943a93ec"
+checksum = "ac2a5518c70fa84342385732db33fb3f44bc4cc748936eb5833d2df34d6445ef"
 dependencies = [
  "async-trait",
  "axum",
  "base64",
  "bytes",
- "h2 0.4.13",
+ "h2 0.4.14",
  "http 1.4.0",
  "http-body 1.0.1",
  "http-body-util",
@@ -5926,9 +6148,9 @@ dependencies = [
 
 [[package]]
 name = "tonic-prost"
-version = "0.14.5"
+version = "0.14.6"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "a55376a0bbaa4975a3f10d009ad763d8f4108f067c7c2e74f3001fb49778d309"
+checksum = "50849f68853be452acf590cde0b146665b8d507b3b8af17261df47e02c209ea0"
 dependencies = [
  "bytes",
  "prost",
@@ -5943,7 +6165,7 @@ checksum = "ebe5ef63511595f1344e2d5cfa636d973292adc0eec1f0ad45fae9f0851ab1d4"
 dependencies = [
  "futures-core",
  "futures-util",
- "indexmap 2.13.0",
+ "indexmap 2.14.0",
  "pin-project-lite",
  "slab",
  "sync_wrapper",
@@ -5956,9 +6178,9 @@ dependencies = [
 
 [[package]]
 name = "tower-http"
-version = "0.6.8"
+version = "0.6.11"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "d4e6559d53cc268e5031cd8429d05415bc4cb4aefc4aa5d6cc35fbf5b924a1f8"
+checksum = "4cfcf7e2740e6fc6d4d688b4ef00650406bb94adf4731e43c096c3a19fe40840"
 dependencies = [
  "async-compression",
  "bitflags",
@@ -5968,13 +6190,13 @@ dependencies = [
  "http 1.4.0",
  "http-body 1.0.1",
  "http-body-util",
- "iri-string",
  "pin-project-lite",
  "tokio",
  "tokio-util",
  "tower",
  "tower-layer",
  "tower-service",
+ "url",
 ]
 
 [[package]]
@@ -6018,36 +6240,46 @@ source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "db97caf9d906fbde555dd62fa95ddba9eecfd14cb388e4f491a66d74cd5fb79a"
 dependencies = [
  "once_cell",
- "valuable",
 ]
 
 [[package]]
-name = "tracing-log"
-version = "0.2.0"
+name = "tree-sitter"
+version = "0.26.9"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "ee855f1f400bd0e5c02d150ae5de3840039a3f54b025156404e34c23c03f47c3"
+checksum = "4dab76d0b724ba557954125188cf0633a1ca43199ced82d95c7b9c32cc3de1f3"
 dependencies = [
- "log",
- "once_cell",
- "tracing-core",
+ "cc",
+ "regex",
+ "regex-syntax",
+ "serde_json",
+ "streaming-iterator",
+ "tree-sitter-language",
 ]
 
 [[package]]
-name = "tracing-subscriber"
-version = "0.3.23"
+name = "tree-sitter-language"
+version = "0.1.7"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "cb7f578e5945fb242538965c2d0b04418d38ec25c79d160cd279bf0731c8d319"
+checksum = "009994f150cc0cd50ff54917d5bc8bffe8cad10ca10d81c34da2ec421ae61782"
+
+[[package]]
+name = "tree-sitter-python"
+version = "0.25.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "6bf85fd39652e740bf60f46f4cda9492c3a9ad75880575bf14960f775cb74a1c"
 dependencies = [
- "matchers",
- "nu-ansi-term",
- "once_cell",
- "regex-automata",
- "sharded-slab",
- "smallvec",
- "thread_local",
- "tracing",
- "tracing-core",
- "tracing-log",
+ "cc",
+ "tree-sitter-language",
+]
+
+[[package]]
+name = "tree-sitter-typescript"
+version = "0.23.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "6c5f76ed8d947a75cc446d5fccd8b602ebf0cde64ccf2ffa434d873d7a575eff"
+dependencies = [
+ "cc",
+ "tree-sitter-language",
 ]
 
 [[package]]
@@ -6078,9 +6310,9 @@ dependencies = [
 
 [[package]]
 name = "typenum"
-version = "1.19.0"
+version = "1.20.0"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "562d481066bde0658276a35467c4af00bdc6ee726305698a55b86e61d7ad82bb"
+checksum = "40ce102ab67701b8526c123c1bab5cbe42d7040ccfd0f64af1a385808d2f43de"
 
 [[package]]
 name = "typespec"
@@ -6108,8 +6340,8 @@ dependencies = [
  "futures",
  "getrandom 0.3.4",
  "pin-project",
- "rand 0.9.2",
- "reqwest",
+ "rand 0.9.4",
+ "reqwest 0.12.28",
  "serde",
  "serde_json",
  "time",
@@ -6133,58 +6365,6 @@ dependencies = [
  "syn",
 ]
 
-[[package]]
-name = "unic-char-property"
-version = "0.9.0"
-source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "a8c57a407d9b6fa02b4795eb81c5b6652060a15a7903ea981f3d723e6c0be221"
-dependencies = [
- "unic-char-range",
-]
-
-[[package]]
-name = "unic-char-range"
-version = "0.9.0"
-source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "0398022d5f700414f6b899e10b8348231abf9173fa93144cbc1a43b9793c1fbc"
-
-[[package]]
-name = "unic-common"
-version = "0.9.0"
-source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "80d7ff825a6a654ee85a63e80f92f054f904f21e7d12da4e22f9834a4aaa35bc"
-
-[[package]]
-name = "unic-emoji-char"
-version = "0.9.0"
-source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "0b07221e68897210270a38bde4babb655869637af0f69407f96053a34f76494d"
-dependencies = [
- "unic-char-property",
- "unic-char-range",
- "unic-ucd-version",
-]
-
-[[package]]
-name = "unic-ucd-ident"
-version = "0.9.0"
-source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "e230a37c0381caa9219d67cf063aa3a375ffed5bf541a452db16e744bdab6987"
-dependencies = [
- "unic-char-property",
- "unic-char-range",
- "unic-ucd-version",
-]
-
-[[package]]
-name = "unic-ucd-version"
-version = "0.9.0"
-source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "96bd2f2237fe450fcd0a1d2f5f4e91711124f7857ba2e964247776ebeeb7b0c4"
-dependencies = [
- "unic-common",
-]
-
 [[package]]
 name = "unicase"
 version = "2.9.0"
@@ -6222,26 +6402,10 @@ source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "ebc1c04c71510c7f702b52b7c350734c9ff1295c464a03335b00bb84fc54f853"
 
 [[package]]
-name = "unicode_names2"
-version = "1.3.0"
+name = "unit-prefix"
+version = "0.5.2"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "d1673eca9782c84de5f81b82e4109dcfb3611c8ba0d52930ec4a9478f547b2dd"
-dependencies = [
- "phf",
- "unicode_names2_generator",
-]
-
-[[package]]
-name = "unicode_names2_generator"
-version = "1.3.0"
-source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "b91e5b84611016120197efd7dc93ef76774f4e084cd73c9fb3ea4a86c570c56e"
-dependencies = [
- "getopts",
- "log",
- "phf_codegen",
- "rand 0.8.5",
-]
+checksum = "81e544489bf3d8ef66c953931f56617f423cd4b5494be343d9b9d3dda037b9a3"
 
 [[package]]
 name = "universal-hash"
@@ -6249,7 +6413,7 @@ version = "0.5.1"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "fc1de2c688dc15305988b563c3854064043356019f97a4b46276fe734c4f07ea"
 dependencies = [
- "crypto-common",
+ "crypto-common 0.1.7",
  "subtle",
 ]
 
@@ -6280,6 +6444,40 @@ version = "0.0.4"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "6d49784317cd0d1ee7ec5c716dd598ec5b4483ea832a2dced265471cc0f690ae"
 
+[[package]]
+name = "ureq"
+version = "3.3.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "dea7109cdcd5864d4eeb1b58a1648dc9bf520360d7af16ec26d0a9354bafcfc0"
+dependencies = [
+ "base64",
+ "cookie_store",
+ "encoding_rs",
+ "flate2",
+ "log",
+ "percent-encoding",
+ "rustls 0.23.40",
+ "rustls-pki-types",
+ "serde",
+ "serde_json",
+ "socks",
+ "ureq-proto",
+ "utf8-zero",
+ "webpki-roots",
+]
+
+[[package]]
+name = "ureq-proto"
+version = "0.6.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "e994ba84b0bd1b1b0cf92878b7ef898a5c1760108fe7b6010327e274917a808c"
+dependencies = [
+ "base64",
+ "http 1.4.0",
+ "httparse",
+ "log",
+]
+
 [[package]]
 name = "url"
 version = "2.5.8"
@@ -6304,6 +6502,12 @@ version = "0.7.6"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "09cc8ee72d2a9becf2f2febe0205bbed8fc6615b7cb429ad062dc7b7ddd036a9"
 
+[[package]]
+name = "utf8-zero"
+version = "0.8.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "b8c0a043c9540bae7c578c88f91dda8bd82e59ae27c21baca69c8b191aaf5a6e"
+
 [[package]]
 name = "utf8_iter"
 version = "1.0.4"
@@ -6318,9 +6522,9 @@ checksum = "06abde3611657adf66d383f00b093d7faecc7fa57071cce2578660c9f1010821"
 
 [[package]]
 name = "uuid"
-version = "1.23.0"
+version = "1.23.1"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "5ac8b6f42ead25368cf5b098aeb3dc8a1a2c05a3eee8a9a1a68c640edbfc79d9"
+checksum = "ddd74a9687298c6858e9b88ec8935ec45d22e8fd5e6394fa1bd4e99a87789c76"
 dependencies = [
  "getrandom 0.4.2",
  "js-sys",
@@ -6357,12 +6561,6 @@ dependencies = [
  "syn",
 ]
 
-[[package]]
-name = "valuable"
-version = "0.1.1"
-source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "ba73ea9cf16a25df0c8caa16c51acb937d5712a8429db78a3ee29d5dcacd3a65"
-
 [[package]]
 name = "vcpkg"
 version = "0.2.15"
@@ -6417,11 +6615,11 @@ checksum = "ccf3ec651a847eb01de73ccad15eb7d99f80485de043efb2f370cd654f4ea44b"
 
 [[package]]
 name = "wasip2"
-version = "1.0.2+wasi-0.2.9"
+version = "1.0.3+wasi-0.2.9"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "9517f9239f02c069db75e65f174b3da828fe5f5b945c4dd26bd25d89c03ebcf5"
+checksum = "20064672db26d7cdc89c7798c48a0fdfac8213434a1186e5ef29fd560ae223d6"
 dependencies = [
- "wit-bindgen",
+ "wit-bindgen 0.57.1",
 ]
 
 [[package]]
@@ -6430,14 +6628,14 @@ version = "0.4.0+wasi-0.3.0-rc-2026-01-06"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "5428f8bf88ea5ddc08faddef2ac4a67e390b88186c703ce6dbd955e1c145aca5"
 dependencies = [
- "wit-bindgen",
+ "wit-bindgen 0.51.0",
 ]
 
 [[package]]
 name = "wasm-bindgen"
-version = "0.2.117"
+version = "0.2.122"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "0551fc1bb415591e3372d0bc4780db7e587d84e2a7e79da121051c5c4b89d0b0"
+checksum = "3ed04576f974d2b2fba0f38c51dbc5518011e38c36bf1143164be765528fd409"
 dependencies = [
  "cfg-if",
  "once_cell",
@@ -6448,9 +6646,9 @@ dependencies = [
 
 [[package]]
 name = "wasm-bindgen-futures"
-version = "0.4.67"
+version = "0.4.72"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "03623de6905b7206edd0a75f69f747f134b7f0a2323392d664448bf2d3c5d87e"
+checksum = "9473dbd2991ae90b6291c3c32c30c6187ac49aa32f9905d1cce280ec1e110b0f"
 dependencies = [
  "js-sys",
  "wasm-bindgen",
@@ -6458,9 +6656,9 @@ dependencies = [
 
 [[package]]
 name = "wasm-bindgen-macro"
-version = "0.2.117"
+version = "0.2.122"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "7fbdf9a35adf44786aecd5ff89b4563a90325f9da0923236f6104e603c7e86be"
+checksum = "916151b09da36bd82f6615cbf3a419e2f0ba23a03c6160e8e92eb6bd4aa1dec6"
 dependencies = [
  "quote",
  "wasm-bindgen-macro-support",
@@ -6468,9 +6666,9 @@ dependencies = [
 
 [[package]]
 name = "wasm-bindgen-macro-support"
-version = "0.2.117"
+version = "0.2.122"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "dca9693ef2bab6d4e6707234500350d8dad079eb508dca05530c85dc3a529ff2"
+checksum = "299047362ccbfce148b67ab7e73349f77748e00c8296f9542adfad2ad82c5c5e"
 dependencies = [
  "bumpalo",
  "proc-macro2",
@@ -6481,9 +6679,9 @@ dependencies = [
 
 [[package]]
 name = "wasm-bindgen-shared"
-version = "0.2.117"
+version = "0.2.122"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "39129a682a6d2d841b6c429d0c51e5cb0ed1a03829d8b3d1e69a011e62cb3d3b"
+checksum = "9a929b2c61f11ba3e9bc35b50c1f25cb38e0e892c0c231ae2b8cf78d5dad4437"
 dependencies = [
  "unicode-ident",
 ]
@@ -6505,7 +6703,7 @@ source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "bb0e353e6a2fbdc176932bbaab493762eb1255a7900fe0fea1a2f96c296cc909"
 dependencies = [
  "anyhow",
- "indexmap 2.13.0",
+ "indexmap 2.14.0",
  "wasm-encoder",
  "wasmparser",
 ]
@@ -6523,6 +6721,19 @@ dependencies = [
  "web-sys",
 ]
 
+[[package]]
+name = "wasm-streams"
+version = "0.5.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "9d1ec4f6517c9e11ae630e200b2b65d193279042e28edd4a2cda233e46670bbb"
+dependencies = [
+ "futures-util",
+ "js-sys",
+ "wasm-bindgen",
+ "wasm-bindgen-futures",
+ "web-sys",
+]
+
 [[package]]
 name = "wasmparser"
 version = "0.244.0"
@@ -6531,7 +6742,7 @@ checksum = "47b807c72e1bac69382b3a6fb3dbe8ea4c0ed87ff5629b8685ae6b9a611028fe"
 dependencies = [
  "bitflags",
  "hashbrown 0.15.5",
- "indexmap 2.13.0",
+ "indexmap 2.14.0",
  "semver",
 ]
 
@@ -6543,7 +6754,7 @@ checksum = "2857dd20b54e916ec7253b3d6b4d5c4d7d4ca2c33c2e11c6c76a99bd8744755d"
 dependencies = [
  "cc",
  "downcast-rs",
- "rustix 1.1.4",
+ "rustix",
  "smallvec",
  "wayland-sys",
 ]
@@ -6555,7 +6766,7 @@ source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "645c7c96bb74690c3189b5c9cb4ca1627062bb23693a4fad9d8c3de958260144"
 dependencies = [
  "bitflags",
- "rustix 1.1.4",
+ "rustix",
  "wayland-backend",
  "wayland-scanner",
 ]
@@ -6592,7 +6803,7 @@ source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "9c324a910fd86ebdc364a3e61ec1f11737d3b1d6c273c0239ee8ff4bc0d24b4a"
 dependencies = [
  "proc-macro2",
- "quick-xml 0.39.2",
+ "quick-xml 0.39.4",
  "quote",
 ]
 
@@ -6607,9 +6818,9 @@ dependencies = [
 
 [[package]]
 name = "web-sys"
-version = "0.3.94"
+version = "0.3.99"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "cd70027e39b12f0849461e08ffc50b9cd7688d942c1c8e3c7b22273236b4dd0a"
+checksum = "6d621441cfc37b84979402712047321980c178f299193a3589d05b99e8763436"
 dependencies = [
  "js-sys",
  "wasm-bindgen",
@@ -6626,10 +6837,19 @@ dependencies = [
 ]
 
 [[package]]
-name = "webpki-roots"
-version = "1.0.6"
+name = "webpki-root-certs"
+version = "1.0.7"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "22cfaf3c063993ff62e73cb4311efde4db1efb31ab78a3e5c457939ad5cc0bed"
+checksum = "f31141ce3fc3e300ae89b78c0dd67f9708061d1d2eda54b8209346fd6be9a92c"
+dependencies = [
+ "rustls-pki-types",
+]
+
+[[package]]
+name = "webpki-roots"
+version = "1.0.7"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "52f5ee44c96cf55f1b349600768e3ece3a8f26010c05265ab73f945bb1a2eb9d"
 dependencies = [
  "rustls-pki-types",
 ]
@@ -7030,6 +7250,12 @@ dependencies = [
  "wit-bindgen-rust-macro",
 ]
 
+[[package]]
+name = "wit-bindgen"
+version = "0.57.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "1ebf944e87a7c253233ad6766e082e3cd714b5d03812acc24c318f549614536e"
+
 [[package]]
 name = "wit-bindgen-core"
 version = "0.51.0"
@@ -7049,7 +7275,7 @@ checksum = "b7c566e0f4b284dd6561c786d9cb0142da491f46a9fbed79ea69cdad5db17f21"
 dependencies = [
  "anyhow",
  "heck",
- "indexmap 2.13.0",
+ "indexmap 2.14.0",
  "prettyplease",
  "syn",
  "wasm-metadata",
@@ -7080,7 +7306,7 @@ checksum = "9d66ea20e9553b30172b5e831994e35fbde2d165325bec84fc43dbf6f4eb9cb2"
 dependencies = [
  "anyhow",
  "bitflags",
- "indexmap 2.13.0",
+ "indexmap 2.14.0",
  "log",
  "serde",
  "serde_derive",
@@ -7099,7 +7325,7 @@ checksum = "ecc8ac4bc1dc3381b7f59c34f00b67e18f910c2c0f50015669dde7def656a736"
 dependencies = [
  "anyhow",
  "id-arena",
- "indexmap 2.13.0",
+ "indexmap 2.14.0",
  "log",
  "semver",
  "serde",
@@ -7118,7 +7344,7 @@ dependencies = [
  "libc",
  "log",
  "os_pipe",
- "rustix 1.1.4",
+ "rustix",
  "thiserror 2.0.18",
  "tree_magic_mini",
  "wayland-backend",
@@ -7129,9 +7355,9 @@ dependencies = [
 
 [[package]]
 name = "writeable"
-version = "0.6.2"
+version = "0.6.3"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "9edde0db4769d2dc68579893f2306b26c6ecfbe0ef499b013d731b7b9247e0b9"
+checksum = "1ffae5123b2d3fc086436f8834ae3ab053a283cfac8fe0a0b8eaae044768a4c4"
 
 [[package]]
 name = "x11rb"
@@ -7140,7 +7366,7 @@ source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "9993aa5be5a26815fe2c3eacfc1fde061fc1a1f094bf1ad2a18bf9c495dd7414"
 dependencies = [
  "gethostname",
- "rustix 1.1.4",
+ "rustix",
  "x11rb-protocol",
 ]
 
@@ -7150,6 +7376,16 @@ version = "0.13.2"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "ea6fc2961e4ef194dcbfe56bb845534d0dc8098940c7e5c012a258bfec6701bd"
 
+[[package]]
+name = "xattr"
+version = "1.6.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "32e45ad4206f6d2479085147f02bc2ef834ac85886624a23575ae137c8aa8156"
+dependencies = [
+ "libc",
+ "rustix",
+]
+
 [[package]]
 name = "xml5ever"
 version = "0.18.1"
@@ -7224,9 +7460,9 @@ dependencies = [
 
 [[package]]
 name = "zerofrom"
-version = "0.1.7"
+version = "0.1.8"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "69faa1f2a1ea75661980b013019ed6687ed0e83d069bc1114e2cc74c6c04c4df"
+checksum = "0ec05a11813ea801ff6d75110ad09cd0824ddba17dfe17128ea0d5f68e6c5272"
 dependencies = [
  "zerofrom-derive",
 ]
@@ -7296,8 +7532,52 @@ dependencies = [
  "syn",
 ]
 
+[[package]]
+name = "zip"
+version = "6.0.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "eb2a05c7c36fde6c09b08576c9f7fb4cda705990f73b58fe011abf7dfb24168b"
+dependencies = [
+ "arbitrary",
+ "crc32fast",
+ "flate2",
+ "indexmap 2.14.0",
+ "memchr",
+ "time",
+ "zopfli",
+]
+
+[[package]]
+name = "zipsign-api"
+version = "0.1.5"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "dba6063ff82cdbd9a765add16d369abe81e520f836054e997c2db217ceca40c0"
+dependencies = [
+ "base64",
+ "ed25519-dalek",
+ "thiserror 2.0.18",
+]
+
+[[package]]
+name = "zlib-rs"
+version = "0.6.3"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "3be3d40e40a133f9c916ee3f9f4fa2d9d63435b5fbe1bfc6d9dae0aa0ada1513"
+
 [[package]]
 name = "zmij"
 version = "1.0.21"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "b8848ee67ecc8aedbaf3e4122217aff892639231befc6a1b58d29fff4c2cabaa"
+
+[[package]]
+name = "zopfli"
+version = "0.8.3"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "f05cd8797d63865425ff89b5c4a48804f35ba0ce8d125800027ad6017d2b5249"
+dependencies = [
+ "bumpalo",
+ "crc32fast",
+ "log",
+ "simd-adler32",
+]
diff --git a/Cargo.toml b/Cargo.toml
index 1683cb0..132d44f 100644
--- a/Cargo.toml
+++ b/Cargo.toml
@@ -10,7 +10,7 @@ repository = "https://github.com/Dark-Alex-17/loki"
 categories = ["command-line-utilities"]
 readme = "README.md"
 license = "MIT"
-rust-version = "1.89.0"
+rust-version = "1.95.0"
 exclude = [".github", "CONTRIBUTING.md"]
 
 [dependencies]
@@ -18,10 +18,11 @@ anyhow = "1.0.69"
 bytes = "1.4.0"
 clap = { version = "4.5.40", features = ["cargo", "derive", "wrap_help"] }
 dirs = "6.0.0"
+dunce = "1.0.5"
 futures-util = "0.3.29"
 inquire = "0.9.4"
 is-terminal = "0.4.9"
-reedline = "0.40.0"
+reedline = "0.47.0"
 serde = { version = "1.0.152", features = ["derive"] }
 serde_json = { version = "1.0.93", features = ["preserve_order"] }
 serde_yaml = "0.9.17"
@@ -33,11 +34,7 @@ tokio = { version = "1.34.0", features = [
   "rt-multi-thread",
   "full",
 ] }
-tokio-graceful = "0.2.2"
-tokio-stream = { version = "0.1.15", default-features = false, features = [
-  "sync",
-] }
-crossterm = "0.28.1"
+crossterm = "0.29.0"
 chrono = "0.4.23"
 bincode = { version = "2.0.0", features = [
   "serde",
@@ -50,7 +47,7 @@ nu-ansi-term = "0.50.0"
 async-trait = "0.1.74"
 textwrap = "0.16.0"
 ansi_colours = "1.2.2"
-reqwest-eventsource = "0.6.0"
+eventsource-stream = "0.2.3"
 log = "0.4.28"
 log4rs = { version = "1.4.0", features = ["file_appender"] }
 shell-words = "1.1.0"
@@ -58,20 +55,14 @@ sha2 = "0.10.8"
 unicode-width = "0.2.0"
 async-recursion = "1.1.1"
 http = "1.1.0"
-http-body-util = "0.1"
-hyper = { version = "1.0", features = ["full"] }
-hyper-util = { version = "0.1", features = ["server-auto", "client-legacy"] }
-time = { version = "0.3.36", features = ["macros"] }
 indexmap = { version = "2.2.6", features = ["serde"] }
 hmac = "0.12.1"
 aws-smithy-eventstream = "0.60.4"
 urlencoding = "2.1.3"
-unicode-segmentation = "1.11.0"
 json-patch = { version = "4.0.0", default-features = false }
 bitflags = "2.5.0"
 path-absolutize = "3.1.1"
 hnsw_rs = "0.3.0"
-rayon = "1.10.0"
 uuid = { version = "1.9.1", features = ["v4"] }
 scraper = { version = "0.23.1", default-features = false, features = [
   "deterministic",
@@ -88,26 +79,41 @@ duct = "1.0.0"
 argc = "1.23.0"
 strum_macros = "0.27.2"
 indoc = "2.0.6"
-rmcp = { version = "0.16.0", features = ["client", "transport-child-process"] }
+rmcp = { version = "1.5.0", features = [
+  "client",
+  "transport-child-process",
+  "transport-streamable-http-client-reqwest",
+  "reqwest-native-tls",
+] }
 num_cpus = "1.17.0"
-rustpython-parser = "0.4.0"
-rustpython-ast = "0.4.0"
+tree-sitter = "0.26.8"
+tree-sitter-python = "0.25.0"
+tree-sitter-typescript = "0.23"
 colored = "3.0.0"
 clap_complete = { version = "4.5.58", features = ["unstable-dynamic"] }
-gman = "0.3.0"
+gman = "0.4.1"
 clap_complete_nushell = "4.5.9"
 open = "5"
-rand = "0.9.0"
+rand = { version = "0.10.0", features = ["default"] }
 url = "2.5.8"
+self_update = { version = "0.44", default-features = false, features = [
+  "reqwest",
+  "rustls",
+  "archive-tar",
+  "compression-flate2",
+  "archive-zip",
+  "compression-zip-deflate",
+] }
 
 [dependencies.reqwest]
-version = "0.12.0"
+version = "0.13.3"
 features = [
   "json",
   "multipart",
+  "stream",
+  "form",
   "socks",
-  "rustls-tls",
-  "rustls-tls-native-roots",
+  "rustls",
 ]
 default-features = false
 
@@ -117,7 +123,7 @@ default-features = false
 features = ["parsing", "regex-onig", "plist-load"]
 
 [target.'cfg(target_os = "macos")'.dependencies]
-crossterm = { version = "0.28.1", features = ["use-dev-tty"] }
+crossterm = { version = "0.29.0", features = ["use-dev-tty"] }
 
 [target.'cfg(target_os = "linux")'.dependencies]
 arboard = { version = "3.3.0", default-features = false, features = [
@@ -129,6 +135,7 @@ arboard = { version = "3.3.0", default-features = false }
 
 [dev-dependencies]
 pretty_assertions = "1.4.0"
+serial_test = "3"
 
 [[bin]]
 name = "loki"
diff --git a/README.md b/README.md
index df5e59e..c1f98db 100644
--- a/README.md
+++ b/README.md
@@ -1,7 +1,6 @@
 # Loki: All-in-one, batteries-included LLM CLI Tool
 
 ![Test](https://github.com/Dark-Alex-17/loki/actions/workflows/ci.yaml/badge.svg)
-![LOC](https://tokei.rs/b1/github/Dark-Alex-17/loki?category=code)
 [![crates.io link](https://img.shields.io/crates/v/loki-ai.svg)](https://crates.io/crates/loki-ai)
 ![Release](https://img.shields.io/github/v/release/Dark-Alex-17/loki?color=%23c694ff)
 ![Crate.io downloads](https://img.shields.io/crates/d/loki-ai?label=Crate%20downloads)
@@ -11,53 +10,47 @@ Loki is an all-in-one, batteries-included, LLM CLI tool featuring Shell Assistan
 Agents, and More.
 
 It is designed to include a number of useful agents, roles, macros, and more so users can get up and running with Loki 
-in as little time as possible.
+in as little time as possible. You can also install entire bundles of agents, roles, macros, tools, and MCP servers from 
+any git repository — see [Sharing Configurations](#sharing-configurations).
 
-![Agent example](./docs/images/agents/sql.gif)
+![Agent example](https://raw.githubusercontent.com/wiki/Dark-Alex-17/loki/images/agents/sql.gif)
 
-Coming from [AIChat](https://github.com/sigoden/aichat)? Follow the [migration guide](./docs/AICHAT-MIGRATION.md) to get started.
+Coming from [AIChat](https://github.com/sigoden/aichat)? Follow the [migration guide](https://github.com/Dark-Alex-17/loki/wiki/AIChat-Migration) to get started.
 
 ## Quick Links
-* [AIChat Migration Guide](./docs/AICHAT-MIGRATION.md): Coming from AIChat? Follow the migration guide to get started.
+* [AIChat Migration Guide](https://github.com/Dark-Alex-17/loki/wiki/AIChat-Migration): Coming from AIChat? Follow the migration guide to get started.
 * [Installation](#install): Install Loki
 * [Getting Started](#getting-started): Get started with Loki by doing first-run setup steps.
-* [REPL](./docs/REPL.md): Interactive Read-Eval-Print Loop for conversational interactions with LLMs and Loki.
-  * [Custom REPL Prompt](./docs/REPL-PROMPT.md): Customize the REPL prompt to provide useful contextual information.
-* [Vault](./docs/VAULT.md): Securely store and manage sensitive information such as API keys and credentials.
-* [Shell Integrations](./docs/SHELL-INTEGRATIONS.md): Seamlessly integrate Loki with your shell environment for enhanced command-line assistance.
-* [Function Calling](./docs/function-calling/TOOLS.md#Tools): Leverage function calling capabilities to extend Loki's functionality with custom tools
-    * [Creating Custom Tools](./docs/function-calling/CUSTOM-TOOLS.md): You can create your own custom tools to enhance Loki's capabilities.
-        * [Create Custom Python Tools](./docs/function-calling/CUSTOM-TOOLS.md#custom-python-based-tools)
-        * [Create Custom Bash Tools](./docs/function-calling/CUSTOM-BASH-TOOLS.md)
-            * [Bash Prompt Utilities](./docs/function-calling/BASH-PROMPT-HELPERS.md)
-* [First-Class MCP Server Support](./docs/function-calling/MCP-SERVERS.md): Easily connect and interact with MCP servers for advanced functionality.
-* [Macros](./docs/MACROS.md): Automate repetitive tasks and workflows with Loki "scripts" (macros).
-* [RAG](./docs/RAG.md): Retrieval-Augmented Generation for enhanced information retrieval and generation.
-* [Sessions](/docs/SESSIONS.md): Manage and persist conversational contexts and settings across multiple interactions.
-* [Roles](./docs/ROLES.md): Customize model behavior for specific tasks or domains.
-* [Agents](/docs/AGENTS.md): Leverage AI agents to perform complex tasks and workflows, including sub-agent spawning, teammate messaging, and user interaction tools.
-    * [Todo System](./docs/TODO-SYSTEM.md): Built-in task tracking for improved agent reliability with smaller models.
-* [Environment Variables](./docs/ENVIRONMENT-VARIABLES.md): Override and customize your Loki configuration at runtime with environment variables.
-* [Client Configurations](./docs/clients/CLIENTS.md): Configuration instructions for various LLM providers.
-    * [Authentication (API Key & OAuth)](./docs/clients/CLIENTS.md#authentication): Authenticate with API keys or OAuth for subscription-based access.
-    * [Patching API Requests](./docs/clients/PATCHES.md): Learn how to patch API requests for advanced customization.
-* [Custom Themes](./docs/THEMES.md): Change the look and feel of Loki to your preferences with custom themes.
+* [Sharing Configurations](https://github.com/Dark-Alex-17/loki/wiki/Sharing-Configurations): Install bundles of agents, roles, macros, tools, and MCP servers from any git repo, and share your own.
+* [REPL](https://github.com/Dark-Alex-17/loki/wiki/REPL): Interactive Read-Eval-Print Loop for conversational interactions with LLMs and Loki.
+  * [Custom REPL Prompt](https://github.com/Dark-Alex-17/loki/wiki/REPL-Prompt): Customize the REPL prompt to provide useful contextual information.
+* [Vault](https://github.com/Dark-Alex-17/loki/wiki/Vault): Securely store and manage sensitive information such as API keys and credentials.
+* [Shell Integrations](https://github.com/Dark-Alex-17/loki/wiki/Shell-Integrations): Seamlessly integrate Loki with your shell environment for enhanced command-line assistance.
+* [Function Calling](https://github.com/Dark-Alex-17/loki/wiki/Tools): Leverage function calling capabilities to extend Loki's functionality with custom tools
+    * [Creating Custom Tools](https://github.com/Dark-Alex-17/loki/wiki/Custom-Tools): You can create your own custom tools to enhance Loki's capabilities.
+        * [Create Custom Python Tools](https://github.com/Dark-Alex-17/loki/wiki/Custom-Tools#custom-python-based-tools)
+        * [Create Custom TypeScript Tools](https://github.com/Dark-Alex-17/loki/wiki/Custom-Tools#custom-typescript-based-tools)
+        * [Create Custom Bash Tools](https://github.com/Dark-Alex-17/loki/wiki/Custom-Bash-Tools)
+            * [Bash Prompt Utilities](https://github.com/Dark-Alex-17/loki/wiki/Bash-Prompt-Helpers)
+* [First-Class MCP Server Support](https://github.com/Dark-Alex-17/loki/wiki/MCP-Servers): Easily connect and interact with MCP servers for advanced functionality.
+* [Macros](https://github.com/Dark-Alex-17/loki/wiki/Macros): Automate repetitive tasks and workflows with Loki "scripts" (macros).
+* [RAG](https://github.com/Dark-Alex-17/loki/wiki/RAG): Retrieval-Augmented Generation for enhanced information retrieval and generation.
+* [Sessions](https://github.com/Dark-Alex-17/loki/wiki/Sessions): Manage and persist conversational contexts and settings across multiple interactions.
+* [Roles](https://github.com/Dark-Alex-17/loki/wiki/Roles): Customize model behavior for specific tasks or domains.
+* [Agents](https://github.com/Dark-Alex-17/loki/wiki/Agents): Leverage AI agents to perform complex tasks and workflows, including sub-agent spawning, teammate messaging, and user interaction tools.
+    * [Graph Agents](https://github.com/Dark-Alex-17/loki/wiki/Graph-Agents): Define an agent as a declarative, YAML-driven workflow. A directed graph of typed nodes (LLM calls, scripts, approvals, user input, RAG retrieval, sub-agent spawns).
+* [Todo System](https://github.com/Dark-Alex-17/loki/wiki/TODO-System): Built-in task tracking for improved LLM reliability with smaller models.
+* [Environment Variables](https://github.com/Dark-Alex-17/loki/wiki/Environment-Variables): Override and customize your Loki configuration at runtime with environment variables.
+* [Client Configurations](https://github.com/Dark-Alex-17/loki/wiki/Clients): Configuration instructions for various LLM providers.
+    * [Authentication (API Key & OAuth)](https://github.com/Dark-Alex-17/loki/wiki/Clients#authentication): Authenticate with API keys or OAuth for subscription-based access.
+    * [Patching API Requests](https://github.com/Dark-Alex-17/loki/wiki/Patches): Learn how to patch API requests for advanced customization.
+* [Custom Themes](https://github.com/Dark-Alex-17/loki/wiki/Themes): Change the look and feel of Loki to your preferences with custom themes.
 * [History](#history): A history of how Loki came to be.
 
 ## Prerequisites
 Loki requires the following tools to be installed on your system:
 * [jq](https://github.com/jqlang/jq)
     * `brew install jq`
-* [jira (optional)](https://github.com/ankitpokhrel/jira-cli/wiki/Installation) (For the `query_jira_issues` tool)
-    * `brew tap ankitpokhrel/jira-cli && brew install jira-cli`
-    * You'll need to [create a JIRA API token](https://id.atlassian.com/manage-profile/security/api-tokens) for authentication
-    * Then, save it as an environment variable to your shell profile:
-      ```sh
-      # ~/.bashrc or ~/.zshrc
-      export JIRA_API_TOKEN="your_jira_api_token_here"
-      ```
-    * Then run `jira init`, select installation type as `cloud`, and provide the required details to generate a config
-      file for the Jira CLI.
 * [usql](https://github.com/xo/usql) (For the `sql` agent)
     * `brew install xo/xo/usql`
 * [docker](https://docs.docker.com/engine/install/)
@@ -65,7 +58,7 @@ Loki requires the following tools to be installed on your system:
     * `curl -LsSf https://astral.sh/uv/install.sh | sh`
 
 These tools are used to provide various functionalities within Loki, such as document processing, JSON manipulation,
-interaction with Jira, and they are used within agents and tools.
+etc., and they are used within agents and tools.
 
 ## Install
 
@@ -137,6 +130,29 @@ 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 can update itself in place to the latest GitHub release. Run `loki --update`
+for the newest release, or `loki --update v0.4.0` for a specific version:
+
+```shell
+loki --update
+loki --update v0.4.0
+```
+
+The same is available from within the REPL via `.update` and `.update v0.4.0`.
+
+If Loki was installed with a package manager, prefer that package manager so its
+records stay in sync with the binary on disk; i.e. `brew upgrade loki` for Homebrew,
+or `cargo install --locked loki-ai` for Cargo.
+
+When Loki detects a package-manager install it prints a warning and asks for
+confirmation. In a non-interactive shell (no TTY), pass `--force` to update
+anyway:
+
+```shell
+loki --update --force
+```
+
 ## Getting Started
 After installation, you can generate the configuration files and directories by simply running:
 
@@ -153,23 +169,22 @@ loki --list-secrets
 
 ### 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 
+(set via `api_key` in the config or through the [vault](https://github.com/Dark-Alex-17/loki/wiki/Vault)). For providers that support OAuth (e.g. Claude Pro/Max 
 subscribers, Google Gemini), you can authenticate with your existing subscription instead:
 
 ```yaml
 # In your config.yaml
 clients:
   - type: claude
-    name: my-claude-oauth
     auth: oauth # Indicate you want to authenticate with OAuth instead of an API key
 ```
 
 ```sh
-loki --authenticate my-claude-oauth
+loki --authenticate claude
 # Or via the REPL: .authenticate
 ```
 
-For full details, see the [authentication documentation](./docs/clients/CLIENTS.md#authentication).
+For full details, see the [authentication documentation](https://github.com/Dark-Alex-17/loki/wiki/Clients#authentication).
 
 ### Tab-Completions
 You can also enable tab completions to make using Loki easier. To do so, add the following to your shell profile:
@@ -246,7 +261,7 @@ shown below:
 
 | Setting         | Description                                                                                                                                                                                                                                                                                                 |
 |-----------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
-| `repl_prelude`  | This setting lets you specify a default `session` or `role` to use when starting Loki in [REPL](./docs/REPL.md) mode. <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> |
+| `repl_prelude`  | This setting lets you specify a default `session` or `role` to use when starting Loki in [REPL](https://github.com/Dark-Alex-17/loki/wiki/REPL) mode. <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> |
 | `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`)                                                                                                                                        |
 
diff --git a/assets/agents/coder/README.md b/assets/agents/coder/README.md
index dd23a02..51c4477 100644
--- a/assets/agents/coder/README.md
+++ b/assets/agents/coder/README.md
@@ -1,40 +1,82 @@
 # Coder
 
-An AI agent that assists you with your coding tasks.
+A graph-based implementation agent. Plans, implements, and runs build +
+tests in a bounded fix-loop until verified. Designed to be delegated to by
+the **[Sisyphus](../sisyphus/README.md)** agent.
 
-This agent is designed to be delegated to by the **[Sisyphus](../sisyphus/README.md)** agent to implement code specifications. Sisyphus
-acts as the coordinator/architect, while Coder handles the implementation details.
+Coder is a [graph agent](https://github.com/Dark-Alex-17/loki/wiki/Graph-Agents): its workflow is
+defined declaratively in `graph.yaml`, with verification and the
+implement-fix loop enforced as graph edges rather than prose.
 
-## Features
+## Workflow
 
-- 🏗️ Intelligent project structure creation and management
-- 🖼️ Convert screenshots into clean, functional code
-- 📁 Comprehensive file system operations (create folders, files, read/write files)
-- 🧐 Advanced code analysis and improvement suggestions
-- 📊 Precise diff-based file editing for controlled code modifications
+```
+analyze_request (llm + output_schema)   plan + complexity extraction
+        ↓
+route_complexity (script)               opt-out approval gate (complexity ≥ 7)
+        ↓
+gate_approval (approval, optional)
+        ↓
+implement (llm + fs tools)              actual file edits
+        ↓
+verify_build (script)
+        ↓
+verify_tests (script)
+        ↓
+fix_loop_gate (script)                  back-edge to implement (bounded)
+        ↓
+end_success / end_rejected / end_failure
+```
 
-It can also be used as a standalone tool for direct coding assistance.
+End nodes emit one of three sentinel outcomes for the caller:
 
-## Pro-Tip: Use an IDE MCP Server for Improved Performance
-Many modern IDEs now include MCP servers that let LLMs perform operations within the IDE itself and use IDE tools. Using
-an IDE's MCP server dramatically improves the performance of coding agents. So if you have an IDE, try adding that MCP
-server to your config (see the [MCP Server docs](../../../docs/function-calling/MCP-SERVERS.md) to see how to configure
-them), and modify the agent definition to look like this:
+- `CODER_COMPLETE` — build and tests passed.
+- `CODER_REJECTED` — user rejected the plan at the approval gate.
+- `CODER_FAILED` — fix-loop exhausted; build/tests still failing.
+
+## Tuning
+
+The agent's `project_dir` is exposed via the standard `variables:` block,
+so it accepts the runtime override flag:
+
+```sh
+# Invoke from inside the project (project_dir defaults to ".")
+cd /path/to/your/project
+loki -a coder "Add a foo() function..."
+
+# Or invoke from anywhere with an explicit override
+loki -a coder --agent-variable project_dir /path/to/your/project "Add..."
+```
+
+`graph.yaml` `initial_state` exposes:
+
+- `max_fix_attempts` (default `3`) — fix-loop budget before `end_failure`.
+
+Environment overrides honored by the script nodes:
+
+- `BUILD_CMD` — skip project-type detection for the build/check command.
+- `TEST_CMD` — skip detection for tests.
+- `CODER_AUTOAPPROVE=1` — bypass the approval gate (for non-interactive runs
+  where complexity might trip the gate).
+
+## Pro-Tip: IDE MCP Server
+
+Modern IDEs (JetBrains, VS Code, Cursor, Zed, etc.) expose MCP servers
+that let LLMs use IDE tools directly. To wire one in, edit `graph.yaml`:
 
 ```yaml
-# ...
-
 mcp_servers:
-  - jetbrains # The name of your configured IDE MCP server
+  - your-ide-mcp-server
 
 global_tools:
-  # Keep useful read-only tools for reading files in other non-project directories
+  # Keep read-only fs tools for files outside the IDE project
   - fs_read.sh
   - fs_grep.sh
   - fs_glob.sh
 #  - fs_write.sh
 #  - fs_patch.sh
   - execute_command.sh
+```
 
-# ...
-```
\ No newline at end of file
+Then add the MCP server's write/patch tools to the `implement` node's
+`tools:` whitelist.
diff --git a/assets/agents/coder/config.yaml b/assets/agents/coder/config.yaml
deleted file mode 100644
index 730ce8c..0000000
--- a/assets/agents/coder/config.yaml
+++ /dev/null
@@ -1,129 +0,0 @@
-name: coder
-description: Implementation agent - writes code, follows patterns, verifies with builds
-version: 1.0.0
-temperature: 0.1
-
-auto_continue: true
-max_auto_continues: 15
-inject_todo_instructions: true
-
-variables:
-  - name: project_dir
-    description: Project directory to work in
-    default: '.'
-  - name: auto_confirm
-    description: Auto-confirm command execution
-    default: '1'
-
-global_tools:
-  - fs_read.sh
-  - fs_grep.sh
-  - fs_glob.sh
-  - fs_write.sh
-  - fs_patch.sh
-  - execute_command.sh
-
-instructions: |
-  You are a senior engineer. You write code that works on the first try.
-
-  ## Your Mission
-
-  Given an implementation task:
-  1. Check for orchestrator context first (see below)
-  2. Fill gaps only. Read files NOT already covered in context
-  3. Write the code (using tools, NOT chat output)
-  4. Verify it compiles/builds
-  5. Signal completion with a summary
-
-  ## Using Orchestrator Context (IMPORTANT)
-
-  When spawned by sisyphus, your prompt will often contain a `<context>` block
-  with prior findings: file paths, code patterns, and conventions discovered by
-  explore agents.
-
-  **If context is provided:**
-  1. Use it as your primary reference. Don't re-read files already summarized
-  2. Follow the code patterns shown. Snippets in context ARE the style guide
-  3. Read the referenced files ONLY IF you need more detail (e.g. full function
-     signature, import list, or adjacent code not included in the snippet)
-  4. If context includes a "Conventions" section, follow it exactly
-
-  **If context is NOT provided or is too vague to act on:**
-  Fall back to self-exploration: grep for similar files, read 1-2 examples,
-  match their style.
-
-  **Never ignore provided context.** It represents work already done upstream.
-
-  ## Todo System
-
-  For multi-file changes:
-  1. `todo__init` with the implementation goal
-  2. `todo__add` for each file to create/modify
-  3. Implement each, calling `todo__done` immediately after
-
-  ## Writing Code
-
-  **CRITICAL**: Write code using `write_file` tool, NEVER paste code in chat.
-
-  Correct:
-  ```
-  write_file --path "src/user.rs" --content "pub struct User { ... }"
-  ```
-
-  Wrong:
-  ```
-  Here's the implementation:
-  \`\`\`rust
-  pub struct User { ... }
-  \`\`\`
-  ```
-
-  ## File Reading Strategy (IMPORTANT - minimize token usage)
-
-  1. **Use grep to find relevant code** - `fs_grep --pattern "fn handle_request" --include "*.rs"` finds where things are
-  2. **Read only what you need** - `fs_read --path "src/main.rs" --offset 50 --limit 30` reads lines 50-79
-  3. **Never cat entire large files** - If 500+ lines, read the relevant section after grepping for it
-  4. **Use glob to find files** - `fs_glob --pattern "*.rs" --path src/` discovers files by name
-
-  ## Pattern Matching
-
-  Before writing ANY file:
-  1. Find a similar existing file (use `fs_grep` to locate, then `fs_read` to examine)
-  2. Match its style: imports, naming, structure
-  3. Follow the same patterns exactly
-
-  ## Verification
-
-  After writing files:
-  1. Run `verify_build` to check compilation
-  2. If it fails, fix the error (minimal change)
-  3. Don't move on until build passes
-
-  ## Completion Signal
-
-  When done, end your response with a summary so the parent agent knows what happened:
-
-  ```
-  CODER_COMPLETE: [summary of what was implemented, which files were created/modified, and build status]
-  ```
-
-  Or if something went wrong:
-  ```
-  CODER_FAILED: [what went wrong]
-  ```
-
-  ## Rules
-
-  1. **Write code via tools** - Never output code to chat
-  2. **Follow patterns** - Read existing files first
-  3. **Verify builds** - Don't finish without checking
-  4. **Minimal fixes** - If build fails, fix precisely
-  5. **No refactoring** - Only implement what's asked
-
-  ## Context
-  - Project: {{project_dir}}
-  - CWD: {{__cwd__}}
-  - Shell: {{__shell__}}
-  
-  ## Available tools:
-  {{__tools__}}
\ No newline at end of file
diff --git a/assets/agents/coder/graph.yaml b/assets/agents/coder/graph.yaml
new file mode 100644
index 0000000..1d5e9df
--- /dev/null
+++ b/assets/agents/coder/graph.yaml
@@ -0,0 +1,278 @@
+name: coder
+description: |
+  Implementation agent. Plans, implements, and runs build + tests in a
+  bounded fix-loop until verified. Designed to be delegated to by sisyphus.
+version: "1.0"
+
+temperature: 0.1
+
+global_tools:
+  - fs_cat.sh
+  - fs_ls.sh
+  - fs_write.sh
+  - fs_patch.sh
+  - execute_command.sh
+
+variables:
+  - name: project_dir
+    description: |
+      Absolute path to the project directory. Defaults to "." which is the
+      directory you invoked `loki` from. Override at runtime with
+      `loki -a coder --agent-variable project_dir /abs/path "..."`.
+    default: "."
+
+settings:
+  max_loop_iterations: 20
+  log_state_snapshots: true
+  validate_before_run: true
+  timeout: 1800
+
+initial_state:
+  project_dir: ""
+  fix_attempts: 0
+  max_fix_attempts: 3
+  fix_instructions: ""
+  build_output: ""
+  tests_output: ""
+  last_node_output: ""
+  plan_summary: ""
+  files_to_modify: []
+  files_to_create: []
+  risks: []
+  complexity_score: 0
+
+start: resolve_paths
+
+nodes:
+  resolve_paths:
+    id: resolve_paths
+    type: script
+    description: Resolve project_dir to an absolute path from the agent variable
+    script: scripts/resolve_paths.sh
+    timeout: 5
+    fallback: end_failure
+
+  analyze_request:
+    id: analyze_request
+    type: llm
+    description: Extract a structured plan and complexity score from the orchestrator's prompt
+    instructions: |
+      You are a senior engineer's planning assistant. Read the orchestrator's
+      request and emit a structured plan. You only plan. You never edit files.
+
+      Score complexity from 1 to 10:
+        1-3: trivial - single file, <=20 lines changed, obvious approach
+        4-6: moderate - 2-5 files, clear approach, some pattern matching
+        7-10: complex - multi-component, ambiguous tradeoffs, refactoring,
+              or wide blast radius
+
+      Be specific in `files_to_modify` and `files_to_create`. All paths
+      MUST be absolute. The project root is {{project_dir}}. Prefer paths
+      like "{{project_dir}}/src/foo.rs" over "src/foo.rs". The implementer
+      uses these paths directly with fs_write and fs_patch tools, which
+      resolve relative paths against the loki invocation directory (NOT
+      the project dir). Empty arrays are fine if no files in that category.
+
+      `risks` is a list of short strings. Anything that could derail the
+      implementation: unknown dependencies, brittle tests, blast radius,
+      etc. Empty list is fine.
+
+      Project directory: {{project_dir}}
+    prompt: "{{initial_prompt}}"
+    tools: []
+    output_schema:
+      type: object
+      properties:
+        plan_summary:
+          type: string
+          description: 1-3 sentences summarizing what will be done
+        files_to_modify:
+          type: array
+          items: {type: string}
+        files_to_create:
+          type: array
+          items: {type: string}
+        complexity_score:
+          type: integer
+          minimum: 1
+          maximum: 10
+        risks:
+          type: array
+          items: {type: string}
+      required: [plan_summary, files_to_modify, files_to_create, complexity_score, risks]
+    state_updates:
+      last_node_output: "{{output}}"
+    fallback: end_failure
+    next: route_complexity
+
+  route_complexity:
+    id: route_complexity
+    type: script
+    description: Route to approval gate for complex plans; skip otherwise
+    script: scripts/route_complexity.sh
+    timeout: 5
+    fallback: implement
+
+  gate_approval:
+    id: gate_approval
+    type: approval
+    description: Optional human checkpoint for high-complexity plans
+    question: |
+      ## Plan
+      {{plan_summary}}
+
+      ## Files to modify
+      {{files_to_modify}}
+
+      ## Files to create
+      {{files_to_create}}
+
+      ## Risks
+      {{risks}}
+
+      Complexity: {{complexity_score}}/10
+
+      Approve this plan?
+    options:
+      - "yes"
+      - "no"
+    routes:
+      "yes": implement
+      "no": end_rejected
+    on_other: end_rejected
+
+  implement:
+    id: implement
+    type: llm
+    description: Write code via fs tools. Bounded tool-call loop.
+    instructions: |
+      You are a senior engineer. Implement the plan by writing code via
+      tools. Follow existing patterns in the codebase.
+
+      ## Writing code
+
+      1. Use `fs_patch` for surgical edits to existing files.
+      2. Use `fs_write` for new files or full rewrites.
+      3. NEVER output code to chat. Always use tools.
+      4. ALWAYS pass ABSOLUTE paths to fs_write and fs_patch. Relative
+         paths resolve against the loki invocation directory (not the
+         project dir), which is rarely what you want. The project root
+         is {{project_dir}}.
+
+      ## File reading
+
+      1. Use `execute_command` to grep/find:
+         `execute_command --command "grep -rn 'fn handle_request' --include='*.rs' ."`
+         `execute_command --command "find . -name '*.rs' -not -path '*/target/*'"`
+      2. Read only what you need:
+         `fs_cat --path "src/main.rs" --offset 50 --limit 30`
+      3. Never read entire large files. Use offset/limit.
+      4. Use `fs_ls` to list directory contents.
+
+      ## Pattern matching
+
+      Before writing ANY file:
+      1. Find a similar existing file (grep, then read).
+      2. Match its style: imports, naming, structure, error handling.
+      3. Follow the same patterns exactly. Do not invent new ones.
+
+      ## Fix loop
+
+      If the "Fix loop status" section in your user prompt is non-empty,
+      the previous attempt failed verification. Read the error, identify
+      the minimal fix, apply it. Do not refactor while fixing.
+
+      ## Rules
+
+      1. Match existing patterns - read examples first.
+      2. Minimal changes - implement only what's asked.
+      3. Never suppress errors (`as any`, `@ts-ignore`, `#[allow(...)]`
+         on unfamiliar lints, etc.).
+      4. No dead code, no commented-out blocks, no premature abstractions.
+      5. End your turn when editing is done. The graph runs verification next.
+
+      Project directory: {{project_dir}}
+    prompt: |
+      ## Plan summary
+      {{plan_summary}}
+
+      ## Files involved
+      - Modify: {{files_to_modify}}
+      - Create: {{files_to_create}}
+
+      ## Original request from the orchestrator
+      {{initial_prompt}}
+
+      ## Fix loop status
+      {{fix_instructions}}
+    tools:
+      - fs_cat
+      - fs_ls
+      - fs_write
+      - fs_patch
+      - execute_command
+    max_iterations: 30
+    state_updates:
+      last_node_output: "{{output}}"
+    fallback: end_failure
+    next: verify_build
+
+  verify_build:
+    id: verify_build
+    type: script
+    description: Run the project's check/build command. Routes to verify_tests on success, fix_loop_gate on failure.
+    script: scripts/verify_build.sh
+    timeout: 300
+    fallback: fix_loop_gate
+
+  verify_tests:
+    id: verify_tests
+    type: script
+    description: Run the project's test command. Routes to end_success on pass, fix_loop_gate on failure.
+    script: scripts/verify_tests.sh
+    timeout: 600
+    fallback: fix_loop_gate
+
+  fix_loop_gate:
+    id: fix_loop_gate
+    type: script
+    description: Budget gate. Loops back to implement with fix_instructions populated, or terminates as end_failure.
+    script: scripts/fix_loop_gate.sh
+    timeout: 5
+    fallback: end_failure
+
+  end_success:
+    id: end_success
+    type: end
+    output: |
+      CODER_COMPLETE
+      Plan: {{plan_summary}}
+      Files modified: {{files_to_modify}}
+      Files created: {{files_to_create}}
+      Build: passed
+      Tests: passed
+
+  end_rejected:
+    id: end_rejected
+    type: end
+    output: |
+      CODER_REJECTED
+      Plan was rejected at the approval gate.
+      Plan: {{plan_summary}}
+
+  end_failure:
+    id: end_failure
+    type: end
+    output: |
+      CODER_FAILED
+      Plan: {{plan_summary}}
+      Attempts: {{fix_attempts}}/{{max_fix_attempts}}
+
+      Last node output:
+      {{last_node_output}}
+
+      Last build output:
+      {{build_output}}
+
+      Last tests output:
+      {{tests_output}}
diff --git a/assets/agents/coder/scripts/fix_loop_gate.sh b/assets/agents/coder/scripts/fix_loop_gate.sh
new file mode 100644
index 0000000..29a0bf0
--- /dev/null
+++ b/assets/agents/coder/scripts/fix_loop_gate.sh
@@ -0,0 +1,49 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+if [[ -n "${GRAPH_STATE_FILE:-}" ]]; then
+  state=$(cat "$GRAPH_STATE_FILE")
+elif [[ -n "${GRAPH_STATE:-}" ]]; then
+  state="$GRAPH_STATE"
+else
+  state='{}'
+fi
+
+fix_attempts=$(echo "$state" | jq -r '.fix_attempts // 0')
+max_fix_attempts=$(echo "$state" | jq -r '.max_fix_attempts // 3')
+build_ok=$(echo "$state" | jq -r '.build_ok | if . == null then "true" else (. | tostring) end')
+tests_ok=$(echo "$state" | jq -r '.tests_ok | if . == null then "true" else (. | tostring) end')
+build_output=$(echo "$state" | jq -r '.build_output // ""')
+tests_output=$(echo "$state" | jq -r '.tests_output // ""')
+
+if (( fix_attempts >= max_fix_attempts )); then
+  jq -nc \
+    --argjson n "$fix_attempts" \
+    '{
+      "fix_attempts": $n,
+      "_next": "end_failure"
+    }'
+  exit 0
+fi
+
+next_attempts=$((fix_attempts + 1))
+
+if [[ "$build_ok" != "true" ]]; then
+  fix_instructions=$(printf '## Fix loop status (attempt %d of %d)\n\nThe previous attempt failed the build.\n\nBuild output:\n```\n%s\n```\n\nIdentify the minimal fix and apply it. Do not refactor.' \
+    "$next_attempts" "$max_fix_attempts" "$build_output")
+elif [[ "$tests_ok" != "true" ]]; then
+  fix_instructions=$(printf '## Fix loop status (attempt %d of %d)\n\nBuild passed but tests failed.\n\nTest output:\n```\n%s\n```\n\nIdentify the minimal fix and apply it. Do not refactor.' \
+    "$next_attempts" "$max_fix_attempts" "$tests_output")
+else
+  fix_instructions=$(printf '## Fix loop status (attempt %d of %d)\n\nfix_loop_gate was reached but no failure was detected in state. Re-run the verification step.' \
+    "$next_attempts" "$max_fix_attempts")
+fi
+
+jq -nc \
+  --argjson n "$next_attempts" \
+  --arg fi "$fix_instructions" \
+  '{
+    "fix_attempts": $n,
+    "fix_instructions": $fi,
+    "_next": "implement"
+  }'
diff --git a/assets/agents/coder/scripts/resolve_paths.sh b/assets/agents/coder/scripts/resolve_paths.sh
new file mode 100644
index 0000000..2c9433c
--- /dev/null
+++ b/assets/agents/coder/scripts/resolve_paths.sh
@@ -0,0 +1,12 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+project_dir="${LLM_AGENT_VAR_PROJECT_DIR:-.}"
+resolved=$(cd "$project_dir" 2>/dev/null && pwd) || resolved="$project_dir"
+
+jq -nc \
+  --arg pd "$resolved" \
+  '{
+    "project_dir": $pd,
+    "_next": "analyze_request"
+  }'
diff --git a/assets/agents/coder/scripts/route_complexity.sh b/assets/agents/coder/scripts/route_complexity.sh
new file mode 100644
index 0000000..d45ca91
--- /dev/null
+++ b/assets/agents/coder/scripts/route_complexity.sh
@@ -0,0 +1,23 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+if [[ -n "${GRAPH_STATE_FILE:-}" ]]; then
+  state=$(cat "$GRAPH_STATE_FILE")
+elif [[ -n "${GRAPH_STATE:-}" ]]; then
+  state="$GRAPH_STATE"
+else
+  state='{}'
+fi
+
+complexity=$(echo "$state" | jq -r '.complexity_score // 0')
+
+if [[ "${CODER_AUTOAPPROVE:-0}" == "1" ]]; then
+  jq -nc '{"_next": "implement"}'
+  exit 0
+fi
+
+if (( complexity >= 7 )); then
+  jq -nc '{"_next": "gate_approval"}'
+else
+  jq -nc '{"_next": "implement"}'
+fi
diff --git a/assets/agents/coder/scripts/verify_build.sh b/assets/agents/coder/scripts/verify_build.sh
new file mode 100644
index 0000000..f9b9d65
--- /dev/null
+++ b/assets/agents/coder/scripts/verify_build.sh
@@ -0,0 +1,55 @@
+#!/usr/bin/env bash
+set -uo pipefail
+
+# shellcheck disable=SC1091
+source "$(dirname "$0")/../../.shared/utils.sh"
+
+if [[ -n "${GRAPH_STATE_FILE:-}" ]]; then
+  state=$(cat "$GRAPH_STATE_FILE")
+elif [[ -n "${GRAPH_STATE:-}" ]]; then
+  state="$GRAPH_STATE"
+else
+  state='{}'
+fi
+
+project_dir=$(echo "$state" | jq -r '.project_dir // "."')
+
+if [[ -n "${BUILD_CMD:-}" ]]; then
+  cmd="$BUILD_CMD"
+else
+  project_info=$(detect_project "$project_dir")
+  cmd=$(echo "$project_info" | jq -r '.check // .build // ""')
+fi
+
+if [[ -z "$cmd" || "$cmd" == "null" ]]; then
+  jq -nc '{
+    "build_ok": true,
+    "build_output": "(no build/check command available for this project type)",
+    "_next": "verify_tests"
+  }'
+  exit 0
+fi
+
+exit_code=0
+output=$(cd "$project_dir" && eval "$cmd" 2>&1) || exit_code=$?
+
+if (( exit_code == 0 )); then
+  jq -nc \
+    --arg out "$output" \
+    --arg cmd "$cmd" \
+    '{
+      "build_ok": true,
+      "build_output": ("Ran: " + $cmd + "\n\n" + $out),
+      "_next": "verify_tests"
+    }'
+else
+  jq -nc \
+    --arg out "$output" \
+    --arg cmd "$cmd" \
+    --argjson rc "$exit_code" \
+    '{
+      "build_ok": false,
+      "build_output": ("Ran: " + $cmd + "\nExit code: " + ($rc | tostring) + "\n\n" + $out),
+      "_next": "fix_loop_gate"
+    }'
+fi
diff --git a/assets/agents/coder/scripts/verify_tests.sh b/assets/agents/coder/scripts/verify_tests.sh
new file mode 100644
index 0000000..102364e
--- /dev/null
+++ b/assets/agents/coder/scripts/verify_tests.sh
@@ -0,0 +1,55 @@
+#!/usr/bin/env bash
+set -uo pipefail
+
+# shellcheck disable=SC1091
+source "$(dirname "$0")/../../.shared/utils.sh"
+
+if [[ -n "${GRAPH_STATE_FILE:-}" ]]; then
+  state=$(cat "$GRAPH_STATE_FILE")
+elif [[ -n "${GRAPH_STATE:-}" ]]; then
+  state="$GRAPH_STATE"
+else
+  state='{}'
+fi
+
+project_dir=$(echo "$state" | jq -r '.project_dir // "."')
+
+if [[ -n "${TEST_CMD:-}" ]]; then
+  cmd="$TEST_CMD"
+else
+  project_info=$(detect_project "$project_dir")
+  cmd=$(echo "$project_info" | jq -r '.test // ""')
+fi
+
+if [[ -z "$cmd" || "$cmd" == "null" ]]; then
+  jq -nc '{
+    "tests_ok": true,
+    "tests_output": "(no test command available for this project type)",
+    "_next": "end_success"
+  }'
+  exit 0
+fi
+
+exit_code=0
+output=$(cd "$project_dir" && eval "$cmd" 2>&1) || exit_code=$?
+
+if (( exit_code == 0 )); then
+  jq -nc \
+    --arg out "$output" \
+    --arg cmd "$cmd" \
+    '{
+      "tests_ok": true,
+      "tests_output": ("Ran: " + $cmd + "\n\n" + $out),
+      "_next": "end_success"
+    }'
+else
+  jq -nc \
+    --arg out "$output" \
+    --arg cmd "$cmd" \
+    --argjson rc "$exit_code" \
+    '{
+      "tests_ok": false,
+      "tests_output": ("Ran: " + $cmd + "\nExit code: " + ($rc | tostring) + "\n\n" + $out),
+      "_next": "fix_loop_gate"
+    }'
+fi
diff --git a/assets/agents/coder/tools.sh b/assets/agents/coder/tools.sh
index e7cc50a..d1086a7 100755
--- a/assets/agents/coder/tools.sh
+++ b/assets/agents/coder/tools.sh
@@ -14,99 +14,6 @@ _project_dir() {
   (cd "${dir}" 2>/dev/null && pwd) || echo "${dir}"
 }
 
-# Normalize a path to be relative to project root.
-# Strips the project_dir prefix if the LLM passes an absolute path.
-# Usage: local rel_path; rel_path=$(_normalize_path "/abs/or/rel/path")
-_normalize_path() {
-  local input_path="$1"
-  local project_dir
-  project_dir=$(_project_dir)
-
-  if [[ "${input_path}" == /* ]]; then
-    input_path="${input_path#"${project_dir}"/}"
-  fi
-
-  input_path="${input_path#./}"
-  echo "${input_path}"
-}
-
-# @cmd Read a file's contents before modifying
-# @option --path! Path to the file (relative to project root)
-read_file() {
-  local file_path
-	# shellcheck disable=SC2154
-  file_path=$(_normalize_path "${argc_path}")
-  local project_dir
-  project_dir=$(_project_dir)
-  local full_path="${project_dir}/${file_path}"
-  
-  if [[ ! -f "${full_path}" ]]; then
-    warn "File not found: ${file_path}" >> "$LLM_OUTPUT"
-    return 0
-  fi
-  
-  {
-  	info "Reading: ${file_path}"
-  	echo ""
-  	cat "${full_path}"
-  } >> "$LLM_OUTPUT"
-}
-
-# @cmd Write complete file contents
-# @option --path! Path for the file (relative to project root)
-# @option --content! Complete file contents to write
-write_file() {
-  local file_path
-  file_path=$(_normalize_path "${argc_path}")
-  # shellcheck disable=SC2154
-  local content="${argc_content}"
-  local project_dir
-  project_dir=$(_project_dir)
-  local full_path="${project_dir}/${file_path}"
-  
-  mkdir -p "$(dirname "${full_path}")"
-  printf '%s' "${content}" > "${full_path}"
-  
-  green "Wrote: ${file_path}" >> "$LLM_OUTPUT"
-}
-
-# @cmd Find files similar to a given path (for pattern matching)
-# @option --path! Path to find similar files for
-find_similar_files() {
-  local file_path
-  file_path=$(_normalize_path "${argc_path}")
-  local project_dir
-  project_dir=$(_project_dir)
-  
-  local ext="${file_path##*.}"
-  local dir
-  dir=$(dirname "${file_path}")
-  
-  info "Similar files to: ${file_path}" >> "$LLM_OUTPUT"
-  echo "" >> "$LLM_OUTPUT"
-  
-  local results
-  results=$(find "${project_dir}/${dir}" -maxdepth 1 -type f -name "*.${ext}" \
-    ! -name "$(basename "${file_path}")" \
-    ! -name "*test*" \
-    ! -name "*spec*" \
-    2>/dev/null | sed "s|^${project_dir}/||" | head -3)
-  
-  if [[ -z "${results}" ]]; then
-    results=$(find "${project_dir}/src" -type f -name "*.${ext}" \
-      ! -name "*test*" \
-      ! -name "*spec*" \
-      -not -path '*/target/*' \
-      2>/dev/null | sed "s|^${project_dir}/||" | head -3)
-  fi
-  
-  if [[ -n "${results}" ]]; then
-    echo "${results}" >> "$LLM_OUTPUT"
-  else
-    warn "No similar files found" >> "$LLM_OUTPUT"
-  fi
-}
-
 # @cmd Verify the project builds successfully
 verify_build() {
   local project_dir
@@ -189,28 +96,3 @@ get_project_structure() {
   } >> "$LLM_OUTPUT"
 }
 
-# @cmd Search for content in the codebase
-# @option --pattern! Pattern to search for
-search_code() {
-	# shellcheck disable=SC2154
-  local pattern="${argc_pattern}"
-  local project_dir
-  project_dir=$(_project_dir)
-  
-  info "Searching: ${pattern}" >> "$LLM_OUTPUT"
-  echo "" >> "$LLM_OUTPUT"
-  
-  local results
-  results=$(grep -rn "${pattern}" "${project_dir}" 2>/dev/null | \
-    grep -v '/target/' | \
-    grep -v '/node_modules/' | \
-    grep -v '/.git/' | \
-    sed "s|^${project_dir}/||" | \
-    head -20) || true
-  
-  if [[ -n "${results}" ]]; then
-    echo "${results}" >> "$LLM_OUTPUT"
-  else
-    warn "No matches" >> "$LLM_OUTPUT"
-  fi
-}
\ No newline at end of file
diff --git a/assets/agents/deep-research/README.md b/assets/agents/deep-research/README.md
new file mode 100644
index 0000000..fbb1f2f
--- /dev/null
+++ b/assets/agents/deep-research/README.md
@@ -0,0 +1,274 @@
+# deep-research
+
+A deep web research agent, built as a Loki graph agent. It plans an
+investigation, decomposes it into sub-questions researched in
+parallel, grounds the work in a local knowledge corpus, vets the
+credibility of cited sources, runs a reflexion self-critique loop to
+revise weak findings, delegates the final write-up to a focused
+sub-agent, checks that the cited sources are reachable, and gates the
+result behind human approval.
+
+Unlike a regular agent (which takes a goal and improvises the steps),
+this agent runs a fixed graph: every request goes through the same
+`plan -> parallel research -> vet -> critique -> synthesize -> verify -> approve`
+pipeline.
+
+This agent is also the **canonical reference for the Loki graph
+system**: it exercises every node type (`script`, `llm`, `rag`, `map`,
+`agent`, `input`, `approval`, `end`) and both static fan-out and
+dynamic `map` fan-out. If you are learning how to build a graph
+agent, this is the file to read alongside the
+[Graph-Agents wiki](https://github.com/Dark-Alex-17/loki/wiki/Graph-Agents).
+
+## Workflow
+
+17 nodes. `->` is the static route; a script node can also route
+dynamically via `_next`. The `▶▶` line is a parallel super-step —
+those branches run concurrently:
+
+```
+parse_request (script)              -> bootstrap_research   (or -> ask_topic if no topic)
+ask_topic (input)                   -> bootstrap_research
+bootstrap_research (script)         -> [plan, knowledge_lookup]   ▶▶ parallel
+plan (llm + output_schema)          -> research_each_question
+knowledge_lookup (rag)              -> research_each_question
+research_each_question (map)        -> combine_findings    (spawns one branch per question)
+  └─ research_one_question (llm)    (atomic; runs N×, joins at map)
+combine_findings (script)           -> vet_sources
+vet_sources (llm + custom tool)     -> critique
+critique (llm)                      -> reflexion_gate
+reflexion_gate (script)             -> synthesize  (or -> research_each_question: reflexion loop)
+synthesize (agent: report-writer)   -> verify_sources
+verify_sources (script)             -> approve
+approve (approval)                  -> end_accepted          ("accept")
+                                    -> end_rejected          ("reject")
+                                    -> incorporate_feedback   (any free-form answer)
+incorporate_feedback (script)       -> research_each_question (the human-feedback loop)
+```
+
+### Node-type breakdown
+
+| Type | Nodes |
+|---|---|
+| `script` (Python) | `parse_request`, `bootstrap_research`, `combine_findings`, `reflexion_gate`, `verify_sources`, `incorporate_feedback` |
+| `llm` (tools: `[]`) | `plan`, `critique` |
+| `llm` (with tool whitelist) | `research_one_question`, `vet_sources` |
+| `rag` | `knowledge_lookup` — local corpus retrieval |
+| `map` | `research_each_question` — dynamic fan-out per sub-question |
+| `agent` | `synthesize` — spawns the `report-writer` sub-agent |
+| `input` | `ask_topic` |
+| `approval` | `approve` |
+| `end` | `end_accepted`, `end_rejected` |
+
+## Parallel execution
+
+The graph has two parallel super-steps where Loki's BSP scheduler runs
+branches concurrently.
+
+**1. Context loading (`plan` ‖ `knowledge_lookup`)** — after
+`bootstrap_research`, the LLM planner (which decomposes the topic into
+sub-questions) and the RAG retrieval over the local `knowledge/`
+corpus run side by side. They write disjoint state keys (`plan` writes
+`research_plan` and `questions`; `knowledge_lookup` writes
+`local_context` and `local_sources`) so no reducer is needed.
+
+**2. Per-question research (`research_each_question` map)** — the
+plan emits a `questions` array (3-5 entries, enforced by its
+`output_schema`). The `map` node spawns one parallel branch per
+question (`max_concurrency: 3`). Each branch is an isolated
+`research_one_question` LLM invocation with web tools, instructed to
+investigate exactly its assigned question. Outputs collect into
+`question_findings` in input order, then `combine_findings` joins
+them into a single `findings` Markdown document for downstream nodes.
+
+`settings.max_concurrency: 4` is the graph-wide cap; the per-`map`
+override (`max_concurrency: 3` on `research_each_question`) is
+deliberately lower to leave headroom for the planner's tool calls
+running alongside RAG.
+
+## Local knowledge corpus
+
+`knowledge_lookup` is a `rag` node — it runs hybrid (vector + keyword)
+retrieval over every file in `knowledge/`. The directory ships with a
+small `research-style-notes.md` so the RAG node has something to
+retrieve against on a clean install; drop your own Markdown notes,
+PDFs, or text files into `knowledge/` to bias the research toward
+your local context.
+
+The knowledge base is built once, at agent-load time, into
+`~/.config/loki/agents/deep-research/knowledge_lookup.yaml`. Because
+the node fully specifies its build config (`embedding_model`,
+`chunk_size`, `chunk_overlap`), the build is non-interactive. Delete
+that cached file after adding or changing knowledge to force a
+rebuild.
+
+## Sub-agent: report-writer
+
+The `synthesize` node is an `agent` node that spawns the
+`report-writer` sub-agent (`assets/agents/report-writer/`). This is
+the agent-as-tool pattern: the orchestrating graph delegates the
+writing phase to a focused sub-agent dedicated to coherent prose,
+while the research phase uses different (typically cheaper) LLM nodes
+for fast-and-many-question investigation.
+
+The `report-writer` sub-agent has no tools — it cannot access the
+web, cannot search, and cannot invent facts. It reads only the
+findings it is given and produces a final Markdown report preserving
+every inline citation. See `assets/agents/report-writer/README.md`
+for details.
+
+## Tools and tool scoping
+
+This agent demonstrates Loki's three tool sources and how an `llm`
+node's `tools:` whitelist scopes them per node.
+
+The agent's full tool universe, declared in `graph.yaml`:
+
+- **Global tools** (`global_tools`): `web_search_loki`,
+  `fetch_url_via_curl`, `search_arxiv` - Loki's built-in tool scripts.
+- **MCP server** (`mcp_servers`): `ddg-search` - a DuckDuckGo web
+  search MCP server. Referenced in a whitelist as `mcp:ddg-search`.
+- **Custom agent tool** (`tools.sh`): `classify_source` - a
+  deterministic source-credibility classifier shipped with this agent.
+
+No node receives all of these. Each `llm` node's `tools:` whitelist
+narrows the universe to exactly what that step needs:
+
+| Node | `tools:` whitelist | Draws from |
+|---|---|---|
+| `plan`, `critique` | `[]` | nothing - pure reasoning |
+| `research_one_question` | `web_search_loki`, `fetch_url_via_curl`, `search_arxiv`, `mcp:ddg-search` | global tools + MCP |
+| `vet_sources` | `classify_source` | the custom tool only |
+
+`research_one_question` (each parallel branch of the map) can search
+and fetch but cannot classify sources; `vet_sources` can classify
+sources but cannot touch the web. That separation is the point of the
+`tools:` whitelist: a node gets only the tools its job calls for,
+never the agent's full set.
+
+The `classify_source` custom tool (`tools.sh`) takes a URL and returns
+a credibility tier (government, academic, preprint, organization,
+unverified) derived from the host and top-level domain. It is
+deterministic - exactly the kind of logic a tool should own rather than
+the LLM guessing.
+
+Web search may require API-key configuration; see the
+[Tools](https://github.com/Dark-Alex-17/loki/wiki/Tools) docs.
+`fetch_url_via_curl`, `search_arxiv`, and `classify_source` work
+without a key.
+
+## Setup
+
+`research_one_question` (each parallel branch of the `map`) uses the
+`ddg-search` MCP server via `mcp:ddg-search`. It is one of Loki's
+default MCP servers; make sure it is registered in
+`~/.config/loki/mcp.json` (run `loki --install mcp_config` to restore
+the default template if it is missing). If `ddg-search` is unavailable,
+the branches still have their global web-search tools to fall back on.
+
+The `synthesize` node spawns the `report-writer` sub-agent. Both
+agents ship with `loki agents install`; if you install one manually,
+install both so the agent reference resolves.
+
+## Reflexion
+
+The agent has two loops, both built with script nodes that route via
+`_next`. The engine allows back-edges at runtime; the validator only
+rejects cycles built from static `next` / `routes` edges, so script
+`_next` loops are always allowed.
+
+**Automated reflexion loop.** After the parallel research map and
+`vet_sources`, the `critique` node reviews the merged findings
+against the research plan and the source credibility assessment, and
+emits `VERDICT: PASS` or `VERDICT: REVISE` with specific feedback.
+`reflexion_gate.py` then:
+
+- `PASS` -> continue to `synthesize`.
+- `REVISE`, budget remaining -> loop back to `research_each_question`,
+  with the critique injected as `research_feedback` so every parallel
+  branch sees it on the retry.
+- `REVISE`, budget spent -> continue to `synthesize` anyway (the human
+  approval step is the final backstop).
+
+The budget is `MAX_REFLEXION_REVISIONS` in `reflexion_gate.py`
+(default 2, so the research map runs at most 3 times per pass).
+
+**Human-feedback loop.** At `approve` the user answers `accept`,
+`reject`, or types their own feedback. A free-form answer routes via
+the approval node's `on_other` to `incorporate_feedback.py`, which
+folds that text into `research_feedback` and loops back to
+`research_each_question` for another parallel pass.
+
+`settings.max_loop_iterations` (40) is the engine's infinite-loop
+backstop: it caps the total visits to any single node.
+
+## Running
+
+```sh
+loki agents install                  # ships deep-research
+loki -a deep-research "How does HTTP/3 differ from HTTP/2?"
+loki -a deep-research "Recent advances in solid-state batteries"
+loki -a deep-research                # no prompt -> triggers ask_topic
+```
+
+## Anti-hallucination
+
+- `research_one_question` (each map branch) is instructed to back
+  every claim with a real retrieved source and never to fabricate
+  URLs, titles, or DOIs.
+- `vet_sources` classifies every cited source so weak sources are
+  visible to the critique step.
+- `critique` independently reviews the merged findings and sends weak
+  or uncited work back for another parallel research pass.
+- `synthesize` (the `report-writer` sub-agent) is grounded: it may use
+  only the gathered findings and must keep each claim's inline source.
+  It has no tools and cannot browse the web.
+- `verify_sources` probes every cited URL / DOI with an HTTP HEAD
+  request and reports which are unreachable, so the human reviewer
+  sees broken citations before approving.
+
+## Customizing
+
+- **Loop budget.** `MAX_REFLEXION_REVISIONS` in `reflexion_gate.py`.
+- **Map concurrency.** The `research_each_question` node's
+  `max_concurrency: 3` caps simultaneous web-research branches.
+  Raise to investigate more questions in parallel; lower to be gentle
+  on rate-limited providers.
+- **Per-node model.** Add `model: anthropic:...` to any `llm` node.
+  Cheap models work well for `plan` / `critique` / `vet_sources`; the
+  heavy intelligence is needed in `research_one_question` and the
+  `report-writer` sub-agent.
+- **Tool scope.** Narrow the `research_one_question` node's `tools:`
+  list to constrain where each branch looks (for example, drop
+  `web_search_loki` and `mcp:ddg-search` to force arXiv-only
+  research).
+- **Local knowledge.** Drop files into `knowledge/` to bias every
+  research branch toward your local context (see the *Local
+  knowledge corpus* section above).
+- **Different writer.** Replace `agent: report-writer` on the
+  `synthesize` node with the name of any other agent. The
+  orchestrator does not care what kind of agent the writer is.
+- **Skip approval.** Point both `approve` routes at `end_accepted`,
+  or wire `verify_sources` straight to an `end` node.
+
+## Files
+
+```
+assets/agents/deep-research/
+  graph.yaml                    - agent config + 17-node workflow
+  tools.sh                      - classify_source custom tool
+  README.md                     - this file
+  knowledge/
+    README.md                   - corpus-format notes
+    research-style-notes.md     - starter knowledge file (replace with your notes)
+  scripts/
+    parse_request.py            - _next: bootstrap_research, or ask_topic if no topic
+    bootstrap_research.py       - fan-out source: next [plan, knowledge_lookup]
+    combine_findings.py         - joins map output (question_findings) into findings
+    reflexion_gate.py           - _next: research_each_question (revise) or synthesize
+    verify_sources.py           - HTTP HEAD on cited URLs / DOIs
+    incorporate_feedback.py     - _next: research_each_question, with user feedback
+```
+
+See also `assets/agents/report-writer/` — the sub-agent the
+`synthesize` node spawns.
diff --git a/assets/agents/deep-research/graph.yaml b/assets/agents/deep-research/graph.yaml
new file mode 100644
index 0000000..7c8f9e6
--- /dev/null
+++ b/assets/agents/deep-research/graph.yaml
@@ -0,0 +1,293 @@
+name: deep-research
+description: |
+  Deep web research workflow. Plans an investigation, decomposes it
+  into sub-questions researched in parallel, grounds the work in a
+  local knowledge corpus, vets the credibility of cited sources, runs
+  a reflexion self-critique loop to revise weak or incomplete findings,
+  delegates the final write-up to a focused sub-agent, checks that the
+  cited sources are reachable, and gates the result behind human
+  approval. A reviewer's free-form feedback at the approval step feeds
+  back into another research pass.
+
+  This is the canonical Loki graph-agent reference: it exercises every
+  node type (script, llm, rag, map, agent, input, approval, end) and
+  both static fan-out and dynamic map fan-out.
+
+version: "1.0"
+
+temperature: 0.0
+
+global_tools:
+  - web_search_loki.sh
+  - fetch_url_via_curl.sh
+  - search_arxiv.sh
+
+mcp_servers:
+  - ddg-search
+
+conversation_starters:
+  - "How does HTTP/3 differ from HTTP/2?"
+  - "Summarize recent advances in solid-state battery chemistry"
+
+settings:
+  max_loop_iterations: 40
+  log_state_snapshots: false
+  validate_before_run: true
+  max_concurrency: 4
+
+initial_state:
+  research_feedback: ""
+  research_attempts: 0
+  local_context: ""
+  local_sources: ""
+
+start: parse_request
+
+nodes:
+
+  parse_request:
+    id: parse_request
+    type: script
+    script: scripts/parse_request.py
+    next: bootstrap_research
+
+  ask_topic:
+    id: ask_topic
+    type: input
+    question: "What would you like me to research?"
+    validation: "len(input) > 0"
+    state_updates:
+      topic: "{{input}}"
+    next: bootstrap_research
+
+  bootstrap_research:
+    id: bootstrap_research
+    type: script
+    script: scripts/bootstrap_research.py
+    next: [plan, knowledge_lookup]
+
+  plan:
+    id: plan
+    type: llm
+    instructions: |
+      You are a research planner. Given a topic, produce a focused
+      research plan and decompose it into 3-5 specific sub-questions
+      that can each be researched independently in parallel.
+
+      The plan is a short narrative naming the key questions and the
+      kinds of sources that would be authoritative. The sub-questions
+      are precise, self-contained queries (each one is sent on its own
+      to a separate research worker, so they must be answerable
+      without each other's context).
+    prompt: "Research topic: {{topic}}"
+    tools: []
+    output_schema:
+      type: object
+      properties:
+        research_plan:
+          type: string
+          description: A short plan narrative.
+        questions:
+          type: array
+          items: { type: string }
+          minItems: 1
+          maxItems: 6
+          description: 3-5 specific, self-contained sub-questions.
+      required: [research_plan, questions]
+    next: research_each_question
+
+  knowledge_lookup:
+    id: knowledge_lookup
+    type: rag
+    documents:
+      - ./knowledge/
+    query: "{{topic}}"
+    top_k: 6
+    chunk_size: 1000
+    chunk_overlap: 100
+    state_updates:
+      local_context: "{{output.context}}"
+      local_sources: "{{output.sources}}"
+    next: research_each_question
+
+  research_each_question:
+    id: research_each_question
+    type: map
+    over: "{{questions}}"
+    as: question
+    branch: research_one_question
+    collect_into: question_findings
+    max_concurrency: 3
+    next: combine_findings
+
+  research_one_question:
+    id: research_one_question
+    type: llm
+    instructions: |
+      You are a web research assistant. Investigate the SINGLE question
+      given to you using your tools: search the web, fetch and read
+      pages, and search arXiv for academic sources.
+
+      Rules:
+        - Every factual claim must be backed by a real source you
+          actually retrieved. Never fabricate URLs, page titles,
+          authors, or DOIs.
+        - Prefer primary and authoritative sources over aggregators.
+        - Where sources disagree, report the disagreement rather than
+          papering over it.
+        - Put the URL (or DOI) inline next to each claim it supports.
+
+      Return organized findings in plain text. Do not include
+      meta-commentary about the process.
+    prompt: |
+      Research question: {{question}}
+
+      Local context that may help:
+      {{local_context}}
+
+      {{research_feedback}}
+    tools:
+      - web_search_loki
+      - fetch_url_via_curl
+      - search_arxiv
+      - mcp:ddg-search
+    max_iterations: 10
+    max_attempts: 2
+    temperature: 0.1
+
+  combine_findings:
+    id: combine_findings
+    type: script
+    script: scripts/combine_findings.py
+    next: vet_sources
+
+  vet_sources:
+    id: vet_sources
+    type: llm
+    instructions: |
+      You assess the credibility of the sources cited in a set of
+      research findings. For every distinct source URL in the findings,
+      call the `classify_source` tool to get its credibility tier. Then
+      summarize: which claims rest on HIGH-credibility sources, and
+      which rest on PREPRINT or UNVERIFIED sources and so need
+      corroboration. Do NOT do any new research -- assess only what is
+      already cited.
+    prompt: |
+      Findings to assess:
+      {{findings}}
+    tools:
+      - classify_source
+    max_iterations: 15
+    state_updates:
+      source_assessment: "{{output}}"
+    next: critique
+
+  critique:
+    id: critique
+    type: llm
+    instructions: |
+      You are a meticulous research reviewer. Judge whether the
+      findings below are good enough to synthesize a complete,
+      well-supported report that answers the research plan.
+
+      Mark the findings REVISE if ANY of these hold:
+        - A research-plan question is unanswered or only weakly
+          addressed.
+        - A factual claim has no source, or cites a source that looks
+          fabricated.
+        - The findings lean on a single source where corroboration is
+          needed.
+        - A key claim rests only on a PREPRINT or UNVERIFIED source,
+          per the source credibility assessment below.
+        - An obvious counter-perspective or recent development is
+          missing.
+      Otherwise mark them PASS.
+
+      Respond in EXACTLY this format, nothing else:
+
+      VERDICT: <PASS or REVISE>
+      FEEDBACK: <if REVISE, be specific and actionable -- name the gaps
+      and what kind of source would close them; if PASS, write "none">
+    prompt: |
+      Research plan:
+      {{research_plan}}
+
+      Findings under review:
+      {{findings}}
+
+      Source credibility assessment:
+      {{source_assessment}}
+    tools: []
+    state_updates:
+      critique: "{{output}}"
+    next: reflexion_gate
+
+  reflexion_gate:
+    id: reflexion_gate
+    type: script
+    script: scripts/reflexion_gate.py
+    next: synthesize
+
+  synthesize:
+    id: synthesize
+    type: agent
+    agent: report-writer
+    prompt: |
+      Research topic: {{topic}}
+
+      Findings (organized by sub-question, with inline citations):
+      {{findings}}
+
+      Source credibility assessment:
+      {{source_assessment}}
+
+      Produce the final report following your instructions.
+    timeout: 300
+    state_updates:
+      report: "{{output}}"
+    next: verify_sources
+
+  verify_sources:
+    id: verify_sources
+    type: script
+    script: scripts/verify_sources.py
+    next: approve
+
+  approve:
+    id: approve
+    type: approval
+    question: |
+      Research report on: {{topic}}
+
+      {{report}}
+
+      ----
+      {{source_check}}
+      ----
+
+      Accept this report? Pick "accept" or "reject", or type specific
+      feedback to send the research back for another pass.
+    options:
+      - "accept"
+      - "reject"
+    routes:
+      "accept": end_accepted
+      "reject": end_rejected
+    on_other: incorporate_feedback
+    state_updates:
+      decision: "{{choice}}"
+
+  incorporate_feedback:
+    id: incorporate_feedback
+    type: script
+    script: scripts/incorporate_feedback.py
+
+  end_accepted:
+    id: end_accepted
+    type: end
+    output: "{{report}}"
+
+  end_rejected:
+    id: end_rejected
+    type: end
+    output: "Research on '{{topic}}' was rejected and discarded."
diff --git a/assets/agents/deep-research/knowledge/README.md b/assets/agents/deep-research/knowledge/README.md
new file mode 100644
index 0000000..52b578b
--- /dev/null
+++ b/assets/agents/deep-research/knowledge/README.md
@@ -0,0 +1,23 @@
+# Local knowledge corpus for deep-research
+
+The `knowledge_lookup` node in `graph.yaml` is a `rag` node that runs
+hybrid (vector + keyword) retrieval over every file in this directory.
+Drop your own notes, papers (PDFs), Markdown docs, or text files here
+and they will be indexed into a per-agent knowledge base on first run.
+
+Loki supports common file types out of the box: `.md`, `.txt`, `.pdf`,
+`.html`, and others. Subdirectories are walked recursively.
+
+A small starter file (`research-style-notes.md`) ships so the RAG
+node has something non-empty to retrieve against on a clean install.
+Replace or extend it with your own materials to bias the research
+phase toward your local context.
+
+To force the knowledge base to rebuild after you add or change files,
+delete the cached index:
+
+```sh
+rm ~/.config/loki/agents/deep-research/knowledge_lookup.yaml
+```
+
+The next run will rebuild from the current contents of this directory.
diff --git a/assets/agents/deep-research/knowledge/research-style-notes.md b/assets/agents/deep-research/knowledge/research-style-notes.md
new file mode 100644
index 0000000..a64848d
--- /dev/null
+++ b/assets/agents/deep-research/knowledge/research-style-notes.md
@@ -0,0 +1,49 @@
+# Research style notes
+
+These are general principles the `deep-research` agent should keep in
+mind regardless of topic. Replace this file with your own notes if you
+want to bias retrieval toward your local context.
+
+## What "good research" means here
+
+- **Every factual claim cites a source you actually retrieved.** Never
+  fabricate URLs, page titles, authors, or DOIs.
+- **Primary sources beat aggregators.** Prefer the original paper, the
+  RFC, the standards body, or the manufacturer over a blog summarizing
+  them.
+- **Corroboration matters where stakes are high.** If a single source
+  makes a strong claim, look for a second independent source before
+  taking it as established.
+- **Disagreement is information, not noise.** If two credible sources
+  disagree, report the disagreement and the reasoning on each side.
+- **Old does not mean wrong.** A 2014 RFC is still authoritative if no
+  newer one has obsoleted it; check before assuming a source is stale.
+
+## Source-tier heuristics
+
+The `vet_sources` node uses these rough tiers to weigh credibility.
+The custom tool `classify_source` (see `tools.sh`) implements this
+deterministically by hostname / TLD.
+
+- **HIGH:** government domains (`.gov`, `.mil`), academic institutions
+  (`.edu`, university subdomains), peer-reviewed journals, standards
+  bodies (IETF/RFCs, W3C, ISO, IEEE, NIST), and primary documents from
+  the entities being researched (e.g. a vendor's official spec page).
+- **PREPRINT:** arXiv, bioRxiv, medRxiv, SSRN. Useful but not yet
+  peer-reviewed; treat numeric claims with extra caution.
+- **ORGANIZATION:** established nonprofits, standards-adjacent groups,
+  industry consortia. Reliable for their stated mission but may have a
+  perspective.
+- **UNVERIFIED:** general web pages, blogs, news aggregators, social
+  media. Useful for leads but should not be the only source for a
+  factual claim.
+
+## Common pitfalls to flag in critique
+
+- A claim cited only to a PREPRINT or UNVERIFIED source on a numeric
+  or contested point.
+- A research-plan question that the findings address only obliquely.
+- "Findings" that paraphrase a single source three times rather than
+  triangulating.
+- Citation collisions where two sources are listed but turn out to
+  be the same study reported via different aggregators.
diff --git a/assets/agents/deep-research/scripts/bootstrap_research.py b/assets/agents/deep-research/scripts/bootstrap_research.py
new file mode 100644
index 0000000..d230afc
--- /dev/null
+++ b/assets/agents/deep-research/scripts/bootstrap_research.py
@@ -0,0 +1,18 @@
+#!/usr/bin/env python3
+"""Fan-out source for context loading.
+
+Has no logic of its own. Exists so the static `next: [plan, knowledge_lookup]`
+list on this node fans out into two parallel branches (the LLM planner and
+the RAG knowledge lookup) as a single super-step. The validator requires
+declared parallel-branch script outputs, so we emit an empty JSON object
+explicitly here.
+"""
+import json
+
+
+def main():
+    print(json.dumps({}))
+
+
+if __name__ == "__main__":
+    main()
diff --git a/assets/agents/deep-research/scripts/combine_findings.py b/assets/agents/deep-research/scripts/combine_findings.py
new file mode 100644
index 0000000..b55d7aa
--- /dev/null
+++ b/assets/agents/deep-research/scripts/combine_findings.py
@@ -0,0 +1,39 @@
+#!/usr/bin/env python3
+"""Join the per-question map outputs into a single `findings` string.
+
+The `research_each_question` map writes `question_findings` (an array,
+one entry per sub-question, in input order). Downstream nodes
+(`vet_sources`, `critique`, `synthesize`) read `{{findings}}` as a
+single block, so this script renders the array as a Markdown document
+with one section per question.
+"""
+import json
+import os
+
+
+def load_state():
+    path = os.environ.get("GRAPH_STATE_FILE")
+    if path:
+        with open(path) as f:
+            return json.load(f)
+    return json.loads(os.environ.get("GRAPH_STATE", "{}"))
+
+
+def main():
+    state = load_state()
+    questions = state.get("questions") or []
+    per_question = state.get("question_findings") or []
+
+    sections = []
+    for idx, q in enumerate(questions):
+        body = per_question[idx] if idx < len(per_question) else ""
+        if isinstance(body, dict) or isinstance(body, list):
+            body = json.dumps(body, indent=2)
+        sections.append(f"## {q}\n\n{body}")
+
+    findings = "\n\n".join(sections) if sections else "No findings gathered."
+    print(json.dumps({"findings": findings}))
+
+
+if __name__ == "__main__":
+    main()
diff --git a/assets/agents/deep-research/scripts/incorporate_feedback.py b/assets/agents/deep-research/scripts/incorporate_feedback.py
new file mode 100644
index 0000000..27c22f2
--- /dev/null
+++ b/assets/agents/deep-research/scripts/incorporate_feedback.py
@@ -0,0 +1,41 @@
+#!/usr/bin/env python3
+"""Fold a reviewer's free-form feedback back into the research loop.
+
+Runs when the user answers the approval step with their own text
+instead of "accept" or "reject". That text (saved by the approval node
+as `decision`) becomes `research_feedback`, and the graph loops back to
+`research_each_question` for another informed pass (each sub-question is
+re-researched in parallel with the new feedback in context). The
+reflexion counter is reset so the user-driven pass gets a fresh revision
+budget.
+
+Routing (`_next`): always research_each_question.
+"""
+import json
+import os
+
+
+def load_state():
+    path = os.environ.get("GRAPH_STATE_FILE")
+    if path:
+        with open(path) as f:
+            return json.load(f)
+    return json.loads(os.environ.get("GRAPH_STATE", "{}"))
+
+
+def main():
+    state = load_state()
+    feedback = (state.get("decision") or "").strip()
+    output = {
+        "_next": "research_each_question",
+        "research_attempts": 0,
+        "research_feedback": (
+            "The user reviewed the report and asked for changes. Treat "
+            "this as the top priority for the next pass:\n\n" + feedback
+        ),
+    }
+    print(json.dumps(output))
+
+
+if __name__ == "__main__":
+    main()
diff --git a/assets/agents/deep-research/scripts/parse_request.py b/assets/agents/deep-research/scripts/parse_request.py
new file mode 100644
index 0000000..faae28c
--- /dev/null
+++ b/assets/agents/deep-research/scripts/parse_request.py
@@ -0,0 +1,35 @@
+#!/usr/bin/env python3
+"""Entry router for deep-research.
+
+Reads the caller's prompt from state. If it contains a usable research
+topic, stores it as `topic` and falls through to the static `next`
+(plan). If the prompt is empty, routes to `ask_topic` so the user can
+supply one interactively.
+
+Routing (`_next`):
+  - prompt present -> (no _next; static next: plan)
+  - prompt empty   -> ask_topic
+"""
+import json
+import os
+
+
+def load_state():
+    path = os.environ.get("GRAPH_STATE_FILE")
+    if path:
+        with open(path) as f:
+            return json.load(f)
+    return json.loads(os.environ.get("GRAPH_STATE", "{}"))
+
+
+def main():
+    state = load_state()
+    prompt = (state.get("initial_prompt") or "").strip()
+    if prompt:
+        print(json.dumps({"topic": prompt}))
+    else:
+        print(json.dumps({"_next": "ask_topic"}))
+
+
+if __name__ == "__main__":
+    main()
diff --git a/assets/agents/deep-research/scripts/reflexion_gate.py b/assets/agents/deep-research/scripts/reflexion_gate.py
new file mode 100644
index 0000000..2dd1e6b
--- /dev/null
+++ b/assets/agents/deep-research/scripts/reflexion_gate.py
@@ -0,0 +1,76 @@
+#!/usr/bin/env python3
+"""Reflexion gate for deep-research.
+
+Runs after `critique` has reviewed the current research findings. If the
+critique's verdict is REVISE and the reflexion budget is not spent,
+loops back to `research` with the critique attached as
+`research_feedback`, so the retry is informed rather than a blind
+re-run. Otherwise it proceeds to `synthesize`.
+
+Routing (`_next`):
+  - verdict PASS                     -> synthesize
+  - verdict REVISE, budget remaining -> research_each_question  (+ research_feedback)
+  - verdict REVISE, budget spent     -> synthesize
+
+Reflexion is a best-effort quality booster, not a hard gate: once the
+budget is spent the workflow proceeds anyway, and the human approval
+step is the final backstop.
+"""
+import json
+import os
+import re
+
+# Automated revision passes allowed. `research` runs at most
+# MAX_REFLEXION_REVISIONS + 1 times per user pass. Bump to allow more.
+MAX_REFLEXION_REVISIONS = 2
+
+
+def load_state():
+    path = os.environ.get("GRAPH_STATE_FILE")
+    if path:
+        with open(path) as f:
+            return json.load(f)
+    return json.loads(os.environ.get("GRAPH_STATE", "{}"))
+
+
+def as_int(value, default=0):
+    try:
+        return int(value)
+    except (TypeError, ValueError):
+        return default
+
+
+def parse_verdict(critique):
+    """Pull PASS/REVISE from the critique's `VERDICT:` line. Defaults to
+    PASS when no verdict line is found, so a malformed critique lets the
+    workflow proceed instead of burning the whole revision budget."""
+    match = re.search(r"VERDICT:\s*([A-Za-z]+)", critique, re.IGNORECASE)
+    if not match:
+        return "PASS"
+    return match.group(1).upper()
+
+
+def main():
+    state = load_state()
+    critique = state.get("critique") or ""
+    verdict = parse_verdict(critique)
+    attempts = as_int(state.get("research_attempts"))
+
+    if verdict == "REVISE" and attempts < MAX_REFLEXION_REVISIONS:
+        feedback = (
+            "A reviewer judged the previous research pass incomplete. "
+            "Address every point in the critique below:\n\n" + critique
+        )
+        output = {
+            "_next": "research_each_question",
+            "research_attempts": attempts + 1,
+            "research_feedback": feedback,
+        }
+    else:
+        output = {"_next": "synthesize"}
+
+    print(json.dumps(output))
+
+
+if __name__ == "__main__":
+    main()
diff --git a/assets/agents/deep-research/scripts/verify_sources.py b/assets/agents/deep-research/scripts/verify_sources.py
new file mode 100644
index 0000000..9828341
--- /dev/null
+++ b/assets/agents/deep-research/scripts/verify_sources.py
@@ -0,0 +1,69 @@
+#!/usr/bin/env python3
+"""Check that the sources cited in the research report are reachable.
+
+Scans the final report for URLs and DOIs, probes each with a HEAD
+request, and writes a `source_check` summary into state so the human
+reviewer sees broken citations at the approval step.
+
+Times out per request so a slow source cannot stall the graph.
+"""
+import json
+import os
+import re
+import urllib.error
+import urllib.request
+
+DOI_RE = re.compile(r"\b(10\.\d{4,9}/[-._;()/:A-Z0-9]+)", re.IGNORECASE)
+URL_RE = re.compile(r"https?://[^\s)\]\}\"'>]+")
+
+
+def load_state():
+    path = os.environ.get("GRAPH_STATE_FILE")
+    if path:
+        with open(path) as f:
+            return json.load(f)
+    return json.loads(os.environ.get("GRAPH_STATE", "{}"))
+
+
+def reachable(url, timeout=5.0):
+    req = urllib.request.Request(url, method="HEAD")
+    try:
+        with urllib.request.urlopen(req, timeout=timeout) as resp:
+            return 200 <= resp.status < 400
+    except urllib.error.HTTPError as e:
+        return 200 <= e.code < 400
+    except Exception:
+        return False
+
+
+def main():
+    state = load_state()
+    report = state.get("report") or ""
+
+    urls = sorted({u.rstrip(".,;)") for u in URL_RE.findall(report)})
+    dois = sorted(set(DOI_RE.findall(report)))
+
+    results = []
+    for url in urls:
+        ok = reachable(url)
+        results.append(f"  {'OK' if ok else 'UNREACHABLE'}  {url}")
+    for doi in dois:
+        url = f"https://doi.org/{doi}"
+        if url in urls:
+            continue
+        ok = reachable(url)
+        results.append(f"  {'OK' if ok else 'UNREACHABLE'}  DOI {doi} ({url})")
+
+    if not results:
+        summary = "No web sources were cited in the report."
+    else:
+        summary = (
+            f"Source reachability ({len(results)} checked):\n"
+            + "\n".join(results)
+        )
+
+    print(json.dumps({"source_check": summary}))
+
+
+if __name__ == "__main__":
+    main()
diff --git a/assets/agents/deep-research/tools.sh b/assets/agents/deep-research/tools.sh
new file mode 100644
index 0000000..b715364
--- /dev/null
+++ b/assets/agents/deep-research/tools.sh
@@ -0,0 +1,39 @@
+#!/usr/bin/env bash
+
+set -e
+
+# @env LLM_OUTPUT=/dev/stdout The output path
+
+# @cmd Classify the credibility tier of a web source from its URL.
+# A deterministic check based on the host and top-level domain. Use it
+# to weigh how much trust to place in a source before relying on it.
+# @option --url!  The full source URL to classify
+classify_source() {
+    # shellcheck disable=SC2154
+    local url="$argc_url"
+    local host="${url#*://}"
+    host="${host%%/*}"
+    host="${host##*@}"
+    host="${host%%:*}"
+    host="$(printf '%s' "$host" | tr '[:upper:]' '[:lower:]')"
+
+    local tier
+    case "$host" in
+        '')
+            tier="UNKNOWN - no host could be parsed from the URL" ;;
+        *.gov | *.gov.* | *.mil)
+            tier="HIGH - government source" ;;
+        *.edu | *.edu.* | *.ac.*)
+            tier="HIGH - academic institution" ;;
+        arxiv.org | *.arxiv.org | biorxiv.org | *.biorxiv.org | medrxiv.org | *.medrxiv.org | ssrn.com | *.ssrn.com)
+            tier="PREPRINT - not yet peer reviewed, corroborate before citing" ;;
+        wikipedia.org | *.wikipedia.org)
+            tier="TERTIARY - encyclopedia, good for orientation not citation" ;;
+        *.org | *.org.*)
+            tier="MEDIUM - organization site, check for institutional bias" ;;
+        *)
+            tier="UNVERIFIED - general web source, corroborate before citing" ;;
+    esac
+
+    printf '%s: %s\n' "${host:-<none>}" "$tier" >> "$LLM_OUTPUT"
+}
diff --git a/assets/agents/jira-helper/README.md b/assets/agents/jira-helper/README.md
deleted file mode 100644
index 2db1697..0000000
--- a/assets/agents/jira-helper/README.md
+++ /dev/null
@@ -1,14 +0,0 @@
-# Jira AI Agent
-
-## Overview
-
-The Jira AI Agent is designed to assist with managing tasks within Jira projects, providing capabilities such as 
-creating, searching, updating, assigning, linking, and commenting on issues. Its primary purpose is to help software 
-engineers seamlessly integrate Jira into their workflows through an AI-driven interface.
-
-## Configuration
-This agent uses the official [Atlassian MCP Server](https://github.com/atlassian/atlassian-mcp-server). To use it, 
-ensure you have Node.js v18+ installed to run the local MCP proxy (`mcp-remote`).
-
-The server uses OAuth 2.0 so it will automatically open your browser for you to sign in to your account. No manual 
-configuration is necessary!
diff --git a/assets/agents/jira-helper/config.yaml b/assets/agents/jira-helper/config.yaml
deleted file mode 100644
index 3e50717..0000000
--- a/assets/agents/jira-helper/config.yaml
+++ /dev/null
@@ -1,37 +0,0 @@
-name: Jira Agent
-description: An AI agent that can assist with Jira tasks such as creating issues, searching for issues, and updating issues.
-version: 0.1.0
-agent_session: temp
-mcp_servers:
-  - atlassian
-instructions: |
-  You are a AI agent designed to assist with managing Jira tasks and helping software engineers utilize and integrate 
-  Jira into their workflows. You can create, search, update, assign, link, and comment on issues in Jira.
-  
-  ## Create Issue (MANDATORY when creating a issue)
-  When a user prompts you to create a Jira issue:
-  1. Prompt the user for what Jira project they want the ticket created in
-  2. If the ticket type requires a parent issue:
-    a. Query Jira for potentially relevant parents
-    b. Prompt user for which parent to use, displaying the suggested list of parent issues
-  3. Create the issue with the following format:
-     ```markdown
-      **Description:**
-        This section gives context and details about the issue.
-      **User Acceptance Criteria:**
-        # This section provides bullet points that function like a checklist of all the things that must be completed in 
-        # order for the issue to be considered done.
-        * Example criteria one
-        * Example criteria two
-     ```
-  4. Ask the user if the issue should be assigned to them
-    a. If yes, then assign the user to the newly created issue
-
-
-  Available tools:
-  {{__tools__}}
-conversation_starters:
-  - What are the latest issues in my Jira project?
-  - Can you create a new Jira issue for me?
-  - What are my open Jira issues?
-  - Can you search for issues with the label "bug" in my Jira project?
diff --git a/assets/agents/report-writer/README.md b/assets/agents/report-writer/README.md
new file mode 100644
index 0000000..0adf134
--- /dev/null
+++ b/assets/agents/report-writer/README.md
@@ -0,0 +1,46 @@
+# report-writer
+
+A tiny, focused sub-agent that turns a set of research findings into a
+single coherent final report. Reads only what it is given — does not
+do independent research, does not access the web, does not invent
+facts. It exists as a focused tool for orchestrating agents to
+delegate the writing phase to.
+
+## Why a separate agent?
+
+This is an example of the **agent-as-tool** pattern in graph agents.
+The `deep-research` graph agent's `synthesize` node is an `agent` node
+that spawns this one (see `assets/agents/deep-research/graph.yaml`).
+Separating the role has two practical benefits:
+
+- The orchestrating agent can use a cheap model (or a high-temperature
+  exploratory one) for the research phase, while letting the writing
+  phase use a different (typically lower-temperature, possibly larger)
+  model dedicated to coherent prose.
+- The writing prompt is owned by this agent's `config.yaml` rather
+  than buried inside another agent's graph. You can polish it
+  independently without touching the research flow.
+
+## Standalone use
+
+You can also use this agent directly if you have a set of findings you
+want polished:
+
+```sh
+loki -a report-writer "Topic: X. Findings: <paste findings here>"
+```
+
+It will produce a single Markdown report following the rules in its
+system prompt: executive summary at the top, grouped sections by
+related sub-questions, every inline citation preserved verbatim, and a
+final "Open questions / disagreements" section.
+
+## What it will NOT do
+
+- Search the web, fetch URLs, query an MCP server, or use any tool.
+  It has no tools configured.
+- Invent facts beyond what is in the findings you give it.
+- Strip or rewrite citations.
+
+These constraints are the point of the agent existing: a writer that
+the orchestrator can trust to stay in its lane.
diff --git a/assets/agents/report-writer/config.yaml b/assets/agents/report-writer/config.yaml
new file mode 100644
index 0000000..2940c7d
--- /dev/null
+++ b/assets/agents/report-writer/config.yaml
@@ -0,0 +1,34 @@
+name: report-writer
+description: Polishes research findings into a clear, citation-preserving final report
+version: 1.0.0
+temperature: 0.2
+
+instructions: |
+  You are a technical writer. You will be given:
+    - a research topic
+    - a set of findings, organized per sub-question, with inline
+      citations next to each claim
+    - a source-credibility assessment of the cited sources
+
+  Your job is to produce a single, well-organized final report:
+
+  Rules:
+    - Use ONLY the findings provided. Do not introduce facts from
+      your own memory. Do not speculate beyond what the findings
+      support.
+    - Preserve every inline citation. If a sentence in the findings
+      had a URL or DOI, the equivalent sentence in your report must
+      keep the same citation.
+    - Lead with a 2-3 sentence executive summary at the top.
+    - Organize the body so that related sub-questions are grouped,
+      not strictly one section per question. The findings are raw
+      material; the report should read as a single coherent answer
+      to the original topic.
+    - End with a short "Open questions / disagreements" section
+      naming anything the findings flagged as unresolved or
+      contested.
+
+  Output plain Markdown. No metadata, no JSON wrapper.
+
+conversation_starters:
+  - "Polish these findings into a cited report"
diff --git a/assets/agents/sisyphus/README.md b/assets/agents/sisyphus/README.md
index e59369e..e2a3381 100644
--- a/assets/agents/sisyphus/README.md
+++ b/assets/agents/sisyphus/README.md
@@ -18,16 +18,15 @@ Sisyphus acts as the primary entry point, capable of handling complex tasks by c
 - 🛠️ **Tool Integration**: Seamlessly uses system tools for building, testing, and file manipulation.
 
 ## Pro-Tip: Use an IDE MCP Server for Improved Performance
-Many modern IDEs now include MCP servers that let LLMs perform operations within the IDE itself and use IDE tools. Using
-an IDE's MCP server dramatically improves the performance of coding agents. So if you have an IDE, try adding that MCP
-server to your config (see the [MCP Server docs](../../../docs/function-calling/MCP-SERVERS.md) to see how to configure
-them), and modify the agent definition to look like this:
+Many modern IDEs (JetBrains, VS Code, Cursor, Zed, etc.) expose MCP servers that let LLMs use IDE tools directly. Using
+one dramatically improves the performance of coding agents. If you have one, add it to your loki config (see the
+[MCP Server docs](../../../docs/function-calling/MCP-SERVERS.md)) and reference it in this agent's `mcp_servers:` list:
 
 ```yaml
 # ...
 
 mcp_servers:
-  - jetbrains
+  - your-ide-mcp-server
 
 global_tools:
   - fs_read.sh
diff --git a/assets/agents/sisyphus/config.yaml b/assets/agents/sisyphus/config.yaml
index a6cb81a..8bb3821 100644
--- a/assets/agents/sisyphus/config.yaml
+++ b/assets/agents/sisyphus/config.yaml
@@ -119,20 +119,21 @@ instructions: |
   1. todo__init --goal "Add user profiles API endpoint"
   2. todo__add --task "Explore existing API patterns"
   3. todo__add --task "Implement profile endpoint"
-  4. todo__add --task "Verify with build/test"
-  5. agent__spawn --agent explore --prompt "Find existing API endpoint patterns, route structures, and controller conventions. Include code snippets."
-  6. agent__spawn --agent explore --prompt "Find existing data models and database query patterns. Include code snippets."
-  7. agent__collect --id <id1>
-  8. agent__collect --id <id2>
-  9. todo__done --id 1
-  10. agent__spawn --agent coder --prompt "<structured prompt using Coder Delegation Format above, including code snippets from explore results>"
-  11. agent__collect --id <coder_id>
-  12. todo__done --id 2
-  13. run_build
-  14. run_tests
-  15. todo__done --id 3
+  4. agent__spawn --agent explore --prompt "Find existing API endpoint patterns, route structures, and controller conventions. Include code snippets."
+  5. agent__spawn --agent explore --prompt "Find existing data models and database query patterns. Include code snippets."
+  6. agent__collect --id <id1>
+  7. agent__collect --id <id2>
+  8. todo__done --id 1
+  9. agent__spawn --agent coder --prompt "<structured prompt using Coder Delegation Format above, including code snippets from explore results>"
+  10. agent__collect --id <coder_id>
+  11. todo__done --id 2
   ```
 
+  Note: the `coder` agent is a graph agent that runs verification (build +
+  tests) and a bounded fix-loop internally. You do NOT need to spawn a
+  separate build/test step. A `CODER_COMPLETE` outcome means build and
+  tests already passed.
+
   ### Example 2: Architecture/design question (explore + oracle in parallel)
 
   User: "How should I structure the authentication for this app?"
@@ -172,6 +173,22 @@ instructions: |
   10. **Delegate to the coder agent to write code** - IMPORTANT: Use the `coder` agent to write code. Do not try to write code yourself except for trivial changes
   11. **Always output a summary of changes when finished** - Make it clear to user's that you've completed your tasks
 
+  ## Coder Outcomes
+
+  The `coder` agent is a graph agent that runs the implement -> verify_build
+  -> verify_tests -> fix_loop pipeline internally. It always returns one of
+  three sentinel outcomes:
+
+  - `CODER_COMPLETE` - implementation succeeded with build + tests green.
+    Continue with any follow-up todos.
+  - `CODER_REJECTED` - user rejected the plan at the approval gate (only
+    triggered for high-complexity plans). Do NOT re-spawn coder blindly;
+    ask the user what to change first.
+  - `CODER_FAILED` - the fix-loop exhausted its budget without producing
+    green build/tests. The failure output includes the last build and tests
+    output. Surface this to the user; consider spawning `oracle` for
+    diagnosis if the failure is unclear.
+
   ## When to Do It Yourself
 
   - Simple command execution
diff --git a/assets/functions/mcp.json b/assets/functions/mcp.json
index d3794f6..0ae8f79 100644
--- a/assets/functions/mcp.json
+++ b/assets/functions/mcp.json
@@ -1,6 +1,7 @@
 {
   "mcpServers": {
     "github": {
+      "type": "stdio",
       "command": "docker",
       "args": [
         "run",
@@ -15,14 +16,17 @@
       }
     },
     "atlassian": {
+      "type": "stdio",
       "command": "npx",
       "args": ["-y", "mcp-remote@0.1.13", "https://mcp.atlassian.com/v1/mcp"]
     },
     "docker": {
+      "type": "stdio",
       "command": "uvx",
       "args": ["mcp-server-docker"]
     },
     "ddg-search": {
+      "type": "stdio",
       "command": "uvx",
       "args": ["duckduckgo-mcp-server"]
     }
diff --git a/assets/functions/scripts/run-agent.py b/assets/functions/scripts/run-agent.py
index 6125c5a..e22368b 100755
--- a/assets/functions/scripts/run-agent.py
+++ b/assets/functions/scripts/run-agent.py
@@ -50,7 +50,13 @@ def parse_raw_data(data):
 
 def parse_argv():
     agent_func = sys.argv[1]
-    agent_data = sys.argv[2]
+
+    tool_data_file = os.environ.get("LLM_TOOL_DATA_FILE")
+    if tool_data_file and os.path.isfile(tool_data_file):
+        with open(tool_data_file, "r", encoding="utf-8") as f:
+            agent_data = f.read()
+    else:
+        agent_data = sys.argv[2]
 
     if (not agent_data) or (not agent_func):
         print("Usage: ./{agent_name}.py <agent-func> <agent-data>", file=sys.stderr)
diff --git a/assets/functions/scripts/run-agent.sh b/assets/functions/scripts/run-agent.sh
index 5dd5179..ee1af7e 100644
--- a/assets/functions/scripts/run-agent.sh
+++ b/assets/functions/scripts/run-agent.sh
@@ -14,7 +14,11 @@ main() {
 
 parse_argv() {
 		agent_func="$1"
-		agent_data="$2"
+    if [[ -n "$LLM_TOOL_DATA_FILE" ]] && [[ -f "$LLM_TOOL_DATA_FILE" ]]; then
+      	agent_data="$(cat "$LLM_TOOL_DATA_FILE")"
+    else
+				agent_data="$2"
+    fi
     if [[ -z "$agent_data" ]] || [[ -z "$agent_func" ]]; then
         die "usage: ./{agent_name}.sh <agent-func> <agent-data>"
     fi
@@ -57,7 +61,6 @@ run() {
     if [[ "$OS" == "Windows_NT" ]]; then
         set -o igncr
         tools_path="$(cygpath -w "$tools_path")"
-        tool_data="$(echo "$tool_data" | sed 's/\\/\\\\/g')"
     fi
 
     jq_script="$(cat <<-'EOF'
@@ -70,11 +73,11 @@ def to_args:
     to_entries | .[] |
     (.key | split("_") | join("-")) as $key |
     if .value | type == "array" then
-        .value | .[] | "--\($key) \(. | escape_shell_word)"
+        .value | .[] | "--\($key)=\(. | escape_shell_word)"
     elif .value | type == "boolean" then
         if .value then "--\($key)" else "" end
     else
-        "--\($key) \(.value | escape_shell_word)"
+        "--\($key)=\(.value | escape_shell_word)"
     end;
 [ to_args ] | join(" ")
 EOF
diff --git a/assets/functions/scripts/run-agent.ts b/assets/functions/scripts/run-agent.ts
new file mode 100644
index 0000000..a8e02a3
--- /dev/null
+++ b/assets/functions/scripts/run-agent.ts
@@ -0,0 +1,189 @@
+#!/usr/bin/env tsx
+
+// Usage: ./{agent_name}.ts <agent-func> <agent-data>
+
+import { readFileSync, writeFileSync, existsSync } from "fs";
+import { join } from "path";
+import { pathToFileURL } from "url";
+
+async function main(): Promise<void> {
+  const { agentFunc, rawData } = parseArgv();
+  const agentData = parseRawData(rawData);
+
+  const configDir = "{config_dir}";
+  setupEnv(configDir, agentFunc);
+
+  const agentToolsPath = join(configDir, "agents", "{agent_name}", "tools.ts");
+  await run(agentToolsPath, agentFunc, agentData);
+}
+
+function parseRawData(data: string): Record<string, unknown> {
+  if (!data) {
+    throw new Error("No JSON data");
+  }
+
+  try {
+    return JSON.parse(data);
+  } catch {
+    throw new Error("Invalid JSON data");
+  }
+}
+
+function parseArgv(): { agentFunc: string; rawData: string } {
+  const agentFunc = process.argv[2];
+
+  const toolDataFile = process.env["LLM_TOOL_DATA_FILE"];
+  let agentData: string;
+  if (toolDataFile && existsSync(toolDataFile)) {
+    agentData = readFileSync(toolDataFile, "utf-8");
+  } else {
+    agentData = process.argv[3];
+  }
+
+  if (!agentFunc || !agentData) {
+    process.stderr.write("Usage: ./{agent_name}.ts <agent-func> <agent-data>\n");
+    process.exit(1);
+  }
+
+  return { agentFunc, rawData: agentData };
+}
+
+function setupEnv(configDir: string, agentFunc: string): void {
+  loadEnv(join(configDir, ".env"));
+  process.env["LLM_ROOT_DIR"] = configDir;
+  process.env["LLM_AGENT_NAME"] = "{agent_name}";
+  process.env["LLM_AGENT_FUNC"] = agentFunc;
+  process.env["LLM_AGENT_ROOT_DIR"] = join(configDir, "agents", "{agent_name}");
+  process.env["LLM_AGENT_CACHE_DIR"] = join(configDir, "cache", "{agent_name}");
+}
+
+function loadEnv(filePath: string): void {
+  let lines: string[];
+  try {
+    lines = readFileSync(filePath, "utf-8").split("\n");
+  } catch {
+    return;
+  }
+
+  for (const raw of lines) {
+    const line = raw.trim();
+    if (line.startsWith("#") || !line) {
+      continue;
+    }
+
+    const eqIdx = line.indexOf("=");
+    if (eqIdx === -1) {
+      continue;
+    }
+
+    const key = line.slice(0, eqIdx).trim();
+    if (key in process.env) {
+      continue;
+    }
+
+    let value = line.slice(eqIdx + 1).trim();
+    if (
+      (value.startsWith('"') && value.endsWith('"')) ||
+      (value.startsWith("'") && value.endsWith("'"))
+    ) {
+      value = value.slice(1, -1);
+    }
+    process.env[key] = value;
+  }
+}
+
+function extractParamNames(fn: Function): string[] {
+  const src = fn.toString();
+  const match = src.match(/^(?:async\s+)?function\s*\w*\s*\(([^)]*)\)/);
+  if (!match) {
+    return [];
+  }
+  return match[1]
+    .split(",")
+    .map((p) => p.trim().replace(/[:=?].*/s, "").trim())
+    .filter(Boolean);
+}
+
+function spreadArgs(
+  fn: Function,
+  data: Record<string, unknown>,
+): unknown[] {
+  const names = extractParamNames(fn);
+  if (names.length === 0) {
+    return [];
+  }
+  return names.map((name) => data[name]);
+}
+
+async function run(
+  agentPath: string,
+  agentFunc: string,
+  agentData: Record<string, unknown>,
+): Promise<void> {
+  const mod = await import(pathToFileURL(agentPath).href);
+
+  if (typeof mod[agentFunc] !== "function") {
+    throw new Error(`No module function '${agentFunc}' at '${agentPath}'`);
+  }
+
+  const fn = mod[agentFunc] as Function;
+  const args = spreadArgs(fn, agentData);
+  const value = await fn(...args);
+  returnToLlm(value);
+  dumpResult(`{agent_name}:${agentFunc}`);
+}
+
+function returnToLlm(value: unknown): void {
+  if (value === null || value === undefined) {
+    return;
+  }
+
+  const output = process.env["LLM_OUTPUT"];
+  const write = (s: string) => {
+    if (output) {
+      writeFileSync(output, s, "utf-8");
+    } else {
+      process.stdout.write(s);
+    }
+  };
+
+  if (typeof value === "string" || typeof value === "number" || typeof value === "boolean") {
+    write(String(value));
+  } else if (typeof value === "object") {
+    write(JSON.stringify(value, null, 2));
+  }
+}
+
+function dumpResult(name: string): void {
+  const dumpResults = process.env["LLM_DUMP_RESULTS"];
+  const llmOutput = process.env["LLM_OUTPUT"];
+
+  if (!dumpResults || !llmOutput || !process.stdout.isTTY) {
+    return;
+  }
+
+  try {
+    const pattern = new RegExp(`\\b(${dumpResults})\\b`);
+    if (!pattern.test(name)) {
+      return;
+    }
+  } catch {
+    return;
+  }
+
+  let data: string;
+  try {
+    data = readFileSync(llmOutput, "utf-8");
+  } catch {
+    return;
+  }
+
+  process.stdout.write(
+    `\x1b[2m----------------------\n${data}\n----------------------\x1b[0m\n`,
+  );
+}
+
+main().catch((err) => {
+  process.stderr.write(`${err}\n`);
+  process.exit(1);
+});
diff --git a/assets/functions/scripts/run-tool.py b/assets/functions/scripts/run-tool.py
index d8c90b1..9ac3c07 100644
--- a/assets/functions/scripts/run-tool.py
+++ b/assets/functions/scripts/run-tool.py
@@ -49,6 +49,11 @@ def parse_raw_data(data):
 
 
 def parse_argv():
+    tool_data_file = os.environ.get("LLM_TOOL_DATA_FILE")
+    if tool_data_file and os.path.isfile(tool_data_file):
+        with open(tool_data_file, "r", encoding="utf-8") as f:
+            return f.read()
+
     argv = sys.argv[:] + [None] * max(0, 2 - len(sys.argv))
 
     tool_data = argv[1]
diff --git a/assets/functions/scripts/run-tool.sh b/assets/functions/scripts/run-tool.sh
index ead83f6..c612273 100644
--- a/assets/functions/scripts/run-tool.sh
+++ b/assets/functions/scripts/run-tool.sh
@@ -13,7 +13,11 @@ main() {
 }
 
 parse_argv() {
-		tool_data="$1"
+    if [[ -n "$LLM_TOOL_DATA_FILE" ]] && [[ -f "$LLM_TOOL_DATA_FILE" ]]; then
+        tool_data="$(cat "$LLM_TOOL_DATA_FILE")"
+    else
+				tool_data="$1"
+    fi
     if [[ -z "$tool_data" ]]; then
         die "usage: ./{function_name}.sh <tool-data>"
     fi
@@ -54,7 +58,6 @@ run() {
     if [[ "$OS" == "Windows_NT" ]]; then
         set -o igncr
         tool_path="$(cygpath -w "$tool_path")"
-        tool_data="$(echo "$tool_data" | sed 's/\\/\\\\/g')"
     fi
 
     jq_script="$(cat <<-'EOF'
@@ -67,11 +70,11 @@ def to_args:
     to_entries | .[] |
     (.key | split("_") | join("-")) as $key |
     if .value | type == "array" then
-        .value | .[] | "--\($key) \(. | escape_shell_word)"
+        .value | .[] | "--\($key)=\(. | escape_shell_word)"
     elif .value | type == "boolean" then
         if .value then "--\($key)" else "" end
     else
-        "--\($key) \(.value | escape_shell_word)"
+        "--\($key)=\(.value | escape_shell_word)"
     end;
 [ to_args ] | join(" ")
 EOF
diff --git a/assets/functions/scripts/run-tool.ts b/assets/functions/scripts/run-tool.ts
new file mode 100644
index 0000000..228166a
--- /dev/null
+++ b/assets/functions/scripts/run-tool.ts
@@ -0,0 +1,184 @@
+#!/usr/bin/env tsx
+
+// Usage: ./{function_name}.ts <tool-data>
+
+import { readFileSync, writeFileSync, existsSync } from "fs";
+import { join } from "path";
+import { pathToFileURL } from "url";
+
+async function main(): Promise<void> {
+  const rawData = parseArgv();
+  const toolData = parseRawData(rawData);
+
+  const rootDir = "{root_dir}";
+  setupEnv(rootDir);
+
+  const toolPath = "{tool_path}.ts";
+  await run(toolPath, "run", toolData);
+}
+
+function parseRawData(data: string): Record<string, unknown> {
+  if (!data) {
+    throw new Error("No JSON data");
+  }
+
+  try {
+    return JSON.parse(data);
+  } catch {
+    throw new Error("Invalid JSON data");
+  }
+}
+
+function parseArgv(): string {
+  const toolDataFile = process.env["LLM_TOOL_DATA_FILE"];
+  if (toolDataFile && existsSync(toolDataFile)) {
+    return readFileSync(toolDataFile, "utf-8");
+  }
+
+  const toolData = process.argv[2];
+
+  if (!toolData) {
+    process.stderr.write("Usage: ./{function_name}.ts <tool-data>\n");
+    process.exit(1);
+  }
+
+  return toolData;
+}
+
+function setupEnv(rootDir: string): void {
+  loadEnv(join(rootDir, ".env"));
+  process.env["LLM_ROOT_DIR"] = rootDir;
+  process.env["LLM_TOOL_NAME"] = "{function_name}";
+  process.env["LLM_TOOL_CACHE_DIR"] = join(rootDir, "cache", "{function_name}");
+}
+
+function loadEnv(filePath: string): void {
+  let lines: string[];
+  try {
+    lines = readFileSync(filePath, "utf-8").split("\n");
+  } catch {
+    return;
+  }
+
+  for (const raw of lines) {
+    const line = raw.trim();
+    if (line.startsWith("#") || !line) {
+      continue;
+    }
+
+    const eqIdx = line.indexOf("=");
+    if (eqIdx === -1) {
+      continue;
+    }
+
+    const key = line.slice(0, eqIdx).trim();
+    if (key in process.env) {
+      continue;
+    }
+
+    let value = line.slice(eqIdx + 1).trim();
+    if (
+      (value.startsWith('"') && value.endsWith('"')) ||
+      (value.startsWith("'") && value.endsWith("'"))
+    ) {
+      value = value.slice(1, -1);
+    }
+    process.env[key] = value;
+  }
+}
+
+function extractParamNames(fn: Function): string[] {
+  const src = fn.toString();
+  const match = src.match(/^(?:async\s+)?function\s*\w*\s*\(([^)]*)\)/);
+  if (!match) {
+    return [];
+  }
+  return match[1]
+    .split(",")
+    .map((p) => p.trim().replace(/[:=?].*/s, "").trim())
+    .filter(Boolean);
+}
+
+function spreadArgs(
+  fn: Function,
+  data: Record<string, unknown>,
+): unknown[] {
+  const names = extractParamNames(fn);
+  if (names.length === 0) {
+    return [];
+  }
+  return names.map((name) => data[name]);
+}
+
+async function run(
+  toolPath: string,
+  toolFunc: string,
+  toolData: Record<string, unknown>,
+): Promise<void> {
+  const mod = await import(pathToFileURL(toolPath).href);
+
+  if (typeof mod[toolFunc] !== "function") {
+    throw new Error(`No module function '${toolFunc}' at '${toolPath}'`);
+  }
+
+  const fn = mod[toolFunc] as Function;
+  const args = spreadArgs(fn, toolData);
+  const value = await fn(...args);
+  returnToLlm(value);
+  dumpResult("{function_name}");
+}
+
+function returnToLlm(value: unknown): void {
+  if (value === null || value === undefined) {
+    return;
+  }
+
+  const output = process.env["LLM_OUTPUT"];
+  const write = (s: string) => {
+    if (output) {
+      writeFileSync(output, s, "utf-8");
+    } else {
+      process.stdout.write(s);
+    }
+  };
+
+  if (typeof value === "string" || typeof value === "number" || typeof value === "boolean") {
+    write(String(value));
+  } else if (typeof value === "object") {
+    write(JSON.stringify(value, null, 2));
+  }
+}
+
+function dumpResult(name: string): void {
+  const dumpResults = process.env["LLM_DUMP_RESULTS"];
+  const llmOutput = process.env["LLM_OUTPUT"];
+
+  if (!dumpResults || !llmOutput || !process.stdout.isTTY) {
+    return;
+  }
+
+  try {
+    const pattern = new RegExp(`\\b(${dumpResults})\\b`);
+    if (!pattern.test(name)) {
+      return;
+    }
+  } catch {
+    return;
+  }
+
+  let data: string;
+  try {
+    data = readFileSync(llmOutput, "utf-8");
+  } catch {
+    return;
+  }
+
+  process.stdout.write(
+    `\x1b[2m----------------------\n${data}\n----------------------\x1b[0m\n`,
+  );
+}
+
+main().catch((err) => {
+  process.stderr.write(`${err}\n`);
+  process.exit(1);
+});
diff --git a/assets/functions/tools/demo_py.py b/assets/functions/tools/demo_py.py
index 8b0ca0a..d71cd52 100644
--- a/assets/functions/tools/demo_py.py
+++ b/assets/functions/tools/demo_py.py
@@ -1,6 +1,7 @@
 import os
 from typing import List, Literal, Optional
 
+
 def run(
     string: str,
     string_enum: Literal["foo", "bar"],
@@ -9,26 +10,38 @@ def run(
     number: float,
     array: List[str],
     string_optional: Optional[str] = None,
+    integer_with_default: int = 42,
+    boolean_with_default: bool = True,
+    number_with_default: float = 3.14,
+    string_with_default: str = "hello",
     array_optional: Optional[List[str]] = None,
 ):
-    """Demonstrates how to create a tool using Python and how to use comments.
+    """Demonstrates all supported Python parameter types and variations.
     Args:
-        string: Define a required string property
-        string_enum: Define a required string property with enum
-        boolean: Define a required boolean property
-        integer: Define a required integer property
-        number: Define a required number property
-        array: Define a required string array property
-        string_optional: Define an optional string property
-        array_optional: Define an optional string array property
+        string: A required string property
+        string_enum: A required string property constrained to specific values
+        boolean: A required boolean property
+        integer: A required integer property
+        number: A required number (float) property
+        array: A required string array property
+        string_optional: An optional string property (Optional[str] with None default)
+        integer_with_default: An optional integer with a non-None default value
+        boolean_with_default: An optional boolean with a default value
+        number_with_default: An optional number with a default value
+        string_with_default: An optional string with a default value
+        array_optional: An optional string array property
     """
     output = f"""string: {string}
 string_enum: {string_enum}
-string_optional: {string_optional}
 boolean: {boolean}
 integer: {integer}
 number: {number}
 array: {array}
+string_optional: {string_optional}
+integer_with_default: {integer_with_default}
+boolean_with_default: {boolean_with_default}
+number_with_default: {number_with_default}
+string_with_default: {string_with_default}
 array_optional: {array_optional}"""
 
     for key, value in os.environ.items():
diff --git a/assets/functions/tools/demo_ts.ts b/assets/functions/tools/demo_ts.ts
new file mode 100644
index 0000000..26dc8d1
--- /dev/null
+++ b/assets/functions/tools/demo_ts.ts
@@ -0,0 +1,53 @@
+/**
+ * Demonstrates all supported TypeScript parameter types and variations.
+ *
+ * @param string - A required string property
+ * @param string_enum - A required string property constrained to specific values
+ * @param boolean - A required boolean property
+ * @param number - A required number property
+ * @param array_bracket - A required string array using bracket syntax
+ * @param array_generic - A required string array using generic syntax
+ * @param string_optional - An optional string using the question mark syntax
+ * @param string_nullable - An optional string using the union-with-null syntax
+ * @param number_with_default - An optional number with a default value
+ * @param boolean_with_default - An optional boolean with a default value
+ * @param string_with_default - An optional string with a default value
+ * @param array_optional - An optional string array using the question mark syntax
+ */
+export function run(
+  string: string,
+  string_enum: "foo" | "bar",
+  boolean: boolean,
+  number: number,
+  array_bracket: string[],
+  array_generic: Array<string>,
+  string_optional?: string,
+  string_nullable: string | null = null,
+  number_with_default: number = 42,
+  boolean_with_default: boolean = true,
+  string_with_default: string = "hello",
+  array_optional?: string[],
+): string {
+  const parts = [
+    `string: ${string}`,
+    `string_enum: ${string_enum}`,
+    `boolean: ${boolean}`,
+    `number: ${number}`,
+    `array_bracket: ${JSON.stringify(array_bracket)}`,
+    `array_generic: ${JSON.stringify(array_generic)}`,
+    `string_optional: ${string_optional}`,
+    `string_nullable: ${string_nullable}`,
+    `number_with_default: ${number_with_default}`,
+    `boolean_with_default: ${boolean_with_default}`,
+    `string_with_default: ${string_with_default}`,
+    `array_optional: ${JSON.stringify(array_optional)}`,
+  ];
+
+  for (const [key, value] of Object.entries(process.env)) {
+    if (key.startsWith("LLM_")) {
+      parts.push(`${key}: ${value}`);
+    }
+  }
+
+  return parts.join("\n");
+}
diff --git a/assets/functions/tools/get_current_weather.ts b/assets/functions/tools/get_current_weather.ts
new file mode 100644
index 0000000..34bbf0d
--- /dev/null
+++ b/assets/functions/tools/get_current_weather.ts
@@ -0,0 +1,24 @@
+#!/usr/bin/env tsx
+
+import { appendFileSync, mkdirSync } from "fs";
+import { dirname } from "path";
+
+/**
+ * Get the current weather in a given location
+ * @param location - The city and optionally the state or country (e.g., "London", "San Francisco, CA").
+ */
+export async function run(location: string): string {
+  const encoded = encodeURIComponent(location);
+  const url = `https://wttr.in/${encoded}?format=4`;
+
+  const resp = await fetch(url);
+  const data = await resp.text();
+
+  const dest = process.env["LLM_OUTPUT"] ?? "/dev/stdout";
+  if (dest !== "-" && dest !== "/dev/stdout") {
+    mkdirSync(dirname(dest), { recursive: true });
+    appendFileSync(dest, data, "utf-8");
+  }
+
+  return data;
+}
diff --git a/assets/functions/tools/query_jira_issues.sh b/assets/functions/tools/query_jira_issues.sh
deleted file mode 100755
index 4160be0..0000000
--- a/assets/functions/tools/query_jira_issues.sh
+++ /dev/null
@@ -1,11 +0,0 @@
-#!/usr/bin/env bash
-set -e
-
-# @meta require-tools jira
-# @describe Query for jira issues using a Jira Query Language (JQL) query
-# @option --jql-query! The Jira Query Language query to execute
-# @env LLM_OUTPUT=/dev/stdout The output path
-
-main() {
-  jira issue ls -q "$argc_jql_query" --plain >> "$LLM_OUTPUT"
-}
\ No newline at end of file
diff --git a/assets/roles/atlassian.md b/assets/roles/atlassian.md
new file mode 100644
index 0000000..510dd5f
--- /dev/null
+++ b/assets/roles/atlassian.md
@@ -0,0 +1,8 @@
+---
+enabled_mcp_servers: atlassian
+---
+You are the librarian for the company's Confluence and Jira knowledge bases. Your job is to help users find and retrieve
+information from these platforms. Use all tools at your disposal to answer user queries.
+
+Available Tools:
+{{__tools__}}
diff --git a/config.agent.example.yaml b/config.agent.example.yaml
index db26d3b..d79b633 100644
--- a/config.agent.example.yaml
+++ b/config.agent.example.yaml
@@ -17,16 +17,18 @@ agent_session: null              # Set a session to use when starting the agent.
 name: <agent-name>               # Name of the agent, used in the UI and logs
 description: <description>       # Description of the agent, used in the UI
 version: 1                       # Version of the agent
-# Todo System & Auto-Continuation
-# These settings help smaller models handle multi-step tasks more reliably.
-# See docs/TODO-SYSTEM.md for detailed documentation.
+# Auto-Continue (Todo System)
+# The auto-continue system provides built-in task tracking for improved reliability.
+# When enabled, the model can create todo lists and the system will automatically
+# prompt it to continue when incomplete tasks remain.
+# See the [Todo System documentation](https://github.com/Dark-Alex-17/loki/wiki/TODO-System) for more information
 auto_continue: false             # Enable automatic continuation when incomplete todos remain
 max_auto_continues: 10           # Maximum number of automatic continuations before stopping
 inject_todo_instructions: true   # Inject the default todo tool usage instructions into the agent's system prompt
 continuation_prompt: null        # Custom prompt used when auto-continuing (optional; uses default if null)
 # Sub-Agent Spawning System
 # Enable this agent to spawn and manage child agents in parallel.
-# See docs/AGENTS.md for detailed documentation.
+# See https://github.com/Dark-Alex-17/loki/wiki/Agents for detailed documentation.
 can_spawn_agents: false          # Enable the agent to spawn child agents
 max_concurrent_agents: 4         # Maximum number of agents that can run simultaneously
 max_agent_depth: 3               # Maximum nesting depth for sub-agents (prevents runaway spawning)
diff --git a/config.example.yaml b/config.example.yaml
index b626163..0418818 100644
--- a/config.example.yaml
+++ b/config.example.yaml
@@ -27,18 +27,18 @@ sync_models_url: >               # URL to sync model changes from
   https://raw.githubusercontent.com/Dark-Alex-17/loki/refs/heads/main/models.yaml
 
 # ---- REPL Prompt ----
-# Custom REPL left/right prompts; see the [REPL Prompt Documentation](./docs/REPL-PROMPT.md) for more information
+# Custom REPL left/right prompts; see the [REPL Prompt Documentation](https://github.com/Dark-Alex-17/loki/wiki/REPL-Prompt) for more information
 left_prompt:
   '{color.red}{model}){color.green}{?session {?agent {agent}>}{session}{?role /}}{!session {?agent {agent}>}}{role}{?rag @{rag}}{color.cyan}{?session )}{!session >}{color.reset} '
 right_prompt:
   '{color.purple}{?session {?consume_tokens {consume_tokens}({consume_percent}%)}{!consume_tokens {consume_tokens}}}{color.reset}'
 
 # ---- Vault ----
-# See the [Vault documentation](./docs/VAULT.md) for more information on the Loki vault
+# See the [Vault documentation](https://github.com/Dark-Alex-17/loki/wiki/Vault) for more information on the Loki vault
 vault_password_file: null        # Path to a file containing the password for the Loki vault (cannot be a secret template)
 
 # ---- Function Calling ----
-# See the [Tools documentation](./docs/function-calling/TOOLS.md) for more details
+# See the [Tools documentation](https://github.com/Dark-Alex-17/loki/wiki/Tools) for more details
 function_calling: true           # Enables or disables function calling (Globally).
 mapping_tools:                   # Alias for a tool or toolset
   fs: 'fs_cat,fs_ls,fs_mkdir,fs_rm,fs_write,fs_read,fs_glob,fs_grep'
@@ -46,6 +46,7 @@ enabled_tools: null              # Which tools to enable by default. (e.g. 'fs,w
 visible_tools:                   # Which tools are visible to be compiled (and are thus able to be defined in 'enabled_tools')
 #  - demo_py.py
 #  - demo_sh.sh
+#  - demo_ts.ts
   - execute_command.sh
 #  - execute_py_code.py
 #  - execute_sql_code.sh
@@ -61,8 +62,8 @@ visible_tools:                   # Which tools are visible to be compiled (and a
 #  - fs_write.sh
   - get_current_time.sh
 #  - get_current_weather.py
+#  - get_current_weather.ts
   - get_current_weather.sh
-  - query_jira_issues.sh
 #  - search_arxiv.sh
 #  - search_wikipedia.sh
 #  - search_wolframalpha.sh
@@ -73,14 +74,24 @@ visible_tools:                   # Which tools are visible to be compiled (and a
 #  - web_search_tavily.sh
 
 # ---- MCP Servers ----
-# See the [MCP Servers documentation](./docs/MCP-SERVERS.md) for more details
+# See the [MCP Servers documentation](https://github.com/Dark-Alex-17/loki/wiki/MCP-Servers) for more details
 mcp_server_support: true         # Enables or disables MCP servers (globally).
 mapping_mcp_servers:             # Alias for an MCP server or set of servers
   git: github,gitmcp
 enabled_mcp_servers: null        # Which MCP servers to enable by default (e.g. 'github,slack,ddg-search')
 
+# ---- Auto-Continue (Todo System) ----
+# The auto-continue system provides built-in task tracking for improved reliability.
+# When enabled, the model can create todo lists and the system will automatically
+# prompt it to continue when incomplete tasks remain.
+# See the [Todo System documentation](https://github.com/Dark-Alex-17/loki/wiki/TODO-System) for more information
+auto_continue: false              # Enable automatic continuation when incomplete todos remain (default: false)
+max_auto_continues: 10            # Maximum number of automatic continuations before stopping (default: 10)
+inject_todo_instructions: true    # Inject default todo usage instructions into the system prompt (default: true)
+continuation_prompt: null         # Custom prompt used when auto-continuing. If null, uses built-in default
+
 # ---- Session ----
-# See the [Session documentation](./docs/SESSIONS.md) for more information
+# See the [Session documentation](https://github.com/Dark-Alex-17/loki/wiki/Sessions) for more information
 save_session: null               # Controls the persistence of the session. If true, auto save; if false, don't auto-save save; if null, ask the user what to do
 compression_threshold: 4000      # Compress the session when the token count reaches or exceeds this threshold
 summarization_prompt: >          # The text prompt used for creating a concise summary of session message
@@ -89,7 +100,7 @@ summary_context_prompt: >        # The text prompt used for including the summar
   'This is a summary of the chat history as a recap: '
 
 # ---- RAG ----
-# See the [RAG Docs](./docs/RAG.md) for more details.
+# See the [RAG Docs](https://github.com/Dark-Alex-17/loki/wiki/RAG) for more details.
 rag_embedding_model: null        # Specifies the embedding model used for context retrieval
 rag_reranker_model: null         # Specifies the reranker model used for sorting retrieved documents; Loki uses Reciprocal Rank Fusion by default
 rag_top_k: 5                     # Specifies the number of documents to retrieve for answering queries
@@ -135,7 +146,7 @@ document_loaders:
     sh -c "yek $1 --json | jq 'map({ path: .filename, contents: .content })'"
 
 # ---- Clients ----
-# See the [Clients documentation](./docs/clients/CLIENTS.md) for more details
+# See the [Clients documentation](https://github.com/Dark-Alex-17/loki/wiki/Clients) for more details
 clients:
   # All clients have the following configuration:
   # - type: xxxx
diff --git a/config.role.example.md b/config.role.example.md
index 3159277..25804bf 100644
--- a/config.role.example.md
+++ b/config.role.example.md
@@ -1,5 +1,9 @@
 ---
-# Everything in this section is optional
+############################################
+## Everything in this section is optional ##
+############################################
+
+# Role Configuration
 name: <role-name>                     # The name of the role
 model: openai:gpt-4o                  # The model to use for this role
 temperature: 0.2                      # The temperature to use for this role when querying the model
@@ -8,5 +12,14 @@ enabled_tools: fs_ls,fs_cat           # A comma-separated list of tools to enabl
 enabled_mcp_servers: github,gitmcp    # A comma-separated list of MCP servers to enable for this role
 prompt: null                          # A custom prompt to use for this role that will immediately query
                                       # the model for output instead of using the instructions below
+# Auto-Continue (Todo System)
+# The auto-continue system provides built-in task tracking for improved reliability.
+# When enabled, the model can create todo lists and the system will automatically
+# prompt it to continue when incomplete tasks remain.
+# See the [Todo System documentation](https://github.com/Dark-Alex-17/loki/wiki/TODO-System) for more information
+auto_continue: false                  # Enable automatic continuation when incomplete todos remain (default: false)
+max_auto_continues: 10                # Maximum number of automatic continuations before stopping (default: 10)
+inject_todo_instructions: true        # Inject default todo tool usage instructions into the system prompt (default: true)
+continuation_prompt: null             # Custom prompt used when auto-continuing. If null, uses built-in default
 ---
 You are an expert at doing things. This is where you write the instructions for the role.
diff --git a/docs/AGENTS.md b/docs/AGENTS.md
deleted file mode 100644
index d9d0aea..0000000
--- a/docs/AGENTS.md
+++ /dev/null
@@ -1,722 +0,0 @@
-# Agents
-
-Agents in Loki follow the same style as OpenAI's GPTs. They consist of 3 parts:
-
-* [Role](./ROLES.md) - Tell the LLM how to behave
-* [RAG](./RAG.md) - Pre-built knowledge bases specifically for the agent
-* [Function Calling](./function-calling/TOOLS.md#tools) ([#2](./function-calling/MCP-SERVERS.md)) - Extends the functionality of the LLM through custom functions it can call
-
-![Agent example](./images/agents/sql.gif)
-
-Agent configuration files are stored in the `agents` subdirectory of your Loki configuration directory. The location of
-this directory varies between systems so you can use the following command to locate yours:
-
-```shell
-loki --info | grep 'agents_dir' | awk '{print $2}'
-```
-
-If you're looking for more example agents, refer to the [built-in agents](../assets/agents).
-
-## Quick Links
-<!--toc:start-->
-- [Directory Structure](#directory-structure)
-- [Metadata](#1-metadata)
-- [2. Define the Instructions](#2-define-the-instructions)
-  - [Static Instructions](#static-instructions)
-    - [Special Variables](#special-variables)
-    - [User-Defined Variables](#user-defined-variables)
-  - [Dynamic Instructions](#dynamic-instructions)
-  - [Variables](#variables)
-- [3. Initializing RAG](#3-initializing-rag)
-- [4. Building Tools for Agents](#4-building-tools-for-agents)
-  - [Limitations](#limitations)
-  - [.env File Support](#env-file-support)
-  - [Python-Based Agent Tools](#python-based-agent-tools)
-  - [Bash-Based Agent Tools](#bash-based-agent-tools)
-- [5. Conversation Starters](#5-conversation-starters)
-- [6. Todo System & Auto-Continuation](#6-todo-system--auto-continuation)
-- [7. Sub-Agent Spawning System](#7-sub-agent-spawning-system)
-  - [Configuration](#spawning-configuration)
-  - [Spawning & Collecting Agents](#spawning--collecting-agents)
-  - [Task Queue with Dependencies](#task-queue-with-dependencies)
-  - [Active Task Dispatch](#active-task-dispatch)
-  - [Output Summarization](#output-summarization)
-  - [Teammate Messaging](#teammate-messaging)
-  - [Runaway Safeguards](#runaway-safeguards)
-- [8. User Interaction Tools](#8-user-interaction-tools)
-  - [Available Tools](#user-interaction-available-tools)
-  - [Escalation (Sub-Agent to User)](#escalation-sub-agent-to-user)
-- [9. Auto-Injected Prompts](#9-auto-injected-prompts)
-- [Built-In Agents](#built-in-agents)
-<!--toc:end-->
-
----
-
-## Directory Structure
-Agent configurations often have the following directory structure:
-
-```
-<loki-config-dir>/agents
-    └── my-agent
-        ├── config.yaml
-        ├── tools.sh
-            or
-        ├── tools.py
-```
-
-This means that agent configurations often are only two files: the agent configuration file (`config.yaml`), and the 
-tool definitions (`agents/my-agent/tools.sh` or `tools.py`).
-
-To see a full example configuration file, refer to the [example agent config file](../config.agent.example.yaml).
-
-The best way to understand how an agent is built is to go step by step in the following manner:
-
----
-
-## 1. Metadata
-Agent configurations have the following settings available to customize each agent:
-
-```yaml
-# Model Configuration
-model: openai:gpt-4o                 # Specify the LLM to use
-temperature: null                    # Set default temperature parameter, range (0, 1)
-top_p: null                          # Set default top-p parameter, with a range of (0, 1) or (0, 2), depending on the model
-# Agent Metadata Configuration
-agent_session: null                  # Set a session to use when starting the agent. (e.g. temp, default); defaults to globally set agent_session
-# Agent Configuration
-name: <agent-name>                   # Name of the agent, used in the UI and logs
-description: <description>           # Description of the agent, used in the UI
-version: 1                           # Version of the agent
-# Function Calling Configuration
-mcp_servers:                         # Optional list of MCP servers that the agent utilizes
-  - github                           # Corresponds to the name of an MCP server in the `<loki-config-dir>/functions/mcp.json` file
-global_tools:                        # Optional list of additional global tools to enable for the agent; i.e. not tools specific to the agent
-  - web_search
-  - fs
-  - python
-# Todo System & Auto-Continuation (see "Todo System & Auto-Continuation" section below)
-auto_continue: false                 # Enable automatic continuation when incomplete todos remain
-max_auto_continues: 10               # Maximum continuation attempts before stopping
-inject_todo_instructions: true       # Inject todo tool instructions into system prompt
-continuation_prompt: null            # Custom prompt for continuations (optional)
-# Sub-Agent Spawning (see "Sub-Agent Spawning System" section below)
-can_spawn_agents: false              # Enable spawning child agents
-max_concurrent_agents: 4             # Max simultaneous child agents
-max_agent_depth: 3                   # Max nesting depth (prevents runaway)
-inject_spawn_instructions: true      # Inject spawning instructions into system prompt
-summarization_model: null            # Model for summarizing sub-agent output (e.g. 'openai:gpt-4o-mini')
-summarization_threshold: 4000        # Char count above which sub-agent output is summarized
-escalation_timeout: 300              # Seconds sub-agents wait for escalated user input (default: 5 min)
-```
-
-As mentioned previously: Agents utilize function calling to extend a model's capabilities. However, agents operate in 
-isolated environment, so in order for an agent to use a tool or MCP server that you have defined globally, you must 
-explicitly state which tools and/or MCP servers the agent uses. Otherwise, it is assumed that the agent doesn't use any 
-tools outside its own custom defined tools.
-
-And if you don't define a `agents/my-agent/tools.sh` or `agents/my-agent/tools.py`, then the agent is really just a 
-`role`.
-
-You'll notice there's no settings for agent-specific tooling. This is because they are handled separately and 
-automatically. See the [Building Tools for Agents](#4-building-tools-for-agents) section below for more information.
-
-To see a full example configuration file, refer to the [example agent config file](../config.agent.example.yaml).
-
-## 2. Define the Instructions
-At their heart, agents function similarly to roles in that they tell the model how to behave. Agent configuration files
-have the following settings for the instruction definitions:
-
-```yaml
-dynamic_instructions:     # Whether to use dynamically generated instructions for the agent; if false, static instructions are used. False by default.
-instructions:             # Static instructions for the LLM; These are ignored if dynamic instructions are used
-variables:                # An array of optional variables that the agent expects and uses
-```
-
-### Static Instructions
-By default, Loki agents use statically defined instructions. Think of them as being identical to the instructions for a
-[role](./ROLES.md#instructions), because they virtually are. 
-
-**Example:**
-```yaml
-instructions: |
-  You are an AI agent designed to demonstrate agentic capabilities
-```
-
-Just like roles, agents support variable interpolation at runtime. There's two types of variables that can be 
-interpolated into the instructions at runtime: special variables (like roles have), and user-defined variables. Just 
-like roles, variables are interpolated into your instructions anywhere Loki sees the `{{variable}}` syntax.
-
-#### Special Variables
-The following special variables are provided by Loki at runtime and can be injected into your agent's instructions:
-
-| Name            | Description                                                         | Example                    |
-|-----------------|---------------------------------------------------------------------|----------------------------|
-| `__os__`        | Operating system name                                               | `linux`                    |
-| `__os_family__` | Operating system family                                             | `unix`                     |
-| `__arch__`      | System architecture                                                 | `x86_64`                   |
-| `__shell__`     | The current user's default shell                                    | `bash`                     |
-| `__locale__`    | The current user's preferred language and region settings           | `en-US`                    |
-| `__now__`       | Current timestamp in ISO 8601 format                                | `2025-11-07T10:15:44.268Z` |
-| `__cwd__`       | The current working directory                                       | `/tmp`                     |
-| `__tools__`     | A list of the enabled tools (global + mcp servers + agent-specific) |                            |
-
-#### User-Defined Variables
-Agents also support user-defined variables that can be interpolated into the instructions, and are made available to any
-agent-specific tools you define (see [Building Tools for Agents](#4-building-tools-for-agents) for more details on how to 
-create agent-specific tooling).
-
-The `variables` setting in an agent's config has the following fields:
-
-| Field         | Required | Description                                                                                        |
-|---------------|----------|----------------------------------------------------------------------------------------------------|
-| `name`        | *        | The name of the variable                                                                           |
-| `description` | *        | The description of the field                                                                       |
-| `default`     |          | A default value for the field. If left undefined, the user will be prompted for a value at runtime |
-
-These variables can be referenced in both the agent's instructions, and in the tool definitions via `LLM_AGENT_VAR_<name>`.
-
-**Example:**
-```yaml
-instructions: |
-  You are an agent who answers questions about a user's system.
-
-  <tools>
-  {{__tools__}}
-  </tools>
-
-  <system>
-  os: {{__os__}}
-  os_family: {{__os_family__}}
-  arch: {{__arch__}}
-  shell: {{__shell__}}
-  locale: {{__locale__}}
-  now: {{__now__}}
-  cwd: {{__cwd__}}
-  </system>
-
-  <user>
-  username: {{username}}
-  </user>
-variables:
-  - name: username                 # Accessible from the tool definitions via the `LLM_AGENT_VAR_USERNAME` environment variable
-    description: Your user name
-```
-
-### Dynamic Instructions
-Sometimes you may find it useful to dynamically generate instructions on startup. Whether that be via a call to Loki
-itself to generate them, or by some other means. Loki supports this type of behavior using a special function defined
-in your `agents/my-agent/tools.py` or `agents/my-agent/tools.sh`.
-
-**Example: Instructions for a JSON-reader agent that specializes on each JSON input it receives**
-`agents/json-reader/tools.py`:
-```python
-import json
-from pathlib import Path
-from genson import SchemaBuilder
-
-def _instructions():
-    """Generates instructions for the agent dynamically"""
-    value = input("Enter a JSON file path OR paste raw JSON: ").strip()
-    if not value:
-        raise SystemExit("A file path or JSON string is required.")
-
-    p = Path(value)
-    if p.exists() and p.is_file():
-        json_file_path = str(p.resolve())
-        json_text = p.read_text(encoding="utf-8")
-    else:
-        try:
-            json.loads(value)
-        except json.JSONDecodeError as e:
-            raise SystemExit(f"Input is neither a file nor valid JSON.\n{e}")
-        json_file_path = "<provided-inline-json>"
-        json_text = value
-
-    try:
-        data = json.loads(json_text)
-    except json.JSONDecodeError as e:
-        raise SystemExit(f"Provided content is not valid JSON.\n{e}")
-
-    builder = SchemaBuilder()
-    builder.add_object(data)
-    json_schema = builder.to_schema()
-    return f"""
-        You are an AI agent that can view and filter JSON data with jq.
-        
-        ## Context
-        json_file_path: {json_file_path}
-        json_schema: {json.dumps(json_schema, indent=2)}
-    """
-```
-
-or
-
-`agents/json-reader/tools.sh`:
-```bash
-#!/usr/bin/env bash
-set -e
-
-# @meta require-tools jq,genson
-# @env LLM_OUTPUT=/dev/stdout The output path
-
-# @cmd Generates instructions for the agent dynamically
-_instructions() {
-	read -r -p "Enter a JSON file path OR paste raw JSON: " value
-	
-	if [[ -z "${value}" ]]; then
-		echo "A file path or JSON string is required" >&2
-		exit 1
-	fi 
-	json_file_path=""
-    inline_temp=""
-    cleanup() {
-      [[ -n "${inline_temp:-}" && -f "${inline_temp}" ]] && rm -f "${inline_temp}"
-    }
-    trap cleanup EXIT
-    
-    if [[ -f "${value}" ]]; then
-      json_file_path="$(realpath "${value}")"
-      if ! jq empty "${json_file_path}" >/dev/null 2>&1; then
-        echo "Error: File does not contain valid JSON: ${json_file_path}" >&2
-        exit 1
-      fi
-    else
-      inline_temp="$(mktemp)"
-      printf "%s" "${value}" > "${inline_temp}"
-      if ! jq empty "${inline_temp}" >/dev/null 2>&1; then
-        echo "Error: Input is neither a file nor valid JSON." >&2
-        exit 1
-      fi
-      json_file_path="<provided-inline-json>"
-    fi
-    
-    source_file="${json_file_path}"
-    if [[ "${json_file_path}" == "<provided-inline-json>" ]]; then
-      source_file="${inline_temp}"
-    fi
-    
-    json_schema="$(genson < "${source_file}" | jq -c '.')"
-	cat <<EOF >> "$LLM_OUTPUT"
-You are an AI agent that can view and filter JSON data with jq.
-
-## Context
-json_file_path: ${json_file_path}
-json_schema: ${json_schema}
-EOF
-}
-```
-
-For more information on how to create custom tools for your agent and the structure of the `agent/my-agent/tools.sh` or 
-`agent/my-agent/tools.py` files, refer to the [Building Tools for Agents](#4-building-tools-for-agents) section below.
-
-#### Variables
-All the same variable interpolations supported by static instructions is also supported by dynamic instructions. For 
-more information on what variables are available and how to use them, refer to the [Special Variables](#special-variables)
-and [User-Defined Variables](#user-defined-variables) sections above.
-
-## 3. Initializing RAG
-Each agent you create also has a dedicated knowledge base that adds additional context to your queries and helps the LLM
-answer queries effectively. The documents to load into RAG are defined in the `documents` array of your agent 
-configuration file:
-
-```yaml
-documents:
-  - https://www.ohdsi.org/data-standardization/
-  - https://github.com/OHDSI/Vocabulary-v5.0/wiki/**
-  - OMOPCDM_ddl.sql       # Relative path to agent (i.e. file lives at '<loki-config-dir>/agents/my-agent/OMOPCDM_ddl.sql')
-```
-
-These documents use the same syntax as those you'd define when constructing RAG normally. To see all the available types
-of documents that Loki supports and how to use custom document loaders, refer to the [RAG documentation](./RAG.md#supported-document-sources).
-
-Anytime your agent starts up, it will automatically be using the RAG you've defined here.
-
-## 4. Building Tools for Agents
-Building tools for agents is virtually identical to building custom tools, with one slight difference: instead of 
-defining a single function that gets executed at runtime (e.g. `main` for bash tools and `run` for Python tools), agent
-tools define a number of *subcommands*.
-
-### Limitations
-You can only utilize either a bash-based `<loki-config-dir>/agents/my-agent/tools.sh` or a Python-based 
-`<loki-config-dir>/agents/my-agent/tools.py`. However, if it's easier to achieve a task in one language vs the other, 
-you're free to define other scripts in your agent's configuration directory and reference them from the main 
-`tools.py/sh` file. **Any scripts *not* named `tools.{py,sh}` will not be picked up by Loki's compiler**, meaning they 
-can be used like any other set of scripts.
-
-It's important to keep in mind the following:
-
-* **Do not give agents the same name as an executable**. Loki compiles the tools for each agent into a binary that it
-  temporarily places on your path during execution. If you have a binary with the same name as your agent, then your 
-  shell may execute the existing binary instead of your agent's tools
-* **`LLM_ROOT_DIR` points to the agent's configuration directory**. This is where agents differ slightly from normal 
-  tools: The `LLM_ROOT_DIR` environment variable does *not* point to the `functions/tools` directory like it does in 
-  global tools. Instead, it points to the agent's configuration directory, making it easier to source scripts and other
-  miscellaneous files
-
-### .env File Support
-When Loki loads an agent, it will also search the agent's configuration directory for a `.env` file. If found, all 
-environment variables defined in the file will be made available to the agent's tools.
-
-### Python-Based Agent Tools
-Python-based tools are defined exactly the same as they are for custom tool definitions. The only difference is that 
-instead of a single `run` function, you define as many as you like with whatever arguments you like.
-
-**Example:**
-`agents/my-agent/tools.py`
-```python
-import urllib.request
-
-def get_ip_info():
-  """
-  Get your IP information
-  """
-  with urllib.request.urlopen("https://httpbin.org/ip") as response:
-    data = response.read()
-    return data.decode('utf-8')
-
-def get_ip_address_from_aws():
-    """
-    Find your public IP address using AWS
-    """
-    with urllib.request.urlopen("https://checkip.amazonaws.com") as response:
-        data = response.read()
-        return data.decode('utf-8')
-```
-
-Loki automatically compiles these as separate functions for the LLM to call. No extra work is needed. Just make sure you
-follow all the same steps to define each function as you would when creating custom Python tools.
-
-For more information on how to build tools in Python, refer to the [custom Python tools documentation](./function-calling/CUSTOM-TOOLS.md#custom-python-based-tools)
-
-### Bash-Based Agent Tools
-Bash-based agent tools are virtually identical to custom bash tools, with only one difference. Instead of defining a 
-single entrypoint via the `main` function, you actually define as many subcommands as you like.
-
-**Example:**
-`agents/my-agent/tools.sh`
-```bash
-#!/usr/bin/env bash
-
-# @env LLM_OUTPUT=/dev/stdout The output path
-# @describe Discover network information about your computer and its place in the internet
-
-# Use the `@cmd` annotation to define subcommands for your script.
-# @cmd Get your IP information
-get_ip_info() {
-  curl -fsSL https://httpbin.org/ip >> "$LLM_OUTPUT"
-}
-
-# @cmd Find your public IP address using AWS
-get_ip_address_from_aws() {
-  curl -fsSL https://checkip.amazonaws.com >> "$LLM_OUTPUT"
-}
-```
-To compile the script so it's executable and testable:
-```bash
-$ loki --build-tools
-```
-
-Then you can execute your script (assuming your current working directory is `agents/my-agent`):
-```bash
-$ ./tools.sh get_ip_info
-$ ./tools.sh get_ip_address_from_aws
-```
-
-All other special annotations (`@env`, `@arg`, `@option` `@flags`) apply to subcommands as well, so be sure to follow 
-the same syntax ad formatting as is used to create custom bash tools globally.
-
-For more information on how to write, [build and test](function-calling/CUSTOM-BASH-TOOLS.md#execute-and-test-your-bash-tools) tools in bash, refer to the 
-[custom bash tools documentation](function-calling/CUSTOM-BASH-TOOLS.md).
-
-## 5. Conversation Starters
-It's often helpful to also have some conversation starters so users know what kinds of things the agent is capable of 
-doing. These are available in the REPL via the `.starter` command and are selectable.
-
-They are defined using the `conversation_starters` setting in your agent's configuration file:
-
-**Example:**
-`agents/my-agent/config.yaml`:
-```yaml
-conversation_starters:
-  - What is my username?
-  - What is my current shell?
-  - What is my ip?
-  - How much disk space is left on my PC??
-  - How to create an agent?
-```
-
-![Example Conversation Starters](./images/agents/conversation-starters.gif)
-
-## 6. Todo System & Auto-Continuation
-
-Loki includes a built-in task tracking system designed to improve the reliability of agents, especially when using
-smaller language models. The Todo System helps models:
-
-- Break complex tasks into manageable steps
-- Track progress through multi-step workflows
-- Automatically continue work until all tasks are complete
-
-### Quick Configuration
-
-```yaml
-# agents/my-agent/config.yaml
-auto_continue: true              # Enable auto-continuation
-max_auto_continues: 10           # Max continuation attempts
-inject_todo_instructions: true   # Include the default todo instructions into prompt
-```
-
-### How It Works
-
-1. When `inject_todo_instructions` is enabled, agents receive instructions on using five built-in tools:
-    - `todo__init`: Initialize a todo list with a goal
-    - `todo__add`: Add a task to the list
-    - `todo__done`: Mark a task complete
-    - `todo__list`: View current todo state
-    - `todo__clear`: Clear the entire todo list and reset the goal
-   
-   These instructions are a reasonable default that detail how to use Loki's To-Do System. If you wish, 
-   you can disable the injection of the default instructions and specify your own instructions for how 
-   to use the To-Do System into your main `instructions` for the agent.
-
-2. When `auto_continue` is enabled and the model stops with incomplete tasks, Loki automatically sends a
-   continuation prompt with the current todo state, nudging the model to continue working.
-
-3. This continues until all tasks are done or `max_auto_continues` is reached.
-
-### When to Use
-
-- Multistep tasks where the model might lose track
-- Smaller models that need more structure
-- Workflows requiring guaranteed completion of all steps
-
-For complete documentation including all configuration options, tool details, and best practices, see the
-[Todo System Guide](./TODO-SYSTEM.md).
-
-## 7. Sub-Agent Spawning System
-
-Loki agents can spawn and manage child agents that run **in parallel** as background tasks inside the same process.
-This enables orchestrator-style agents that delegate specialized work to other agents, similar to how tools like
-Claude Code or OpenCode handle complex multi-step tasks.
-
-For a working example of an orchestrator agent that uses sub-agent spawning, see the built-in
-[sisyphus](../assets/agents/sisyphus) agent. For an example of the teammate messaging pattern with parallel sub-agents, 
-see the [code-reviewer](../assets/agents/code-reviewer) agent.
-
-### Spawning Configuration
-
-| Setting                     | Type    | Default       | Description                                                                    |
-|-----------------------------|---------|---------------|--------------------------------------------------------------------------------|
-| `can_spawn_agents`          | boolean | `false`       | Enable this agent to spawn child agents                                        |
-| `max_concurrent_agents`     | integer | `4`           | Maximum number of child agents that can run simultaneously                     |
-| `max_agent_depth`           | integer | `3`           | Maximum nesting depth for sub-agents (prevents runaway spawning chains)        |
-| `inject_spawn_instructions` | boolean | `true`        | Inject the default spawning instructions into the agent's system prompt        |
-| `summarization_model`       | string  | current model | Model to use for summarizing long sub-agent output (e.g. `openai:gpt-4o-mini`) |
-| `summarization_threshold`   | integer | `4000`        | Character count above which sub-agent output is summarized before returning    |
-| `escalation_timeout`        | integer | `300`         | Seconds a sub-agent waits for an escalated user interaction response           |
-
-**Example configuration:**
-```yaml
-# agents/my-orchestrator/config.yaml
-can_spawn_agents: true
-max_concurrent_agents: 6
-max_agent_depth: 2
-inject_spawn_instructions: true
-summarization_model: openai:gpt-4o-mini
-summarization_threshold: 3000
-escalation_timeout: 600
-```
-
-### Spawning & Collecting Agents
-
-When `can_spawn_agents` is enabled, the agent receives tools for spawning and managing child agents:
-
-| Tool             | Description                                                             |
-|------------------|-------------------------------------------------------------------------|
-| `agent__spawn`   | Spawn a child agent in the background. Returns an agent ID immediately. |
-| `agent__check`   | Non-blocking check: is the agent done? Returns `PENDING` or the result. |
-| `agent__collect` | Blocking wait: wait for an agent to finish, return its output.          |
-| `agent__list`    | List all spawned agents and their status.                               |
-| `agent__cancel`  | Cancel a running agent by ID.                                           |
-
-The core pattern is **Spawn -> Continue -> Collect**:
-
-```
-# 1. Spawn agents in parallel (returns IDs immediately)
-agent__spawn --agent explore --prompt "Find auth middleware patterns in src/"
-agent__spawn --agent explore --prompt "Find error handling patterns in src/"
-
-# 2. Continue your own work while they run
-
-# 3. Check if done (non-blocking)
-agent__check --id agent_explore_a1b2c3d4
-
-# 4. Collect results when ready (blocking)
-agent__collect --id agent_explore_a1b2c3d4
-agent__collect --id agent_explore_e5f6g7h8
-```
-
-Any agent defined in your `<loki-config-dir>/agents/` directory can be spawned as a child. Child agents:
-- Run in a fully isolated environment (separate session, config, and tools)
-- Have their output suppressed from the terminal (no spinner, no tool call logging)
-- Return their accumulated output to the parent when collected
-
-### Task Queue with Dependencies
-
-For complex workflows where tasks have ordering requirements, the spawning system includes a dependency-aware
-task queue:
-
-| Tool                   | Description                                                                 |
-|------------------------|-----------------------------------------------------------------------------|
-| `agent__task_create`   | Create a task with optional dependencies and auto-dispatch agent.           |
-| `agent__task_list`     | List all tasks with their status, dependencies, and assignments.            |
-| `agent__task_complete` | Mark a task done. Returns newly unblocked tasks and auto-dispatches agents. |
-| `agent__task_fail`     | Mark a task as failed. Dependents remain blocked.                           |
-
-```
-# Create tasks with dependency ordering
-agent__task_create --subject "Explore existing patterns"
-agent__task_create --subject "Implement feature" --blocked_by ["task_1"]
-agent__task_create --subject "Write tests" --blocked_by ["task_2"]
-
-# Mark tasks complete to unblock dependents
-agent__task_complete --task_id task_1
-```
-
-### Active Task Dispatch
-
-Tasks can optionally specify an agent to auto-spawn when the task becomes runnable:
-
-```
-agent__task_create \
-  --subject "Implement the auth module" \
-  --blocked_by ["task_1"] \
-  --agent coder \
-  --prompt "Implement auth module based on patterns found in task_1"
-```
-
-When `task_1` completes and the dependent task becomes unblocked, an agent is automatically spawned with the
-specified prompt. No manual intervention needed. This enables fully automated multi-step pipelines.
-
-### Output Summarization
-
-When a child agent produces long output, it can be automatically summarized before returning to the parent.
-This keeps parent context windows manageable.
-
-- If the output exceeds `summarization_threshold` characters (default: 4000), it is sent through an LLM
-  summarization pass
-- The `summarization_model` setting lets you use a cheaper/faster model for summarization (e.g. `gpt-4o-mini`)
-- If `summarization_model` is not set, the parent's current model is used
-- The summarization preserves all actionable information: code snippets, file paths, error messages, and
-  concrete recommendations
-
-### Teammate Messaging
-
-All agents (including children) automatically receive tools for **direct sibling-to-sibling messaging**:
-
-| Tool                  | Description                                         |
-|-----------------------|-----------------------------------------------------|
-| `agent__send_message` | Send a text message to another agent's inbox by ID. |
-| `agent__check_inbox`  | Drain all pending messages from your inbox.         |
-
-This enables coordination patterns where child agents share cross-cutting findings:
-
-```
-# Agent A discovers something relevant to Agent B
-agent__send_message --id agent_reviewer_b1c2d3e4 --message "Found a security issue in auth.rs line 42"
-
-# Agent B checks inbox before finalizing
-agent__check_inbox
-```
-
-Messages are routed through the parent's supervisor. A parent can message its children, and children can message
-their siblings. For a working example of the teammate pattern, see the built-in
-[code-reviewer](../assets/agents/code-reviewer) agent, which spawns file-specific reviewers that share
-cross-cutting findings with each other.
-
-### Runaway Safeguards
-
-The spawning system includes built-in safeguards to prevent runaway agent chains:
-
-- **`max_concurrent_agents`:** Caps how many agents can run at once (default: 4). Spawn attempts beyond this
-  limit return an error asking the agent to wait or cancel existing agents.
-- **`max_agent_depth`:** Caps nesting depth (default: 3). A child agent spawning its own child increments the
-  depth counter. Attempts beyond the limit are rejected.
-- **`can_spawn_agents`:** Only agents with this flag set to `true` can spawn children. By default, spawning is
-  disabled. This means child agents cannot spawn their own children unless you explicitly create them with
-  `can_spawn_agents: true` in their config.
-
-## 8. User Interaction Tools
-
-Loki includes built-in tools for agents (and the REPL) to interactively prompt the user for input. These tools
-are **always available**. No configuration needed. They are automatically injected into every agent and into
-REPL mode when function calling is enabled.
-
-### User Interaction Available Tools
-
-| Tool             | Description                             | Returns                          |
-|------------------|-----------------------------------------|----------------------------------|
-| `user__ask`      | Present a single-select list of options | The selected option string       |
-| `user__confirm`  | Ask a yes/no question                   | `"yes"` or `"no"`                |
-| `user__input`    | Request free-form text input            | The text entered by the user     |
-| `user__checkbox` | Present a multi-select checkbox list    | Array of selected option strings |
-
-**Parameters:**
-
-- `user__ask`: `--question "..." --options ["Option A", "Option B", "Option C"]`
-- `user__confirm`: `--question "..."`
-- `user__input`: `--question "..."`
-- `user__checkbox`: `--question "..." --options ["Option A", "Option B", "Option C"]`
-
-At the top level (depth 0), these tools render interactive terminal prompts directly using arrow-key navigation,
-checkboxes, and text input fields.
-
-### Escalation (Sub-Agent to User)
-
-When a **child agent** (depth > 0) calls a `user__*` tool, it cannot prompt the terminal directly. Instead,
-the request is **automatically escalated** to the root agent:
-
-1. The child agent calls `user__ask(...)` and **blocks**, waiting for a reply
-2. The root agent sees a `pending_escalations` notification in its next tool results
-3. The root agent either answers from context or prompts the user itself, then calls
-   `agent__reply_escalation` to unblock the child
-4. The child receives the reply and continues
-
-The escalation timeout is configurable via `escalation_timeout` in the agent's `config.yaml` (default: 300
-seconds / 5 minutes). If the timeout expires, the child receives a fallback message asking it to use its
-best judgment.
-
-| Tool                      | Description                                                              |
-|---------------------------|--------------------------------------------------------------------------|
-| `agent__reply_escalation` | Reply to a pending child escalation, unblocking the waiting child agent. |
-
-This tool is automatically available to any agent with `can_spawn_agents: true`.
-
-## 9. Auto-Injected Prompts
-
-Loki automatically appends usage instructions to your agent's system prompt for each enabled built-in system.
-These instructions are injected into both **static and dynamic instructions** after your own instructions,
-ensuring agents always know how to use their available tools.
-
-| System             | Injected When                                                  | Toggle                      |
-|--------------------|----------------------------------------------------------------|-----------------------------|
-| Todo tools         | `auto_continue: true` AND `inject_todo_instructions: true`     | `inject_todo_instructions`  |
-| Spawning tools     | `can_spawn_agents: true` AND `inject_spawn_instructions: true` | `inject_spawn_instructions` |
-| Teammate messaging | Always (all agents)                                            | None (always injected)      |
-| User interaction   | Always (all agents)                                            | None (always injected)      |
-
-If you prefer to write your own instructions for a system, set the corresponding `inject_*` flag to `false`
-and include your custom instructions in the agent's `instructions` field. The built-in tools will still be
-available; only the auto-injected prompt text is suppressed.
-
-## Built-In Agents
-Loki comes packaged with some useful built-in agents:
-
-* `coder`: An agent to assist you with all your coding tasks
-* `code-reviewer`: A [CodeRabbit](https://coderabbit.ai)-style code reviewer that spawns per-file reviewers using the teammate messaging pattern
-* `demo`: An example agent to use for reference when learning to create your own agents
-* `explore`: An agent designed to help you explore and understand your codebase
-* `file-reviewer`: An agent designed to perform code-review on a single file (used by the `code-reviewer` agent)
-* `jira-helper`: An agent that assists you with all your Jira-related tasks
-* `oracle`: An agent for high-level architecture, design decisions, and complex debugging
-* `sisyphus`: A powerhouse orchestrator agent for writing complex code and acting as a natural language interface for your codebase (similar to ClaudeCode, Gemini CLI, Codex, or OpenCode). Uses sub-agent spawning to delegate to `explore`, `coder`, and `oracle`.
-* `sql`: A universal SQL agent that enables you to talk to any relational database in natural language
diff --git a/docs/AICHAT-MIGRATION.md b/docs/AICHAT-MIGRATION.md
deleted file mode 100644
index f48050f..0000000
--- a/docs/AICHAT-MIGRATION.md
+++ /dev/null
@@ -1,211 +0,0 @@
-# AIChat to Loki Migration Guide
-Loki originally started as a fork of AIChat but has since evolved into its own separate project with separate goals.
-
-As a result, there's some changes you'll need to make to your AIChat configuration to be able to use Loki.
-
-Be sure you've run `loki` at least once so that the Loki configuration directory and subdirectories exist and is
-populated with the built-in defaults.
-
-## Global Configuration File
-You should be able to copy/paste your AIChat configuration file into your Loki configuration directory. Since the 
-location of the Loki configuration directory varies between systems, you can use the following command to locate your
-config directory:
-
-```shell
-loki --info | grep 'config_dir' | awk '{print $2}'
-```
-
-Then, you'll need to make the following changes:
-
-* `function_calling` -> `function_calling_support`
-* `use_tools` -> `enabled_tools`
-* `agent_prelude` -> `agent_session`
-* `compress_threshold` -> `compression_threshold`
-* `summarize_prompt` -> `summarization_prompt`
-* `summary_prompt` -> `summary_context_prompt`
-
-## Roles
-Locate your `roles` directory using the following command:
-
-```shell
-loki --info | grep 'roles_dir' | awk '{print $2}'
-```
-
-Update any roles that have `use_tools` to `enabled_tools`.
-
-## Sessions
-Locate your `sessions` directory using the following command:
-
-```shell
-loki --info | grep 'sessions_dir' | awk '{print $2}'
-```
-
-Update the following settings:
-* `use_tools` -> `enabled_tools`
-* `compress_threshold` -> `compression_threshold`
-* `summarize_prompt` -> `summarization_prompt`
-* `summary_prompt` -> `summary_context_prompt`
-
----
-
-# LLM Functions Changes
-Probably the most significant difference between AIChat and Loki is how tools are handled. So if you cloned the 
-[llm-functions](https://github.com/sigoden/llm-functions) repo, you'll need to make the following changes.
-
-**Note: JavaScript functions are not supported in Loki.**
-
-The following guide assumes you're using the `llm-functions` repository as your base for custom functions, and thus
-follows that directory structure.
-
-## Agents
-Agents are now all handled in one place: the `agents` directory (`<loki-config-dir>/agents`):
-
-```shell
-loki --info | grep 'agents_dir' | awk '{print $2}'
-```
-
-And instead of separate `index.yaml` and `config.yaml` files, they're now both in a single `config.yaml` file.
-
-So now for all of your agents, copy all the contents of those directories to the corresponding directory in the Loki 
-`agents` directory. Then make the following changes:
-
-* Copy the contents of your `<aichat-config-dir>/functions/agents` directory into `<loki-config-dir/agents`
-* Merge `index.yaml` into `config.yaml`
-  * If you never created a custom `config.yaml` file, then simply rename `index.yaml` to `config.yaml`
-  * If you've defined an `agent_prelude`, rename that field to `agent_session`
-* Convert all JavaScript tools to either Python or Bash
-* For Bash `tools.sh`: Remove the following line:
-  ```bash
-  eval "$(argc --argc-eval "$0" "$@")"
-  ```
-* Any `tools.txt` files you have that define what global functions the agent uses is now replaced by the `global_tools`
-  field in the agent's `config.yaml`. So for example: If your `tools.txt` looks like this:
-  ```text
-  fs_mkdir.sh
-  fs_ls.sh
-  fs_patch.sh
-  fs_cat.sh
-  ```
-  then you need to add the following to your agent's `config.yaml`:
-  ```yaml
-  global_tools:
-    - fs_mkdir.sh
-    - fs_ls.sh
-    - fs_patch.sh
-    - fs_cat.sh
-  ```
-* If you have any bash `tools.sh` that depend on the utility scripts in the `llm-functions` repository, they've been 
-  replaced by built-in utility scripts. So use the following to replace any matching lines in your `tools.sh` files:
-  ```bash
-  ##################
-  ## Scripts file ##
-  ##################
-  ROOT_DIR="${LLM_ROOT_DIR:-$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)}"
-  # replace with
-  source "$LLM_PROMPT_UTILS_FILE"
-  
-  #######################
-  ## guard_path script ##
-  #######################
-  "$ROOT_DIR/utils/guard_path.sh"
-  # replace with
-  guard_path
-  
-  ############################
-  ## guard_operation script ##
-  ############################
-  "$ROOT_DIR/utils/guard_operation.sh"
-  # replace with
-  guard_operation
-  
-  ######################
-  ## patch.awk script ##
-  ######################
-  awk -f "$ROOT_DIR/utils/patch.awk"
-  # replace with
-  patch_file
-  ```
-  
-When you're done with this migration, you should have the following:
-
-* No more `functions/agents` directory
-* No `functions/agents.txt` file (Loki assumes that if the agent directory exists, it is loadable)
-* No `<loki-config-dir>/agents/<agent-name>/tools.txt`
-* No `<loki-config-dir>/agents/<agent-name>/index.yaml`
-
-## Functions
-Loki consolidates much of the `llm-functions` repo functionality into one binary. So this means
-
-* There's no need to have `argc` installed anymore
-* No separate repository to manage
-* No `tools.txt`
-* No `functions.json`
-* No `functions/mcp` directory at all
-* No `functions/scripts`
-
-Here's how to migrate your functions over to Loki from the `llm-functions` repository.
-
-* Copy your AIChat `<aichat-config-dir>/functions` directory into your Loki config directory
-* Delete the following files and directories from your `<loki-config-dir>/functions` directory:
-  * `scripts/`
-  * `agents.txt`
-  * `functions.json`
-  * `Argcfile.sh`
-  * `README.md` (irrelevant now)
-  * `LICENSE` (irrelevant now)
-  * `utils/guard_operation.sh`
-  * `utils/guard_path.sh`
-  * `utils/patch.awk`
-* Everything in `tools.txt` now lives in the global config file under the `visible_tools` setting:
-  ```text
-  get_current_weather.sh
-  execute_command.sh
-  web_search.sh
-  #execute_py_code.py
-  query_jira_issues.sh
-  ```
-  becomes the following in your `<loki-config-dir>/config.yaml`
-  ```yaml
-  visible_tools:
-    - get_current_weather.sh
-    - execute_command.sh
-    - web_search.sh
-    # - web_search.sh
-    - query_jira_issues.sh
-  ```
-* If you've defined a `functions/mcp.json` file, you can leave it alone.
-* Similarly to agents, if you have any bash `tools.sh` that depend on the utility scripts in the `llm-functions` 
-  repository, they've been replaced by built-in utility scripts. So use the following to replace any matching lines in 
-  your `tools.sh` files:
-  ```bash
-  ##################
-  ## Scripts file ##
-  ##################
-  ROOT_DIR="${LLM_ROOT_DIR:-$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)}"
-  # replace with
-  source "$LLM_PROMPT_UTILS_FILE"
-  
-  #######################
-  ## guard_path script ##
-  #######################
-  "$ROOT_DIR/utils/guard_path.sh"
-  # replace with
-  guard_path
-  
-  ############################
-  ## guard_operation script ##
-  ############################
-  "$ROOT_DIR/utils/guard_operation.sh"
-  # replace with
-  guard_operation
-  
-  ######################
-  ## patch.awk script ##
-  ######################
-  awk -f "$ROOT_DIR/utils/patch.awk"
-  # replace with
-  patch_file
-  ```
-  
-Refer to the [custom bash tools docs](./function-calling/CUSTOM-BASH-TOOLS.md) to learn how to compile and test bash 
-tools in Loki without needing to use `argc`.
diff --git a/docs/ENVIRONMENT-VARIABLES.md b/docs/ENVIRONMENT-VARIABLES.md
deleted file mode 100644
index 3bb52e0..0000000
--- a/docs/ENVIRONMENT-VARIABLES.md
+++ /dev/null
@@ -1,112 +0,0 @@
-# Environment Variables
-
-Loki is designed to be highly dynamic and customizable. As a result, Loki utilizes a number of environment variables
-that can be used to modify its behavior at runtime without needing to modify the existing configuration files.
-
-Loki also supports defining environment variables via a `.env` file in the Loki configuration directory. This directory
-varies between systems, so you can find the location of your configuration directory using the following command:
-
-```shell
-loki --info | grep 'config_dir' | awk '{print $2}'
-```
-
-## Quick Links
-<!--toc:start-->
-- [Global Configuration Related Variables](#global-configuration-related-variables)
-- [Client Related Variables](#client-related-variables)
-- [Files and Directory Related Variables](#files-and-directory-related-variables)
-- [Agent Related Variables](#agent-related-variables)
-- [Logging Related Variables](#logging-related-variables)
-- [Miscellaneous Variables](#miscellaneous-variables)
-<!--toc:end-->
-
----
-
-## Global Configuration Related Variables
-All configuration items in the global config file have environment variables that can be overridden at runtime. To see
-all configuration options and more thorough descriptions, refer to the [example config file](../config.example.yaml).
-
-Below are the most commonly used configuration settings and their corresponding environment variables:
-
-| Setting                    | Environment Variable            |
-|----------------------------|---------------------------------|
-| `model`                    | `LOKI_MODEL`                    |
-| `temperature`              | `LOKI_TEMPERATURE`              |
-| `top_p`                    | `LOKI_TOP_P`                    |
-| `stream`                   | `LOKI_STREAM`                   |
-| `save`                     | `LOKI_SAVE`                     |
-| `editor`                   | `LOKI_EDITOR`                   |
-| `wrap`                     | `LOKI_WRAP`                     |
-| `wrap_code`                | `LOKI_WRAP_CODE`                |
-| `save_session`             | `LOKI_SAVE_SESSION`             |
-| `compression_threshold`    | `LOKI_COMPRESSION_THRESHOLD`    |
-| `function_calling_support` | `LOKI_FUNCTION_CALLING_SUPPORT` |
-| `enabled_tools`            | `LOKI_ENABLED_TOOLS`            |
-| `mcp_server_support`       | `LOKI_MCP_SERVER_SUPPORT`       |
-| `enabled_mcp_servers`      | `LOKI_ENABLED_MCP_SERVERS`      |
-| `rag_embedding_model`      | `LOKI_RAG_EMBEDDING_MODEL`      |
-| `rag_reranker_model`       | `LOKI_RAG_RERANKER_MODEL`       |
-| `rag_top_k`                | `LOKI_RAG_TOP_K`                |
-| `rag_chunk_size`           | `LOKI_RAG_CHUNK_SIZE`           |
-| `rag_chunk_overlap`        | `LOKI_RAG_CHUNK_OVERLAP`        |
-| `highlight`                | `LOKI_HIGHLIGHT`                |
-| `theme`                    | `LOKI_THEME`                    |
-| `serve_addr`               | `LOKI_SERVE_ADDR`               |
-| `user_agent`               | `LOKI_USER_AGENT`               |
-| `save_shell_history`       | `LOKI_SAVE_SHELL_HISTORY`       |
-| `sync_models_url`          | `LOKI_SYNC_MODELS_URL`          |
-
-
-## Client Related Variables
-The following environment variables are available for clients in Loki:
-
-| Environment Variable                   | Description                                                                                                                                                                                                                                             |
-|----------------------------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
-| `{client}_API_KEY`                     | For clients that require an API key, you can define the keys either through environment variables or <br>using the [vault](./VAULT.md). The variables are named after the client to which they apply; <br>e.g. `OPENAI_API_KEY`, `GEMINI_API_KEY`, etc. |
-| `LOKI_PLATFORM`                        | Combine with `{client}_API_KEY` to run Loki without a configuration file. <br>This variable is ignored if a configuration file exists.                                                                                                                  |
-| `LOKI_PATCH_{client}_CHAT_COMPLETIONS` | Patch chat completion requests to models on the corresponding client; Can modify the URL, body, <br>or headers.                                                                                                                                         | 
-| `LOKI_SHELL`                           | Specify the shell that Loki should be using when executing commands                                                                                                                                                                                     |
-
-## Files and Directory Related Variables
-You can also customize the files and directories that Loki loads its configuration files from:
-
-| Environment Variable | Description                                                            | Default Value                   |
-|----------------------|------------------------------------------------------------------------|---------------------------------|
-| `LOKI_CONFIG_DIR`    | Customize the location of the Loki configuration directory.            | `<user-config-dir>/loki`        |
-| `LOKI_ENV_FILE`      | Customize the location of the `.env` file to load at startup.          | `<loki-config-dir>/.env`        |
-| `LOKI_CONFIG_FILE`   | Customize the location of the global `config.yaml` configuration file. | `<loki-config-dir>/config.yaml` |
-| `LOKI_ROLES_DIR`     | Customize the location of the `roles` directory.                       | `<loki-config-dir>/roles`       |
-| `LOKI_SESSIONS_DIR`  | Customize the location of the `sessions` directory.                    | `<loki-config-dir>/sessions`    |
-| `LOKI_RAGS_DIR`      | Customize the location of the `rags` directory.                        | `<loki-config-dir>/rags`        |
-| `LOKI_FUNCTIONS_DIR` | Customize the location of the `functions` directory.                   | `<loki-config-dir>/functions`   |
-
-## Agent Related Variables
-You can also customize the location of full agent configurations using the following environment variables:
-
-| Environment Variable         | Description                                                                                                                         |
-|------------------------------|-------------------------------------------------------------------------------------------------------------------------------------|
-| `<AGENT_NAME>_CONFIG_FILE`   | Customize the location of the agent's configuration file; e.g. `SQL_CONFIG_FILE`                                                    |
-| `<AGENT_NAME>_MODEL`         | Customize the `model` used for the agent; e.g `SQL_MODEL`                                                                           |
-| `<AGENT_NAME>_TEMPERATURE`   | Customize the `temperature` used for the agent; e.g. `SQL_TEMPERATURE`                                                              |
-| `<AGENT_NAME>_TOP_P`         | Customize the `top_p` used for the agent; e.g. `SQL_TOP_P`                                                                          |
-| `<AGENT_NAME>_GLOBAL_TOOLS`  | Customize the `global_tools` that are enabled for the agent (a JSON string array); e.g. `SQL_GLOBAL_TOOLS`                          |
-| `<AGENT_NAME>_MCP_SERVERS`   | Customize the `mcp_servers` that are enabled for the agent (a JSON string array); e.g. `SQL_MCP_SERVERS`                            |
-| `<AGENT_NAME>_AGENT_SESSION` | Customize the `agent_session` used with the agent; e.g. `SQL_SESSION`                                                               |
-| `<AGENT_NAME>_INSTRUCTIONS`  | Customize the `instructions` for the agent; e.g. `SQL_INSTRUCTIONS`                                                                 |
-| `<AGENT_NAME>_VARIABLES`     | Customize the `variables` used for the agent (in JSON format of `[{"key1": "value1", "key2": "value2"}]`); <br>e.g. `SQL_VARIABLES` |
-
-## Logging Related Variables
-The following variables can be used to change the log level of Loki or the location of the log file:
-
-| Environment Variable | Description                                 | Default Value                    |
-|----------------------|---------------------------------------------|----------------------------------|
-| `LOKI_LOG_LEVEL`     | Customize the log level of Loki             | `INFO`                           |
-| `LOKI_LOG_FILE`      | Customize the location of the Loki log file | `<user-cache-dir>/loki/loki.log` |
-
-**Pro-Tip:** You can always tail the Loki logs using the `--tail-logs` flag. If you need to disable color output, you
-can also pass the `--disable-log-colors` flag as well.
-
-## Miscellaneous Variables
-| Environment Variable | Description                                                                                      | Default Value |
-|----------------------|--------------------------------------------------------------------------------------------------|---------------|
-| `AUTO_CONFIRM`       | Bypass all `guard_*` checks in the bash prompt helpers; useful for agent composition and routing |               |
\ No newline at end of file
diff --git a/docs/MACROS.md b/docs/MACROS.md
deleted file mode 100644
index a90aafe..0000000
--- a/docs/MACROS.md
+++ /dev/null
@@ -1,103 +0,0 @@
-# Macros
-Macros are essentially Loki "scripts"; that is, a predefined sequence of REPL commands that automate repetitive tasks or
-workflows. Macros run in isolated environments, ensuring that the macros don't inherit any pre-existing role, session, 
-RAG, or agent state, and they will not affect your current context. 
-
-This isolation ensures that your workspace remains clean and unaffected by macro operations.
-
-![Macro Example](./images/macros/macros-example.gif)
-
-For more information on Loki's REPL, refer to the [REPL](./REPL.md) documentation.
-
-## Quick Links
-<!--toc:start-->
-- [Macro Definition](#macro-definition)
-  - [Step Definitions](#step-definitions)
-  - [Macro Variables](#macro-variables)
-- [Built-In Macros](#built-in-macros)
-<!--toc:end-->
-
----
-
-## Macro Definition
-Macros are defined as YAML files in the `macros` subdirectory of your Loki configuration directory. The Loki configuration 
-directory can vary between systems, so to find the location of your macros config directory, you can use the following 
-command:
-
-```shell
-loki --info | grep 'macros_dir' | awk '{print $2}'
-```
-
-Macro definitions are broken into two parts: the `steps` of the macro, and an optional `variables` section that lets 
-users pass in variables to alter the behavior of the macro at runtime.
-
-### Step Definitions
-The step definitions for a macro are straightforward: They are simply the exact commands you would otherwise type in the
-REPL. 
-
-**Example: Macro to generate a git commit message**
-`macros/generate-commit-message.yaml`
-```yaml
-steps:
-  - .file `git diff` -- generate git commit message
-```
-Usage:
-```shell
-$ loki --macro generate-commit-message
->> .file `git diff` -- generate a git commit message
-Add documentation on macros
-```
-
-For a full example configuration, refer to the [example macro configuration file](../config.macro.example.yaml) in the root of this project.
-
-### Macro Variables
-Sometimes it's useful to be able to modify the behavior of a macro at runtime. This is achieved with the `variables` 
-array of the macro definition.
-
-To pass variables to a macro, since they are just Loki scripts, the syntax is the same as it is for any other scripting 
-language: You just pass them alongside your invocation.
-
-**Example:**
-```shell
-$ loki --macro example-variable-macro first_argument second_argument
-```
-
-Each variable in the `variables` array has the following properties:
-* `name` (Required): the name of the variable, which can be referenced in the actual steps of the macro using the 
-  `{{name}}` syntax.
-* `default` (Optional): A default value for the variable if no value is specified. If no default value is defined, and 
-  no value is provided for the variable at runtime, Loki will error out.
-* `rest` (Optional, Boolean): When set to `true`, this variable will collect all remaining arguments passed to the 
-  macro. This behavior is only applicable when the variable is the last variable in the list. By default, this is 
-  `false`.
-
-The `variables` array is order-dependent; that is to say that all arguments passed to the macro are positional. So be
-careful about the ordering if that is important to your macro's invocation.
-
-**Example: Simple variable example to invoke an agent**
-`macros/invoke-agent.yaml`
-```yaml
-variables:
-  - name: agent                 # No default value means this must be defined at runtime
-  - name: args
-    rest: true                  # All remaining arguments to the macro are collected into this variable
-    default: What can you do?   # This is used if no value is passed at runtime
-steps:
-  - .agent {{agent}}
-  - '{{args}}'
-```
-Usage:
-```shell
-$ loki --macro invoke-agent sql
-# or
-$ loki --macro invoke-agent sql What tables are available?
-```
-
-For a full example configuration, refer to the [example macro configuration file](../config.macro.example.yaml) in the root of this project.
-
-## Built-In Macros
-Loki comes packaged with some useful built-in macros. These are also good examples if you're looking for more examples 
-on how to make your own macros, so be sure to check out the [built-in macro definitions](../assets/macros) if you're 
-looking for more examples.
-
-* `generate-commit-message` - Generate a Git commit message based on the staged changes in the current directory
diff --git a/docs/RAG.md b/docs/RAG.md
deleted file mode 100644
index ea3fe9e..0000000
--- a/docs/RAG.md
+++ /dev/null
@@ -1,307 +0,0 @@
-# RAG
-Retrieval Augmented Generation (RAG) is a method of minimizing LLM hallucinations and extending the model's context 
-without consuming a significant portion of the context length. It uses documents and other additional resources that you
-provide to give the model more context for all of your prompts.
-
-Loki has a built-in vector database and full-text search engine to support RAG knowledge bases for your queries.
-
-The generated knowledge bases are stored in the `rag` subdirectory of your Loki configuration directory. The location of 
-this directory varies by system, so you can use the following command to find your RAG directory:
-
-```shell
-loki --info | grep 'rags_dir' | awk '{print $2}'
-```
-
-## Quick Links
-<!--toc:start-->
-- [Usage](#usage)
-  - [Persistent RAG](#persistent-rag)
-  - [Ephemeral RAG](#ephemeral-rag)
-- [How It Works](#how-it-works)
-    - [1. Build](#1-build)
-    - [2. Lookup](#2-lookup)
-    - [2a. Reranking (Optional)](#2a-reranking-optional)
-    - [3. Prompt](#3-prompt)
-- [Supported Document Sources](#supported-document-sources)
-- [Document Loaders](#document-loaders)
-  - [Document Loader Usage](#document-loader-usage)
-- [Advanced Customizations](#advanced-customizations)
-  - [Embedding Model](#embedding-model)
-  - [Reranker](#reranker)
-  - [Chunk Size](#chunk-size)
-    - [Trade-Offs](#chunk-size-trade-offs)
-  - [Chunk Overlap](#chunk-overlap)
-  - [Top K](#top-k)
-    - [Trade-Offs](#top-k-trade-offs)
-  - [RAG Template](#rag-template)
-<!--toc:end-->
-
----
-
-## Usage
-There's two ways to use RAG in Loki: A persistent RAG that can be loaded on-demand for queries, and an ephemeral one for
-adding RAG to a single specific query.
-
-### Persistent RAG
-In the REPL, persistent RAG is initialized via the `.rag` command:
-
-![Persistent RAG example](./images/rag/persistent-rag.gif)
-
-The generated RAG is then saved to the `rag` subdirectory of the Loki configuration, and can then be loaded whenever you
-want that knowledge base via either `.rag <name>` or `loki --rag <RAG>`.
-
-### Ephemeral RAG
-Short-lived RAG that is only used for a single session or query is loaded using `.file`/`--file`.
-
-You can use it to either execute a prompt from a file, or for temporary RAG. The difference is the usage of the `--` 
-separator. If you only specify a filename and no `--` separator, Loki will know to read the file contents and pass them 
-as a query to the model. Otherwise, the `--` separator is read to indicate that this is the end of the list of documents
-to load into the ephemeral RAG, and what follows is the query to pass to the model.
-
-```shell
-.file prompt.md # Read the file as a prompt
-.file %% -- translate the last reply to italian
-.file `git diff` -- generate a commit message
-```
-
-![Ephemeral RAG Example](./images/rag/ephemeral-rag.gif)
-
-Once the session ends, this RAG will no longer be accessible and is only visible to the current session.
-
-#### The `%%` Document Type
-In addition to the usual documents that can be specified for persistent RAG, ephemeral RAG has a special `%%` value. 
-This value references the content of the last reply. So you can use it like this:
-
-```shell
-.file %% -- translate the last reply to italian
-```
-
-The `--` indicates that this is the end of your documents and the beginning of your prompt.
-
-#### The `cmd` Document Type
-Loki also lets you use command outputs for ephemeral RAG input. Simply enclose the command in backticks:
-
-```shell
-.file `git diff` -- generate a commit message
-```
-
-The `--` indicates that this is the end of your documents and the beginning of your prompt.
-
-## How It Works
-#### 1. Build
-When you define RAG, Loki will first "build" the RAG. This means that Loki will consume the documents you specified and
-generate [embeddings](https://huggingface.co/spaces/hesamation/primer-llm-embedding) for that text. This essentially just means that Loki translates the document into a language 
-the LLM can understand.
-
-These embeddings are then stored in an in-memory vector database.
-
-#### 2. Lookup
-Loki sits between you and the model. So when you submit a prompt to the model, before Loki ever sends it, it will first 
-convert your prompt into embeddings (LLM language), and look for relevant snippets of text in the vector database.
-
-Loki then passes the top `n`-snippets of text that it finds in the vector database as additional context to the model
-before your prompt.
-
-#### 2a. Reranking (Optional)
-The lookup for relevant snippets of texts uses embeddings to find text that is semantically similar to your prompt, and 
-returns the top `n`-results. This often works fairly well, however these top results aren't always the most relevant for
-answering the specific query.
-
-Reranking improves these initial results (say, the top 20-100 text snippets) and re-scores them using a more 
-sophisticated model. The reranker model will rank documents by their actual usefulness for answering the query to ensure
-the most relevant context is passed to the model alongside your query.
-
-This reranking model can be customized for each RAG you build in Loki. See the [Custom Reranker](#reranker) section
-below for more details on how to customize this.
-
-#### 3. Prompt
-Finally, the text snippets that were looked up in RAG are passed to the model as additional context to your prompt, 
-giving the model query-specific context to answer your question.
-
-## Supported Document Sources
-Loki supports a number of document sources that can be used for RAG:
-
-| Source                   | Example                                                               | Comments                                                                                                                                                 |
-|--------------------------|-----------------------------------------------------------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------|
-| Files                    | `/tmp/dir1/file1;/tmp/dir1/file2`                                     |                                                                                                                                                          | 
-| Directory                | `/tmp/dir`                                                            | Picks up all files in a directory and all its subdirectories                                                                                             |
-| Directory (extensions}   | `/tmp/dir2/**/*.{md,txt}`                                             | Finds all files in all subdirectories with the specified extensions                                                                                      |
-| Recursive Filename       | `/tmp/*/LOKI.md`                                                      | The following files will be picked up: <br><ul><li>`/tmp/dir1/LOKI.md`</li><li>`/tmp/dir2/subdir1/LOKI.md`</li><li>`/tmp/dir2/subdir2/LOKI.md`</li></ul> |
-| URL                      | `https://www.ohdsi.org/data-standardization/`                         | Downloads and loads the specified webpage into the <br>knowledge base                                                                                    |
-| Recursive URL (Websites) | `https://github.com/OHDSI/Vocabulary-v5.0/wiki/**`                    | Crawls all pages under the given URL and loads them <br>into the knowledge base                                                                          |
-| Document Loader (custom) | `jina:https://cloud.google.com/bigquery/docs/reference/standard-sql/` | Use a custom document loader to parse the given document                                                                                                 | 
-
-## Document Loaders
-Loki only has built-in support for loading text files. But that functionality can be extended to read all kinds of files
-into your knowledge bases. These custom loaders are used by both RAG and for documents specified using the 
-`.file`/`--file` flags.
-
-In the global configuration file, you can specify loaders for specific document types using the `document_loaders` 
-setting. Each loader is defined by specifying a name and then a command that Loki will execute to load the document.
-
-The following variables are interpolated at runtime by Loki and can be used as placeholders in your command definitions:
-* `$1` (Required) - The input file
-* `$2` (Optional) - The output file. If omitted, `stdout` is used as the output destination
-
-**Note:** It is your responsibility to ensure that any tools used to parse documents into text that Loki can read are 
-installed on your system and are available on your `$PATH`. Loki does not have any built-in way of installing 
-dependencies for document loaders for you.
-
-The following are some example loaders:
-```yaml
-document_loaders:
-  pdf: 'pdftotext $1 -'                                                                 # Use pdftotext to convert a PDF file to text
-                                                                                        # (see https://poppler.freedesktop.org for details on how to install pdftotext)
-  docx: 'pandoc --to plain $1'                                                          # Use pandoc to convert a .docx file to text
-                                                                                        # (see https://pandoc.org for details on how to install pandoc)
-  jina: 'curl -fsSL https://r.jina.ai/$1 -H "Authorization: Bearer {{JINA_API_KEY}}'    # Use Jina to translate a website into text;
-                                                                                        # Requires a Jina API key to be added to the Loki vault
-  git: >                                                                                # Use yek to load a git repository into the knowledgebase (https://github.com/bodo-run/yek)
-    sh -c "yek $1 --json | jq 'map({ path: .filename, contents: .content })'" 
-```
-
-### Document Loader Usage
-Once you have your loaders defined, you can specify when Loki should use them by prefixing any RAG file/directory/URI 
-with the name of the loader.
-
-**Example: Load a git repo into RAG**
-![Git Repo Loader Example](./images/rag/git-loader.png)
-
-**Example: Use pdf loader for ephemeral RAG**
-```shell
-$ loki --file pdf:some-file.pdf
-```
-
-## Advanced Customizations
-For those familiar with RAG, Loki exposes a handful of advanced global settings that can be used to tweak your default
-RAG configurations.
-
-### Embedding Model
-When Loki queries your RAG knowledge bases, it needs to first convert your query into embeddings. By default, Loki uses 
-the same embedding model that was used to create the knowledge base in the first place.
-
-This can be customized to any other embedding model available in your configured clients by setting the 
-`rag_embedding_model` setting in your global Loki configuration file:
-
-```yaml
-rag_embedding_model: null        # Specifies the embedding model used for context retrieval
-```
-
-### Reranker
-By default, Loki uses [Reciprocal Rank Fusion (RRF)](https://www.elastic.co/docs/reference/elasticsearch/rest-apis/reciprocal-rank-fusion) to merge vector and keyword search results.
-
-You can change the default reranker model to any other reranking model in your configured clients. To change the default
-reranker model, simply change the value of the `rag_reranker_model` setting in your global configuration file:
-
-```yaml
-rag_reranker_model: null       # By default, 
-```
-
-### Chunk Size
-In the context of RAG, the chunk size is the maximum length of each text chunk (measured in characters) that is created 
-when splitting documents. In Loki, this defaults to `2000` characters.
-
-You can specify a different global default by setting the `rag_chunk_size` property in your global configuration file:
-
-```yaml
-rag_chunk_size: null             # Defines the size of chunks for document processing in characters
-```
-
-#### Chunk Size Trade-Offs
-Keep in mind the following trade-offs when changing the chunk size:
-
-* **Smaller chunks (e.g. 256 characters):** More precise retrieval, better semantic focus, but may lack context or split
-  important information
-* **Larger chunks (e.g. 1024 characters):** More context preserved, fewer chunks to manage, but less precise matching 
-  and more noise in retrieved document
-
-### Chunk Overlap
-Chunk overlap in RAG is the number of characters that overlap between consecutive chunks to maintain continuity. 
-
----
-
-**Example:** If the following sentence is cut off at the end of one chunk
-
-`I was doing fine until someone brought up`
-
-You'll ideally want that full sentence to be picked up at the beginning of the next chunk to make sure the full meaning 
-is captured. So in this example, if your chunk overlap is 42 characters, then the start of the next chunk would look
-like this:
-
-`I was doing fine until someone brought up the game. <next sentence>`
-
----
-
-Often, this value is 10%-20% of the chunk size.
-
-By default, in Loki, this value is 5% the chunk size. You can override this and specify the default chunk overlap (in 
-characters) that Loki should use as a global default by setting the `rag_chunk_overlap` property in the global Loki 
-configuration file:
-
-```yaml
-rag_chunk_overlap: null          # Defines the overlap between chunks
-```
-
-### Top K
-In RAG, `top_k` represents the top `k`-chunks to return from the vector database query. Think of it like if you search 
-something on Google and only care about the top 10 results, that's what you'll use for your context.
-
-In Loki, the default value for this is `5`. You can customize this global default by setting the `rag_top_k` property in
-your global configuration file:
-
-```yaml
-rag_top_k: 5                     # Specifies the number of documents to retrieve for answering queries
-```
-
-#### Top K Trade-Offs
-When customizing this value, keep in mind the following trade-offs so you get the best performance:
-
-* **Lower top_k (e.g. 3):** Faster, more focused context, lower cost, but risks missing relevant information
-* **Higher top_k (e.g. 10):** More comprehensive coverage, but more noise, higher latency, increased token costs, and 
-  potential context window constraints
-
-### RAG Template
-When you use RAG in Loki, after Loki performs the lookup for relevant chunks of text to add as context to your query, it
-will add the retrieved text chunks as context to your query before sending it to the model. The format of this context
-is determined by the `rag_template` setting in your global Loki configuration file.
-
-This template utilizes three placeholders:
-* `__INPUT__`: The user's actual query
-* `__CONTEXT__`: The context retrieved from RAG
-* `__SOURCES__`: A numbered list of the source file paths or URLs that the retrieved context came from
-
-These placeholders are replaced with the corresponding values into the template and make up what's actually passed to 
-the model at query-time. The `__SOURCES__` placeholder enables the model to cite which documents its answer is based on,
-which is especially useful when building knowledge-base assistants that need to provide verifiable references.
-
-The default template that Loki uses is the following:
-
-```text
-Answer the query based on the context while respecting the rules. (user query, some textual context and rules, all inside xml tags)
-
-<context>
-__CONTEXT__
-</context>
-
-<sources>
-__SOURCES__
-</sources>
-
-<rules>
-- If you don't know, just say so.
-- If you are not sure, ask for clarification.
-- Answer in the same language as the user query.
-- If the context appears unreadable or of poor quality, tell the user then answer as best as you can.
-- If the answer is not in the context but you think you know the answer, explain that to the user then answer with your own knowledge.
-- Answer directly and without using xml tags.
-- When using information from the context, cite the relevant source from the <sources> section.
-</rules>
-
-<user_query>
-__INPUT__
-</user_query>
-```
-
-You can customize this template by specifying the `rag_template` setting in your global Loki configuration file. Your 
-template *must* include both the `__INPUT__` and `__CONTEXT__` placeholders in order for it to be valid. The 
-`__SOURCES__` placeholder is optional. If it is omitted, source references will not be included in the prompt.
diff --git a/docs/REPL-PROMPT.md b/docs/REPL-PROMPT.md
deleted file mode 100644
index 01acbb9..0000000
--- a/docs/REPL-PROMPT.md
+++ /dev/null
@@ -1,117 +0,0 @@
-# Customize REPL Prompt
-
-The prompt you see when you start the Loki REPL can be customized to your liking. This is achieved via the `left_prompt`
-and `right_prompt` settings in the global Loki configuration file:
-
-```yaml
-left_prompt: '{color.red}{model}){color.green}{?session {?agent {agent}>}{session}{?role /}}{!session {?agent {agent}>}}{role}{?rag @{rag}}{color.cyan}{?session )}{!session >}{color.reset} '
-right_prompt: '{color.purple}{?session {?consume_tokens {consume_tokens}({consume_percent}%)}{!consume_tokens {consume_tokens}}}{color.reset}'
-```
-
-The location of the global configuration file differs between systems, so you can use the following command to find your
-global configuration file's location:
-
-```shell
-loki --info | grep 'config_file' | awk '{print $2}'
-```
-
-## Quick Links
-<!--toc:start-->
-- [Syntax](#syntax)
-- [Variables](#variables)
-<!--toc:end-->
-
-## Syntax
-The syntax for the prompts consists of plain text and templates contained in `{...}`. The plain text is 
-printed exactly as given. 
-
-The syntax for the templates `{...}` is as follows:
-
-* `{variable}` - Replaced with the value of `variable`
-* `{?variable <template>}` - Evaluate the `<template>` when `variable` is evaluated to `true`
-* `{!variable <template>}` - Evaluate the `<template>` when `variable` is evaluated to `false`
-
-Where a `<template>` is another expression consisting of plain text and/or more special computations inside `{...}`.
-
-Variables are evaluated to also be "truthy"; that is, if a variable is undefined, it is considered to be the exact same
-as if that variable's value was `false`.
-
-**Example 1: Simple Boolean Usage**
-For the prompt `{?variable yay}{!variable boo}`, if `variable=true`, then the output will be
-```
-yay
-```
-
-And if `variable=false`:
-```
-boo
-```
-
-**Example 2: Nested Expressions**
-For the prompt `{?variable {!variable2 yay}>}`, and assuming
-* `variable=true`
-* `variable2=false`
-the output will be
-```
-yay>
-```
-
-If `variable2=true`, the output will be empty.
-
-If `variable=false`, the output will be empty.
-
-## Variables
-The following variables and output modifiers are available to you when you're creating your prompts:
-
-```yaml
-# Model Variables
-model: openai:gpt-4            # The active model's full name
-client_name: openai            # The name of the client serving the active model
-model_name: gpt-4              # The aliased name of the active model
-max_input_tokens: 4096         # The maximum number of input tokens for the active model
-
-# Configuration Variables
-temperature: 1.0               # The temperature for the active model
-top_p: 0.9                     # The top_p for the active model
-dry_run: true                  # Whether the given command is flagged to be a dry run
-stream: false                  # Whether streaming responses are enabled
-save: true                     # Whether shell history is saved
-wrap: 120                      # The number of characters to allow before wrapping around output to the next line
-
-# Role Variables
-role: code                     # The active role 
-
-# Session Variables
-session: temp                  # The name of the active session
-dirty: false                   # Whether the session settings have been updated but not persisted
-consume_tokens: 200            # The number of tokens consumed
-consume_percent: 1%            # The percentage of tokens consumed to the maximum input tokens
-user_messages_len: 0           # The total number of sent user messages 
-
-# RAG Variables
-rag: temp                      # The name of the active RAG
-
-# Agent Variables
-agent: todo-sh                 # The name of the active agent
-
-# ANSI COLORS
-color.reset:
-color.black:
-color.dark_gray:
-color.red:
-color.light_red:
-color.green:
-color.light_green:
-color.yellow:
-color.light_yellow:
-color.blue:
-color.light_blue:
-color.purple:
-color.light_purple:
-color.magenta:
-color.light_magenta:
-color.cyan:
-color.light_cyan:
-color.white:
-color.light_gray:
-```
diff --git a/docs/REPL.md b/docs/REPL.md
deleted file mode 100644
index 2726883..0000000
--- a/docs/REPL.md
+++ /dev/null
@@ -1,260 +0,0 @@
-# Loki REPL Guide
-In addition to being a CLI, Loki also has a built-in REPL (Read-Execute-Print-Loop). This enables users to quickly try
-out prompts, commands, configurations, and everything in between without having to modify the same command every time.
-
-You can enter the REPL by simply typing `loki` without any follow-up flags or arguments.
-## Quick Links
-<!--toc:start-->
-- [Features](#features)
-- [REPL Commands](#repl-commands)
-    - [`.model` - Change the current LLM](#model---change-the-current-llm)
-    - [`.role` - Role management](#role---role-management)
-    - [`.prompt` - Set a temporary role using a prompt](#prompt---set-a-temporary-role-using-a-prompt)
-    - [`.session` - Session management](#session---session-management)
-    - [`.agent` - Chat with an AI agent](#agent---chat-with-an-ai-agent)
-    - [`.rag` - Chat with documents](#rag---chat-with-documents)
-    - [`.macro` - Execute a macro](#macro---execute-a-macro)
-    - [`.file` - Read files and use them as input](#file---read-files-and-use-them-as-input)
-    - [`.vault` - Manage the Loki vault](#vault---manage-the-loki-vault)
-    - [`.continue` - Continue the previous response](#continue---continue-the-previous-response)
-    - [`.regenerate` - Regenerate the last response](#regenerate---regenerate-the-last-response)
-    - [`.copy` - Copy the last response to your clipboard](#copy---copy-the-last-response-to-your-clipboard)
-    - [`.set` - Adjust runtime settings](#set---adjust-runtime-settings)
-    - [`.edit` - Modify configuration files](#edit---modify-configuration-files)
-    - [`.delete` - Delete configurations from Loki](#delete---delete-configurations-from-loki)
-    - [`.info` - Display information about the current mode](#info---display-information-about-the-current-mode)
-    - [`.authenticate` - Authenticate the current model client via OAuth](#authenticate---authenticate-the-current-model-client-via-oauth)
-    - [`.exit` - Exit an agent/role/session/rag or the Loki REPL itself](#exit---exit-an-agentrolesessionrag-or-the-loki-repl-itself)
-    - [`.help` - Show the help guide](#help---show-the-help-guide)
-<!--toc:end-->
-
----
-
-## Features
-The REPL has features that are intended to make your Loki experience as easy and as enjoyable as possible! This includes
-things like
-
-* **Tab Autocompletion:** Every command in the REPL (i.e. everything that starts with a `.`) has fuzzy search auto 
-  completions. 
-  * `.<tab>` to complete REPL commands
-  * `.model <tab>` to complete chat models
-  * `.set <tab>` to complete configuration keys
-  * `.set key <tab>` to complete configuration values
-* **Multi-Line Prompts:** You can also type prompts that span more than one line to help organize your thoughts. This 
-  can be done in the following ways:
-  * `Ctrl-o` to open the current input buffer in your preferred editor (either the value of `editor` or `$EDITOR`)
-  * You can paste multi-line text
-  * You can type `:::` to start multi-line editing, and use `:::` to finish it.
-  * And finally, you can use hotkeys like `{ctrl/shift/alt}+enter` or `ctrl-j` to insert a new line directly in the 
-    REPL.
-* **History Search** Press `ctrl+r` to search the REPL history, and navigate it with `↑↓`
-* **Configurable Keybindings:** You can switch between `emacs` style keybindings or `vi` style keybindings
-* [**Custom REPL Prompt:**](./REPL-PROMPT.md) You can even customize the REPL prompt to display information about the 
-  current context in the prompt
-* **Built-in user interaction tools:** When function calling is enabled in the REPL, the `user__ask`, `user__confirm`,
-  `user__input`, and `user__checkbox` tools are always available for interactive prompts. These are not injected in the
-  one-shot CLI mode.
-
----
-
-## REPL Commands
-All REPL commands begin with a `.` to indicate that they're not part of a prompt. The following list details the 
-commands available in Loki:
-
-### `.model` - Change the current LLM
-When browsing models in the REPL, use the following legend to understand the purpose of each column in the model table:
-```
-openai:gpt-4o     128000 /     4096  |       5 /     15    👁 ⚒ 
-|                 |            |             |       |     |  └─ supports function calling
-|                 |            |             |       |     └─ support vision (multi-modal)
-|                 |            |             |       └─ output price ($/1M)
-|                 |            |             └─ input price ($/1M)
-|                 |            |
-|                 |            └─ max output tokens
-|                 └─ max input tokens
-└─ model id
-```
-![model](./images/repl/model.gif)
-
-For more information about how to add models to Loki, refer to the [clients documentation](./clients/CLIENTS.md).
-
-### `.role` - Role management
-Loki offers the following commands to manage your roles:
-
-| Command      | Description                                                             |
-|--------------|-------------------------------------------------------------------------|
-| `.role`      | Create or switch to a role                                              |
-| `.info role` | Show information about the active role                                  |
-| `.edit role` | Open the active role's configuration file in your preferred text editor |
-| `.save role` | Save the active role and its configurations to a configuration file     |
-| `.exit role` | Exit the active role                                                    |
-
-![role](./images/roles/code.gif)
-
-For more information about roles in Loki and how to build them, refer to the [roles documentation](./ROLES.md).
-
-### `.prompt` - Set a temporary role using a prompt
-If you need to create a temporary role that you want to discard after use, you use `.prompt`. `.prompt`-based roles 
-cannot be persisted to a file and saved.
-
-![prompt-role](./images/roles/prompt-role.gif)
-
-### `.session` - Session management
-Use the following commands to manage sessions in Loki:
-
-| Command             | Description                                                                                 |
-|---------------------|---------------------------------------------------------------------------------------------|
-| `.session`          | Start or switch to a session                                                                |
-| `.empty session`    | Clear all messages for the active session                                                   |
-| `.compress session` | Compress the session messages using the `summarization_prompt` setting in the global config |
-| `.info session`     | Display information about the active session                                                |
-| `.edit session`     | Open the active session's configuration in your preferred text editor                       |
-| `.save session`     | Save the active session to a `session` configuration file                                   |
-| `.exit session`     | Exit the active session                                                                     |
-
-![sessions](./images/sessions/sessions-example.gif)
-
-For more information on sessions and how to use them in Loki, refer to the [sessions documentation](./SESSIONS.md).
-
-### `.agent` - Chat with an AI agent
-Loki lets you build OpenAI GPT-style agents. The following commands let you interact with and manage your agents in 
-Loki:
-
-| Command              | Description                                                                                   |
-|----------------------|-----------------------------------------------------------------------------------------------|
-| `.agent`             | Use an agent                                                                                  |
-| `.starter`           | Display and use conversation starters for the active agent                                    |
-| `.clear todo`        | Clear the todo list and stop auto-continuation (requires `auto_continue: true` on the agent)  |
-| `.edit agent-config` | Open the agent configuration in your preferred text editor                                    |
-| `.info agent`        | Display information about the active agent                                                    |
-| `.exit agent`        | Leave the active agent                                                                        |
-
-![agent](./images/agents/sql.gif)
-
-For more information on agents in Loki and how to create them, refer to the [agents documentation](./AGENTS.md).
-
-### `.rag` - Chat with documents
-RAG (Retrieval Augmented Generation) enables you to load documents into the LLM so you can ask questions about it or 
-complete tasks using the documents as additional context.
-
-| Command          | Description                                                                  |
-|------------------|------------------------------------------------------------------------------|
-| `.rag`           | Initialize or access a RAG                                                   |
-| `.edit rag-docs` | Add or remove documents from the active RAG using your preferred text editor |
-| `.rebuild rag`   | Rebuild the active RAG to accommodate document changes                       |
-| `.sources rag`   | Show a works-cited of the sources used in the last query                     |
-| `.info rag`      | Display information about the active RAG                                     |
-| `.exit rag`      | Exit the active RAG                                                          |
-
-![rag](./images/rag/persistent-rag.gif)
-
-For more information about RAG in Loki and how to utilize it, refer to the [rag documentation](./RAG.md).
-
-### `.macro` - Execute a macro
-Macros in Loki are like "scripts" of commands that can be run in isolated environments; that means they do not use any
-active settings and use the same settings they had when written. They are created/executed using the `.macro <name>` 
-command.
-
-![macro](./images/macros/macros-example.gif)
-
-For more information on macros in Loki and how to create them, refer to the [macros documentation](./MACROS.md).
-
-### `.file` - Read files and use them as input
-Loki lets you specify any number of documents that you can load and use as ephemeral RAG to chat with the LLM. To see
-what files or values you can pass to it, simply run the command `.file` with no arguments:
-
-```shell
-openai:gpt-4o)> .file
-Usage: .file <file|dir|url|%%|cmd>... [-- <text>...]
-```
-
-![ephemeral-rag](./images/rag/ephemeral-rag.gif)
-
-For more information about ephemeral RAG, refer to the [ephemeral RAG documentation](./RAG.md#ephemeral-rag).
-
-### `.vault` - Manage the Loki vault
-The Loki vault lets users store sensitive secrets and credentials securely so that there's no plaintext secrets
-anywhere in your configurations.
-
-![vault](./images/vault/vault-demo.gif)
-
-For more information about the Loki vault, refer to the [vault documentation](./VAULT.md).
-
-### `.continue` - Continue the previous response
-When you have a response that exceeds the context length, you can use the `.continue` command to continue the generation
-of the last response.
-
-![continue](./images/repl/continue.gif)
-
-### `.regenerate` - Regenerate the last response
-If ever your response is interrupted, or you want to try generating it again, you can use the `.regenerate` command to do
-this without having to retype your query:
-
-![regenerate](./images/repl/regenerate.gif)
-
-### `.copy` - Copy the last response to your clipboard
-If you're trying to copy the last response (like copying some code), you can use the `.copy` command to copy the entire
-last response to your system clipboard:
-
-![copy](./images/repl/copy.gif)
-
-### `.set` - Adjust runtime settings
-You can use `.set` to adjust select settings at runtime. This is useful when you're experimenting with settings and want
-to know how they'll affect Loki. To persist the changes you make, be sure to update them in the global configuration 
-file.
-
-![set](./images/repl/set.gif)
-
-### `.edit` - Modify configuration files
-The `.edit` command lets you modify configuration files for the current mode of the REPL. It will open the selected 
-configuration in your preferred text editor. It lets you modify the following configurations:
-
-* `.edit config` - Modify the global configuration
-* `.edit role` - Modify the active role's configuration
-* `.edit session` - Modify the active session's configuration
-* `.edit agent-config` - Modify the active agent's configuration
-* `.edit rag-docs` - Add or remove documents from the active RAG
-
-### `.delete` - Delete configurations from Loki
-The `.delete` command allows you to delete entities in Loki without having to directly run `rm -rf` on the configuration 
-directory or file corresponding to the target entity. You can use it to delete the following entities:
-
-* `.delete role` - Delete select roles
-* `.delete session` - Delete select sessions
-* `.delete macro` - Delete select macros
-* `.delete rag` - Delete select RAGs
-* `.delete agent-data` - Delete select agent's configurations and all tools
-
-### `.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.
-
-The following entities are supported:
-
-| Command         | Description                                                 |
-|-----------------|-------------------------------------------------------------|
-| `.info`         | Display system information (identical to the `--info` flag) |
-| `.info role`    | Display information about the active role                   |
-| `.info session` | Display information about the active session                |
-| `.info agent`   | Display information about the active agent                  |
-| `.info rag`     | Display information about the active RAG                    |
-
-### `.authenticate` - Authenticate the current model client via OAuth
-The `.authenticate` command will start the OAuth flow for the current model client if
-* The client supports OAuth (See the [clients documentation](./clients/CLIENTS.md#providers-that-support-oauth) for supported clients)
-* The client is configured in your Loki configuration to use OAuth via the `auth: oauth` property
-
-### `.exit` - Exit an agent/role/session/rag or the Loki REPL itself
-The `.exit` command is used to move between modes in the Loki REPL.
-
-| Command         | Description             |
-|-----------------|-------------------------|
-| `.exit role`    | Exit the active role    |
-| `.exit session` | Exit the active session |
-| `.exit agent`   | Exit the active agent   |
-| `.exit rag`     | Exit the active RAG     |
-| `.exit`         | Exit the Loki REPL      |
-
-### `.help` - Show the help guide
-Just like with any shell or REPL, you sometimes need a little help and want to know what commands are available to you.
-That's when you use the `.help` command.
diff --git a/docs/ROLES.md b/docs/ROLES.md
deleted file mode 100644
index 2adebcf..0000000
--- a/docs/ROLES.md
+++ /dev/null
@@ -1,266 +0,0 @@
-# Roles
-When customizing the behavior or LLMs, we use roles to "constrain" the responses or behavior of the LLM to whatever
-purpose we desire. 
-
-Think of them kind of like a baby: That baby can grow up to do anything! Be a resume builder, teacher, engineer, etc.
-
-The only difference is that with roles, we're explicitly telling the LLM what we want it to be. Also: the LLM is already
-grown up so we don't have to wait!
-
-![Role demo](./images/roles/code.gif)
-
-## Quick Links
-<!--toc:start-->
-- [Role Definition](#role-definition)
-  - [Metadata Header](#metadata-header)
-  - [Instructions](#instructions)
-  - [Special Case: Metadata Header Only](#special-case-metadata-header-only)
-- [Prompt Types](#prompt-types)
-  - [Embedded Prompts](#embedded-prompts)
-  - [System Prompts](#system-prompts)
-  - [Few-Shot Prompt](#few-shot-prompt)
-- [Built-In Roles](#built-in-roles)
-<!--toc:end-->
-
----
-
-## Role Definition
-Roles in Loki are Markdown files that live in the `roles` directory of your Loki configuration. Loki configuration 
-locations vary between systems, so you can use the following command to find the location of your roles configuration
-directory:
-
-```shell
-loki --info | grep 'roles_dir' | awk '{print $2}'
-```
-
-All role configuration files have two parts: The metadata header, and the instructions.
-
-**Example:** An expert resume builder role that specializes in helping users build and refine their resumes.
-```markdown
----
-# This is the metadata header
-name: resume-builder
-model: openai:gpt-4o
-temperature: 0.2
-top_p: 0
-enabled_tools: fs_ls,fs_cat
-enabled_mcp_servers: github
----
-<!-- This is the instructions -->
-You are an expert resume builder.
-```
-
-To see a full example configuration for a role, refer to the [example role configuration](../config.role.example.md) 
-file in the root of the repo.
-
-### Metadata Header
-The metadata header in all role configuration files is completely optional. It lets you define role-specific settings
-for each role that make the model work the way you want for your role. This includes things like forcing your role to
-always use a specific model, set of tools, and tailoring the hyperparameters of the model for your role.
-
-The header consists of a YAML-formatted list of settings that let you customize the model behavior for your role. These 
-settings sit between `---` separators in your role configuration so Loki knows they're not part of the instructions you 
-want to feed the model.
-
-The following table lists the available configuration settings and their default values (if undefined):
-
-| Setting               | Default                                                        | Description                                                                                                   |
-|-----------------------|----------------------------------------------------------------|---------------------------------------------------------------------------------------------------------------|
-| `name`                | The name of the role markdown file                             | The name of the role                                                                                          |
-| `model`               | Default configured model or currently in-use model (REPL mode) | The preferred model to use with this role                                                                     |
-| `temperature`         | Default `temperature` for the preferred model                  | Controls the creativity and randomness of the model's responses                                               |
-| `top_p`               | Default `top_p` for the preferred model                        | Alternative way to control the model's output diversity, affecting the <br>probability distribution of tokens |
-| `enabled_tools`       | Global setting for `enabled_tools`                             | The tools that this role utilizes                                                                             |
-| `enabled_mcp_servers` | Global setting for `enabled_mcp_servers`                       | The MCP servers that this role utilizes                                                                       |
-| `prompt`              | `null`                                                         | See [Prompt Types](#prompt-types) for detailed usage                                                          | 
-
-### Instructions
-The instructions for a role is what you use to tell the model how you want it to behave. This typically consists of one 
-or two sentences, but can be more. To see some examples, look at the [built-in roles](../assets/roles) to see how they are defined.
-
-**Pro-Tip:** The struggle to create good instructions for a role (or any other kind of instructions for your model) is 
-so common, that Loki comes with a role to help you write instructions for roles! Simply invoke the role to start 
-creating a role with the `create-prompt` role:
-
-```shell
-loki -r create-prompt
-```
-
-### Special Case: Metadata Header Only
-When instructions are defined, the metadata header is optional. However sometimes we want a way to enable specific 
-functions or MCP servers when prompting different models. In this situation, you need only specify the metadata header 
-to just enable these settings as you like.
-
-**Example: Role that enables all filesystem tools**
-`roles/filesystem-functions.md`
-```markdown
----
-enabled_tools: fs_ls,fs_cat,fs_mkdir,fs_patch,fs_write
----
-```
-
-**Example: Role that enables the GitHub MCP server with the ollama:deepseek-r1 model**
-`roles/github.md`
-```markdown
----
-model: ollama:deepseek-r1
-enabled_mcp_servers: github
----
-```
-
-For more examples of this special use case of roles, you can look at the role configuration files for the following
-built-in roles:
-
-* [explain-shell](../assets/roles/explain-shell.md) - Explains cryptic shell commands in natural language
-* [functions](../assets/roles/functions.md) - Enables all available functions (i.e. all globally `visible_functions`)
-* [mcp-servers](../assets/roles/mcp-servers.md) - Enables all available MCP servers
-
-## Special Variables
-Loki has a set of built-in special variables that it will inject into your role's instructions if it finds them in the 
-`{{variable_name}}` syntax. The available special variables are listed below:
-
-| Name            | Description                                               | Example                    |
-|-----------------|-----------------------------------------------------------|----------------------------|
-| `__os__`        | Operating system name                                     | `linux`                    |
-| `__os_family__` | Operating system family                                   | `unix`                     |
-| `__arch__`      | System architecture                                       | `x86_64`                   |
-| `__shell__`     | The current user's default shell                          | `bash`                     |
-| `__locale__`    | The current user's preferred language and region settings | `en-US`                    |
-| `__now__`       | Current timestamp in ISO 8601 format                      | `2025-11-07T10:15:44.268Z` |
-| `__cwd__`       | The current working directory                             | `/tmp`                     |
-
-## Prompt Types
-In Loki, you can also create roles with pre-configured prompts so you can template prompts for your use cases. This is 
-the purpose of the `prompt` field in the role's metadata header. 
-
-There's three types of prompts you can create:
-
-### Embedded Prompts
-Embedded prompts let you create templated prompts for any input given to it. They are ideal for concise, input-driven
-replies from the model. The input that users pass to Loki are injected into your prompt via a `__INPUT__` placeholder in 
-your prompt.
-
-**Example: Role to convert the given input to TOML**
-`roles/convert-to-toml.md`
-```markdown
----
-prompt: convert __INPUT__ to TOML
----
-Convert the given input to TOML format. Exclude any markdown formatting or code blocks and only output code.
-```
-Usage:
-```shell
-$ loki -r json-to-toml '{"test":"hi me"}'
-test = "hi me"
-```
-
-Without the instructions (i.e. the prompt after the metadata header), this role would simply generate the following 
-message for the model:
-
-```json
-[
-  {"role":  "user", "content": "convert {\"test\":\"hi me\"} to TOML"}
-]
-```
-
-### System Prompts
-System prompts let you set the general context of the LLMs behavior. This is no different than other system prompts you
-define in ChatGPT, Claude, Open WebUI, etc.
-
-They are essentially Embedded Prompts without an `__INPUT__` placeholder.
-
-**Example: Role to convert all input words to emoji**
-`roles/emoji.md`
-```markdown
----
-prompt: convert my words to emojis
----
-Convert all given input words into emojis
-```
-Usage:
-```shell
-$ loki -r emoji music joy
-🎵 😊
-```
-
-Without the instructions (i.e. the prompt after the metadata header), this role would simply generate the following 
-messages for the model:
-
-```json
-[
-  {"role": "system", "content":  "convert my words to emojis"},
-  {"role": "user", "content":  "music joy"}
-]
-```
-
-### Few-Shot Prompt
-[Few-Shot prompting](https://www.promptingguide.ai/techniques/fewshot) is a technique to enable in-context learning for LLMs by providing examples in the prompt to steer 
-the model to better performance. In Loki, this is done as an extension of System Prompts.
-
-**Example: Role to output code only**
-`roles/code-generator.md`
-~~~markdown
----
-prompt: |-
-    Output code only without comments or explanations.
-    ### INPUT:
-    async sleep in js
-    ### OUTPUT:
-    ```javascript
-    async function timeout(ms) {
-      return new Promise(resolve => setTimeout(resolve, ms));
-    }
-    ```
----
-Output code only in response to the user's request
-~~~
-Usage:
-~~~shell
-$ loki -r code-generator python add two numbers
-```python
-# Function to add two numbers
-def add_numbers(num1, num2):
-    return num1 + num2
-
-# Example usage
-number1 = 5
-number2 = 7
-
-result = add_numbers(number1, number2)
-print(f"The sum of {number1} and {number2} is {result}.")
-```
-~~~
-
-Without the instructions (i.e. the prompt after the metadata header), this role would simply generate the following
-messages for the model:
-
-```json
-[
-  {"role": "system", "content": "Output code only without comments or explanations."},
-  {"role": "user", "content": "async sleep in js"},
-  {"role": "assistant", "content": "```javascript\nasync function timeout(ms) {\n  return new Promise(resolve => setTimeout(resolve, ms));\n}\n```"},
-  {"role": "user", "content": "python add two numbers"}
-]
-```
-
-## Built-In Roles
-Loki comes packaged with some useful built-in roles. These are also good examples if you're looking for more examples on
-how to make your own roles, so be sure to check out the [built-in role definitions](../assets/roles) if you're looking 
-for more examples.
-
-* `code`: Generates code (used by `loki -c`)
-* `create-prompt`: Creates a prompt based on the user's input
-* `create-title`: Creates 3-6 word titles based on the user's input
-* `explain-shell`: Explains shell commands
-* `functions`: Enable all globally-visible functions
-* `github`: Interact with GitHub using natural language
-* `mcp-servers`: Enables all MCP servers
-* `repo-analyzer`: Ask questions about the code repository in the current working directory
-* `shell`: Convert natural language into shell commands (used by `loki -e`)
-* `slack`: Interact with Slack using natural language
-
-## Temporary Roles
-Loki also enables you to create temporary roles that will be discarded once you're finished with them. This is done via 
-the `.prompt/--prompt` command:
-
-![prompt role](./images/roles/prompt-role.gif)
\ No newline at end of file
diff --git a/docs/SESSIONS.md b/docs/SESSIONS.md
deleted file mode 100644
index 7f683ec..0000000
--- a/docs/SESSIONS.md
+++ /dev/null
@@ -1,44 +0,0 @@
-# Sessions
-By default, Loki does not send back all previous messages in a conversation to the model. This means that each time you 
-query a model, it's essentially a one-off. However, Loki does support chat-like conversations with LLMs via its 
-`sessions` mechanism.
-
-Sessions in Loki enable the familiar conversational interactions with LLMs. This means you can reference previous 
-answers and ask follow-up questions and the model will know what you're referring to.
-
-Sessions can be temporary, or can be saved so you can continue conversations at a later time.
-
-Saved sessions are stored in the `sessions` subdirectory of the Loki configuration directory. The location of the 
-`sessions` directory varies by system, so you can use the following command to find the `sessions` directory if you need 
-it:
-
-```shell
-loki --info | grep 'sessions_dir' | awk '{print $2}'
-```
-
-## Usage
-When you use a session in Loki, you can either persist it or discard it once you're done. Sessions you discard are then
-just considered 'temporary' sessions.
-
-![Persistent Session Example](./images/sessions/sessions-example.gif)
-
-Sessions you persist and then load again later will inherit the same configuration as was used during the last usage of 
-that session. That is to say, if you had certain tools or MCP servers enabled when you were last in that session, they 
-will be available again when you continue that session.
-
-## Configuration
-Session behavior can be configured from the global Loki configuration file. The location of this file varies between 
-systems so you can use the following command to locate it on your system:
-
-```shell
-loki --info | grep 'config_file' | awk '{print $2}'
-```
-
-The following settings are available to customize the default behavior of sessions globally:
-
-| Setting                  | Description                                                                                                                                                                                                                                                                                                                                                            |
-|--------------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
-| `save_session`           | Controls the persistence of the session. <br><ul><li>If `true`, then any time you're in a session, changes will auto-save unless explicitly defined otherwise.</li> <li>If `false`, then any time you're in a session, changes will not auto-save unless explicitly specified otherwise.</li><li>If `null`, Loki will always prompt the user for what to do.</li></ul> |
-| `compression_threshold`  | Defines the token count threshold at which Loki will compress the session to save on the context length                                                                                                                                                                                                                                                                |
-| `summarization_prompt`   | This is the prompt that is used to compress the session up to a given point when compression is triggered                                                                                                                                                                                                                                                              |
-| `summary_context_prompt` | This is the prompt that's used to add the summarized conversation generated by the `summarization_prompt` as context to the model                                                                                                                                                                                                                                      |
diff --git a/docs/SHELL-INTEGRATIONS.md b/docs/SHELL-INTEGRATIONS.md
deleted file mode 100644
index b5353cd..0000000
--- a/docs/SHELL-INTEGRATIONS.md
+++ /dev/null
@@ -1,104 +0,0 @@
-# Loki Shell Integrations
-Loki supports the following integrations with a handful of shell environments to enhance user experience and streamline workflows.
-
-## Tab Completions
-### Dynamic
-Dynamic tab completions are supported by Loki to assist users in quickly completing commands, options, and arguments.
-You can enable it by using the corresponding command for your shell. To enable dynamic tab completions for every
-shell session (i.e. persistently), add the corresponding command to your shell's configuration file as indicated:
-
-```shell
-# Bash
-# (add to: `~/.bashrc`)
-source <(COMPLETE=bash loki) 
-
-# Zsh
-# (add to: `~/.zshrc`)
-source <(COMPLETE=zsh loki)
-
-# Fish
-# (add to: `~/.config/fish/config.fish`)
-source <(COMPLETE=fish loki | psub)
-
-# Elvish
-# (add to: `~/.elvish/rc.elv`)
-eval (E:COMPLETE=elvish loki | slurp)
-
-# PowerShell
-# (add to: `$PROFILE`)
-$env:COMPLETE = "powershell"
-loki | Out-String | Invoke-Expression
-```
-
-At the time of writing, `nushell` is not yet fully supported for dynamic tab completions due to limitations
-in the [`clap`](https://crates.io/crates/clap) crate. However, `nushell` support is being actively developed, and will
-be added in a future release.
-
-Progress on this feature can be tracked in the following issue: [Clap Issue #5840](https://github.com/clap-rs/clap/issues/5840).
-
-### Static
-Static tab completions (i.e. pre-generated completion scripts that are not context aware) can also be generated using the
-`--completions` flag. You can enable static tab completions by using the corresponding commands for your shell. These commands
-will enable them for every shell session (i.e. persistently):
-
-```shell
-# Bash
-echo 'source <(loki --completions bash)' >> ~/.bashrc
-
-# Zsh
-echo 'source <(loki --completions zsh)' >> ~/.zshrc
-
-# Fish
-echo 'loki --completions fish | source' >> ~/.config/fish/config.fish
-
-# Elvish
-echo 'eval (loki --completions elvish | slurp)' >> ~/.elvish/rc.elv
-
-# Nushell
-[[ -d ~/.config/nushell/completions ]] || mkdir -p ~/.config/nushell/completions
-loki --completions nushell | save -f ~/.config/nushell/completions/loki.nu
-echo 'use ~/.config/nushell/completions/cli.nu *' >> ~/.config/nushell/config.nu
-
-# PowerShell
-Add-content $PROFILE "loki --completions powershell | Out-String | Invoke-Expression"
-```
-
-## Shell Assistant
-Loki has an `-e,--execute` flag that allows users to run natural language commands directly from the CLI. It accepts
-natural language input and translates it into executable shell commands.
-
-![Shell Assistant Demo](./images/shell_integrations/assistant.gif)
-
-## Intelligent Command Completions
-Loki also provides shell scripts that bind `Alt-e` to `loki -e "<current command line>"`, allowing users to generate
-commands from natural text directly without invoking the CLI.
-
-For example:
-
-```shell
-$ find all typescript files with more than 100 lines<Alt-e>
-# Gets replaced with
-$ find . -name '*.ts' -type f -exec awk 'NR>100{exit 1}' {} \; -print
-```
-
-To use the CLI helper, add the content of the appropriate integration script for your shell to your shell configuration file:
-* [Bash Integration](../scripts/shell-integration/integration.bash) (add to: `~/.bashrc`)
-* [Zsh Integration](../scripts/shell-integration/integration.zsh) (add to: `~/.zshrc`)
-* [Elvish Integration](../scripts/shell-integration/integration.elv) (add to: `~/.elvish/rc.elv`)
-* [Fish Integration](../scripts/shell-integration/integration.fish) (add to: `~/.config/fish/config.fish`)
-* [Nushell Integration](../scripts/shell-integration/integration.nu) (add to: `~/.config/nushell/config.nu`)
-* [PowerShell Integration](../scripts/shell-integration/integration.ps1) (add to: `$PROFILE`)
-
-## Explain Commands
-In addition to the Shell Assistant, Loki has a built-in role that explains shell commands to you to decipher their 
-language. So if Loki generates a command that you're unsure of what it does, simply pass it to the `explain-shell` role:
-
-![Explain Shell Role](./images/shell_integrations/explain-shell.png)
-
-## Code Generation
-Users can also directly generate code snippets from natural language prompts using the `-c,--code` flag.
-
-![Code Generation Demo](./images/shell_integrations/code-generation.gif)
-
-**Pro Tip:** Pipe the output of the code generation directly into `tee` to ensure the generated code is properly extracted
-from any generated Markdown (i.e. remove any triple backticks).
diff --git a/docs/THEMES.md b/docs/THEMES.md
deleted file mode 100644
index 5d625a3..0000000
--- a/docs/THEMES.md
+++ /dev/null
@@ -1,71 +0,0 @@
-# Theming Loki
-Loki supports customizing the theme via a `.tmTheme` file.
-
-## Setup
-To install a custom theme, download the `.tmTheme` file to the Loki configuration directory and name it `dark.tmTheme`
-or `light.tmTheme`. The location of the Loki configuration directory varies between systems, so you can use the 
-following command to locate it on your system:
-
-```shell
-loki --info | grep 'config_dir' | awk '{print $2}'
-```
-
-## Themes
-### 1337-Scheme
-https://raw.githubusercontent.com/MarkMichos/1337-Scheme/ca6a329cfda8307449d405b70f8fab34b8fd23b5/1337.tmTheme
-![1337-scheme](./images/themes/1337-scheme.png)
-
-### Coldark
-https://raw.githubusercontent.com/ArmandPhilippot/coldark-bat/e44750b2a9629dd12d8ed3ad9fd50c77232170b9/Coldark-Dark.tmTheme
-![coldark](./images/themes/coldark.png)
-
-### Dracula
-https://raw.githubusercontent.com/dracula/sublime/c2de0acf5af67042393cf70de68013153c043656/Dracula.tmTheme
-![dracula](./images/themes/dracula.png)
-
-### GitHub
-https://raw.githubusercontent.com/AlexanderEkdahl/github-sublime-theme/508740b2430c3c3a9e785fc93ee1d7c6f233af53/GitHub.tmTheme
-![github](./images/themes/github.png)
-
-### gruvbox
-#### Dark
-https://raw.githubusercontent.com/subnut/gruvbox-tmTheme/64c47250e54298b91e2cf8d401320009aba9f991/gruvbox-dark.tmTheme
-![gruvbox-dark](./images/themes/gruvbox-dark.png)
-
-#### Light
-https://raw.githubusercontent.com/subnut/gruvbox-tmTheme/64c47250e54298b91e2cf8d401320009aba9f991/gruvbox-light.tmTheme
-![gruvbox-light](./images/themes/gruvbox-light.png)
-
-### OneHalf
-#### Dark
-https://raw.githubusercontent.com/sonph/onehalf/141c775ace6b71992305f144a8ab68e9a8ca4a25/sublimetext/OneHalfDark.tmTheme
-![onehalf-dark](./images/themes/onehalf-dark.png)
-
-#### Light
-https://raw.githubusercontent.com/sonph/onehalf/141c775ace6b71992305f144a8ab68e9a8ca4a25/sublimetext/OneHalfLight.tmTheme
-![onehalf-light](./images/themes/onehalf-light.png)
-
-### Solarized
-#### Dark
-https://raw.githubusercontent.com/braver/Solarized/87e01090cggjf5fb821a234265b3138426ae84900e7/Solarized%20(dark).tmTheme
-![solarized-dark](./images/themes/solarized-dark.png)
-
-#### Light
-https://raw.githubusercontent.com/braver/Solarized/87e01090cf5fb821a234265b3138426ae84900e7/Solarized%20(light).tmTheme
-![solarized-light](./images/themes/solarized-light.png)
-
-### Sublime Snazzy
-https://raw.githubusercontent.com/greggb/sublime-snazzy/70343201f1d7539adbba3c79e2fe81c2559a0431/Sublime%20Snazzy.tmTheme
-![sublime-snazzy](./images/themes/sublime-snazzy.png)
-
-### TwoDark
-https://raw.githubusercontent.com/erremauro/TwoDark/8e0f6fa5b59d196658a22288f519fd8320de4c87/TwoDark.tmTheme
-![twodark](./images/themes/twodark.png)
-
-### Visual Studio Dark+
-https://raw.githubusercontent.com/vidann1/visual-studio-dark-plus/01ee1e8e0dc578f3b4e8c0dbb6aa0279b4a26a40/Visual%20Studio%20Dark%2B.tmTheme
-![visual-studio-dark-plus](./images/themes/visual-studio-dark-plus.png)
-
-### Zenburn
-https://raw.githubusercontent.com/colinta/zenburn/86d4ee7a1f884851a1d21d66249687f527fced32/zenburn.tmTheme
-![zenburn](./images/themes/zenburn.png)
\ No newline at end of file
diff --git a/docs/TODO-SYSTEM.md b/docs/TODO-SYSTEM.md
deleted file mode 100644
index 18a06eb..0000000
--- a/docs/TODO-SYSTEM.md
+++ /dev/null
@@ -1,250 +0,0 @@
-# Todo System
-
-Loki's Todo System is a built-in task tracking feature designed to improve the reliability and effectiveness of LLM agents,
-especially smaller models. It provides structured task management that helps models:
-
-- Break complex tasks into manageable steps
-- Track progress through multistep workflows
-- Automatically continue work until all tasks are complete
-- Avoid forgetting steps or losing context
-
-![Todo System Example](./images/agents/todo-system.png)
-
-## Quick Links
-<!--toc:start-->
-- [Why Use the Todo System?](#why-use-the-todo-system)
-- [How It Works](#how-it-works)
-- [Configuration Options](#configuration-options)
-- [Available Tools](#available-tools)
-- [Auto-Continuation](#auto-continuation)
-- [Best Practices](#best-practices)
-- [Example Workflow](#example-workflow)
-- [Troubleshooting](#troubleshooting)
-<!--toc:end-->
-
-## Why Use the Todo System?
-Smaller language models often struggle with:
-- **Context drift**: Forgetting earlier steps in a multi-step task
-- **Incomplete execution**: Stopping before all work is done
-- **Lack of structure**: Jumping between tasks without clear organization
-
-The Loki Todo System addresses these issues by giving the model explicit tools to plan, track, and verify task completion.
-The system automatically prompts the model to continue when incomplete tasks remain, ensuring work gets finished.
-
-## How It Works
-1. **Planning Phase**: The model initializes a todo list with a goal and adds individual tasks
-2. **Execution Phase**: The model works through tasks, marking each done immediately after completion
-3. **Continuation Phase**: If incomplete tasks remain, the system automatically prompts the model to continue
-4. **Completion**: When all tasks are marked done, the workflow ends naturally
-
-The todo state is preserved across the conversation (and any compressions), and injected into continuation prompts,
-keeping the model focused on remaining work.
-
-## Configuration Options
-The Todo System is configured per-agent in `<loki-config-dir>/agents/<agent-name>/config.yaml`:
-
-| Setting                    | Type    | Default     | Description                                                                     |
-|----------------------------|---------|-------------|---------------------------------------------------------------------------------|
-| `auto_continue`            | boolean | `false`     | Enable the To-Do system for automatic continuation when incomplete todos remain |
-| `max_auto_continues`       | integer | `10`        | Maximum number of automatic continuations before stopping                       |
-| `inject_todo_instructions` | boolean | `true`      | Inject the default todo tool usage instructions into the agent's system prompt  |
-| `continuation_prompt`      | string  | (see below) | Custom prompt used when auto-continuing                                         |
-
-### Example Configuration
-```yaml
-# agents/my-agent/config.yaml
-model: openai:gpt-4o
-auto_continue: true              # Enable auto-continuation
-max_auto_continues: 15           # Allow up to 15 automatic continuations
-inject_todo_instructions: true   # Include todo instructions in system prompt
-continuation_prompt: |           # Optional: customize the continuation prompt
-  [CONTINUE]
-  You have unfinished tasks. Proceed with the next pending item.
-  Do not explain; just execute.
-```
-
-### Default Continuation Prompt
-If `continuation_prompt` is not specified, the following default is used:
-
-```
-[SYSTEM REMINDER - TODO CONTINUATION]
-You have incomplete tasks in your todo list. Continue with the next pending item.
-Call tools immediately. Do not explain what you will do.
-```
-
-## Available Tools
-When `inject_todo_instructions` is enabled (the default), agents have access to four built-in todo management tools:
-
-### `todo__init`
-Initialize a new todo list with a goal. Clears any existing todos.
-
-**Parameters:**
-- `goal` (string, required): The overall goal to achieve when all todos are completed
-
-**Example:**
-```json
-{"goal": "Refactor the authentication module"}
-```
-
-### `todo__add`
-Add a new todo item to the list.
-
-**Parameters:**
-- `task` (string, required): Description of the todo task
-
-**Example:**
-```json
-{"task": "Extract password validation into separate function"}
-```
-
-**Returns:** The assigned task ID
-
-### `todo__done`
-Mark a todo item as done by its ID.
-
-**Parameters:**
-- `id` (integer, required): The ID of the todo item to mark as done
-
-**Example:**
-```json
-{"id": 1}
-```
-
-### `todo__list`
-Display the current todo list with status of each item.
-
-**Parameters:** None
-
-**Returns:** The full todo list with goal, progress, and item statuses
-
-### `todo__clear`
-Clear the entire todo list and reset the goal. Use when the current task has been canceled or invalidated.
-
-**Parameters:** None
-
-**Returns:** Confirmation that the todo list was cleared
-
-### REPL Command: `.clear todo`
-You can also clear the todo list manually from the REPL by typing `.clear todo`. This is useful when:
-- You gave a custom response that changes or cancels the current task
-- The agent is stuck in auto-continuation with stale todos
-- You want to start fresh without leaving and re-entering the agent
-
-**Note:** This command is only available when an agent with `auto_continue: true` is active. If the todo
-system isn't enabled for the current agent, the command will display an error message.
-
-## Auto-Continuation
-When `auto_continue` is enabled, Loki automatically sends a continuation prompt if:
-
-1. The agent's response completes (model stops generating)
-2. There are incomplete tasks in the todo list
-3. The continuation count hasn't exceeded `max_auto_continues`
-4. The response isn't identical to the previous continuation (prevents loops)
-
-### What Gets Injected
-Each continuation prompt includes:
-- The continuation prompt text (default or custom)
-- The current todo list state showing:
-  - The goal
-  - Progress (e.g., "3/5 completed")
-  - Each task with status (✓ done, ○ pending)
-
-**Example continuation context:**
-```
-[SYSTEM REMINDER - TODO CONTINUATION]
-You have incomplete tasks in your todo list. Continue with the next pending item.
-Call tools immediately. Do not explain what you will do.
-
-Goal: Refactor the authentication module
-Progress: 2/4 completed
-  ✓ 1. Extract password validation into separate function
-  ✓ 2. Add unit tests for password validation
-  ○ 3. Update login handler to use new validation
-  ○ 4. Update registration handler to use new validation
-```
-
-### Visual Feedback
-During auto-continuation, you'll see a message in your terminal:
-```
-📋 Auto-continuing (3/10): 2 incomplete todo(s) remain
-```
-
-## Best Practices
-
-### For Agent Developers
-1. **Enable for complex workflows**: Use `auto_continue: true` for agents that handle multistep tasks
-2. **Set reasonable limits**: Adjust `max_auto_continues` based on typical task complexity
-3. **Customize the prompt**: If your agent needs specific continuation behavior, set a custom `continuation_prompt`
-
-### For Model Behavior
-The injected instructions tell models to:
-
-1. **Always create a todo list before starting work**: This ensures planning happens upfront
-2. **Mark each task done immediately after finishing**: Don't batch completions
-3. **Add all planned steps before starting**: Complete planning before execution
-
-### When to Use vs. Skip
-**Use the Todo System when:**
-- Tasks have 3+ distinct steps
-- The model might lose track of progress
-- You want guaranteed completion of all steps
-- Working with smaller/less capable models
-
-**Skip the Todo System when:**
-- Single-step, simple tasks
-- Interactive Q&A sessions
-- The overhead of task tracking isn't worth it
-
-## Example Workflow
-Here's how a typical todo-driven workflow looks:
-
-**User prompt:** "Add input validation to the user registration form"
-
-**Model actions:**
-```
-1. todo__init(goal="Add input validation to user registration form")
-2. todo__add(task="Analyze current registration form fields")
-3. todo__add(task="Create validation rules for email field")
-4. todo__add(task="Create validation rules for password field")
-5. todo__add(task="Implement client-side validation")
-6. todo__add(task="Add server-side validation")
-7. todo__add(task="Write tests for validation logic")
-```
-
-**Model executes first task, then:**
-```
-8. todo__done(id=1)
-9. [Proceeds with task 2...]
-10. todo__done(id=2)
-...
-```
-
-**If model stops with incomplete tasks:**
-- System automatically sends continuation prompt
-- Model sees remaining tasks and continues
-- Repeats until all tasks are done or max continuations reached
-
-## Troubleshooting
-
-### Model Not Using Todo Tools
-- Verify `inject_todo_instructions: true` in your agent config
-- Check that the agent is properly loaded (not just a role)
-- Some models may need explicit prompting to use the tools
-
-### Too Many Continuations
-- Lower `max_auto_continues` to a reasonable limit
-- Check if the model is creating new tasks without completing old ones
-- Ensure tasks are appropriately scoped (not too granular)
-
-### Continuation Loop
-The system detects when a model's response is identical to its previous continuation response and stops
-automatically. If you're seeing loops:
-- The model may be stuck; check if a task is impossible to complete
-- Consider adjusting the `continuation_prompt` to be more directive
-
----
-
-## Additional Docs
-- [Agents](./AGENTS.md) - Full agent configuration guide
-- [Function Calling](./function-calling/TOOLS.md) - How tools work in Loki
-- [Sessions](./SESSIONS.md) - How conversation state is managed
diff --git a/docs/VAULT.md b/docs/VAULT.md
deleted file mode 100644
index 9bb6374..0000000
--- a/docs/VAULT.md
+++ /dev/null
@@ -1,161 +0,0 @@
-# The Loki Vault
-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](./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](./images/vault/vault-repl.png)
-![Loki Vault REPL Commands](./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)
-
diff --git a/docs/clients/CLIENTS.md b/docs/clients/CLIENTS.md
deleted file mode 100644
index 5e98a5b..0000000
--- a/docs/clients/CLIENTS.md
+++ /dev/null
@@ -1,185 +0,0 @@
-# Model Clients
-
-Loki supports a large number of model providers (referred to as `clients` since Loki is a client of these providers). In 
-order to use them, you must configure each one in the `clients` array in the global Loki configuration file.
-
-The location of the global Loki configuration file varies between systems, so you can use the following command to 
-locate your configuration file:
-
-```shell
-loki --info | grep 'config_file' | awk '{print $2}'
-```
-
-## Quick Links
-<!--toc:start-->
-- [Supported Clients](#supported-clients)
-- [Client Configuration](#client-configuration)
-- [Authentication](#authentication)
-- [Extra Settings](#extra-settings)
-<!--toc:end-->
-
----
-
-## Supported Clients
-Loki supports the following model client types:
-
-* Azure AI Foundry
-* AWS Bedrock
-* Anthropic Claude
-* Cohere
-* Google Gemini
-* OpenAI
-* OpenAI-Compatible
-* GCP Vertex AI
-
-In addition to the settings detailed below, each client may have additional settings specific to the provider. Check the
-[example global configuration file](../../config.example.yaml) to verify that your client has all the necessary fields
-defined.
-
-## Client Configuration
-Each client in Loki has the same configuration settings available to them, with only special authentication fields added
-for specific clients as necessary. They are each placed under the `clients` array in your global configuration file:
-
-```yaml
-clients:
-  - name: client1
-    # ... client configuration ...
-  - name: client2
-    # ... client configuration ...
-```
-
-### Metadata
-The client metadata uniquely identifies the client in Loki so you can reference it across your configurations. The 
-available settings are listed below:
-
-| Setting  | Description                                                                                                |
-|----------|------------------------------------------------------------------------------------------------------------|
-| `name`   | The name of the client (e.g. `openai`, `gemini`, etc.)                                                     |
-| `auth`   | Authentication method: `oauth` for OAuth, or omit to use `api_key` (see [Authentication](#authentication)) |
-| `models` | See the [model settings](#model-settings) documentation below                                              |
-| `patch`  | See the [client patch configuration](./PATCHES.md#client-configuration-patches) documentation              |
-| `extra`  | See the [extra settings](#extra-settings) documentation below                                              |
-
-Be sure to also check provider-specific configurations for any extra fields that are added for authentication purposes.
-
-### Model Settings
-The `models` array lists the available models from the model client. Each one has the following settings:
-
-| Setting                     | Required | Model Type  | Description                                                                                                                                                                                                                                   |
-|-----------------------------|----------|-------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
-| `name`                      | *        | `all`       | The name of the model                                                                                                                                                                                                                         |
-| `real_name`                 |          | `all`       | You can define model aliases via the `name` field. However, Loki still needs to know the real name <br>of the model so it can query it. For example: If you have `name: gpt-alias`, then you must <br>also define `real_name: gpt-oss:latest` |
-| `type`                      | *        | `all`       | The type of model. Loki supports only 3 types of models: <ul><li>`chat`</li><li>`embedding`</li><li>`reranker`</li></ul>                                                                                                                      |
-| `input_price`               |          | `all`       | The cost in USD per 1M tokens for each input sequence; Loki will keep track of usage costs if this is defined                                                                                                                                 |
-| `output_price`              |          | `all`       | The cost in USD per 1M tokens of the model output; Loki will keep track of usage costs if this is defined                                                                                                                                     |
-| `patch`                     |          | `all`       | See the [model-specific patch configuration](./PATCHES.md#model-specific-patches) documentation                                                                                                                                               |
-| `max_input_tokens`          |          | `all`       | The maximum number of input tokens for the model                                                                                                                                                                                              |
-| `max_output_tokens`         |          | `chat`      | The maximum number of output tokens for the model                                                                                                                                                                                             |
-| `require_max_tokens`        |          | `chat`      | Whether to enforce the `max_output_tokens` constraint.                                                                                                                                                                                        |
-| `supports_vision`           |          | `chat`      | Indicates if the model supports multimodal queries that would require vision (i.e. image recognition)                                                                                                                                         |
-| `supports_function_calling` |          | `chat`      | Indicates if the model supports function calling                                                                                                                                                                                              |
-| `no_stream`                 |          | `chat`      | Enable or disable streaming API responses                                                                                                                                                                                                     |
-| `no_system_message`         |          | `chat`      | Controls whether the model supports system messages                                                                                                                                                                                           |
-| `system_prompt_prefix`      |          | `chat`      | An additional prefix prompt to add to all system prompts to ensure consistent behavior across all interactions                                                                                                                                |
-| `max_tokens_per_chunk`      |          | `embedding` | The maximum chunk size supported by the embedding model                                                                                                                                                                                       |
-| `default_chunk_size`        |          | `embedding` | The default chunk size to use with the given model                                                                                                                                                                                            |
-| `max_batch_size`            |          | `embedding` | The maximum batch size that the given embedding model supports                                                                                                                                                                                |
-
-## Authentication
-
-Loki clients support two authentication methods: **API keys** and **OAuth**. Each client entry in your configuration
-must use one or the other.
-
-### API Key Authentication
-
-Most clients authenticate using an API key. Simply set the `api_key` field directly or inject it from the
-[Loki vault](../VAULT.md):
-
-```yaml
-clients:
-  - type: claude
-    api_key: '{{ANTHROPIC_API_KEY}}'
-```
-
-API keys can also be provided via environment variables named `{CLIENT_NAME}_API_KEY` (e.g. `OPENAI_API_KEY`,
-`GEMINI_API_KEY`). See the [environment variables documentation](../ENVIRONMENT-VARIABLES.md#client-related-variables)
-for details.
-
-### OAuth Authentication
-
-For [providers that support OAuth](#providers-that-support-oauth), you can authenticate using your existing subscription instead of an API key. This uses
-the OAuth 2.0 PKCE flow.
-
-**Step 1: Configure the client**
-
-Add a client entry with `auth: oauth` and no `api_key`:
-
-```yaml
-clients:
-  - type: claude
-    name: my-claude-oauth
-    auth: oauth
-```
-
-**Step 2: Authenticate**
-
-Run the `--authenticate` flag with the client name:
-
-```sh
-loki --authenticate my-claude-oauth
-```
-
-Or if you have only one OAuth-configured client, you can omit the name:
-
-```sh
-loki --authenticate
-```
-
-Alternatively, you can use the REPL command `.authenticate`.
-
-This opens your browser for the OAuth authorization flow. Depending on the provider, Loki will either start a
-temporary localhost server to capture the callback automatically (e.g. Gemini) or ask you to paste the authorization
-code back into the terminal (e.g. Claude). Loki stores the tokens in `~/.cache/loki/oauth` and automatically refreshes
-them when they expire.
-
-#### Gemini OAuth Note
-Loki uses the following scopes for OAuth with Gemini:
-* https://www.googleapis.com/auth/generative-language.peruserquota 
-* https://www.googleapis.com/auth/userinfo.email
-* https://www.googleapis.com/auth/generative-language.retriever (Sensitive)
-
-Since the `generative-language.retriever` scope is a sensitive scope, Google needs to verify Loki, which requires full
-branding (logo, official website, privacy policy, terms of service, etc.). The Loki app is open-source and is designed 
-to be used as a simple CLI. As such, there's no terms of service or privacy policy associated with it, and thus Google 
-cannot verify Loki. 
-
-So, when you kick off OAuth with Gemini, you may see a page similar to the following:
-![](../images/clients/gemini-oauth-page.png)
-
-Simply click the `Advanced` link and click `Go to Loki (unsafe)` to continue the OAuth flow.
-
-![](../images/clients/gemini-oauth-unverified.png)
-![](../images/clients/gemini-oauth-unverified-allow.png)
-
-**Step 3: Use normally**
-
-Once authenticated, the client works like any other. Loki uses the stored OAuth tokens automatically:
-
-```sh
-loki -m my-claude-oauth:claude-sonnet-4-20250514 "Hello!"
-```
-
-> **Note:** You can have multiple clients for the same provider. For example: you can have one with an API key and 
-> another with OAuth. Use the `name` field to distinguish them.
-
-### Providers That Support OAuth
-* Claude
-* Gemini
-
-## Extra Settings
-Loki also lets you customize some extra settings for interacting with APIs:
-
-| Setting           | Description                                           |
-|-------------------|-------------------------------------------------------|
-| `proxy`           | Set a proxy to use                                    |
-| `connect_timeout` | Set the timeout in seconds for connections to the API |
diff --git a/docs/clients/PATCHES.md b/docs/clients/PATCHES.md
deleted file mode 100644
index 23246b9..0000000
--- a/docs/clients/PATCHES.md
+++ /dev/null
@@ -1,368 +0,0 @@
-# Request Patching in Loki
-Loki provides two mechanisms for modifying API requests sent to LLM providers: **Model-Specific Patches** and 
-**Client Configuration Patches**. These allow you to customize request parameters, headers, and URLs to work around 
-provider quirks or add custom behavior.
-
-## Quick Links
-- [Model-Specific Patches](#model-specific-patches)
-- [Client Configuration Patches](#client-configuration-patches)
-- [Comparison](#comparison)
-- [Common Use Cases](#common-use-cases)
-- [Environment Variable Patches](#environment-variable-patches)
-- [Tips](#tips)
-- [Debugging Patches](#debugging-patches)
-
----
-
-## Model-Specific Patches
-
-### Overview
-Model-specific patches are applied **unconditionally** to a single model. They are useful for handling model-specific 
-quirks or requirements.
-
-### When to Use
-- A specific model requires certain parameters to be set or removed
-- A model needs different default values than other models from the same provider
-- You need to add special configuration for one model only
-
-### Structure
-
-```yaml
-models:
-  - name: model-name
-    type: chat
-    # ... other model properties ...
-    patch:
-      url: "https://custom-endpoint.com"   # Optional: override the API endpoint
-      body:                                # Optional: modify request body
-        <parameter>: <value>               # Add or modify parameters
-        <parameter>: null                  # Remove parameters (set to null)
-      headers:                             # Optional: modify request headers
-        <header-name>: <value>             # Add or modify headers
-        <header-name>: null                # Remove headers (set to null)
-```
-
-### Examples
-
-#### Example 1: Removing Parameters
-OpenAI's o1 models don't support `temperature`, `top_p`, or `max_tokens` parameters. The `patch` removes them:
-
-```yaml
-- name: o4-mini
-  type: chat
-  max_input_tokens: 200000
-  max_output_tokens: 100000
-  supports_function_calling: true
-  patch:
-    body:
-      max_tokens: null      # Remove max_tokens from request
-      temperature: null     # Remove temperature from request
-      top_p: null           # Remove top_p from request
-```
-
-#### Example 2: Setting Required Parameters
-Some models require specific parameters to be set:
-
-```yaml
-- name: o4-mini-high
-  type: chat
-  patch:
-    body:
-      reasoning_effort: high  # Always set reasoning_effort to "high"
-      max_tokens: null
-      temperature: null
-```
-
-#### Example 3: Custom Endpoint
-If a model needs a different API endpoint:
-
-```yaml
-- name: custom-model
-  type: chat
-  patch:
-    url: "https://special-endpoint.example.com/v1/chat"
-```
-
-#### Example 4: Adding Headers
-Add authentication or custom headers:
-
-```yaml
-- name: special-model
-  type: chat
-  patch:
-    headers:
-      X-Custom-Header: "special-value"
-      X-API-Version: "2024-01"
-```
-
-### How It Works
-1. When you use a model, Loki loads its configuration
-2. If the model has a `patch` field, it's **always applied** to every request
-3. The patch modifies the request URL, body, or headers before sending to the API
-4. Parameters set to `null` are **removed** from the request
-
----
-
-## Client Configuration Patches
-
-### Overview
-Client configuration patches allow you to apply customizations to **multiple models** based on 
-**regex pattern matching**. They're defined in your `config.yaml` file and can target specific API types (`chat`, 
-`embeddings`, or `rerank`).
-
-### When to Use
-- You want to apply the same settings to multiple models from a provider
-- You need different configurations for different groups of models
-- You want to override the default client model settings
-- You need environment-specific customizations
-
-### Structure
-
-```yaml
-clients:
-  - type: <client>                      # e.g., gemini, openai, claude
-    # ... client configuration ...
-    patch:
-      chat_completions:                 # For chat models
-        '<regex-pattern>':              # Regex to match model names
-          url: "..."                    # Optional: override endpoint
-          body:                         # Optional: modify request body
-            <parameter>: <value>
-          headers:                      # Optional: modify headers
-            <header>: <value>
-      embeddings:                       # For embedding models
-        '<regex-pattern>':
-          # ... same structure ...
-      rerank:                           # For reranker models
-        '<regex-pattern>':
-          # ... same structure ...
-```
-
-### Pattern Matching
-- Patterns are **regular expressions** that match against the model name
-- Use `.*` to match all models
-- Use specific patterns like `gpt-4.*` to match model families
-- Use `model1|model2` to match multiple specific models
-
-### Examples
-
-#### Example 1: Disable Safety Filters for Gemini Models
-Apply to all Gemini chat models:
-
-```yaml
-clients:
-  - type: gemini
-    api_key: "{{GEMINI_API_KEY}}"
-    patch:
-      chat_completions:
-        '.*':  # Matches all Gemini models
-          body:
-            safetySettings:
-              - category: HARM_CATEGORY_HARASSMENT
-                threshold: BLOCK_NONE
-              - category: HARM_CATEGORY_HATE_SPEECH
-                threshold: BLOCK_NONE
-              - category: HARM_CATEGORY_SEXUALLY_EXPLICIT
-                threshold: BLOCK_NONE
-              - category: HARM_CATEGORY_DANGEROUS_CONTENT
-                threshold: BLOCK_NONE
-```
-
-#### Example 2: Apply Settings to Specific Model Family
-Only apply to GPT-4 models (not GPT-3.5):
-
-```yaml
-clients:
-  - type: openai
-    api_key: "{{OPENAI_API_KEY}}"
-    patch:
-      chat_completions:
-        'gpt-4.*':  # Matches gpt-4, gpt-4-turbo, gpt-4o, etc.
-          body:
-            frequency_penalty: 0.2
-            presence_penalty: 0.1
-```
-
-#### Example 3: Different Settings for Different Models
-Apply different patches based on model name:
-
-```yaml
-clients:
-  - type: openai
-    api_key: "{{OPENAI_API_KEY}}"
-    patch:
-      chat_completions:
-        'gpt-4o':  # Specific model
-          body:
-            temperature: 0.7
-        'gpt-3.5.*':  # Model family
-          body:
-            temperature: 0.9
-            max_tokens: 2000
-```
-
-#### Example 4: Modify Embedding Requests
-Apply to embedding models:
-
-```yaml
-clients:
-  - type: openai
-    api_key: "{{OPENAI_API_KEY}}"
-    patch:
-      embeddings:
-        'text-embedding-.*':  # All text-embedding models
-          body:
-            dimensions: 1536
-            encoding_format: "float"
-```
-
-#### Example 5: Custom Headers for Specific Models
-Add headers only for certain models:
-
-```yaml
-clients:
-  - type: openai-compatible
-    api_base: "https://api.example.com/v1"
-    patch:
-      chat_completions:
-        'custom-model-.*':
-          headers:
-            X-Custom-Auth: "bearer-token"
-            X-Model-Version: "latest"
-```
-
-#### Example 6: Override Endpoint for Specific Models
-Use different endpoints for different model groups:
-
-```yaml
-clients:
-  - type: openai-compatible
-    api_base: "https://default-endpoint.com/v1"
-    patch:
-      chat_completions:
-        'premium-.*':  # Premium models use different endpoint
-          url: "https://premium-endpoint.com/v1/chat/completions"
-```
-
-### How It Works
-1. When making a request, Loki checks if the client has a `patch` configuration
-2. It looks at the appropriate API type (`chat_completions`, `embeddings`, or `rerank`)
-3. For each pattern in that section, it checks if the regex matches the model name
-4. If a match is found, that patch is applied to the request
-5. Only the **first matching pattern** is applied (patterns are processed in order)
-
----
-
-## Comparison
-
-| Feature               | Model-Specific Patch  | Client Configuration Patch          |
-|-----------------------|-----------------------|-------------------------------------|
-| **Scope**             | Single model only     | Multiple models via regex           |
-| **Matching**          | Exact model name      | Regular expression pattern          |
-| **Application**       | Always applied        | Only if pattern matches             |
-| **API Type**          | All APIs              | Separate for chat/embeddings/rerank |
-| **Override**          | Cannot be overridden  | Can override model patch            |
-| **Use Case**          | Model-specific quirks | User preferences & customization    |
-| **Application Order** | Applied first         | Applied second (can override)       |
-
-### Patch Application Order
-When both patches are present, they're applied in this order:
-
-1. **Model-Specific Patch**
-2. **Client Configuration Patch**
-
-This means client configuration patches can override model-specific patches if they modify the same parameters.
-
-## Common Use Cases
-
-### Removing Unsupported Parameters
-Some models don't support standard parameters like `temperature` or `max_tokens`:
-
-**Model Patch**:
-```yaml
-patch:
-  body:
-    temperature: null
-    max_tokens: null
-```
-
-### Adding Provider-Specific Parameters
-Providers often have unique parameters:
-
-**Client Patch**:
-```yaml
-patch:
-  chat_completions:
-    '.*':
-      body:
-        safetySettings: [...]        # Gemini
-        thinking_budget: 10000       # DeepSeek
-        response_format:             # OpenAI
-          type: json_object
-```
-
-### Changing Endpoints
-Use custom or regional endpoints:
-
-**Client Patch**:
-```yaml
-patch:
-  chat_completions:
-    '.*':
-      url: "https://eu-endpoint.example.com/v1/chat"
-```
-
-### Setting Default Values
-Provide defaults for specific models or model families:
-
-**Client Patch**:
-```yaml
-patch:
-  chat_completions:
-    'claude-3-.*':
-      body:
-        max_tokens: 4096
-        temperature: 0.7
-```
-
-### Custom Authentication
-Add special authentication headers:
-
-**Client Patch**:
-```yaml
-patch:
-  chat_completions:
-    '.*':
-      headers:
-        Authorization: "Bearer {{custom_token}}"
-        X-Organization-ID: "org-123"
-```
-
-## Environment Variable Patches
-You can also apply patches via environment variables for temporary overrides:
-
-```bash
-export LLM_PATCH_OPENAI_CHAT_COMPLETIONS='{"gpt-4.*":{"body":{"temperature":0.5}}}'
-```
-
-This takes precedence over client configuration patches but not model-specific patches.
-
-## Tips
-1. **Use model patches** for permanent, model-specific requirements
-2. **Use client patches** for personal preferences or environment-specific settings
-3. **Test regex patterns** carefully
-4. **Set to `null`** to remove parameters, don't just omit them
-5. **Check each model provider's docs** for available parameters and their formats
-6. **Be specific** with patterns to avoid unintended matches
-7. **Remember order matters** - first matching pattern wins for client patches
-8. **Patches merge** - both types can be applied, with client patches overriding model patches
-
-## Debugging Patches
-To see what request is actually being sent, enable debug logging:
-
-```bash
-export RUST_LOG=loki=debug
-loki "your prompt here"
-```
-
-This will show the final request body after all patches are applied.
diff --git a/docs/function-calling/BASH-PROMPT-HELPERS.md b/docs/function-calling/BASH-PROMPT-HELPERS.md
deleted file mode 100644
index bf0c891..0000000
--- a/docs/function-calling/BASH-PROMPT-HELPERS.md
+++ /dev/null
@@ -1,279 +0,0 @@
-# Bash Prompt Helpers
-
-When creating bash based tools, it's often helpful to prompt the user for input or confirmation.
-
-Loki comes pre-packaged with a handful of prompt helpers for your bash-based tools. These helpers
-can be used to prompt the user for various types of input, such as yes/no confirmations,
-text input, and selections from a list.
-
-The utility script is located at `functions/utils/prompt-utils.sh` within your Loki `functions` directory.
-
-The Loki `functions` directory varies between machines, so you can find its location on your system by running the following command in your terminal:
-
-```shell
-loki --info | grep functions_dir | awk '{print $2}'
-```
-
-## Quick Links
-<!--toc:start-->
-- [Import The Prompt Utils Into Your Tools Script](#import-the-prompt-utils-into-your-tools-script)
-- [Included Utility Functions](#included-utility-functions)
-  - [input](#input)
-  - [confirm](#confirm)
-  - [list](#list)
-  - [checkbox](#checkbox)
-  - [password](#password)
-  - [editor](#editor)
-  - [with_validate](#with_validate)
-  - [validate_present](#validate_present)
-  - [detect_os](#detect_os)
-  - [get_opener](#get_opener)
-  - [open_link](#open_link)
-  - [guard_operation](#guard_operation)
-  - [guard_path](#guard_path)
-  - [patch_file](#patch_file)
-  - [error](#error)
-  - [warn](#warn)
-  - [info](#info)
-  - [debug](#debug)
-  - [trace](#trace)
-  - [Colored Output](#colored-output)
-<!--toc:end-->
-
----
-
-## Import The Prompt Utils Into Your Tools Script
-In order to use the bash prompt helpers in your bash scripts, you need to source the provided `prompt-utils.sh` script.
-This script is pre-packaged with Loki and is located [here](../../assets/functions/utils/prompt-utils.sh).
-
-When sourcing the file in your bash script, you use the `LLM_PROMPT_UTILS_FILE` environment variable that automatically 
-populates the `functions/utils/prompt-utils.sh` path for you.
-
-Thus, to properly source and enable all the bash prompt helpers in your Bash tools, add the following prelude to your
-scripts:
-
-```bash
-source "$LLM_PROMPT_UTILS_FILE"
-```
-
-## Included Utility Functions
-Below are the built-in bash prompt helpers that can be used to enhance user interaction with your tool scripts.
-
-### input
-Prompt for text input
-
-![Prompt Utils Input](../images/tools/prompt-utils-input.png)
-
-**Example With Validation:**
-```bash
-text=$(with_validation 'input "Please enter something:"' validate_present 2>/dev/tty)
-```
-
-**Example Without Validation:**
-```bash
-text=$(input "Please enter something:" 2>/dev/tty)
-```
-
-### confirm
-Show a confirm dialog with options for yes/no
-
-![Prompt Utils Confirm](../images/tools/prompt-utils-confirm.png)
-
-**Example:**
-```bash
-confirmed=$(confirm "Do the thing?" 2>/dev/tty)
-if [[ $confirmed == "0" ]]; then echo "No"; else echo "Yes"; fi
-```
-
-### list
-Renders a text based list of options that can be selected by the user using up, down, and enter
-keys that then returns the chosen option.
-
-![Prompt Utils List](../images/tools/prompt-utils-list.png)
-
-**Example:**
-```bash
-options=("one" "two" "three" "four")
-choice=$(list "Select an item" "${options[@]}" 2>/dev/tty)
-echo "Your choice: ${options[$choice]}"
-```
-
-### checkbox
-Render a text based list of options, where multiple options can be selected by the user using down, up,
-and enter keys that then returns the chosen options.
-
-![Prompt Utils Checkbox](../images/tools/prompt-utils-checkbox.png)
-
-**Example:**
-```bash
-options=("one" "two" "three" "four")
-checked=$(checkbox "Select one or more items" "${options[@]}" 2>/dev/tty)
-echo "Your choices: ${checked}"
-```
-
-### password
-Show a password prompt displaying stars for each character typed.
-
-![Prompt Utils Password](../images/tools/prompt-utils-password.png)
-
-**Example With Validation:**
-```bash
-validate_password() {
-  if [[ ${#1} -lt 10 ]]; then
-    echo "Password must be at least 10 characters"
-    exit 1
-  fi
-}
-pass=$(with_validate 'password "Enter your password"' validate_password 2>/dev/tty)
-```
-
-**Example Without Validation:**
-```bash
-pass="$(password "Enter your password:" 2>/dev/tty)"
-```
-
-### editor
-Open the default editor (`$EDITOR`); if none is set, default back to `vi`
-
-**Example:**
-```bash
-text=$(editor "Please enter something in the editor" 2>/dev/tty)
-echo -e "You wrote:\n${text}"
-```
-
-### with_validate
-Evaluate the given prompt command with validation. This prompts the user for input until the
-validation functions returns 0.
-
-![Prompt Utils With-validate](../images/tools/prompt-utils-with-validate.png)
-
-**Example:**
-```bash
-# Using the built-in 'validate_present' validator
-text=$(with_validate 'input "Please enter something and confirm with enter"' validate_present 2>/dev/tty)
-
-# Using a custom validator; e.g. for password
-validate_password() {
-  if [[ ${#1} -lt 10 ]]; then
-    echo "Password needs to be at least 10 characters"
-    exit 1
-  fi
-}
-pass=$(with_validate 'password "Enter random password"' validate_password 2>/dev/tty)
-```
-
-### validate_present
-Validate that the prompt returned a value.
-
-![Prompt Utils Validate-Present](../images/tools/prompt-utils-validate-present.png)
-
-**Example:**
-```bash
-text=$(with_validate 'input "Please enter something and confirm with enter"' validate_present 2>/dev/tty)
-```
-
-### detect_os
-Detect the current OS.
-
-Returns one of the following:
-
-* `solaris`
-* `macos`
-* `linux`
-* `bsd`
-* `windows`
-* `unknown`
-
-**Example:**
-```bash
-detect_os
-```
-
-### get_opener
-Determines the Os-specific file opening command (i.e. the command to open anything)
-
-**Example:**
-```bash
-# Returns 'xdg-open'
-get_opener
-```
-
-### open_link
-Opens the given link in the default browser
-
-**Example:**
-```bash
-open_link https://www.google.com
-```
-
-### guard_operation
-Prompt for permission to run an operation.
-
-Can be disabled by setting the environment variable `AUTO_CONFIRM`.
-
-**Example:**
-```bash
-guard_operation "Execute SQL?"
-_run_sql
-```
-
-### guard_path
-Prompt for permission to perform path operations.
-
-Can be disabled by setting the environment variable `AUTO_CONFIRM`.
-
-**Example:***
-```bash
-guard_path "$target_path" "Remove '$target_path'?"
-rm -rf "$target_path"
-```
-
-### patch_file
-Patch a file and show a diff using the default diff viewer. Uses git diff syntax.
-
-**Example:**
-```bash
-new_contents="$(patch_file "$path" file.patch)"
-```
-
-### error
-Log an error
-
-![Prompt Utils Error](../images/tools/prompt-utils-error.png)
-
-### warn
-Log a warning
-
-![Prompt Utils Warning](../images/tools/prompt-utils-warning.png)
-
-### info
-Log info
-
-![Prompt Utils Info](../images/tools/prompt-utils-info.png)
-
-### debug
-Log a debug message
-
-![Prompt Utils Debug](../images/tools/prompt-utils-debug.png)
-
-### trace
-Log a trace message
-
-![Prompt Utils Trace](../images/tools/prompt-utils-trace.png)
-
-### Colored Output
-The following commands allow users to output text in specific colors.
-
-* `red`
-* `green`
-* `gold`
-* `blue`
-* `magenta`
-* `cyan`
-* `white`
-
-**Example:**
-```bash
-red "This will be red"
-yellow "This will be yellow"
-```
diff --git a/docs/function-calling/CUSTOM-BASH-TOOLS.md b/docs/function-calling/CUSTOM-BASH-TOOLS.md
deleted file mode 100644
index 868d9c4..0000000
--- a/docs/function-calling/CUSTOM-BASH-TOOLS.md
+++ /dev/null
@@ -1,309 +0,0 @@
-# Custom Bash-Based Tools
-Loki supports tools written in Bash. However, they must be written in a special format with special annotations in order 
-for Loki to be able to properly parse and utilize them. This formatting ensures that each Bash script is 
-self-describing, and formatted in such a way that Loki can anticipate how to execute it and what parameters to pass to 
-it. This standardization also lets Loki compile the script into a JSON schema that can be used to inform the LLM about 
-how to use the tool.
-
-Each Bash-based tool must follow a specific structure in order for Loki to be able to properly compile and execute it:
-
-* The tool must be a Bash script with a `.sh` file extension.
-* The script must have the following comments:
-    * `# @describe ...` comment at the top that describes the tool.
-    * `# @env LLM_OUTPUT=/dev/stdout The output path` comment to describe the `LLM_OUTPUT` environment variable. This 
-      syntax in particular assigns `/dev/stdout` as the default value for `LLM_OUTPUT`, so that if it's not set by Loki, 
-      the script will still function properly.
-    * `# @option --option <value>  An example option` comments to define each option that the tool accepts.
-        * Use `--flag` syntax for boolean flags.
-        * Use `--option <value>` syntax for options that accept a value.
-        * Use `--option <value1,value2>` syntax for options that accept multiple values (i.e. arrays).
-* The script must have a `main` function
-* The `main` function must redirect the return value to the `>> "$LLM_OUTPUT"` environment variable.
-    * This is necessary because Loki relies on the `$LLM_OUTPUT` environment variable to capture the output of the tool.
-
-Essentially, you can think of the Bash-based tool script as just a normal Bash script that uses special comments to 
-define a CLI.
-* The `# @env LLM_OUTPUT=/dev/stdout` comment to define the `$LLM_OUTPUT` environment variable (good practice)
-* A `# @describe`
-* And a `main` function that writes to `$LLM_OUTPUT`
-
-The following section explains how you can add parameters to your bash functions and how to test out your scripts.
-
-## Quick Links:
-<!--toc:start-->
-- [Loki Bash Tools Syntax](#loki-bash-tools-syntax)
-  - [Metadata](#metadata)
-  - [Environment Variables](#environment-variables)
-  - [Arguments](#arguments)
-  - [Flags](#flags)
-  - [Options](#options)
-  - [Subcommands (Agents only)](#subcommands-agents-only)
-- [Execute and Test Your Bash Tools](#execute-and-test-your-bash-tools)
-  - [Example](#example)
-- [Prompt Helpers](#prompt-helpers)
-<!--toc:end-->
-
----
-
-## Loki Bash Tools Syntax
-Loki Bash tools work via `@___` annotations that describe specific functionality of a script. The following reference
-explains the general syntax of these annotations and how to use them to create a CLI that Loki can recognize.
-
-Refer to the [Execute and Test Your Bash Tools](#execute-and-test-your-bash-tools) section to learn how to test out your Bash tools
-without needing to go through Loki itself.
-
-It's important to note that any functions prefixed with `_` are not sent to the LLM, so they will be invisible to the 
-LLM at runtime.
-
-### Metadata:
-You can define different metadata about your script to help Loki understand its dependencies and purpose.
-
-```bash
-# Use the `@meta require-tools` annotation to specify any external tools that your script depends on.
-# @meta require-tools jq,yq
-
-# Use the `@describe` annotation to describe the purpose of the script.
-# @describe A tool to interact with things
-```
-
-### Environment Variables:
-```bash
-###########################
-## Environment Variables ##
-###########################
-
-# Use `@env` to define environment variables that the script uses.
-# @env LLM_OUTPUT=/dev/stdout                          The output path, with a default value of '/dev/stdout' if not set.
-# @env OPTIONAL                                        An optional environment variable
-# @env REQUIRED!                                       A required environment variable
-# @env DEFAULT_VALUE=default                           An environment variable with a default value if unset.
-# @env DEFAULT_FROM_FN=`_default_env_fn`               An environment variable with a default value calculated from a function if unset.
-# @env CHOICE[even|odd]                                An environment variable that, if set, must be set to either `even` or `odd`
-# @env CHOICE_WITH_DEFAULT[=even|odd]                  An environment variable that, if set, must be set to either `even` or `odd`, and defaults to `even` when unset
-# @env CHOICE_FROM_FN[`_choice_env_fn`]                An environment variable that, if set, must be set to one of the values returned by the `_choice_fn` function.
-
-# Example variable usage:
-export CHOICE=even
-# ./script.sh
-main() {
-  [[ $CHOICE == "even" ]] || { echo "The value of the 'CHOICE' env var is not 'even'" >> "$LLM_OUTPUT" && exit 1 }
-}
-
-# Loki does not pass functions prefixed with `_` to the LLM, so these are essentially `private` functions
-_default_env_fn() {
-  echo "calculated default env value"
-}
-
-# Loki does not pass functions prefixed with `_` to the LLM, so these are essentially `private` functions
-_choice_env_fn() {
-  echo even
-  echo odd
-}
-```
-
-### Arguments:
-When referencing an argument defined via the `@arg` annotation, you can access its value using the `argc_<argument_name>` variable that
-is created at runtime.
-
-```bash
-###############
-## Arguments ##
-###############
-
-# Use `@arg` To define positional arguments for your script.
-# To reference an argument within your script, use the `argc_<argument_name>` variable.
-# @arg optional                                             Optional argument
-# @arg required!                                            Required argument
-# @arg multi_value*                                         An argument that accepts multiple values (e.g. './script.sh one two three')
-# @arg multi_value_required+                                An argument that is required and accepts multiple values
-# @arg value_notated <VALUE>                                An argument that explicitly specifies the name for documentation (e.g. Usage: ./script.sh [VALUE])
-# @arg default=default                                      An argument with a default value if unset
-# @arg default_from_fn=`_default_arg_fn`                    An argument with a default value calculated from a function if unset
-# @arg choice[even|odd]                                     An argument that, if set, must be set to either `even` or `odd`
-# @arg required_choice+[even|odd]                           An required argument that must be set to either `even` or `odd`
-# @arg default_choice[=even|odd]                            An argument that if unset defaults to 'even', but if set must be either `even` or `odd`
-# @arg multi_value_choice*[even|odd]                        An argument that, if set, must be set to either `even` or `odd`, and accepts multiple values
-# @arg choice_fn[`_choice_arg_fn`]                          An argument that, if set, must be set to one of the values returned by the `_choice_arg_fn` function.
-# @arg choice_fn_no_valid[?`_choice_arg_fn`]                An argument that, if set, can be set to one of the values returned by the `_choice_arg_fn` function,
-#                                                           but does not validate the value.
-# @arg multi_choice_fn*[`_choice_arg_fn`]                   An argument that, if set, must be set to one of the values returned by the `_choice_arg_fn` function,
-#                                                           and accepts multiple values.
-# @arg multi_choice_comma_fn*,[`_choice_arg_fn`]            An argument that, if set, must be set to one of the values returned by the `_choice_arg_fn` function,
-#                                                           and accepts multiple values in the form of a comma-separated list
-# @arg capture_arg~                                         An argument that captures all remaining args passed to the script
-
-# Example usage 1: ./script.sh something_required
-main() {
-  [[ $argc_required == "something_required" ]] || { echo "The value of the 'required' arg is not 'something_required'" >> "$LLM_OUTPUT" && exit 1 }
-}
-
-# Example usage 2: ./script.sh this is a test
-main() {
-  [[ "${argc_multi_value[*]}" == "this is a test" ]] || { echo "The value of the 'multi_value' arg is not 'this is a test'" >> "$LLM_OUTPUT" && exit 1 }
-}
-
-
-# Loki does not pass functions prefixed with `_` to the LLM, so these are essentially `private` functions
-_default_arg_fn() {
-  echo "default arg value"
-}
-
-# Loki does not pass functions prefixed with `_` to the LLM, so these are essentially `private` functions
-_choice_arg_fn() {
-  echo even
-  echo odd
-}
-```
-
-### Flags:
-To access the value of a flag defined via the `@flag` annotation, you can check the value of the `argc_<flag_name>` variable.
-
-```bash
-###########
-## Flags ##
-###########
-
-# Use `@flag` to define boolean flags for your script
-# To reference a flag within your script, use the `argc_<argument_name>` variable.
-# @flag    --bool                              A boolean flag with only a long option
-# @flag -b --bool                              A boolean flag with a short and long option
-# @flag -b                                     A boolean flag with only a short option
-# @flag    --multi*                            A boolean flag that can be used multiple times (e.g. '--multi --multi' will return '2')
-
-# Example usage 1: ./script.sh --bool
-main() {
-  [[ $argc_bool == "1" ]] || { echo "The value of the 'bool' flag is not '1'" >> "$LLM_OUTPUT" && exit 1 }
-}
-
-# Example usage 2: ./script.sh --multi --multi
-main() {
-  [[ $argc_multi == "2" ]] || { echo "The value of the 'multi' flag is not 2" >> "$LLM_OUTPUT" && exit 1 }
-}
-```
-
-### Options:
-To access the value of an option defined via the `@option` annotation, you can check the value of the `argc_<option_name>` variable.
-
-```bash
-#############
-## Options ##
-#############
-
-# Use `@option` to define flags that accept values
-# To reference an option within your script, use the `argc_<argument_name>` variable.
-# @option    --option                                     An option that accepts a value with only a long flag
-# @option -o --option                                     An option that accepts a value with both a short and long flag
-# @option -o                                              An option that accepts a value with only a short flag
-# @option    --required                                   A required option that accepts a value
-# @option    --multi*                                     An option that accepts multiple values                                      
-# @option    --required-multi+                            An option that accepts multiple values and is required
-# @option    --multi-comma*,                              An option that accepts multiple values in the form of a comma-separated list
-# @option    --value <VALUE>                              An option that explicitly specifies the name for documentation (e.g. Usage: ./script.sh --value [VALUE])
-# @option    --two-args <SRC> <DEST>                      An option that accepts two arguments and explicitly names them for documentation
-#                                                         (e.g. Usage: ./script.sh --two-args [SRC] [DEST])
-# @option    --unlimited-args <SRC> <DEST+>               An option that accepts an unlimited number of arguments and explicitly names them for documentation
-#                                                         (e.g. Usage: ./script.sh --unlimited-args [SRC] [DEST ...])
-# @option    --default=default                            An option that has a default value if unset
-# @option    --default-from-fn=`_default_opt_fn`          An option that has a default value calculated from a function if unset
-# @option    --choice[even|odd]                           An option that, if set, must be set to either `even` or `odd`
-# @option    --choice-default[=even|odd]                  An option that, if unset, defaults to `even`, but if set must be either `even` or `odd`
-# @option    --choice-multi*[even|odd]                    An option that, if set, must be set to either `even` or `odd`, and can be specified multiple times
-#                                                         (e.g. ./script.sh --choice-multi even --choice-multi odd)
-# @option    --required-choice-multi+[even|odd]           A required option that, must be set to either `even` or `odd`, and can be specified multiple times
-# @option    --choice-fn[`_choice_opt_fn`]                An option that, if set, must be set to one of the values returned by the `_choice_opt_fn` function.`
-# @option    --choice-fn-no-valid[?`_choice_opt_fn`]      An option that, if set, can be set to one of the values returned by the `_choice_opt_fn` function, with no validation
-# @option    --choice-multi-fn*[`_choice_opt_fn`]         An option that, if set, must be set to one of the values returned by the `_choice_opt_fn` function,
-#                                                         and can be specified multiple times
-# @option    --choice-multi-comma*,[`_choice_opt_fn`]     An option that, if set, must be set to one of the values returned by the `_choice_opt_fn` function,
-#                                                         and is specified as a comma-separated list
-# @option    --capture~                                   An option that captures all remaining arguments passed to the script
-
-# Example usage 1: ./script.sh --option some_value
-main() {
-  [[ $argc_option == "some_value" ]] || { echo "The value of the 'option' option is not 'some_value'" >> "$LLM_OUTPUT" && exit 1 }
-}
-
-# Example usage 2: ./script.sh --multi value1 --multi value2
-main() {
-  [[ "${argc_multi[*]}" == "value1 value2" ]] || { echo "The value of the 'multi' option is not 'value1 value2'" >> "$LLM_OUTPUT" && exit 1 }
-}
-
-
-# Loki does not pass functions prefixed with `_` to the LLM, so these are essentially `private` functions
-_default_opt_fn() {
-  echo "calculated default option value"
-}
-
-# Loki does not pass functions prefixed with `_` to the LLM, so these are essentially `private` functions
-_choice_opt_fn() {
-  echo even
-  echo odd
-}
-```
-
-### Subcommands (Agents only):
-By default, if no `@cmd` annotations are defined, the script's `main` function is treated as the default command.
-However, for agents, there can be many functions defined in one file, and thus it is useful to create subcommands
-to organize your agent's tools.
-
-```bash
-#################
-## Subcommands ##
-#################
-
-# Use the `@cmd` annotation to define subcommands for your script.
-# @cmd List all files
-list() {
-  ls -la >> "$LLM_OUTPUT"
-}
-
-# @cmd Output the contents of the specified file
-# @arg file! The file to output
-cat() {
-  cat "$argc_file" >> "$LLM_OUTPUT"
-}
-
-# Example usage 1: ./script.sh cat myfile.txt
-```
-
-## Execute and Test Your Bash Tools
-Your bash tools are just normal bash scripts stored in the `functions/tools` directory. So you can execute and test them
-directly by first having Loki compile them so all this syntactic sugar means something.
-
-This is achieved via the `loki --build-tools` command.
-
-### Example
-Suppose we want to execute the `functions/tools/get_current_time.sh` script for testing.
-
-We'd first make sure the script is visible in all contexts by ensuring it's in the `visible_tools` array in your global 
-`config.yaml` file. This ensures Loki builds the tool so it's ready to use in any context.
-
-You can find the location of your global `config.yaml` file with the following command:
-
-```shell
-loki --info | grep 'config_file' | awk '{print $2}'
-```
-
-Then, we can instruct Loki to build the script so we can test it out:
-
-```shell
-loki --build-tools
-```
-
-This will add additional boilerplate to the top of the script so that it can be executed directly.
-
-Finally, we can now execute the script:
-
-```bash
-$ ./get_current_time.sh
-Fri Oct 24 05:55:04 PM MDT 2025
-```
-
-## Prompt Helpers
-It's often useful to create interactive prompts for our bash tools so that our tools can get input from
-users.
-
-To accommodate this, Loki provides a set of prompt helper functions that can be referenced and used within your Bash
-tools.
-
-For more information, refer to the [Bash Prompt Helpers documentation](BASH-PROMPT-HELPERS.md).
diff --git a/docs/function-calling/CUSTOM-TOOLS.md b/docs/function-calling/CUSTOM-TOOLS.md
deleted file mode 100644
index 1cabcad..0000000
--- a/docs/function-calling/CUSTOM-TOOLS.md
+++ /dev/null
@@ -1,119 +0,0 @@
-# Custom Tools
-Loki is designed to be as flexible and as customizable as possible. One of the key
-features that enables this flexibility is the ability to create and integrate custom tools
-into your Loki setup. This document provides a guide on how to create and use custom tools within Loki.
-
-## Quick Links
-<!--toc:start-->
-- [Supported Languages](#supported-languages)
-- [Creating a Custom Tool](#creating-a-custom-tool)
-  - [Environment Variables](#environment-variables)
-  - [Custom Bash-Based Tools](#custom-bash-based-tools)
-  - [Custom Python-Based Tools](#custom-python-based-tools)
-<!--toc:end-->
-
----
-
-## Supported Languages
-Loki supports custom tools written in the following programming languages:
-
-* Python
-* Bash
-
-## Creating a Custom Tool
-All tools are created as scripts in either Python or Bash. They should be placed in the `functions/tools` directory.
-The location of the `functions` directory varies between systems, so you can use the following command to locate
-your `functions` directory:
-
-```shell
-loki --info | grep functions_dir | awk '{print $2}'
-```
-
-Once you've created your custom tool, remember to add it to the `visible_tools` array in your global `config.yaml` file 
-to enable it globally. See the [Tools](TOOLS.md#enablingdisabling-global-tools) documentation for more information on how Loki utilizes the 
-`visible_tools` array.
-
-### Environment Variables
-All tools have access to the following environment variables that provide context about the current execution environment:
-
-| Variable             | Description                                                                                                                                |
-|----------------------|--------------------------------------------------------------------------------------------------------------------------------------------|
-| `LLM_OUTPUT`         | Indicates where the output of the tool should go. <br>In certain situations, this may be set to a temporary file instead of `/dev/stdout`. |
-| `LLM_ROOT_DIR`       | The root `config_dir` directory for Loki <br>(i.e. `dirname $(loki --info \| grep config_file \| awk '{print $2}')`)                       |
-| `LLM_TOOL_NAME`      | The name of the tool being executed                                                                                                        |
-| `LLM_TOOL_CACHE_DIR` | A directory specific to the tool for storing cache or temporary files                                                                      |
-
-Loki also searches the tools directory on startup for a `.env` file. If found, all tools in `functions/tools/` will have
-the environment variables defined in the `.env` file available to them.
-
-### Custom Bash-Based Tools
-To create a Bash-based tool, refer to the [custom bash tools documentation](CUSTOM-BASH-TOOLS.md).
-
-### Custom Python-Based Tools
-Loki supports tools written in Python.
-
-Each Python-based tool must follow a specific structure in order for Loki to be able to properly compile and
-execute it:
-
-* The tool must be a Python script with a `.py` file extension.
-* The tool must have a `def run` function that serves as the entry point for the tool.
-* The `run` function must accept parameters that define the inputs for the tool.
-  * Always use type hints to specify the data type of each parameter.
-  * Use `Optional[...]` to indicate optional parameters
-* The `run` function must return a `str`.
-  * For Python, this is automatically written to the `LLM_OUTPUT` environment variable, so there's no need to explicitly
-    write to the environment variable within the function.
-* The function must also have a docstring that describes the tool and its parameters.
-  * Each parameter in the `run` function should be documented in the docstring using the `Args:` section. They should use the following format:
-    * `<parameter_name>: <description>` Where
-      * `<parameter_name>`: The name of the parameter
-      * `<description>`: The description of the parameter
-  * These are *very* important because these descriptions are what's passed to the LLM as the description of the tool,
-    letting the LLM know what the tool does and how to use it.
-
-It's important to note that any functions prefixed with `_` are not sent to the LLM, so they will be invisible to the LLM
-at runtime.
-
-Below is the [`demo_py.py`](../../assets/functions/tools/demo_py.py) tool definition that comes pre-packaged with
-Loki and demonstrates how to create a Python-based tool:
-
-```python
-import os
-from typing import List, Literal, Optional
-
-def run(
-    string: str,
-    string_enum: Literal["foo", "bar"],
-    boolean: bool,
-    integer: int,
-    number: float,
-    array: List[str],
-    string_optional: Optional[str] = None,
-    array_optional: Optional[List[str]] = None,
-):
-    """Demonstrates how to create a tool using Python and how to use comments.
-    Args:
-        string: Define a required string property
-        string_enum: Define a required string property with enum
-        boolean: Define a required boolean property
-        integer: Define a required integer property
-        number: Define a required number property
-        array: Define a required string array property
-        string_optional: Define an optional string property
-        array_optional: Define an optional string array property
-    """
-    output = f"""string: {string}
-string_enum: {string_enum}
-string_optional: {string_optional}
-boolean: {boolean}
-integer: {integer}
-number: {number}
-array: {array}
-array_optional: {array_optional}"""
-
-    for key, value in os.environ.items():
-        if key.startswith("LLM_"):
-            output = f"{output}\n{key}: {value}"
-
-    return output
-```
diff --git a/docs/function-calling/MCP-SERVERS.md b/docs/function-calling/MCP-SERVERS.md
deleted file mode 100644
index 56a3121..0000000
--- a/docs/function-calling/MCP-SERVERS.md
+++ /dev/null
@@ -1,120 +0,0 @@
-# MCP Servers
-[MCP servers](https://modelcontextprotocol.io/docs/getting-started/intro) are essentially APIs designed specifically for LLMs that work like a remote repository of
-tools for the model to access and extend its capabilities.
-
-So think of it like this: Instead of having to write all your own custom tools to interact with different
-services, those services can expose their functionality through an MCP server.
-
-Loki has first-class support for MCP servers.
-
-As mentioned in the [Loki Vault documentation](../VAULT.md), Loki can inject sensitive
-configuration data into your MCP configuration file to ensure that secrets are not hard-coded.
-
-## Quick Links
-<!--toc:start-->
-- [Important Note](#important-note)
-- [MCP Server Configuration](#mcp-server-configuration)
-  - [Secret Injection](#secret-injection)
-- [Default MCP Servers](#default-mcp-servers)
-- [Loki Configuration](#loki-configuration)
-  - [Global Configuration](#global-configuration)
-  - [Role Configuration](#role-configuration)
-  - [Agent Configuration](#agent-configuration)
-<!--toc:end-->
-
----
-
-## Important Note
-Be careful how many MCP servers you enable at one time, regardless of the context. When there is a significant
-number of configured MCP servers, enabling too many MCP servers may overwhelm the context length of a model,
-and quickly exceed token limits.
-
-## MCP Server Configuration
-Loki stores the MCP server configuration file, `functions/mcp.json`, in the `functions` directory. You can find
-this directory using the following command:
-
-```shell
-loki --info | grep functions_dir | awk '{print $2}'
-```
-
-The syntax for the `functions/mcp.json` file is identical to the syntax for MCP server configurations for Claude Desktop.
-So any time you're looking to add a new server, look at the docs for it and find the configuration example for
-Claude desktop. You should be able to use the exact same configuration in your `functions/mcp.json` file.
-
-### Secret Injection
-As mentioned in the [Loki Vault documentation](../VAULT.md), you can use Loki Vault to inject secrets into your MCP configuration file.
-
-In fact, this is why you need to set up your vault before using Loki at all: the built-in MCP configuration
-requires you set up some secrets to use it.
-
-For more information about how to set up your vault and inject secrets, please refer to the [Loki Vault documentation](../VAULT.md).
-
-## Default MCP Servers
-Loki ships with a `functions/mcp.json` file that includes some useful MCP servers:
-
-* [github](https://github.com/github/github-mcp-server) - Interact with GitHub repositories, issues, pull requests, and more.
-* [docker](https://github.com/ckreiling/mcp-server-docker) - Manage your local Docker containers with natural language
-* [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
-
-## Loki Configuration
-MCP servers, like tools, can be used in a handful of contexts:
-* Inside a session
-* Inside a role
-* Inside an agent
-* Globally (i.e. outside a session, role, or agent)
-
-Each of these has a different configuration and interaction with the global configuration.
-
-***Note:** The names of each MCP server referenced in the below configuration properties directly corresponds
-to the names given in the `functions/mcp.json` configuration file. So if you change the name of an MCP server
-from `slack` to `lucem-slack`, then you need to also update your Loki configuration accordingly.
-
-### Global Configuration
-The global configuration is essentially what settings you want to have on by default when
-you just invoke `loki`. (Don't worry about agents, roles, or sessions yet. We'll get to them in a bit).
-
-The following settings are available in the global configuration for MCP servers:
-
-```yaml
-mcp_server_support: true         # Enables or disables MCP server support (globally).
-mapping_mcp_servers:             # Alias for an MCP server or set of servers
-  git: github,gitmcp
-enabled_mcp_servers: null        # Which MCP servers to enable by default (e.g. 'github,slack')
-```
-
-A special note about `enabled_mcp_servers`: a user can set this to `all` to enable all configured MCP servers in the 
-`functions/mcp.json` configuration.
-
-(See the [Configuration Example](../../config.example.yaml) file for an example global configuration with all options.)
-
-When running in REPL-mode, the `mcp_server_support` and `enabled_mcp_servers` settings can be overridden using the 
-`.set` command:
-
-![REPL set MCP servers](../images/mcp/global-settings-overrides-repl.png)
-
-### Role Configuration
-When you create a role, you have the following MCP-related configuration options available to you:
-
-```yaml
-enabled_mcp_servers: github    # Which MCP servers the role uses.
-```
-
-The values for `mapping_mcp_servers` are inherited from the `[global configuration](#global-configuration)`.
-
-For more information about roles, refer to the [Roles](../ROLES.md) documentation.
-
-### Agent Configuration
-When you create an agent, you have the following MCP-related configuration options available to you:
-
-```yaml
-mcp_servers:                 # Which MCP servers the agent uses
-  - github
-  - docker
-```
-
-The values for `mapping_mcp_servers` are inherited from the [global configuration](#global-configuration).
-
-For more information about agents, refer to the [Agents](../AGENTS.md) documentation.
-
-For a full example configuration for an agent, see the [Agent Configuration Example](../../config.agent.example.yaml) file.
diff --git a/docs/function-calling/TOOLS.md b/docs/function-calling/TOOLS.md
deleted file mode 100644
index 7aec07b..0000000
--- a/docs/function-calling/TOOLS.md
+++ /dev/null
@@ -1,190 +0,0 @@
-# Tools
-Loki supports function calling with various tools built-in to enhance LLM capabilities. All built-in tools for Loki
-are located in the [`functions/tools`](../../assets/functions/tools) directory. These tools are also stored in your Loki `functions`
-directory, which is also where you'd go to add more tools.
-
-**Pro Tip:** The Loki functions directory can be found by running the following command:
-```bash
-loki --info | grep functions_dir | awk '{print $2}'
-```
-
-# Quick Links
-<!--toc:start-->
-- [Built-In Tools](#built-in-tools)
-- [Configuration](#configuration)
-  - [Global Configuration](#global-configuration)
-  - [Enabling/Disabling Global Tools](#enablingdisabling-global-tools)
-  - [Role Configuration](#role-configuration)
-  - [Agent Configuration](#agent-configuration)
-- [Tool Error Handling](#tool-error-handling)
-  - [Native/Shell Tool Errors](#nativeshell-tool-errors)
-  - [MCP Errors](#mcp-tool-errors)
-  - [Why Tool Error Handling Is Important](#why-this-matters)
-<!--toc:end-->
-
----
-
-## Built-In Tools
-The following tools are built-in to Loki by default, and their default enabled/disabled status is indicated. More about how tools can
-be enabled/disabled can be found in the [Configuration](#configuration) section below.
-
-| Tool                                                                                | Description                                                                                                                                                                                                                          | Enabled/Disabled |
-|-------------------------------------------------------------------------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|------------------|
-| [`demo_py.py`](../../assets/functions/tools/demo_py.py)                             | Demonstrates how to create a tool using Python and how to use comments.                                                                                                                                                              | 🔴               |
-| [`demo_sh.sh`](../../assets/functions/tools/demo_sh.sh)                             | Demonstrate how to create a tool using Bash and how to use comment tags.                                                                                                                                                             | 🔴               |
-| [`execute_command.sh`](../../assets/functions/tools/execute_command.sh)             | Execute the shell command.                                                                                                                                                                                                           | 🟢               |
-| [`execute_py_code.py`](../../assets/functions/tools/execute_py_code.py)             | Execute the given Python code.                                                                                                                                                                                                       | 🔴               |
-| [`execute_sql_code.sh`](../../assets/functions/tools/execute_sql_code.sh)           | Execute SQL code.                                                                                                                                                                                                                    | 🔴               |
-| [`fetch_url_via_curl.sh`](../../assets/functions/tools/fetch_url_via_curl.sh)       | Extract the content from a given URL using cURL.                                                                                                                                                                                     | 🔴               |
-| [`fetch_url_via_jina.sh`](../../assets/functions/tools/fetch_url_via_jina.sh)       | Extract the content from a given URL using Jina.                                                                                                                                                                                     | 🔴               |
-| [`fs_cat.sh`](../../assets/functions/tools/fs_cat.sh)                               | Read the contents of a file at the specified path.                                                                                                                                                                                   | 🟢               |
-| [`fs_read.sh`](../../assets/functions/tools/fs_read.sh)                             | Controlled reading of the contents of a file at the specified path  with line numbers, offset, and limit to read specific sections.                                                                                                  | 🟢               |
-| [`fs_glob.sh`](../../assets/functions/tools/fs_glob.sh)                             | Find files by glob pattern. Returns matching file paths sorted by modification time.                                                                                                                                                 | 🟢               |
-| [`fs_grep.sh`](../../assets/functions/tools/fs_grep.sh)                             | Search file contents using regular expressions. Returns matching file paths and lines.                                                                                                                                               | 🟢               |
-| [`fs_ls.sh`](../../assets/functions/tools/fs_ls.sh)                                 | List all files and directories at the specified path.                                                                                                                                                                                | 🟢               |
-| [`fs_mkdir.sh`](../../assets/functions/tools/fs_mkdir.sh)                           | Create a new directory at the specified path.                                                                                                                                                                                        | 🔴               |
-| [`fs_patch.sh`](../../assets/functions/tools/fs_patch.sh)                           | Apply a patch to a file at the specified path. <br>This can be used to edit a file without having to rewrite the whole file.                                                                                                         | 🔴               |
-| [`fs_rm.sh`](../../assets/functions/tools/fs_rm.sh)                                 | Remove a file or directory at the specified path.                                                                                                                                                                                    | 🔴               |
-| [`fs_write.sh`](../../assets/functions/tools/fs_write.sh)                           | Write the full file contents to a file at the specified path.                                                                                                                                                                        | 🟢               |
-| [`get_current_time.sh`](../../assets/functions/tools/get_current_time.sh)           | Get the current time.                                                                                                                                                                                                                | 🟢               |
-| [`get_current_weather.py`](../../assets/functions/tools/get_current_weather.py)     | Get the current weather in a given location (Python implementation)                                                                                                                                                                  | 🔴               |
-| [`get_current_weather.sh`](../../assets/functions/tools/get_current_weather.sh)     | Get the current weather in a given location.                                                                                                                                                                                         | 🟢               |
-| [`query_jira_issues.sh`](../../assets/functions/tools/query_jira_issues.sh)         | Query for jira issues using a Jira Query Language (JQL) query.                                                                                                                                                                       | 🟢               |
-| [`search_arxiv.sh`](../../assets/functions/tools/search_arxiv.sh)                   | Search arXiv using the given search query and return the top papers.                                                                                                                                                                 | 🔴               |
-| [`search_wikipedia.sh`](../../assets/functions/tools/search_wikipedia.sh)           | Search Wikipedia using the given search query. <br>Use it to get detailed information about a public figure, interpretation of a <br>complex scientific concept or in-depth connectivity of a significant historical <br>event, etc. | 🔴               |
-| [`search_wolframalpha.sh`](../../assets/functions/tools/search_wolframalpha.sh)     | Get an answer to a question using Wolfram Alpha. The input query should be <br>in English. Use it to answer user questions that require computation, detailed <br>facts, data analysis, or complex queries.                          | 🔴               |
-| [`send_mail.sh`](../../assets/functions/tools/send_mail.sh)                         | Send an email.                                                                                                                                                                                                                       | 🔴               |
-| [`send_twilio.sh`](../../assets/functions/tools/send_twilio.sh)                     | Send SMS or Twilio Messaging Channels messages using the Twilio API.                                                                                                                                                                 | 🔴               |
-| [`web_search_loki.sh`](../../assets/functions/tools/web_search_loki.sh)             | Perform a web search to get up-to-date information or additional context. <br>Use this when you need current information or feel a search could provide <br>a better answer.                                                         | 🔴               |
-| [`web_search_perplexity.sh`](../../assets/functions/tools/web_search_perplexity.sh) | Perform a web search using the Perplexity API to get up-to-date <br>information or additional context. Use this when you need current <br>information or feel a search could provide a better answer.                                | 🔴               |
-| [`web_search_tavily.sh`](../../assets/functions/tools/web_search_tavily.sh)         | Perform a web search using the Tavily API to get up-to-date <br>information or additional context. Use this when you need current <br>information or feel a search could provide a better answer.                                    | 🔴               |
-
-Details on what configuration, if any, is necessary for each tool can be found inside the tool file definition itself.
-
-## Configuration
-Tools can be used in a handful of contexts:
-* Inside a session
-* Inside a role
-* Inside an agent
-* Globally (i.e. outside a session, role, or agent)
-
-Each of these has a different configuration and interaction with the global configuration.
-
-**Note:** For each configuration property listed below, the functions that are mentioned *only*
-correspond to the tool scripts located in your Loki `functions/tools` directory.
-
-### Global Configuration
-The global configuration is essentially what settings you want to have on by default when
-you just invoke `loki`. (Don't worry about agents, roles, or sessions yet. We'll get to them in a bit).
-
-The following settings are available in the global configuration for tools:
-
-```yaml
-function_calling_support: true   # Enables or disables function calling in any context
-mapping_tools:                   # Alias for a tool or toolset
-  fs: 'fs_cat,fs_ls,fs_mkdir,fs_rm,fs_write'
-enabled_tools: null              # Which tools to use by default. (e.g. 'fs,web_search_loki')
-visible_tools:                   # Which tools are visible to be compiled (and are thus able to be defined in 'enabled_tools')
-  #  - demo_py.py
-  - execute_command.sh
-```
-
-A special not about `enabled_tools`: a user can set this to `all` to enable all available tools listed in the 
-`visible_tools` section of your Loki `config.yaml` file.
-See the [Enabling/Disabling Global Tools](#enablingdisabling-global-tools) section below for more information on how tools
-are globally enabled/disabled globally.
-
-(See the [Configuration Example](../../config.example.yaml) file for an example global configuration with all options.)
-
-When running in REPL-mode, the `function_calling_support` and `enabled_tools` settings can be overridden using the 
-`.set` command:
-
-![REPL set function calling](../images/tools/global-settings-overrides-repl.png)
-
-You'll notice that mentioned above, some tools are disabled while others are enabled. How is that determined?
-
-### Enabling/Disabling Global Tools
-The configured tools are enabled/disabled by looking at the values in the `visible_tools` array in your `config.yaml` 
-file. This file is located in the root of the Loki `config` directory. The location of the Loki config varies by system,
-so your config file can be found using the following command:
-
-```bash
-loki --info | grep 'config_file' | awk '{print $2}'
-```
-
-Each line in the `visible_tools` array lists a tool.
-
-If that line is commented out, then that tool is not included in the global tool set, and cannot be used in any context;
-This means it will not be built, and even if enabled under `enabled_tools`, it still will not be available in any 
-context.
-
-### Role Configuration
-When you create a role, you have the following global tool-related configuration options available to you:
-
-```yaml
-enabled_tools: query_jira_issues    # Which tools the role uses.
-```
-
-The values for `mapping_tools` are inherited from the [global configuration](#global-configuration).
-
-For more information about roles, refer to the [Roles](../ROLES.md) documentation.
-
-### Agent Configuration
-When you create an agent, you have the following global tool-related configuration options available to you:
-
-```yaml
-global_tools:                 # Which global tools the agent uses
-  - query_jira_issues.sh
-  - fs_cat.sh
-  - fs_ls.sh
-```
-
-The values for `mapping_tools` are inherited from the [global configuration](#global-configuration).
-
-For more information about agents, refer to the [Agents](../AGENTS.md) documentation.
-
-For a full example configuration for an agent, see the [Agent Configuration Example](../../config.agent.example.yaml) file.
-
----
-
-## Tool Error Handling
-When tools fail, Loki captures error information and passes it back to the model so it can diagnose issues and 
-potentially retry or adjust its approach.
-
-### Native/Shell Tool Errors
-When a shell-based tool exits with a non-zero exit code, the model receives:
-
-```json
-{
-  "tool_call_error": "Tool call 'my_tool' exited with code 1",
-  "stderr": "Error: file not found: config.json"
-}
-```
-
-The `stderr` field contains the actual error output from the tool, giving the model context about what went wrong.
-If the tool produces no stderr output, only the `tool_call_error` field is included.
-
-**Note:** Tool stdout streams to your terminal in real-time so you can see progress. Only stderr is captured for 
-error reporting.
-
-### MCP Tool Errors
-When an MCP (Model Context Protocol) tool invocation fails due to connection issues, timeouts, or server errors,
-the model receives:
-
-```json
-{
-  "tool_call_error": "MCP tool invocation failed: connection refused"
-}
-```
-
-This allows the model to understand that an external service failed and take appropriate action (retry, use an 
-alternative approach, or inform the user).
-
-### Why This Matters
-Without proper error propagation, models would only know that "something went wrong" without understanding *what*
-went wrong. By including stderr output and detailed error messages, models can:
-
-- Diagnose the root cause of failures
-- Suggest fixes (e.g., "the file doesn't exist, should I create it?")
-- Retry with corrected parameters
-- Fall back to alternative approaches when appropriate
diff --git a/docs/images/agents/conversation-starters.gif b/docs/images/agents/conversation-starters.gif
deleted file mode 100644
index 594a663..0000000
Binary files a/docs/images/agents/conversation-starters.gif and /dev/null differ
diff --git a/docs/images/agents/sql.gif b/docs/images/agents/sql.gif
deleted file mode 100644
index b7fbd38..0000000
Binary files a/docs/images/agents/sql.gif and /dev/null differ
diff --git a/docs/images/agents/todo-system.png b/docs/images/agents/todo-system.png
deleted file mode 100644
index e66212a..0000000
Binary files a/docs/images/agents/todo-system.png and /dev/null differ
diff --git a/docs/images/macros/macros-example.gif b/docs/images/macros/macros-example.gif
deleted file mode 100644
index 005beb0..0000000
Binary files a/docs/images/macros/macros-example.gif and /dev/null differ
diff --git a/docs/images/mcp/global-settings-overrides-repl.png b/docs/images/mcp/global-settings-overrides-repl.png
deleted file mode 100644
index 00adbcf..0000000
Binary files a/docs/images/mcp/global-settings-overrides-repl.png and /dev/null differ
diff --git a/docs/images/rag/ephemeral-rag.gif b/docs/images/rag/ephemeral-rag.gif
deleted file mode 100644
index fb31d62..0000000
Binary files a/docs/images/rag/ephemeral-rag.gif and /dev/null differ
diff --git a/docs/images/rag/git-loader.png b/docs/images/rag/git-loader.png
deleted file mode 100644
index b6905f8..0000000
Binary files a/docs/images/rag/git-loader.png and /dev/null differ
diff --git a/docs/images/rag/persistent-rag.gif b/docs/images/rag/persistent-rag.gif
deleted file mode 100644
index 6459312..0000000
Binary files a/docs/images/rag/persistent-rag.gif and /dev/null differ
diff --git a/docs/images/repl/continue.gif b/docs/images/repl/continue.gif
deleted file mode 100644
index 3fae887..0000000
Binary files a/docs/images/repl/continue.gif and /dev/null differ
diff --git a/docs/images/repl/copy.gif b/docs/images/repl/copy.gif
deleted file mode 100644
index ad86371..0000000
Binary files a/docs/images/repl/copy.gif and /dev/null differ
diff --git a/docs/images/repl/model.gif b/docs/images/repl/model.gif
deleted file mode 100644
index f64bfd7..0000000
Binary files a/docs/images/repl/model.gif and /dev/null differ
diff --git a/docs/images/repl/regenerate.gif b/docs/images/repl/regenerate.gif
deleted file mode 100644
index ad798cc..0000000
Binary files a/docs/images/repl/regenerate.gif and /dev/null differ
diff --git a/docs/images/repl/set.gif b/docs/images/repl/set.gif
deleted file mode 100644
index 3882417..0000000
Binary files a/docs/images/repl/set.gif and /dev/null differ
diff --git a/docs/images/roles/code.gif b/docs/images/roles/code.gif
deleted file mode 100644
index 18c1d69..0000000
Binary files a/docs/images/roles/code.gif and /dev/null differ
diff --git a/docs/images/roles/prompt-role.gif b/docs/images/roles/prompt-role.gif
deleted file mode 100644
index 54be216..0000000
Binary files a/docs/images/roles/prompt-role.gif and /dev/null differ
diff --git a/docs/images/sessions/sessions-example.gif b/docs/images/sessions/sessions-example.gif
deleted file mode 100644
index b4eef8a..0000000
Binary files a/docs/images/sessions/sessions-example.gif and /dev/null differ
diff --git a/docs/images/shell_integrations/assistant.gif b/docs/images/shell_integrations/assistant.gif
deleted file mode 100644
index 511730d..0000000
Binary files a/docs/images/shell_integrations/assistant.gif and /dev/null differ
diff --git a/docs/images/shell_integrations/code-generation.gif b/docs/images/shell_integrations/code-generation.gif
deleted file mode 100644
index a757bff..0000000
Binary files a/docs/images/shell_integrations/code-generation.gif and /dev/null differ
diff --git a/docs/images/shell_integrations/explain-shell.png b/docs/images/shell_integrations/explain-shell.png
deleted file mode 100644
index 84690e4..0000000
Binary files a/docs/images/shell_integrations/explain-shell.png and /dev/null differ
diff --git a/docs/images/themes/1337-scheme.png b/docs/images/themes/1337-scheme.png
deleted file mode 100644
index 6ad2e87..0000000
Binary files a/docs/images/themes/1337-scheme.png and /dev/null differ
diff --git a/docs/images/themes/coldark.png b/docs/images/themes/coldark.png
deleted file mode 100644
index 2501fc5..0000000
Binary files a/docs/images/themes/coldark.png and /dev/null differ
diff --git a/docs/images/themes/dracula.png b/docs/images/themes/dracula.png
deleted file mode 100644
index 3077c05..0000000
Binary files a/docs/images/themes/dracula.png and /dev/null differ
diff --git a/docs/images/themes/github.png b/docs/images/themes/github.png
deleted file mode 100644
index e6f98c6..0000000
Binary files a/docs/images/themes/github.png and /dev/null differ
diff --git a/docs/images/themes/gruvbox-dark.png b/docs/images/themes/gruvbox-dark.png
deleted file mode 100644
index fbaf262..0000000
Binary files a/docs/images/themes/gruvbox-dark.png and /dev/null differ
diff --git a/docs/images/themes/gruvbox-light.png b/docs/images/themes/gruvbox-light.png
deleted file mode 100644
index 616b201..0000000
Binary files a/docs/images/themes/gruvbox-light.png and /dev/null differ
diff --git a/docs/images/themes/onehalf-dark.png b/docs/images/themes/onehalf-dark.png
deleted file mode 100644
index 9146282..0000000
Binary files a/docs/images/themes/onehalf-dark.png and /dev/null differ
diff --git a/docs/images/themes/onehalf-light.png b/docs/images/themes/onehalf-light.png
deleted file mode 100644
index 86ed15b..0000000
Binary files a/docs/images/themes/onehalf-light.png and /dev/null differ
diff --git a/docs/images/themes/solarized-dark.png b/docs/images/themes/solarized-dark.png
deleted file mode 100644
index 4458464..0000000
Binary files a/docs/images/themes/solarized-dark.png and /dev/null differ
diff --git a/docs/images/themes/solarized-light.png b/docs/images/themes/solarized-light.png
deleted file mode 100644
index 1c71093..0000000
Binary files a/docs/images/themes/solarized-light.png and /dev/null differ
diff --git a/docs/images/themes/sublime-snazzy.png b/docs/images/themes/sublime-snazzy.png
deleted file mode 100644
index 6136a0b..0000000
Binary files a/docs/images/themes/sublime-snazzy.png and /dev/null differ
diff --git a/docs/images/themes/twodark.png b/docs/images/themes/twodark.png
deleted file mode 100644
index a301183..0000000
Binary files a/docs/images/themes/twodark.png and /dev/null differ
diff --git a/docs/images/themes/visual-studio-dark-plus.png b/docs/images/themes/visual-studio-dark-plus.png
deleted file mode 100644
index 1222644..0000000
Binary files a/docs/images/themes/visual-studio-dark-plus.png and /dev/null differ
diff --git a/docs/images/themes/zenburn.png b/docs/images/themes/zenburn.png
deleted file mode 100644
index 5aee8df..0000000
Binary files a/docs/images/themes/zenburn.png and /dev/null differ
diff --git a/docs/images/tools/global-settings-overrides-repl.png b/docs/images/tools/global-settings-overrides-repl.png
deleted file mode 100644
index 463f638..0000000
Binary files a/docs/images/tools/global-settings-overrides-repl.png and /dev/null differ
diff --git a/docs/images/tools/prompt-utils-checkbox.png b/docs/images/tools/prompt-utils-checkbox.png
deleted file mode 100644
index f557f4a..0000000
Binary files a/docs/images/tools/prompt-utils-checkbox.png and /dev/null differ
diff --git a/docs/images/tools/prompt-utils-confirm.png b/docs/images/tools/prompt-utils-confirm.png
deleted file mode 100644
index cc18a8b..0000000
Binary files a/docs/images/tools/prompt-utils-confirm.png and /dev/null differ
diff --git a/docs/images/tools/prompt-utils-debug.png b/docs/images/tools/prompt-utils-debug.png
deleted file mode 100644
index 2eed9bb..0000000
Binary files a/docs/images/tools/prompt-utils-debug.png and /dev/null differ
diff --git a/docs/images/tools/prompt-utils-error.png b/docs/images/tools/prompt-utils-error.png
deleted file mode 100644
index 3f3e733..0000000
Binary files a/docs/images/tools/prompt-utils-error.png and /dev/null differ
diff --git a/docs/images/tools/prompt-utils-info.png b/docs/images/tools/prompt-utils-info.png
deleted file mode 100644
index 221f0e8..0000000
Binary files a/docs/images/tools/prompt-utils-info.png and /dev/null differ
diff --git a/docs/images/tools/prompt-utils-input.png b/docs/images/tools/prompt-utils-input.png
deleted file mode 100644
index 513e567..0000000
Binary files a/docs/images/tools/prompt-utils-input.png and /dev/null differ
diff --git a/docs/images/tools/prompt-utils-list.png b/docs/images/tools/prompt-utils-list.png
deleted file mode 100644
index 604d146..0000000
Binary files a/docs/images/tools/prompt-utils-list.png and /dev/null differ
diff --git a/docs/images/tools/prompt-utils-password.png b/docs/images/tools/prompt-utils-password.png
deleted file mode 100644
index 2206020..0000000
Binary files a/docs/images/tools/prompt-utils-password.png and /dev/null differ
diff --git a/docs/images/tools/prompt-utils-trace.png b/docs/images/tools/prompt-utils-trace.png
deleted file mode 100644
index f698c2e..0000000
Binary files a/docs/images/tools/prompt-utils-trace.png and /dev/null differ
diff --git a/docs/images/tools/prompt-utils-validate-present.png b/docs/images/tools/prompt-utils-validate-present.png
deleted file mode 100644
index bacd958..0000000
Binary files a/docs/images/tools/prompt-utils-validate-present.png and /dev/null differ
diff --git a/docs/images/tools/prompt-utils-warning.png b/docs/images/tools/prompt-utils-warning.png
deleted file mode 100644
index 5363986..0000000
Binary files a/docs/images/tools/prompt-utils-warning.png and /dev/null differ
diff --git a/docs/images/tools/prompt-utils-with-validate.png b/docs/images/tools/prompt-utils-with-validate.png
deleted file mode 100644
index 4c4dbb8..0000000
Binary files a/docs/images/tools/prompt-utils-with-validate.png and /dev/null differ
diff --git a/docs/images/vault/vault-demo.gif b/docs/images/vault/vault-demo.gif
deleted file mode 100644
index dd473e6..0000000
Binary files a/docs/images/vault/vault-demo.gif and /dev/null differ
diff --git a/docs/images/vault/vault-repl-commands.png b/docs/images/vault/vault-repl-commands.png
deleted file mode 100644
index 0562a49..0000000
Binary files a/docs/images/vault/vault-repl-commands.png and /dev/null differ
diff --git a/docs/images/vault/vault-repl.png b/docs/images/vault/vault-repl.png
deleted file mode 100644
index 9c7d6aa..0000000
Binary files a/docs/images/vault/vault-repl.png and /dev/null differ
diff --git a/graph.example.yaml b/graph.example.yaml
new file mode 100644
index 0000000..9116f1b
--- /dev/null
+++ b/graph.example.yaml
@@ -0,0 +1,427 @@
+# Graph-based agent definition (full-featured reference)
+# Location: <loki-config-dir>/agents/<agent-name>/graph.yaml
+#
+# A graph agent is defined by this file alone. An agent directory contains
+# either a config.yaml (a normal LLM-loop agent) or a graph.yaml (a graph
+# agent), never both. The presence of graph.yaml is what makes the agent
+# a graph agent.
+#
+# This file is a reference: it documents every available field, themed
+# around a deep web research workflow with parallel retrieval. It is not
+# a runnable agent as-is. The `agent:`, `script:`, and `documents:` values
+# point at things that would need to exist for a real agent. For a real,
+# runnable deep-research graph agent, see assets/agents/deep-research/.
+#
+# Full documentation:
+#   https://github.com/Dark-Alex-17/loki/wiki/Graph-Agents
+
+# ---------------------------------------------------------------------------
+# Identity
+# ---------------------------------------------------------------------------
+name: deep-research-example        # Agent name (should match the directory name)
+description: |                     # Free-form prose describing the workflow
+  A reference workflow: triage a research request, retrieve local
+  context, branch on a script decision, run either a sub-agent or an
+  LLM research step, then gate the result behind human approval.
+version: "1.0"                     # Graph schema version. Only "1.0" is accepted.
+
+# ---------------------------------------------------------------------------
+# Agent-level config (all optional)
+# The same knobs a normal agent's config.yaml carries. In a graph agent they
+# live here instead of in a config.yaml.
+# ---------------------------------------------------------------------------
+model: claude:claude-sonnet-4-6    # Default model for `llm` nodes that don't override it
+temperature: 0.0                   # Default sampling temperature for `llm` nodes
+top_p: null                        # Default sampling top-p for `llm` nodes
+
+global_tools:                      # Tool universe an `llm` node's `tools:` whitelist draws from
+  - web_search_loki.sh
+  - fetch_url_via_curl.sh
+
+mcp_servers:                       # MCP servers an `llm` node may reference via `mcp:<server>`
+  - ddg-search
+
+conversation_starters:             # Suggested prompts surfaced in the UI
+  - "Research the current state of WebAssembly outside the browser"
+
+# ---------------------------------------------------------------------------
+# Agent variables (optional)
+# Declared the same way as a normal agent's config.yaml `variables:` block.
+# Each variable becomes available to:
+#   - LLM nodes via the template form `{{name}}` once seeded into state
+#     (see initial_state below).
+#   - Script nodes via the env var `LLM_AGENT_VAR_<UPPER_NAME>`.
+# Values may be overridden at runtime with
+#   `loki -a <agent> --agent-variable <name> <value> "..."`.
+# ---------------------------------------------------------------------------
+variables:
+  - name: project_dir
+    description: |
+      Absolute path to the project directory.
+    default: "."
+
+# ---------------------------------------------------------------------------
+# Execution settings (all optional)
+# ---------------------------------------------------------------------------
+settings:
+  max_loop_iterations: 100   # Per-node visit cap. If one node id is entered more
+                             # than this many times, execution aborts. Default 100.
+  timeout: 600               # Optional wall-clock cap (seconds) on the whole run,
+                             # checked between node transitions.
+  log_state_snapshots: true  # Log state before each node (debug/trace). Default true.
+  validate_before_run: true  # Run the graph validator at startup. Default true.
+  max_concurrency: 4         # Cap on simultaneously running branches in any
+                             # super-step (static fan-out OR a `map` node).
+                             # Default 4. Per-`map` overrides this. See Parallel
+                             # Execution below.
+
+# ---------------------------------------------------------------------------
+# Reducers (optional, required whenever two parallel branches write the same
+# state key in the same super-step; otherwise the validator errors at load).
+#
+# A reducer says how two values for the same key get merged. Built-ins:
+#   append    list += [value]              (single value appended to a list)
+#   extend    list += value (a list)       (list-of-lists flattened by one level)
+#   concat    "a\nb"                       (string join with newline separator)
+#   sum       a + b                        (numeric add; ints stay ints)
+#   max       max(a, b)
+#   min       min(a, b)
+#   merge     {**a, **b}                   (dict union, RHS wins on key collision)
+#   overwrite last-write-wins              (explicit opt-in; B's value replaces A's)
+#
+# Keys not listed here have an implicit "single writer per super-step" rule:
+# the validator rejects any graph where two parallel branches both write a
+# key with no reducer.
+# ---------------------------------------------------------------------------
+reducers:
+  sources: append             # The diamond below writes `sources` from both
+                              # branches; append accumulates them into a list.
+  context: concat             # Each branch contributes prose; concat joins them.
+
+# ---------------------------------------------------------------------------
+# Seed state (optional)
+# Values placed into graph state before any node runs; reference anywhere via
+# {{key}}.
+#
+# Note: `initial_prompt` is seeded automatically by Loki with the
+# caller's prompt. So there's no need to set it here.
+# ---------------------------------------------------------------------------
+initial_state:
+  audience: "general reader"
+  # Seed an empty default for any key that a strict field (a node prompt /
+  # instructions / question / End output) references but that is only set on
+  # some paths. `refinement` is set only if the `refine` input node runs;
+  # seeding it "" keeps `finalize`'s strict prompt from failing on the
+  # approve-directly path.
+  refinement: ""
+
+# ---------------------------------------------------------------------------
+# Entry point
+# ---------------------------------------------------------------------------
+start: triage                # ID of the first node to run (must exist in `nodes`)
+
+# ---------------------------------------------------------------------------
+# Nodes
+# Each node is keyed by its id. The `id:` inside a node must match its key
+# (it may also be omitted and thus Loki fills it in from the key).
+#
+# Node types: agent | script | approval | input | llm | rag | map | end
+# ---------------------------------------------------------------------------
+nodes:
+
+  # --- llm node -----------------------------------------------------------
+  # A one-shot LLM call (with an optional bounded tool-call loop). Runs in a
+  # fresh isolated context. Tools are strictly opt-in (see `tools`).
+  triage:
+    id: triage
+    type: llm
+    description: Classify the research request and extract its topic.
+    instructions: |            # Optional system prompt (templated against state)
+      You triage research requests for a {{audience}} audience.
+    prompt: |                  # Required user prompt (templated against state)
+      Classify this request and extract the core research topic:
+      {{initial_prompt}}
+    tools: []                  # Tool whitelist. Omitted or [] = no tools at all.
+                               # A list narrows to exactly those entries.
+    output_schema:             # Optional JSON Schema. The output is parsed to JSON
+      type: object             # and its top-level object keys auto-merge into state
+      properties:              # (so `topic` / `needs_deep_dive` become {{topic}} etc).
+        topic: { type: string }
+        needs_deep_dive: { type: boolean }
+      required: [topic, needs_deep_dive]
+    state_updates:             # {{output}} = this node's result (here, the parsed object)
+      triage_result: "{{output}}"
+    # --- Polymorphic `next` -----------------------------------------------
+    # A single string runs the next node sequentially (e.g. `next: retrieve`).
+    # A list runs all listed nodes in parallel as one BSP super-step
+    # (for more info on BSP, see https://en.wikipedia.org/wiki/Bulk_synchronous_parallel).
+    # Their writes are merged via `reducers:` at the join. Branches converge
+    # implicitly when they all route to the same downstream node (here,
+    # `synthesize`). See the diamond:
+    #
+    #          triage
+    #          /     \
+    #     retrieve  web_search   (run concurrently)
+    #          \     /
+    #         synthesize         (join; fires once after both finish)
+    next: [retrieve, web_search]
+
+  # --- rag node (parallel branch 1 of the diamond) ------------------------
+  # Hybrid (vector + keyword) retrieval against a per-node knowledge base.
+  # The knowledge base is built once, at agent load time, into
+  # <agent-dir>/retrieve.yaml (named after this node's id).
+  retrieve:
+    id: retrieve
+    type: rag
+    documents:                 # Required. Files, directories, URLs, loader paths.
+      - ./knowledge/           #   relative paths resolve against the agent directory
+      - https://example.com/reference
+    query: "{{topic}}"         # Retrieval query (templated). Default: {{initial_prompt}}.
+    top_k: 5                   # Chunks to retrieve. Default = the KB's own top_k.
+    timeout: 120               # Retrieval timeout in seconds. Default 120.
+    # Knowledge-base build config (optional; used only when the KB is first
+    # built). When embedding_model + chunk_size + chunk_overlap are all set,
+    # the KB builds with no interactive prompts (works in non-interactive runs).
+    embedding_model: openai:text-embedding-3-small
+    chunk_size: 1000
+    chunk_overlap: 100
+    reranker_model: null       # Optional reranker for hybrid-search results
+    batch_size: 100            # Optional embedding-request batch size
+    state_updates:             # {{output}} = { context: <str>, sources: [<path>, ...] }
+      context: "{{output.context}}"   # writes `context` -> `reducers.context = concat`
+      sources: "{{output.sources}}"   # writes `sources` -> `reducers.sources = append`
+    next: synthesize           # Joins with web_search at `synthesize`.
+
+  # --- llm node (parallel branch 2 of the diamond) ------------------------
+  # Runs concurrently with `retrieve`. Both branches write `context` and
+  # `sources`; the validator confirms both keys have a reducer declared, and
+  # the BSP scheduler merges them at the join.
+  web_search:
+    id: web_search
+    type: llm
+    instructions: "You are a web researcher. Cite every claim."
+    prompt: "Web research: {{topic}}. Return findings and sources."
+    tools:
+      - web_search_loki
+      - mcp:ddg-search
+    output_schema:
+      type: object
+      properties:
+        context: { type: string }
+        sources:
+          type: array
+          items: { type: string }
+      required: [context, sources]
+    # When `output_schema` is set, top-level keys auto-merge into state, so
+    # `context` and `sources` are produced without needing `state_updates`.
+    next: synthesize           # Joins with retrieve at `synthesize`.
+
+  # --- script node (the diamond's join; also dispatches) -----------------
+  # Runs a .sh / .py / .ts script. The script receives state via the
+  # GRAPH_STATE env var (inline JSON) or GRAPH_STATE_FILE (path to a JSON
+  # file, used when state exceeds 32 KiB). Exactly one is set. It must print
+  # a single JSON object on stdout: keys merge into state, and the reserved
+  # `_next` key (if present) overrides routing.
+  #
+  # The script also receives these env vars (parity with bash tools called
+  # from normal agents):
+  #   GRAPH_STATE / GRAPH_STATE_FILE  state payload (one of the two is set)
+  #   LLM_ROOT_DIR                    loki config dir
+  #   LLM_PROMPT_UTILS_FILE           path to .shared/prompt-utils.sh
+  #   LLM_AGENT_DATA_DIR              this agent's data directory
+  #   LLM_AGENT_VAR_<NAME>            one per declared `variables:` entry
+  #   PATH                            with loki's functions bin dir prepended
+  #   CLICOLOR_FORCE / FORCE_COLOR    so child tools emit ANSI colors
+  # The script's working directory is loki's invocation CWD (not the agent
+  # directory), matching the behavior of bash tools.
+  #
+  # This node fires once: after both `retrieve` and `web_search` finish.
+  # The BSP scheduler dedups the two incoming edges into a single frontier
+  # entry, applies the staged branch writes through the reducers, then runs
+  # this node against the merged state. Inside the script, `context` is the
+  # concatenated text of both branches and `sources` is the combined list.
+  synthesize:
+    id: synthesize
+    type: script
+    script: scripts/synthesize.py  # Path relative to the agent directory
+    timeout: 30                # Seconds. Default 30.
+    state_updates:             # Applied after the stdout JSON is merged
+      decided_for: "{{topic}}"
+    next: summarize            # Default route if the script emits no `_next`
+    fallback: summarize        # Route taken if the script fails (crash / bad JSON)
+    # This script is expected to emit `_next: deep_dive` (or `_next: subjects_map`
+    # to demonstrate the map node below), or no `_next` (then `next` is used).
+    # Targets reached only via the script's dynamic `_next` get an
+    # "unreachable" warning from the validator. This is expected for `_next`-routed
+    # targets.
+
+  # --- agent node ---------------------------------------------------------
+  # Spawns a full Loki sub-agent and waits for it. The child uses its own
+  # tool stack. Agent nodes have no `tools:` field. No schema hint is
+  # injected even when `output_schema` is set (unlike llm nodes).
+  deep_dive:
+    id: deep_dive
+    type: agent
+    agent: deep-research       # Name of an existing Loki agent to spawn
+    prompt: |                  # User message sent to the child (templated)
+      Research {{topic}} in depth. Existing context:
+      {{context}}
+    timeout: 600               # Optional wall-clock cap, seconds. Default 300.
+    output_schema:             # Optional. Same extraction as llm nodes
+      type: object
+      properties:
+        summary: { type: string }
+        findings:
+          type: array
+          items: { type: string }
+      required: [summary, findings]
+    state_updates:
+      research: "{{output}}"
+    next: review               # Required for agent nodes
+
+  # --- map node (Dynamic fan-out. Think: LangGraph's `Send` API) ----------------
+  # Spawns one parallel sub-branch per item in `over`. Each sub-branch runs
+  # the node referenced by `branch:` with the item bound to `as:`. Outputs
+  # collect into the array named by `collect_into:`, preserving input order.
+  #
+  # Reach via `synthesize`'s `_next: subjects_map`. The producer is expected
+  # to have written a list at `subjects` (e.g. an upstream LLM node with an
+  # `output_schema` returning {"subjects": ["a", "b", "c"]}).
+  subjects_map:
+    id: subjects_map
+    type: map
+    over: "{{subjects}}"        # Required. List expression resolved from state.
+                                # Empty list is allowed. It means no branches spawn,
+                                # and thus `collect_into` is written as [].
+    as: subject                 # Required. Per-branch state key holding the
+                                # current item. Read with {{subject}} inside
+                                # the branch node's prompt.
+    branch: research_subject    # Required. Node id to invoke per item.
+                                # Must point to an llm | agent | rag | script
+                                # node satisfying the map branch contract:
+                                #   - no `next:` (atomic, joined at map exit)
+                                #   - no `state_updates:` other than via the
+                                #     map's `collect_into` channel
+                                #   - no `output_schema:` (top-level merge
+                                #     would clash with collect_into)
+                                # Validator enforces all three.
+    collect_into: subject_findings  # Required. State key for the array of
+                                    # per-branch outputs, in input order
+                                    # (not spawn-finish order).
+    max_concurrency: 3          # Optional per-map cap. Defaults to
+                                # settings.max_concurrency above.
+    output_key: output          # Optional. State key the branch's output
+                                # appears under. Default "output". Useful
+                                # only if the branch reads its own bound
+                                # name back (rare).
+    next: aggregate_subjects    # Where to go after all sub-branches finish.
+
+  # Branch node for subjects_map. Each invocation receives a different
+  # `subject` in state. The branch is "atomic", meaning it cannot route on
+  # its own; the surrounding `map` joins after all invocations finish.
+  research_subject:
+    id: research_subject
+    type: llm
+    instructions: "Research one subject deeply for a {{audience}} audience."
+    prompt: "Research {{subject}}: pull the key facts and one citation."
+    tools:
+      - web_search_loki
+    # No `next:`, `state_updates:`, or `output_schema:` here. Map branches
+    # have a strict contract (see `subjects_map.branch` comment).
+
+  # Aggregator that runs after the map joins. Reads the collected list.
+  aggregate_subjects:
+    id: aggregate_subjects
+    type: llm
+    instructions: "Combine N per-subject reports into one cohesive summary."
+    prompt: |
+      Per-subject reports (in original input order):
+      {{subject_findings}}
+    state_updates:
+      research: "{{output}}"
+    next: review
+
+  # --- llm node with a narrowed tool whitelist ----------------------------
+  summarize:
+    id: summarize
+    type: llm
+    instructions: "You write concise research summaries for a {{audience}} audience."
+    prompt: "Summarize the topic {{topic}}, using your tools as needed."
+    tools:                     # Narrow whitelist: exactly these entries, nothing else
+      - web_search_loki        #   an exact global-tool / custom-tool name
+      - mcp:ddg-search         #   `mcp:<server>` includes that server's functions
+    model: claude:claude-haiku-4-5  # Optional per-node model override
+    temperature: 0.3           # Optional per-node sampling override
+    max_attempts: 2            # Retry count on transient errors only. Default 1.
+    max_iterations: 10         # Tool-call-loop turn cap. Default 10.
+    fallback: review           # Route here if all attempts fail
+    timeout: 300               # Optional node wall-clock cap, seconds (unset = no timeout)
+    state_updates:
+      research: "{{output}}"
+    next: review               # Required for llm nodes: the success route
+
+  # --- approval node ------------------------------------------------------
+  # Human-in-the-loop checkpoint. `user__ask` always offers a free-form
+  # "type your own answer" option, so `on_other` is required.
+  review:
+    id: review
+    type: approval
+    question: |
+      Proposed research result for {{topic}}:
+      {{research}}
+
+      Approve?
+    options:                   # The listed choices shown to the user
+      - "yes"
+      - "no"
+    routes:                    # Map each listed option to its next node
+      "yes": finalize
+      "no": rejected_end
+    on_other: refine           # Required: route for ANY answer not in `routes`
+    state_updates:
+      decision: "{{choice}}"   # {{choice}} = the chosen option or the free-form text
+
+  # --- input node ---------------------------------------------------------
+  # Collects a free-form string from the user.
+  refine:
+    id: refine
+    type: input
+    question: "What should be changed about the research result?"
+    default: "tighten the summary"  # Optional: used if the user submits empty input.
+                                    # Note: a substituted default is not re-validated,
+                                    # so make sure it would satisfy `validation`.
+    validation: "len(input) > 0"   # Optional length predicate: len(input) <op> N,
+                                   # <op> in > >= < <= == . Length only -- no regex.
+    state_updates:
+      refinement: "{{input}}"  # {{input}} = the user's text
+    next: finalize             # Required for input nodes: the success route
+
+  # --- llm node (final synthesis) -----------------------------------------
+  finalize:
+    id: finalize
+    type: llm
+    prompt: |
+      Produce the final research report for {{topic}}.
+      Result so far: {{research}}
+      Requested refinement (if any): {{refinement}}
+    state_updates:
+      final_report: "{{output}}"
+    next: done
+
+  # --- end nodes ----------------------------------------------------------
+  # Terminate the graph. `output` (templated, lenient interpolation) becomes
+  # the graph's final result. A graph needs at least one `end` node.
+  done:
+    id: done
+    type: end
+    state_updates:             # Optional: applied before `output` is rendered
+      status: "completed"
+    output: |
+      [{{status}}] {{final_report}}
+
+      Sources: {{sources}}
+
+  rejected_end:
+    id: rejected_end
+    type: end
+    output: "Research on {{topic}} was not approved."
diff --git a/models.yaml b/models.yaml
index 987c091..877faac 100644
--- a/models.yaml
+++ b/models.yaml
@@ -211,23 +211,31 @@
       supports_function_calling: true
     - name: gemini-2.5-flash
       max_input_tokens: 1048576
-      max_output_tokens: 65535
-      input_price: 0.3
-      output_price: 2.5
+      max_output_tokens: 65536
+      input_price: 0
+      output_price: 0
       supports_vision: true
       supports_function_calling: true
     - name: gemini-2.5-pro
       max_input_tokens: 1048576
       max_output_tokens: 65536
-      input_price: 1.25
-      output_price: 10
+      input_price: 0
+      output_price: 0
       supports_vision: true
       supports_function_calling: true
     - name: gemini-2.5-flash-lite
+      max_input_tokens: 1000000
+      max_output_tokens: 64000
+      input_price: 0
+      output_price: 0
+      supports_vision: true
+      supports_function_calling: true
+    - name: gemini-3-pro-preview
+      max_input_tokens: 1048576
+      supports_vision: true
+      supports_function_calling: true
+    - name: gemini-3-flash-preview
       max_input_tokens: 1048576
-      max_output_tokens: 65535
-      input_price: 0.1
-      output_price: 0.4
       supports_vision: true
       supports_function_calling: true
     - name: gemini-2.0-flash
@@ -245,11 +253,10 @@
       supports_vision: true
       supports_function_calling: true
     - name: gemma-3-27b-it
-      supports_vision: true
-      max_input_tokens: 128000
-      max_output_tokens: 65536
-      input_price: 0.04
-      output_price: 0.15
+      max_input_tokens: 131072
+      max_output_tokens: 8192
+      input_price: 0
+      output_price: 0
     - name: text-embedding-004
       type: embedding
       input_price: 0
@@ -432,7 +439,7 @@
           thinking:
             type: enabled
             budget_tokens: 16000
-    - name: claude-sonnet-4-20250514
+    - name: claude-sonnet-4-5-20250929
       max_input_tokens: 200000
       max_output_tokens: 8192
       require_max_tokens: true
@@ -440,8 +447,8 @@
       output_price: 15
       supports_vision: true
       supports_function_calling: true
-    - name: claude-sonnet-4-20250514:thinking
-      real_name: claude-sonnet-4-20250514
+    - name: claude-sonnet-4-5-20250929:thinking
+      real_name: claude-sonnet-4-5-20250929
       max_input_tokens: 200000
       max_output_tokens: 24000
       require_max_tokens: true
@@ -456,22 +463,23 @@
           thinking:
             type: enabled
             budget_tokens: 16000
-    - name: claude-3-7-sonnet-20250219
+    - name: claude-haiku-4-5-20251001
       max_input_tokens: 200000
       max_output_tokens: 8192
       require_max_tokens: true
-      input_price: 3
-      output_price: 15
+      input_price: 1
+      output_price: 5
       supports_vision: true
       supports_function_calling: true
-    - name: claude-3-7-sonnet-20250219:thinking
-      real_name: claude-3-7-sonnet-20250219
+    - name: claude-haiku-4-5-20251001:thinking
+      real_name: claude-haiku-4-5-20251001
       max_input_tokens: 200000
       max_output_tokens: 24000
       require_max_tokens: true
-      input_price: 3
-      output_price: 15
+      input_price: 1
+      output_price: 5
       supports_vision: true
+      supports_function_calling: true
       patch:
         body:
           temperature: null
@@ -479,14 +487,6 @@
           thinking:
             type: enabled
             budget_tokens: 16000
-    - name: claude-3-5-haiku-20241022
-      max_input_tokens: 200000
-      max_output_tokens: 8192
-      require_max_tokens: true
-      input_price: 0.8
-      output_price: 4
-      supports_vision: true
-      supports_function_calling: true
 
 # Links:
 #  - https://docs.mistral.ai/getting-started/models/models_overview/
@@ -494,6 +494,12 @@
 #  - https://docs.mistral.ai/api/
 - provider: mistral
   models:
+    - name: mistral-large-latest
+      max_output_tokens: 262144
+      input_price: 0.5
+      output_price: 1.5
+      supports_function_calling: true
+      supports_vision: true
     - name: mistral-medium-latest
       max_input_tokens: 131072
       input_price: 0.4
@@ -507,28 +513,33 @@
       supports_function_calling: true
       supports_vision: true
     - name: magistral-medium-latest
-      max_input_tokens: 40960
+      max_input_tokens: 131072
       input_price: 2
       output_price: 5
     - name: magistral-small-latest
-      max_input_tokens: 40960
+      max_input_tokens: 131072
       input_price: 0.5
       output_price: 1.5
     - name: devstral-medium-latest
-      max_input_tokens: 256000
+      max_input_tokens: 262144
       input_price: 0.4
       output_price: 2
       supports_function_calling: true
     - name: devstral-small-latest
-      max_input_tokens: 256000
+      max_input_tokens: 262144
       input_price: 0.1
       output_price: 0.3
       supports_function_calling: true
     - name: codestral-latest
-      max_input_tokens: 256000
+      max_input_tokens: 262144
       input_price: 0.3
       output_price: 0.9
       supports_function_calling: true
+    - name: ministral-14b-latest
+      max_input_tokens: 262144
+      input_price: 0.2
+      output_price: 0.2
+      supports_function_calling: true
     - name: mistral-embed
       type: embedding
       max_input_tokens: 8092
@@ -577,8 +588,8 @@
       output_price: 10
       supports_vision: true
     - name: command-r7b-12-2024
-      max_input_tokens: 128000
-      max_output_tokens: 4000
+      max_input_tokens: 131072
+      max_output_tokens: 4096
       input_price: 0.0375
       output_price: 0.15
     - name: embed-v4.0
@@ -614,23 +625,17 @@
 #  - https://docs.x.ai/docs/api-reference#chat-completions
 - provider: xai
   models:
-    - name: grok-4
-      supports_vision: true
-      max_input_tokens: 256000
-      input_price: 3
-      output_price: 15
-      supports_function_calling: true
-    - name: grok-4-fast-non-reasoning
+    - name: grok-4-1-fast-non-reasoning
       max_input_tokens: 2000000
       input_price: 0.2
       output_price: 0.5
       supports_function_calling: true
-    - name: grok-4-fast-reasoning
+    - name: grok-4-1-fast-reasoning
       max_input_tokens: 2000000
       input_price: 0.2
       output_price: 0.5
       supports_function_calling: true
-    - name: grok-code-fast
+    - name: grok-code-fast-1
       max_input_tokens: 256000
       input_price: 0.2
       output_price: 1.5
@@ -755,16 +760,24 @@
       supports_function_calling: true
     - name: gemini-2.5-flash-lite
       max_input_tokens: 1048576
-      max_output_tokens: 65535
-      input_price: 0.1
+      max_output_tokens: 65536
+      input_price: 0.3
       output_price: 0.4
       supports_vision: true
       supports_function_calling: true
+    - name: gemini-3-pro-preview
+      max_input_tokens: 1048576
+      supports_vision: true
+      supports_function_calling: true
+    - name: gemini-3-flash-preview
+      max_input_tokens: 1048576
+      supports_vision: true
+      supports_function_calling: true
     - name: gemini-2.0-flash-001
       max_input_tokens: 1048576
       max_output_tokens: 8192
-      input_price: 0.1
-      output_price: 0.4
+      input_price: 0.15
+      output_price: 0.6
       supports_vision: true
       supports_function_calling: true
     - name: gemini-2.0-flash-lite-001
@@ -774,6 +787,75 @@
       output_price: 0.3
       supports_vision: true
       supports_function_calling: true
+    - name: claude-opus-4-6
+      max_input_tokens: 200000
+      max_output_tokens: 8192
+      require_max_tokens: true
+      input_price: 5
+      output_price: 25
+      supports_vision: true
+      supports_function_calling: true
+    - name: claude-opus-4-6:thinking
+      real_name: claude-opus-4-6
+      max_input_tokens: 200000
+      max_output_tokens: 24000
+      require_max_tokens: true
+      input_price: 5
+      output_price: 25
+      supports_vision: true
+      patch:
+        body:
+          temperature: null
+          top_p: null
+          thinking:
+            type: enabled
+            budget_tokens: 16000
+    - name: claude-sonnet-4-6
+      max_input_tokens: 200000
+      max_output_tokens: 8192
+      require_max_tokens: true
+      input_price: 3
+      output_price: 15
+      supports_vision: true
+      supports_function_calling: true
+    - name: claude-sonnet-4-6:thinking
+      real_name: claude-sonnet-4-6
+      max_input_tokens: 200000
+      max_output_tokens: 24000
+      require_max_tokens: true
+      input_price: 3
+      output_price: 15
+      supports_vision: true
+      patch:
+        body:
+          temperature: null
+          top_p: null
+          thinking:
+            type: enabled
+            budget_tokens: 16000
+    - name: claude-opus-4-5@20251101
+      max_input_tokens: 200000
+      max_output_tokens: 8192
+      require_max_tokens: true
+      input_price: 5
+      output_price: 25
+      supports_vision: true
+      supports_function_calling: true
+    - name: claude-opus-4-5@20251101:thinking
+      real_name: claude-opus-4-5@20251101
+      max_input_tokens: 200000
+      max_output_tokens: 24000
+      require_max_tokens: true
+      input_price: 5
+      output_price: 25
+      supports_vision: true
+      patch:
+        body:
+          temperature: null
+          top_p: null
+          thinking:
+            type: enabled
+            budget_tokens: 16000
     - name: claude-sonnet-4-5@20250929
       max_input_tokens: 200000
       max_output_tokens: 8192
@@ -820,98 +902,6 @@
           thinking:
             type: enabled
             budget_tokens: 16000
-    - name: claude-opus-4-1@20250805
-      max_input_tokens: 200000
-      max_output_tokens: 8192
-      require_max_tokens: true
-      input_price: 15
-      output_price: 75
-      supports_vision: true
-      supports_function_calling: true
-    - name: claude-opus-4-1@20250805:thinking
-      real_name: claude-opus-4-1@20250805
-      max_input_tokens: 200000
-      max_output_tokens: 24000
-      require_max_tokens: true
-      input_price: 15
-      output_price: 75
-      supports_vision: true
-      patch:
-        body:
-          temperature: null
-          top_p: null
-          thinking:
-            type: enabled
-            budget_tokens: 16000
-    - name: claude-opus-4@20250514
-      max_input_tokens: 200000
-      max_output_tokens: 8192
-      require_max_tokens: true
-      input_price: 15
-      output_price: 75
-      supports_vision: true
-      supports_function_calling: true
-    - name: claude-opus-4@20250514:thinking
-      real_name: claude-opus-4@20250514
-      max_input_tokens: 200000
-      max_output_tokens: 24000
-      require_max_tokens: true
-      input_price: 15
-      output_price: 75
-      supports_vision: true
-      patch:
-        body:
-          temperature: null
-          top_p: null
-          thinking:
-            type: enabled
-            budget_tokens: 16000
-    - name: claude-sonnet-4@20250514
-      max_input_tokens: 200000
-      max_output_tokens: 8192
-      require_max_tokens: true
-      input_price: 3
-      output_price: 15
-      supports_vision: true
-      supports_function_calling: true
-    - name: claude-sonnet-4@20250514:thinking
-      real_name: claude-sonnet-4@20250514
-      max_input_tokens: 200000
-      max_output_tokens: 24000
-      require_max_tokens: true
-      input_price: 3
-      output_price: 15
-      supports_vision: true
-      patch:
-        body:
-          temperature: null
-          top_p: null
-          thinking:
-            type: enabled
-            budget_tokens: 16000
-    - name: claude-3-7-sonnet@20250219
-      max_input_tokens: 200000
-      max_output_tokens: 8192
-      require_max_tokens: true
-      input_price: 3
-      output_price: 15
-      supports_vision: true
-      supports_function_calling: true
-    - name: claude-3-7-sonnet@20250219:thinking
-      real_name: claude-3-7-sonnet@20250219
-      max_input_tokens: 200000
-      max_output_tokens: 24000
-      require_max_tokens: true
-      input_price: 3
-      output_price: 15
-      supports_vision: true
-      patch:
-        body:
-          temperature: null
-          top_p: null
-          thinking:
-            type: enabled
-            budget_tokens: 16000
     - name: claude-3-5-haiku@20241022
       max_input_tokens: 200000
       max_output_tokens: 8192
@@ -952,6 +942,81 @@
 #  - https://docs.aws.amazon.com/bedrock/latest/userguide/conversation-inference-call.html
 - provider: bedrock
   models:
+    - name: us.anthropic.claude-opus-4-6-v1
+      max_input_tokens: 200000
+      max_output_tokens: 8192
+      require_max_tokens: true
+      input_price: 5
+      output_price: 25
+      supports_vision: true
+      supports_function_calling: true
+    - name: us.anthropic.claude-opus-4-6-v1:thinking
+      real_name: us.anthropic.claude-opus-4-6-v1
+      max_input_tokens: 200000
+      max_output_tokens: 24000
+      require_max_tokens: true
+      input_price: 5
+      output_price: 25
+      supports_vision: true
+      patch:
+        body:
+          inferenceConfig:
+            temperature: null
+            topP: null
+          additionalModelRequestFields:
+            thinking:
+              type: enabled
+              budget_tokens: 16000
+    - name: us.anthropic.claude-sonnet-4-6
+      max_input_tokens: 200000
+      max_output_tokens: 8192
+      require_max_tokens: true
+      input_price: 3
+      output_price: 15
+      supports_vision: true
+      supports_function_calling: true
+    - name: us.anthropic.claude-sonnet-4-6:thinking
+      real_name: us.anthropic.claude-sonnet-4-6
+      max_input_tokens: 200000
+      max_output_tokens: 24000
+      require_max_tokens: true
+      input_price: 3
+      output_price: 15
+      supports_vision: true
+      patch:
+        body:
+          inferenceConfig:
+            temperature: null
+            topP: null
+          additionalModelRequestFields:
+            thinking:
+              type: enabled
+              budget_tokens: 16000
+    - name: us.anthropic.claude-opus-4-5-20251101-v1:0
+      max_input_tokens: 200000
+      max_output_tokens: 8192
+      require_max_tokens: true
+      input_price: 5
+      output_price: 25
+      supports_vision: true
+      supports_function_calling: true
+    - name: us.anthropic.claude-opus-4-5-20251101-v1:0:thinking
+      real_name: us.anthropic.claude-opus-4-5-20251101-v1:0
+      max_input_tokens: 200000
+      max_output_tokens: 24000
+      require_max_tokens: true
+      input_price: 5
+      output_price: 25
+      supports_vision: true
+      patch:
+        body:
+          inferenceConfig:
+            temperature: null
+            topP: null
+          additionalModelRequestFields:
+            thinking:
+              type: enabled
+              budget_tokens: 16000
     - name: us.anthropic.claude-sonnet-4-5-20250929-v1:0
       max_input_tokens: 200000
       max_output_tokens: 8192
@@ -1002,114 +1067,6 @@
             thinking:
               type: enabled
               budget_tokens: 16000
-    - name: us.anthropic.claude-opus-4-1-20250805-v1:0
-      max_input_tokens: 200000
-      max_output_tokens: 8192
-      require_max_tokens: true
-      input_price: 15
-      output_price: 75
-      supports_vision: true
-      supports_function_calling: true
-    - name: us.anthropic.claude-opus-4-1-20250805-v1:0:thinking
-      real_name: us.anthropic.claude-opus-4-1-20250805-v1:0
-      max_input_tokens: 200000
-      max_output_tokens: 24000
-      require_max_tokens: true
-      input_price: 15
-      output_price: 75
-      supports_vision: true
-      patch:
-        body:
-          inferenceConfig:
-            temperature: null
-            topP: null
-          additionalModelRequestFields:
-            thinking:
-              type: enabled
-              budget_tokens: 16000
-    - name: us.anthropic.claude-opus-4-20250514-v1:0
-      max_input_tokens: 200000
-      max_output_tokens: 8192
-      require_max_tokens: true
-      input_price: 15
-      output_price: 75
-      supports_vision: true
-      supports_function_calling: true
-    - name: us.anthropic.claude-opus-4-20250514-v1:0:thinking
-      real_name: us.anthropic.claude-opus-4-20250514-v1:0
-      max_input_tokens: 200000
-      max_output_tokens: 24000
-      require_max_tokens: true
-      input_price: 15
-      output_price: 75
-      supports_vision: true
-      patch:
-        body:
-          inferenceConfig:
-            temperature: null
-            topP: null
-          additionalModelRequestFields:
-            thinking:
-              type: enabled
-              budget_tokens: 16000
-    - name: us.anthropic.claude-sonnet-4-20250514-v1:0
-      max_input_tokens: 200000
-      max_output_tokens: 8192
-      require_max_tokens: true
-      input_price: 3
-      output_price: 15
-      supports_vision: true
-      supports_function_calling: true
-    - name: us.anthropic.claude-sonnet-4-20250514-v1:0:thinking
-      real_name: us.anthropic.claude-sonnet-4-20250514-v1:0
-      max_input_tokens: 200000
-      max_output_tokens: 24000
-      require_max_tokens: true
-      input_price: 3
-      output_price: 15
-      supports_vision: true
-      patch:
-        body:
-          inferenceConfig:
-            temperature: null
-            topP: null
-          additionalModelRequestFields:
-            thinking:
-              type: enabled
-              budget_tokens: 16000
-    - name: us.anthropic.claude-3-7-sonnet-20250219-v1:0
-      max_input_tokens: 200000
-      max_output_tokens: 8192
-      require_max_tokens: true
-      input_price: 3
-      output_price: 15
-      supports_vision: true
-      supports_function_calling: true
-    - name: us.anthropic.claude-3-7-sonnet-20250219-v1:0:thinking
-      real_name: us.anthropic.claude-3-7-sonnet-20250219-v1:0
-      max_input_tokens: 200000
-      max_output_tokens: 24000
-      require_max_tokens: true
-      input_price: 3
-      output_price: 15
-      supports_vision: true
-      patch:
-        body:
-          inferenceConfig:
-            temperature: null
-            topP: null
-          additionalModelRequestFields:
-            thinking:
-              type: enabled
-              budget_tokens: 16000
-    - name: anthropic.claude-3-5-haiku-20241022-v1:0
-      max_input_tokens: 200000
-      max_output_tokens: 8192
-      require_max_tokens: true
-      input_price: 0.8
-      output_price: 4
-      supports_vision: true
-      supports_function_calling: true
     - name: us.meta.llama4-maverick-17b-instruct-v1:0
       max_input_tokens: 131072
       max_output_tokens: 8192
@@ -1201,6 +1158,12 @@
       require_max_tokens: true
       input_price: 0
       output_price: 0
+    - name: '@cf/zai-org/glm-4.7-flash'
+      max_input_tokens: 131072
+      max_output_tokens: 2048
+      require_max_tokens: true
+      input_price: 0
+      output_price: 0
     - name: '@cf/google/gemma-3-12b-it'
       max_input_tokens: 131072
       max_output_tokens: 2048
@@ -1264,40 +1227,55 @@
 #  - https://help.aliyun.com/zh/model-studio/developer-reference/use-qwen-by-calling-api
 - provider: qianwen
   models:
-    - name: qwen3-max
-      input_price: 1.2
-      output_price: 6
-      max_output_tokens: 32768
+    - name: qwen3.5-plus
       max_input_tokens: 262144
       supports_function_calling: true
-    - name: qwen-plus
-      input_price: 0.4
-      output_price: 1.2
-      max_output_tokens: 32768
-      max_input_tokens: 1000000
+      patch:
+        body:
+          enable_thinking: false
+    - name: qwen3.5-plus:thinking
+      real_name: qwen3.5-plus
+      max_input_tokens: 262144
       supports_function_calling: true
-    - name: qwen-flash
-      max_input_tokens: 1000000
+    - name: qwen3-max
+      max_input_tokens: 262144
       supports_function_calling: true
+    - name: qwen3-max:thinking
+      real_name: qwen3-max
+      max_input_tokens: 262144
+      supports_function_calling: true
+      patch:
+        body:
+          enable_thinking: true
     - name: qwen3-vl-plus
       max_input_tokens: 262144
       supports_vision: true
     - name: qwen3-vl-flash
       max_input_tokens: 262144
       supports_vision: true
-    - name: qwen-coder-plus
+    - name: qwen3-coder-plus
       max_input_tokens: 1000000
-    - name: qwen-coder-flash
+    - name: qwen3-coder-flash
       max_input_tokens: 1000000
-    - name: qwen3-next-80b-a3b-instruct
+    - name: qwen3.5-397b-a17b
       max_input_tokens: 262144
-      input_price: 0.09
-      output_price: 1.1
+      supports_function_calling: true
+      patch:
+        body:
+          enable_thinking: false
+    - name: qwen3.5-397b-a17b:thinking
+      real_name: qwen3.5-397b-a17b
+      max_input_tokens: 262144
+      supports_function_calling: true
+    - name: qwen3-next-80b-a3b-instruct
+      max_input_tokens: 131072
+      input_price: 0.14
+      output_price: 0.56
       supports_function_calling: true
     - name: qwen3-next-80b-a3b-thinking
-      max_input_tokens: 128000
-      input_price: 0.15
-      output_price: 1.2
+      max_input_tokens: 131072
+      input_price: 0.14
+      output_price: 1.4
     - name: qwen3-235b-a22b-instruct-2507
       max_input_tokens: 131072
       input_price: 0.28
@@ -1305,43 +1283,33 @@
       supports_function_calling: true
     - name: qwen3-235b-a22b-thinking-2507
       max_input_tokens: 131072
-      input_price: 0
-      output_price: 0
+      input_price: 0.28
+      output_price: 2.8
     - name: qwen3-30b-a3b-instruct-2507
-      max_output_tokens: 262144
-      max_input_tokens: 262144
-      input_price: 0.09
-      output_price: 0.3
+      max_input_tokens: 131072
+      input_price: 0.105
+      output_price: 0.42
       supports_function_calling: true
     - name: qwen3-30b-a3b-thinking-2507
-      max_input_tokens: 32768
-      input_price: 0.051
-      output_price: 0.34
+      max_input_tokens: 131072
+      input_price: 0.105
+      output_price: 1.05
     - name: qwen3-vl-32b-instruct
-      max_output_tokens: 32768
-      max_input_tokens: 131072
-      input_price: 0.104
-      output_price: 0.416
-      supports_vision: true
-    - name: qwen3-vl-8b-instruct
-      max_output_tokens: 32768
-      max_input_tokens: 131072
-      input_price: 0.08
-      output_price: 0.5
-      supports_vision: true
-    - name: qwen3-coder-480b-a35b-instruct
-      max_input_tokens: 262144
-      input_price: 1.26
-      output_price: 5.04
-    - name: qwen3-coder-30b-a3b-instruct
-      max_output_tokens: 32768
-      max_input_tokens: 160000
-      input_price: 0.07
-      output_price: 0.27
-    - name: deepseek-v3.2-exp
       max_input_tokens: 131072
       input_price: 0.28
-      output_price: 0.42
+      output_price: 1.12
+      supports_vision: true
+    - name: qwen3-vl-8b-instruct
+      max_input_tokens: 131072
+      input_price: 0.07
+      output_price: 0.28
+      supports_vision: true
+    - name: qwen3-coder-next
+      max_input_tokens: 262144
+    - name: qwen3-coder-480b-a35b-instruct
+      max_input_tokens: 262144
+    - name: qwen3-coder-30b-a3b-instruct
+      max_input_tokens: 262144
     - name: text-embedding-v4
       type: embedding
       input_price: 0.1
@@ -1361,27 +1329,20 @@
 #  - https://cloud.tencent.com/document/product/1729/111007
 - provider: hunyuan
   models:
-    - name: hunyuan-turbos-latest
-      max_input_tokens: 28000
+    - name: hunyuan-2.0-instruct-20251111
+      max_input_tokens: 131072
       input_price: 0.112
       output_price: 0.28
       supports_function_calling: true
-    - name: hunyuan-t1-latest
-      max_input_tokens: 28000
+    - name: hunyuan-2.0-thinking-20251109
+      max_input_tokens: 131072
       input_price: 0.14
       output_price: 0.56
-    - name: hunyuan-lite
-      max_input_tokens: 250000
-      input_price: 0
-      output_price: 0
       supports_function_calling: true
-    - name: hunyuan-turbos-vision
-      max_input_tokens: 6144
+    - name: hunyuan-vision-1.5-instruct
+      max_input_tokens: 24576
       input_price: 0.42
-      output_price: 0.84
-      supports_vision: true
-    - name: hunyuan-t1-vision
-      max_input_tokens: 24000
+      output_price: 1.26
       supports_vision: true
     - name: hunyuan-embedding
       type: embedding
@@ -1395,6 +1356,12 @@
 #  - https://platform.moonshot.cn/docs/api/chat#%E5%85%AC%E5%BC%80%E7%9A%84%E6%9C%8D%E5%8A%A1%E5%9C%B0%E5%9D%80
 - provider: moonshot
   models:
+    - name: kimi-k2.5
+      max_input_tokens: 262144
+      input_price: 0.56
+      output_price: 2.94
+      supports_vision: true
+      supports_function_calling: true
     - name: kimi-k2-turbo-preview
       max_input_tokens: 262144
       input_price: 1.12
@@ -1413,9 +1380,9 @@
       output_price: 8.12
       supports_vision: true
     - name: kimi-k2-thinking
-      max_input_tokens: 131072
-      input_price: 0.47
-      output_price: 2
+      max_input_tokens: 262144
+      input_price: 0.56
+      output_price: 2.24
       supports_vision: true
 
 # Links:
@@ -1424,10 +1391,10 @@
 - provider: deepseek
   models:
     - name: deepseek-chat
-      max_input_tokens: 163840
-      max_output_tokens: 163840
-      input_price: 0.32
-      output_price: 0.89
+      max_input_tokens: 64000
+      max_output_tokens: 8192
+      input_price: 0.56
+      output_price: 1.68
       supports_function_calling: true
     - name: deepseek-reasoner
       max_input_tokens: 64000
@@ -1440,54 +1407,41 @@
 #  - https://open.bigmodel.cn/dev/api#glm-4
 - provider: zhipuai
   models:
-    - name: glm-4.6
+    - name: glm-5
       max_input_tokens: 202752
-      input_price: 0.28
-      output_price: 1.12
       supports_function_calling: true
-    - name: glm-4.5
-      max_input_tokens: 131072
-      input_price: 0.28
-      output_price: 1.12
-    - name: glm-4.5-x
-      max_input_tokens: 131072
-      input_price: 1.12
-      output_price: 4.48
+    - name: glm-5:instruct
+      real_name: glm-5
+      max_input_tokens: 202752
       supports_function_calling: true
-    - name: glm-4.5-air
-      max_input_tokens: 131072
-      input_price: 0.084
-      output_price: 0.56
-    - name: glm-4.5-airx
-      max_input_tokens: 131072
-      input_price: 0.56
-      output_price: 2.24
+      patch:
+        body:
+          thinking:
+            type: disabled
+    - name: glm-4.7
+      max_input_tokens: 202752
       supports_function_calling: true
-    - name: glm-4.5-flash
-      max_input_tokens: 131072
+    - name: glm-4.7:instruct
+      real_name: glm-4.7
+      max_input_tokens: 202752
+      supports_function_calling: true
+      patch:
+        body:
+          thinking:
+            type: disabled
+    - name: glm-4.7-flash
+      max_input_tokens: 202752
       input_price: 0
       output_price: 0
-    - name: glm-4.5v
+      supports_function_calling: true
+    - name: glm-4.6v
       max_input_tokens: 65536
-      input_price: 0.56
-      output_price: 1.68
       supports_vision: true
-    - name: glm-z1-air
-      max_input_tokens: 131072
-      input_price: 0.07
-      output_price: 0.07
-    - name: glm-z1-airx
-      max_input_tokens: 131072
-      input_price: 0.7
-      output_price: 0.7
-    - name: glm-z1-flashx
-      max_input_tokens: 131072
-      input_price: 0.014
-      output_price: 0.014
-    - name: glm-z1-flash
-      max_input_tokens: 131072
+    - name: glm-4.6v-flash
+      max_input_tokens: 65536
       input_price: 0
       output_price: 0
+      supports_vision: true
     - name: embedding-3
       type: embedding
       max_input_tokens: 8192
@@ -1500,15 +1454,29 @@
       input_price: 0.112
 
 # Links:
-# - https://platform.minimaxi.com/docs/guides/pricing
+# - https://platform.minimaxi.com/docs/guides/pricing-paygo
 # - https://platform.minimaxi.com/document/ChatCompletion%20v2
 - provider: minimax
   models:
-    - name: minimax-m2
-      max_output_tokens: 65536
-      max_input_tokens: 196608
-      input_price: 0.255
-      output_price: 1
+    - name: minimax-m2.5
+      max_input_tokens: 204800
+      input_price: 0.294
+      output_price: 1.176
+      supports_function_calling: true
+    - name: minimax-m2.5-highspeed
+      max_input_tokens: 204800
+      input_price: 0.588
+      output_price: 2.352
+      supports_function_calling: true
+    - name: minimax-m2.1
+      max_input_tokens: 204800
+      input_price: 0.294
+      output_price: 1.176
+      supports_function_calling: true
+    - name: minimax-m2.1-highspeed
+      max_input_tokens: 204800
+      input_price: 0.588
+      output_price: 2.352
       supports_function_calling: true
 
 # Links:
@@ -1516,18 +1484,11 @@
 #  - https://openrouter.ai/docs/api-reference/chat-completion
 - provider: openrouter
   models:
-    - name: openai/gpt-5.1
+    - name: openai/gpt-5.2
       max_input_tokens: 400000
       max_output_tokens: 128000
-      input_price: 1.25
-      output_price: 10
-      supports_vision: true
-      supports_function_calling: true
-    - name: openai/gpt-5.1-chat
-      max_input_tokens: 128000
-      max_output_tokens: 16384
-      input_price: 1.25
-      output_price: 10
+      input_price: 1.75
+      output_price: 14
       supports_vision: true
       supports_function_calling: true
     - name: openai/gpt-5
@@ -1537,13 +1498,6 @@
       output_price: 10
       supports_vision: true
       supports_function_calling: true
-    - name: openai/gpt-5-chat
-      max_input_tokens: 128000
-      max_output_tokens: 16384
-      input_price: 1.25
-      output_price: 10
-      supports_vision: true
-      supports_function_calling: true
     - name: openai/gpt-5-mini
       max_input_tokens: 400000
       max_output_tokens: 128000
@@ -1565,164 +1519,82 @@
       output_price: 8
       supports_vision: true
       supports_function_calling: true
-    - name: openai/gpt-4.1-mini
-      max_input_tokens: 1047576
-      max_output_tokens: 32768
-      input_price: 0.4
-      output_price: 1.6
-      supports_vision: true
-      supports_function_calling: true
-    - name: openai/gpt-4.1-nano
-      max_input_tokens: 1047576
-      max_output_tokens: 32768
-      input_price: 0.1
-      output_price: 0.4
-      supports_vision: true
-      supports_function_calling: true
     - name: openai/gpt-4o
-      max_output_tokens: 16384
       max_input_tokens: 128000
       input_price: 2.5
       output_price: 10
       supports_vision: true
       supports_function_calling: true
-    - name: openai/gpt-4o-mini
-      max_output_tokens: 16384
-      max_input_tokens: 128000
-      input_price: 0.15
-      output_price: 0.6
-      supports_vision: true
-      supports_function_calling: true
-    - name: openai/o4-mini
-      max_output_tokens: 100000
-      max_input_tokens: 200000
-      input_price: 1.1
-      output_price: 4.4
-      supports_vision: true
-      supports_function_calling: true
-      system_prompt_prefix: Formatting re-enabled
-      patch:
-        body:
-          max_tokens: null
-          temperature: null
-          top_p: null
-    - name: openai/o4-mini-high
-      max_output_tokens: 100000
-      max_input_tokens: 200000
-      input_price: 1.1
-      output_price: 4.4
-      supports_vision: true
-      supports_function_calling: true
-      system_prompt_prefix: Formatting re-enabled
-      patch:
-        body:
-          reasoning_effort: high
-          max_tokens: null
-          temperature: null
-          top_p: null
-    - name: openai/o3
-      max_output_tokens: 100000
-      max_input_tokens: 200000
-      input_price: 2
-      output_price: 8
-      supports_vision: true
-      supports_function_calling: true
-      system_prompt_prefix: Formatting re-enabled
-      patch:
-        body:
-          max_tokens: null
-          temperature: null
-          top_p: null
-    - name: openai/o3-high
-      real_name: openai/o3
-      max_input_tokens: 200000
-      input_price: 2
-      output_price: 8
-      supports_vision: true
-      supports_function_calling: true
-      system_prompt_prefix: Formatting re-enabled
-      patch:
-        body:
-          reasoning_effort: high
-          temperature: null
-          top_p: null
-    - name: openai/o3-mini
-      max_output_tokens: 100000
-      max_input_tokens: 200000
-      input_price: 1.1
-      output_price: 4.4
-      supports_vision: true
-      supports_function_calling: true
-      system_prompt_prefix: Formatting re-enabled
-      patch:
-        body:
-          temperature: null
-          top_p: null
-    - name: openai/o3-mini-high
-      max_output_tokens: 100000
-      max_input_tokens: 200000
-      input_price: 1.1
-      output_price: 4.4
-      supports_vision: true
-      supports_function_calling: true
-      system_prompt_prefix: Formatting re-enabled
-      patch:
-        body:
-          temperature: null
-          top_p: null
     - name: openai/gpt-oss-120b
       max_input_tokens: 131072
-      input_price: 0.039
-      output_price: 0.19
+      input_price: 0.09
+      output_price: 0.45
       supports_function_calling: true
     - name: openai/gpt-oss-20b
       max_input_tokens: 131072
-      input_price: 0.03
-      output_price: 0.14
+      input_price: 0.04
+      output_price: 0.16
       supports_function_calling: true
     - name: google/gemini-2.5-flash
-      max_output_tokens: 65535
       max_input_tokens: 1048576
       input_price: 0.3
       output_price: 2.5
       supports_vision: true
       supports_function_calling: true
     - name: google/gemini-2.5-pro
-      max_output_tokens: 65536
       max_input_tokens: 1048576
       input_price: 1.25
       output_price: 10
       supports_vision: true
       supports_function_calling: true
     - name: google/gemini-2.5-flash-lite
-      max_output_tokens: 65535
       max_input_tokens: 1048576
-      input_price: 0.1
+      input_price: 0.3
       output_price: 0.4
       supports_vision: true
     - name: google/gemini-2.0-flash-001
-      max_output_tokens: 8192
-      max_input_tokens: 1048576
-      input_price: 0.1
-      output_price: 0.4
+      max_input_tokens: 1000000
+      input_price: 0.15
+      output_price: 0.6
       supports_vision: true
       supports_function_calling: true
     - name: google/gemini-2.0-flash-lite-001
-      max_output_tokens: 8192
       max_input_tokens: 1048576
       input_price: 0.075
       output_price: 0.3
       supports_vision: true
       supports_function_calling: true
     - name: google/gemma-3-27b-it
-      max_output_tokens: 65536
+      max_input_tokens: 131072
+      input_price: 0.1
+      output_price: 0.2
+    - name: anthropic/claude-opus-4.6
+      max_input_tokens: 200000
+      max_output_tokens: 8192
+      require_max_tokens: true
+      input_price: 5
+      output_price: 25
       supports_vision: true
-      max_input_tokens: 128000
-      input_price: 0.04
-      output_price: 0.15
+      supports_function_calling: true
+    - name: anthropic/claude-sonnet-4.6
+      max_input_tokens: 200000
+      max_output_tokens: 8192
+      require_max_tokens: true
+      input_price: 3
+      output_price: 15
+      supports_vision: true
+      supports_function_calling: true
+    - name: anthropic/claude-opus-4.5
+      max_input_tokens: 200000
+      max_output_tokens: 8192
+      require_max_tokens: true
+      input_price: 5
+      output_price: 25
+      supports_vision: true
+      supports_function_calling: true
     - name: anthropic/claude-sonnet-4.5
-      max_input_tokens: 1000000
-      max_output_tokens: 64000
+      max_input_tokens: 200000
+      max_output_tokens: 8192
       require_max_tokens: true
       input_price: 3
       output_price: 15
@@ -1730,71 +1602,33 @@
       supports_function_calling: true
     - name: anthropic/claude-haiku-4.5
       max_input_tokens: 200000
-      max_output_tokens: 64000
+      max_output_tokens: 8192
       require_max_tokens: true
       input_price: 1
       output_price: 5
       supports_vision: true
       supports_function_calling: true
-    - name: anthropic/claude-opus-4.1
-      max_input_tokens: 200000
-      max_output_tokens: 32000
-      require_max_tokens: true
-      input_price: 15
-      output_price: 75
-      supports_vision: true
-      supports_function_calling: true
-    - name: anthropic/claude-opus-4
-      max_input_tokens: 200000
-      max_output_tokens: 32000
-      require_max_tokens: true
-      input_price: 15
-      output_price: 75
-      supports_vision: true
-      supports_function_calling: true
-    - name: anthropic/claude-sonnet-4
-      max_input_tokens: 1000000
-      max_output_tokens: 64000
-      require_max_tokens: true
-      input_price: 3
-      output_price: 15
-      supports_vision: true
-      supports_function_calling: true
-    - name: anthropic/claude-3.7-sonnet
-      max_input_tokens: 200000
-      max_output_tokens: 64000
-      require_max_tokens: true
-      input_price: 3
-      output_price: 15
-      supports_vision: true
-      supports_function_calling: true
-    - name: anthropic/claude-3.5-haiku
-      max_input_tokens: 200000
-      max_output_tokens: 8192
-      require_max_tokens: true
-      input_price: 0.8
-      output_price: 4
-      supports_vision: true
-      supports_function_calling: true
     - name: meta-llama/llama-4-maverick
-      max_output_tokens: 16384
       max_input_tokens: 1048576
-      input_price: 0.15
+      input_price: 0.18
       output_price: 0.6
       supports_vision: true
       supports_function_calling: true
     - name: meta-llama/llama-4-scout
-      max_output_tokens: 16384
       max_input_tokens: 327680
       input_price: 0.08
       output_price: 0.3
       supports_vision: true
       supports_function_calling: true
     - name: meta-llama/llama-3.3-70b-instruct
-      max_output_tokens: 16384
       max_input_tokens: 131072
-      input_price: 0.1
-      output_price: 0.32
+      input_price: 0.12
+      output_price: 0.3
+    - name: mistralai/mistral-large-2512
+      max_input_tokens: 262144
+      input_price: 0.5
+      output_price: 1.5
+      supports_function_calling: true
     - name: mistralai/mistral-medium-3.1
       max_input_tokens: 131072
       input_price: 0.4
@@ -1802,142 +1636,119 @@
       supports_function_calling: true
       supports_vision: true
     - name: mistralai/mistral-small-3.2-24b-instruct
-      max_output_tokens: 131072
-      max_input_tokens: 131072
-      input_price: 0.06
-      output_price: 0.18
-      supports_vision: true
-    - name: mistralai/magistral-medium-2506
-      max_input_tokens: 40960
-      input_price: 2
-      output_price: 5
-    - name: mistralai/magistral-medium-2506:thinking
-      max_input_tokens: 40960
-      input_price: 2
-      output_price: 5
-    - name: mistralai/magistral-small-2506
-      max_input_tokens: 40960
-      input_price: 0.5
-      output_price: 1.5
-    - name: mistralai/devstral-medium
-      max_input_tokens: 131072
-      input_price: 0.4
-      output_price: 2
-      supports_function_calling: true
-    - name: mistralai/devstral-small
       max_input_tokens: 131072
       input_price: 0.1
       output_price: 0.3
+      supports_vision: true
+    - name: mistralai/devstral-2512
+      max_input_tokens: 262144
+      input_price: 0.5
+      output_price: 0.22
+      supports_function_calling: true
+    - name: mistralai/devstral-small
+      max_input_tokens: 131072
+      input_price: 0.07
+      output_price: 0.28
       supports_function_calling: true
     - name: mistralai/codestral-2508
       max_input_tokens: 256000
       input_price: 0.3
       output_price: 0.9
       supports_function_calling: true
+    - name: mistralai/ministral-14b-2512
+      max_input_tokens: 262144
+      input_price: 0.2
+      output_price: 0.2
+      supports_function_calling: true
     - name: ai21/jamba-large-1.7
-      max_output_tokens: 4096
       max_input_tokens: 256000
       input_price: 2
       output_price: 8
       supports_function_calling: true
-    - name: ai21/jamba-mini-1.7
-      max_input_tokens: 256000
-      input_price: 0.2
-      output_price: 0.4
-      supports_function_calling: true
     - name: cohere/command-a
-      max_output_tokens: 8192
       max_input_tokens: 256000
       input_price: 2.5
       output_price: 10
       supports_function_calling: true
     - name: cohere/command-r7b-12-2024
       max_input_tokens: 128000
-      max_output_tokens: 4000
+      max_output_tokens: 4096
       input_price: 0.0375
       output_price: 0.15
-    - name: deepseek/deepseek-v3.2-exp
-      max_output_tokens: 65536
+    - name: deepseek/deepseek-v3.2
       max_input_tokens: 163840
-      input_price: 0.27
-      output_price: 0.41
-    - name: deepseek/deepseek-v3.1-terminus
-      max_input_tokens: 163840
-      input_price: 0.21
-      output_price: 0.79
-    - name: deepseek/deepseek-chat-v3.1
-      max_output_tokens: 7168
-      max_input_tokens: 32768
-      input_price: 0.15
-      output_price: 0.75
-    - name: deepseek/deepseek-r1-0528
-      max_output_tokens: 65536
-      max_input_tokens: 163840
-      input_price: 0.4
-      output_price: 1.75
-      patch:
-        body:
-          include_reasoning: true
+      input_price: 0.25
+      output_price: 0.38
     - name: qwen/qwen3-max
-      max_output_tokens: 32768
       max_input_tokens: 262144
       input_price: 1.2
       output_price: 6
       supports_function_calling: true
-    - name: qwen/qwen-plus
+    - name: qwen/qwen3-max-thinking
+      max_input_tokens: 262144
+      input_price: 1.2
+      output_price: 6
+      supports_function_calling: true
+    - name: qwen/qwen3.5-plus-02-15
       max_input_tokens: 1000000
-      max_output_tokens: 32768
+      max_output_tokens: 8192
       input_price: 0.4
-      output_price: 1.2
+      output_price: 2.4
+      supports_function_calling: true
+    - name: qwen/qwen3.5-397b-a17b
+      max_input_tokens: 262144
+      max_output_tokens: 8192
+      input_price: 0.15
+      output_price: 1
       supports_function_calling: true
     - name: qwen/qwen3-next-80b-a3b-instruct
       max_input_tokens: 262144
-      input_price: 0.09
-      output_price: 1.1
+      input_price: 0.1
+      output_price: 0.8
       supports_function_calling: true
     - name: qwen/qwen3-next-80b-a3b-thinking
-      max_input_tokens: 128000
-      input_price: 0.15
-      output_price: 1.2
-    - name: qwen/qwen5-235b-a22b-2507 # Qwen3 235B A22B Instruct 2507
+      max_input_tokens: 262144
+      input_price: 0.1
+      output_price: 0.8
+    - name: qwen/qwen3-235b-a22b-2507 # Qwen3 235B A22B Instruct 2507
       max_input_tokens: 262144
       input_price: 0.12
       output_price: 0.59
       supports_function_calling: true
     - name: qwen/qwen3-235b-a22b-thinking-2507
-      max_input_tokens: 131072
-      input_price: 0
-      output_price: 0
-    - name: qwen/qwen3-30b-a3b-instruct-2507
-      max_output_tokens: 262144
       max_input_tokens: 262144
-      input_price: 0.09
-      output_price: 0.3
-    - name: qwen/qwen3-30b-a3b-thinking-2507
-      max_input_tokens: 32768
-      input_price: 0.051
-      output_price: 0.34
-    - name: qwen/qwen3-vl-32b-instruct
-      max_output_tokens: 32768
+      input_price: 0.118
+      output_price: 0.118
+    - name: qwen/qwen3-30b-a3b-instruct-2507
       max_input_tokens: 131072
-      input_price: 0.104
-      output_price: 0.416
+      input_price: 0.2
+      output_price: 0.8
+    - name: qwen/qwen3-30b-a3b-thinking-2507
+      max_input_tokens: 262144
+      input_price: 0.071
+      output_price: 0.285
+    - name: qwen/qwen3-vl-32b-instruct
+      max_input_tokens: 262144
+      input_price: 0.35
+      output_price: 1.1
       supports_vision: true
     - name: qwen/qwen3-vl-8b-instruct
-      max_output_tokens: 32768
-      max_input_tokens: 131072
+      max_input_tokens: 262144
       input_price: 0.08
-      output_price: 0.5
+      output_price: 0.50
       supports_vision: true
+    - name: qwen/qwen3-coder-next
+      max_input_tokens: 262144
+      input_price: 0.12
+      output_price: 0.75
+      supports_function_calling: true
     - name: qwen/qwen3-coder-plus
-      max_output_tokens: 65536
-      max_input_tokens: 1000000
+      max_input_tokens: 128000
       input_price: 1
       output_price: 5
       supports_function_calling: true
     - name: qwen/qwen3-coder-flash
-      max_output_tokens: 65536
-      max_input_tokens: 1000000
+      max_input_tokens: 128000
       input_price: 0.3
       output_price: 1.5
       supports_function_calling: true
@@ -1947,47 +1758,38 @@
       output_price: 0.95
       supports_function_calling: true
     - name: qwen/qwen3-coder-30b-a3b-instruct
-      max_output_tokens: 32768
-      max_input_tokens: 160000
-      input_price: 0.07
-      output_price: 0.27
+      max_input_tokens: 262144
+      input_price: 0.052
+      output_price: 0.207
+      supports_function_calling: true
+    - name: moonshotai/kimi-k2.5
+      max_input_tokens: 262144
+      input_price: 0.57
+      output_price: 2.85
+      supports_vision: true
       supports_function_calling: true
     - name: moonshotai/kimi-k2-0905
-      max_input_tokens: 131072
-      input_price: 0.4
-      output_price: 2
+      max_input_tokens: 262144
+      input_price: 0.296
+      output_price: 1.185
+      supports_vision: true
       supports_function_calling: true
     - name: moonshotai/kimi-k2-thinking
-      max_input_tokens: 131072
-      input_price: 0.47
-      output_price: 2
+      max_input_tokens: 262144
+      input_price: 0.45
+      output_price: 2.35
       supports_function_calling: true
-    - name: moonshotai/kimi-dev-72b
-      max_input_tokens: 131072
-      input_price: 0.29
-      output_price: 1.15
-      supports_function_calling: true
-    - name: x-ai/grok-4
-      supports_vision: true
-      max_input_tokens: 256000
-      input_price: 3
-      output_price: 15
-      supports_function_calling: true
-    - name: x-ai/grok-4-fast
-      max_output_tokens: 30000
-      supports_vision: true
+    - name: x-ai/grok-4.1-fast
       max_input_tokens: 2000000
       input_price: 0.2
       output_price: 0.5
       supports_function_calling: true
     - name: x-ai/grok-code-fast-1
-      max_output_tokens: 10000
       max_input_tokens: 256000
       input_price: 0.2
       output_price: 1.5
       supports_function_calling: true
     - name: amazon/nova-premier-v1
-      max_output_tokens: 32000
       max_input_tokens: 1000000
       input_price: 2.5
       output_price: 12.5
@@ -2010,49 +1812,57 @@
       input_price: 0.035
       output_price: 0.14
     - name: perplexity/sonar-pro
-      max_output_tokens: 8000
-      supports_vision: true
       max_input_tokens: 200000
       input_price: 3
       output_price: 15
     - name: perplexity/sonar
-      supports_vision: true
       max_input_tokens: 127072
       input_price: 1
       output_price: 1
     - name: perplexity/sonar-reasoning-pro
-      supports_vision: true
       max_input_tokens: 128000
       input_price: 2
       output_price: 8
       patch:
         body:
           include_reasoning: true
-    - name: perplexity/sonar-reasoning
-      max_input_tokens: 127000
-      input_price: 1
-      output_price: 5
-      patch:
-        body:
-          include_reasoning: true
     - name: perplexity/sonar-deep-research
-      max_input_tokens: 128000
+      max_input_tokens: 200000
       input_price: 2
       output_price: 8
       patch:
         body:
           include_reasoning: true
-    - name: minimax/minimax-m2
-      max_output_tokens: 65536
+    - name: minimax/minimax-m2.5
       max_input_tokens: 196608
-      input_price: 0.255
-      output_price: 1
-    - name: z-ai/glm-4.6
-      max_output_tokens: 131072
-      max_input_tokens: 202752
-      input_price: 0.35
-      output_price: 1.71
+      input_price: 0.3
+      output_price: 1.1
       supports_function_calling: true
+    - name: minimax/minimax-m2.1
+      max_input_tokens: 196608
+      input_price: 0.12
+      output_price: 0.48
+      supports_function_calling: true
+    - name: z-ai/glm-5
+      max_input_tokens: 204800
+      input_price: 0.95
+      output_price: 2.55
+      supports_function_calling: true
+    - name: z-ai/glm-4.7
+      max_input_tokens: 202752
+      input_price: 0.16
+      output_price: 0.80
+      supports_function_calling: true
+    - name: z-ai/glm-4.7-flash
+      max_input_tokens: 202752
+      input_price: 0.07
+      output_price: 0.40
+      supports_function_calling: true
+    - name: z-ai/glm-4.6v
+      max_input_tokens: 131072
+      input_price: 0.3
+      output_price: 0.9
+      supports_vision: true
 
 # Links:
 #  - https://github.com/marketplace?type=models
@@ -2063,11 +1873,6 @@
       max_output_tokens: 128000
       supports_vision: true
       supports_function_calling: true
-    - name: gpt-5-chat
-      max_input_tokens: 400000
-      max_output_tokens: 128000
-      supports_vision: true
-      supports_function_calling: true
     - name: gpt-5-mini
       max_input_tokens: 400000
       max_output_tokens: 128000
@@ -2083,90 +1888,10 @@
       max_output_tokens: 32768
       supports_vision: true
       supports_function_calling: true
-    - name: gpt-4.1-mini
-      max_input_tokens: 1047576
-      max_output_tokens: 32768
-      supports_vision: true
-      supports_function_calling: true
-    - name: gpt-4.1-nano
-      max_input_tokens: 1047576
-      max_output_tokens: 32768
-      supports_vision: true
-      supports_function_calling: true
     - name: gpt-4o
       max_input_tokens: 128000
       max_output_tokens: 16384
       supports_function_calling: true
-    - name: gpt-4o-mini
-      max_input_tokens: 128000
-      max_output_tokens: 16384
-      supports_function_calling: true
-    - name: o4-mini
-      max_input_tokens: 200000
-      supports_vision: true
-      supports_function_calling: true
-      system_prompt_prefix: Formatting re-enabled
-      patch:
-        body:
-          max_tokens: null
-          temperature: null
-          top_p: null
-    - name: o4-mini-high
-      real_name: o4-mini
-      max_input_tokens: 200000
-      supports_vision: true
-      supports_function_calling: true
-      system_prompt_prefix: Formatting re-enabled
-      patch:
-        body:
-          reasoning_effort: high
-          max_tokens: null
-          temperature: null
-          top_p: null
-    - name: o3
-      max_input_tokens: 200000
-      supports_vision: true
-      supports_function_calling: true
-      system_prompt_prefix: Formatting re-enabled
-      patch:
-        body:
-          max_tokens: null
-          temperature: null
-          top_p: null
-    - name: o3-high
-      real_name: o3
-      max_input_tokens: 200000
-      supports_vision: true
-      supports_function_calling: true
-      system_prompt_prefix: Formatting re-enabled
-      patch:
-        body:
-          reasoning_effort: high
-          max_tokens: null
-          temperature: null
-          top_p: null
-    - name: o3-mini
-      max_input_tokens: 200000
-      supports_vision: true
-      supports_function_calling: true
-      system_prompt_prefix: Formatting re-enabled
-      patch:
-        body:
-          max_tokens: null
-          temperature: null
-          top_p: null
-    - name: o3-mini-high
-      real_name: o3-mini
-      max_input_tokens: 200000
-      supports_vision: true
-      supports_function_calling: true
-      system_prompt_prefix: Formatting re-enabled
-      patch:
-        body:
-          reasoning_effort: high
-          max_tokens: null
-          temperature: null
-          top_p: null
     - name: text-embedding-3-large
       type: embedding
       max_tokens_per_chunk: 8191
@@ -2248,6 +1973,16 @@
       input_price: 0.08
       output_price: 0.3
       supports_vision: true
+    - name: Qwen/Qwen3-Max
+      max_input_tokens: 262144
+      input_price: 1.2
+      output_price: 6
+      supports_function_calling: true
+    - name: Qwen/Qwen3-Max-Thinking
+      max_input_tokens: 262144
+      input_price: 1.2
+      output_price: 6
+      supports_function_calling: true
     - name: Qwen/Qwen3-Next-80B-A3B-Instruct
       max_input_tokens: 262144
       input_price: 0.14
@@ -2285,22 +2020,11 @@
       input_price: 0.18
       output_price: 0.69
       supports_vision: true
-    - name: deepseek-ai/DeepSeek-V3.2-Exp
+    - name: deepseek-ai/DeepSeek-V3.2
       max_input_tokens: 163840
-      input_price: 0.27
-      output_price: 0.40
-    - name: deepseek-ai/DeepSeek-V3.1-Terminus
-      max_input_tokens: 163840
-      input_price: 0.27
-      output_price: 1.0
-    - name: deepseek-ai/DeepSeek-V3.1
-      max_input_tokens: 163840
-      input_price: 0.3
-      output_price: 1.0
-    - name: deepseek-ai/DeepSeek-R1-0528
-      max_input_tokens: 163840
-      input_price: 0.5
-      output_price: 2.15
+      input_price: 0.26
+      output_price: 0.39
+      supports_function_calling: true
     - name: google/gemma-3-27b-it
       max_input_tokens: 131072
       input_price: 0.1
@@ -2309,6 +2033,11 @@
       max_input_tokens: 32768
       input_price: 0.06
       output_price: 0.12
+    - name: moonshotai/Kimi-K2.5
+      max_input_tokens: 262144
+      input_price: 0.5
+      output_price: 2.8
+      supports_function_calling: true
     - name: moonshotai/Kimi-K2-Instruct-0905
       max_input_tokens: 262144
       input_price: 0.5
@@ -2319,11 +2048,36 @@
       input_price: 0.55
       output_price: 2.5
       supports_function_calling: true
-    - name: zai-org/GLM-4.6
-      max_input_tokens: 202752
-      input_price: 0.6
-      output_price: 1.9
+    - name: MiniMaxAI/MiniMax-M2.5
+      max_input_tokens: 196608
+      input_price: 0.27
+      output_price: 0.95
       supports_function_calling: true
+    - name: MiniMaxAI/MiniMax-M2.1
+      max_input_tokens: 196608
+      input_price: 0.27
+      output_price: 0.95
+      supports_function_calling: true
+    - name: zai-org/GLM-5
+      max_input_tokens: 202752
+      input_price: 0.8
+      output_price: 2.56
+      supports_function_calling: true
+    - name: zai-org/GLM-4.7
+      max_input_tokens: 202752
+      input_price: 0.43
+      output_price: 1.75
+      supports_function_calling: true
+    - name: zai-org/GLM-4.7-Flash
+      max_input_tokens: 202752
+      input_price: 0.06
+      output_price: 0.4
+      supports_function_calling: true
+    - name: zai-org/GLM-4.6V
+      max_input_tokens: 131072
+      input_price: 0.3
+      output_price: 0.9
+      supports_vision: true
     - name: BAAI/bge-large-en-v1.5
       type: embedding
       input_price: 0.01
diff --git a/src/cli/completer.rs b/src/cli/completer.rs
index 81bc604..dff7b41 100644
--- a/src/cli/completer.rs
+++ b/src/cli/completer.rs
@@ -1,7 +1,11 @@
 use crate::client::{ModelType, list_models};
-use crate::config::{Config, list_agents};
+use crate::config::paths;
+use crate::config::{AppConfig, Config, list_agents, list_sessions};
+use crate::utils::list_file_names;
+use crate::vault::Vault;
 use clap_complete::{CompletionCandidate, Shell, generate};
 use clap_complete_nushell::Nushell;
+use std::env;
 use std::ffi::OsStr;
 use std::io;
 
@@ -32,8 +36,8 @@ impl ShellCompletion {
 
 pub(super) fn model_completer(current: &OsStr) -> Vec<CompletionCandidate> {
     let cur = current.to_string_lossy();
-    match Config::init_bare() {
-        Ok(config) => list_models(&config, ModelType::Chat)
+    match load_app_config_for_completion() {
+        Ok(app_config) => list_models(&app_config, ModelType::Chat)
             .into_iter()
             .filter(|&m| m.id().starts_with(&*cur))
             .map(|m| CompletionCandidate::new(m.id()))
@@ -42,9 +46,23 @@ pub(super) fn model_completer(current: &OsStr) -> Vec<CompletionCandidate> {
     }
 }
 
+fn load_app_config_for_completion() -> anyhow::Result<AppConfig> {
+    let h = tokio::runtime::Handle::try_current().ok();
+    let cfg = match h {
+        Some(handle) => {
+            tokio::task::block_in_place(|| handle.block_on(Config::load_with_interpolation(true)))?
+        }
+        None => {
+            let rt = tokio::runtime::Runtime::new()?;
+            rt.block_on(Config::load_with_interpolation(true))?
+        }
+    };
+    AppConfig::from_config(cfg)
+}
+
 pub(super) fn role_completer(current: &OsStr) -> Vec<CompletionCandidate> {
     let cur = current.to_string_lossy();
-    Config::list_roles(true)
+    paths::list_roles(true)
         .into_iter()
         .filter(|r| r.starts_with(&*cur))
         .map(CompletionCandidate::new)
@@ -62,7 +80,7 @@ pub(super) fn agent_completer(current: &OsStr) -> Vec<CompletionCandidate> {
 
 pub(super) fn rag_completer(current: &OsStr) -> Vec<CompletionCandidate> {
     let cur = current.to_string_lossy();
-    Config::list_rags()
+    paths::list_rags()
         .into_iter()
         .filter(|r| r.starts_with(&*cur))
         .map(CompletionCandidate::new)
@@ -71,31 +89,53 @@ pub(super) fn rag_completer(current: &OsStr) -> Vec<CompletionCandidate> {
 
 pub(super) fn macro_completer(current: &OsStr) -> Vec<CompletionCandidate> {
     let cur = current.to_string_lossy();
-    Config::list_macros()
+    paths::list_macros()
         .into_iter()
         .filter(|m| m.starts_with(&*cur))
         .map(CompletionCandidate::new)
         .collect()
 }
 
+fn extract_agent_from_args() -> Option<String> {
+    let args: Vec<String> = env::args().collect();
+    let mut i = 0;
+    while i < args.len() {
+        let arg = &args[i];
+
+        if let Some(value) = arg.strip_prefix("--agent=") {
+            return Some(value.to_string());
+        }
+
+        if (arg == "--agent" || arg == "-a") && i + 1 < args.len() {
+            return Some(args[i + 1].clone());
+        }
+
+        i += 1;
+    }
+    None
+}
+
 pub(super) fn session_completer(current: &OsStr) -> Vec<CompletionCandidate> {
     let cur = current.to_string_lossy();
-    match Config::init_bare() {
-        Ok(config) => config
-            .list_sessions()
-            .into_iter()
-            .filter(|s| s.starts_with(&*cur))
-            .map(CompletionCandidate::new)
-            .collect(),
-        Err(_) => vec![],
-    }
+
+    let sessions = if let Some(agent_name) = extract_agent_from_args() {
+        let sessions_dir = paths::agent_data_dir(&agent_name).join("sessions");
+        list_file_names(sessions_dir, ".yaml")
+    } else {
+        list_sessions()
+    };
+
+    sessions
+        .into_iter()
+        .filter(|s| s.starts_with(&*cur))
+        .map(CompletionCandidate::new)
+        .collect()
 }
 
 pub(super) fn secrets_completer(current: &OsStr) -> Vec<CompletionCandidate> {
     let cur = current.to_string_lossy();
-    match Config::init_bare() {
-        Ok(config) => config
-            .vault
+    match load_app_config_for_completion() {
+        Ok(app_config) => Vault::init(&app_config)
             .list_secrets(false)
             .unwrap_or_default()
             .into_iter()
diff --git a/src/cli/mod.rs b/src/cli/mod.rs
index 2f4f8fb..0fb8e24 100644
--- a/src/cli/mod.rs
+++ b/src/cli/mod.rs
@@ -4,9 +4,10 @@ use crate::cli::completer::{
     ShellCompletion, agent_completer, macro_completer, model_completer, rag_completer,
     role_completer, secrets_completer, session_completer,
 };
+use crate::config::{AssetCategory, InstallFilter};
 use anyhow::{Context, Result};
 use clap::ValueHint;
-use clap::{Parser, crate_authors, crate_description, crate_name, crate_version};
+use clap::{Parser, crate_authors, crate_description, crate_version};
 use clap_complete::ArgValueCompleter;
 use is_terminal::IsTerminal;
 use std::io::{Read, stdin};
@@ -14,7 +15,7 @@ use std::io::{Read, stdin};
 #[derive(Parser, Debug)]
 #[command(author, version, about, long_about = None)]
 #[command(
-	name = crate_name!(),
+	name = "loki",
 	author = crate_authors!(),
 	version = crate_version!(),
 	about = crate_description!(),
@@ -82,6 +83,18 @@ pub struct Cli {
     /// Build all configured Bash tool scripts
     #[arg(long)]
     pub build_tools: bool,
+    /// Reinstall bundled assets, overwriting any local changes
+    #[arg(long, value_name = "CATEGORY", value_enum)]
+    pub install: Option<AssetCategory>,
+    /// Install assets from a remote git repository (URL may be suffixed with #<ref>)
+    #[arg(long, value_name = "GIT_URL")]
+    pub install_from: Option<String>,
+    /// Restrict --install-from to a single asset category
+    #[arg(long, value_name = "CATEGORY", value_enum, requires = "install_from")]
+    pub filter: Option<InstallFilter>,
+    /// Overwrite all conflicts without prompting (used with --install-from)
+    #[arg(long, requires = "install_from")]
+    pub install_force: bool,
     /// Sync models updates
     #[arg(long)]
     pub sync_models: bool,
@@ -133,6 +146,12 @@ pub struct Cli {
     /// Generate static shell completion scripts
     #[arg(long, value_name = "SHELL", value_enum)]
     pub completions: Option<ShellCompletion>,
+    /// Update Loki to the latest release, or to a specific version
+    #[arg(long, value_name = "VERSION")]
+    pub update: Option<Option<String>>,
+    /// With --update, update even if Loki was installed via a package manager
+    #[arg(long, requires = "update")]
+    pub force: bool,
 }
 
 impl Cli {
@@ -176,3 +195,247 @@ impl Cli {
         }
     }
 }
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use clap::Parser;
+
+    fn parse(args: &[&str]) -> Cli {
+        let mut full_args = vec!["loki"];
+        full_args.extend_from_slice(args);
+        Cli::try_parse_from(full_args).unwrap()
+    }
+
+    #[test]
+    fn parse_no_args_defaults() {
+        let cli = parse(&[]);
+        assert!(cli.model.is_none());
+        assert!(cli.role.is_none());
+        assert!(cli.session.is_none());
+        assert!(cli.agent.is_none());
+        assert!(!cli.execute);
+        assert!(!cli.code);
+        assert!(!cli.no_stream);
+        assert!(!cli.dry_run);
+        assert!(!cli.info);
+        assert!(!cli.build_tools);
+        assert!(cli.file.is_empty());
+        assert!(cli.text.is_empty());
+    }
+
+    #[test]
+    fn parse_model_flag() {
+        let cli = parse(&["--model", "gpt-4o"]);
+        assert_eq!(cli.model, Some("gpt-4o".to_string()));
+    }
+
+    #[test]
+    fn parse_model_short_flag() {
+        let cli = parse(&["-m", "gpt-4o"]);
+        assert_eq!(cli.model, Some("gpt-4o".to_string()));
+    }
+
+    #[test]
+    fn parse_role_flag() {
+        let cli = parse(&["--role", "coder"]);
+        assert_eq!(cli.role, Some("coder".to_string()));
+    }
+
+    #[test]
+    fn parse_session_with_name() {
+        let cli = parse(&["--session", "my-session"]);
+        assert_eq!(cli.session, Some(Some("my-session".to_string())));
+    }
+
+    #[test]
+    fn parse_agent_flag() {
+        let cli = parse(&["--agent", "sisyphus"]);
+        assert_eq!(cli.agent, Some("sisyphus".to_string()));
+    }
+
+    #[test]
+    fn parse_agent_short_flag() {
+        let cli = parse(&["-a", "sisyphus"]);
+        assert_eq!(cli.agent, Some("sisyphus".to_string()));
+    }
+
+    #[test]
+    fn parse_execute_flag() {
+        let cli = parse(&["-e", "list files"]);
+        assert!(cli.execute);
+    }
+
+    #[test]
+    fn parse_code_flag() {
+        let cli = parse(&["-c", "hello world"]);
+        assert!(cli.code);
+    }
+
+    #[test]
+    fn parse_no_stream_flag() {
+        let cli = parse(&["-S", "test"]);
+        assert!(cli.no_stream);
+    }
+
+    #[test]
+    fn parse_dry_run_flag() {
+        let cli = parse(&["--dry-run", "test"]);
+        assert!(cli.dry_run);
+    }
+
+    #[test]
+    fn parse_info_flag() {
+        let cli = parse(&["--info"]);
+        assert!(cli.info);
+    }
+
+    #[test]
+    fn parse_list_flags() {
+        assert!(parse(&["--list-models"]).list_models);
+        assert!(parse(&["--list-roles"]).list_roles);
+        assert!(parse(&["--list-sessions"]).list_sessions);
+        assert!(parse(&["--list-agents"]).list_agents);
+        assert!(parse(&["--list-rags"]).list_rags);
+        assert!(parse(&["--list-macros"]).list_macros);
+    }
+
+    #[test]
+    fn parse_file_flag_single() {
+        let cli = parse(&["-f", "file.txt", "question"]);
+        assert_eq!(cli.file, vec!["file.txt"]);
+    }
+
+    #[test]
+    fn parse_file_flag_multiple() {
+        let cli = parse(&["-f", "a.txt", "-f", "b.txt", "question"]);
+        assert_eq!(cli.file, vec!["a.txt", "b.txt"]);
+    }
+
+    #[test]
+    fn parse_trailing_text() {
+        let cli = parse(&["hello", "world"]);
+        assert_eq!(cli.text, vec!["hello", "world"]);
+    }
+
+    #[test]
+    fn parse_prompt_flag() {
+        let cli = parse(&["--prompt", "be a pirate"]);
+        assert_eq!(cli.prompt, Some("be a pirate".to_string()));
+    }
+
+    #[test]
+    fn parse_empty_session_flag() {
+        let cli = parse(&["--session", "s", "--empty-session"]);
+        assert!(cli.empty_session);
+    }
+
+    #[test]
+    fn parse_save_session_flag() {
+        let cli = parse(&["--session", "s", "--save-session"]);
+        assert!(cli.save_session);
+    }
+
+    #[test]
+    fn parse_build_tools_flag() {
+        let cli = parse(&["--build-tools"]);
+        assert!(cli.build_tools);
+    }
+
+    #[test]
+    fn parse_sync_models_flag() {
+        let cli = parse(&["--sync-models"]);
+        assert!(cli.sync_models);
+    }
+
+    #[test]
+    fn parse_model_with_role() {
+        let cli = parse(&["-m", "gpt-4o", "-r", "coder"]);
+        assert_eq!(cli.model, Some("gpt-4o".to_string()));
+        assert_eq!(cli.role, Some("coder".to_string()));
+    }
+
+    #[test]
+    fn parse_agent_with_file_and_text() {
+        let cli = parse(&["-a", "sisyphus", "-f", "code.rs", "explain", "this"]);
+        assert_eq!(cli.agent, Some("sisyphus".to_string()));
+        assert_eq!(cli.file, vec!["code.rs"]);
+        assert_eq!(cli.text, vec!["explain", "this"]);
+    }
+
+    #[test]
+    fn parse_role_with_session() {
+        let cli = parse(&["-r", "coder", "-s", "dev-session"]);
+        assert_eq!(cli.role, Some("coder".to_string()));
+        assert_eq!(cli.session, Some(Some("dev-session".to_string())));
+    }
+
+    #[test]
+    fn cli_text_returns_none_when_no_text_no_stdin() {
+        let cli = parse(&[]);
+        assert!(cli.text().unwrap().is_none());
+    }
+
+    #[test]
+    fn cli_text_joins_trailing_args() {
+        let cli = parse(&["hello", "world"]);
+        assert_eq!(cli.text().unwrap(), Some("hello world".to_string()));
+    }
+
+    #[test]
+    fn parse_add_secret_flag() {
+        let cli = parse(&["--add-secret", "MY_KEY"]);
+        assert_eq!(cli.add_secret, Some("MY_KEY".to_string()));
+    }
+
+    #[test]
+    fn parse_get_secret_flag() {
+        let cli = parse(&["--get-secret", "MY_KEY"]);
+        assert_eq!(cli.get_secret, Some("MY_KEY".to_string()));
+    }
+
+    #[test]
+    fn parse_list_secrets_flag() {
+        let cli = parse(&["--list-secrets"]);
+        assert!(cli.list_secrets);
+    }
+
+    #[test]
+    fn parse_rag_flag() {
+        let cli = parse(&["--rag", "my-rag"]);
+        assert_eq!(cli.rag, Some("my-rag".to_string()));
+    }
+
+    #[test]
+    fn parse_macro_flag() {
+        let cli = parse(&["--macro", "my-macro"]);
+        assert_eq!(cli.macro_name, Some("my-macro".to_string()));
+    }
+
+    #[test]
+    fn parse_update_flag_no_value() {
+        let cli = parse(&["--update"]);
+
+        assert_eq!(cli.update, Some(None));
+    }
+
+    #[test]
+    fn parse_update_flag_with_version() {
+        let cli = parse(&["--update", "v0.4.0"]);
+
+        assert_eq!(cli.update, Some(Some("v0.4.0".to_string())));
+    }
+
+    #[test]
+    fn parse_update_with_force() {
+        let cli = parse(&["--update", "--force"]);
+
+        assert_eq!(cli.update, Some(None));
+        assert!(cli.force);
+    }
+
+    #[test]
+    fn parse_force_without_update_fails() {
+        assert!(Cli::try_parse_from(["loki", "--force"]).is_err());
+    }
+}
diff --git a/src/client/claude.rs b/src/client/claude.rs
index 9c266b4..ae84c53 100644
--- a/src/client/claude.rs
+++ b/src/client/claude.rs
@@ -117,33 +117,38 @@ async fn prepare_chat_completions(
 /// So this function injects the Claude Code system prompt into the request
 /// body to make it a valid request.
 fn inject_oauth_system_prompt(body: &mut Value) {
-    let prefix_block = json!({
-        "type": "text",
-        "text": CLAUDE_CODE_PREFIX,
-    });
-
-    match body.get("system") {
-        Some(Value::String(existing)) => {
-            let existing_block = json!({
-                "type": "text",
-                "text": existing,
-            });
-            body["system"] = json!([prefix_block, existing_block]);
-        }
-        Some(Value::Array(_)) => {
-            if let Some(arr) = body["system"].as_array_mut() {
-                let already_injected = arr
-                    .iter()
-                    .any(|block| block["text"].as_str() == Some(CLAUDE_CODE_PREFIX));
-                if !already_injected {
-                    arr.insert(0, prefix_block);
-                }
+    let existing_text = match body.get("system") {
+        Some(Value::String(s)) => {
+            if s.starts_with(CLAUDE_CODE_PREFIX) {
+                return;
             }
+            (!s.is_empty()).then(|| s.clone())
         }
-        _ => {
-            body["system"] = json!([prefix_block]);
+        Some(Value::Array(blocks)) => {
+            let already_injected = blocks.iter().any(|b| {
+                b.get("text")
+                    .and_then(|t| t.as_str())
+                    .map(|t| t.starts_with(CLAUDE_CODE_PREFIX))
+                    .unwrap_or(false)
+            });
+            if already_injected {
+                return;
+            }
+            let joined: Vec<String> = blocks
+                .iter()
+                .filter_map(|b| b.get("text").and_then(|t| t.as_str()).map(String::from))
+                .collect();
+            (!joined.is_empty()).then(|| joined.join("\n\n"))
         }
-    }
+        _ => None,
+    };
+
+    let merged = match existing_text {
+        Some(rest) => format!("{}\n\n{}", CLAUDE_CODE_PREFIX, rest),
+        None => CLAUDE_CODE_PREFIX.to_string(),
+    };
+
+    body["system"] = json!([{ "type": "text", "text": merged }]);
 }
 
 pub async fn claude_chat_completions(
diff --git a/src/client/common.rs b/src/client/common.rs
index 202d732..33fb8a7 100644
--- a/src/client/common.rs
+++ b/src/client/common.rs
@@ -1,7 +1,8 @@
 use super::*;
 
+use crate::config::{RenderMode, paths};
 use crate::{
-    config::{Config, GlobalConfig, Input},
+    config::{AppConfig, Input, RequestContext},
     function::{FunctionDeclaration, ToolCall, ToolResult, eval_tool_calls},
     render::render_stream,
     utils::*,
@@ -24,7 +25,7 @@ use tokio::sync::mpsc::unbounded_channel;
 pub const MODELS_YAML: &str = include_str!("../../models.yaml");
 
 pub static ALL_PROVIDER_MODELS: LazyLock<Vec<ProviderModels>> = LazyLock::new(|| {
-    Config::local_models_override()
+    paths::local_models_override()
         .ok()
         .unwrap_or_else(|| serde_yaml::from_str(MODELS_YAML).unwrap())
 });
@@ -37,7 +38,7 @@ static ESCAPE_SLASH_RE: LazyLock<Regex> = LazyLock::new(|| Regex::new(r"(?<!\\)/
 
 #[async_trait::async_trait]
 pub trait Client: Sync + Send {
-    fn global_config(&self) -> &GlobalConfig;
+    fn app_config(&self) -> &AppConfig;
 
     fn extra_config(&self) -> Option<&ExtraConfig>;
 
@@ -58,7 +59,7 @@ pub trait Client: Sync + Send {
         if let Some(proxy) = extra.and_then(|v| v.proxy.as_deref()) {
             builder = set_proxy(builder, proxy)?;
         }
-        if let Some(user_agent) = self.global_config().read().user_agent.as_ref() {
+        if let Some(user_agent) = self.app_config().user_agent.as_ref() {
             builder = builder.user_agent(user_agent);
         }
         let client = builder
@@ -69,7 +70,7 @@ pub trait Client: Sync + Send {
     }
 
     async fn chat_completions(&self, input: Input) -> Result<ChatCompletionsOutput> {
-        if self.global_config().read().dry_run {
+        if self.app_config().dry_run {
             let content = input.echo_messages();
             return Ok(ChatCompletionsOutput::new(&content));
         }
@@ -89,7 +90,7 @@ pub trait Client: Sync + Send {
         let input = input.clone();
         tokio::select! {
             ret = async {
-                if self.global_config().read().dry_run {
+                if self.app_config().dry_run {
                     let content = input.echo_messages();
                     handler.text(&content)?;
                     return Ok(());
@@ -413,10 +414,12 @@ pub async fn call_chat_completions(
     print: bool,
     extract_code: bool,
     client: &dyn Client,
+    ctx: &mut RequestContext,
     abort_signal: AbortSignal,
 ) -> Result<(String, Vec<ToolResult>)> {
-    let is_child_agent = client.global_config().read().current_depth > 0;
-    let spinner_message = if is_child_agent { "" } else { "Generating" };
+    let is_child_agent = ctx.current_depth > 0;
+    let suppress_spinner = is_child_agent || ctx.render_mode == RenderMode::Silent;
+    let spinner_message = if suppress_spinner { "" } else { "Generating" };
     let ret = abortable_run_with_spinner(
         client.chat_completions(input.clone()),
         spinner_message,
@@ -436,15 +439,13 @@ pub async fn call_chat_completions(
                     text = extract_code_block(&strip_think_tag(&text)).to_string();
                 }
                 if print {
-                    client.global_config().read().print_markdown(&text)?;
+                    ctx.app.config.print_markdown(&text)?;
                 }
             }
-            let tool_results = eval_tool_calls(client.global_config(), tool_calls).await?;
-            if let Some(tracker) = client.global_config().write().tool_call_tracker.as_mut() {
-                tool_results
-                    .iter()
-                    .for_each(|res| tracker.record_call(res.call.clone()));
-            }
+            let tool_results = eval_tool_calls(ctx, tool_calls).await?;
+            tool_results
+                .iter()
+                .for_each(|res| ctx.tool_scope.tool_tracker.record_call(res.call.clone()));
             Ok((text, tool_results))
         }
         Err(err) => Err(err),
@@ -454,14 +455,19 @@ pub async fn call_chat_completions(
 pub async fn call_chat_completions_streaming(
     input: &Input,
     client: &dyn Client,
+    ctx: &mut RequestContext,
     abort_signal: AbortSignal,
 ) -> Result<(String, Vec<ToolResult>)> {
     let (tx, rx) = unbounded_channel();
     let mut handler = SseHandler::new(tx, abort_signal.clone());
+    let silent = ctx.render_mode == RenderMode::Silent;
+    if silent {
+        handler.set_silent(true);
+    }
 
     let (send_ret, render_ret) = tokio::join!(
         client.chat_completions_streaming(input, &mut handler),
-        render_stream(rx, client.global_config(), abort_signal.clone()),
+        render_stream(rx, client.app_config(), abort_signal.clone(), silent),
     );
 
     if handler.abort().aborted() {
@@ -476,12 +482,10 @@ pub async fn call_chat_completions_streaming(
             if !text.is_empty() && !text.ends_with('\n') {
                 println!();
             }
-            let tool_results = eval_tool_calls(client.global_config(), tool_calls).await?;
-            if let Some(tracker) = client.global_config().write().tool_call_tracker.as_mut() {
-                tool_results
-                    .iter()
-                    .for_each(|res| tracker.record_call(res.call.clone()));
-            }
+            let tool_results = eval_tool_calls(ctx, tool_calls).await?;
+            tool_results
+                .iter()
+                .for_each(|res| ctx.tool_scope.tool_tracker.record_call(res.call.clone()));
             Ok((text, tool_results))
         }
         Err(err) => {
diff --git a/src/client/macros.rs b/src/client/macros.rs
index 0c8ac9d..8e8bbe4 100644
--- a/src/client/macros.rs
+++ b/src/client/macros.rs
@@ -24,7 +24,7 @@ macro_rules! register_client {
         $(
             #[derive(Debug)]
             pub struct $client {
-                global_config: $crate::config::GlobalConfig,
+                app_config: std::sync::Arc<$crate::config::AppConfig>,
                 config: $config,
                 model: $crate::client::Model,
             }
@@ -32,8 +32,8 @@ macro_rules! register_client {
             impl $client {
                 pub const NAME: &'static str = $name;
 
-                pub fn init(global_config: &$crate::config::GlobalConfig, model: &$crate::client::Model) -> Option<Box<dyn Client>> {
-                    let config = global_config.read().clients.iter().find_map(|client_config| {
+                pub fn init(app_config: &std::sync::Arc<$crate::config::AppConfig>, model: &$crate::client::Model) -> Option<Box<dyn Client>> {
+                    let config = app_config.clients.iter().find_map(|client_config| {
                         if let ClientConfig::$config(c) = client_config {
                             if Self::name(c) == model.client_name() {
                                 return Some(c.clone())
@@ -43,7 +43,7 @@ macro_rules! register_client {
                     })?;
 
                     Some(Box::new(Self {
-                        global_config: global_config.clone(),
+                        app_config: std::sync::Arc::clone(app_config),
                         config,
                         model: model.clone(),
                     }))
@@ -72,10 +72,9 @@ macro_rules! register_client {
 
         )+
 
-        pub fn init_client(config: &$crate::config::GlobalConfig, model: Option<$crate::client::Model>) -> anyhow::Result<Box<dyn Client>> {
-            let model = model.unwrap_or_else(|| config.read().model.clone());
+        pub fn init_client(app_config: &std::sync::Arc<$crate::config::AppConfig>, model: $crate::client::Model) -> anyhow::Result<Box<dyn Client>> {
             None
-            $(.or_else(|| $client::init(config, &model)))+
+            $(.or_else(|| $client::init(app_config, &model)))+
             .ok_or_else(|| {
                 anyhow::anyhow!("Invalid model '{}'", model.id())
             })
@@ -101,7 +100,7 @@ macro_rules! register_client {
 
         static ALL_CLIENT_NAMES: std::sync::OnceLock<Vec<String>> = std::sync::OnceLock::new();
 
-        pub fn list_client_names(config: &$crate::config::Config) -> Vec<&'static String> {
+        pub fn list_client_names(config: &$crate::config::AppConfig) -> Vec<&'static String> {
             let names = ALL_CLIENT_NAMES.get_or_init(|| {
                 config
                     .clients
@@ -117,7 +116,7 @@ macro_rules! register_client {
 
         static ALL_MODELS: std::sync::OnceLock<Vec<$crate::client::Model>> = std::sync::OnceLock::new();
 
-        pub fn list_all_models(config: &$crate::config::Config) -> Vec<&'static $crate::client::Model> {
+        pub fn list_all_models(config: &$crate::config::AppConfig) -> Vec<&'static $crate::client::Model> {
             let models = ALL_MODELS.get_or_init(|| {
                 config
                     .clients
@@ -131,7 +130,7 @@ macro_rules! register_client {
             models.iter().collect()
         }
 
-        pub fn list_models(config: &$crate::config::Config, model_type: $crate::client::ModelType) -> Vec<&'static $crate::client::Model> {
+        pub fn list_models(config: &$crate::config::AppConfig, model_type: $crate::client::ModelType) -> Vec<&'static $crate::client::Model> {
             list_all_models(config).into_iter().filter(|v| v.model_type() == model_type).collect()
         }
     };
@@ -140,8 +139,8 @@ macro_rules! register_client {
 #[macro_export]
 macro_rules! client_common_fns {
     () => {
-        fn global_config(&self) -> &$crate::config::GlobalConfig {
-            &self.global_config
+        fn app_config(&self) -> &$crate::config::AppConfig {
+            &self.app_config
         }
 
         fn extra_config(&self) -> Option<&$crate::client::ExtraConfig> {
diff --git a/src/client/message.rs b/src/client/message.rs
index 3fded76..f73b1b9 100644
--- a/src/client/message.rs
+++ b/src/client/message.rs
@@ -94,21 +94,21 @@ impl MessageContent {
         match self {
             MessageContent::Text(text) => multiline_text(text),
             MessageContent::Array(list) => {
-                let (mut concated_text, mut files) = (String::new(), vec![]);
+                let (mut concatenated_text, mut files) = (String::new(), vec![]);
                 for item in list {
                     match item {
                         MessageContentPart::Text { text } => {
-                            concated_text = format!("{concated_text} {text}")
+                            concatenated_text = format!("{concatenated_text} {text}")
                         }
                         MessageContentPart::ImageUrl { image_url } => {
                             files.push(resolve_url_fn(&image_url.url))
                         }
                     }
                 }
-                if !concated_text.is_empty() {
-                    concated_text = format!(" -- {}", multiline_text(&concated_text))
+                if !concatenated_text.is_empty() {
+                    concatenated_text = format!(" -- {}", multiline_text(&concatenated_text))
                 }
-                format!(".file {}{}", files.join(" "), concated_text)
+                format!(".file {}{}", files.join(" "), concatenated_text)
             }
             MessageContent::ToolCalls(MessageContentToolCalls {
                 tool_results, text, ..
@@ -227,9 +227,14 @@ pub fn patch_messages(messages: &mut Vec<Message>, model: &Model) {
 }
 
 pub fn extract_system_message(messages: &mut Vec<Message>) -> Option<String> {
+    if messages.is_empty() {
+        return None;
+    }
+
     if messages[0].role.is_system() {
         let system_message = messages.remove(0);
         return Some(system_message.content.to_text());
     }
+
     None
 }
diff --git a/src/client/model.rs b/src/client/model.rs
index c55c045..325ce47 100644
--- a/src/client/model.rs
+++ b/src/client/model.rs
@@ -3,7 +3,7 @@ use super::{
     message::{Message, MessageContent, MessageContentPart},
 };
 
-use crate::config::Config;
+use crate::config::AppConfig;
 use crate::utils::{estimate_token_length, strip_think_tag};
 
 use anyhow::{Result, bail};
@@ -44,7 +44,11 @@ impl Model {
             .collect()
     }
 
-    pub fn retrieve_model(config: &Config, model_id: &str, model_type: ModelType) -> Result<Self> {
+    pub fn retrieve_model(
+        config: &AppConfig,
+        model_id: &str,
+        model_type: ModelType,
+    ) -> Result<Self> {
         let models = list_all_models(config);
         let (client_name, model_name) = match model_id.split_once(':') {
             Some((client_name, model_name)) => {
diff --git a/src/client/oauth.rs b/src/client/oauth.rs
index 6390dc3..0a9555f 100644
--- a/src/client/oauth.rs
+++ b/src/client/oauth.rs
@@ -1,6 +1,6 @@
 use super::ClientConfig;
 use super::access_token::{is_valid_access_token, set_access_token};
-use crate::config::Config;
+use crate::config::paths;
 use anyhow::{Result, anyhow, bail};
 use base64::Engine;
 use base64::engine::general_purpose::URL_SAFE_NO_PAD;
@@ -178,13 +178,13 @@ pub async fn run_oauth_flow(provider: &dyn OAuthProvider, client_name: &str) ->
 }
 
 pub fn load_oauth_tokens(client_name: &str) -> Option<OAuthTokens> {
-    let path = Config::token_file(client_name);
+    let path = paths::token_file(client_name);
     let content = fs::read_to_string(path).ok()?;
     serde_json::from_str(&content).ok()
 }
 
 fn save_oauth_tokens(client_name: &str, tokens: &OAuthTokens) -> Result<()> {
-    let path = Config::token_file(client_name);
+    let path = paths::token_file(client_name);
     if let Some(parent) = path.parent() {
         fs::create_dir_all(parent)?;
     }
diff --git a/src/client/stream.rs b/src/client/stream.rs
index 3780d93..daf308e 100644
--- a/src/client/stream.rs
+++ b/src/client/stream.rs
@@ -2,9 +2,9 @@ use super::{ToolCall, catch_error};
 use crate::utils::AbortSignal;
 
 use anyhow::{Context, Result, anyhow, bail};
+use eventsource_stream::Eventsource;
 use futures_util::{Stream, StreamExt};
-use reqwest::RequestBuilder;
-use reqwest_eventsource::{Error as EventSourceError, Event, RequestBuilderExt};
+use reqwest::{RequestBuilder, header};
 use serde_json::Value;
 use tokio::sync::mpsc::UnboundedSender;
 
@@ -16,6 +16,7 @@ pub struct SseHandler {
     last_tool_calls: Vec<ToolCall>,
     max_call_repeats: usize,
     call_repeat_chain_len: usize,
+    silent: bool,
 }
 
 impl SseHandler {
@@ -28,14 +29,24 @@ impl SseHandler {
             last_tool_calls: Vec::new(),
             max_call_repeats: 2,
             call_repeat_chain_len: 3,
+            silent: false,
         }
     }
 
+    pub fn set_silent(&mut self, silent: bool) {
+        self.silent = silent;
+    }
+
     pub fn text(&mut self, text: &str) -> Result<()> {
         if text.is_empty() {
             return Ok(());
         }
         self.buffer.push_str(text);
+
+        if self.silent {
+            return Ok(());
+        }
+
         let ret = self
             .sender
             .send(SseEvent::Text(text.to_string()))
@@ -193,11 +204,46 @@ pub async fn sse_stream<F>(builder: RequestBuilder, mut handle: F) -> Result<()>
 where
     F: FnMut(SseMessage) -> Result<bool>,
 {
-    let mut es = builder.eventsource()?;
+    let res = builder
+        .header(header::ACCEPT, "text/event-stream")
+        .header(header::CACHE_CONTROL, "no-store")
+        .send()
+        .await?;
+    let status = res.status();
+    if !status.is_success() {
+        let text = res.text().await?;
+        let data: Value = match text.parse() {
+            Ok(data) => data,
+            Err(_) => {
+                bail!(
+                    "Invalid response data: {text} (status: {})",
+                    status.as_u16()
+                );
+            }
+        };
+        catch_error(&data, status.as_u16())?;
+        return Ok(());
+    }
+
+    let content_type = res
+        .headers()
+        .get(header::CONTENT_TYPE)
+        .and_then(|value| value.to_str().ok())
+        .map(|value| value.to_string());
+    let is_event_stream = content_type
+        .as_deref()
+        .map(|ct| ct.starts_with("text/event-stream"))
+        .unwrap_or(false);
+    if !is_event_stream {
+        let header_value = content_type.unwrap_or_default();
+        let text = res.text().await?;
+        bail!("Invalid response event-stream. content-type: {header_value}, data: {text}");
+    }
+
+    let mut es = res.bytes_stream().boxed().eventsource();
     while let Some(event) = es.next().await {
         match event {
-            Ok(Event::Open) => {}
-            Ok(Event::Message(message)) => {
+            Ok(message) => {
                 let message = SseMessage {
                     event: message.event,
                     data: message.data,
@@ -207,33 +253,7 @@ where
                 }
             }
             Err(err) => {
-                match err {
-                    EventSourceError::StreamEnded => {}
-                    EventSourceError::InvalidStatusCode(status, res) => {
-                        let text = res.text().await?;
-                        let data: Value = match text.parse() {
-                            Ok(data) => data,
-                            Err(_) => {
-                                bail!(
-                                    "Invalid response data: {text} (status: {})",
-                                    status.as_u16()
-                                );
-                            }
-                        };
-                        catch_error(&data, status.as_u16())?;
-                    }
-                    EventSourceError::InvalidContentType(header_value, res) => {
-                        let text = res.text().await?;
-                        bail!(
-                            "Invalid response event-stream. content-type: {}, data: {text}",
-                            header_value.to_str().unwrap_or_default()
-                        );
-                    }
-                    _ => {
-                        bail!("{}", err);
-                    }
-                }
-                es.close();
+                bail!("{err}");
             }
         }
     }
@@ -311,10 +331,8 @@ impl JsonStreamParser {
                     }
                     self.balances.push(ch);
                 }
-                '[' => {
-                    if self.start.is_some() {
-                        self.balances.push(ch);
-                    }
+                '[' if self.start.is_some() => {
+                    self.balances.push(ch);
                 }
                 '}' => {
                     self.balances.pop();
@@ -342,7 +360,7 @@ mod tests {
 
     use bytes::Bytes;
     use futures_util::stream;
-    use rand::Rng;
+    use rand::random_range;
     use serde_json::json;
 
     #[test]
@@ -392,10 +410,9 @@ mod tests {
     }
 
     fn split_chunks(text: &str) -> Vec<Vec<u8>> {
-        let mut rng = rand::rng();
         let len = text.len();
-        let cut1 = rng.random_range(1..len - 1);
-        let cut2 = rng.random_range(cut1 + 1..len);
+        let cut1 = random_range(1..len - 1);
+        let cut2 = random_range(cut1 + 1..len);
         let chunk1 = text.as_bytes()[..cut1].to_vec();
         let chunk2 = text.as_bytes()[cut1..cut2].to_vec();
         let chunk3 = text.as_bytes()[cut2..].to_vec();
diff --git a/src/config/agent.rs b/src/config/agent.rs
index 87490ba..c452c8c 100644
--- a/src/config/agent.rs
+++ b/src/config/agent.rs
@@ -1,4 +1,3 @@
-use super::todo::TodoList;
 use super::*;
 
 use crate::{
@@ -6,10 +5,14 @@ use crate::{
     function::{Functions, run_llm_function},
 };
 
+use super::rag_cache::RagKey;
+use crate::config::paths;
 use crate::config::prompts::{
     DEFAULT_SPAWN_INSTRUCTIONS, DEFAULT_TEAMMATE_INSTRUCTIONS, DEFAULT_TODO_INSTRUCTIONS,
     DEFAULT_USER_INTERACTION_INSTRUCTIONS,
 };
+use crate::graph::{Graph, GraphParser, NodeType};
+use crate::rag::RagInitConfig;
 use crate::vault::SECRET_RE;
 use anyhow::{Context, Result};
 use fancy_regex::Captures;
@@ -36,18 +39,16 @@ pub struct Agent {
     session_dynamic_instructions: Option<String>,
     functions: Functions,
     rag: Option<Arc<Rag>>,
+    graph_rags: HashMap<String, Arc<Rag>>,
     model: Model,
     vault: GlobalVault,
-    todo_list: TodoList,
-    continuation_count: usize,
-    last_continuation_response: Option<String>,
 }
 
 impl Agent {
-    pub fn install_builtin_agents() -> Result<()> {
+    pub fn install_builtin_agents(force: bool) -> Result<()> {
         info!(
             "Installing built-in agents in {}",
-            Config::agents_data_dir().display()
+            paths::agents_data_dir().display()
         );
 
         for file in AgentAssets::iter() {
@@ -56,7 +57,7 @@ impl Agent {
             let embedded_file = AgentAssets::get(&file)
                 .ok_or_else(|| anyhow!("Failed to load embedded agent file: {}", file.as_ref()))?;
             let content = unsafe { std::str::from_utf8_unchecked(&embedded_file.data) };
-            let file_path = Config::agents_data_dir().join(file.as_ref());
+            let file_path = paths::agents_data_dir().join(file.as_ref());
             let file_extension = file_path
                 .extension()
                 .and_then(OsStr::to_str)
@@ -64,7 +65,7 @@ impl Agent {
             #[cfg_attr(not(unix), expect(unused))]
             let is_script = matches!(file_extension.as_deref(), Some("sh") | Some("py"));
 
-            if file_path.exists() {
+            if file_path.exists() && !force {
                 debug!(
                     "Agent file already exists, skipping: {}",
                     file_path.display()
@@ -88,72 +89,69 @@ impl Agent {
     }
 
     pub async fn init(
-        config: &GlobalConfig,
+        app: &AppConfig,
+        app_state: &AppState,
+        current_model: &Model,
+        info_flag: bool,
         name: &str,
         abort_signal: AbortSignal,
     ) -> Result<Self> {
-        let agent_data_dir = Config::agent_data_dir(name);
-        let loaders = config.read().document_loaders.clone();
-        let rag_path = Config::agent_rag_file(name, DEFAULT_AGENT_NAME);
-        let config_path = Config::agent_config_file(name);
-        let mut agent_config = if config_path.exists() {
-            AgentConfig::load(&config_path)?
-        } else {
-            bail!("Agent config file not found at '{}'", config_path.display())
+        let agent_data_dir = paths::agent_data_dir(name);
+        let loaders = app.document_loaders.clone();
+        let rag_path = paths::agent_rag_file(name, DEFAULT_AGENT_NAME);
+        let config_path = paths::agent_config_file(name);
+        let graph_path = paths::agent_graph_file(name);
+        let mut graph_for_rag: Option<Graph> = None;
+        let mut agent_config = match (config_path.exists(), graph_path.exists()) {
+            (true, true) => bail!(
+                "Agent '{name}' has both config.yaml and graph.yaml. A graph agent \
+                 is defined by graph.yaml alone; a normal agent by config.yaml alone. \
+                 Remove one of the two files."
+            ),
+            (true, false) => AgentConfig::load(&config_path)?,
+            (false, true) => {
+                let parser = GraphParser::new(&agent_data_dir);
+                let graph = parser
+                    .load_from_file(&graph_path)
+                    .with_context(|| format!("Failed to load graph.yaml for agent '{name}'"))?;
+                let config = AgentConfig::from_graph(name, &graph);
+                graph_for_rag = Some(graph);
+                config
+            }
+            (false, false) => bail!(
+                "Agent '{name}' has neither a config.yaml nor a graph.yaml at '{}'",
+                agent_data_dir.display()
+            ),
         };
         let mut functions = Functions::init_agent(name, &agent_config.global_tools)?;
 
-        config.write().functions.clear_mcp_meta_functions();
-        let mcp_servers = if config.read().mcp_server_support {
-            (!agent_config.mcp_servers.is_empty()).then(|| agent_config.mcp_servers.join(","))
-        } else {
-            eprintln!(
-                "{}",
-                formatdoc!(
-                    "
-										This agent uses MCP servers, but MCP support is disabled.
-										To enable it, exit the agent and set 'mcp_server_support: true', then try again
-										"
-                )
-            );
-            None
-        };
+        agent_config.load_envs(app);
 
-        let registry = config
-            .write()
-            .mcp_registry
-            .take()
-            .with_context(|| "MCP registry should be populated")?;
-        let new_mcp_registry =
-            McpRegistry::reinit(registry, mcp_servers, abort_signal.clone()).await?;
-
-        if !new_mcp_registry.is_empty() {
-            functions.append_mcp_meta_functions(new_mcp_registry.list_started_servers());
-        }
-
-        config.write().mcp_registry = Some(new_mcp_registry);
-
-        agent_config.load_envs(&config.read());
-
-        let model = {
-            let config = config.read();
-            match agent_config.model_id.as_ref() {
-                Some(model_id) => Model::retrieve_model(&config, model_id, ModelType::Chat)?,
-                None => {
-                    if agent_config.temperature.is_none() {
-                        agent_config.temperature = config.temperature;
-                    }
-                    if agent_config.top_p.is_none() {
-                        agent_config.top_p = config.top_p;
-                    }
-                    config.current_model().clone()
+        let model = match agent_config.model_id.as_ref() {
+            Some(model_id) => Model::retrieve_model(app, model_id, ModelType::Chat)?,
+            None => {
+                if agent_config.temperature.is_none() {
+                    agent_config.temperature = app.temperature;
                 }
+                if agent_config.top_p.is_none() {
+                    agent_config.top_p = app.top_p;
+                }
+                current_model.clone()
             }
         };
 
         let rag = if rag_path.exists() {
-            Some(Arc::new(Rag::load(config, DEFAULT_AGENT_NAME, &rag_path)?))
-        } else if !agent_config.documents.is_empty() && !config.read().info_flag {
+            let key = RagKey::Agent(name.to_string());
+            let app_clone = app.clone();
+            let rag_path_clone = rag_path.clone();
+            let rag = app_state
+                .rag_cache
+                .load_with(key, || async move {
+                    Rag::load(&app_clone, DEFAULT_AGENT_NAME, &rag_path_clone)
+                })
+                .await?;
+            Some(rag)
+        } else if !agent_config.documents.is_empty() && !info_flag {
             let mut ans = false;
             if *IS_STDOUT_TERMINAL {
                 ans = Confirm::new("The agent has documents attached, init RAG?")
@@ -161,33 +159,19 @@ impl Agent {
                     .prompt()?;
             }
             if ans {
-                let mut document_paths = vec![];
-                for path in &agent_config.documents {
-                    if is_url(path) {
-                        document_paths.push(path.to_string());
-                    } else if is_loader_protocol(&loaders, path) {
-                        let (protocol, document_path) = path
-                            .split_once(':')
-                            .with_context(|| "Invalid loader protocol path")?;
-                        let resolved_path = resolve_home_dir(document_path);
-                        let new_path = if Path::new(&resolved_path).is_relative() {
-                            safe_join_path(&agent_data_dir, resolved_path)
-                                .ok_or_else(|| anyhow!("Invalid document path: '{path}'"))?
-                        } else {
-                            PathBuf::from(&resolved_path)
-                        };
-                        document_paths.push(format!("{}:{}", protocol, new_path.display()));
-                    } else if Path::new(&resolve_home_dir(path)).is_relative() {
-                        let new_path = safe_join_path(&agent_data_dir, path)
-                            .ok_or_else(|| anyhow!("Invalid document path: '{path}'"))?;
-                        document_paths.push(new_path.display().to_string())
-                    } else {
-                        document_paths.push(path.to_string())
-                    }
-                }
-                let rag =
-                    Rag::init(config, "rag", &rag_path, &document_paths, abort_signal).await?;
-                Some(Arc::new(rag))
+                let document_paths =
+                    resolve_document_paths(&agent_config.documents, &loaders, &agent_data_dir)?;
+                let key = RagKey::Agent(name.to_string());
+                let app_clone = app.clone();
+                let rag_path_clone = rag_path.clone();
+                let abort = abort_signal.clone();
+                let rag = app_state
+                    .rag_cache
+                    .load_with(key, || async move {
+                        Rag::init(&app_clone, "rag", &rag_path_clone, &document_paths, abort).await
+                    })
+                    .await?;
+                Some(rag)
             } else {
                 None
             }
@@ -195,6 +179,23 @@ impl Agent {
             None
         };
 
+        let graph_rags = match &graph_for_rag {
+            Some(graph) => {
+                init_graph_rags(
+                    app,
+                    app_state,
+                    name,
+                    graph,
+                    &agent_data_dir,
+                    &loaders,
+                    info_flag,
+                    abort_signal.clone(),
+                )
+                .await?
+            }
+            None => HashMap::new(),
+        };
+
         if agent_config.auto_continue {
             functions.append_todo_functions();
         }
@@ -217,11 +218,9 @@ impl Agent {
             session_dynamic_instructions: None,
             functions,
             rag,
+            graph_rags,
             model,
-            vault: Arc::clone(&config.read().vault),
-            todo_list: TodoList::default(),
-            continuation_count: 0,
-            last_continuation_response: None,
+            vault: app_state.vault.clone(),
         })
     }
 
@@ -295,14 +294,17 @@ impl Agent {
         let mut config = self.config.clone();
         config.instructions = self.interpolated_instructions();
         value["definition"] = json!(config);
-        value["data_dir"] = Config::agent_data_dir(&self.name)
-            .display()
-            .to_string()
-            .into();
-        value["config_file"] = Config::agent_config_file(&self.name)
+        value["data_dir"] = paths::agent_data_dir(&self.name)
             .display()
             .to_string()
             .into();
+        let config_path = paths::agent_config_file(&self.name);
+        let definition_file = if config_path.exists() {
+            config_path
+        } else {
+            paths::agent_graph_file(&self.name)
+        };
+        value["config_file"] = definition_file.display().to_string().into();
         let data = serde_yaml::to_string(&value)?;
         Ok(data)
     }
@@ -323,6 +325,18 @@ impl Agent {
         self.rag.clone()
     }
 
+    pub fn graph_rag(&self, node_id: &str) -> Option<Arc<Rag>> {
+        self.graph_rags.get(node_id).cloned()
+    }
+
+    pub fn append_mcp_meta_functions(&mut self, mcp_servers: Vec<String>) {
+        self.functions.append_mcp_meta_functions(mcp_servers);
+    }
+
+    pub fn mcp_server_names(&self) -> &[String] {
+        &self.config.mcp_servers
+    }
+
     pub fn conversation_starters(&self) -> Vec<String> {
         self.config
             .conversation_starters
@@ -419,6 +433,14 @@ impl Agent {
         self.config.max_auto_continues
     }
 
+    pub fn inject_todo_instructions(&self) -> bool {
+        self.config.inject_todo_instructions
+    }
+
+    pub fn continuation_prompt_value(&self) -> Option<String> {
+        self.config.continuation_prompt.clone()
+    }
+
     pub fn can_spawn_agents(&self) -> bool {
         self.config.can_spawn_agents
     }
@@ -443,56 +465,6 @@ impl Agent {
         self.config.escalation_timeout
     }
 
-    pub fn continuation_count(&self) -> usize {
-        self.continuation_count
-    }
-
-    pub fn increment_continuation(&mut self) {
-        self.continuation_count += 1;
-    }
-
-    pub fn reset_continuation(&mut self) {
-        self.continuation_count = 0;
-        self.last_continuation_response = None;
-    }
-
-    pub fn set_last_continuation_response(&mut self, response: String) {
-        self.last_continuation_response = Some(response);
-    }
-
-    pub fn todo_list(&self) -> &TodoList {
-        &self.todo_list
-    }
-
-    pub fn init_todo_list(&mut self, goal: &str) {
-        self.todo_list = TodoList::new(goal);
-    }
-
-    pub fn add_todo(&mut self, task: &str) -> usize {
-        self.todo_list.add(task)
-    }
-
-    pub fn mark_todo_done(&mut self, id: usize) -> bool {
-        self.todo_list.mark_done(id)
-    }
-
-    pub fn clear_todo_list(&mut self) {
-        self.todo_list.clear();
-        self.reset_continuation();
-    }
-
-    pub fn continuation_prompt(&self) -> String {
-        self.config.continuation_prompt.clone().unwrap_or_else(|| {
-            formatdoc! {"
-                [SYSTEM REMINDER - TODO CONTINUATION]
-                You have incomplete tasks. Rules:
-                1. BEFORE marking a todo done: verify the work compiles/works. No premature completion.
-                2. If a todo is broad (e.g. \"implement X and implement Y\"): break it into specific subtasks FIRST using todo__add, then work on those.\n\
-                3. Each todo should be atomic and be \"single responsibility\" - completable in one focused action.
-                4. Continue with the next pending item now. Call tools immediately."}
-        })
-    }
-
     pub fn compression_threshold(&self) -> Option<usize> {
         self.config.compression_threshold
     }
@@ -696,12 +668,31 @@ impl AgentConfig {
         Ok(agent_config)
     }
 
-    fn load_envs(&mut self, config: &Config) {
+    pub fn from_graph(dir_name: &str, graph: &Graph) -> Self {
+        AgentConfig {
+            name: dir_name.to_string(),
+            model_id: graph.model.clone(),
+            temperature: graph.temperature,
+            top_p: graph.top_p,
+            description: graph.description.clone(),
+            global_tools: graph.global_tools.clone(),
+            mcp_servers: graph.mcp_servers.clone(),
+            conversation_starters: graph.conversation_starters.clone(),
+            variables: graph.variables.clone(),
+            can_spawn_agents: graph.has_agent_node(),
+            max_concurrent_agents: default_max_concurrent_agents(),
+            max_agent_depth: default_max_agent_depth(),
+            escalation_timeout: default_escalation_timeout(),
+            ..AgentConfig::default()
+        }
+    }
+
+    fn load_envs(&mut self, app: &AppConfig) {
         let name = &self.name;
         let with_prefix = |v: &str| normalize_env_name(&format!("{name}_{v}"));
 
         if self.agent_session.is_none() {
-            self.agent_session = config.agent_session.clone();
+            self.agent_session = app.agent_session.clone();
         }
 
         if let Some(v) = read_env_value::<String>(&with_prefix("model")) {
@@ -792,8 +783,138 @@ pub struct AgentVariable {
     pub value: String,
 }
 
+fn resolve_document_paths(
+    documents: &[String],
+    loaders: &HashMap<String, String>,
+    agent_data_dir: &Path,
+) -> Result<Vec<String>> {
+    let mut document_paths = vec![];
+    for path in documents {
+        if is_url(path) {
+            document_paths.push(path.to_string());
+        } else if is_loader_protocol(loaders, path) {
+            let (protocol, document_path) = path
+                .split_once(':')
+                .with_context(|| "Invalid loader protocol path")?;
+            let resolved_path = resolve_home_dir(document_path);
+            let new_path = if Path::new(&resolved_path).is_relative() {
+                safe_join_path(agent_data_dir, resolved_path)
+                    .ok_or_else(|| anyhow!("Invalid document path: '{path}'"))?
+            } else {
+                PathBuf::from(&resolved_path)
+            };
+
+            document_paths.push(format!("{}:{}", protocol, new_path.display()));
+        } else if Path::new(&resolve_home_dir(path)).is_relative() {
+            let new_path = safe_join_path(agent_data_dir, path)
+                .ok_or_else(|| anyhow!("Invalid document path: '{path}'"))?;
+            document_paths.push(new_path.display().to_string())
+        } else {
+            document_paths.push(path.to_string())
+        }
+    }
+    Ok(document_paths)
+}
+
+#[allow(clippy::too_many_arguments)]
+async fn init_graph_rags(
+    app: &AppConfig,
+    app_state: &AppState,
+    agent_name: &str,
+    graph: &Graph,
+    agent_data_dir: &Path,
+    loaders: &HashMap<String, String>,
+    info_flag: bool,
+    abort_signal: AbortSignal,
+) -> Result<HashMap<String, Arc<Rag>>> {
+    let mut rags = HashMap::new();
+    if info_flag {
+        return Ok(rags);
+    }
+
+    for (node_id, node) in &graph.nodes {
+        let NodeType::Rag(rag_node) = &node.node_type else {
+            continue;
+        };
+        let rag_path = paths::agent_rag_file(agent_name, node_id);
+        let key = RagKey::GraphNode {
+            agent: agent_name.to_string(),
+            node: node_id.clone(),
+        };
+        let rag = if rag_path.exists() {
+            let app_clone = app.clone();
+            let path_clone = rag_path.clone();
+            let name_clone = node_id.clone();
+            app_state
+                .rag_cache
+                .load_with(key, || async move {
+                    Rag::load(&app_clone, &name_clone, &path_clone)
+                })
+                .await?
+        } else {
+            let config = RagInitConfig {
+                embedding_model: rag_node.embedding_model.clone(),
+                chunk_size: rag_node.chunk_size,
+                chunk_overlap: rag_node.chunk_overlap,
+                reranker_model: rag_node.reranker_model.clone(),
+                top_k: rag_node.top_k,
+                batch_size: rag_node.batch_size,
+            };
+            let fully_specified = config.embedding_model.is_some()
+                && config.chunk_size.is_some()
+                && config.chunk_overlap.is_some();
+            if !fully_specified {
+                if !*IS_STDOUT_TERMINAL {
+                    bail!(
+                        "Agent '{agent_name}' requires RAG for rag node '{node_id}', but its \
+                         knowledge base is not built and the node does not fully specify how \
+                         to build it. Set `embedding_model`, `chunk_size`, and `chunk_overlap` \
+                         on the node, or run the agent once interactively."
+                    );
+                }
+
+                let ans = Confirm::new(&format!(
+                    "Initialize RAG knowledge base for rag node '{node_id}'?"
+                ))
+                .with_default(true)
+                .prompt()?;
+
+                if !ans {
+                    bail!(
+                        "Agent '{agent_name}' has rag node '{node_id}' but its RAG was not \
+                         initialized. RAG initialization is required for this agent."
+                    );
+                }
+            }
+
+            let document_paths =
+                resolve_document_paths(&rag_node.documents, loaders, agent_data_dir)?;
+            let app_clone = app.clone();
+            let path_clone = rag_path.clone();
+            let name_clone = node_id.clone();
+            let abort = abort_signal.clone();
+            app_state
+                .rag_cache
+                .load_with(key, || async move {
+                    Rag::init_with_config(
+                        &app_clone,
+                        &name_clone,
+                        &path_clone,
+                        &document_paths,
+                        &config,
+                        abort,
+                    )
+                    .await
+                })
+                .await?
+        };
+        rags.insert(node_id.clone(), rag);
+    }
+    Ok(rags)
+}
+
 pub fn list_agents() -> Vec<String> {
-    let agents_data_dir = Config::agents_data_dir();
+    let agents_data_dir = paths::agents_data_dir();
     if !agents_data_dir.exists() {
         return vec![];
     }
@@ -803,6 +924,7 @@ pub fn list_agents() -> Vec<String> {
         for entry in entries.flatten() {
             if entry.path().is_dir()
                 && let Some(name) = entry.file_name().to_str()
+                && !name.starts_with('.')
             {
                 agents.push(name.to_string());
             }
@@ -813,7 +935,7 @@ pub fn list_agents() -> Vec<String> {
 }
 
 pub fn complete_agent_variables(agent_name: &str) -> Vec<(String, Option<String>)> {
-    let config_path = Config::agent_config_file(agent_name);
+    let config_path = paths::agent_config_file(agent_name);
     if !config_path.exists() {
         return vec![];
     }
@@ -832,3 +954,173 @@ pub fn complete_agent_variables(agent_name: &str) -> Vec<(String, Option<String>
         })
         .collect()
 }
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn agent_config_parses_from_yaml() {
+        let yaml = r#"
+name: test-agent
+description: A test agent
+instructions: You are helpful
+auto_continue: true
+max_auto_continues: 5
+can_spawn_agents: true
+max_concurrent_agents: 8
+max_agent_depth: 2
+mcp_servers:
+  - github
+  - jira
+global_tools:
+  - execute_command.sh
+  - fs_read.sh
+conversation_starters:
+  - "Hello!"
+  - "How are you?"
+variables:
+  - name: username
+    description: Your name
+"#;
+
+        let config: AgentConfig = serde_yaml::from_str(yaml).unwrap();
+
+        assert_eq!(config.name, "test-agent");
+        assert_eq!(config.description, "A test agent");
+        assert!(config.auto_continue);
+        assert_eq!(config.max_auto_continues, 5);
+        assert!(config.can_spawn_agents);
+        assert_eq!(config.max_concurrent_agents, 8);
+        assert_eq!(config.max_agent_depth, 2);
+        assert_eq!(config.mcp_servers, vec!["github", "jira"]);
+        assert_eq!(config.global_tools.len(), 2);
+        assert_eq!(config.conversation_starters.len(), 2);
+        assert_eq!(config.variables.len(), 1);
+        assert_eq!(config.variables[0].name, "username");
+    }
+
+    #[test]
+    fn agent_config_defaults() {
+        let yaml = "name: minimal\ninstructions: hi\n";
+        let config: AgentConfig = serde_yaml::from_str(yaml).unwrap();
+
+        assert_eq!(config.name, "minimal");
+        assert!(!config.auto_continue);
+        assert!(!config.can_spawn_agents);
+        assert_eq!(config.max_concurrent_agents, 4);
+        assert_eq!(config.max_agent_depth, 3);
+        assert_eq!(config.max_auto_continues, 10);
+        assert!(config.mcp_servers.is_empty());
+        assert!(config.global_tools.is_empty());
+        assert!(config.conversation_starters.is_empty());
+        assert!(config.variables.is_empty());
+        assert!(config.model_id.is_none());
+        assert!(config.temperature.is_none());
+        assert!(config.top_p.is_none());
+    }
+
+    #[test]
+    fn agent_config_with_model() {
+        let yaml =
+            "name: test\nmodel: openai:gpt-4\ntemperature: 0.7\ntop_p: 0.9\ninstructions: hi\n";
+        let config: AgentConfig = serde_yaml::from_str(yaml).unwrap();
+
+        assert_eq!(config.model_id, Some("openai:gpt-4".to_string()));
+        assert_eq!(config.temperature, Some(0.7));
+        assert_eq!(config.top_p, Some(0.9));
+    }
+
+    #[test]
+    fn agent_config_inject_defaults_true() {
+        let yaml = "name: test\ninstructions: hi\n";
+        let config: AgentConfig = serde_yaml::from_str(yaml).unwrap();
+
+        assert!(config.inject_todo_instructions);
+        assert!(config.inject_spawn_instructions);
+    }
+
+    #[test]
+    fn from_graph_maps_agent_level_fields() {
+        let yaml = formatdoc! {r#"
+            name: graph_name_ignored
+            description: A graph agent
+            model: claude:claude-sonnet-4-6
+            temperature: 0.3
+            top_p: 0.8
+            global_tools:
+              - fetch_pdf.sh
+            mcp_servers:
+              - pubmed-search
+            conversation_starters:
+              - "Start here"
+            start: e
+            nodes:
+              e:
+                id: e
+                type: end
+                output: done
+            "#};
+        let graph: Graph = serde_yaml::from_str(&yaml).unwrap();
+
+        let config = AgentConfig::from_graph("my-agent-dir", &graph);
+
+        assert_eq!(config.name, "my-agent-dir");
+        assert_eq!(config.description, "A graph agent");
+        assert_eq!(config.model_id.as_deref(), Some("claude:claude-sonnet-4-6"));
+        assert_eq!(config.temperature, Some(0.3));
+        assert_eq!(config.top_p, Some(0.8));
+        assert_eq!(config.global_tools, vec!["fetch_pdf.sh"]);
+        assert_eq!(config.mcp_servers, vec!["pubmed-search"]);
+        assert_eq!(config.conversation_starters, vec!["Start here"]);
+    }
+
+    #[test]
+    fn from_graph_derives_can_spawn_agents_from_agent_nodes() {
+        let with_agent = formatdoc! {r#"
+            name: g
+            start: a
+            nodes:
+              a:
+                id: a
+                type: agent
+                agent: helper
+                prompt: hi
+                next: e
+              e:
+                id: e
+                type: end
+                output: done
+            "#};
+        let graph: Graph = serde_yaml::from_str(&with_agent).unwrap();
+        assert!(AgentConfig::from_graph("d", &graph).can_spawn_agents);
+
+        let no_agent =
+            "name: g\nstart: x\nnodes:\n  x:\n    id: x\n    type: end\n    output: ok\n";
+        let graph: Graph = serde_yaml::from_str(no_agent).unwrap();
+        assert!(!AgentConfig::from_graph("d", &graph).can_spawn_agents);
+    }
+
+    #[test]
+    fn from_graph_keeps_defaults_for_llm_loop_fields() {
+        let yaml = "name: g\nstart: x\nnodes:\n  x:\n    id: x\n    type: end\n    output: ok\n";
+        let graph: Graph = serde_yaml::from_str(yaml).unwrap();
+
+        let config = AgentConfig::from_graph("d", &graph);
+
+        assert!(!config.auto_continue);
+        assert!(config.instructions.is_empty());
+        assert!(config.documents.is_empty());
+        assert!(!config.inject_todo_instructions);
+        assert!(!config.inject_spawn_instructions);
+        assert_eq!(config.max_auto_continues, 0);
+        assert_eq!(config.summarization_threshold, 0);
+
+        assert_eq!(
+            config.max_concurrent_agents,
+            default_max_concurrent_agents()
+        );
+        assert_eq!(config.max_agent_depth, default_max_agent_depth());
+        assert_eq!(config.escalation_timeout, default_escalation_timeout());
+    }
+}
diff --git a/src/config/app_config.rs b/src/config/app_config.rs
new file mode 100644
index 0000000..41fb193
--- /dev/null
+++ b/src/config/app_config.rs
@@ -0,0 +1,755 @@
+use crate::client::{ClientConfig, list_models};
+use crate::render::{MarkdownRender, RenderOptions};
+use crate::utils::{IS_STDOUT_TERMINAL, NO_COLOR, decode_bin, get_env_name};
+
+use super::paths;
+use anyhow::{Context, Result, anyhow};
+use indexmap::IndexMap;
+use serde::Deserialize;
+use std::collections::HashMap;
+use std::env;
+use std::path::PathBuf;
+use syntect::highlighting::ThemeSet;
+use terminal_colorsaurus::{ColorScheme, QueryOptions, color_scheme};
+
+#[derive(Debug, Clone, Deserialize)]
+#[serde(default)]
+pub struct AppConfig {
+    #[serde(rename(serialize = "model", deserialize = "model"))]
+    #[serde(default)]
+    pub model_id: String,
+    pub temperature: Option<f64>,
+    pub top_p: Option<f64>,
+
+    pub dry_run: bool,
+    pub stream: bool,
+    pub save: bool,
+    pub keybindings: String,
+    pub editor: Option<String>,
+    pub wrap: Option<String>,
+    pub wrap_code: bool,
+    pub(crate) vault_password_file: Option<PathBuf>,
+
+    pub function_calling_support: bool,
+    pub mapping_tools: IndexMap<String, String>,
+    pub enabled_tools: Option<String>,
+    pub visible_tools: Option<Vec<String>>,
+
+    pub mcp_server_support: bool,
+    pub mapping_mcp_servers: IndexMap<String, String>,
+    pub enabled_mcp_servers: Option<String>,
+
+    pub auto_continue: bool,
+    pub max_auto_continues: usize,
+    pub inject_todo_instructions: bool,
+    pub continuation_prompt: Option<String>,
+
+    pub repl_prelude: Option<String>,
+    pub cmd_prelude: Option<String>,
+    pub agent_session: Option<String>,
+
+    pub save_session: Option<bool>,
+    pub compression_threshold: usize,
+    pub summarization_prompt: Option<String>,
+    pub summary_context_prompt: Option<String>,
+
+    pub rag_embedding_model: Option<String>,
+    pub rag_reranker_model: Option<String>,
+    pub rag_top_k: usize,
+    pub rag_chunk_size: Option<usize>,
+    pub rag_chunk_overlap: Option<usize>,
+    pub rag_template: Option<String>,
+
+    #[serde(default)]
+    pub document_loaders: HashMap<String, String>,
+
+    pub highlight: bool,
+    pub theme: Option<String>,
+    pub left_prompt: Option<String>,
+    pub right_prompt: Option<String>,
+
+    pub user_agent: Option<String>,
+    pub save_shell_history: bool,
+    pub sync_models_url: Option<String>,
+
+    pub clients: Vec<ClientConfig>,
+}
+
+impl Default for AppConfig {
+    fn default() -> Self {
+        Self {
+            model_id: Default::default(),
+            temperature: None,
+            top_p: None,
+
+            dry_run: false,
+            stream: true,
+            save: false,
+            keybindings: "emacs".into(),
+            editor: None,
+            wrap: None,
+            wrap_code: false,
+            vault_password_file: None,
+
+            function_calling_support: true,
+            mapping_tools: Default::default(),
+            enabled_tools: None,
+            visible_tools: None,
+
+            mcp_server_support: true,
+            mapping_mcp_servers: Default::default(),
+            enabled_mcp_servers: None,
+
+            auto_continue: false,
+            max_auto_continues: 10,
+            inject_todo_instructions: true,
+            continuation_prompt: None,
+
+            repl_prelude: None,
+            cmd_prelude: None,
+            agent_session: None,
+
+            save_session: None,
+            compression_threshold: 4000,
+            summarization_prompt: None,
+            summary_context_prompt: None,
+
+            rag_embedding_model: None,
+            rag_reranker_model: None,
+            rag_top_k: 5,
+            rag_chunk_size: None,
+            rag_chunk_overlap: None,
+            rag_template: None,
+
+            document_loaders: Default::default(),
+
+            highlight: true,
+            theme: None,
+            left_prompt: None,
+            right_prompt: None,
+
+            user_agent: None,
+            save_shell_history: true,
+            sync_models_url: None,
+
+            clients: vec![],
+        }
+    }
+}
+
+impl AppConfig {
+    pub fn from_config(config: super::Config) -> Result<Self> {
+        let mut app_config = Self {
+            model_id: config.model_id,
+            temperature: config.temperature,
+            top_p: config.top_p,
+
+            dry_run: config.dry_run,
+            stream: config.stream,
+            save: config.save,
+            keybindings: config.keybindings,
+            editor: config.editor,
+            wrap: config.wrap,
+            wrap_code: config.wrap_code,
+            vault_password_file: config.vault_password_file,
+
+            function_calling_support: config.function_calling_support,
+            mapping_tools: config.mapping_tools,
+            enabled_tools: config.enabled_tools,
+            visible_tools: config.visible_tools,
+
+            mcp_server_support: config.mcp_server_support,
+            mapping_mcp_servers: config.mapping_mcp_servers,
+            enabled_mcp_servers: config.enabled_mcp_servers,
+
+            auto_continue: config.auto_continue,
+            max_auto_continues: config.max_auto_continues,
+            inject_todo_instructions: config.inject_todo_instructions,
+            continuation_prompt: config.continuation_prompt,
+
+            repl_prelude: config.repl_prelude,
+            cmd_prelude: config.cmd_prelude,
+            agent_session: config.agent_session,
+
+            save_session: config.save_session,
+            compression_threshold: config.compression_threshold,
+            summarization_prompt: config.summarization_prompt,
+            summary_context_prompt: config.summary_context_prompt,
+
+            rag_embedding_model: config.rag_embedding_model,
+            rag_reranker_model: config.rag_reranker_model,
+            rag_top_k: config.rag_top_k,
+            rag_chunk_size: config.rag_chunk_size,
+            rag_chunk_overlap: config.rag_chunk_overlap,
+            rag_template: config.rag_template,
+
+            document_loaders: config.document_loaders,
+
+            highlight: config.highlight,
+            theme: config.theme,
+            left_prompt: config.left_prompt,
+            right_prompt: config.right_prompt,
+
+            user_agent: config.user_agent,
+            save_shell_history: config.save_shell_history,
+            sync_models_url: config.sync_models_url,
+
+            clients: config.clients,
+        };
+        app_config.load_envs();
+        if let Some(wrap) = app_config.wrap.clone() {
+            app_config.set_wrap(&wrap)?;
+        }
+        app_config.setup_document_loaders();
+        app_config.setup_user_agent();
+        app_config.resolve_model()?;
+        Ok(app_config)
+    }
+
+    pub fn resolve_model(&mut self) -> Result<()> {
+        if self.model_id.is_empty() {
+            let models = list_models(self, crate::client::ModelType::Chat);
+            if models.is_empty() {
+                anyhow::bail!("No available model");
+            }
+            self.model_id = models[0].id();
+        }
+        Ok(())
+    }
+
+    pub fn vault_password_file(&self) -> PathBuf {
+        match &self.vault_password_file {
+            Some(path) => match path.exists() {
+                true => path.clone(),
+                false => gman::config::Config::local_provider_password_file(),
+            },
+            None => gman::config::Config::local_provider_password_file(),
+        }
+    }
+
+    pub fn editor(&self) -> Result<String> {
+        super::EDITOR.get_or_init(move || {
+            let editor = self.editor.clone()
+                .or_else(|| env::var("VISUAL").ok().or_else(|| env::var("EDITOR").ok()))
+                .unwrap_or_else(|| {
+                    if cfg!(windows) {
+                        "notepad".to_string()
+                    } else {
+                        "nano".to_string()
+                    }
+                });
+            which::which(&editor).ok().map(|_| editor)
+        })
+            .clone()
+            .ok_or_else(|| anyhow!("Editor not found. Please add the `editor` configuration or set the $EDITOR or $VISUAL environment variable."))
+    }
+
+    pub fn sync_models_url(&self) -> String {
+        self.sync_models_url
+            .clone()
+            .unwrap_or_else(|| super::SYNC_MODELS_URL.into())
+    }
+
+    pub fn light_theme(&self) -> bool {
+        matches!(self.theme.as_deref(), Some("light"))
+    }
+
+    pub fn render_options(&self) -> Result<RenderOptions> {
+        let theme = if self.highlight {
+            let theme_mode = if self.light_theme() { "light" } else { "dark" };
+            let theme_filename = format!("{theme_mode}.tmTheme");
+            let theme_path = paths::local_path(&theme_filename);
+            if theme_path.exists() {
+                let theme = ThemeSet::get_theme(&theme_path)
+                    .with_context(|| format!("Invalid theme at '{}'", theme_path.display()))?;
+                Some(theme)
+            } else {
+                let theme = if self.light_theme() {
+                    decode_bin(super::LIGHT_THEME).context("Invalid builtin light theme")?
+                } else {
+                    decode_bin(super::DARK_THEME).context("Invalid builtin dark theme")?
+                };
+                Some(theme)
+            }
+        } else {
+            None
+        };
+        let wrap = if *IS_STDOUT_TERMINAL {
+            self.wrap.clone()
+        } else {
+            None
+        };
+        let truecolor = matches!(
+            env::var("COLORTERM").as_ref().map(|v| v.as_str()),
+            Ok("truecolor")
+        );
+        Ok(RenderOptions::new(theme, wrap, self.wrap_code, truecolor))
+    }
+
+    pub fn print_markdown(&self, text: &str) -> Result<()> {
+        if *IS_STDOUT_TERMINAL {
+            let render_options = self.render_options()?;
+            let mut markdown_render = MarkdownRender::init(render_options)?;
+            println!("{}", markdown_render.render(text));
+        } else {
+            println!("{text}");
+        }
+        Ok(())
+    }
+}
+
+impl AppConfig {
+    pub fn set_wrap(&mut self, value: &str) -> Result<()> {
+        if value == "no" {
+            self.wrap = None;
+        } else if value == "auto" {
+            self.wrap = Some(value.into());
+        } else {
+            value
+                .parse::<u16>()
+                .map_err(|_| anyhow!("Invalid wrap value"))?;
+            self.wrap = Some(value.into())
+        }
+        Ok(())
+    }
+
+    pub fn setup_document_loaders(&mut self) {
+        [("pdf", "pdftotext $1 -"), ("docx", "pandoc --to plain $1")]
+            .into_iter()
+            .for_each(|(k, v)| {
+                let (k, v) = (k.to_string(), v.to_string());
+                self.document_loaders.entry(k).or_insert(v);
+            });
+    }
+
+    pub fn setup_user_agent(&mut self) {
+        if let Some("auto") = self.user_agent.as_deref() {
+            self.user_agent = Some(format!(
+                "{}/{}",
+                env!("CARGO_CRATE_NAME"),
+                env!("CARGO_PKG_VERSION")
+            ));
+        }
+    }
+
+    pub fn load_envs(&mut self) {
+        if let Ok(v) = env::var(get_env_name("model")) {
+            self.model_id = v;
+        }
+        if let Some(v) = super::read_env_value::<f64>(&get_env_name("temperature")) {
+            self.temperature = v;
+        }
+        if let Some(v) = super::read_env_value::<f64>(&get_env_name("top_p")) {
+            self.top_p = v;
+        }
+
+        if let Some(Some(v)) = super::read_env_bool(&get_env_name("dry_run")) {
+            self.dry_run = v;
+        }
+        if let Some(Some(v)) = super::read_env_bool(&get_env_name("stream")) {
+            self.stream = v;
+        }
+        if let Some(Some(v)) = super::read_env_bool(&get_env_name("save")) {
+            self.save = v;
+        }
+        if let Ok(v) = env::var(get_env_name("keybindings"))
+            && v == "vi"
+        {
+            self.keybindings = v;
+        }
+        if let Some(v) = super::read_env_value::<String>(&get_env_name("editor")) {
+            self.editor = v;
+        }
+        if let Some(v) = super::read_env_value::<String>(&get_env_name("wrap")) {
+            self.wrap = v;
+        }
+        if let Some(Some(v)) = super::read_env_bool(&get_env_name("wrap_code")) {
+            self.wrap_code = v;
+        }
+
+        if let Some(Some(v)) = super::read_env_bool(&get_env_name("function_calling_support")) {
+            self.function_calling_support = v;
+        }
+        if let Ok(v) = env::var(get_env_name("mapping_tools"))
+            && let Ok(v) = serde_json::from_str(&v)
+        {
+            self.mapping_tools = v;
+        }
+        if let Some(v) = super::read_env_value::<String>(&get_env_name("enabled_tools")) {
+            self.enabled_tools = v;
+        }
+
+        if let Some(Some(v)) = super::read_env_bool(&get_env_name("mcp_server_support")) {
+            self.mcp_server_support = v;
+        }
+        if let Ok(v) = env::var(get_env_name("mapping_mcp_servers"))
+            && let Ok(v) = serde_json::from_str(&v)
+        {
+            self.mapping_mcp_servers = v;
+        }
+        if let Some(v) = super::read_env_value::<String>(&get_env_name("enabled_mcp_servers")) {
+            self.enabled_mcp_servers = v;
+        }
+
+        if let Some(v) = super::read_env_value::<String>(&get_env_name("repl_prelude")) {
+            self.repl_prelude = v;
+        }
+        if let Some(v) = super::read_env_value::<String>(&get_env_name("cmd_prelude")) {
+            self.cmd_prelude = v;
+        }
+        if let Some(v) = super::read_env_value::<String>(&get_env_name("agent_session")) {
+            self.agent_session = v;
+        }
+
+        if let Some(v) = super::read_env_bool(&get_env_name("save_session")) {
+            self.save_session = v;
+        }
+        if let Some(Some(v)) =
+            super::read_env_value::<usize>(&get_env_name("compression_threshold"))
+        {
+            self.compression_threshold = v;
+        }
+        if let Some(v) = super::read_env_value::<String>(&get_env_name("summarization_prompt")) {
+            self.summarization_prompt = v;
+        }
+        if let Some(v) = super::read_env_value::<String>(&get_env_name("summary_context_prompt")) {
+            self.summary_context_prompt = v;
+        }
+
+        if let Some(v) = super::read_env_value::<String>(&get_env_name("rag_embedding_model")) {
+            self.rag_embedding_model = v;
+        }
+        if let Some(v) = super::read_env_value::<String>(&get_env_name("rag_reranker_model")) {
+            self.rag_reranker_model = v;
+        }
+        if let Some(Some(v)) = super::read_env_value::<usize>(&get_env_name("rag_top_k")) {
+            self.rag_top_k = v;
+        }
+        if let Some(v) = super::read_env_value::<usize>(&get_env_name("rag_chunk_size")) {
+            self.rag_chunk_size = v;
+        }
+        if let Some(v) = super::read_env_value::<usize>(&get_env_name("rag_chunk_overlap")) {
+            self.rag_chunk_overlap = v;
+        }
+        if let Some(v) = super::read_env_value::<String>(&get_env_name("rag_template")) {
+            self.rag_template = v;
+        }
+
+        if let Ok(v) = env::var(get_env_name("document_loaders"))
+            && let Ok(v) = serde_json::from_str(&v)
+        {
+            self.document_loaders = v;
+        }
+
+        if let Some(Some(v)) = super::read_env_bool(&get_env_name("highlight")) {
+            self.highlight = v;
+        }
+        if *NO_COLOR {
+            self.highlight = false;
+        }
+        if self.highlight && self.theme.is_none() {
+            if let Some(v) = super::read_env_value::<String>(&get_env_name("theme")) {
+                self.theme = v;
+            } else if *IS_STDOUT_TERMINAL
+                && let Ok(color_scheme) = color_scheme(QueryOptions::default())
+            {
+                let theme = match color_scheme {
+                    ColorScheme::Dark => "dark",
+                    ColorScheme::Light => "light",
+                };
+                self.theme = Some(theme.into());
+            }
+        }
+        if let Some(v) = super::read_env_value::<String>(&get_env_name("left_prompt")) {
+            self.left_prompt = v;
+        }
+        if let Some(v) = super::read_env_value::<String>(&get_env_name("right_prompt")) {
+            self.right_prompt = v;
+        }
+        if let Some(v) = super::read_env_value::<String>(&get_env_name("user_agent")) {
+            self.user_agent = v;
+        }
+        if let Some(Some(v)) = super::read_env_bool(&get_env_name("save_shell_history")) {
+            self.save_shell_history = v;
+        }
+        if let Some(v) = super::read_env_value::<String>(&get_env_name("sync_models_url")) {
+            self.sync_models_url = v;
+        }
+    }
+}
+
+impl AppConfig {
+    #[allow(dead_code)]
+    pub fn set_temperature_default(&mut self, value: Option<f64>) {
+        self.temperature = value;
+    }
+
+    #[allow(dead_code)]
+    pub fn set_top_p_default(&mut self, value: Option<f64>) {
+        self.top_p = value;
+    }
+
+    #[allow(dead_code)]
+    pub fn set_enabled_tools_default(&mut self, value: Option<String>) {
+        self.enabled_tools = value;
+    }
+
+    #[allow(dead_code)]
+    pub fn set_enabled_mcp_servers_default(&mut self, value: Option<String>) {
+        self.enabled_mcp_servers = value;
+    }
+
+    #[allow(dead_code)]
+    pub fn set_save_session_default(&mut self, value: Option<bool>) {
+        self.save_session = value;
+    }
+
+    #[allow(dead_code)]
+    pub fn set_compression_threshold_default(&mut self, value: Option<usize>) {
+        self.compression_threshold = value.unwrap_or_default();
+    }
+
+    #[allow(dead_code)]
+    pub fn set_rag_reranker_model_default(&mut self, value: Option<String>) {
+        self.rag_reranker_model = value;
+    }
+
+    #[allow(dead_code)]
+    pub fn set_rag_top_k_default(&mut self, value: usize) {
+        self.rag_top_k = value;
+    }
+
+    #[allow(dead_code)]
+    pub fn set_model_id_default(&mut self, model_id: String) {
+        self.model_id = model_id;
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use crate::config::Config;
+
+    fn cached_editor() -> Option<String> {
+        super::super::EDITOR.get().cloned().flatten()
+    }
+
+    #[test]
+    fn from_config_copies_serialized_fields() {
+        let cfg = Config {
+            model_id: "test-model".to_string(),
+            temperature: Some(0.7),
+            top_p: Some(0.9),
+            dry_run: true,
+            stream: false,
+            save: true,
+            highlight: false,
+            compression_threshold: 2000,
+            rag_top_k: 10,
+            clients: vec![ClientConfig::default()],
+            ..Config::default()
+        };
+
+        let app = AppConfig::from_config(cfg).unwrap();
+
+        assert_eq!(app.model_id, "test-model");
+        assert_eq!(app.temperature, Some(0.7));
+        assert_eq!(app.top_p, Some(0.9));
+        assert!(app.dry_run);
+        assert!(!app.stream);
+        assert!(app.save);
+        assert!(!app.highlight);
+        assert_eq!(app.compression_threshold, 2000);
+        assert_eq!(app.rag_top_k, 10);
+    }
+
+    #[test]
+    fn from_config_copies_clients() {
+        let cfg = Config {
+            model_id: "test-model".to_string(),
+            clients: vec![ClientConfig::default()],
+            ..Config::default()
+        };
+        let app = AppConfig::from_config(cfg).unwrap();
+
+        assert_eq!(app.clients.len(), 1);
+    }
+
+    #[test]
+    fn from_config_copies_mapping_fields() {
+        let mut cfg = Config {
+            model_id: "test-model".to_string(),
+            clients: vec![ClientConfig::default()],
+            ..Config::default()
+        };
+        cfg.mapping_tools
+            .insert("alias".to_string(), "real_tool".to_string());
+        cfg.mapping_mcp_servers
+            .insert("gh".to_string(), "github-mcp".to_string());
+
+        let app = AppConfig::from_config(cfg).unwrap();
+
+        assert_eq!(
+            app.mapping_tools.get("alias"),
+            Some(&"real_tool".to_string())
+        );
+        assert_eq!(
+            app.mapping_mcp_servers.get("gh"),
+            Some(&"github-mcp".to_string())
+        );
+    }
+
+    #[test]
+    fn editor_returns_configured_value() {
+        let configured = cached_editor()
+            .unwrap_or_else(|| std::env::current_exe().unwrap().display().to_string());
+        let app = AppConfig {
+            editor: Some(configured.clone()),
+            ..AppConfig::default()
+        };
+
+        assert_eq!(app.editor().unwrap(), configured);
+    }
+
+    #[test]
+    fn editor_falls_back_to_env() {
+        if let Some(expected) = cached_editor() {
+            let app = AppConfig::default();
+            assert_eq!(app.editor().unwrap(), expected);
+            return;
+        }
+
+        let expected = std::env::current_exe().unwrap().display().to_string();
+        unsafe {
+            std::env::set_var("VISUAL", &expected);
+        }
+
+        let app = AppConfig::default();
+        let result = app.editor();
+
+        assert!(result.is_ok());
+        assert_eq!(result.unwrap(), expected);
+    }
+
+    #[test]
+    fn light_theme_default_is_false() {
+        let app = AppConfig::default();
+        assert!(!app.light_theme());
+    }
+
+    #[test]
+    fn sync_models_url_has_default() {
+        let app = AppConfig::default();
+        let url = app.sync_models_url();
+        assert!(!url.is_empty());
+    }
+
+    #[test]
+    fn from_config_copies_serde_fields() {
+        let cfg = Config {
+            model_id: "provider:model-x".to_string(),
+            temperature: Some(0.42),
+            compression_threshold: 1234,
+            ..Config::default()
+        };
+
+        let app = AppConfig::from_config(cfg).unwrap();
+
+        assert_eq!(app.model_id, "provider:model-x");
+        assert_eq!(app.temperature, Some(0.42));
+        assert_eq!(app.compression_threshold, 1234);
+    }
+
+    #[test]
+    fn from_config_installs_default_document_loaders() {
+        let cfg = Config {
+            model_id: "provider:test".to_string(),
+            ..Config::default()
+        };
+        let app = AppConfig::from_config(cfg).unwrap();
+
+        assert_eq!(
+            app.document_loaders.get("pdf"),
+            Some(&"pdftotext $1 -".to_string())
+        );
+        assert_eq!(
+            app.document_loaders.get("docx"),
+            Some(&"pandoc --to plain $1".to_string())
+        );
+    }
+
+    #[test]
+    fn from_config_resolves_auto_user_agent() {
+        let cfg = Config {
+            model_id: "provider:test".to_string(),
+            user_agent: Some("auto".to_string()),
+            ..Config::default()
+        };
+
+        let app = AppConfig::from_config(cfg).unwrap();
+
+        let ua = app.user_agent.as_deref().unwrap();
+        assert!(ua != "auto", "user_agent should have been resolved");
+        assert!(ua.contains('/'), "user_agent should be '<name>/<version>'");
+    }
+
+    #[test]
+    fn from_config_preserves_explicit_user_agent() {
+        let cfg = Config {
+            model_id: "provider:test".to_string(),
+            user_agent: Some("custom/1.0".to_string()),
+            ..Config::default()
+        };
+
+        let app = AppConfig::from_config(cfg).unwrap();
+
+        assert_eq!(app.user_agent.as_deref(), Some("custom/1.0"));
+    }
+
+    #[test]
+    fn from_config_validates_wrap_value() {
+        let cfg = Config {
+            model_id: "provider:test".to_string(),
+            wrap: Some("invalid".to_string()),
+            ..Config::default()
+        };
+
+        let result = AppConfig::from_config(cfg);
+        assert!(result.is_err());
+    }
+
+    #[test]
+    fn from_config_accepts_wrap_auto() {
+        let cfg = Config {
+            model_id: "provider:test".to_string(),
+            wrap: Some("auto".to_string()),
+            ..Config::default()
+        };
+
+        let app = AppConfig::from_config(cfg).unwrap();
+        assert_eq!(app.wrap.as_deref(), Some("auto"));
+    }
+
+    #[test]
+    fn resolve_model_errors_when_no_models_available() {
+        let mut app = AppConfig {
+            model_id: String::new(),
+            clients: vec![],
+            ..AppConfig::default()
+        };
+
+        let result = app.resolve_model();
+        assert!(result.is_err());
+    }
+
+    #[test]
+    fn resolve_model_keeps_explicit_model_id() {
+        let mut app = AppConfig {
+            model_id: "provider:explicit".to_string(),
+            ..AppConfig::default()
+        };
+
+        app.resolve_model().unwrap();
+        assert_eq!(app.model_id, "provider:explicit");
+    }
+}
diff --git a/src/config/app_state.rs b/src/config/app_state.rs
new file mode 100644
index 0000000..d3e8332
--- /dev/null
+++ b/src/config/app_state.rs
@@ -0,0 +1,93 @@
+use super::mcp_factory::{McpFactory, McpServerKey};
+use super::rag_cache::RagCache;
+use crate::config::AppConfig;
+use crate::function::Functions;
+use crate::mcp::{McpRegistry, McpServersConfig};
+use crate::utils::AbortSignal;
+use crate::vault::{GlobalVault, Vault};
+
+use anyhow::Result;
+use std::path::PathBuf;
+use std::sync::Arc;
+
+#[derive(Clone)]
+pub struct AppState {
+    pub config: Arc<AppConfig>,
+    pub vault: GlobalVault,
+    pub mcp_factory: Arc<McpFactory>,
+    pub rag_cache: Arc<RagCache>,
+    pub mcp_config: Option<McpServersConfig>,
+    pub mcp_log_path: Option<PathBuf>,
+    pub mcp_registry: Option<Arc<McpRegistry>>,
+    pub functions: Functions,
+}
+
+impl AppState {
+    #[cfg(test)]
+    pub fn test_default() -> Self {
+        Self {
+            config: Arc::new(AppConfig::default()),
+            vault: Arc::new(Vault::default()),
+            mcp_factory: Arc::new(McpFactory::default()),
+            rag_cache: Arc::new(RagCache::default()),
+            mcp_config: None,
+            mcp_log_path: None,
+            mcp_registry: None,
+            functions: Functions::default(),
+        }
+    }
+
+    pub async fn init(
+        config: Arc<AppConfig>,
+        log_path: Option<PathBuf>,
+        start_mcp_servers: bool,
+        abort_signal: AbortSignal,
+    ) -> Result<Self> {
+        let vault = Arc::new(Vault::init(&config));
+
+        let mcp_registry = McpRegistry::init(
+            log_path,
+            start_mcp_servers,
+            config.enabled_mcp_servers.clone(),
+            abort_signal,
+            &config,
+            &vault,
+        )
+        .await?;
+
+        let mcp_config = mcp_registry.mcp_config().cloned();
+        let mcp_log_path = mcp_registry.log_path().cloned();
+
+        let mcp_factory = Arc::new(McpFactory::default());
+        if let Some(mcp_servers_config) = &mcp_config {
+            for (id, handle) in mcp_registry.running_servers() {
+                if let Some(spec) = mcp_servers_config.mcp_servers.get(id) {
+                    let key = McpServerKey::from_spec(id, spec);
+                    mcp_factory.insert_active(key, handle);
+                }
+            }
+        }
+
+        let mut functions = Functions::init(config.visible_tools.as_ref().unwrap_or(&Vec::new()))?;
+        if !mcp_registry.is_empty() && config.mcp_server_support {
+            functions.append_mcp_meta_functions(mcp_registry.list_started_servers());
+        }
+
+        let mcp_registry = if mcp_registry.is_empty() {
+            None
+        } else {
+            Some(Arc::new(mcp_registry))
+        };
+
+        Ok(Self {
+            config,
+            vault,
+            mcp_factory,
+            rag_cache: Arc::new(RagCache::default()),
+            mcp_config,
+            mcp_log_path,
+            mcp_registry,
+            functions,
+        })
+    }
+}
diff --git a/src/config/input.rs b/src/config/input.rs
index ab4e029..f030ab6 100644
--- a/src/config/input.rs
+++ b/src/config/input.rs
@@ -9,7 +9,7 @@ use crate::utils::{AbortSignal, base64_encode, is_loader_protocol, sha256};
 
 use anyhow::{Context, Result, bail};
 use indexmap::IndexSet;
-use std::{collections::HashMap, fs::File, io::Read};
+use std::{collections::HashMap, fs::File, io::Read, sync::Arc};
 use unicode_width::{UnicodeWidthChar, UnicodeWidthStr};
 
 const IMAGE_EXTS: [&str; 5] = ["png", "jpeg", "jpg", "webp", "gif"];
@@ -17,7 +17,11 @@ const SUMMARY_MAX_WIDTH: usize = 80;
 
 #[derive(Debug, Clone)]
 pub struct Input {
-    config: GlobalConfig,
+    app_config: Arc<AppConfig>,
+    stream_enabled: bool,
+    session: Option<Session>,
+    rag: Option<Arc<Rag>>,
+    functions: Option<Vec<FunctionDeclaration>>,
     text: String,
     raw: (String, Vec<String>),
     patched_text: Option<String>,
@@ -34,10 +38,15 @@ pub struct Input {
 }
 
 impl Input {
-    pub fn from_str(config: &GlobalConfig, text: &str, role: Option<Role>) -> Self {
-        let (role, with_session, with_agent) = resolve_role(&config.read(), role);
+    pub fn from_str(ctx: &RequestContext, text: &str, role: Option<Role>) -> Self {
+        let (role, with_session, with_agent) = resolve_role(ctx, role);
+        let captured = capture_input_config(ctx, &role);
         Self {
-            config: config.clone(),
+            app_config: Arc::clone(&ctx.app.config),
+            stream_enabled: captured.stream_enabled,
+            session: captured.session,
+            rag: captured.rag,
+            functions: captured.functions,
             text: text.to_string(),
             raw: (text.to_string(), vec![]),
             patched_text: None,
@@ -55,12 +64,12 @@ impl Input {
     }
 
     pub async fn from_files(
-        config: &GlobalConfig,
+        ctx: &RequestContext,
         raw_text: &str,
         paths: Vec<String>,
         role: Option<Role>,
     ) -> Result<Self> {
-        let loaders = config.read().document_loaders.clone();
+        let loaders = ctx.app.config.document_loaders.clone();
         let (raw_paths, local_paths, remote_urls, external_cmds, protocol_paths, with_last_reply) =
             resolve_paths(&loaders, paths)?;
         let mut last_reply = None;
@@ -78,7 +87,7 @@ impl Input {
             texts.push(raw_text.to_string());
         };
         if with_last_reply {
-            if let Some(LastMessage { input, output, .. }) = config.read().last_message.as_ref() {
+            if let Some(LastMessage { input, output, .. }) = ctx.last_message.as_ref() {
                 if !output.is_empty() {
                     last_reply = Some(output.clone())
                 } else if let Some(v) = input.last_reply.as_ref() {
@@ -102,9 +111,14 @@ impl Input {
                 ));
             }
         }
-        let (role, with_session, with_agent) = resolve_role(&config.read(), role);
+        let (role, with_session, with_agent) = resolve_role(ctx, role);
+        let captured = capture_input_config(ctx, &role);
         Ok(Self {
-            config: config.clone(),
+            app_config: Arc::clone(&ctx.app.config),
+            stream_enabled: captured.stream_enabled,
+            session: captured.session,
+            rag: captured.rag,
+            functions: captured.functions,
             text: texts.join("\n"),
             raw: (raw_text.to_string(), raw_paths),
             patched_text: None,
@@ -122,14 +136,14 @@ impl Input {
     }
 
     pub async fn from_files_with_spinner(
-        config: &GlobalConfig,
+        ctx: &RequestContext,
         raw_text: &str,
         paths: Vec<String>,
         role: Option<Role>,
         abort_signal: AbortSignal,
     ) -> Result<Self> {
         abortable_run_with_spinner(
-            Input::from_files(config, raw_text, paths, role),
+            Input::from_files(ctx, raw_text, paths, role),
             "Loading files",
             abort_signal,
         )
@@ -164,7 +178,7 @@ impl Input {
     }
 
     pub fn stream(&self) -> bool {
-        self.config.read().stream && !self.role().model().no_stream()
+        self.stream_enabled && !self.role().model().no_stream()
     }
 
     pub fn continue_output(&self) -> Option<&str> {
@@ -183,10 +197,9 @@ impl Input {
         self.regenerate
     }
 
-    pub fn set_regenerate(&mut self) {
-        let role = self.config.read().extract_role();
-        if role.name() == self.role().name() {
-            self.role = role;
+    pub fn set_regenerate(&mut self, current_role: Role) {
+        if current_role.name() == self.role().name() {
+            self.role = current_role;
         }
         self.regenerate = true;
         self.tool_calls = None;
@@ -196,9 +209,10 @@ impl Input {
         if self.text.is_empty() {
             return Ok(());
         }
-        let rag = self.config.read().rag.clone();
-        if let Some(rag) = rag {
-            let result = Config::search_rag(&self.config, &rag, &self.text, abort_signal).await?;
+        if let Some(rag) = &self.rag {
+            let result = rag
+                .search_with_template(&self.app_config, &self.text, abort_signal)
+                .await?;
             self.patched_text = Some(result);
             self.rag_name = Some(rag.name().to_string());
         }
@@ -220,7 +234,7 @@ impl Input {
     }
 
     pub fn create_client(&self) -> Result<Box<dyn Client>> {
-        init_client(&self.config, Some(self.role().model().clone()))
+        init_client(&self.app_config, self.role().model().clone())
     }
 
     pub async fn fetch_chat_text(&self) -> Result<String> {
@@ -240,7 +254,7 @@ impl Input {
         model.guard_max_input_tokens(&messages)?;
         let (temperature, top_p) = (self.role().temperature(), self.role().top_p());
         let functions = if model.supports_function_calling() {
-            let fns = self.config.read().select_functions(self.role());
+            let fns = self.functions.clone();
             if let Some(vec) = &fns {
                 for def in vec {
                     debug!("Function definition: {:?}", def.name);
@@ -260,7 +274,7 @@ impl Input {
     }
 
     pub fn build_messages(&self) -> Result<Vec<Message>> {
-        let mut messages = if let Some(session) = self.session(&self.config.read().session) {
+        let mut messages = if let Some(session) = self.session(&self.session) {
             session.build_messages(self)
         } else {
             self.role().build_messages(self)
@@ -275,7 +289,7 @@ impl Input {
     }
 
     pub fn echo_messages(&self) -> String {
-        if let Some(session) = self.session(&self.config.read().session) {
+        if let Some(session) = self.session(&self.session) {
             session.echo_messages(self)
         } else {
             self.role().echo_messages(self)
@@ -384,17 +398,33 @@ impl Input {
     }
 }
 
-fn resolve_role(config: &Config, role: Option<Role>) -> (Role, bool, bool) {
+fn resolve_role(ctx: &RequestContext, role: Option<Role>) -> (Role, bool, bool) {
     match role {
         Some(v) => (v, false, false),
         None => (
-            config.extract_role(),
-            config.session.is_some(),
-            config.agent.is_some(),
+            ctx.extract_role(ctx.app.config.as_ref()),
+            ctx.session.is_some(),
+            ctx.agent.is_some(),
         ),
     }
 }
 
+struct CapturedInputConfig {
+    stream_enabled: bool,
+    session: Option<Session>,
+    rag: Option<Arc<Rag>>,
+    functions: Option<Vec<FunctionDeclaration>>,
+}
+
+fn capture_input_config(ctx: &RequestContext, role: &Role) -> CapturedInputConfig {
+    CapturedInputConfig {
+        stream_enabled: ctx.app.config.stream,
+        session: ctx.session.clone(),
+        rag: ctx.rag.clone(),
+        functions: ctx.select_functions(role),
+    }
+}
+
 type ResolvePathsOutput = (
     Vec<String>,
     Vec<String>,
@@ -548,3 +578,390 @@ fn read_media_to_data_url(image_path: &str) -> Result<String> {
 
     Ok(data_url)
 }
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use crate::config::request_context::RequestContext;
+    use crate::config::{AppState, WorkingMode};
+    use std::fs;
+    use std::sync::Arc;
+    use std::time::SystemTime;
+
+    fn default_app_state() -> Arc<AppState> {
+        Arc::new(AppState::test_default())
+    }
+
+    fn create_test_ctx() -> RequestContext {
+        RequestContext::new(default_app_state(), WorkingMode::Cmd)
+    }
+
+    #[test]
+    fn resolve_role_with_explicit_role() {
+        let ctx = create_test_ctx();
+        let role = Role::new("custom", "be helpful");
+        let (resolved, with_session, with_agent) = resolve_role(&ctx, Some(role));
+        assert_eq!(resolved.name(), "custom");
+        assert!(!with_session);
+        assert!(!with_agent);
+    }
+
+    #[test]
+    fn resolve_role_without_role_no_session_no_agent() {
+        let ctx = create_test_ctx();
+        let (resolved, with_session, with_agent) = resolve_role(&ctx, None);
+        assert_eq!(resolved.name(), "");
+        assert!(!with_session);
+        assert!(!with_agent);
+    }
+
+    #[test]
+    fn resolve_role_without_role_with_session() {
+        let mut ctx = create_test_ctx();
+        ctx.session = Some(Session::default());
+        let (_resolved, with_session, with_agent) = resolve_role(&ctx, None);
+        assert!(with_session);
+        assert!(!with_agent);
+    }
+
+    #[test]
+    fn resolve_role_explicit_role_overrides_session_flag() {
+        let mut ctx = create_test_ctx();
+        ctx.session = Some(Session::default());
+        let role = Role::new("explicit", "prompt");
+        let (_resolved, with_session, _with_agent) = resolve_role(&ctx, Some(role));
+        assert!(!with_session);
+    }
+
+    #[test]
+    fn resolve_paths_detects_last_reply_syntax() {
+        let loaders = HashMap::new();
+        let (_, _, _, _, _, with_last_reply) =
+            resolve_paths(&loaders, vec!["%%".to_string()]).unwrap();
+        assert!(with_last_reply);
+    }
+
+    #[test]
+    fn resolve_paths_detects_url() {
+        let loaders = HashMap::new();
+        let (_, local, remote, _, _, _) =
+            resolve_paths(&loaders, vec!["https://example.com".to_string()]).unwrap();
+        assert!(local.is_empty());
+        assert_eq!(remote, vec!["https://example.com"]);
+    }
+
+    #[test]
+    fn resolve_paths_detects_external_command() {
+        let loaders = HashMap::new();
+        let (_, _, _, external, _, _) =
+            resolve_paths(&loaders, vec!["`echo hello`".to_string()]).unwrap();
+        assert_eq!(external, vec!["echo hello"]);
+    }
+
+    #[test]
+    fn resolve_paths_empty_input() {
+        let loaders = HashMap::new();
+        let (raw, local, remote, external, protocol, with_last) =
+            resolve_paths(&loaders, vec![]).unwrap();
+        assert!(raw.is_empty());
+        assert!(local.is_empty());
+        assert!(remote.is_empty());
+        assert!(external.is_empty());
+        assert!(protocol.is_empty());
+        assert!(!with_last);
+    }
+
+    #[test]
+    fn resolve_paths_rejects_url_with_glob_suffix() {
+        let loaders = HashMap::new();
+        let result = resolve_paths(&loaders, vec!["https://example.com**".to_string()]);
+        assert!(result.is_err());
+    }
+
+    #[test]
+    fn resolve_paths_mixed_inputs() {
+        let loaders = HashMap::new();
+        let paths = vec![
+            "%%".to_string(),
+            "https://example.com".to_string(),
+            "`ls`".to_string(),
+        ];
+        let (_, _, remote, external, _, with_last) = resolve_paths(&loaders, paths).unwrap();
+        assert!(with_last);
+        assert_eq!(remote.len(), 1);
+        assert_eq!(external.len(), 1);
+    }
+
+    #[test]
+    fn input_from_str_captures_text() {
+        let ctx = create_test_ctx();
+        let input = Input::from_str(&ctx, "hello world", None);
+        assert_eq!(input.text(), "hello world");
+    }
+
+    #[test]
+    fn input_from_str_with_explicit_role() {
+        let ctx = create_test_ctx();
+        let role = Role::new("pirate", "you are a pirate");
+        let input = Input::from_str(&ctx, "ahoy", Some(role));
+        assert_eq!(input.role().name(), "pirate");
+        assert!(!input.with_agent());
+    }
+
+    #[test]
+    fn input_from_str_captures_stream_from_config() {
+        let mut state = AppState::test_default();
+        let mut config = (*state.config).clone();
+        config.stream = false;
+        state.config = Arc::new(config);
+        let ctx = RequestContext::new(Arc::new(state), WorkingMode::Cmd);
+        let input = Input::from_str(&ctx, "test", None);
+        assert!(!input.stream_enabled);
+    }
+
+    #[test]
+    fn input_is_empty_with_no_text_and_no_medias() {
+        let ctx = create_test_ctx();
+        let input = Input::from_str(&ctx, "", None);
+        assert!(input.is_empty());
+    }
+
+    #[test]
+    fn input_is_not_empty_with_text() {
+        let ctx = create_test_ctx();
+        let input = Input::from_str(&ctx, "hello", None);
+        assert!(!input.is_empty());
+    }
+
+    #[test]
+    fn input_set_text_changes_text() {
+        let ctx = create_test_ctx();
+        let mut input = Input::from_str(&ctx, "original", None);
+        input.set_text("modified".to_string());
+        assert_eq!(input.text(), "modified");
+    }
+
+    #[test]
+    fn input_text_returns_patched_when_set() {
+        let ctx = create_test_ctx();
+        let mut input = Input::from_str(&ctx, "original", None);
+        input.patched_text = Some("patched".to_string());
+        assert_eq!(input.text(), "patched");
+    }
+
+    #[test]
+    fn input_clear_patch_restores_original() {
+        let ctx = create_test_ctx();
+        let mut input = Input::from_str(&ctx, "original", None);
+        input.patched_text = Some("patched".to_string());
+        input.clear_patch();
+        assert_eq!(input.text(), "original");
+    }
+
+    #[test]
+    fn input_set_continue_output_accumulates() {
+        let ctx = create_test_ctx();
+        let mut input = Input::from_str(&ctx, "test", None);
+        assert!(input.continue_output().is_none());
+        input.set_continue_output("first ");
+        assert_eq!(input.continue_output(), Some("first "));
+        input.set_continue_output("second");
+        assert_eq!(input.continue_output(), Some("first second"));
+    }
+
+    #[test]
+    fn input_set_regenerate_sets_flag_and_clears_tool_calls() {
+        let ctx = create_test_ctx();
+        let mut input = Input::from_str(&ctx, "test", None);
+        let role = input.role().clone();
+        assert!(!input.regenerate());
+        input.set_regenerate(role);
+        assert!(input.regenerate());
+        assert!(input.tool_calls().is_none());
+    }
+
+    #[test]
+    fn input_summary_truncates_long_text() {
+        let ctx = create_test_ctx();
+        let long_text = "a".repeat(200);
+        let input = Input::from_str(&ctx, &long_text, None);
+        let summary = input.summary();
+        assert!(summary.len() < 200);
+        assert!(summary.ends_with("..."));
+    }
+
+    #[test]
+    fn input_summary_preserves_short_text() {
+        let ctx = create_test_ctx();
+        let input = Input::from_str(&ctx, "short", None);
+        assert_eq!(input.summary(), "short");
+    }
+
+    #[test]
+    fn input_raw_with_no_files() {
+        let ctx = create_test_ctx();
+        let input = Input::from_str(&ctx, "hello", None);
+        assert_eq!(input.raw(), "hello");
+    }
+
+    #[test]
+    fn input_render_with_no_medias() {
+        let ctx = create_test_ctx();
+        let input = Input::from_str(&ctx, "hello", None);
+        assert_eq!(input.render(), "hello");
+    }
+
+    #[test]
+    fn input_with_agent_false_when_no_agent() {
+        let ctx = create_test_ctx();
+        let input = Input::from_str(&ctx, "test", None);
+        assert!(!input.with_agent());
+    }
+
+    #[test]
+    fn input_session_returns_none_when_with_session_false() {
+        let ctx = create_test_ctx();
+        let input = Input::from_str(&ctx, "test", Some(Role::new("r", "p")));
+        let session = Some(Session::default());
+        assert!(input.session(&session).is_none());
+    }
+
+    #[test]
+    fn input_session_returns_some_when_with_session_true() {
+        let mut ctx = create_test_ctx();
+        ctx.session = Some(Session::default());
+        let input = Input::from_str(&ctx, "test", None);
+        let session = Some(Session::default());
+        assert!(input.session(&session).is_some());
+    }
+
+    #[test]
+    fn is_image_recognizes_image_extensions() {
+        assert!(is_image("photo.png"));
+        assert!(is_image("photo.jpeg"));
+        assert!(is_image("photo.jpg"));
+        assert!(is_image("photo.webp"));
+        assert!(is_image("photo.gif"));
+    }
+
+    #[test]
+    fn is_image_rejects_non_image_extensions() {
+        assert!(!is_image("file.txt"));
+        assert!(!is_image("file.rs"));
+        assert!(!is_image("file.pdf"));
+    }
+
+    #[test]
+    fn resolve_data_url_returns_path_for_known_hash() {
+        let mut data_urls = HashMap::new();
+        let data_url = "data:image/png;base64,abc123";
+        let hash = sha256(data_url);
+        data_urls.insert(hash, "/path/to/image.png".to_string());
+        let result = resolve_data_url(&data_urls, data_url.to_string());
+        assert_eq!(result, "/path/to/image.png");
+    }
+
+    #[test]
+    fn resolve_data_url_returns_original_for_non_data_url() {
+        let data_urls = HashMap::new();
+        let result = resolve_data_url(&data_urls, "https://example.com/image.png".to_string());
+        assert_eq!(result, "https://example.com/image.png");
+    }
+
+    fn run_async<F: Future>(f: F) -> F::Output {
+        tokio::runtime::Builder::new_current_thread()
+            .enable_all()
+            .build()
+            .unwrap()
+            .block_on(f)
+    }
+
+    #[test]
+    fn from_files_loads_single_text_file() {
+        let dir = env::temp_dir().join(format!(
+            "loki-input-test-{}",
+            SystemTime::now()
+                .duration_since(std::time::UNIX_EPOCH)
+                .unwrap()
+                .as_nanos()
+        ));
+        create_dir_all(&dir).unwrap();
+        let file_path = dir.join("test.txt");
+        fs::write(&file_path, "file content here").unwrap();
+
+        let ctx = create_test_ctx();
+        let input = run_async(Input::from_files(
+            &ctx,
+            "question",
+            vec![file_path.to_string_lossy().to_string()],
+            None,
+        ))
+        .unwrap();
+
+        assert!(input.text().contains("file content here"));
+        assert!(input.text().contains("question"));
+        let _ = fs::remove_dir_all(&dir);
+    }
+
+    #[test]
+    fn from_files_loads_multiple_files() {
+        let dir = env::temp_dir().join(format!(
+            "loki-input-test-multi-{}",
+            SystemTime::now()
+                .duration_since(std::time::UNIX_EPOCH)
+                .unwrap()
+                .as_nanos()
+        ));
+        create_dir_all(&dir).unwrap();
+        fs::write(dir.join("a.txt"), "content A").unwrap();
+        fs::write(dir.join("b.txt"), "content B").unwrap();
+
+        let ctx = create_test_ctx();
+        let input = run_async(Input::from_files(
+            &ctx,
+            "question",
+            vec![
+                dir.join("a.txt").to_string_lossy().to_string(),
+                dir.join("b.txt").to_string_lossy().to_string(),
+            ],
+            None,
+        ))
+        .unwrap();
+
+        assert!(input.text().contains("content A"));
+        assert!(input.text().contains("content B"));
+        let _ = fs::remove_dir_all(&dir);
+    }
+
+    #[test]
+    fn from_files_with_no_paths_just_text() {
+        let ctx = create_test_ctx();
+        let input = run_async(Input::from_files(&ctx, "just text", vec![], None)).unwrap();
+        assert_eq!(input.text(), "just text");
+    }
+
+    #[test]
+    fn from_files_with_external_command() {
+        let ctx = create_test_ctx();
+        let input = run_async(Input::from_files(
+            &ctx,
+            "question",
+            vec!["`echo hello from cmd`".to_string()],
+            None,
+        ))
+        .unwrap();
+        assert!(input.text().contains("hello from cmd"));
+    }
+
+    #[test]
+    fn from_files_nonexistent_file_errors() {
+        let ctx = create_test_ctx();
+        let result = run_async(Input::from_files(
+            &ctx,
+            "question",
+            vec!["/nonexistent/path/xyz.txt".to_string()],
+            None,
+        ));
+        assert!(result.is_err());
+    }
+}
diff --git a/src/config/install_remote.rs b/src/config/install_remote.rs
new file mode 100644
index 0000000..61e7c5c
--- /dev/null
+++ b/src/config/install_remote.rs
@@ -0,0 +1,1309 @@
+use anyhow::{Context, Result, bail};
+use indexmap::IndexMap;
+use inquire::{Confirm, Select};
+use std::ffi::{OsStr, OsString};
+use std::fs;
+use std::path::{Path, PathBuf};
+
+use crate::config::{InstallFilter, paths};
+#[cfg(not(windows))]
+use crate::function::Language;
+use crate::mcp::{McpServer, McpServersConfig};
+use crate::utils;
+use crate::utils::IS_STDOUT_TERMINAL;
+use crate::vault::{Vault, create_vault_password_file, interpolate_secrets};
+
+pub fn install_remote(git_url: &str, filter: Option<InstallFilter>, force: bool) -> Result<()> {
+    let (url, reference) = parse_url_with_ref(git_url)?;
+    let temp = clone_to_temp(&url, reference.as_deref())?;
+    println!("Cloned {git_url} to {}", temp.path().display());
+
+    let layout = scan_remote_layout(temp.path())?;
+    let layout = apply_filter(layout, filter);
+
+    if layout.is_empty() {
+        println!(
+            "No recognized assets found in {git_url}. Expected one or more of: \
+             agents/, roles/, macros/, functions/tools/, functions/mcp.json"
+        );
+        return Ok(());
+    }
+
+    let plan = plan_changes(&layout)?;
+
+    if !plan.files.is_empty() {
+        print_plan_summary(&plan);
+        apply_plan(&plan, force)?;
+    }
+
+    if let Some((remote_mcp, local_mcp)) = &plan.mcp_json {
+        let local = local_mcp.exists().then_some(local_mcp.as_path());
+        let report = merge_mcp_json(local, remote_mcp, local_mcp, force)?;
+        print_mcp_merge_report(&report);
+        handle_missing_secrets(&report.missing_secrets)?;
+    }
+
+    Ok(())
+}
+
+pub fn install_remote_from_repl_args(args: &str) -> Result<()> {
+    let tokens = shell_words::split(args)
+        .with_context(|| format!("failed to parse '.install remote' args: {args}"))?;
+
+    let mut iter = tokens.into_iter();
+    let url = iter.next().with_context(|| {
+        format!(
+            "Usage: .install remote <git-url> [--filter <{}>] [--force]",
+            InstallFilter::NAMES.join("|")
+        )
+    })?;
+
+    let mut filter: Option<InstallFilter> = None;
+    let mut force = false;
+
+    while let Some(tok) = iter.next() {
+        match tok.as_str() {
+            "--force" => force = true,
+            "--filter" => {
+                let val = iter.next().with_context(|| {
+                    format!(
+                        "--filter requires a value (one of: {})",
+                        InstallFilter::NAMES.join(", ")
+                    )
+                })?;
+                filter = Some(parse_filter(&val)?);
+            }
+            s if s.starts_with("--filter=") => {
+                filter = Some(parse_filter(&s["--filter=".len()..])?);
+            }
+            other => bail!("Unexpected argument to '.install remote': {other}"),
+        }
+    }
+
+    install_remote(&url, filter, force)
+}
+
+fn parse_filter(name: &str) -> Result<InstallFilter> {
+    InstallFilter::parse(name).with_context(|| {
+        format!(
+            "Unknown filter '{name}'. Valid values: {}",
+            InstallFilter::NAMES.join(", ")
+        )
+    })
+}
+
+fn parse_url_with_ref(input: &str) -> Result<(String, Option<String>)> {
+    match input.rsplit_once('#') {
+        Some((url, refspec)) if !url.is_empty() => {
+            if refspec.is_empty() {
+                bail!("Empty ref after '#' in URL: {input}");
+            }
+            if refspec.contains("..") {
+                bail!("Invalid ref '{refspec}': cannot contain '..'");
+            }
+            if refspec.starts_with('-') {
+                bail!(
+                    "Invalid ref '{refspec}': cannot start with '-' \
+                     (would be parsed by git as a CLI flag)"
+                );
+            }
+            if !refspec
+                .chars()
+                .all(|c| c.is_ascii_alphanumeric() || matches!(c, '.' | '_' | '/' | '-' | '+'))
+            {
+                bail!("Invalid ref '{refspec}': only [A-Za-z0-9._/+-] characters allowed");
+            }
+            Ok((url.to_string(), Some(refspec.to_string())))
+        }
+        _ => Ok((input.to_string(), None)),
+    }
+}
+
+struct TempRepoDir {
+    path: PathBuf,
+}
+
+impl TempRepoDir {
+    fn path(&self) -> &Path {
+        &self.path
+    }
+}
+
+impl Drop for TempRepoDir {
+    fn drop(&mut self) {
+        let _ = fs::remove_dir_all(&self.path);
+    }
+}
+
+fn clone_to_temp(url: &str, reference: Option<&str>) -> Result<TempRepoDir> {
+    let dest = utils::temp_file("loki-remote-install-", "");
+    let dest_arg: OsString = dest.as_os_str().into();
+
+    let is_sha = reference
+        .map(|r| r.len() >= 4 && r.len() <= 40 && r.chars().all(|c| c.is_ascii_hexdigit()))
+        .unwrap_or(false);
+
+    match reference {
+        Some(r) if !is_sha => {
+            run_git(vec![
+                "clone".into(),
+                "--depth".into(),
+                "1".into(),
+                "--branch".into(),
+                r.into(),
+                url.into(),
+                dest_arg,
+            ])?;
+        }
+        Some(r) => {
+            run_git(vec!["clone".into(), url.into(), dest_arg.clone()])?;
+            run_git(vec!["-C".into(), dest_arg, "checkout".into(), r.into()])?;
+        }
+        None => {
+            run_git(vec![
+                "clone".into(),
+                "--depth".into(),
+                "1".into(),
+                url.into(),
+                dest_arg,
+            ])?;
+        }
+    }
+
+    Ok(TempRepoDir { path: dest })
+}
+
+fn run_git(args: Vec<OsString>) -> Result<()> {
+    let output = duct::cmd("git", &args)
+        .stderr_to_stdout()
+        .stdout_capture()
+        .unchecked()
+        .run()
+        .context("failed to spawn git (is it installed and on PATH?)")?;
+
+    if !output.status.success() {
+        let combined = String::from_utf8_lossy(&output.stdout);
+        bail!("git failed: {}", combined.trim());
+    }
+
+    Ok(())
+}
+
+#[derive(Default)]
+struct RemoteLayout {
+    agents: Option<PathBuf>,
+    roles: Option<PathBuf>,
+    macros: Option<PathBuf>,
+    functions_tools: Option<PathBuf>,
+    mcp_json: Option<PathBuf>,
+}
+
+impl RemoteLayout {
+    fn is_empty(&self) -> bool {
+        self.agents.is_none()
+            && self.roles.is_none()
+            && self.macros.is_none()
+            && self.functions_tools.is_none()
+            && self.mcp_json.is_none()
+    }
+}
+
+fn scan_remote_layout(root: &Path) -> Result<RemoteLayout> {
+    let mut layout = RemoteLayout::default();
+
+    let agents = root.join("agents");
+    if agents.is_dir() {
+        layout.agents = Some(agents);
+    }
+    let roles = root.join("roles");
+    if roles.is_dir() {
+        layout.roles = Some(roles);
+    }
+    let macros = root.join("macros");
+    if macros.is_dir() {
+        layout.macros = Some(macros);
+    }
+    let functions = root.join("functions");
+    if functions.is_dir() {
+        let tools = functions.join("tools");
+        if tools.is_dir() {
+            layout.functions_tools = Some(tools);
+        }
+        let mcp = functions.join("mcp.json");
+        if mcp.is_file() {
+            layout.mcp_json = Some(mcp);
+        }
+    }
+
+    Ok(layout)
+}
+
+fn apply_filter(mut layout: RemoteLayout, filter: Option<InstallFilter>) -> RemoteLayout {
+    let Some(filter) = filter else {
+        return layout;
+    };
+    match filter {
+        InstallFilter::Agents => RemoteLayout {
+            agents: layout.agents.take(),
+            ..RemoteLayout::default()
+        },
+        InstallFilter::Roles => RemoteLayout {
+            roles: layout.roles.take(),
+            ..RemoteLayout::default()
+        },
+        InstallFilter::Macros => RemoteLayout {
+            macros: layout.macros.take(),
+            ..RemoteLayout::default()
+        },
+        InstallFilter::Functions => RemoteLayout {
+            functions_tools: layout.functions_tools.take(),
+            ..RemoteLayout::default()
+        },
+        InstallFilter::McpConfig => RemoteLayout {
+            mcp_json: layout.mcp_json.take(),
+            ..RemoteLayout::default()
+        },
+    }
+}
+
+fn walk_files(root: &Path) -> Result<Vec<PathBuf>> {
+    let mut out = Vec::new();
+    walk_files_inner(root, &mut out)?;
+    Ok(out)
+}
+
+fn walk_files_inner(dir: &Path, out: &mut Vec<PathBuf>) -> Result<()> {
+    for entry in fs::read_dir(dir).with_context(|| format!("failed to read {}", dir.display()))? {
+        let entry = entry?;
+        let file_type = entry.file_type()?;
+        let name = entry.file_name();
+
+        if file_type.is_symlink() {
+            bail!(
+                "Symlink not allowed in remote install source: {}",
+                entry.path().display()
+            );
+        }
+        if name == OsStr::new(".git") {
+            continue;
+        }
+        if name == OsStr::new("..") {
+            bail!(
+                "Path traversal '..' not allowed: {}",
+                entry.path().display()
+            );
+        }
+
+        let path = entry.path();
+        if file_type.is_dir() {
+            walk_files_inner(&path, out)?;
+        } else if file_type.is_file() {
+            out.push(path);
+        }
+    }
+    Ok(())
+}
+
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+enum TopCategory {
+    Agents,
+    Roles,
+    Macros,
+    FunctionsTools,
+}
+
+impl TopCategory {
+    fn label(&self) -> &'static str {
+        match self {
+            TopCategory::Agents => "agents",
+            TopCategory::Roles => "roles",
+            TopCategory::Macros => "macros",
+            TopCategory::FunctionsTools => "functions/tools",
+        }
+    }
+}
+
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+enum PlannedKind {
+    New,
+    Identical,
+    Conflict,
+}
+
+struct PlannedFile {
+    src: PathBuf,
+    dst: PathBuf,
+    kind: PlannedKind,
+    top_category: TopCategory,
+}
+
+struct InstallPlan {
+    files: Vec<PlannedFile>,
+    mcp_json: Option<(PathBuf, PathBuf)>,
+}
+
+fn plan_changes(layout: &RemoteLayout) -> Result<InstallPlan> {
+    let mut files = Vec::new();
+
+    if let Some(src_dir) = &layout.agents {
+        plan_dir_into(
+            src_dir,
+            &paths::agents_data_dir(),
+            TopCategory::Agents,
+            &mut files,
+        )?;
+    }
+    if let Some(src_dir) = &layout.roles {
+        plan_dir_into(src_dir, &paths::roles_dir(), TopCategory::Roles, &mut files)?;
+    }
+    if let Some(src_dir) = &layout.macros {
+        plan_dir_into(
+            src_dir,
+            &paths::macros_dir(),
+            TopCategory::Macros,
+            &mut files,
+        )?;
+    }
+    if let Some(src_dir) = &layout.functions_tools {
+        plan_dir_into(
+            src_dir,
+            &paths::functions_dir().join("tools"),
+            TopCategory::FunctionsTools,
+            &mut files,
+        )?;
+    }
+
+    let mcp_json = layout
+        .mcp_json
+        .as_ref()
+        .map(|src| (src.clone(), paths::mcp_config_file()));
+
+    Ok(InstallPlan { files, mcp_json })
+}
+
+fn plan_dir_into(
+    src_dir: &Path,
+    dst_dir: &Path,
+    category: TopCategory,
+    out: &mut Vec<PlannedFile>,
+) -> Result<()> {
+    for src in walk_files(src_dir)? {
+        let rel = src
+            .strip_prefix(src_dir)
+            .expect("walk_files only returns paths under src_dir");
+        let dst = dst_dir.join(rel);
+        let kind = classify_file(&src, &dst)?;
+        out.push(PlannedFile {
+            src,
+            dst,
+            kind,
+            top_category: category,
+        });
+    }
+    Ok(())
+}
+
+fn classify_file(src: &Path, dst: &Path) -> Result<PlannedKind> {
+    if !dst.exists() {
+        return Ok(PlannedKind::New);
+    }
+    if files_equal(src, dst)? {
+        Ok(PlannedKind::Identical)
+    } else {
+        Ok(PlannedKind::Conflict)
+    }
+}
+
+const LARGE_FILE_THRESHOLD: u64 = 8 * 1024 * 1024;
+
+fn files_equal(a: &Path, b: &Path) -> Result<bool> {
+    let a_meta = fs::metadata(a).with_context(|| format!("stat {}", a.display()))?;
+    let b_meta = fs::metadata(b).with_context(|| format!("stat {}", b.display()))?;
+    if a_meta.len() != b_meta.len() {
+        return Ok(false);
+    }
+    if a_meta.len() > LARGE_FILE_THRESHOLD {
+        files_equal_streaming(a, b)
+    } else {
+        let a_bytes = fs::read(a).with_context(|| format!("read {}", a.display()))?;
+        let b_bytes = fs::read(b).with_context(|| format!("read {}", b.display()))?;
+        Ok(a_bytes == b_bytes)
+    }
+}
+
+fn files_equal_streaming(a: &Path, b: &Path) -> Result<bool> {
+    use std::io::Read;
+    let mut fa = fs::File::open(a).with_context(|| format!("open {}", a.display()))?;
+    let mut fb = fs::File::open(b).with_context(|| format!("open {}", b.display()))?;
+    let mut buf_a = [0u8; 8192];
+    let mut buf_b = [0u8; 8192];
+    loop {
+        let na = fa.read(&mut buf_a)?;
+        let nb = fb.read(&mut buf_b)?;
+        if na != nb {
+            return Ok(false);
+        }
+        if na == 0 {
+            return Ok(true);
+        }
+        if buf_a[..na] != buf_b[..nb] {
+            return Ok(false);
+        }
+    }
+}
+
+fn print_plan_summary(plan: &InstallPlan) {
+    println!("Plan:");
+    for cat in [
+        TopCategory::Agents,
+        TopCategory::Roles,
+        TopCategory::Macros,
+        TopCategory::FunctionsTools,
+    ] {
+        let new_ = count_kind(plan, cat, PlannedKind::New);
+        let identical = count_kind(plan, cat, PlannedKind::Identical);
+        let conflict = count_kind(plan, cat, PlannedKind::Conflict);
+        if new_ + identical + conflict > 0 {
+            println!(
+                "  {:<16} new={new_}  identical={identical}  conflict={conflict}",
+                cat.label()
+            );
+        }
+    }
+}
+
+fn count_kind(plan: &InstallPlan, cat: TopCategory, kind: PlannedKind) -> usize {
+    plan.files
+        .iter()
+        .filter(|p| p.top_category == cat && p.kind == kind)
+        .count()
+}
+
+#[derive(Debug, Clone, Copy, PartialEq)]
+enum StickyMode {
+    None,
+    KeepAll,
+    ReplaceAll,
+}
+
+enum ConflictAction {
+    Keep,
+    Replace,
+}
+
+struct ApplyReport {
+    new_count: usize,
+    identical_count: usize,
+    replaced_count: usize,
+    kept_count: usize,
+}
+
+fn apply_plan(plan: &InstallPlan, force: bool) -> Result<ApplyReport> {
+    let mut report = ApplyReport {
+        new_count: 0,
+        identical_count: 0,
+        replaced_count: 0,
+        kept_count: 0,
+    };
+    let mut sticky = if force {
+        StickyMode::ReplaceAll
+    } else {
+        StickyMode::None
+    };
+
+    for planned in &plan.files {
+        match planned.kind {
+            PlannedKind::New => {
+                write_file(&planned.src, &planned.dst)?;
+                report.new_count += 1;
+            }
+            PlannedKind::Identical => {
+                report.identical_count += 1;
+            }
+            PlannedKind::Conflict => match resolve_conflict(planned, &mut sticky)? {
+                ConflictAction::Keep => report.kept_count += 1,
+                ConflictAction::Replace => {
+                    write_file(&planned.src, &planned.dst)?;
+                    report.replaced_count += 1;
+                }
+            },
+        }
+    }
+
+    println!(
+        "\nInstalled: {} new, {} replaced, {} kept, {} identical.",
+        report.new_count, report.replaced_count, report.kept_count, report.identical_count
+    );
+
+    Ok(report)
+}
+
+fn resolve_conflict(planned: &PlannedFile, sticky: &mut StickyMode) -> Result<ConflictAction> {
+    match *sticky {
+        StickyMode::KeepAll => return Ok(ConflictAction::Keep),
+        StickyMode::ReplaceAll => return Ok(ConflictAction::Replace),
+        StickyMode::None => {}
+    }
+
+    if !*IS_STDOUT_TERMINAL {
+        bail!(
+            "Refusing to overwrite local file {} non-interactively. \
+             Re-run with --install-force or in a terminal.",
+            planned.dst.display()
+        );
+    }
+
+    let prompt = format!(
+        "Conflict at {} (category: {})",
+        planned.dst.display(),
+        planned.top_category.label()
+    );
+    let choice = Select::new(
+        &prompt,
+        vec!["keep", "replace", "keep-all", "replace-all", "abort"],
+    )
+    .prompt()
+    .with_context(|| "failed to read conflict choice")?;
+
+    match choice {
+        "keep" => Ok(ConflictAction::Keep),
+        "replace" => Ok(ConflictAction::Replace),
+        "keep-all" => {
+            *sticky = StickyMode::KeepAll;
+            Ok(ConflictAction::Keep)
+        }
+        "replace-all" => {
+            *sticky = StickyMode::ReplaceAll;
+            Ok(ConflictAction::Replace)
+        }
+        "abort" => bail!("Install aborted by user at conflict resolution."),
+        _ => unreachable!("inquire::Select returned an unexpected option"),
+    }
+}
+
+fn write_file(src: &Path, dst: &Path) -> Result<()> {
+    if let Some(parent) = dst.parent() {
+        fs::create_dir_all(parent)
+            .with_context(|| format!("failed to create directory {}", parent.display()))?;
+    }
+    fs::copy(src, dst)
+        .with_context(|| format!("failed to copy {} to {}", src.display(), dst.display()))?;
+    set_executable_bit_if_script(dst)?;
+    Ok(())
+}
+
+#[cfg(unix)]
+fn set_executable_bit_if_script(path: &Path) -> Result<()> {
+    use std::os::unix::fs::PermissionsExt;
+
+    let Some(ext) = path.extension().and_then(OsStr::to_str) else {
+        return Ok(());
+    };
+    if Language::from_extension(ext) == Language::Unsupported {
+        return Ok(());
+    }
+    fs::set_permissions(path, fs::Permissions::from_mode(0o755))
+        .with_context(|| format!("chmod {}", path.display()))?;
+    Ok(())
+}
+
+#[cfg(not(unix))]
+fn set_executable_bit_if_script(_path: &Path) -> Result<()> {
+    Ok(())
+}
+
+#[derive(Debug)]
+struct McpMergeReport {
+    added: Vec<String>,
+    kept_local: Vec<String>,
+    replaced: Vec<String>,
+    renamed: Vec<(String, String)>,
+    final_path: PathBuf,
+    missing_secrets: Vec<String>,
+}
+
+enum McpConflictAction {
+    KeepLocal,
+    TakeRemote,
+    RenameRemote,
+}
+
+fn merge_mcp_json(
+    local: Option<&Path>,
+    remote: &Path,
+    target: &Path,
+    force: bool,
+) -> Result<McpMergeReport> {
+    let remote_content = fs::read_to_string(remote)
+        .with_context(|| format!("failed to read remote mcp.json at {}", remote.display()))?;
+    let remote_config: McpServersConfig = serde_json::from_str(&remote_content)
+        .with_context(|| format!("failed to parse remote mcp.json at {}", remote.display()))?;
+
+    let mut merged = if let Some(local_path) = local {
+        let content = fs::read_to_string(local_path).with_context(|| {
+            format!("failed to read local mcp.json at {}", local_path.display())
+        })?;
+        serde_json::from_str::<McpServersConfig>(&content).with_context(|| {
+            format!("failed to parse local mcp.json at {}", local_path.display())
+        })?
+    } else {
+        McpServersConfig {
+            mcp_servers: IndexMap::new(),
+        }
+    };
+
+    let final_path = target.to_path_buf();
+    let mut report = McpMergeReport {
+        added: Vec::new(),
+        kept_local: Vec::new(),
+        replaced: Vec::new(),
+        renamed: Vec::new(),
+        final_path: final_path.clone(),
+        missing_secrets: Vec::new(),
+    };
+    let mut to_validate: Vec<String> = Vec::new();
+
+    for (name, remote_server) in remote_config.mcp_servers {
+        if let Some(local_server) = merged.mcp_servers.get(&name) {
+            if local_server == &remote_server {
+                continue;
+            }
+            match resolve_mcp_conflict(&name, force)? {
+                McpConflictAction::KeepLocal => report.kept_local.push(name),
+                McpConflictAction::TakeRemote => {
+                    merged.mcp_servers.insert(name.clone(), remote_server);
+                    report.replaced.push(name.clone());
+                    to_validate.push(name);
+                }
+                McpConflictAction::RenameRemote => {
+                    let new_name = unique_renamed_key(&name, &merged.mcp_servers);
+                    merged.mcp_servers.insert(new_name.clone(), remote_server);
+                    report.renamed.push((name, new_name.clone()));
+                    to_validate.push(new_name);
+                }
+            }
+        } else {
+            merged.mcp_servers.insert(name.clone(), remote_server);
+            report.added.push(name.clone());
+            to_validate.push(name);
+        }
+    }
+
+    for key in &to_validate {
+        let spec = merged
+            .mcp_servers
+            .get(key)
+            .expect("entry was just inserted");
+        spec.validate(key).with_context(|| {
+            format!("MCP server '{key}' failed validation; refusing to write merged mcp.json")
+        })?;
+    }
+
+    let serialized =
+        serde_json::to_string_pretty(&merged).context("failed to serialize merged mcp.json")?;
+    write_atomically(&final_path, &serialized)?;
+
+    let vault = Vault::init_bare();
+    let (_parsed, missing) = interpolate_secrets(&serialized, &vault);
+    let mut deduped: Vec<String> = Vec::new();
+    for s in missing {
+        if !deduped.contains(&s) {
+            deduped.push(s);
+        }
+    }
+    report.missing_secrets = deduped;
+
+    Ok(report)
+}
+
+fn resolve_mcp_conflict(name: &str, force: bool) -> Result<McpConflictAction> {
+    if force {
+        return Ok(McpConflictAction::TakeRemote);
+    }
+    if !*IS_STDOUT_TERMINAL {
+        bail!(
+            "MCP server '{name}' already exists locally. Refusing to merge non-interactively. \
+             Re-run with --install-force or in a terminal."
+        );
+    }
+    let rename_label = format!("rename remote as \"{name}-remote\"");
+    let prompt = format!("Conflict on MCP server '{name}'");
+    let choice = Select::new(
+        &prompt,
+        vec![
+            "keep local".to_string(),
+            "take remote".to_string(),
+            rename_label.clone(),
+            "abort merge".to_string(),
+        ],
+    )
+    .prompt()
+    .with_context(|| "failed to read MCP conflict choice")?;
+
+    if choice == "keep local" {
+        Ok(McpConflictAction::KeepLocal)
+    } else if choice == "take remote" {
+        Ok(McpConflictAction::TakeRemote)
+    } else if choice == rename_label {
+        Ok(McpConflictAction::RenameRemote)
+    } else if choice == "abort merge" {
+        bail!("Aborted MCP merge by user.")
+    } else {
+        unreachable!("inquire::Select returned an unexpected option")
+    }
+}
+
+fn unique_renamed_key(name: &str, existing: &IndexMap<String, McpServer>) -> String {
+    let base = format!("{name}-remote");
+    if !existing.contains_key(&base) {
+        return base;
+    }
+    for i in 2..=u32::MAX {
+        let candidate = format!("{name}-remote-{i}");
+        if !existing.contains_key(&candidate) {
+            return candidate;
+        }
+    }
+    unreachable!("ran out of suffix variants")
+}
+
+fn write_atomically(path: &Path, content: &str) -> Result<()> {
+    if let Some(parent) = path.parent() {
+        fs::create_dir_all(parent)
+            .with_context(|| format!("failed to create directory {}", parent.display()))?;
+    }
+    let tmp_path = path.with_extension("json.tmp");
+    fs::write(&tmp_path, content)
+        .with_context(|| format!("failed to write {}", tmp_path.display()))?;
+    fs::rename(&tmp_path, path).with_context(|| {
+        format!(
+            "failed to rename {} to {}",
+            tmp_path.display(),
+            path.display()
+        )
+    })?;
+    Ok(())
+}
+
+fn print_mcp_merge_report(report: &McpMergeReport) {
+    println!("\nMCP merge ({}):", report.final_path.display());
+    println!(
+        "  added: {}, replaced: {}, kept local: {}, renamed: {}",
+        report.added.len(),
+        report.replaced.len(),
+        report.kept_local.len(),
+        report.renamed.len()
+    );
+    if !report.added.is_empty() {
+        println!("  + new servers: {}", report.added.join(", "));
+    }
+    if !report.replaced.is_empty() {
+        println!("  ~ replaced:    {}", report.replaced.join(", "));
+    }
+    if !report.kept_local.is_empty() {
+        println!("  = kept local:  {}", report.kept_local.join(", "));
+    }
+    if !report.renamed.is_empty() {
+        let pairs: Vec<String> = report
+            .renamed
+            .iter()
+            .map(|(orig, new_)| format!("{orig} -> {new_}"))
+            .collect();
+        println!("  > renamed:     {}", pairs.join(", "));
+    }
+}
+
+fn handle_missing_secrets(missing: &[String]) -> Result<()> {
+    if missing.is_empty() {
+        return Ok(());
+    }
+    let (added, deferred) = if *IS_STDOUT_TERMINAL {
+        println!(
+            "\nThe merged mcp.json references {} secret(s) not yet in the vault.",
+            missing.len()
+        );
+        prompt_for_each_secret(missing)?
+    } else {
+        (Vec::new(), missing.to_vec())
+    };
+
+    print_secret_summary(&added, &deferred);
+    Ok(())
+}
+
+fn prompt_for_each_secret(missing: &[String]) -> Result<(Vec<String>, Vec<String>)> {
+    let mut vault = Vault::init_bare();
+    let mut password_file_ensured = false;
+    let mut added = Vec::new();
+    let mut deferred = Vec::new();
+
+    for name in missing {
+        let proceed = Confirm::new(&format!("Add {{{{ {name} }}}} to vault now?"))
+            .with_default(false)
+            .prompt()
+            .with_context(|| format!("failed to read confirmation for secret '{name}'"))?;
+        if !proceed {
+            deferred.push(name.clone());
+            continue;
+        }
+        if !password_file_ensured {
+            create_vault_password_file(&mut vault)
+                .context("Failed to initialize the vault password file")?;
+            password_file_ensured = true;
+        }
+
+        match vault.add_secret(name) {
+            Ok(()) => added.push(name.clone()),
+            Err(e) => {
+                eprintln!("Failed to add '{name}' to vault: {e:#}");
+                deferred.push(name.clone());
+            }
+        }
+    }
+
+    Ok((added, deferred))
+}
+
+fn print_secret_summary(added: &[String], deferred: &[String]) {
+    if !added.is_empty() {
+        println!(
+            "\nAdded {} secret(s) to the vault: {}",
+            added.len(),
+            added.join(", ")
+        );
+    }
+    if !deferred.is_empty() {
+        println!(
+            "\nThe following secrets are still required by your MCP servers. \
+             Add them with `loki --add-secret <NAME>` or `.vault add <NAME>` in the REPL:"
+        );
+        for name in deferred {
+            println!("  {{{{ {name} }}}}");
+        }
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn parse_url_no_ref() {
+        let (url, r) = parse_url_with_ref("https://github.com/foo/bar.git").unwrap();
+
+        assert_eq!(url, "https://github.com/foo/bar.git");
+        assert_eq!(r, None);
+    }
+
+    #[test]
+    fn parse_url_with_branch_ref() {
+        let (url, r) = parse_url_with_ref("https://github.com/foo/bar.git#main").unwrap();
+
+        assert_eq!(url, "https://github.com/foo/bar.git");
+        assert_eq!(r.as_deref(), Some("main"));
+    }
+
+    #[test]
+    fn parse_url_with_tag_ref() {
+        let (url, r) = parse_url_with_ref("https://github.com/foo/bar.git#v1.2.3").unwrap();
+
+        assert_eq!(url, "https://github.com/foo/bar.git");
+        assert_eq!(r.as_deref(), Some("v1.2.3"));
+    }
+
+    #[test]
+    fn parse_url_with_sha_ref() {
+        let (url, r) = parse_url_with_ref("https://github.com/foo/bar.git#abc1234").unwrap();
+
+        assert_eq!(url, "https://github.com/foo/bar.git");
+        assert_eq!(r.as_deref(), Some("abc1234"));
+    }
+
+    #[test]
+    fn parse_url_with_slash_in_ref() {
+        let (url, r) = parse_url_with_ref("git@github.com:foo/bar.git#release/v2").unwrap();
+
+        assert_eq!(url, "git@github.com:foo/bar.git");
+        assert_eq!(r.as_deref(), Some("release/v2"));
+    }
+
+    #[test]
+    fn parse_url_rejects_empty_ref() {
+        assert!(parse_url_with_ref("https://github.com/foo/bar.git#").is_err());
+    }
+
+    #[test]
+    fn parse_url_rejects_dotdot() {
+        assert!(parse_url_with_ref("https://github.com/foo/bar.git#foo..bar").is_err());
+    }
+
+    #[test]
+    fn parse_url_rejects_leading_dash_argument_injection() {
+        assert!(parse_url_with_ref("https://github.com/foo/bar.git#-evil").is_err());
+    }
+
+    #[test]
+    fn parse_url_rejects_shell_metachars() {
+        assert!(parse_url_with_ref("https://github.com/foo/bar.git#foo bar").is_err());
+        assert!(parse_url_with_ref("https://github.com/foo/bar.git#$inject").is_err());
+        assert!(parse_url_with_ref("https://github.com/foo/bar.git#;rm -rf /").is_err());
+    }
+
+    fn touch(p: &Path) {
+        if let Some(parent) = p.parent() {
+            fs::create_dir_all(parent).unwrap();
+        }
+        fs::write(p, b"").unwrap();
+    }
+
+    fn fresh_temp_dir(name: &str) -> PathBuf {
+        let dir = utils::temp_file(name, "");
+        fs::create_dir_all(&dir).unwrap();
+        dir
+    }
+
+    #[test]
+    fn remote_layout_is_empty_when_default() {
+        assert!(RemoteLayout::default().is_empty());
+    }
+
+    #[test]
+    fn remote_layout_is_not_empty_when_any_field_set() {
+        let l = RemoteLayout {
+            agents: Some(PathBuf::from("/x")),
+            ..RemoteLayout::default()
+        };
+
+        assert!(!l.is_empty());
+    }
+
+    #[test]
+    fn apply_filter_none_passes_through() {
+        let l = RemoteLayout {
+            agents: Some(PathBuf::from("a")),
+            roles: Some(PathBuf::from("r")),
+            macros: Some(PathBuf::from("m")),
+            functions_tools: Some(PathBuf::from("f")),
+            mcp_json: Some(PathBuf::from("j")),
+        };
+
+        let out = apply_filter(l, None);
+
+        assert!(out.agents.is_some() && out.roles.is_some() && out.macros.is_some());
+        assert!(out.functions_tools.is_some() && out.mcp_json.is_some());
+    }
+
+    #[test]
+    fn apply_filter_functions_keeps_only_tools_not_mcp() {
+        let l = RemoteLayout {
+            agents: Some(PathBuf::from("a")),
+            roles: None,
+            macros: None,
+            functions_tools: Some(PathBuf::from("f")),
+            mcp_json: Some(PathBuf::from("j")),
+        };
+
+        let out = apply_filter(l, Some(InstallFilter::Functions));
+
+        assert!(out.agents.is_none());
+        assert_eq!(out.functions_tools, Some(PathBuf::from("f")));
+        assert!(out.mcp_json.is_none());
+    }
+
+    #[test]
+    fn apply_filter_mcp_config_keeps_only_mcp_json() {
+        let l = RemoteLayout {
+            agents: Some(PathBuf::from("a")),
+            roles: None,
+            macros: None,
+            functions_tools: Some(PathBuf::from("f")),
+            mcp_json: Some(PathBuf::from("j")),
+        };
+
+        let out = apply_filter(l, Some(InstallFilter::McpConfig));
+
+        assert!(out.agents.is_none() && out.functions_tools.is_none());
+        assert_eq!(out.mcp_json, Some(PathBuf::from("j")));
+    }
+
+    #[test]
+    fn apply_filter_roles_keeps_only_roles() {
+        let l = RemoteLayout {
+            agents: Some(PathBuf::from("a")),
+            roles: Some(PathBuf::from("r")),
+            macros: Some(PathBuf::from("m")),
+            functions_tools: Some(PathBuf::from("f")),
+            mcp_json: Some(PathBuf::from("j")),
+        };
+
+        let out = apply_filter(l, Some(InstallFilter::Roles));
+
+        assert_eq!(out.roles, Some(PathBuf::from("r")));
+        assert!(out.agents.is_none() && out.macros.is_none());
+        assert!(out.functions_tools.is_none() && out.mcp_json.is_none());
+    }
+
+    #[test]
+    fn walk_files_skips_dot_git_and_collects_regular_files() {
+        let root = fresh_temp_dir("walk-test-");
+        touch(&root.join("a.txt"));
+        touch(&root.join("sub/b.txt"));
+        touch(&root.join(".git/HEAD"));
+        touch(&root.join(".git/objects/pack/foo"));
+
+        let mut files = walk_files(&root).unwrap();
+        files.sort();
+        let rels: Vec<_> = files
+            .iter()
+            .map(|p| p.strip_prefix(&root).unwrap().to_owned())
+            .collect();
+
+        assert_eq!(
+            rels,
+            vec![PathBuf::from("a.txt"), PathBuf::from("sub/b.txt")]
+        );
+        let _ = fs::remove_dir_all(&root);
+    }
+
+    #[cfg(unix)]
+    #[test]
+    fn walk_files_rejects_symlink() {
+        let root = fresh_temp_dir("walk-symlink-test-");
+        touch(&root.join("real.txt"));
+        std::os::unix::fs::symlink(root.join("real.txt"), root.join("link.txt")).unwrap();
+
+        let err = walk_files(&root).unwrap_err();
+
+        assert!(
+            err.to_string().contains("Symlink not allowed"),
+            "got error: {err}"
+        );
+        let _ = fs::remove_dir_all(&root);
+    }
+
+    #[test]
+    fn scan_remote_layout_finds_known_subdirs() {
+        let root = fresh_temp_dir("scan-test-");
+        fs::create_dir_all(root.join("agents/sample")).unwrap();
+        fs::create_dir_all(root.join("roles")).unwrap();
+        fs::create_dir_all(root.join("macros")).unwrap();
+        fs::create_dir_all(root.join("functions/tools")).unwrap();
+        touch(&root.join("functions/mcp.json"));
+        touch(&root.join("README.md"));
+
+        let layout = scan_remote_layout(&root).unwrap();
+        assert!(layout.agents.is_some());
+        assert!(layout.roles.is_some());
+        assert!(layout.macros.is_some());
+        assert!(layout.functions_tools.is_some());
+        assert!(layout.mcp_json.is_some());
+        let _ = fs::remove_dir_all(&root);
+    }
+
+    #[test]
+    fn scan_remote_layout_ignores_unrelated_files() {
+        let root = fresh_temp_dir("scan-unrelated-");
+        fs::create_dir_all(root.join("docs")).unwrap();
+        touch(&root.join("docs/intro.md"));
+        touch(&root.join("README.md"));
+
+        let layout = scan_remote_layout(&root).unwrap();
+
+        assert!(layout.is_empty());
+        let _ = fs::remove_dir_all(&root);
+    }
+
+    #[test]
+    fn classify_file_new_when_dst_missing() {
+        let dir = fresh_temp_dir("classify-new-");
+        let src = dir.join("src");
+        fs::write(&src, b"hello").unwrap();
+
+        let dst = dir.join("dst");
+
+        assert_eq!(classify_file(&src, &dst).unwrap(), PlannedKind::New);
+        let _ = fs::remove_dir_all(&dir);
+    }
+
+    #[test]
+    fn classify_file_identical_when_bytes_match() {
+        let dir = fresh_temp_dir("classify-identical-");
+        let src = dir.join("src");
+        let dst = dir.join("dst");
+
+        fs::write(&src, b"same bytes").unwrap();
+        fs::write(&dst, b"same bytes").unwrap();
+
+        assert_eq!(classify_file(&src, &dst).unwrap(), PlannedKind::Identical);
+        let _ = fs::remove_dir_all(&dir);
+    }
+
+    #[test]
+    fn classify_file_conflict_when_bytes_differ() {
+        let dir = fresh_temp_dir("classify-conflict-");
+        let src = dir.join("src");
+        let dst = dir.join("dst");
+
+        fs::write(&src, b"version A").unwrap();
+        fs::write(&dst, b"version B").unwrap();
+
+        assert_eq!(classify_file(&src, &dst).unwrap(), PlannedKind::Conflict);
+        let _ = fs::remove_dir_all(&dir);
+    }
+
+    fn write_mcp(path: &Path, json: &str) {
+        if let Some(parent) = path.parent() {
+            fs::create_dir_all(parent).unwrap();
+        }
+        fs::write(path, json).unwrap();
+    }
+
+    const FIXTURE_REMOTE: &str = r#"{
+        "mcpServers": {
+            "alpha": {"type": "stdio", "command": "echo", "args": ["a"]},
+            "beta":  {"type": "stdio", "command": "echo", "args": ["b"]}
+        }
+    }"#;
+
+    #[test]
+    fn unique_renamed_key_appends_remote_suffix() {
+        let map: IndexMap<String, McpServer> = IndexMap::new();
+        assert_eq!(unique_renamed_key("foo", &map), "foo-remote");
+    }
+
+    #[test]
+    fn unique_renamed_key_appends_numeric_when_remote_taken() {
+        let mut map: IndexMap<String, McpServer> = IndexMap::new();
+        map.insert(
+            "foo-remote".to_string(),
+            serde_json::from_str(r#"{"type":"stdio","command":"x"}"#).unwrap(),
+        );
+        assert_eq!(unique_renamed_key("foo", &map), "foo-remote-2");
+    }
+
+    #[test]
+    fn merge_into_empty_local_adds_all_remote_servers() {
+        let dir = fresh_temp_dir("merge-empty-");
+        let remote = dir.join("remote.json");
+        let target = dir.join("target.json");
+        write_mcp(&remote, FIXTURE_REMOTE);
+
+        let report = merge_mcp_json(None, &remote, &target, false).unwrap();
+
+        assert_eq!(report.added, vec!["alpha", "beta"]);
+        assert!(report.kept_local.is_empty());
+        assert!(report.replaced.is_empty());
+        assert!(report.renamed.is_empty());
+        assert!(target.exists());
+        let _ = fs::remove_dir_all(&dir);
+    }
+
+    #[test]
+    fn merge_force_replaces_local_on_conflict() {
+        let dir = fresh_temp_dir("merge-force-");
+        let remote = dir.join("remote.json");
+        let target = dir.join("target.json");
+        write_mcp(
+            &target,
+            r#"{"mcpServers": {"alpha": {"type": "stdio", "command": "OLD"}}}"#,
+        );
+        write_mcp(&remote, FIXTURE_REMOTE);
+
+        let report = merge_mcp_json(Some(&target), &remote, &target, true).unwrap();
+
+        assert_eq!(report.added, vec!["beta"]);
+        assert_eq!(report.replaced, vec!["alpha"]);
+
+        let written = fs::read_to_string(&target).unwrap();
+
+        assert!(written.contains("\"command\": \"echo\""), "got: {written}");
+        assert!(!written.contains("OLD"));
+        let _ = fs::remove_dir_all(&dir);
+    }
+
+    #[test]
+    fn merge_non_tty_conflict_aborts_without_force() {
+        let dir = fresh_temp_dir("merge-non-tty-");
+        let remote = dir.join("remote.json");
+        let target = dir.join("target.json");
+        write_mcp(
+            &target,
+            r#"{"mcpServers": {"alpha": {"type": "stdio", "command": "LOCAL"}}}"#,
+        );
+        write_mcp(&remote, FIXTURE_REMOTE);
+
+        let err = merge_mcp_json(Some(&target), &remote, &target, false).unwrap_err();
+
+        assert!(
+            err.to_string()
+                .contains("Refusing to merge non-interactively"),
+            "got: {err}"
+        );
+        let _ = fs::remove_dir_all(&dir);
+    }
+
+    #[test]
+    fn merge_rejects_invalid_remote_server() {
+        let dir = fresh_temp_dir("merge-invalid-");
+        let remote = dir.join("remote.json");
+        let target = dir.join("target.json");
+        write_mcp(&remote, r#"{"mcpServers": {"broken": {"type": "stdio"}}}"#);
+
+        let err = merge_mcp_json(None, &remote, &target, false).unwrap_err();
+
+        assert!(
+            format!("{err:#}").contains("missing a \"command\" field"),
+            "got: {err:#}"
+        );
+        let _ = fs::remove_dir_all(&dir);
+    }
+
+    #[tokio::test(flavor = "multi_thread", worker_threads = 1)]
+    async fn merge_detects_missing_secrets_in_output() {
+        let dir = fresh_temp_dir("merge-secret-");
+        let remote = dir.join("remote.json");
+        let target = dir.join("target.json");
+        write_mcp(
+            &remote,
+            r#"{"mcpServers": {"x": {"type":"stdio","command":"echo","env":{"K":"{{LOKI_TEST_MERGE_SECRET}}"}}}}"#,
+        );
+
+        let report = merge_mcp_json(None, &remote, &target, false).unwrap();
+
+        assert_eq!(report.missing_secrets, vec!["LOKI_TEST_MERGE_SECRET"]);
+        let _ = fs::remove_dir_all(&dir);
+    }
+
+    #[test]
+    fn merge_is_idempotent_on_re_run() {
+        let dir = fresh_temp_dir("merge-idempotent-");
+        let remote = dir.join("remote.json");
+        let target = dir.join("target.json");
+        write_mcp(&remote, FIXTURE_REMOTE);
+
+        merge_mcp_json(None, &remote, &target, false).unwrap();
+        let after_first = fs::read(&target).unwrap();
+
+        let report = merge_mcp_json(Some(&target), &remote, &target, false).unwrap();
+        assert!(report.added.is_empty(), "got: {:?}", report.added);
+        let after_second = fs::read(&target).unwrap();
+
+        assert_eq!(after_first, after_second);
+        let _ = fs::remove_dir_all(&dir);
+    }
+
+    #[test]
+    fn handle_missing_secrets_noop_on_empty_input() {
+        assert!(handle_missing_secrets(&[]).is_ok());
+    }
+
+    #[test]
+    fn handle_missing_secrets_defers_all_in_non_tty() {
+        let missing = vec![
+            "LOKI_TEST_STEP4_A".to_string(),
+            "LOKI_TEST_STEP4_B".to_string(),
+        ];
+
+        assert!(handle_missing_secrets(&missing).is_ok());
+    }
+}
diff --git a/src/config/macros.rs b/src/config/macros.rs
index 2b93c5d..289952d 100644
--- a/src/config/macros.rs
+++ b/src/config/macros.rs
@@ -1,12 +1,12 @@
-use crate::config::{Config, GlobalConfig, RoleLike, ensure_parent_exists};
+use crate::config::paths;
+use crate::config::{RequestContext, RoleLike, ensure_parent_exists};
 use crate::repl::{run_repl_command, split_args_text};
 use crate::utils::{AbortSignal, multiline_text};
-use anyhow::{Result, anyhow};
+use anyhow::{Context, Result, anyhow};
 use indexmap::IndexMap;
-use parking_lot::RwLock;
 use rust_embed::Embed;
 use serde::Deserialize;
-use std::fs::File;
+use std::fs::{File, read_to_string};
 use std::io::Write;
 use std::sync::Arc;
 
@@ -16,12 +16,12 @@ struct MacroAssets;
 
 #[async_recursion::async_recursion]
 pub async fn macro_execute(
-    config: &GlobalConfig,
+    ctx: &mut RequestContext,
     name: &str,
     args: Option<&str>,
     abort_signal: AbortSignal,
 ) -> Result<()> {
-    let macro_value = Config::load_macro(name)?;
+    let macro_value = Macro::load(name)?;
     let (mut new_args, text) = split_args_text(args.unwrap_or_default(), cfg!(windows));
     if !text.is_empty() {
         new_args.push(text.to_string());
@@ -29,25 +29,42 @@ pub async fn macro_execute(
     let variables = macro_value
         .resolve_variables(&new_args)
         .map_err(|err| anyhow!("{err}. Usage: {}", macro_value.usage(name)))?;
-    let role = config.read().extract_role();
-    let mut config = config.read().clone();
-    config.temperature = role.temperature();
-    config.top_p = role.top_p();
-    config.enabled_tools = role.enabled_tools().clone();
-    config.enabled_mcp_servers = role.enabled_mcp_servers().clone();
-    config.macro_flag = true;
-    config.model = role.model().clone();
-    config.role = None;
-    config.session = None;
-    config.rag = None;
-    config.agent = None;
-    config.discontinuous_last_message();
-    let config = Arc::new(RwLock::new(config));
-    config.write().macro_flag = true;
+    let role = ctx.extract_role(ctx.app.config.as_ref());
+    let mut app_config = (*ctx.app.config).clone();
+    app_config.temperature = role.temperature();
+    app_config.top_p = role.top_p();
+    app_config.enabled_tools = role.enabled_tools().clone();
+    app_config.enabled_mcp_servers = role.enabled_mcp_servers().clone();
+
+    let mut app_state = (*ctx.app).clone();
+    app_state.config = Arc::new(app_config);
+
+    let mut macro_ctx = RequestContext::new(Arc::new(app_state), ctx.working_mode);
+    macro_ctx.macro_flag = true;
+    macro_ctx.info_flag = ctx.info_flag;
+    macro_ctx.model = role.model().clone();
+    macro_ctx.agent_variables = ctx.agent_variables.clone();
+    macro_ctx.last_message = ctx.last_message.clone();
+    macro_ctx.supervisor = ctx.supervisor.clone();
+    macro_ctx.parent_supervisor = ctx.parent_supervisor.clone();
+    macro_ctx.self_agent_id = ctx.self_agent_id.clone();
+    macro_ctx.inbox = ctx.inbox.clone();
+    macro_ctx.escalation_queue = ctx.escalation_queue.clone();
+    macro_ctx.current_depth = ctx.current_depth;
+    macro_ctx.auto_continue_count = ctx.auto_continue_count;
+    macro_ctx.todo_list = ctx.todo_list.clone();
+    macro_ctx.tool_scope.tool_tracker = ctx.tool_scope.tool_tracker.clone();
+    macro_ctx.discontinuous_last_message();
+
+    let app = macro_ctx.app.config.clone();
+    macro_ctx
+        .bootstrap_tools(app.as_ref(), true, abort_signal.clone())
+        .await?;
+
     for step in &macro_value.steps {
         let command = Macro::interpolate_command(step, &variables);
         println!(">> {}", multiline_text(&command));
-        run_repl_command(&config, abort_signal.clone(), &command).await?;
+        run_repl_command(&mut macro_ctx, abort_signal.clone(), &command).await?;
     }
     Ok(())
 }
@@ -60,10 +77,18 @@ pub struct Macro {
 }
 
 impl Macro {
-    pub fn install_macros() -> Result<()> {
+    pub fn load(name: &str) -> Result<Macro> {
+        let path = paths::macro_file(name);
+        let err = || format!("Failed to load macro '{name}' at '{}'", path.display());
+        let content = read_to_string(&path).with_context(err)?;
+        let value: Macro = serde_yaml::from_str(&content).with_context(err)?;
+        Ok(value)
+    }
+
+    pub fn install_macros(force: bool) -> Result<()> {
         info!(
             "Installing built-in macros in {}",
-            Config::macros_dir().display()
+            paths::macros_dir().display()
         );
 
         for file in MacroAssets::iter() {
@@ -71,9 +96,9 @@ impl Macro {
             let embedded_file = MacroAssets::get(&file)
                 .ok_or_else(|| anyhow!("Failed to load embedded macro file: {}", file.as_ref()))?;
             let content = unsafe { std::str::from_utf8_unchecked(&embedded_file.data) };
-            let file_path = Config::macros_dir().join(file.as_ref());
+            let file_path = paths::macros_dir().join(file.as_ref());
 
-            if file_path.exists() {
+            if file_path.exists() && !force {
                 debug!(
                     "Macro file already exists, skipping: {}",
                     file_path.display()
@@ -144,3 +169,205 @@ pub struct MacroVariable {
     pub rest: bool,
     pub default: Option<String>,
 }
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    fn var(name: &str, rest: bool, default: Option<&str>) -> MacroVariable {
+        MacroVariable {
+            name: name.to_string(),
+            rest,
+            default: default.map(String::from),
+        }
+    }
+
+    fn macro_with_vars(vars: Vec<MacroVariable>) -> Macro {
+        Macro {
+            variables: vars,
+            steps: vec![],
+        }
+    }
+
+    #[test]
+    fn resolve_no_variables() {
+        let m = macro_with_vars(vec![]);
+        let result = m.resolve_variables(&[]).unwrap();
+        assert!(result.is_empty());
+    }
+
+    #[test]
+    fn resolve_required_variable_provided() {
+        let m = macro_with_vars(vec![var("name", false, None)]);
+        let result = m.resolve_variables(&["Alice".into()]).unwrap();
+        assert_eq!(result["name"], "Alice");
+    }
+
+    #[test]
+    fn resolve_required_variable_missing_errors() {
+        let m = macro_with_vars(vec![var("name", false, None)]);
+        let result = m.resolve_variables(&[]);
+        assert!(result.is_err());
+        assert!(result.unwrap_err().to_string().contains("name"));
+    }
+
+    #[test]
+    fn resolve_default_variable_uses_default() {
+        let m = macro_with_vars(vec![var("color", false, Some("blue"))]);
+        let result = m.resolve_variables(&[]).unwrap();
+        assert_eq!(result["color"], "blue");
+    }
+
+    #[test]
+    fn resolve_default_variable_overridden() {
+        let m = macro_with_vars(vec![var("color", false, Some("blue"))]);
+        let result = m.resolve_variables(&["red".into()]).unwrap();
+        assert_eq!(result["color"], "red");
+    }
+
+    #[test]
+    fn resolve_rest_variable_captures_all_remaining() {
+        let m = macro_with_vars(vec![var("first", false, None), var("rest", true, None)]);
+        let result = m
+            .resolve_variables(&["a".into(), "b".into(), "c".into()])
+            .unwrap();
+        assert_eq!(result["first"], "a");
+        assert_eq!(result["rest"], "b c");
+    }
+
+    #[test]
+    fn resolve_rest_variable_with_default() {
+        let m = macro_with_vars(vec![var("args", true, Some("default text"))]);
+        let result = m.resolve_variables(&[]).unwrap();
+        assert_eq!(result["args"], "default text");
+    }
+
+    #[test]
+    fn resolve_multiple_variables() {
+        let m = macro_with_vars(vec![
+            var("a", false, None),
+            var("b", false, None),
+            var("c", false, Some("default_c")),
+        ]);
+        let result = m.resolve_variables(&["x".into(), "y".into()]).unwrap();
+        assert_eq!(result["a"], "x");
+        assert_eq!(result["b"], "y");
+        assert_eq!(result["c"], "default_c");
+    }
+
+    #[test]
+    fn usage_no_variables() {
+        let m = macro_with_vars(vec![]);
+        assert_eq!(m.usage("my-macro"), "my-macro");
+    }
+
+    #[test]
+    fn usage_required_variable() {
+        let m = macro_with_vars(vec![var("name", false, None)]);
+        assert_eq!(m.usage("greet"), "greet <name>");
+    }
+
+    #[test]
+    fn usage_optional_variable() {
+        let m = macro_with_vars(vec![var("color", false, Some("blue"))]);
+        assert_eq!(m.usage("paint"), "paint [color]");
+    }
+
+    #[test]
+    fn usage_rest_variable() {
+        let m = macro_with_vars(vec![var("args", true, None)]);
+        assert_eq!(m.usage("run"), "run <args>...");
+    }
+
+    #[test]
+    fn usage_rest_with_default() {
+        let m = macro_with_vars(vec![var("args", true, Some("default"))]);
+        assert_eq!(m.usage("run"), "run [args]...");
+    }
+
+    #[test]
+    fn usage_mixed_variables() {
+        let m = macro_with_vars(vec![
+            var("target", false, None),
+            var("flags", true, Some("")),
+        ]);
+        assert_eq!(m.usage("build"), "build <target> [flags]...");
+    }
+
+    #[test]
+    fn interpolate_replaces_variables() {
+        let vars = IndexMap::from([("name".to_string(), "world".to_string())]);
+        let result = Macro::interpolate_command("hello {{name}}", &vars);
+        assert_eq!(result, "hello world");
+    }
+
+    #[test]
+    fn interpolate_multiple_variables() {
+        let vars = IndexMap::from([
+            ("a".to_string(), "1".to_string()),
+            ("b".to_string(), "2".to_string()),
+        ]);
+        let result = Macro::interpolate_command("{{a}} + {{b}}", &vars);
+        assert_eq!(result, "1 + 2");
+    }
+
+    #[test]
+    fn interpolate_no_variables_passthrough() {
+        let vars = IndexMap::new();
+        let result = Macro::interpolate_command("no vars here", &vars);
+        assert_eq!(result, "no vars here");
+    }
+
+    #[test]
+    fn interpolate_variable_not_found_left_as_is() {
+        let vars = IndexMap::new();
+        let result = Macro::interpolate_command("hello {{missing}}", &vars);
+        assert_eq!(result, "hello {{missing}}");
+    }
+
+    #[test]
+    fn deserialize_macro_from_yaml() {
+        let yaml = r#"
+steps:
+  - ".role coder"
+  - "write code for {{task}}"
+variables:
+  - name: task
+"#;
+        let m: Macro = serde_yaml::from_str(yaml).unwrap();
+        assert_eq!(m.steps.len(), 2);
+        assert_eq!(m.variables.len(), 1);
+        assert_eq!(m.variables[0].name, "task");
+        assert!(!m.variables[0].rest);
+        assert!(m.variables[0].default.is_none());
+    }
+
+    #[test]
+    fn deserialize_macro_with_defaults() {
+        let yaml = r#"
+steps:
+  - "test"
+variables:
+  - name: mode
+    default: "fast"
+  - name: args
+    rest: true
+    default: "none"
+"#;
+        let m: Macro = serde_yaml::from_str(yaml).unwrap();
+        assert_eq!(m.variables[0].default, Some("fast".to_string()));
+        assert!(m.variables[1].rest);
+        assert_eq!(m.variables[1].default, Some("none".to_string()));
+    }
+
+    #[test]
+    fn deserialize_macro_no_variables() {
+        let yaml = r#"
+steps:
+  - ".help"
+"#;
+        let m: Macro = serde_yaml::from_str(yaml).unwrap();
+        assert!(m.variables.is_empty());
+        assert_eq!(m.steps.len(), 1);
+    }
+}
diff --git a/src/config/mcp_factory.rs b/src/config/mcp_factory.rs
new file mode 100644
index 0000000..1f05401
--- /dev/null
+++ b/src/config/mcp_factory.rs
@@ -0,0 +1,307 @@
+use crate::mcp::{ConnectedServer, JsonField, McpServer, McpTransportType, spawn_mcp_server};
+
+use anyhow::Result;
+use parking_lot::Mutex;
+use std::collections::HashMap;
+use std::path::Path;
+use std::sync::{Arc, Weak};
+
+#[derive(Clone, Debug, Eq, Hash, PartialEq)]
+pub struct McpServerKey {
+    pub name: String,
+    pub transport: McpTransportKey,
+}
+
+#[derive(Clone, Debug, Eq, Hash, PartialEq)]
+pub enum McpTransportKey {
+    Stdio {
+        command: String,
+        args: Vec<String>,
+        env: Vec<(String, String)>,
+    },
+    Remote {
+        transport_type: McpTransportType,
+        url: String,
+        headers: Vec<(String, String)>,
+    },
+}
+
+impl McpServerKey {
+    pub fn from_spec(name: &str, spec: &McpServer) -> Self {
+        let transport = if spec.is_remote() {
+            let url = spec.url.clone().unwrap_or_default();
+            let mut headers: Vec<(String, String)> = spec
+                .headers
+                .as_ref()
+                .map(|h| h.iter().map(|(k, v)| (k.clone(), v.clone())).collect())
+                .unwrap_or_default();
+            headers.sort();
+            McpTransportKey::Remote {
+                transport_type: spec.transport_type.clone(),
+                url,
+                headers,
+            }
+        } else {
+            let command = spec.command.clone().unwrap_or_default();
+            let mut args = spec.args.clone().unwrap_or_default();
+            args.sort();
+            let mut env: Vec<(String, String)> = spec
+                .env
+                .as_ref()
+                .map(|e| {
+                    e.iter()
+                        .map(|(k, v)| {
+                            let v_str = match v {
+                                JsonField::Str(s) => s.clone(),
+                                JsonField::Bool(b) => b.to_string(),
+                                JsonField::Int(i) => i.to_string(),
+                            };
+                            (k.clone(), v_str)
+                        })
+                        .collect()
+                })
+                .unwrap_or_default();
+            env.sort();
+            McpTransportKey::Stdio { command, args, env }
+        };
+        Self {
+            name: name.into(),
+            transport,
+        }
+    }
+}
+
+#[derive(Default)]
+pub struct McpFactory {
+    active: Mutex<HashMap<McpServerKey, Weak<ConnectedServer>>>,
+}
+
+impl McpFactory {
+    pub fn try_get_active(&self, key: &McpServerKey) -> Option<Arc<ConnectedServer>> {
+        let map = self.active.lock();
+        map.get(key).and_then(|weak| weak.upgrade())
+    }
+
+    pub fn insert_active(&self, key: McpServerKey, handle: &Arc<ConnectedServer>) {
+        let mut map = self.active.lock();
+        map.insert(key, Arc::downgrade(handle));
+    }
+
+    pub async fn acquire(
+        &self,
+        name: &str,
+        spec: &McpServer,
+        log_path: Option<&Path>,
+    ) -> Result<Arc<ConnectedServer>> {
+        let key = McpServerKey::from_spec(name, spec);
+
+        if let Some(existing) = self.try_get_active(&key) {
+            return Ok(existing);
+        }
+
+        let handle = spawn_mcp_server(spec, log_path).await?;
+        self.insert_active(key, &handle);
+        Ok(handle)
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use crate::mcp::{JsonField, McpServer, McpTransportType};
+    use indexmap::IndexMap;
+    use std::collections::HashMap;
+
+    fn stdio_spec(
+        command: &str,
+        args: Option<Vec<String>>,
+        env: Option<IndexMap<String, JsonField>>,
+    ) -> McpServer {
+        McpServer {
+            transport_type: McpTransportType::Stdio,
+            command: Some(command.to_string()),
+            args,
+            env,
+            cwd: None,
+            url: None,
+            headers: None,
+        }
+    }
+
+    fn remote_spec(
+        transport: McpTransportType,
+        url: &str,
+        headers: Option<IndexMap<String, String>>,
+    ) -> McpServer {
+        McpServer {
+            transport_type: transport,
+            command: None,
+            args: None,
+            env: None,
+            cwd: None,
+            url: Some(url.to_string()),
+            headers,
+        }
+    }
+
+    #[test]
+    fn key_from_stdio_spec_captures_command_args_env() {
+        let mut env = IndexMap::new();
+        env.insert("TOKEN".into(), JsonField::Str("abc".into()));
+        let spec = stdio_spec("npx", Some(vec!["-y".into(), "server".into()]), Some(env));
+        let key = McpServerKey::from_spec("my-server", &spec);
+
+        assert_eq!(key.name, "my-server");
+        match &key.transport {
+            McpTransportKey::Stdio { command, args, env } => {
+                assert_eq!(command, "npx");
+                assert_eq!(args, &["-y", "server"]);
+                assert_eq!(env, &[("TOKEN".to_string(), "abc".to_string())]);
+            }
+            _ => panic!("expected Stdio transport key"),
+        }
+    }
+
+    #[test]
+    fn key_from_stdio_spec_sorts_args_and_env() {
+        let mut env = IndexMap::new();
+        env.insert("Z_VAR".into(), JsonField::Str("z".into()));
+        env.insert("A_VAR".into(), JsonField::Int(42));
+        let spec = stdio_spec(
+            "cmd",
+            Some(vec!["charlie".into(), "alpha".into(), "bravo".into()]),
+            Some(env),
+        );
+        let key = McpServerKey::from_spec("s", &spec);
+
+        match &key.transport {
+            McpTransportKey::Stdio { args, env, .. } => {
+                assert_eq!(args, &["alpha", "bravo", "charlie"]);
+                assert_eq!(env[0].0, "A_VAR");
+                assert_eq!(env[0].1, "42");
+                assert_eq!(env[1].0, "Z_VAR");
+                assert_eq!(env[1].1, "z");
+            }
+            _ => panic!("expected Stdio"),
+        }
+    }
+
+    #[test]
+    fn key_from_stdio_spec_defaults_empty_when_none() {
+        let spec = stdio_spec("echo", None, None);
+        let key = McpServerKey::from_spec("bare", &spec);
+
+        match &key.transport {
+            McpTransportKey::Stdio { command, args, env } => {
+                assert_eq!(command, "echo");
+                assert!(args.is_empty());
+                assert!(env.is_empty());
+            }
+            _ => panic!("expected Stdio"),
+        }
+    }
+
+    #[test]
+    fn key_from_remote_http_spec() {
+        let spec = remote_spec(McpTransportType::Http, "http://localhost:8080", None);
+        let key = McpServerKey::from_spec("http-srv", &spec);
+
+        assert_eq!(key.name, "http-srv");
+        match &key.transport {
+            McpTransportKey::Remote {
+                transport_type,
+                url,
+                headers,
+            } => {
+                assert_eq!(*transport_type, McpTransportType::Http);
+                assert_eq!(url, "http://localhost:8080");
+                assert!(headers.is_empty());
+            }
+            _ => panic!("expected Remote"),
+        }
+    }
+
+    #[test]
+    fn key_from_remote_sse_spec_with_sorted_headers() {
+        let mut hdrs = IndexMap::new();
+        hdrs.insert("Z-Key".into(), "z-val".into());
+        hdrs.insert("A-Key".into(), "a-val".into());
+        let spec = remote_spec(McpTransportType::Sse, "http://sse.example.com", Some(hdrs));
+        let key = McpServerKey::from_spec("sse-srv", &spec);
+
+        match &key.transport {
+            McpTransportKey::Remote { headers, .. } => {
+                assert_eq!(headers[0], ("A-Key".to_string(), "a-val".to_string()));
+                assert_eq!(headers[1], ("Z-Key".to_string(), "z-val".to_string()));
+            }
+            _ => panic!("expected Remote"),
+        }
+    }
+
+    #[test]
+    fn key_equality_same_spec_produces_equal_keys() {
+        let spec = stdio_spec("npx", Some(vec!["a".into()]), None);
+        let k1 = McpServerKey::from_spec("s", &spec);
+        let k2 = McpServerKey::from_spec("s", &spec);
+        assert_eq!(k1, k2);
+    }
+
+    #[test]
+    fn key_inequality_different_names() {
+        let spec = stdio_spec("npx", None, None);
+        let k1 = McpServerKey::from_spec("a", &spec);
+        let k2 = McpServerKey::from_spec("b", &spec);
+        assert_ne!(k1, k2);
+    }
+
+    #[test]
+    fn key_inequality_different_commands() {
+        let s1 = stdio_spec("npx", None, None);
+        let s2 = stdio_spec("node", None, None);
+        let k1 = McpServerKey::from_spec("s", &s1);
+        let k2 = McpServerKey::from_spec("s", &s2);
+        assert_ne!(k1, k2);
+    }
+
+    #[test]
+    fn key_env_bool_and_int_coerce_to_string() {
+        let mut env = IndexMap::new();
+        env.insert("FLAG".into(), JsonField::Bool(true));
+        env.insert("PORT".into(), JsonField::Int(3000));
+        let spec = stdio_spec("cmd", None, Some(env));
+        let key = McpServerKey::from_spec("s", &spec);
+
+        match &key.transport {
+            McpTransportKey::Stdio { env, .. } => {
+                let map: HashMap<&str, &str> =
+                    env.iter().map(|(k, v)| (k.as_str(), v.as_str())).collect();
+                assert_eq!(map["FLAG"], "true");
+                assert_eq!(map["PORT"], "3000");
+            }
+            _ => panic!("expected Stdio"),
+        }
+    }
+
+    #[test]
+    fn factory_try_get_active_returns_none_when_empty() {
+        let factory = McpFactory::default();
+        let spec = stdio_spec("cmd", None, None);
+        let key = McpServerKey::from_spec("s", &spec);
+        assert!(factory.try_get_active(&key).is_none());
+    }
+
+    #[test]
+    fn factory_try_get_active_returns_none_for_unknown_key() {
+        let factory = McpFactory::default();
+        let spec = stdio_spec("cmd", None, None);
+        let key = McpServerKey::from_spec("s", &spec);
+        assert!(factory.try_get_active(&key).is_none());
+    }
+
+    #[test]
+    fn factory_default_has_empty_active_map() {
+        let factory = McpFactory::default();
+        let map = factory.active.lock();
+        assert!(map.is_empty());
+    }
+}
diff --git a/src/config/mod.rs b/src/config/mod.rs
index bd788c5..683ab17 100644
--- a/src/config/mod.rs
+++ b/src/config/mod.rs
@@ -1,64 +1,64 @@
 mod agent;
+mod app_config;
+mod app_state;
 mod input;
+mod install_remote;
 mod macros;
+mod mcp_factory;
+pub(crate) mod paths;
 mod prompts;
+mod rag_cache;
+mod request_context;
 mod role;
 mod session;
 pub(crate) mod todo;
+mod tool_scope;
+mod update;
 
-pub use self::agent::{Agent, AgentVariables, complete_agent_variables, list_agents};
+pub use self::agent::{
+    Agent, AgentVariable, AgentVariables, complete_agent_variables, list_agents,
+};
+#[allow(unused_imports)]
+pub use self::app_config::AppConfig;
+#[allow(unused_imports)]
+pub use self::app_state::AppState;
 pub use self::input::Input;
+pub use self::install_remote::{install_remote, install_remote_from_repl_args};
+#[allow(unused_imports)]
+pub use self::request_context::{RenderMode, RequestContext};
 pub use self::role::{
     CODE_ROLE, CREATE_TITLE_ROLE, EXPLAIN_SHELL_ROLE, Role, RoleLike, SHELL_ROLE,
 };
 use self::session::Session;
-pub use macros::macro_execute;
-use mem::take;
-
+pub use self::update::run_self_update;
 use crate::client::{
     ClientConfig, MessageContentToolCalls, Model, ModelType, OPENAI_COMPATIBLE_PROVIDERS,
-    ProviderModels, create_client_config, list_client_types, list_models,
+    ProviderModels, create_client_config, list_client_types,
 };
-use crate::function::user_interaction::USER_FUNCTION_PREFIX;
-use crate::function::{FunctionDeclaration, Functions, ToolCallTracker, ToolResult};
+use crate::function::{FunctionDeclaration, Functions};
 use crate::rag::Rag;
-use crate::render::{MarkdownRender, RenderOptions};
 use crate::utils::*;
+pub use macros::macro_execute;
 
 use crate::config::macros::Macro;
-use crate::mcp::{
-    MCP_DESCRIBE_META_FUNCTION_NAME_PREFIX, MCP_INVOKE_META_FUNCTION_NAME_PREFIX,
-    MCP_SEARCH_META_FUNCTION_NAME_PREFIX, McpRegistry,
-};
-use crate::supervisor::Supervisor;
-use crate::supervisor::escalation::EscalationQueue;
-use crate::supervisor::mailbox::Inbox;
 use crate::vault::{GlobalVault, Vault, create_vault_password_file, interpolate_secrets};
 use anyhow::{Context, Result, anyhow, bail};
 use fancy_regex::Regex;
 use indexmap::IndexMap;
 use indoc::formatdoc;
-use inquire::{Confirm, MultiSelect, Select, Text, list_option::ListOption, validator::Validation};
-use log::LevelFilter;
-use parking_lot::RwLock;
+use inquire::{Confirm, Select};
 use serde::{Deserialize, Serialize};
 use serde_json::json;
-use std::collections::{HashMap, HashSet};
+use std::collections::HashMap;
 use std::sync::LazyLock;
 use std::{
     env,
-    fs::{
-        File, OpenOptions, create_dir_all, read_dir, read_to_string, remove_dir_all, remove_file,
-    },
+    fs::{File, create_dir_all, read_dir, read_to_string},
     io::Write,
-    mem,
     path::{Path, PathBuf},
     process,
     sync::{Arc, OnceLock},
 };
-use syntect::highlighting::ThemeSet;
-use terminal_colorsaurus::{ColorScheme, QueryOptions, color_scheme};
-use tokio::runtime::Handle;
 
 pub const TEMP_ROLE_NAME: &str = "temp";
 pub const TEMP_RAG_NAME: &str = "temp";
@@ -72,6 +72,7 @@ const DARK_THEME: &[u8] = include_bytes!("../../assets/monokai-extended.theme.bi
 const LIGHT_THEME: &[u8] = include_bytes!("../../assets/monokai-extended-light.theme.bin");
 
 const CONFIG_FILE_NAME: &str = "config.yaml";
+const AGENT_GRAPH_FILE_NAME: &str = "graph.yaml";
 const ROLES_DIR_NAME: &str = "roles";
 const MACROS_DIR_NAME: &str = "macros";
 const ENV_FILE_NAME: &str = ".env";
@@ -85,6 +86,26 @@ const GLOBAL_TOOLS_DIR_NAME: &str = "tools";
 const GLOBAL_TOOLS_UTILS_DIR_NAME: &str = "utils";
 const BASH_PROMPT_UTILS_FILE_NAME: &str = "prompt-utils.sh";
 const MCP_FILE_NAME: &str = "mcp.json";
+const DEFAULT_VISIBLE_TOOLS: [&str; 18] = [
+    "execute_command.sh",
+    "execute_py_code.py",
+    "execute_sql_code.sh",
+    "fetch_url_via_curl.sh",
+    "fs_cat.sh",
+    "fs_glob.sh",
+    "fs_grep.sh",
+    "fs_ls.sh",
+    "fs_mkdir.sh",
+    "fs_patch.sh",
+    "fs_read.sh",
+    "fs_rm.sh",
+    "fs_write.sh",
+    "get_current_time.sh",
+    "get_current_weather.sh",
+    "search_wikipedia.sh",
+    "search_arxiv.sh",
+    "web_search_loki.sh",
+];
 
 const CLIENTS_FIELD: &str = "clients";
 
@@ -95,30 +116,6 @@ const SUMMARIZATION_PROMPT: &str =
     "Summarize the discussion briefly in 200 words or less to use as a prompt for future context.";
 const SUMMARY_CONTEXT_PROMPT: &str = "This is a summary of the chat history as a recap: ";
 
-const RAG_TEMPLATE: &str = r#"Answer the query based on the context while respecting the rules. (user query, some textual context and rules, all inside xml tags)
-
-<context>
-__CONTEXT__
-</context>
-
-<sources>
-__SOURCES__
-</sources>
-
-<rules>
-- If you don't know, just say so.
-- If you are not sure, ask for clarification.
-- Answer in the same language as the user query.
-- If the context appears unreadable or of poor quality, tell the user then answer as best as you can.
-- If the answer is not in the context but you think you know the answer, explain that to the user then answer with your own knowledge.
-- Answer directly and without using xml tags.
-- When using information from the context, cite the relevant source from the <sources> section.
-</rules>
-
-<user_query>
-__INPUT__
-</user_query>"#;
-
 const LEFT_PROMPT: &str = "{color.red}{model}){color.green}{?session {?agent {agent}>}{session}{?role /}}{!session {?agent {agent}>}}{role}{?rag @{rag}}{color.cyan}{?session )}{!session >}{color.reset} ";
 const RIGHT_PROMPT: &str = "{color.purple}{?session {?consume_tokens {consume_tokens}({consume_percent}%)}{!consume_tokens {consume_tokens}}}{color.reset}";
 
@@ -140,7 +137,7 @@ pub struct Config {
     pub editor: Option<String>,
     pub wrap: Option<String>,
     pub wrap_code: bool,
-    vault_password_file: Option<PathBuf>,
+    pub(super) vault_password_file: Option<PathBuf>,
 
     pub function_calling_support: bool,
     pub mapping_tools: IndexMap<String, String>,
@@ -151,6 +148,11 @@ pub struct Config {
     pub mapping_mcp_servers: IndexMap<String, String>,
     pub enabled_mcp_servers: Option<String>,
 
+    pub auto_continue: bool,
+    pub max_auto_continues: usize,
+    pub inject_todo_instructions: bool,
+    pub continuation_prompt: Option<String>,
+
     pub repl_prelude: Option<String>,
     pub cmd_prelude: Option<String>,
     pub agent_session: Option<String>,
@@ -180,50 +182,6 @@ pub struct Config {
     pub sync_models_url: Option<String>,
 
     pub clients: Vec<ClientConfig>,
-
-    #[serde(skip)]
-    pub vault: GlobalVault,
-
-    #[serde(skip)]
-    pub macro_flag: bool,
-    #[serde(skip)]
-    pub info_flag: bool,
-    #[serde(skip)]
-    pub agent_variables: Option<AgentVariables>,
-
-    #[serde(skip)]
-    pub model: Model,
-    #[serde(skip)]
-    pub functions: Functions,
-    #[serde(skip)]
-    pub mcp_registry: Option<McpRegistry>,
-    #[serde(skip)]
-    pub working_mode: WorkingMode,
-    #[serde(skip)]
-    pub last_message: Option<LastMessage>,
-
-    #[serde(skip)]
-    pub role: Option<Role>,
-    #[serde(skip)]
-    pub session: Option<Session>,
-    #[serde(skip)]
-    pub rag: Option<Arc<Rag>>,
-    #[serde(skip)]
-    pub agent: Option<Agent>,
-    #[serde(skip)]
-    pub(crate) tool_call_tracker: Option<ToolCallTracker>,
-    #[serde(skip)]
-    pub supervisor: Option<Arc<RwLock<Supervisor>>>,
-    #[serde(skip)]
-    pub parent_supervisor: Option<Arc<RwLock<Supervisor>>>,
-    #[serde(skip)]
-    pub self_agent_id: Option<String>,
-    #[serde(skip)]
-    pub current_depth: usize,
-    #[serde(skip)]
-    pub inbox: Option<Arc<Inbox>>,
-    #[serde(skip)]
-    pub root_escalation_queue: Option<Arc<EscalationQueue>>,
 }
 
 impl Default for Config {
@@ -251,6 +209,11 @@ impl Default for Config {
             mapping_mcp_servers: Default::default(),
             enabled_mcp_servers: None,
 
+            auto_continue: false,
+            max_auto_continues: 10,
+            inject_todo_instructions: true,
+            continuation_prompt: None,
+
             repl_prelude: None,
             cmd_prelude: None,
             agent_session: None,
@@ -279,58 +242,151 @@ impl Default for Config {
             sync_models_url: None,
 
             clients: vec![],
-
-            vault: Default::default(),
-
-            macro_flag: false,
-            info_flag: false,
-            agent_variables: None,
-
-            model: Default::default(),
-            functions: Default::default(),
-            mcp_registry: Default::default(),
-            working_mode: WorkingMode::Cmd,
-            last_message: None,
-
-            role: None,
-            session: None,
-            rag: None,
-            agent: None,
-            tool_call_tracker: Some(ToolCallTracker::default()),
-            supervisor: None,
-            parent_supervisor: None,
-            self_agent_id: None,
-            current_depth: 0,
-            inbox: None,
-            root_escalation_queue: None,
         }
     }
 }
 
-pub type GlobalConfig = Arc<RwLock<Config>>;
+pub fn install_builtins() -> Result<()> {
+    Functions::install_builtin_global_tools(false)?;
+    Agent::install_builtin_agents(false)?;
+    Macro::install_macros(false)?;
+    Ok(())
+}
 
-impl Config {
-    pub fn init_bare() -> Result<Self> {
-        let h = Handle::current();
-        tokio::task::block_in_place(|| {
-            h.block_on(Self::init(
-                WorkingMode::Cmd,
-                true,
-                false,
-                None,
-                create_abort_signal(),
-            ))
-        })
+#[derive(Debug, Clone, Copy, PartialEq, Eq, clap::ValueEnum)]
+pub enum AssetCategory {
+    Agents,
+    Macros,
+    Functions,
+    #[value(name = "mcp_config")]
+    McpConfig,
+}
+
+impl AssetCategory {
+    pub const NAMES: [&'static str; 4] = ["agents", "macros", "functions", "mcp_config"];
+
+    pub fn parse(name: &str) -> Option<Self> {
+        match name {
+            "agents" => Some(Self::Agents),
+            "macros" => Some(Self::Macros),
+            "functions" => Some(Self::Functions),
+            "mcp_config" => Some(Self::McpConfig),
+            _ => None,
+        }
+    }
+}
+
+#[derive(Debug, Clone, Copy, PartialEq, Eq, clap::ValueEnum)]
+pub enum InstallFilter {
+    Agents,
+    Roles,
+    Macros,
+    Functions,
+    #[value(name = "mcp_config")]
+    McpConfig,
+}
+
+impl InstallFilter {
+    pub const NAMES: [&'static str; 5] = ["agents", "roles", "macros", "functions", "mcp_config"];
+
+    pub fn parse(name: &str) -> Option<Self> {
+        match name {
+            "agents" => Some(Self::Agents),
+            "roles" => Some(Self::Roles),
+            "macros" => Some(Self::Macros),
+            "functions" => Some(Self::Functions),
+            "mcp_config" => Some(Self::McpConfig),
+            _ => None,
+        }
+    }
+}
+
+pub fn install_assets(category: AssetCategory) -> Result<()> {
+    let (label, target) = match category {
+        AssetCategory::Agents => ("agents", paths::agents_data_dir()),
+        AssetCategory::Macros => ("macros", paths::macros_dir()),
+        AssetCategory::Functions => ("functions", paths::functions_dir()),
+        AssetCategory::McpConfig => ("MCP config", paths::mcp_config_file()),
+    };
+
+    if !confirm_asset_overwrite(category, label, &target)? {
+        println!("Aborted. No files were changed.");
+        return Ok(());
     }
 
-    pub async fn init(
-        working_mode: WorkingMode,
-        info_flag: bool,
-        start_mcp_servers: bool,
-        log_path: Option<PathBuf>,
-        abort_signal: AbortSignal,
-    ) -> Result<Self> {
-        let config_path = Self::config_file();
+    match category {
+        AssetCategory::Agents => Agent::install_builtin_agents(true)?,
+        AssetCategory::Macros => Macro::install_macros(true)?,
+        AssetCategory::Functions => Functions::install_builtin_global_tools(true)?,
+        AssetCategory::McpConfig => Functions::install_mcp_config()?,
+    }
+
+    println!("Reinstalled bundled {label} ({})", target.display());
+
+    Ok(())
+}
+
+fn confirm_asset_overwrite(category: AssetCategory, label: &str, target: &Path) -> Result<bool> {
+    if !*IS_STDOUT_TERMINAL {
+        return Ok(true);
+    }
+    let body = match category {
+        AssetCategory::McpConfig => format!(
+            "This replaces your MCP server configuration at {} with this \
+             build's bundled template. Your configured MCP servers (and any \
+             custom secret references they contain) will be lost.",
+            target.display()
+        ),
+        _ => format!(
+            "Reinstalling bundled {label} overwrites every bundled {label} in \
+             {} with this build's packaged versions. Local changes to bundled \
+             {label} will be lost; {label} you created yourself are left \
+             untouched.",
+            target.display()
+        ),
+    };
+    let prompt = format!("{} {body}\nContinue? [y/N] ", warning_text("WARNING:"));
+    let answer = read_single_key(&['y', 'Y', 'n', 'N'], 'n', &prompt)?;
+
+    Ok(matches!(answer, 'y' | 'Y'))
+}
+
+pub fn default_sessions_dir() -> PathBuf {
+    match env::var(get_env_name("sessions_dir")) {
+        Ok(value) => PathBuf::from(value),
+        Err(_) => paths::local_path(SESSIONS_DIR_NAME),
+    }
+}
+
+pub fn list_sessions() -> Vec<String> {
+    list_file_names(default_sessions_dir(), ".yaml")
+}
+
+pub async fn sync_models(url: &str, abort_signal: AbortSignal) -> Result<()> {
+    let content = abortable_run_with_spinner(fetch(url), "Fetching models.yaml", abort_signal)
+        .await
+        .with_context(|| format!("Failed to fetch '{url}'"))?;
+    println!("✓ Fetched '{url}'");
+    let list = serde_yaml::from_str::<Vec<ProviderModels>>(&content)
+        .with_context(|| "Failed to parse models.yaml")?;
+    let models_override = ModelsOverride {
+        version: env!("CARGO_PKG_VERSION").to_string(),
+        list,
+    };
+    let models_override_data =
+        serde_yaml::to_string(&models_override).with_context(|| "Failed to serde {}")?;
+
+    let model_override_path = paths::models_override_file();
+    ensure_parent_exists(&model_override_path)?;
+    std::fs::write(&model_override_path, models_override_data)
+        .with_context(|| format!("Failed to write to '{}'", model_override_path.display()))?;
+    println!("✓ Updated '{}'", model_override_path.display());
+    Ok(())
+}
+
+impl Config {
+    pub async fn load_with_interpolation(info_flag: bool) -> Result<Self> {
+        let config_path = paths::config_file();
         let (mut config, content) = if !config_path.exists() {
             match env::var(get_env_name("provider"))
                 .ok()
@@ -348,2407 +404,39 @@ impl Config {
             Self::load_from_file(&config_path)?
         };
 
-        let setup = async |config: &mut Self| -> Result<()> {
-            let vault = Vault::init(config);
-
-            let (parsed_config, missing_secrets) = interpolate_secrets(&content, &vault);
-            if !missing_secrets.is_empty() && !info_flag {
-                debug!(
-                    "Global config references secrets that are missing from the vault: {missing_secrets:?}"
-                );
-                return Err(anyhow!(formatdoc!(
-                    "
-										Global config file references secrets that are missing from the vault: {:?}
-										Please add these secrets to the vault and try again.",
-                    missing_secrets
-                )));
-            }
-
-            if !parsed_config.is_empty() && !info_flag {
-                debug!("Global config is invalid once secrets are injected: {parsed_config}");
-                let new_config = Self::load_from_str(&parsed_config).with_context(|| {
-                    formatdoc!(
-                        "
-												Global config is invalid once secrets are injected.
-												Double check the secret values and file syntax, then try again.
-												"
-                    )
-                })?;
-                *config = new_config.clone();
-            }
-
-            config.working_mode = working_mode;
-            config.info_flag = info_flag;
-            config.vault = Arc::new(vault);
-
-            Agent::install_builtin_agents()?;
-
-            config.load_envs();
-
-            if let Some(wrap) = config.wrap.clone() {
-                config.set_wrap(&wrap)?;
-            }
-
-            config.load_functions()?;
-            config
-                .load_mcp_servers(log_path, start_mcp_servers, abort_signal)
-                .await?;
-
-            config.setup_model()?;
-            config.setup_document_loaders();
-            config.setup_user_agent();
-            Macro::install_macros()?;
-            Ok(())
+        let bootstrap_app = AppConfig {
+            vault_password_file: config.vault_password_file.clone(),
+            ..AppConfig::default()
         };
-        let ret = setup(&mut config).await;
-        if !info_flag {
-            ret?;
+        let vault = Vault::init(&bootstrap_app);
+        let (parsed_config, missing_secrets) = interpolate_secrets(&content, &vault);
+        if !missing_secrets.is_empty() && !info_flag {
+            debug!(
+                "Global config references secrets that are missing from the vault: {missing_secrets:?}"
+            );
+            return Err(anyhow!(formatdoc!(
+                "
+								Global config file references secrets that are missing from the vault: {:?}
+								Please add these secrets to the vault and try again.",
+                missing_secrets
+            )));
+        }
+        if !parsed_config.is_empty() && !info_flag {
+            debug!("Global config is invalid once secrets are injected: {parsed_config}");
+            let new_config = Self::load_from_str(&parsed_config).with_context(|| {
+                formatdoc!(
+                    "
+										Global config is invalid once secrets are injected.
+										Double check the secret values and file syntax, then try again.
+										"
+                )
+            })?;
+            config = new_config;
         }
         Ok(config)
     }
 
-    pub fn config_dir() -> PathBuf {
-        if let Ok(v) = env::var(get_env_name("config_dir")) {
-            PathBuf::from(v)
-        } else if let Ok(v) = env::var("XDG_CONFIG_HOME") {
-            PathBuf::from(v).join(env!("CARGO_CRATE_NAME"))
-        } else {
-            let dir = dirs::config_dir().expect("No user's config directory");
-            dir.join(env!("CARGO_CRATE_NAME"))
-        }
-    }
-
-    pub fn local_path(name: &str) -> PathBuf {
-        Self::config_dir().join(name)
-    }
-
-    pub fn cache_path() -> PathBuf {
-        let base_dir = dirs::cache_dir().unwrap_or_else(env::temp_dir);
-
-        base_dir.join(env!("CARGO_CRATE_NAME"))
-    }
-
-    pub fn oauth_tokens_path() -> PathBuf {
-        Self::cache_path().join("oauth")
-    }
-
-    pub fn token_file(client_name: &str) -> PathBuf {
-        Self::oauth_tokens_path().join(format!("{client_name}_oauth_tokens.json"))
-    }
-
-    pub fn log_path() -> PathBuf {
-        Config::cache_path().join(format!("{}.log", env!("CARGO_CRATE_NAME")))
-    }
-
-    pub fn config_file() -> PathBuf {
-        match env::var(get_env_name("config_file")) {
-            Ok(value) => PathBuf::from(value),
-            Err(_) => Self::local_path(CONFIG_FILE_NAME),
-        }
-    }
-
-    pub fn vault_password_file(&self) -> PathBuf {
-        match &self.vault_password_file {
-            Some(path) => match path.exists() {
-                true => path.clone(),
-                false => gman::config::Config::local_provider_password_file(),
-            },
-            None => gman::config::Config::local_provider_password_file(),
-        }
-    }
-
-    pub fn roles_dir() -> PathBuf {
-        match env::var(get_env_name("roles_dir")) {
-            Ok(value) => PathBuf::from(value),
-            Err(_) => Self::local_path(ROLES_DIR_NAME),
-        }
-    }
-
-    pub fn role_file(name: &str) -> PathBuf {
-        Self::roles_dir().join(format!("{name}.md"))
-    }
-
-    pub fn macros_dir() -> PathBuf {
-        match env::var(get_env_name("macros_dir")) {
-            Ok(value) => PathBuf::from(value),
-            Err(_) => Self::local_path(MACROS_DIR_NAME),
-        }
-    }
-
-    pub fn macro_file(name: &str) -> PathBuf {
-        Self::macros_dir().join(format!("{name}.yaml"))
-    }
-
-    pub fn env_file() -> PathBuf {
-        match env::var(get_env_name("env_file")) {
-            Ok(value) => PathBuf::from(value),
-            Err(_) => Self::local_path(ENV_FILE_NAME),
-        }
-    }
-
-    pub fn messages_file(&self) -> PathBuf {
-        match &self.agent {
-            None => match env::var(get_env_name("messages_file")) {
-                Ok(value) => PathBuf::from(value),
-                Err(_) => Self::cache_path().join(MESSAGES_FILE_NAME),
-            },
-            Some(agent) => Self::cache_path()
-                .join(AGENTS_DIR_NAME)
-                .join(agent.name())
-                .join(MESSAGES_FILE_NAME),
-        }
-    }
-
-    pub fn sessions_dir(&self) -> PathBuf {
-        match &self.agent {
-            None => match env::var(get_env_name("sessions_dir")) {
-                Ok(value) => PathBuf::from(value),
-                Err(_) => Self::local_path(SESSIONS_DIR_NAME),
-            },
-            Some(agent) => Self::agent_data_dir(agent.name()).join(SESSIONS_DIR_NAME),
-        }
-    }
-
-    pub fn rags_dir() -> PathBuf {
-        match env::var(get_env_name("rags_dir")) {
-            Ok(value) => PathBuf::from(value),
-            Err(_) => Self::local_path(RAGS_DIR_NAME),
-        }
-    }
-
-    pub fn functions_dir() -> PathBuf {
-        match env::var(get_env_name("functions_dir")) {
-            Ok(value) => PathBuf::from(value),
-            Err(_) => Self::local_path(FUNCTIONS_DIR_NAME),
-        }
-    }
-
-    pub fn functions_bin_dir() -> PathBuf {
-        Self::functions_dir().join(FUNCTIONS_BIN_DIR_NAME)
-    }
-
-    pub fn mcp_config_file() -> PathBuf {
-        Self::functions_dir().join(MCP_FILE_NAME)
-    }
-
-    pub fn global_tools_dir() -> PathBuf {
-        Self::functions_dir().join(GLOBAL_TOOLS_DIR_NAME)
-    }
-
-    pub fn global_utils_dir() -> PathBuf {
-        Self::functions_dir().join(GLOBAL_TOOLS_UTILS_DIR_NAME)
-    }
-
-    pub fn bash_prompt_utils_file() -> PathBuf {
-        Self::global_utils_dir().join(BASH_PROMPT_UTILS_FILE_NAME)
-    }
-
-    pub fn session_file(&self, name: &str) -> PathBuf {
-        match name.split_once("/") {
-            Some((dir, name)) => self.sessions_dir().join(dir).join(format!("{name}.yaml")),
-            None => self.sessions_dir().join(format!("{name}.yaml")),
-        }
-    }
-
-    pub fn rag_file(&self, name: &str) -> PathBuf {
-        match &self.agent {
-            Some(agent) => Self::agent_rag_file(agent.name(), name),
-            None => Self::rags_dir().join(format!("{name}.yaml")),
-        }
-    }
-
-    pub fn agents_data_dir() -> PathBuf {
-        Self::local_path(AGENTS_DIR_NAME)
-    }
-
-    pub fn agent_data_dir(name: &str) -> PathBuf {
-        match env::var(format!("{}_DATA_DIR", normalize_env_name(name))) {
-            Ok(value) => PathBuf::from(value),
-            Err(_) => Self::agents_data_dir().join(name),
-        }
-    }
-
-    pub fn agent_config_file(name: &str) -> PathBuf {
-        match env::var(format!("{}_CONFIG_FILE", normalize_env_name(name))) {
-            Ok(value) => PathBuf::from(value),
-            Err(_) => Self::agent_data_dir(name).join(CONFIG_FILE_NAME),
-        }
-    }
-
-    pub fn agent_bin_dir(name: &str) -> PathBuf {
-        Self::agent_data_dir(name).join(FUNCTIONS_BIN_DIR_NAME)
-    }
-
-    pub fn agent_rag_file(agent_name: &str, rag_name: &str) -> PathBuf {
-        Self::agent_data_dir(agent_name).join(format!("{rag_name}.yaml"))
-    }
-
-    pub fn agent_functions_file(name: &str) -> Result<PathBuf> {
-        let allowed = ["tools.sh", "tools.py", "tools.js"];
-
-        for entry in read_dir(Self::agent_data_dir(name))? {
-            let entry = entry?;
-            if let Some(file) = entry.file_name().to_str()
-                && allowed.contains(&file)
-            {
-                return Ok(entry.path());
-            }
-        }
-
-        Err(anyhow!(
-            "No tools script found in agent functions directory"
-        ))
-    }
-
-    pub fn models_override_file() -> PathBuf {
-        Self::local_path("models-override.yaml")
-    }
-
-    pub fn state(&self) -> StateFlags {
-        let mut flags = StateFlags::empty();
-        if let Some(session) = &self.session {
-            if session.is_empty() {
-                flags |= StateFlags::SESSION_EMPTY;
-            } else {
-                flags |= StateFlags::SESSION;
-            }
-            if session.role_name().is_some() {
-                flags |= StateFlags::ROLE;
-            }
-        } else if self.role.is_some() {
-            flags |= StateFlags::ROLE;
-        }
-        if self.agent.is_some() {
-            flags |= StateFlags::AGENT;
-        }
-        if self.rag.is_some() {
-            flags |= StateFlags::RAG;
-        }
-        flags
-    }
-
-    pub fn log_config() -> Result<(LevelFilter, Option<PathBuf>)> {
-        let log_level = env::var(get_env_name("log_level"))
-            .ok()
-            .and_then(|v| v.parse().ok())
-            .unwrap_or(match cfg!(debug_assertions) {
-                true => LevelFilter::Debug,
-                false => LevelFilter::Info,
-            });
-        let log_path = match env::var(get_env_name("log_path")) {
-            Ok(v) => Some(PathBuf::from(v)),
-            Err(_) => Some(Config::log_path()),
-        };
-        Ok((log_level, log_path))
-    }
-
-    pub fn edit_config(&self) -> Result<()> {
-        let config_path = Self::config_file();
-        let editor = self.editor()?;
-        edit_file(&editor, &config_path)?;
-        println!(
-            "NOTE: Remember to restart {} if there are changes made to '{}'",
-            env!("CARGO_CRATE_NAME"),
-            config_path.display(),
-        );
-        Ok(())
-    }
-
-    pub fn current_model(&self) -> &Model {
-        if let Some(session) = self.session.as_ref() {
-            session.model()
-        } else if let Some(agent) = self.agent.as_ref() {
-            agent.model()
-        } else if let Some(role) = self.role.as_ref() {
-            role.model()
-        } else {
-            &self.model
-        }
-    }
-
-    pub fn role_like_mut(&mut self) -> Option<&mut dyn RoleLike> {
-        if let Some(session) = self.session.as_mut() {
-            Some(session)
-        } else if let Some(agent) = self.agent.as_mut() {
-            Some(agent)
-        } else if let Some(role) = self.role.as_mut() {
-            Some(role)
-        } else {
-            None
-        }
-    }
-
-    pub fn extract_role(&self) -> Role {
-        if let Some(session) = self.session.as_ref() {
-            session.to_role()
-        } else if let Some(agent) = self.agent.as_ref() {
-            agent.to_role()
-        } else if let Some(role) = self.role.as_ref() {
-            role.clone()
-        } else {
-            let mut role = Role::default();
-            role.batch_set(
-                &self.model,
-                self.temperature,
-                self.top_p,
-                self.enabled_tools.clone(),
-                self.enabled_mcp_servers.clone(),
-            );
-            role
-        }
-    }
-
-    pub fn info(&self) -> Result<String> {
-        if let Some(agent) = &self.agent {
-            let output = agent.export()?;
-            if let Some(session) = &self.session {
-                let session = session
-                    .export()?
-                    .split('\n')
-                    .map(|v| format!("  {v}"))
-                    .collect::<Vec<_>>()
-                    .join("\n");
-                Ok(format!("{output}session:\n{session}"))
-            } else {
-                Ok(output)
-            }
-        } else if let Some(session) = &self.session {
-            session.export()
-        } else if let Some(role) = &self.role {
-            Ok(role.export())
-        } else if let Some(rag) = &self.rag {
-            rag.export()
-        } else {
-            self.sysinfo()
-        }
-    }
-
-    pub fn sysinfo(&self) -> Result<String> {
-        let display_path = |path: &Path| path.display().to_string();
-        let wrap = self
-            .wrap
-            .clone()
-            .map_or_else(|| String::from("no"), |v| v.to_string());
-        let (rag_reranker_model, rag_top_k) = match &self.rag {
-            Some(rag) => rag.get_config(),
-            None => (self.rag_reranker_model.clone(), self.rag_top_k),
-        };
-        let role = self.extract_role();
-        let mut items = vec![
-            ("model", role.model().id()),
-            ("temperature", format_option_value(&role.temperature())),
-            ("top_p", format_option_value(&role.top_p())),
-            ("enabled_tools", format_option_value(&role.enabled_tools())),
-            (
-                "enabled_mcp_servers",
-                format_option_value(&role.enabled_mcp_servers()),
-            ),
-            (
-                "max_output_tokens",
-                role.model()
-                    .max_tokens_param()
-                    .map(|v| format!("{v} (current model)"))
-                    .unwrap_or_else(|| "null".into()),
-            ),
-            ("save_session", format_option_value(&self.save_session)),
-            (
-                "compression_threshold",
-                self.compression_threshold.to_string(),
-            ),
-            (
-                "rag_reranker_model",
-                format_option_value(&rag_reranker_model),
-            ),
-            ("rag_top_k", rag_top_k.to_string()),
-            ("dry_run", self.dry_run.to_string()),
-            (
-                "function_calling_support",
-                self.function_calling_support.to_string(),
-            ),
-            ("mcp_server_support", self.mcp_server_support.to_string()),
-            ("stream", self.stream.to_string()),
-            ("save", self.save.to_string()),
-            ("keybindings", self.keybindings.clone()),
-            ("wrap", wrap),
-            ("wrap_code", self.wrap_code.to_string()),
-            ("highlight", self.highlight.to_string()),
-            ("theme", format_option_value(&self.theme)),
-            ("config_file", display_path(&Self::config_file())),
-            ("env_file", display_path(&Self::env_file())),
-            ("agents_dir", display_path(&Self::agents_data_dir())),
-            ("roles_dir", display_path(&Self::roles_dir())),
-            ("sessions_dir", display_path(&self.sessions_dir())),
-            ("rags_dir", display_path(&Self::rags_dir())),
-            ("macros_dir", display_path(&Self::macros_dir())),
-            ("functions_dir", display_path(&Self::functions_dir())),
-            ("messages_file", display_path(&self.messages_file())),
-            (
-                "vault_password_file",
-                display_path(&self.vault_password_file()),
-            ),
-        ];
-        if let Ok((_, Some(log_path))) = Self::log_config() {
-            items.push(("log_path", display_path(&log_path)));
-        }
-        let output = items
-            .iter()
-            .map(|(name, value)| format!("{name:<30}{value}\n"))
-            .collect::<Vec<String>>()
-            .join("");
-        Ok(output)
-    }
-
-    pub async fn update(
-        config: &GlobalConfig,
-        data: &str,
-        abort_signal: AbortSignal,
-    ) -> Result<()> {
-        let parts: Vec<&str> = data.split_whitespace().collect();
-        if parts.len() != 2 {
-            bail!("Usage: .set <key> <value>. If value is null, unset key.");
-        }
-        let key = parts[0];
-        let value = parts[1];
-        match key {
-            "temperature" => {
-                let value = parse_value(value)?;
-                config.write().set_temperature(value);
-            }
-            "top_p" => {
-                let value = parse_value(value)?;
-                config.write().set_top_p(value);
-            }
-            "enabled_tools" => {
-                let value = parse_value(value)?;
-                config.write().set_enabled_tools(value);
-            }
-            "enabled_mcp_servers" => {
-                let value: Option<String> = parse_value(value)?;
-                if let Some(servers) = value.as_ref()
-                    && let Some(registry) = &config.read().mcp_registry
-                {
-                    if registry.list_configured_servers().is_empty() {
-                        bail!(
-                            "No MCP servers are configured. Please configure MCP servers first before setting 'enabled_mcp_servers'."
-                        );
-                    }
-
-                    if !servers.split(',').all(|s| {
-                        registry
-                            .list_configured_servers()
-                            .contains(&s.trim().to_string())
-                            || s == "all"
-                    }) {
-                        bail!(
-                            "Some of the specified MCP servers in 'enabled_mcp_servers' are not fully configured. Please check your MCP server configuration."
-                        );
-                    }
-                }
-                config.write().set_enabled_mcp_servers(value.clone());
-                if config.read().mcp_server_support {
-                    config.write().functions.clear_mcp_meta_functions();
-                    let registry = config
-                        .write()
-                        .mcp_registry
-                        .take()
-                        .expect("MCP registry should be initialized");
-                    let new_mcp_registry =
-                        McpRegistry::reinit(registry, value, abort_signal.clone()).await?;
-
-                    if !new_mcp_registry.is_empty() {
-                        config
-                            .write()
-                            .functions
-                            .append_mcp_meta_functions(new_mcp_registry.list_started_servers());
-                    }
-
-                    config.write().mcp_registry = Some(new_mcp_registry);
-                }
-            }
-            "max_output_tokens" => {
-                let value = parse_value(value)?;
-                config.write().set_max_output_tokens(value);
-            }
-            "save_session" => {
-                let value = parse_value(value)?;
-                config.write().set_save_session(value);
-            }
-            "compression_threshold" => {
-                let value = parse_value(value)?;
-                config.write().set_compression_threshold(value);
-            }
-            "rag_reranker_model" => {
-                let value = parse_value(value)?;
-                Self::set_rag_reranker_model(config, value)?;
-            }
-            "rag_top_k" => {
-                let value = value.parse().with_context(|| "Invalid value")?;
-                Self::set_rag_top_k(config, value)?;
-            }
-            "dry_run" => {
-                let value = value.parse().with_context(|| "Invalid value")?;
-                config.write().dry_run = value;
-            }
-            "function_calling_support" => {
-                let value = value.parse().with_context(|| "Invalid value")?;
-                if value && config.write().functions.is_empty() {
-                    bail!("Function calling cannot be enabled because no functions are installed.")
-                }
-                config.write().function_calling_support = value;
-            }
-            "mcp_server_support" => {
-                let value = value.parse().with_context(|| "Invalid value")?;
-                config.write().functions.clear_mcp_meta_functions();
-
-                let registry = config
-                    .write()
-                    .mcp_registry
-                    .take()
-                    .expect("MCP registry should be initialized");
-                let enabled_mcp_servers = if value {
-                    config.read().enabled_mcp_servers.clone()
-                } else {
-                    None
-                };
-                let new_registry =
-                    McpRegistry::reinit(registry, enabled_mcp_servers, abort_signal.clone())
-                        .await?;
-                if !new_registry.is_empty() && value {
-                    config
-                        .write()
-                        .functions
-                        .append_mcp_meta_functions(new_registry.list_started_servers());
-                }
-                config.write().mcp_registry = Some(new_registry);
-                config.write().mcp_server_support = value;
-            }
-            "stream" => {
-                let value = value.parse().with_context(|| "Invalid value")?;
-                config.write().stream = value;
-            }
-            "save" => {
-                let value = value.parse().with_context(|| "Invalid value")?;
-                config.write().save = value;
-            }
-            "highlight" => {
-                let value = value.parse().with_context(|| "Invalid value")?;
-                config.write().highlight = value;
-            }
-            _ => bail!("Unknown key '{key}'"),
-        }
-        Ok(())
-    }
-
-    pub fn delete(config: &GlobalConfig, kind: &str) -> Result<()> {
-        let (dir, file_ext) = match kind {
-            "role" => (Self::roles_dir(), Some(".md")),
-            "session" => (config.read().sessions_dir(), Some(".yaml")),
-            "rag" => (Self::rags_dir(), Some(".yaml")),
-            "macro" => (Self::macros_dir(), Some(".yaml")),
-            "agent-data" => (Self::agents_data_dir(), None),
-            _ => bail!("Unknown kind '{kind}'"),
-        };
-        let names = match read_dir(&dir) {
-            Ok(rd) => {
-                let mut names = vec![];
-                for entry in rd.flatten() {
-                    let name = entry.file_name();
-                    match file_ext {
-                        Some(file_ext) => {
-                            if let Some(name) = name.to_string_lossy().strip_suffix(file_ext) {
-                                names.push(name.to_string());
-                            }
-                        }
-                        None => {
-                            if entry.path().is_dir() {
-                                names.push(name.to_string_lossy().to_string());
-                            }
-                        }
-                    }
-                }
-                names.sort_unstable();
-                names
-            }
-            Err(_) => vec![],
-        };
-
-        if names.is_empty() {
-            bail!("No {kind} to delete")
-        }
-
-        let select_names = MultiSelect::new(&format!("Select {kind} to delete:"), names)
-            .with_validator(|list: &[ListOption<&String>]| {
-                if list.is_empty() {
-                    Ok(Validation::Invalid(
-                        "At least one item must be selected".into(),
-                    ))
-                } else {
-                    Ok(Validation::Valid)
-                }
-            })
-            .prompt()?;
-
-        for name in select_names {
-            match file_ext {
-                Some(ext) => {
-                    let path = dir.join(format!("{name}{ext}"));
-                    remove_file(&path).with_context(|| {
-                        format!("Failed to delete {kind} at '{}'", path.display())
-                    })?;
-                }
-                None => {
-                    let path = dir.join(name);
-                    remove_dir_all(&path).with_context(|| {
-                        format!("Failed to delete {kind} at '{}'", path.display())
-                    })?;
-                }
-            }
-        }
-        println!("✓ Successfully deleted {kind}.");
-        Ok(())
-    }
-
-    pub fn set_temperature(&mut self, value: Option<f64>) {
-        match self.role_like_mut() {
-            Some(role_like) => role_like.set_temperature(value),
-            None => self.temperature = value,
-        }
-    }
-
-    pub fn set_top_p(&mut self, value: Option<f64>) {
-        match self.role_like_mut() {
-            Some(role_like) => role_like.set_top_p(value),
-            None => self.top_p = value,
-        }
-    }
-
-    pub fn set_enabled_tools(&mut self, value: Option<String>) {
-        match self.role_like_mut() {
-            Some(role_like) => role_like.set_enabled_tools(value),
-            None => self.enabled_tools = value,
-        }
-    }
-
-    pub fn set_enabled_mcp_servers(&mut self, value: Option<String>) {
-        match self.role_like_mut() {
-            Some(role_like) => role_like.set_enabled_mcp_servers(value),
-            None => self.enabled_mcp_servers = value,
-        }
-    }
-
-    pub fn set_save_session(&mut self, value: Option<bool>) {
-        if let Some(session) = self.session.as_mut() {
-            session.set_save_session(value);
-        } else {
-            self.save_session = value;
-        }
-    }
-
-    pub fn set_compression_threshold(&mut self, value: Option<usize>) {
-        if let Some(session) = self.session.as_mut() {
-            session.set_compression_threshold(value);
-        } else {
-            self.compression_threshold = value.unwrap_or_default();
-        }
-    }
-
-    pub fn set_rag_reranker_model(config: &GlobalConfig, value: Option<String>) -> Result<()> {
-        if let Some(id) = &value {
-            Model::retrieve_model(&config.read(), id, ModelType::Reranker)?;
-        }
-        let has_rag = config.read().rag.is_some();
-        match has_rag {
-            true => update_rag(config, |rag| {
-                rag.set_reranker_model(value)?;
-                Ok(())
-            })?,
-            false => config.write().rag_reranker_model = value,
-        }
-        Ok(())
-    }
-
-    pub fn set_rag_top_k(config: &GlobalConfig, value: usize) -> Result<()> {
-        let has_rag = config.read().rag.is_some();
-        match has_rag {
-            true => update_rag(config, |rag| {
-                rag.set_top_k(value)?;
-                Ok(())
-            })?,
-            false => config.write().rag_top_k = value,
-        }
-        Ok(())
-    }
-
-    pub fn set_wrap(&mut self, value: &str) -> Result<()> {
-        if value == "no" {
-            self.wrap = None;
-        } else if value == "auto" {
-            self.wrap = Some(value.into());
-        } else {
-            value
-                .parse::<u16>()
-                .map_err(|_| anyhow!("Invalid wrap value"))?;
-            self.wrap = Some(value.into())
-        }
-        Ok(())
-    }
-
-    pub fn set_max_output_tokens(&mut self, value: Option<isize>) {
-        match self.role_like_mut() {
-            Some(role_like) => {
-                let mut model = role_like.model().clone();
-                model.set_max_tokens(value, true);
-                role_like.set_model(model);
-            }
-            None => {
-                self.model.set_max_tokens(value, true);
-            }
-        };
-    }
-
-    pub fn set_model(&mut self, model_id: &str) -> Result<()> {
-        let model = Model::retrieve_model(self, model_id, ModelType::Chat)?;
-        match self.role_like_mut() {
-            Some(role_like) => role_like.set_model(model),
-            None => {
-                self.model = model;
-            }
-        }
-        Ok(())
-    }
-
-    pub fn use_prompt(&mut self, prompt: &str) -> Result<()> {
-        let mut role = Role::new(TEMP_ROLE_NAME, prompt);
-        role.set_model(self.current_model().clone());
-        self.use_role_obj(role)
-    }
-
-    pub async fn use_role_safely(
-        config: &GlobalConfig,
-        name: &str,
-        abort_signal: AbortSignal,
-    ) -> Result<()> {
-        let mut cfg = {
-            let mut guard = config.write();
-            take(&mut *guard)
-        };
-
-        cfg.use_role(name, abort_signal.clone()).await?;
-
-        {
-            let mut guard = config.write();
-            *guard = cfg;
-        }
-
-        Ok(())
-    }
-
-    pub async fn use_role(&mut self, name: &str, abort_signal: AbortSignal) -> Result<()> {
-        let role = self.retrieve_role(name)?;
-        let mcp_servers = if self.mcp_server_support {
-            role.enabled_mcp_servers()
-        } else {
-            eprintln!(
-                "{}",
-                formatdoc!(
-                    "
-										This role uses MCP servers, but MCP support is disabled.
-										To enable it, exit the role and set 'mcp_server_support: true', then try again
-										"
-                )
-            );
-            None
-        };
-        self.functions.clear_mcp_meta_functions();
-        let registry = self
-            .mcp_registry
-            .take()
-            .with_context(|| "MCP registry should be populated")?;
-        let new_mcp_registry =
-            McpRegistry::reinit(registry, mcp_servers, abort_signal.clone()).await?;
-
-        if !new_mcp_registry.is_empty() {
-            self.functions
-                .append_mcp_meta_functions(new_mcp_registry.list_started_servers());
-        }
-
-        self.mcp_registry = Some(new_mcp_registry);
-        self.use_role_obj(role)
-    }
-
-    pub fn use_role_obj(&mut self, role: Role) -> Result<()> {
-        if self.agent.is_some() {
-            bail!("Cannot perform this operation because you are using a agent")
-        }
-        if let Some(session) = self.session.as_mut() {
-            session.guard_empty()?;
-            session.set_role(role);
-        } else {
-            self.role = Some(role);
-        }
-        Ok(())
-    }
-
-    pub fn role_info(&self) -> Result<String> {
-        if let Some(session) = &self.session {
-            if session.role_name().is_some() {
-                let role = session.to_role();
-                Ok(role.export())
-            } else {
-                bail!("No session role")
-            }
-        } else if let Some(role) = &self.role {
-            Ok(role.export())
-        } else {
-            bail!("No role")
-        }
-    }
-
-    pub fn exit_role(&mut self) -> Result<()> {
-        if let Some(session) = self.session.as_mut() {
-            session.guard_empty()?;
-            session.clear_role();
-        } else if self.role.is_some() {
-            self.role = None;
-        }
-        Ok(())
-    }
-
-    pub fn retrieve_role(&self, name: &str) -> Result<Role> {
-        let names = Self::list_roles(false);
-        let mut role = if names.contains(&name.to_string()) {
-            let path = Self::role_file(name);
-            let content = read_to_string(&path)?;
-            Role::new(name, &content)
-        } else {
-            Role::builtin(name)?
-        };
-        let current_model = self.current_model().clone();
-        match role.model_id() {
-            Some(model_id) => {
-                if current_model.id() != model_id {
-                    let model = Model::retrieve_model(self, model_id, ModelType::Chat)?;
-                    role.set_model(model);
-                } else {
-                    role.set_model(current_model);
-                }
-            }
-            None => {
-                role.set_model(current_model);
-                if role.temperature().is_none() {
-                    role.set_temperature(self.temperature);
-                }
-                if role.top_p().is_none() {
-                    role.set_top_p(self.top_p);
-                }
-            }
-        }
-        Ok(role)
-    }
-
-    pub fn new_role(&mut self, name: &str) -> Result<()> {
-        if self.macro_flag {
-            bail!("No role");
-        }
-        let ans = Confirm::new("Create a new role?")
-            .with_default(true)
-            .prompt()?;
-        if ans {
-            self.upsert_role(name)?;
-        } else {
-            bail!("No role");
-        }
-        Ok(())
-    }
-
-    pub async fn edit_role(&mut self, abort_signal: AbortSignal) -> Result<()> {
-        let role_name;
-        if let Some(session) = self.session.as_ref() {
-            if let Some(name) = session.role_name().map(|v| v.to_string()) {
-                if session.is_empty() {
-                    role_name = Some(name);
-                } else {
-                    bail!("Cannot perform this operation because you are in a non-empty session")
-                }
-            } else {
-                bail!("No role")
-            }
-        } else {
-            role_name = self.role.as_ref().map(|v| v.name().to_string());
-        }
-        let name = role_name.ok_or_else(|| anyhow!("No role"))?;
-        self.upsert_role(&name)?;
-        self.use_role(&name, abort_signal.clone()).await
-    }
-
-    pub fn upsert_role(&mut self, name: &str) -> Result<()> {
-        let role_path = Self::role_file(name);
-        ensure_parent_exists(&role_path)?;
-        let editor = self.editor()?;
-        edit_file(&editor, &role_path)?;
-        if self.working_mode.is_repl() {
-            println!("✓ Saved the role to '{}'.", role_path.display());
-        }
-        Ok(())
-    }
-
-    pub fn save_role(&mut self, name: Option<&str>) -> Result<()> {
-        let mut role_name = match &self.role {
-            Some(role) => {
-                if role.has_args() {
-                    bail!("Unable to save the role with arguments (whose name contains '#')")
-                }
-                match name {
-                    Some(v) => v.to_string(),
-                    None => role.name().to_string(),
-                }
-            }
-            None => bail!("No role"),
-        };
-        if role_name == TEMP_ROLE_NAME {
-            role_name = Text::new("Role name:")
-                .with_validator(|input: &str| {
-                    let input = input.trim();
-                    if input.is_empty() {
-                        Ok(Validation::Invalid("This name is required".into()))
-                    } else if input == TEMP_ROLE_NAME {
-                        Ok(Validation::Invalid("This name is reserved".into()))
-                    } else {
-                        Ok(Validation::Valid)
-                    }
-                })
-                .prompt()?;
-        }
-        let role_path = Self::role_file(&role_name);
-        if let Some(role) = self.role.as_mut() {
-            role.save(&role_name, &role_path, self.working_mode.is_repl())?;
-        }
-
-        Ok(())
-    }
-
-    pub fn list_roles(with_builtin: bool) -> Vec<String> {
-        let mut names = HashSet::new();
-        if let Ok(rd) = read_dir(Self::roles_dir()) {
-            for entry in rd.flatten() {
-                if let Some(name) = entry
-                    .file_name()
-                    .to_str()
-                    .and_then(|v| v.strip_suffix(".md"))
-                {
-                    names.insert(name.to_string());
-                }
-            }
-        }
-        if with_builtin {
-            names.extend(Role::list_builtin_role_names());
-        }
-        let mut names: Vec<_> = names.into_iter().collect();
-        names.sort_unstable();
-        names
-    }
-
-    pub fn has_role(name: &str) -> bool {
-        let names = Self::list_roles(true);
-        names.contains(&name.to_string())
-    }
-
-    pub async fn use_session_safely(
-        config: &GlobalConfig,
-        session_name: Option<&str>,
-        abort_signal: AbortSignal,
-    ) -> Result<()> {
-        let mut cfg = {
-            let mut guard = config.write();
-            take(&mut *guard)
-        };
-
-        cfg.use_session(session_name, abort_signal.clone()).await?;
-
-        {
-            let mut guard = config.write();
-            *guard = cfg;
-        }
-
-        Ok(())
-    }
-
-    pub async fn use_session(
-        &mut self,
-        session_name: Option<&str>,
-        abort_signal: AbortSignal,
-    ) -> Result<()> {
-        if self.session.is_some() {
-            bail!(
-                "Already in a session, please run '.exit session' first to exit the current session."
-            );
-        }
-        let mut session;
-        match session_name {
-            None | Some(TEMP_SESSION_NAME) => {
-                let session_file = self.session_file(TEMP_SESSION_NAME);
-                if session_file.exists() {
-                    remove_file(session_file).with_context(|| {
-                        format!("Failed to cleanup previous '{TEMP_SESSION_NAME}' session")
-                    })?;
-                }
-                session = Some(Session::new(self, TEMP_SESSION_NAME));
-            }
-            Some(name) => {
-                let session_path = self.session_file(name);
-                if !session_path.exists() {
-                    session = Some(Session::new(self, name));
-                } else {
-                    session = Some(Session::load(self, name, &session_path)?);
-                }
-            }
-        }
-        let mut new_session = false;
-        if let Some(session) = session.as_mut() {
-            let mcp_servers = if self.mcp_server_support {
-                session.enabled_mcp_servers()
-            } else {
-                eprintln!(
-                    "{}",
-                    formatdoc!(
-                        "
-												This session uses MCP servers, but MCP support is disabled.
-												To enable it, exit the session and set 'mcp_server_support: true', then try again
-												"
-                    )
-                );
-                None
-            };
-            self.functions.clear_mcp_meta_functions();
-            let registry = self
-                .mcp_registry
-                .take()
-                .with_context(|| "MCP registry should be populated")?;
-            let new_mcp_registry =
-                McpRegistry::reinit(registry, mcp_servers, abort_signal.clone()).await?;
-
-            if !new_mcp_registry.is_empty() {
-                self.functions
-                    .append_mcp_meta_functions(new_mcp_registry.list_started_servers());
-            }
-
-            self.mcp_registry = Some(new_mcp_registry);
-            if session.is_empty() {
-                new_session = true;
-                if let Some(LastMessage {
-                    input,
-                    output,
-                    continuous,
-                }) = &self.last_message
-                    && (*continuous && !output.is_empty())
-                    && self.agent.is_some() == input.with_agent()
-                {
-                    let ans = Confirm::new(
-                        "Start a session that incorporates the last question and answer?",
-                    )
-                    .with_default(false)
-                    .prompt()?;
-                    if ans {
-                        session.add_message(input, output)?;
-                    }
-                }
-            }
-        }
-        self.session = session;
-        self.init_agent_session_variables(new_session)?;
-        Ok(())
-    }
-
-    pub fn session_info(&self) -> Result<String> {
-        if let Some(session) = &self.session {
-            let render_options = self.render_options()?;
-            let mut markdown_render = MarkdownRender::init(render_options)?;
-            let agent_info: Option<(String, Vec<String>)> = self.agent.as_ref().map(|agent| {
-                let functions = agent
-                    .functions()
-                    .declarations()
-                    .iter()
-                    .filter_map(|v| if v.agent { Some(v.name.clone()) } else { None })
-                    .collect();
-                (agent.name().to_string(), functions)
-            });
-            session.render(&mut markdown_render, &agent_info)
-        } else {
-            bail!("No session")
-        }
-    }
-
-    pub fn exit_session(&mut self) -> Result<()> {
-        if let Some(mut session) = self.session.take() {
-            let sessions_dir = self.sessions_dir();
-            session.exit(&sessions_dir, self.working_mode.is_repl())?;
-            self.discontinuous_last_message();
-        }
-        Ok(())
-    }
-
-    pub fn save_session(&mut self, name: Option<&str>) -> Result<()> {
-        let session_name = match &self.session {
-            Some(session) => match name {
-                Some(v) => v.to_string(),
-                None => session
-                    .autoname()
-                    .unwrap_or_else(|| session.name())
-                    .to_string(),
-            },
-            None => bail!("No session"),
-        };
-        let session_path = self.session_file(&session_name);
-        if let Some(session) = self.session.as_mut() {
-            session.save(&session_name, &session_path, self.working_mode.is_repl())?;
-        }
-        Ok(())
-    }
-
-    pub fn edit_session(&mut self) -> Result<()> {
-        let name = match &self.session {
-            Some(session) => session.name().to_string(),
-            None => bail!("No session"),
-        };
-        let session_path = self.session_file(&name);
-        self.save_session(Some(&name))?;
-        let editor = self.editor()?;
-        edit_file(&editor, &session_path).with_context(|| {
-            format!(
-                "Failed to edit '{}' with '{editor}'",
-                session_path.display()
-            )
-        })?;
-        self.session = Some(Session::load(self, &name, &session_path)?);
-        self.discontinuous_last_message();
-        Ok(())
-    }
-
-    pub fn empty_session(&mut self) -> Result<()> {
-        if let Some(session) = self.session.as_mut() {
-            if let Some(agent) = self.agent.as_ref() {
-                session.sync_agent(agent);
-            }
-            session.clear_messages();
-        } else {
-            bail!("No session")
-        }
-        self.discontinuous_last_message();
-        Ok(())
-    }
-
-    pub fn set_save_session_this_time(&mut self) -> Result<()> {
-        if let Some(session) = self.session.as_mut() {
-            session.set_save_session_this_time();
-        } else {
-            bail!("No session")
-        }
-        Ok(())
-    }
-
-    pub fn list_sessions(&self) -> Vec<String> {
-        list_file_names(self.sessions_dir(), ".yaml")
-    }
-
-    pub fn list_autoname_sessions(&self) -> Vec<String> {
-        list_file_names(self.sessions_dir().join("_"), ".yaml")
-    }
-
-    pub fn maybe_compress_session(config: GlobalConfig) {
-        let mut needs_compression = false;
-        {
-            let mut config = config.write();
-            let compression_threshold = config.compression_threshold;
-            if let Some(session) = config.session.as_mut()
-                && session.needs_compression(compression_threshold)
-            {
-                session.set_compressing(true);
-                needs_compression = true;
-            }
-        };
-        if !needs_compression {
-            return;
-        }
-        let color = if config.read().light_theme() {
-            nu_ansi_term::Color::LightGray
-        } else {
-            nu_ansi_term::Color::DarkGray
-        };
-        print!(
-            "\n📢 {}\n",
-            color.italic().paint("Compressing the session."),
-        );
-        tokio::spawn(async move {
-            if let Err(err) = Config::compress_session(&config).await {
-                warn!("Failed to compress the session: {err}");
-            }
-            if let Some(session) = config.write().session.as_mut() {
-                session.set_compressing(false);
-            }
-        });
-    }
-
-    pub async fn compress_session(config: &GlobalConfig) -> Result<()> {
-        match config.read().session.as_ref() {
-            Some(session) => {
-                if !session.has_user_messages() {
-                    bail!("No need to compress since there are no messages in the session")
-                }
-            }
-            None => bail!("No session"),
-        }
-
-        let prompt = config
-            .read()
-            .summarization_prompt
-            .clone()
-            .unwrap_or_else(|| SUMMARIZATION_PROMPT.into());
-        let input = Input::from_str(config, &prompt, None);
-        let summary = input.fetch_chat_text().await?;
-        let summary_context_prompt = config
-            .read()
-            .summary_context_prompt
-            .clone()
-            .unwrap_or_else(|| SUMMARY_CONTEXT_PROMPT.into());
-
-        let todo_prefix = config
-            .read()
-            .agent
-            .as_ref()
-            .map(|agent| agent.todo_list())
-            .filter(|todos| !todos.is_empty())
-            .map(|todos| format!("[ACTIVE TODO LIST]\n{}\n\n", todos.render_for_model()))
-            .unwrap_or_default();
-
-        if let Some(session) = config.write().session.as_mut() {
-            session.compress(format!("{todo_prefix}{summary_context_prompt}{summary}"));
-        }
-        config.write().discontinuous_last_message();
-        Ok(())
-    }
-
-    pub fn is_compressing_session(&self) -> bool {
-        self.session
-            .as_ref()
-            .map(|v| v.compressing())
-            .unwrap_or_default()
-    }
-
-    pub fn maybe_autoname_session(config: GlobalConfig) {
-        let mut need_autoname = false;
-        if let Some(session) = config.write().session.as_mut()
-            && session.need_autoname()
-        {
-            session.set_autonaming(true);
-            need_autoname = true;
-        }
-        if !need_autoname {
-            return;
-        }
-        let color = if config.read().light_theme() {
-            nu_ansi_term::Color::LightGray
-        } else {
-            nu_ansi_term::Color::DarkGray
-        };
-        print!("\n📢 {}\n", color.italic().paint("Autonaming the session."),);
-        tokio::spawn(async move {
-            if let Err(err) = Config::autoname_session(&config).await {
-                warn!("Failed to autonaming the session: {err}");
-            }
-            if let Some(session) = config.write().session.as_mut() {
-                session.set_autonaming(false);
-            }
-        });
-    }
-
-    pub async fn autoname_session(config: &GlobalConfig) -> Result<()> {
-        let text = match config
-            .read()
-            .session
-            .as_ref()
-            .and_then(|v| v.chat_history_for_autonaming())
-        {
-            Some(v) => v,
-            None => bail!("No chat history"),
-        };
-        let role = config.read().retrieve_role(CREATE_TITLE_ROLE)?;
-        let input = Input::from_str(config, &text, Some(role));
-        let text = input.fetch_chat_text().await?;
-        if let Some(session) = config.write().session.as_mut() {
-            session.set_autoname(&text);
-        }
-        Ok(())
-    }
-
-    pub async fn use_rag(
-        config: &GlobalConfig,
-        rag: Option<&str>,
-        abort_signal: AbortSignal,
-    ) -> Result<()> {
-        if config.read().agent.is_some() {
-            bail!("Cannot perform this operation because you are using a agent")
-        }
-        let rag = match rag {
-            None => {
-                let rag_path = config.read().rag_file(TEMP_RAG_NAME);
-                if rag_path.exists() {
-                    remove_file(&rag_path).with_context(|| {
-                        format!("Failed to cleanup previous '{TEMP_RAG_NAME}' rag")
-                    })?;
-                }
-                Rag::init(config, TEMP_RAG_NAME, &rag_path, &[], abort_signal).await?
-            }
-            Some(name) => {
-                let rag_path = config.read().rag_file(name);
-                if !rag_path.exists() {
-                    if config.read().working_mode.is_cmd() {
-                        bail!("Unknown RAG '{name}'")
-                    }
-                    Rag::init(config, name, &rag_path, &[], abort_signal).await?
-                } else {
-                    Rag::load(config, name, &rag_path)?
-                }
-            }
-        };
-        config.write().rag = Some(Arc::new(rag));
-        Ok(())
-    }
-
-    pub async fn edit_rag_docs(config: &GlobalConfig, abort_signal: AbortSignal) -> Result<()> {
-        let mut rag = match config.read().rag.clone() {
-            Some(v) => v.as_ref().clone(),
-            None => bail!("No RAG"),
-        };
-
-        let document_paths = rag.document_paths();
-        let temp_file = temp_file(&format!("-rag-{}", rag.name()), ".txt");
-        tokio::fs::write(&temp_file, &document_paths.join("\n"))
-            .await
-            .with_context(|| format!("Failed to write to '{}'", temp_file.display()))?;
-        let editor = config.read().editor()?;
-        edit_file(&editor, &temp_file)?;
-        let new_document_paths = tokio::fs::read_to_string(&temp_file)
-            .await
-            .with_context(|| format!("Failed to read '{}'", temp_file.display()))?;
-        let new_document_paths = new_document_paths
-            .split('\n')
-            .filter_map(|v| {
-                let v = v.trim();
-                if v.is_empty() {
-                    None
-                } else {
-                    Some(v.to_string())
-                }
-            })
-            .collect::<Vec<_>>();
-        if new_document_paths.is_empty() || new_document_paths == document_paths {
-            bail!("No changes")
-        }
-        rag.refresh_document_paths(&new_document_paths, false, config, abort_signal)
-            .await?;
-        config.write().rag = Some(Arc::new(rag));
-        Ok(())
-    }
-
-    pub async fn rebuild_rag(config: &GlobalConfig, abort_signal: AbortSignal) -> Result<()> {
-        let mut rag = match config.read().rag.clone() {
-            Some(v) => v.as_ref().clone(),
-            None => bail!("No RAG"),
-        };
-        let document_paths = rag.document_paths().to_vec();
-        rag.refresh_document_paths(&document_paths, true, config, abort_signal)
-            .await?;
-        config.write().rag = Some(Arc::new(rag));
-        Ok(())
-    }
-
-    pub fn rag_sources(config: &GlobalConfig) -> Result<String> {
-        match config.read().rag.as_ref() {
-            Some(rag) => match rag.get_last_sources() {
-                Some(v) => Ok(v),
-                None => bail!("No sources"),
-            },
-            None => bail!("No RAG"),
-        }
-    }
-
-    pub fn rag_info(&self) -> Result<String> {
-        if let Some(rag) = &self.rag {
-            rag.export()
-        } else {
-            bail!("No RAG")
-        }
-    }
-
-    pub fn exit_rag(&mut self) -> Result<()> {
-        self.rag.take();
-        Ok(())
-    }
-
-    pub async fn search_rag(
-        config: &GlobalConfig,
-        rag: &Rag,
-        text: &str,
-        abort_signal: AbortSignal,
-    ) -> Result<String> {
-        let (reranker_model, top_k) = rag.get_config();
-        let (embeddings, sources, ids) = rag
-            .search(text, top_k, reranker_model.as_deref(), abort_signal)
-            .await?;
-        let text = config.read().rag_template(&embeddings, &sources, text);
-        rag.set_last_sources(&ids);
-        Ok(text)
-    }
-
-    pub fn list_rags() -> Vec<String> {
-        match read_dir(Self::rags_dir()) {
-            Ok(rd) => {
-                let mut names = vec![];
-                for entry in rd.flatten() {
-                    let name = entry.file_name();
-                    if let Some(name) = name.to_string_lossy().strip_suffix(".yaml") {
-                        names.push(name.to_string());
-                    }
-                }
-                names.sort_unstable();
-                names
-            }
-            Err(_) => vec![],
-        }
-    }
-
-    pub fn rag_template(&self, embeddings: &str, sources: &str, text: &str) -> String {
-        if embeddings.is_empty() {
-            return text.to_string();
-        }
-        self.rag_template
-            .as_deref()
-            .unwrap_or(RAG_TEMPLATE)
-            .replace("__CONTEXT__", embeddings)
-            .replace("__SOURCES__", sources)
-            .replace("__INPUT__", text)
-    }
-
-    pub async fn use_agent(
-        config: &GlobalConfig,
-        agent_name: &str,
-        session_name: Option<&str>,
-        abort_signal: AbortSignal,
-    ) -> Result<()> {
-        if !config.read().function_calling_support {
-            bail!("Please enable function calling support before using the agent.");
-        }
-        if config.read().agent.is_some() {
-            bail!("Already in an agent, please run '.exit agent' first to exit the current agent.");
-        }
-        let agent = Agent::init(config, agent_name, abort_signal.clone()).await?;
-        if !agent.model().supports_function_calling() {
-            eprintln!(
-                "Warning: The model '{}' does not support function calling. Agent tools (including todo, spawning, and user interaction) will not be available.",
-                agent.model().id()
-            );
-        }
-        let session = session_name.map(|v| v.to_string()).or_else(|| {
-            if config.read().macro_flag {
-                None
-            } else {
-                agent.agent_session().map(|v| v.to_string())
-            }
-        });
-        let should_init_supervisor = agent.can_spawn_agents();
-        let max_concurrent = agent.max_concurrent_agents();
-        let max_depth = agent.max_agent_depth();
-        config.write().rag = agent.rag();
-        config.write().agent = Some(agent);
-        if should_init_supervisor {
-            config.write().supervisor = Some(Arc::new(RwLock::new(Supervisor::new(
-                max_concurrent,
-                max_depth,
-            ))));
-        }
-        if let Some(session) = session {
-            Config::use_session_safely(config, Some(&session), abort_signal).await?;
-        } else {
-            config.write().init_agent_shared_variables()?;
-        }
-        Ok(())
-    }
-
-    pub fn agent_info(&self) -> Result<String> {
-        if let Some(agent) = &self.agent {
-            agent.export()
-        } else {
-            bail!("No agent")
-        }
-    }
-
-    pub fn agent_banner(&self) -> Result<String> {
-        if let Some(agent) = &self.agent {
-            Ok(agent.banner())
-        } else {
-            bail!("No agent")
-        }
-    }
-
-    pub fn edit_agent_config(&self) -> Result<()> {
-        let agent_name = match &self.agent {
-            Some(agent) => agent.name(),
-            None => bail!("No agent"),
-        };
-        let agent_config_path = Config::agent_config_file(agent_name);
-        ensure_parent_exists(&agent_config_path)?;
-        if !agent_config_path.exists() {
-            std::fs::write(
-                &agent_config_path,
-                "# see https://github.com/Dark-Alex-17/loki/blob/main/config.agent.example.yaml\n",
-            )
-            .with_context(|| format!("Failed to write to '{}'", agent_config_path.display()))?;
-        }
-        let editor = self.editor()?;
-        edit_file(&editor, &agent_config_path)?;
-        println!(
-            "NOTE: Remember to reload the agent if there are changes made to '{}'",
-            agent_config_path.display()
-        );
-        Ok(())
-    }
-
-    pub fn exit_agent(&mut self) -> Result<()> {
-        self.exit_session()?;
-        self.load_functions()?;
-        if self.agent.take().is_some() {
-            if let Some(ref supervisor) = self.supervisor {
-                supervisor.read().cancel_all();
-            }
-            self.supervisor.take();
-            self.rag.take();
-            self.discontinuous_last_message();
-        }
-        Ok(())
-    }
-
-    pub fn exit_agent_session(&mut self) -> Result<()> {
-        self.exit_session()?;
-        if let Some(agent) = self.agent.as_mut() {
-            agent.exit_session();
-            if self.working_mode.is_repl() {
-                self.init_agent_shared_variables()?;
-            }
-        }
-        Ok(())
-    }
-
-    pub fn list_macros() -> Vec<String> {
-        list_file_names(Self::macros_dir(), ".yaml")
-    }
-
-    pub fn load_macro(name: &str) -> Result<Macro> {
-        let path = Self::macro_file(name);
-        let err = || format!("Failed to load macro '{name}' at '{}'", path.display());
-        let content = read_to_string(&path).with_context(err)?;
-        let value: Macro = serde_yaml::from_str(&content).with_context(err)?;
-        Ok(value)
-    }
-
-    pub fn has_macro(name: &str) -> bool {
-        let names = Self::list_macros();
-        names.contains(&name.to_string())
-    }
-
-    pub fn new_macro(&mut self, name: &str) -> Result<()> {
-        if self.macro_flag {
-            bail!("No macro");
-        }
-        let ans = Confirm::new("Create a new macro?")
-            .with_default(true)
-            .prompt()?;
-        if ans {
-            let macro_path = Self::macro_file(name);
-            ensure_parent_exists(&macro_path)?;
-            let editor = self.editor()?;
-            edit_file(&editor, &macro_path)?;
-        } else {
-            bail!("No macro");
-        }
-        Ok(())
-    }
-
-    pub async fn apply_prelude(&mut self, abort_signal: AbortSignal) -> Result<()> {
-        if self.macro_flag || !self.state().is_empty() {
-            return Ok(());
-        }
-        let prelude = match self.working_mode {
-            WorkingMode::Repl => self.repl_prelude.as_ref(),
-            WorkingMode::Cmd => self.cmd_prelude.as_ref(),
-        };
-        let prelude = match prelude {
-            Some(v) => {
-                if v.is_empty() {
-                    return Ok(());
-                }
-                v.to_string()
-            }
-            None => return Ok(()),
-        };
-
-        let err_msg = || format!("Invalid prelude '{prelude}");
-        match prelude.split_once(':') {
-            Some(("role", name)) => {
-                self.use_role(name, abort_signal)
-                    .await
-                    .with_context(err_msg)?;
-            }
-            Some(("session", name)) => {
-                self.use_session(Some(name), abort_signal)
-                    .await
-                    .with_context(err_msg)?;
-            }
-            Some((session_name, role_name)) => {
-                self.use_session(Some(session_name), abort_signal.clone())
-                    .await
-                    .with_context(err_msg)?;
-                if let Some(true) = self.session.as_ref().map(|v| v.is_empty()) {
-                    self.use_role(role_name, abort_signal)
-                        .await
-                        .with_context(err_msg)?;
-                }
-            }
-            _ => {
-                bail!("{}", err_msg())
-            }
-        }
-        Ok(())
-    }
-
-    pub fn select_functions(&self, role: &Role) -> Option<Vec<FunctionDeclaration>> {
-        let mut functions = vec![];
-        functions.extend(self.select_enabled_functions(role));
-        functions.extend(self.select_enabled_mcp_servers(role));
-
-        if functions.is_empty() {
-            None
-        } else {
-            Some(functions)
-        }
-    }
-
-    fn select_enabled_functions(&self, role: &Role) -> Vec<FunctionDeclaration> {
-        let mut functions = vec![];
-        if self.function_calling_support {
-            if let Some(enabled_tools) = role.enabled_tools() {
-                let mut tool_names: HashSet<String> = Default::default();
-                let declaration_names: HashSet<String> = self
-                    .functions
-                    .declarations()
-                    .iter()
-                    .filter(|v| {
-                        !v.name.starts_with(MCP_INVOKE_META_FUNCTION_NAME_PREFIX)
-                            && !v.name.starts_with(MCP_SEARCH_META_FUNCTION_NAME_PREFIX)
-                            && !v.name.starts_with(MCP_DESCRIBE_META_FUNCTION_NAME_PREFIX)
-                    })
-                    .map(|v| v.name.to_string())
-                    .collect();
-                if enabled_tools == "all" {
-                    tool_names.extend(declaration_names);
-                } else {
-                    for item in enabled_tools.split(',') {
-                        let item = item.trim();
-                        if let Some(values) = self.mapping_tools.get(item) {
-                            tool_names.extend(
-                                values
-                                    .split(',')
-                                    .map(|v| v.to_string())
-                                    .filter(|v| declaration_names.contains(v)),
-                            )
-                        } else if declaration_names.contains(item) {
-                            tool_names.insert(item.to_string());
-                        }
-                    }
-                }
-                functions = self
-                    .functions
-                    .declarations()
-                    .iter()
-                    .filter_map(|v| {
-                        if tool_names.contains(&v.name) {
-                            Some(v.clone())
-                        } else {
-                            None
-                        }
-                    })
-                    .collect();
-            }
-
-            if self.agent.is_none() {
-                let existing: HashSet<String> = functions.iter().map(|f| f.name.clone()).collect();
-                let builtin_functions: Vec<FunctionDeclaration> = self
-                    .functions
-                    .declarations()
-                    .iter()
-                    .filter(|v| {
-                        v.name.starts_with(USER_FUNCTION_PREFIX) && !existing.contains(&v.name)
-                    })
-                    .cloned()
-                    .collect();
-                functions.extend(builtin_functions);
-            }
-
-            if let Some(agent) = &self.agent {
-                let mut agent_functions: Vec<FunctionDeclaration> = agent
-                    .functions()
-                    .declarations()
-                    .to_vec()
-                    .into_iter()
-                    .filter(|v| {
-                        !v.name.starts_with(MCP_INVOKE_META_FUNCTION_NAME_PREFIX)
-                            && !v.name.starts_with(MCP_SEARCH_META_FUNCTION_NAME_PREFIX)
-                            && !v.name.starts_with(MCP_DESCRIBE_META_FUNCTION_NAME_PREFIX)
-                    })
-                    .collect();
-                let tool_names: HashSet<String> = agent_functions
-                    .iter()
-                    .filter_map(|v| {
-                        if v.agent {
-                            None
-                        } else {
-                            Some(v.name.to_string())
-                        }
-                    })
-                    .collect();
-                agent_functions.extend(
-                    functions
-                        .into_iter()
-                        .filter(|v| !tool_names.contains(&v.name)),
-                );
-                functions = agent_functions;
-            }
-        }
-
-        functions
-    }
-
-    fn select_enabled_mcp_servers(&self, role: &Role) -> Vec<FunctionDeclaration> {
-        let mut mcp_functions = vec![];
-        if self.mcp_server_support {
-            if let Some(enabled_mcp_servers) = role.enabled_mcp_servers() {
-                let mut server_names: HashSet<String> = Default::default();
-                let mcp_declaration_names: HashSet<String> = self
-                    .functions
-                    .declarations()
-                    .iter()
-                    .filter(|v| {
-                        v.name.starts_with(MCP_INVOKE_META_FUNCTION_NAME_PREFIX)
-                            || v.name.starts_with(MCP_SEARCH_META_FUNCTION_NAME_PREFIX)
-                            || v.name.starts_with(MCP_DESCRIBE_META_FUNCTION_NAME_PREFIX)
-                    })
-                    .map(|v| v.name.to_string())
-                    .collect();
-                if enabled_mcp_servers == "all" {
-                    server_names.extend(mcp_declaration_names);
-                } else {
-                    for item in enabled_mcp_servers.split(',') {
-                        let item = item.trim();
-                        let item_invoke_name =
-                            format!("{}_{item}", MCP_INVOKE_META_FUNCTION_NAME_PREFIX);
-                        let item_search_name =
-                            format!("{}_{item}", MCP_SEARCH_META_FUNCTION_NAME_PREFIX);
-                        let item_describe_name =
-                            format!("{}_{item}", MCP_DESCRIBE_META_FUNCTION_NAME_PREFIX);
-                        if let Some(values) = self.mapping_mcp_servers.get(item) {
-                            server_names.extend(
-                                values
-                                    .split(',')
-                                    .flat_map(|v| {
-                                        vec![
-                                            format!(
-                                                "{}_{}",
-                                                MCP_INVOKE_META_FUNCTION_NAME_PREFIX,
-                                                v.to_string()
-                                            ),
-                                            format!(
-                                                "{}_{}",
-                                                MCP_SEARCH_META_FUNCTION_NAME_PREFIX,
-                                                v.to_string()
-                                            ),
-                                            format!(
-                                                "{}_{}",
-                                                MCP_DESCRIBE_META_FUNCTION_NAME_PREFIX,
-                                                v.to_string()
-                                            ),
-                                        ]
-                                    })
-                                    .filter(|v| mcp_declaration_names.contains(v)),
-                            )
-                        } else if mcp_declaration_names.contains(&item_invoke_name) {
-                            server_names.insert(item_invoke_name);
-                            server_names.insert(item_search_name);
-                            server_names.insert(item_describe_name);
-                        }
-                    }
-                }
-                mcp_functions = self
-                    .functions
-                    .declarations()
-                    .iter()
-                    .filter_map(|v| {
-                        if server_names.contains(&v.name) {
-                            Some(v.clone())
-                        } else {
-                            None
-                        }
-                    })
-                    .collect();
-            }
-
-            if let Some(agent) = &self.agent {
-                let mut agent_functions: Vec<FunctionDeclaration> = agent
-                    .functions()
-                    .declarations()
-                    .to_vec()
-                    .into_iter()
-                    .filter(|v| {
-                        v.name.starts_with(MCP_INVOKE_META_FUNCTION_NAME_PREFIX)
-                            || v.name.starts_with(MCP_SEARCH_META_FUNCTION_NAME_PREFIX)
-                            || v.name.starts_with(MCP_DESCRIBE_META_FUNCTION_NAME_PREFIX)
-                    })
-                    .collect();
-                let tool_names: HashSet<String> = agent_functions
-                    .iter()
-                    .filter_map(|v| {
-                        if v.agent {
-                            None
-                        } else {
-                            Some(v.name.to_string())
-                        }
-                    })
-                    .collect();
-                agent_functions.extend(
-                    mcp_functions
-                        .into_iter()
-                        .filter(|v| !tool_names.contains(&v.name)),
-                );
-                mcp_functions = agent_functions;
-            }
-        }
-
-        mcp_functions
-    }
-
-    pub fn editor(&self) -> Result<String> {
-        EDITOR.get_or_init(move || {
-			let editor = self.editor.clone()
-				.or_else(|| env::var("VISUAL").ok().or_else(|| env::var("EDITOR").ok()))
-				.unwrap_or_else(|| {
-					if cfg!(windows) {
-						"notepad".to_string()
-					} else {
-						"nano".to_string()
-					}
-				});
-			which::which(&editor).ok().map(|_| editor)
-		})
-			.clone()
-			.ok_or_else(|| anyhow!("Editor not found. Please add the `editor` configuration or set the $EDITOR or $VISUAL environment variable."))
-    }
-
-    pub fn repl_complete(
-        &self,
-        cmd: &str,
-        args: &[&str],
-        _line: &str,
-    ) -> Vec<(String, Option<String>)> {
-        let mut values: Vec<(String, Option<String>)> = vec![];
-        let filter = args.last().unwrap_or(&"");
-        if args.len() == 1 {
-            values = match cmd {
-                ".role" => map_completion_values(Self::list_roles(true)),
-                ".model" => list_models(self, ModelType::Chat)
-                    .into_iter()
-                    .map(|v| (v.id(), Some(v.description())))
-                    .collect(),
-                ".session" => {
-                    if args[0].starts_with("_/") {
-                        map_completion_values(
-                            self.list_autoname_sessions()
-                                .iter()
-                                .rev()
-                                .map(|v| format!("_/{v}"))
-                                .collect::<Vec<String>>(),
-                        )
-                    } else {
-                        map_completion_values(self.list_sessions())
-                    }
-                }
-                ".rag" => map_completion_values(Self::list_rags()),
-                ".agent" => map_completion_values(list_agents()),
-                ".macro" => map_completion_values(Self::list_macros()),
-                ".starter" => match &self.agent {
-                    Some(agent) => agent
-                        .conversation_starters()
-                        .iter()
-                        .enumerate()
-                        .map(|(i, v)| ((i + 1).to_string(), Some(v.to_string())))
-                        .collect(),
-                    None => vec![],
-                },
-                ".set" => {
-                    let mut values = vec![
-                        "temperature",
-                        "top_p",
-                        "enabled_tools",
-                        "enabled_mcp_servers",
-                        "save_session",
-                        "compression_threshold",
-                        "rag_reranker_model",
-                        "rag_top_k",
-                        "max_output_tokens",
-                        "dry_run",
-                        "function_calling_support",
-                        "mcp_server_support",
-                        "stream",
-                        "save",
-                        "highlight",
-                    ];
-                    values.sort_unstable();
-                    values
-                        .into_iter()
-                        .map(|v| (format!("{v} "), None))
-                        .collect()
-                }
-                ".delete" => {
-                    map_completion_values(vec!["role", "session", "rag", "macro", "agent-data"])
-                }
-                ".vault" => {
-                    let mut values = vec!["add", "get", "update", "delete", "list"];
-                    values.sort_unstable();
-                    values
-                        .into_iter()
-                        .map(|v| (format!("{v} "), None))
-                        .collect()
-                }
-                _ => vec![],
-            };
-        } else if cmd == ".set" && args.len() == 2 {
-            let candidates = match args[0] {
-                "max_output_tokens" => match self.current_model().max_output_tokens() {
-                    Some(v) => vec![v.to_string()],
-                    None => vec![],
-                },
-                "dry_run" => complete_bool(self.dry_run),
-                "stream" => complete_bool(self.stream),
-                "save" => complete_bool(self.save),
-                "function_calling_support" => complete_bool(self.function_calling_support),
-                "enabled_tools" => {
-                    let mut prefix = String::new();
-                    let mut ignores = HashSet::new();
-                    if let Some((v, _)) = args[1].rsplit_once(',') {
-                        ignores = v.split(',').collect();
-                        prefix = format!("{v},");
-                    }
-                    let mut values = vec![];
-                    if prefix.is_empty() {
-                        values.push("all".to_string());
-                    }
-                    values.extend(self.functions.declarations().iter().map(|v| v.name.clone()));
-                    values.extend(self.mapping_tools.keys().map(|v| v.to_string()));
-                    values
-                        .into_iter()
-                        .filter(|v| !ignores.contains(v.as_str()))
-                        .map(|v| format!("{prefix}{v}"))
-                        .collect()
-                }
-                "mcp_server_support" => complete_bool(self.mcp_server_support),
-                "enabled_mcp_servers" => {
-                    let mut prefix = String::new();
-                    let mut ignores = HashSet::new();
-                    if let Some((v, _)) = args[1].rsplit_once(',') {
-                        ignores = v.split(',').collect();
-                        prefix = format!("{v},");
-                    }
-                    let mut values = vec![];
-                    if prefix.is_empty() {
-                        values.push("all".to_string());
-                    }
-
-                    if let Some(registry) = &self.mcp_registry {
-                        values.extend(registry.list_configured_servers());
-                    }
-
-                    values.extend(self.mapping_mcp_servers.keys().map(|v| v.to_string()));
-                    values
-                        .into_iter()
-                        .filter(|v| !ignores.contains(v.as_str()))
-                        .map(|v| format!("{prefix}{v}"))
-                        .collect()
-                }
-                "save_session" => {
-                    let save_session = if let Some(session) = &self.session {
-                        session.save_session()
-                    } else {
-                        self.save_session
-                    };
-                    complete_option_bool(save_session)
-                }
-                "rag_reranker_model" => list_models(self, ModelType::Reranker)
-                    .iter()
-                    .map(|v| v.id())
-                    .collect(),
-                "highlight" => complete_bool(self.highlight),
-                _ => vec![],
-            };
-            values = candidates.into_iter().map(|v| (v, None)).collect();
-        } else if cmd == ".vault" && args.len() == 2 {
-            values = self
-                .vault
-                .list_secrets(false)
-                .unwrap_or_default()
-                .into_iter()
-                .map(|v| (v, None))
-                .collect();
-        } else if cmd == ".agent" {
-            if args.len() == 2 {
-                let dir = Self::agent_data_dir(args[0]).join(SESSIONS_DIR_NAME);
-                values = list_file_names(dir, ".yaml")
-                    .into_iter()
-                    .map(|v| (v, None))
-                    .collect();
-            }
-            values.extend(complete_agent_variables(args[0]));
-        };
-        fuzzy_filter(values, |v| v.0.as_str(), filter)
-    }
-
-    pub fn sync_models_url(&self) -> String {
-        self.sync_models_url
-            .clone()
-            .unwrap_or_else(|| SYNC_MODELS_URL.into())
-    }
-
-    pub async fn sync_models(url: &str, abort_signal: AbortSignal) -> Result<()> {
-        let content = abortable_run_with_spinner(fetch(url), "Fetching models.yaml", abort_signal)
-            .await
-            .with_context(|| format!("Failed to fetch '{url}'"))?;
-        println!("✓ Fetched '{url}'");
-        let list = serde_yaml::from_str::<Vec<ProviderModels>>(&content)
-            .with_context(|| "Failed to parse models.yaml")?;
-        let models_override = ModelsOverride {
-            version: env!("CARGO_PKG_VERSION").to_string(),
-            list,
-        };
-        let models_override_data =
-            serde_yaml::to_string(&models_override).with_context(|| "Failed to serde {}")?;
-
-        let model_override_path = Self::models_override_file();
-        ensure_parent_exists(&model_override_path)?;
-        std::fs::write(&model_override_path, models_override_data)
-            .with_context(|| format!("Failed to write to '{}'", model_override_path.display()))?;
-        println!("✓ Updated '{}'", model_override_path.display());
-        Ok(())
-    }
-
-    pub fn local_models_override() -> Result<Vec<ProviderModels>> {
-        let model_override_path = Self::models_override_file();
-        let err = || {
-            format!(
-                "Failed to load models at '{}'",
-                model_override_path.display()
-            )
-        };
-        let content = read_to_string(&model_override_path).with_context(err)?;
-        let models_override: ModelsOverride = serde_yaml::from_str(&content).with_context(err)?;
-        if models_override.version != env!("CARGO_PKG_VERSION") {
-            bail!("Incompatible version")
-        }
-        Ok(models_override.list)
-    }
-
-    pub fn light_theme(&self) -> bool {
-        matches!(self.theme.as_deref(), Some("light"))
-    }
-
-    pub fn render_options(&self) -> Result<RenderOptions> {
-        let theme = if self.highlight {
-            let theme_mode = if self.light_theme() { "light" } else { "dark" };
-            let theme_filename = format!("{theme_mode}.tmTheme");
-            let theme_path = Self::local_path(&theme_filename);
-            if theme_path.exists() {
-                let theme = ThemeSet::get_theme(&theme_path)
-                    .with_context(|| format!("Invalid theme at '{}'", theme_path.display()))?;
-                Some(theme)
-            } else {
-                let theme = if self.light_theme() {
-                    decode_bin(LIGHT_THEME).context("Invalid builtin light theme")?
-                } else {
-                    decode_bin(DARK_THEME).context("Invalid builtin dark theme")?
-                };
-                Some(theme)
-            }
-        } else {
-            None
-        };
-        let wrap = if *IS_STDOUT_TERMINAL {
-            self.wrap.clone()
-        } else {
-            None
-        };
-        let truecolor = matches!(
-            env::var("COLORTERM").as_ref().map(|v| v.as_str()),
-            Ok("truecolor")
-        );
-        Ok(RenderOptions::new(theme, wrap, self.wrap_code, truecolor))
-    }
-
-    pub fn render_prompt_left(&self) -> String {
-        let variables = self.generate_prompt_context();
-        let left_prompt = self.left_prompt.as_deref().unwrap_or(LEFT_PROMPT);
-        render_prompt(left_prompt, &variables)
-    }
-
-    pub fn render_prompt_right(&self) -> String {
-        let variables = self.generate_prompt_context();
-        let right_prompt = self.right_prompt.as_deref().unwrap_or(RIGHT_PROMPT);
-        render_prompt(right_prompt, &variables)
-    }
-
-    pub fn print_markdown(&self, text: &str) -> Result<()> {
-        if *IS_STDOUT_TERMINAL {
-            let render_options = self.render_options()?;
-            let mut markdown_render = MarkdownRender::init(render_options)?;
-            println!("{}", markdown_render.render(text));
-        } else {
-            println!("{text}");
-        }
-        Ok(())
-    }
-
-    fn generate_prompt_context(&self) -> HashMap<&str, String> {
-        let mut output = HashMap::new();
-        let role = self.extract_role();
-        output.insert("model", role.model().id());
-        output.insert("client_name", role.model().client_name().to_string());
-        output.insert("model_name", role.model().name().to_string());
-        output.insert(
-            "max_input_tokens",
-            role.model()
-                .max_input_tokens()
-                .unwrap_or_default()
-                .to_string(),
-        );
-        if let Some(temperature) = role.temperature()
-            && temperature != 0.0
-        {
-            output.insert("temperature", temperature.to_string());
-        }
-        if let Some(top_p) = role.top_p()
-            && top_p != 0.0
-        {
-            output.insert("top_p", top_p.to_string());
-        }
-        if self.dry_run {
-            output.insert("dry_run", "true".to_string());
-        }
-        if self.stream {
-            output.insert("stream", "true".to_string());
-        }
-        if self.save {
-            output.insert("save", "true".to_string());
-        }
-        if let Some(wrap) = &self.wrap
-            && wrap != "no"
-        {
-            output.insert("wrap", wrap.clone());
-        }
-        if !role.is_derived() {
-            output.insert("role", role.name().to_string());
-        }
-        if let Some(session) = &self.session {
-            output.insert("session", session.name().to_string());
-            if let Some(autoname) = session.autoname() {
-                output.insert("session_autoname", autoname.to_string());
-            }
-            output.insert("dirty", session.dirty().to_string());
-            let (tokens, percent) = session.tokens_usage();
-            output.insert("consume_tokens", tokens.to_string());
-            output.insert("consume_percent", percent.to_string());
-            output.insert("user_messages_len", session.user_messages_len().to_string());
-        }
-        if let Some(rag) = &self.rag {
-            output.insert("rag", rag.name().to_string());
-        }
-        if let Some(agent) = &self.agent {
-            output.insert("agent", agent.name().to_string());
-        }
-
-        if self.highlight {
-            output.insert("color.reset", "\u{1b}[0m".to_string());
-            output.insert("color.black", "\u{1b}[30m".to_string());
-            output.insert("color.dark_gray", "\u{1b}[90m".to_string());
-            output.insert("color.red", "\u{1b}[31m".to_string());
-            output.insert("color.light_red", "\u{1b}[91m".to_string());
-            output.insert("color.green", "\u{1b}[32m".to_string());
-            output.insert("color.light_green", "\u{1b}[92m".to_string());
-            output.insert("color.yellow", "\u{1b}[33m".to_string());
-            output.insert("color.light_yellow", "\u{1b}[93m".to_string());
-            output.insert("color.blue", "\u{1b}[34m".to_string());
-            output.insert("color.light_blue", "\u{1b}[94m".to_string());
-            output.insert("color.purple", "\u{1b}[35m".to_string());
-            output.insert("color.light_purple", "\u{1b}[95m".to_string());
-            output.insert("color.magenta", "\u{1b}[35m".to_string());
-            output.insert("color.light_magenta", "\u{1b}[95m".to_string());
-            output.insert("color.cyan", "\u{1b}[36m".to_string());
-            output.insert("color.light_cyan", "\u{1b}[96m".to_string());
-            output.insert("color.white", "\u{1b}[37m".to_string());
-            output.insert("color.light_gray", "\u{1b}[97m".to_string());
-        }
-
-        output
-    }
-
-    pub fn before_chat_completion(&mut self, input: &Input) -> Result<()> {
-        self.last_message = Some(LastMessage::new(input.clone(), String::new()));
-        Ok(())
-    }
-
-    pub fn after_chat_completion(
-        &mut self,
-        input: &Input,
-        output: &str,
-        tool_results: &[ToolResult],
-    ) -> Result<()> {
-        if !tool_results.is_empty() {
-            return Ok(());
-        }
-        self.last_message = Some(LastMessage::new(input.clone(), output.to_string()));
-        if !self.dry_run {
-            self.save_message(input, output)?;
-        }
-        Ok(())
-    }
-
-    fn discontinuous_last_message(&mut self) {
-        if let Some(last_message) = self.last_message.as_mut() {
-            last_message.continuous = false;
-        }
-    }
-
-    fn save_message(&mut self, input: &Input, output: &str) -> Result<()> {
-        let mut input = input.clone();
-        input.clear_patch();
-        if let Some(session) = input.session_mut(&mut self.session) {
-            session.add_message(&input, output)?;
-            return Ok(());
-        }
-
-        if !self.save {
-            return Ok(());
-        }
-        let mut file = self.open_message_file()?;
-        if output.is_empty() && input.tool_calls().is_none() {
-            return Ok(());
-        }
-        let now = now();
-        let summary = input.summary();
-        let raw_input = input.raw();
-        let scope = if self.agent.is_none() {
-            let role_name = if input.role().is_derived() {
-                None
-            } else {
-                Some(input.role().name())
-            };
-            match (role_name, input.rag_name()) {
-                (Some(role), Some(rag_name)) => format!(" ({role}#{rag_name})"),
-                (Some(role), _) => format!(" ({role})"),
-                (None, Some(rag_name)) => format!(" (#{rag_name})"),
-                _ => String::new(),
-            }
-        } else {
-            String::new()
-        };
-        let tool_calls = match input.tool_calls() {
-            Some(MessageContentToolCalls {
-                tool_results, text, ..
-            }) => {
-                let mut lines = vec!["<tool_calls>".to_string()];
-                if !text.is_empty() {
-                    lines.push(text.clone());
-                }
-                lines.push(serde_json::to_string(&tool_results).unwrap_or_default());
-                lines.push("</tool_calls>\n".to_string());
-                lines.join("\n")
-            }
-            None => String::new(),
-        };
-        let output = format!(
-            "# CHAT: {summary} [{now}]{scope}\n{raw_input}\n--------\n{tool_calls}{output}\n--------\n\n",
-        );
-        file.write_all(output.as_bytes())
-            .with_context(|| "Failed to save message")
-    }
-
-    fn init_agent_shared_variables(&mut self) -> Result<()> {
-        let agent = match self.agent.as_mut() {
-            Some(v) => v,
-            None => return Ok(()),
-        };
-        if !agent.defined_variables().is_empty() && agent.shared_variables().is_empty() {
-            let new_variables = Agent::init_agent_variables(
-                agent.defined_variables(),
-                self.agent_variables.as_ref(),
-                self.info_flag,
-            )?;
-            agent.set_shared_variables(new_variables);
-        }
-        if !self.info_flag {
-            agent.update_shared_dynamic_instructions(false)?;
-        }
-        Ok(())
-    }
-
-    fn init_agent_session_variables(&mut self, new_session: bool) -> Result<()> {
-        let (agent, session) = match (self.agent.as_mut(), self.session.as_mut()) {
-            (Some(agent), Some(session)) => (agent, session),
-            _ => return Ok(()),
-        };
-        if new_session {
-            let shared_variables = agent.shared_variables().clone();
-            let session_variables =
-                if !agent.defined_variables().is_empty() && shared_variables.is_empty() {
-                    let new_variables = Agent::init_agent_variables(
-                        agent.defined_variables(),
-                        self.agent_variables.as_ref(),
-                        self.info_flag,
-                    )?;
-                    agent.set_shared_variables(new_variables.clone());
-                    new_variables
-                } else {
-                    shared_variables
-                };
-            agent.set_session_variables(session_variables);
-            if !self.info_flag {
-                agent.update_session_dynamic_instructions(None)?;
-            }
-            session.sync_agent(agent);
-        } else {
-            let variables = session.agent_variables();
-            agent.set_session_variables(variables.clone());
-            agent.update_session_dynamic_instructions(Some(
-                session.agent_instructions().to_string(),
-            ))?;
-        }
-        Ok(())
-    }
-
-    fn open_message_file(&self) -> Result<File> {
-        let path = self.messages_file();
-        ensure_parent_exists(&path)?;
-        OpenOptions::new()
-            .create(true)
-            .append(true)
-            .open(&path)
-            .with_context(|| format!("Failed to create/append {}", path.display()))
-    }
-
-    fn load_from_file(config_path: &Path) -> Result<(Self, String)> {
+    pub fn load_from_file(config_path: &Path) -> Result<(Self, String)> {
         let err = || format!("Failed to load config at '{}'", config_path.display());
         let content = read_to_string(config_path).with_context(err)?;
         let config = Self::load_from_str(&content).with_context(err)?;
@@ -2756,7 +444,7 @@ impl Config {
         Ok((config, content))
     }
 
-    fn load_from_str(content: &str) -> Result<Self> {
+    pub fn load_from_str(content: &str) -> Result<Self> {
         if PASSWORD_FILE_SECRET_RE.is_match(content)? {
             bail!("secret injection cannot be done on the vault_password_file property");
         }
@@ -2782,7 +470,7 @@ impl Config {
         Ok(config)
     }
 
-    fn load_dynamic(model_id: &str) -> Result<Self> {
+    pub fn load_dynamic(model_id: &str) -> Result<Self> {
         let provider = match model_id.split_once(':') {
             Some((v, _)) => v,
             _ => model_id,
@@ -2804,229 +492,10 @@ impl Config {
             serde_json::from_value(config).with_context(|| "Failed to load config from env")?;
         Ok(config)
     }
-
-    fn load_envs(&mut self) {
-        if let Ok(v) = env::var(get_env_name("model")) {
-            self.model_id = v;
-        }
-        if let Some(v) = read_env_value::<f64>(&get_env_name("temperature")) {
-            self.temperature = v;
-        }
-        if let Some(v) = read_env_value::<f64>(&get_env_name("top_p")) {
-            self.top_p = v;
-        }
-
-        if let Some(Some(v)) = read_env_bool(&get_env_name("dry_run")) {
-            self.dry_run = v;
-        }
-        if let Some(Some(v)) = read_env_bool(&get_env_name("stream")) {
-            self.stream = v;
-        }
-        if let Some(Some(v)) = read_env_bool(&get_env_name("save")) {
-            self.save = v;
-        }
-        if let Ok(v) = env::var(get_env_name("keybindings"))
-            && v == "vi"
-        {
-            self.keybindings = v;
-        }
-        if let Some(v) = read_env_value::<String>(&get_env_name("editor")) {
-            self.editor = v;
-        }
-        if let Some(v) = read_env_value::<String>(&get_env_name("wrap")) {
-            self.wrap = v;
-        }
-        if let Some(Some(v)) = read_env_bool(&get_env_name("wrap_code")) {
-            self.wrap_code = v;
-        }
-
-        if let Some(Some(v)) = read_env_bool(&get_env_name("function_calling_support")) {
-            self.function_calling_support = v;
-        }
-        if let Ok(v) = env::var(get_env_name("mapping_tools"))
-            && let Ok(v) = serde_json::from_str(&v)
-        {
-            self.mapping_tools = v;
-        }
-        if let Some(v) = read_env_value::<String>(&get_env_name("enabled_tools")) {
-            self.enabled_tools = v;
-        }
-
-        if let Some(Some(v)) = read_env_bool(&get_env_name("mcp_server_support")) {
-            self.mcp_server_support = v;
-        }
-        if let Ok(v) = env::var(get_env_name("mapping_mcp_servers"))
-            && let Ok(v) = serde_json::from_str(&v)
-        {
-            self.mapping_mcp_servers = v;
-        }
-        if let Some(v) = read_env_value::<String>(&get_env_name("enabled_mcp_servers")) {
-            self.enabled_mcp_servers = v;
-        }
-
-        if let Some(v) = read_env_value::<String>(&get_env_name("repl_prelude")) {
-            self.repl_prelude = v;
-        }
-        if let Some(v) = read_env_value::<String>(&get_env_name("cmd_prelude")) {
-            self.cmd_prelude = v;
-        }
-        if let Some(v) = read_env_value::<String>(&get_env_name("agent_session")) {
-            self.agent_session = v;
-        }
-
-        if let Some(v) = read_env_bool(&get_env_name("save_session")) {
-            self.save_session = v;
-        }
-        if let Some(Some(v)) = read_env_value::<usize>(&get_env_name("compression_threshold")) {
-            self.compression_threshold = v;
-        }
-        if let Some(v) = read_env_value::<String>(&get_env_name("summarization_prompt")) {
-            self.summarization_prompt = v;
-        }
-        if let Some(v) = read_env_value::<String>(&get_env_name("summary_context_prompt")) {
-            self.summary_context_prompt = v;
-        }
-
-        if let Some(v) = read_env_value::<String>(&get_env_name("rag_embedding_model")) {
-            self.rag_embedding_model = v;
-        }
-        if let Some(v) = read_env_value::<String>(&get_env_name("rag_reranker_model")) {
-            self.rag_reranker_model = v;
-        }
-        if let Some(Some(v)) = read_env_value::<usize>(&get_env_name("rag_top_k")) {
-            self.rag_top_k = v;
-        }
-        if let Some(v) = read_env_value::<usize>(&get_env_name("rag_chunk_size")) {
-            self.rag_chunk_size = v;
-        }
-        if let Some(v) = read_env_value::<usize>(&get_env_name("rag_chunk_overlap")) {
-            self.rag_chunk_overlap = v;
-        }
-        if let Some(v) = read_env_value::<String>(&get_env_name("rag_template")) {
-            self.rag_template = v;
-        }
-
-        if let Ok(v) = env::var(get_env_name("document_loaders"))
-            && let Ok(v) = serde_json::from_str(&v)
-        {
-            self.document_loaders = v;
-        }
-
-        if let Some(Some(v)) = read_env_bool(&get_env_name("highlight")) {
-            self.highlight = v;
-        }
-        if *NO_COLOR {
-            self.highlight = false;
-        }
-        if self.highlight && self.theme.is_none() {
-            if let Some(v) = read_env_value::<String>(&get_env_name("theme")) {
-                self.theme = v;
-            } else if *IS_STDOUT_TERMINAL
-                && let Ok(color_scheme) = color_scheme(QueryOptions::default())
-            {
-                let theme = match color_scheme {
-                    ColorScheme::Dark => "dark",
-                    ColorScheme::Light => "light",
-                };
-                self.theme = Some(theme.into());
-            }
-        }
-        if let Some(v) = read_env_value::<String>(&get_env_name("left_prompt")) {
-            self.left_prompt = v;
-        }
-        if let Some(v) = read_env_value::<String>(&get_env_name("right_prompt")) {
-            self.right_prompt = v;
-        }
-        if let Some(v) = read_env_value::<String>(&get_env_name("user_agent")) {
-            self.user_agent = v;
-        }
-        if let Some(Some(v)) = read_env_bool(&get_env_name("save_shell_history")) {
-            self.save_shell_history = v;
-        }
-        if let Some(v) = read_env_value::<String>(&get_env_name("sync_models_url")) {
-            self.sync_models_url = v;
-        }
-    }
-
-    fn load_functions(&mut self) -> Result<()> {
-        self.functions = Functions::init(self.visible_tools.as_ref().unwrap_or(&Vec::new()))?;
-        if self.working_mode.is_repl() {
-            self.functions.append_user_interaction_functions();
-        }
-        Ok(())
-    }
-
-    async fn load_mcp_servers(
-        &mut self,
-        log_path: Option<PathBuf>,
-        start_mcp_servers: bool,
-        abort_signal: AbortSignal,
-    ) -> Result<()> {
-        let mcp_registry = McpRegistry::init(
-            log_path,
-            start_mcp_servers,
-            self.enabled_mcp_servers.clone(),
-            abort_signal.clone(),
-            self,
-        )
-        .await?;
-        match mcp_registry.is_empty() {
-            false => {
-                if self.mcp_server_support {
-                    self.functions
-                        .append_mcp_meta_functions(mcp_registry.list_started_servers());
-                } else {
-                    debug!(
-                        "Skipping global MCP functions registration since 'mcp_server_support' was 'false'"
-                    );
-                }
-            }
-            _ => debug!(
-                "Skipping global MCP functions registration since 'start_mcp_servers' was 'false'"
-            ),
-        }
-        self.mcp_registry = Some(mcp_registry);
-
-        Ok(())
-    }
-
-    fn setup_model(&mut self) -> Result<()> {
-        let mut model_id = self.model_id.clone();
-        if model_id.is_empty() {
-            let models = list_models(self, ModelType::Chat);
-            if models.is_empty() {
-                bail!("No available model");
-            }
-            model_id = models[0].id()
-        }
-        self.set_model(&model_id)?;
-        self.model_id = model_id;
-
-        Ok(())
-    }
-
-    fn setup_document_loaders(&mut self) {
-        [("pdf", "pdftotext $1 -"), ("docx", "pandoc --to plain $1")]
-            .into_iter()
-            .for_each(|(k, v)| {
-                let (k, v) = (k.to_string(), v.to_string());
-                self.document_loaders.entry(k).or_insert(v);
-            });
-    }
-
-    fn setup_user_agent(&mut self) {
-        if let Some("auto") = self.user_agent.as_deref() {
-            self.user_agent = Some(format!(
-                "{}/{}",
-                env!("CARGO_CRATE_NAME"),
-                env!("CARGO_PKG_VERSION")
-            ));
-        }
-    }
 }
 
 pub fn load_env_file() -> Result<()> {
-    let env_file_path = Config::env_file();
+    let env_file_path = paths::env_file();
     let contents = match read_to_string(&env_file_path) {
         Ok(v) => v,
         Err(_) => return Ok(()),
@@ -3123,7 +592,7 @@ impl AssertState {
     }
 }
 
-async fn create_config_file(config_path: &Path) -> Result<()> {
+pub async fn create_config_file(config_path: &Path) -> Result<()> {
     let ans = Confirm::new("No config file, create a new one?")
         .with_default(true)
         .prompt()?;
@@ -3140,6 +609,18 @@ async fn create_config_file(config_path: &Path) -> Result<()> {
     let (model, clients_config) = create_client_config(client, &vault).await?;
     config["model"] = model.into();
     config["vault_password_file"] = vault.password_file()?.display().to_string().into();
+    config["stream"] = json!(true);
+    config["save"] = json!(true);
+    config["keybindings"] = json!("vi");
+    config["wrap"] = json!("auto");
+    config["wrap_code"] = json!(false);
+    config["function_calling_support"] = json!(true);
+    config["enabled_tools"] = json!(null);
+    config["visible_tools"] = json!(DEFAULT_VISIBLE_TOOLS);
+    config["mcp_server_support"] = json!(true);
+    config["enabled_mcp_servers"] = json!(null);
+    config["highlight"] = json!(true);
+    config["light_theme"] = json!(false);
     config[CLIENTS_FIELD] = clients_config;
 
     let config_data = serde_yaml::to_string(&config).with_context(|| "Failed to create config")?;
@@ -3189,7 +670,7 @@ where
     Some(value)
 }
 
-fn parse_value<T>(value: &str) -> Result<Option<T>>
+pub(super) fn parse_value<T>(value: &str) -> Result<Option<T>>
 where
     T: std::str::FromStr,
 {
@@ -3210,11 +691,11 @@ fn read_env_bool(key: &str) -> Option<Option<bool>> {
     Some(parse_bool(&value))
 }
 
-fn complete_bool(value: bool) -> Vec<String> {
+pub(super) fn complete_bool(value: bool) -> Vec<String> {
     vec![(!value).to_string()]
 }
 
-fn complete_option_bool(value: Option<bool>) -> Vec<String> {
+pub(super) fn complete_option_bool(value: Option<bool>) -> Vec<String> {
     match value {
         Some(true) => vec!["false".to_string(), "null".to_string()],
         Some(false) => vec!["true".to_string(), "null".to_string()],
@@ -3222,24 +703,11 @@ fn complete_option_bool(value: Option<bool>) -> Vec<String> {
     }
 }
 
-fn map_completion_values<T: ToString>(value: Vec<T>) -> Vec<(String, Option<String>)> {
+pub(super) fn map_completion_values<T: ToString>(value: Vec<T>) -> Vec<(String, Option<String>)> {
     value.into_iter().map(|v| (v.to_string(), None)).collect()
 }
 
-fn update_rag<F>(config: &GlobalConfig, f: F) -> Result<()>
-where
-    F: FnOnce(&mut Rag) -> Result<()>,
-{
-    let mut rag = match config.read().rag.clone() {
-        Some(v) => v.as_ref().clone(),
-        None => bail!("No RAG"),
-    };
-    f(&mut rag)?;
-    config.write().rag = Some(Arc::new(rag));
-    Ok(())
-}
-
-fn format_option_value<T>(value: &Option<T>) -> String
+pub(super) fn format_option_value<T>(value: &Option<T>) -> String
 where
     T: std::fmt::Display,
 {
@@ -3248,3 +716,105 @@ where
         None => "null".to_string(),
     }
 }
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn config_defaults_match_expected() {
+        let cfg = Config::default();
+
+        assert_eq!(cfg.model_id, "");
+        assert_eq!(cfg.temperature, None);
+        assert_eq!(cfg.top_p, None);
+        assert!(!cfg.dry_run);
+        assert!(cfg.stream);
+        assert!(!cfg.save);
+        assert!(cfg.highlight);
+        assert!(cfg.function_calling_support);
+        assert!(cfg.mcp_server_support);
+        assert_eq!(cfg.compression_threshold, 4000);
+        assert_eq!(cfg.rag_top_k, 5);
+        assert!(cfg.save_shell_history);
+        assert_eq!(cfg.keybindings, "emacs");
+        assert!(cfg.clients.is_empty());
+        assert!(cfg.save_session.is_none());
+        assert!(cfg.enabled_tools.is_none());
+        assert!(cfg.enabled_mcp_servers.is_none());
+    }
+
+    #[test]
+    fn assert_state_pass_always_true() {
+        let pass = AssertState::pass();
+        assert!(pass.assert(StateFlags::empty()));
+        assert!(pass.assert(StateFlags::ROLE));
+        assert!(pass.assert(StateFlags::SESSION | StateFlags::AGENT));
+        assert!(pass.assert(StateFlags::all()));
+    }
+
+    #[test]
+    fn assert_state_bare_only_empty() {
+        let bare = AssertState::bare();
+        assert!(bare.assert(StateFlags::empty()));
+        assert!(!bare.assert(StateFlags::ROLE));
+        assert!(!bare.assert(StateFlags::SESSION));
+    }
+
+    #[test]
+    fn assert_state_true_requires_flag_present() {
+        let state = AssertState::True(StateFlags::ROLE);
+        assert!(state.assert(StateFlags::ROLE));
+        assert!(state.assert(StateFlags::ROLE | StateFlags::SESSION));
+        assert!(!state.assert(StateFlags::empty()));
+        assert!(!state.assert(StateFlags::SESSION));
+    }
+
+    #[test]
+    fn assert_state_true_with_multiple_flags_any_match() {
+        let state = AssertState::True(StateFlags::SESSION_EMPTY | StateFlags::SESSION);
+        assert!(state.assert(StateFlags::SESSION_EMPTY));
+        assert!(state.assert(StateFlags::SESSION));
+        assert!(state.assert(StateFlags::SESSION | StateFlags::ROLE));
+        assert!(!state.assert(StateFlags::ROLE));
+        assert!(!state.assert(StateFlags::empty()));
+    }
+
+    #[test]
+    fn assert_state_false_requires_flag_absent() {
+        let state = AssertState::False(StateFlags::AGENT);
+        assert!(state.assert(StateFlags::empty()));
+        assert!(state.assert(StateFlags::ROLE));
+        assert!(!state.assert(StateFlags::AGENT));
+        assert!(!state.assert(StateFlags::AGENT | StateFlags::ROLE));
+    }
+
+    #[test]
+    fn assert_state_false_with_multiple_flags() {
+        let state = AssertState::False(StateFlags::SESSION | StateFlags::AGENT);
+        assert!(state.assert(StateFlags::empty()));
+        assert!(state.assert(StateFlags::ROLE));
+        assert!(!state.assert(StateFlags::SESSION));
+        assert!(!state.assert(StateFlags::AGENT));
+        assert!(!state.assert(StateFlags::SESSION | StateFlags::AGENT));
+    }
+
+    #[test]
+    fn assert_state_truefalse_requires_true_present_and_false_absent() {
+        let state = AssertState::TrueFalse(StateFlags::ROLE, StateFlags::SESSION);
+        assert!(state.assert(StateFlags::ROLE));
+        assert!(state.assert(StateFlags::ROLE | StateFlags::RAG));
+        assert!(!state.assert(StateFlags::empty()));
+        assert!(!state.assert(StateFlags::SESSION));
+        assert!(!state.assert(StateFlags::ROLE | StateFlags::SESSION));
+    }
+
+    #[test]
+    fn assert_state_equal_exact_match() {
+        let state = AssertState::Equal(StateFlags::ROLE | StateFlags::SESSION);
+        assert!(state.assert(StateFlags::ROLE | StateFlags::SESSION));
+        assert!(!state.assert(StateFlags::ROLE));
+        assert!(!state.assert(StateFlags::SESSION));
+        assert!(!state.assert(StateFlags::empty()));
+    }
+}
diff --git a/src/config/paths.rs b/src/config/paths.rs
new file mode 100644
index 0000000..b1df31e
--- /dev/null
+++ b/src/config/paths.rs
@@ -0,0 +1,251 @@
+use super::role::Role;
+use super::{
+    AGENT_GRAPH_FILE_NAME, AGENTS_DIR_NAME, BASH_PROMPT_UTILS_FILE_NAME, CONFIG_FILE_NAME,
+    ENV_FILE_NAME, FUNCTIONS_BIN_DIR_NAME, FUNCTIONS_DIR_NAME, GLOBAL_TOOLS_DIR_NAME,
+    GLOBAL_TOOLS_UTILS_DIR_NAME, MACROS_DIR_NAME, MCP_FILE_NAME, ModelsOverride, RAGS_DIR_NAME,
+    ROLES_DIR_NAME,
+};
+use crate::client::ProviderModels;
+use crate::utils::{get_env_name, list_file_names, normalize_env_name};
+
+use anyhow::{Context, Result, anyhow, bail};
+use log::LevelFilter;
+use std::collections::HashSet;
+use std::env;
+use std::fs::{read_dir, read_to_string};
+use std::path::PathBuf;
+
+pub fn config_dir() -> PathBuf {
+    if let Ok(v) = env::var(get_env_name("config_dir")) {
+        PathBuf::from(v)
+    } else if let Ok(v) = env::var("XDG_CONFIG_HOME") {
+        PathBuf::from(v).join(env!("CARGO_CRATE_NAME"))
+    } else {
+        let dir = dirs::config_dir().expect("No user's config directory");
+        dir.join(env!("CARGO_CRATE_NAME"))
+    }
+}
+
+pub fn local_path(name: &str) -> PathBuf {
+    config_dir().join(name)
+}
+
+pub fn cache_path() -> PathBuf {
+    let base_dir = dirs::cache_dir().unwrap_or_else(env::temp_dir);
+    base_dir.join(env!("CARGO_CRATE_NAME"))
+}
+
+pub fn oauth_tokens_path() -> PathBuf {
+    cache_path().join("oauth")
+}
+
+pub fn token_file(client_name: &str) -> PathBuf {
+    oauth_tokens_path().join(format!("{client_name}_oauth_tokens.json"))
+}
+
+pub fn log_path() -> PathBuf {
+    cache_path().join(format!("{}.log", env!("CARGO_CRATE_NAME")))
+}
+
+pub fn config_file() -> PathBuf {
+    match env::var(get_env_name("config_file")) {
+        Ok(value) => PathBuf::from(value),
+        Err(_) => local_path(CONFIG_FILE_NAME),
+    }
+}
+
+pub fn roles_dir() -> PathBuf {
+    match env::var(get_env_name("roles_dir")) {
+        Ok(value) => PathBuf::from(value),
+        Err(_) => local_path(ROLES_DIR_NAME),
+    }
+}
+
+pub fn role_file(name: &str) -> PathBuf {
+    roles_dir().join(format!("{name}.md"))
+}
+
+pub fn macros_dir() -> PathBuf {
+    match env::var(get_env_name("macros_dir")) {
+        Ok(value) => PathBuf::from(value),
+        Err(_) => local_path(MACROS_DIR_NAME),
+    }
+}
+
+pub fn macro_file(name: &str) -> PathBuf {
+    macros_dir().join(format!("{name}.yaml"))
+}
+
+pub fn env_file() -> PathBuf {
+    match env::var(get_env_name("env_file")) {
+        Ok(value) => PathBuf::from(value),
+        Err(_) => local_path(ENV_FILE_NAME),
+    }
+}
+
+pub fn rags_dir() -> PathBuf {
+    match env::var(get_env_name("rags_dir")) {
+        Ok(value) => PathBuf::from(value),
+        Err(_) => local_path(RAGS_DIR_NAME),
+    }
+}
+
+pub fn functions_dir() -> PathBuf {
+    match env::var(get_env_name("functions_dir")) {
+        Ok(value) => PathBuf::from(value),
+        Err(_) => local_path(FUNCTIONS_DIR_NAME),
+    }
+}
+
+pub fn functions_bin_dir() -> PathBuf {
+    functions_dir().join(FUNCTIONS_BIN_DIR_NAME)
+}
+
+pub fn mcp_config_file() -> PathBuf {
+    functions_dir().join(MCP_FILE_NAME)
+}
+
+pub fn global_tools_dir() -> PathBuf {
+    functions_dir().join(GLOBAL_TOOLS_DIR_NAME)
+}
+
+pub fn global_utils_dir() -> PathBuf {
+    functions_dir().join(GLOBAL_TOOLS_UTILS_DIR_NAME)
+}
+
+pub fn bash_prompt_utils_file() -> PathBuf {
+    global_utils_dir().join(BASH_PROMPT_UTILS_FILE_NAME)
+}
+
+pub fn agents_data_dir() -> PathBuf {
+    local_path(AGENTS_DIR_NAME)
+}
+
+pub fn agent_data_dir(name: &str) -> PathBuf {
+    match env::var(format!("{}_DATA_DIR", normalize_env_name(name))) {
+        Ok(value) => PathBuf::from(value),
+        Err(_) => agents_data_dir().join(name),
+    }
+}
+
+pub fn agent_graph_file(agent_name: &str) -> PathBuf {
+    agent_data_dir(agent_name).join(AGENT_GRAPH_FILE_NAME)
+}
+
+pub fn agent_config_file(name: &str) -> PathBuf {
+    match env::var(format!("{}_CONFIG_FILE", normalize_env_name(name))) {
+        Ok(value) => PathBuf::from(value),
+        Err(_) => agent_data_dir(name).join(CONFIG_FILE_NAME),
+    }
+}
+
+pub fn agent_bin_dir(name: &str) -> PathBuf {
+    agent_data_dir(name).join(FUNCTIONS_BIN_DIR_NAME)
+}
+
+pub fn agent_rag_file(agent_name: &str, rag_name: &str) -> PathBuf {
+    agent_data_dir(agent_name).join(format!("{rag_name}.yaml"))
+}
+
+pub fn agent_functions_file(name: &str) -> Result<PathBuf> {
+    let priority = ["tools.sh", "tools.py", "tools.ts", "tools.js"];
+    let dir = agent_data_dir(name);
+
+    for filename in priority {
+        let path = dir.join(filename);
+        if path.exists() {
+            return Ok(path);
+        }
+    }
+
+    Err(anyhow!(
+        "No tools script found in agent functions directory"
+    ))
+}
+
+pub fn models_override_file() -> PathBuf {
+    local_path("models-override.yaml")
+}
+
+pub fn log_config() -> Result<(LevelFilter, Option<PathBuf>)> {
+    let log_level = env::var(get_env_name("log_level"))
+        .ok()
+        .and_then(|v| v.parse().ok())
+        .unwrap_or(match cfg!(debug_assertions) {
+            true => LevelFilter::Debug,
+            false => LevelFilter::Info,
+        });
+    let resolved_log_path = match env::var(get_env_name("log_path")) {
+        Ok(v) => Some(PathBuf::from(v)),
+        Err(_) => Some(log_path()),
+    };
+    Ok((log_level, resolved_log_path))
+}
+
+pub fn list_roles(with_builtin: bool) -> Vec<String> {
+    let mut names = HashSet::new();
+    if let Ok(rd) = read_dir(roles_dir()) {
+        for entry in rd.flatten() {
+            if let Some(name) = entry
+                .file_name()
+                .to_str()
+                .and_then(|v| v.strip_suffix(".md"))
+            {
+                names.insert(name.to_string());
+            }
+        }
+    }
+    if with_builtin {
+        names.extend(Role::list_builtin_role_names());
+    }
+    let mut names: Vec<_> = names.into_iter().collect();
+    names.sort_unstable();
+    names
+}
+
+pub fn has_role(name: &str) -> bool {
+    let names = list_roles(true);
+    names.contains(&name.to_string())
+}
+
+pub fn list_rags() -> Vec<String> {
+    match read_dir(rags_dir()) {
+        Ok(rd) => {
+            let mut names = vec![];
+            for entry in rd.flatten() {
+                let name = entry.file_name();
+                if let Some(name) = name.to_string_lossy().strip_suffix(".yaml") {
+                    names.push(name.to_string());
+                }
+            }
+            names.sort_unstable();
+            names
+        }
+        Err(_) => vec![],
+    }
+}
+
+pub fn list_macros() -> Vec<String> {
+    list_file_names(macros_dir(), ".yaml")
+}
+
+pub fn has_macro(name: &str) -> bool {
+    let names = list_macros();
+    names.contains(&name.to_string())
+}
+
+pub fn local_models_override() -> Result<Vec<ProviderModels>> {
+    let model_override_path = models_override_file();
+    let err = || {
+        format!(
+            "Failed to load models at '{}'",
+            model_override_path.display()
+        )
+    };
+    let content = read_to_string(&model_override_path).with_context(err)?;
+    let models_override: ModelsOverride = serde_yaml::from_str(&content).with_context(err)?;
+    if models_override.version != env!("CARGO_PKG_VERSION") {
+        bail!("Incompatible version")
+    }
+    Ok(models_override.list)
+}
diff --git a/src/config/rag_cache.rs b/src/config/rag_cache.rs
new file mode 100644
index 0000000..5a43eb6
--- /dev/null
+++ b/src/config/rag_cache.rs
@@ -0,0 +1,49 @@
+use crate::rag::Rag;
+
+use anyhow::Result;
+use parking_lot::RwLock;
+use std::collections::HashMap;
+use std::sync::{Arc, Weak};
+
+#[derive(Clone, Debug, Eq, Hash, PartialEq)]
+pub enum RagKey {
+    Named(String),
+    Agent(String),
+    GraphNode { agent: String, node: String },
+}
+
+#[derive(Default)]
+pub struct RagCache {
+    entries: RwLock<HashMap<RagKey, Weak<Rag>>>,
+}
+
+impl RagCache {
+    pub fn try_get(&self, key: &RagKey) -> Option<Arc<Rag>> {
+        let map = self.entries.read();
+        map.get(key).and_then(|weak| weak.upgrade())
+    }
+
+    pub fn insert(&self, key: RagKey, rag: &Arc<Rag>) {
+        let mut map = self.entries.write();
+        map.insert(key, Arc::downgrade(rag));
+    }
+
+    pub fn invalidate(&self, key: &RagKey) {
+        let mut map = self.entries.write();
+        map.remove(key);
+    }
+
+    pub async fn load_with<F, Fut>(&self, key: RagKey, loader: F) -> Result<Arc<Rag>>
+    where
+        F: FnOnce() -> Fut,
+        Fut: Future<Output = Result<Rag>>,
+    {
+        if let Some(existing) = self.try_get(&key) {
+            return Ok(existing);
+        }
+        let rag = loader().await?;
+        let arc = Arc::new(rag);
+        self.insert(key, &arc);
+        Ok(arc)
+    }
+}
diff --git a/src/config/request_context.rs b/src/config/request_context.rs
new file mode 100644
index 0000000..fc879c6
--- /dev/null
+++ b/src/config/request_context.rs
@@ -0,0 +1,3869 @@
+use super::rag_cache::{RagCache, RagKey};
+use super::session::Session;
+use super::todo::TodoList;
+use super::tool_scope::{McpRuntime, ToolScope};
+use super::{
+    AGENTS_DIR_NAME, Agent, AgentVariables, AppConfig, AppState, AssetCategory, CREATE_TITLE_ROLE,
+    Input, InstallFilter, LEFT_PROMPT, LastMessage, MESSAGES_FILE_NAME, RIGHT_PROMPT, Role,
+    RoleLike, SESSIONS_DIR_NAME, SUMMARIZATION_PROMPT, SUMMARY_CONTEXT_PROMPT, StateFlags,
+    TEMP_ROLE_NAME, TEMP_SESSION_NAME, WorkingMode, ensure_parent_exists, list_agents, paths,
+};
+use super::{MessageContentToolCalls, prompts};
+use crate::client::{Model, ModelType, list_models};
+use crate::function::{
+    FunctionDeclaration, Functions, ToolCallTracker, ToolResult,
+    user_interaction::USER_FUNCTION_PREFIX,
+};
+use crate::mcp::{
+    MCP_DESCRIBE_META_FUNCTION_NAME_PREFIX, MCP_INVOKE_META_FUNCTION_NAME_PREFIX,
+    MCP_SEARCH_META_FUNCTION_NAME_PREFIX,
+};
+use crate::rag::Rag;
+use crate::supervisor::Supervisor;
+use crate::supervisor::escalation::EscalationQueue;
+use crate::supervisor::mailbox::Inbox;
+use crate::utils::{
+    AbortSignal, abortable_run_with_spinner, edit_file, fuzzy_filter, get_env_name,
+    list_file_names, now, render_prompt, temp_file,
+};
+
+use crate::graph;
+use anyhow::{Context, Error, Result, bail};
+#[cfg(test)]
+use indexmap::IndexMap;
+use indoc::formatdoc;
+use inquire::{Confirm, MultiSelect, Text, list_option::ListOption, validator::Validation};
+use parking_lot::RwLock;
+use std::collections::{HashMap, HashSet};
+use std::fs::{File, OpenOptions, read_dir, read_to_string, remove_dir_all, remove_file};
+use std::io::Write;
+use std::path::{Path, PathBuf};
+use std::sync::Arc;
+use std::{env, fs};
+
+pub struct AutoContinueConfig {
+    pub enabled: bool,
+    pub max_continues: usize,
+    pub inject_instructions: bool,
+    pub continuation_prompt: Option<String>,
+}
+
+#[derive(Debug, Clone, Copy, PartialEq, Eq, Default)]
+pub enum RenderMode {
+    #[default]
+    Streaming,
+    Silent,
+}
+
+pub struct RequestContext {
+    pub app: Arc<AppState>,
+
+    pub macro_flag: bool,
+    pub info_flag: bool,
+    pub working_mode: WorkingMode,
+
+    pub model: Model,
+    pub agent_variables: Option<AgentVariables>,
+
+    pub role: Option<Role>,
+    pub session: Option<Session>,
+    pub rag: Option<Arc<Rag>>,
+    pub agent: Option<Agent>,
+
+    pub last_message: Option<LastMessage>,
+
+    pub tool_scope: ToolScope,
+
+    pub supervisor: Option<Arc<RwLock<Supervisor>>>,
+    pub parent_supervisor: Option<Arc<RwLock<Supervisor>>>,
+    pub self_agent_id: Option<String>,
+    pub inbox: Option<Arc<Inbox>>,
+    pub escalation_queue: Option<Arc<EscalationQueue>>,
+    pub current_depth: usize,
+    pub auto_continue_count: usize,
+    pub todo_list: TodoList,
+    pub last_continuation_response: Option<String>,
+
+    pub render_mode: RenderMode,
+}
+
+impl RequestContext {
+    pub fn new(app: Arc<AppState>, working_mode: WorkingMode) -> Self {
+        Self {
+            app,
+            macro_flag: false,
+            info_flag: false,
+            working_mode,
+            model: Default::default(),
+            agent_variables: None,
+            role: None,
+            session: None,
+            rag: None,
+            agent: None,
+            last_message: None,
+            tool_scope: ToolScope::default(),
+            supervisor: None,
+            parent_supervisor: None,
+            self_agent_id: None,
+            inbox: None,
+            escalation_queue: None,
+            current_depth: 0,
+            auto_continue_count: 0,
+            todo_list: TodoList::default(),
+            last_continuation_response: None,
+            render_mode: RenderMode::default(),
+        }
+    }
+
+    pub fn bootstrap(
+        app: Arc<AppState>,
+        working_mode: WorkingMode,
+        info_flag: bool,
+    ) -> Result<Self> {
+        let model = Model::retrieve_model(&app.config, &app.config.model_id, ModelType::Chat)?;
+
+        let mut functions = app.functions.clone();
+        if working_mode.is_repl() {
+            functions.append_user_interaction_functions();
+        }
+
+        let mut mcp_runtime = McpRuntime::default();
+        if let Some(registry) = &app.mcp_registry {
+            mcp_runtime.sync_from_registry(registry);
+        }
+
+        Ok(Self {
+            app,
+            macro_flag: false,
+            info_flag,
+            working_mode,
+            model,
+            agent_variables: None,
+            role: None,
+            session: None,
+            rag: None,
+            agent: None,
+            last_message: None,
+            tool_scope: ToolScope {
+                functions,
+                mcp_runtime,
+                tool_tracker: ToolCallTracker::default(),
+            },
+            supervisor: None,
+            parent_supervisor: None,
+            self_agent_id: None,
+            inbox: None,
+            escalation_queue: None,
+            current_depth: 0,
+            auto_continue_count: 0,
+            todo_list: TodoList::default(),
+            last_continuation_response: None,
+            render_mode: RenderMode::default(),
+        })
+    }
+
+    /// Forks the context for one parallel branch of a graph super-step.
+    ///
+    /// Each branch gets a fresh, owned clone. Mutations (role swap,
+    /// `before/after_chat_completion`, tool tracker, last_message, etc.) are
+    /// scoped to the branch and discarded when the branch finishes. The
+    /// user-visible state communication happens through the graph's
+    /// `StateManager` (via `fork_for_branch_state` + `diff_against` +
+    /// `apply_branch_writes` reducers), and not through `RequestContext`.
+    ///
+    /// Distinction from `new_for_child`: `new_for_child` builds a fresh context
+    /// for a spawned sub-agent (different agent identity, different supervisor
+    /// hierarchy, depth+1, fresh tool tracker). `fork_for_branch` keeps the
+    /// caller's identity and supervisor hierarchy; it's a sibling clone of the
+    /// same logical agent, running one of N parallel work items.
+    pub fn fork_for_branch(&self) -> Self {
+        Self {
+            app: Arc::clone(&self.app),
+            macro_flag: self.macro_flag,
+            info_flag: self.info_flag,
+            working_mode: self.working_mode,
+            model: self.model.clone(),
+            agent_variables: self.agent_variables.clone(),
+            role: self.role.clone(),
+            session: self.session.clone(),
+            rag: self.rag.clone(),
+            agent: self.agent.clone(),
+            last_message: self.last_message.clone(),
+            tool_scope: self.tool_scope.clone(),
+            supervisor: self.supervisor.clone(),
+            parent_supervisor: self.parent_supervisor.clone(),
+            self_agent_id: self.self_agent_id.clone(),
+            inbox: self.inbox.clone(),
+            escalation_queue: self.escalation_queue.clone(),
+            current_depth: self.current_depth,
+            auto_continue_count: 0,
+            todo_list: self.todo_list.clone(),
+            last_continuation_response: None,
+            render_mode: self.render_mode,
+        }
+    }
+
+    pub fn new_for_child(
+        app: Arc<AppState>,
+        parent: &Self,
+        current_depth: usize,
+        inbox: Arc<Inbox>,
+        self_agent_id: String,
+    ) -> Self {
+        let tool_call_tracker = ToolCallTracker::new(4, 10);
+
+        Self {
+            app,
+            macro_flag: parent.macro_flag,
+            info_flag: parent.info_flag,
+            working_mode: WorkingMode::Cmd,
+            model: parent.model.clone(),
+            agent_variables: parent.agent_variables.clone(),
+            role: None,
+            session: None,
+            rag: None,
+            agent: None,
+            last_message: None,
+            tool_scope: ToolScope {
+                functions: Functions::default(),
+                mcp_runtime: McpRuntime::default(),
+                tool_tracker: tool_call_tracker,
+            },
+            supervisor: None,
+            parent_supervisor: parent.supervisor.clone(),
+            self_agent_id: Some(self_agent_id),
+            inbox: Some(inbox),
+            escalation_queue: parent.escalation_queue.clone(),
+            current_depth,
+            auto_continue_count: 0,
+            todo_list: TodoList::default(),
+            last_continuation_response: None,
+            render_mode: parent.render_mode,
+        }
+    }
+
+    fn update_app_config(&mut self, update: impl FnOnce(&mut AppConfig)) {
+        let mut app_config = (*self.app.config).clone();
+        update(&mut app_config);
+
+        let mut app_state = (*self.app).clone();
+        app_state.config = Arc::new(app_config);
+        self.app = Arc::new(app_state);
+    }
+
+    pub fn root_escalation_queue(&self) -> Option<&Arc<EscalationQueue>> {
+        self.escalation_queue.as_ref()
+    }
+
+    pub fn ensure_root_escalation_queue(&mut self) -> Arc<EscalationQueue> {
+        self.escalation_queue
+            .get_or_insert_with(|| Arc::new(EscalationQueue::new()))
+            .clone()
+    }
+
+    pub fn rag_cache(&self) -> &Arc<RagCache> {
+        &self.app.rag_cache
+    }
+
+    pub fn init_todo_list(&mut self, goal: &str) {
+        self.todo_list = TodoList::new(goal);
+    }
+
+    pub fn add_todo(&mut self, task: &str) -> usize {
+        self.todo_list.add(task)
+    }
+
+    pub fn mark_todo_done(&mut self, id: usize) -> bool {
+        self.todo_list.mark_done(id)
+    }
+
+    pub fn clear_todo_list(&mut self) {
+        self.todo_list.clear();
+        self.auto_continue_count = 0;
+    }
+
+    pub fn increment_auto_continue_count(&mut self) {
+        self.auto_continue_count += 1;
+    }
+
+    pub fn reset_continuation_count(&mut self) {
+        self.auto_continue_count = 0;
+        self.last_continuation_response = None;
+    }
+
+    pub fn set_last_continuation_response(&mut self, response: String) {
+        self.last_continuation_response = Some(response);
+    }
+
+    pub fn state(&self) -> StateFlags {
+        let mut flags = StateFlags::empty();
+        if let Some(session) = &self.session {
+            if session.is_empty() {
+                flags |= StateFlags::SESSION_EMPTY;
+            } else {
+                flags |= StateFlags::SESSION;
+            }
+            if session.role_name().is_some() {
+                flags |= StateFlags::ROLE;
+            }
+        } else if self.role.is_some() {
+            flags |= StateFlags::ROLE;
+        }
+        if self.agent.is_some() {
+            flags |= StateFlags::AGENT;
+        }
+        if self.rag.is_some() {
+            flags |= StateFlags::RAG;
+        }
+        flags
+    }
+
+    pub fn messages_file(&self) -> PathBuf {
+        match &self.agent {
+            None => match env::var(get_env_name("messages_file")) {
+                Ok(value) => PathBuf::from(value),
+                Err(_) => paths::cache_path().join(MESSAGES_FILE_NAME),
+            },
+            Some(agent) => paths::cache_path()
+                .join(AGENTS_DIR_NAME)
+                .join(agent.name())
+                .join(MESSAGES_FILE_NAME),
+        }
+    }
+
+    pub fn sessions_dir(&self) -> PathBuf {
+        match &self.agent {
+            None => match env::var(get_env_name("sessions_dir")) {
+                Ok(value) => PathBuf::from(value),
+                Err(_) => paths::local_path(SESSIONS_DIR_NAME),
+            },
+            Some(agent) => paths::agent_data_dir(agent.name()).join(SESSIONS_DIR_NAME),
+        }
+    }
+
+    pub fn session_file(&self, name: &str) -> PathBuf {
+        match name.split_once("/") {
+            Some((dir, name)) => self.sessions_dir().join(dir).join(format!("{name}.yaml")),
+            None => self.sessions_dir().join(format!("{name}.yaml")),
+        }
+    }
+
+    pub fn rag_file(&self, name: &str) -> PathBuf {
+        match &self.agent {
+            Some(agent) => paths::agent_rag_file(agent.name(), name),
+            None => paths::rags_dir().join(format!("{name}.yaml")),
+        }
+    }
+
+    pub fn role_info(&self) -> Result<String> {
+        if let Some(session) = &self.session {
+            if session.role_name().is_some() {
+                let role = session.to_role();
+                Ok(role.export())
+            } else {
+                bail!("No session role")
+            }
+        } else if let Some(role) = &self.role {
+            Ok(role.export())
+        } else {
+            bail!("No role")
+        }
+    }
+
+    pub fn agent_info(&self) -> Result<String> {
+        if let Some(agent) = &self.agent {
+            agent.export()
+        } else {
+            bail!("No agent")
+        }
+    }
+
+    pub fn agent_banner(&self) -> Result<String> {
+        if let Some(agent) = &self.agent {
+            Ok(agent.banner())
+        } else {
+            bail!("No agent")
+        }
+    }
+
+    pub fn rag_info(&self) -> Result<String> {
+        if let Some(rag) = &self.rag {
+            rag.export()
+        } else {
+            bail!("No RAG")
+        }
+    }
+
+    pub fn list_sessions(&self) -> Vec<String> {
+        list_file_names(self.sessions_dir(), ".yaml")
+    }
+
+    pub fn list_autoname_sessions(&self) -> Vec<String> {
+        list_file_names(self.sessions_dir().join("_"), ".yaml")
+    }
+
+    pub fn is_compressing_session(&self) -> bool {
+        self.session
+            .as_ref()
+            .map(|v| v.compressing())
+            .unwrap_or_default()
+    }
+
+    pub fn role_like_mut(&mut self) -> Option<&mut dyn RoleLike> {
+        if let Some(session) = self.session.as_mut() {
+            Some(session)
+        } else if let Some(agent) = self.agent.as_mut() {
+            Some(agent)
+        } else if let Some(role) = self.role.as_mut() {
+            Some(role)
+        } else {
+            None
+        }
+    }
+
+    pub fn use_role_obj(&mut self, role: Role) -> Result<()> {
+        if self.agent.is_some() {
+            bail!("Cannot perform this operation because you are using a agent")
+        }
+        if let Some(session) = self.session.as_mut() {
+            session.guard_empty()?;
+            session.set_role(role);
+        } else {
+            self.role = Some(role);
+        }
+        Ok(())
+    }
+
+    pub fn exit_role(&mut self) -> Result<()> {
+        if let Some(session) = self.session.as_mut() {
+            session.guard_empty()?;
+            session.clear_role();
+        } else if self.role.is_some() {
+            self.role = None;
+        }
+        Ok(())
+    }
+
+    pub fn exit_session(&mut self) -> Result<()> {
+        if let Some(mut session) = self.session.take() {
+            let sessions_dir = self.sessions_dir();
+            session.exit(&sessions_dir, self.working_mode.is_repl())?;
+            self.discontinuous_last_message();
+        }
+        Ok(())
+    }
+
+    pub fn save_session(&mut self, name: Option<&str>) -> Result<()> {
+        let session_name = match &self.session {
+            Some(session) => match name {
+                Some(v) => v.to_string(),
+                None => session
+                    .autoname()
+                    .unwrap_or_else(|| session.name())
+                    .to_string(),
+            },
+            None => bail!("No session"),
+        };
+        let session_path = self.session_file(&session_name);
+        if let Some(session) = self.session.as_mut() {
+            session.save(&session_name, &session_path, self.working_mode.is_repl())?;
+        }
+        Ok(())
+    }
+
+    pub fn empty_session(&mut self) -> Result<()> {
+        if let Some(session) = self.session.as_mut() {
+            if let Some(agent) = self.agent.as_ref() {
+                session.sync_agent(agent);
+            }
+            session.clear_messages();
+        } else {
+            bail!("No session")
+        }
+        self.discontinuous_last_message();
+        Ok(())
+    }
+
+    pub fn set_save_session_this_time(&mut self) -> Result<()> {
+        if let Some(session) = self.session.as_mut() {
+            session.set_save_session_this_time();
+        } else {
+            bail!("No session")
+        }
+        Ok(())
+    }
+
+    pub fn exit_rag(&mut self) -> Result<()> {
+        self.rag.take();
+        Ok(())
+    }
+
+    pub fn exit_agent_session(&mut self) -> Result<()> {
+        self.exit_session()?;
+        if let Some(agent) = self.agent.as_mut() {
+            agent.exit_session();
+            if self.working_mode.is_repl() {
+                self.init_agent_shared_variables()?;
+            }
+        }
+        Ok(())
+    }
+
+    pub fn before_chat_completion(&mut self, input: &Input) -> Result<()> {
+        self.last_message = Some(LastMessage::new(input.clone(), String::new()));
+        Ok(())
+    }
+
+    pub fn discontinuous_last_message(&mut self) {
+        if let Some(last_message) = self.last_message.as_mut() {
+            last_message.continuous = false;
+        }
+    }
+
+    pub fn init_agent_shared_variables(&mut self) -> Result<()> {
+        let agent = match self.agent.as_mut() {
+            Some(v) => v,
+            None => return Ok(()),
+        };
+        if !agent.defined_variables().is_empty() && agent.shared_variables().is_empty() {
+            let new_variables = Agent::init_agent_variables(
+                agent.defined_variables(),
+                self.agent_variables.as_ref(),
+                self.info_flag,
+            )?;
+            agent.set_shared_variables(new_variables);
+        }
+        if !self.info_flag {
+            agent.update_shared_dynamic_instructions(false)?;
+        }
+        Ok(())
+    }
+
+    pub fn init_agent_session_variables(&mut self, new_session: bool) -> Result<()> {
+        let (agent, session) = match (self.agent.as_mut(), self.session.as_mut()) {
+            (Some(agent), Some(session)) => (agent, session),
+            _ => return Ok(()),
+        };
+        if new_session {
+            let shared_variables = agent.shared_variables().clone();
+            let session_variables =
+                if !agent.defined_variables().is_empty() && shared_variables.is_empty() {
+                    let new_variables = Agent::init_agent_variables(
+                        agent.defined_variables(),
+                        self.agent_variables.as_ref(),
+                        self.info_flag,
+                    )?;
+                    agent.set_shared_variables(new_variables.clone());
+                    new_variables
+                } else {
+                    shared_variables
+                };
+            agent.set_session_variables(session_variables);
+            if !self.info_flag {
+                agent.update_session_dynamic_instructions(None)?;
+            }
+            session.sync_agent(agent);
+        } else {
+            let variables = session.agent_variables();
+            agent.set_session_variables(variables.clone());
+            agent.update_session_dynamic_instructions(Some(
+                session.agent_instructions().to_string(),
+            ))?;
+        }
+        Ok(())
+    }
+
+    pub fn current_model(&self) -> &Model {
+        if let Some(session) = self.session.as_ref() {
+            session.model()
+        } else if let Some(agent) = self.agent.as_ref() {
+            agent.model()
+        } else if let Some(role) = self.role.as_ref() {
+            role.model()
+        } else {
+            &self.model
+        }
+    }
+
+    pub fn extract_role(&self, app: &AppConfig) -> Role {
+        let mut role = if let Some(session) = self.session.as_ref() {
+            session.to_role()
+        } else if let Some(agent) = self.agent.as_ref() {
+            agent.to_role()
+        } else if let Some(role) = self.role.as_ref() {
+            role.clone()
+        } else {
+            let mut role = Role::default();
+            role.batch_set(
+                &self.model,
+                app.temperature,
+                app.top_p,
+                app.enabled_tools.clone(),
+                app.enabled_mcp_servers.clone(),
+            );
+            role
+        };
+
+        if self.agent.is_none() && self.app.config.function_calling_support {
+            let config = self.auto_continue_config();
+            if config.enabled && config.inject_instructions {
+                role.append_to_prompt(prompts::DEFAULT_TODO_INSTRUCTIONS);
+            }
+        }
+
+        role
+    }
+
+    pub fn auto_continue_config(&self) -> AutoContinueConfig {
+        if let Some(agent) = &self.agent {
+            return AutoContinueConfig {
+                enabled: agent.auto_continue_enabled(),
+                max_continues: agent.max_auto_continues(),
+                inject_instructions: agent.inject_todo_instructions(),
+                continuation_prompt: agent.continuation_prompt_value(),
+            };
+        }
+        let app = &self.app.config;
+        let enabled = self
+            .session
+            .as_ref()
+            .and_then(|s| s.auto_continue())
+            .or_else(|| self.role.as_ref().and_then(|r| r.auto_continue()))
+            .unwrap_or(app.auto_continue);
+        let max = self
+            .session
+            .as_ref()
+            .and_then(|s| s.max_auto_continues())
+            .or_else(|| self.role.as_ref().and_then(|r| r.max_auto_continues()))
+            .unwrap_or(app.max_auto_continues);
+        let inject = self
+            .session
+            .as_ref()
+            .and_then(|s| s.inject_todo_instructions())
+            .or_else(|| {
+                self.role
+                    .as_ref()
+                    .and_then(|r| r.inject_todo_instructions())
+            })
+            .unwrap_or(app.inject_todo_instructions);
+        let prompt = self
+            .session
+            .as_ref()
+            .and_then(|s| s.continuation_prompt().map(|v| v.to_string()))
+            .or_else(|| {
+                self.role
+                    .as_ref()
+                    .and_then(|r| r.continuation_prompt().map(|v| v.to_string()))
+            })
+            .or_else(|| app.continuation_prompt.clone());
+        AutoContinueConfig {
+            enabled,
+            max_continues: max,
+            inject_instructions: inject,
+            continuation_prompt: prompt,
+        }
+    }
+
+    pub fn set_temperature_on_role_like(&mut self, value: Option<f64>) -> bool {
+        match self.role_like_mut() {
+            Some(role_like) => {
+                role_like.set_temperature(value);
+                true
+            }
+            None => false,
+        }
+    }
+
+    pub fn set_top_p_on_role_like(&mut self, value: Option<f64>) -> bool {
+        match self.role_like_mut() {
+            Some(role_like) => {
+                role_like.set_top_p(value);
+                true
+            }
+            None => false,
+        }
+    }
+
+    pub fn set_enabled_tools_on_role_like(&mut self, value: Option<String>) -> bool {
+        match self.role_like_mut() {
+            Some(role_like) => {
+                role_like.set_enabled_tools(value);
+                true
+            }
+            None => false,
+        }
+    }
+
+    pub fn set_enabled_mcp_servers_on_role_like(&mut self, value: Option<String>) -> bool {
+        match self.role_like_mut() {
+            Some(role_like) => {
+                role_like.set_enabled_mcp_servers(value);
+                true
+            }
+            None => false,
+        }
+    }
+
+    pub fn set_save_session_on_session(&mut self, value: Option<bool>) -> bool {
+        match self.session.as_mut() {
+            Some(session) => {
+                session.set_save_session(value);
+                true
+            }
+            None => false,
+        }
+    }
+
+    pub fn set_compression_threshold_on_session(&mut self, value: Option<usize>) -> bool {
+        match self.session.as_mut() {
+            Some(session) => {
+                session.set_compression_threshold(value);
+                true
+            }
+            None => false,
+        }
+    }
+
+    pub fn set_max_output_tokens_on_role_like(&mut self, value: Option<isize>) -> bool {
+        match self.role_like_mut() {
+            Some(role_like) => {
+                let mut model = role_like.model().clone();
+                model.set_max_tokens(value, true);
+                role_like.set_model(model);
+                true
+            }
+            None => false,
+        }
+    }
+
+    pub fn save_message(&mut self, app: &AppConfig, input: &Input, output: &str) -> Result<()> {
+        let mut input = input.clone();
+        input.clear_patch();
+        if let Some(session) = input.session_mut(&mut self.session) {
+            session.add_message(&input, output)?;
+            return Ok(());
+        }
+
+        if !app.save {
+            return Ok(());
+        }
+        let mut file = self.open_message_file()?;
+        if output.is_empty() && input.tool_calls().is_none() {
+            return Ok(());
+        }
+        let now = now();
+        let summary = input.summary();
+        let raw_input = input.raw();
+        let scope = if self.agent.is_none() {
+            let role_name = if input.role().is_derived() {
+                None
+            } else {
+                Some(input.role().name())
+            };
+            match (role_name, input.rag_name()) {
+                (Some(role), Some(rag_name)) => format!(" ({role}#{rag_name})"),
+                (Some(role), _) => format!(" ({role})"),
+                (None, Some(rag_name)) => format!(" (#{rag_name})"),
+                _ => String::new(),
+            }
+        } else {
+            String::new()
+        };
+        let tool_calls = match input.tool_calls() {
+            Some(MessageContentToolCalls {
+                tool_results, text, ..
+            }) => {
+                let mut lines = vec!["<tool_calls>".to_string()];
+                if !text.is_empty() {
+                    lines.push(text.clone());
+                }
+                lines.push(serde_json::to_string(&tool_results).unwrap_or_default());
+                lines.push("</tool_calls>\n".to_string());
+                lines.join("\n")
+            }
+            None => String::new(),
+        };
+        let output = format!(
+            "# CHAT: {summary} [{now}]{scope}\n{raw_input}\n--------\n{tool_calls}{output}\n--------\n\n",
+        );
+        file.write_all(output.as_bytes())
+            .with_context(|| "Failed to save message")
+    }
+
+    fn open_message_file(&self) -> Result<File> {
+        let path = self.messages_file();
+        ensure_parent_exists(&path)?;
+        OpenOptions::new()
+            .create(true)
+            .append(true)
+            .open(&path)
+            .with_context(|| format!("Failed to create/append {}", path.display()))
+    }
+
+    pub fn after_chat_completion(
+        &mut self,
+        app: &AppConfig,
+        input: &Input,
+        output: &str,
+        tool_results: &[ToolResult],
+    ) -> Result<()> {
+        if !tool_results.is_empty() {
+            return Ok(());
+        }
+        self.last_message = Some(LastMessage::new(input.clone(), output.to_string()));
+        if !app.dry_run {
+            self.save_message(app, input, output)?;
+        }
+        Ok(())
+    }
+
+    pub fn sysinfo(&self, app: &AppConfig) -> Result<String> {
+        let display_path = |path: &Path| path.display().to_string();
+        let wrap = app
+            .wrap
+            .clone()
+            .map_or_else(|| String::from("no"), |v| v.to_string());
+        let (rag_reranker_model, rag_top_k) = match &self.rag {
+            Some(rag) => rag.get_config(),
+            None => (app.rag_reranker_model.clone(), app.rag_top_k),
+        };
+        let role = self.extract_role(app);
+        let mut items = vec![
+            ("model", role.model().id()),
+            (
+                "temperature",
+                super::format_option_value(&role.temperature()),
+            ),
+            ("top_p", super::format_option_value(&role.top_p())),
+            (
+                "enabled_tools",
+                super::format_option_value(&role.enabled_tools()),
+            ),
+            (
+                "enabled_mcp_servers",
+                super::format_option_value(&role.enabled_mcp_servers()),
+            ),
+            (
+                "max_output_tokens",
+                role.model()
+                    .max_tokens_param()
+                    .map(|v| format!("{v} (current model)"))
+                    .unwrap_or_else(|| "null".into()),
+            ),
+            (
+                "save_session",
+                super::format_option_value(&app.save_session),
+            ),
+            (
+                "compression_threshold",
+                app.compression_threshold.to_string(),
+            ),
+            (
+                "rag_reranker_model",
+                super::format_option_value(&rag_reranker_model),
+            ),
+            ("rag_top_k", rag_top_k.to_string()),
+            ("dry_run", app.dry_run.to_string()),
+            (
+                "function_calling_support",
+                app.function_calling_support.to_string(),
+            ),
+            ("mcp_server_support", app.mcp_server_support.to_string()),
+            ("auto_continue", app.auto_continue.to_string()),
+            ("max_auto_continues", app.max_auto_continues.to_string()),
+            ("stream", app.stream.to_string()),
+            ("save", app.save.to_string()),
+            ("keybindings", app.keybindings.clone()),
+            ("wrap", wrap),
+            ("wrap_code", app.wrap_code.to_string()),
+            ("highlight", app.highlight.to_string()),
+            ("theme", super::format_option_value(&app.theme)),
+            ("config_file", display_path(&paths::config_file())),
+            ("env_file", display_path(&paths::env_file())),
+            ("agents_dir", display_path(&paths::agents_data_dir())),
+            ("roles_dir", display_path(&paths::roles_dir())),
+            ("sessions_dir", display_path(&self.sessions_dir())),
+            ("rags_dir", display_path(&paths::rags_dir())),
+            ("macros_dir", display_path(&paths::macros_dir())),
+            ("functions_dir", display_path(&paths::functions_dir())),
+            ("messages_file", display_path(&self.messages_file())),
+            (
+                "vault_password_file",
+                display_path(&app.vault_password_file()),
+            ),
+        ];
+        if let Ok((_, Some(log_path))) = paths::log_config() {
+            items.push(("log_path", display_path(&log_path)));
+        }
+        let output = items
+            .iter()
+            .map(|(name, value)| format!("{name:<30}{value}\n"))
+            .collect::<Vec<String>>()
+            .join("");
+        Ok(output)
+    }
+
+    pub fn info(&self, app: &AppConfig) -> Result<String> {
+        if let Some(agent) = &self.agent {
+            let output = agent.export()?;
+            if let Some(session) = &self.session {
+                let session = session
+                    .export()?
+                    .split('\n')
+                    .map(|v| format!("  {v}"))
+                    .collect::<Vec<_>>()
+                    .join("\n");
+                Ok(format!("{output}session:\n{session}"))
+            } else {
+                Ok(output)
+            }
+        } else if let Some(session) = &self.session {
+            session.export()
+        } else if let Some(role) = &self.role {
+            Ok(role.export())
+        } else if let Some(rag) = &self.rag {
+            rag.export()
+        } else {
+            self.sysinfo(app)
+        }
+    }
+
+    pub fn session_info(&self, app: &AppConfig) -> Result<String> {
+        if let Some(session) = &self.session {
+            let render_options = app.render_options()?;
+            let mut markdown_render = crate::render::MarkdownRender::init(render_options)?;
+            let agent_info: Option<(String, Vec<String>)> = self.agent.as_ref().map(|agent| {
+                let functions = agent
+                    .functions()
+                    .declarations()
+                    .iter()
+                    .filter_map(|v| if v.agent { Some(v.name.clone()) } else { None })
+                    .collect();
+                (agent.name().to_string(), functions)
+            });
+            session.render(&mut markdown_render, &agent_info)
+        } else {
+            bail!("No session")
+        }
+    }
+
+    pub fn generate_prompt_context(&self, app: &AppConfig) -> HashMap<&str, String> {
+        let mut output = HashMap::new();
+        let role = self.extract_role(app);
+        output.insert("model", role.model().id());
+        output.insert("client_name", role.model().client_name().to_string());
+        output.insert("model_name", role.model().name().to_string());
+        output.insert(
+            "max_input_tokens",
+            role.model()
+                .max_input_tokens()
+                .unwrap_or_default()
+                .to_string(),
+        );
+        if let Some(temperature) = role.temperature()
+            && temperature != 0.0
+        {
+            output.insert("temperature", temperature.to_string());
+        }
+        if let Some(top_p) = role.top_p()
+            && top_p != 0.0
+        {
+            output.insert("top_p", top_p.to_string());
+        }
+        if app.dry_run {
+            output.insert("dry_run", "true".to_string());
+        }
+        if app.stream {
+            output.insert("stream", "true".to_string());
+        }
+        if app.save {
+            output.insert("save", "true".to_string());
+        }
+        if let Some(wrap) = &app.wrap
+            && wrap != "no"
+        {
+            output.insert("wrap", wrap.clone());
+        }
+        if !role.is_derived() {
+            output.insert("role", role.name().to_string());
+        }
+        if let Some(session) = &self.session {
+            output.insert("session", session.name().to_string());
+            if let Some(autoname) = session.autoname() {
+                output.insert("session_autoname", autoname.to_string());
+            }
+            output.insert("dirty", session.dirty().to_string());
+            let (tokens, percent) = session.tokens_usage();
+            output.insert("consume_tokens", tokens.to_string());
+            output.insert("consume_percent", percent.to_string());
+            output.insert("user_messages_len", session.user_messages_len().to_string());
+        }
+        if let Some(rag) = &self.rag {
+            output.insert("rag", rag.name().to_string());
+        }
+        if let Some(agent) = &self.agent {
+            output.insert("agent", agent.name().to_string());
+        }
+
+        if app.highlight {
+            output.insert("color.reset", "\u{1b}[0m".to_string());
+            output.insert("color.black", "\u{1b}[30m".to_string());
+            output.insert("color.dark_gray", "\u{1b}[90m".to_string());
+            output.insert("color.red", "\u{1b}[31m".to_string());
+            output.insert("color.light_red", "\u{1b}[91m".to_string());
+            output.insert("color.green", "\u{1b}[32m".to_string());
+            output.insert("color.light_green", "\u{1b}[92m".to_string());
+            output.insert("color.yellow", "\u{1b}[33m".to_string());
+            output.insert("color.light_yellow", "\u{1b}[93m".to_string());
+            output.insert("color.blue", "\u{1b}[34m".to_string());
+            output.insert("color.light_blue", "\u{1b}[94m".to_string());
+            output.insert("color.purple", "\u{1b}[35m".to_string());
+            output.insert("color.light_purple", "\u{1b}[95m".to_string());
+            output.insert("color.magenta", "\u{1b}[35m".to_string());
+            output.insert("color.light_magenta", "\u{1b}[95m".to_string());
+            output.insert("color.cyan", "\u{1b}[36m".to_string());
+            output.insert("color.light_cyan", "\u{1b}[96m".to_string());
+            output.insert("color.white", "\u{1b}[37m".to_string());
+            output.insert("color.light_gray", "\u{1b}[97m".to_string());
+        }
+
+        output
+    }
+
+    pub fn render_prompt_left(&self, app: &AppConfig) -> String {
+        let variables = self.generate_prompt_context(app);
+        let left_prompt = app.left_prompt.as_deref().unwrap_or(LEFT_PROMPT);
+        render_prompt(left_prompt, &variables)
+    }
+
+    pub fn render_prompt_right(&self, app: &AppConfig) -> String {
+        let variables = self.generate_prompt_context(app);
+        let right_prompt = app.right_prompt.as_deref().unwrap_or(RIGHT_PROMPT);
+        render_prompt(right_prompt, &variables)
+    }
+
+    pub fn select_enabled_functions(&self, role: &Role) -> Vec<FunctionDeclaration> {
+        let app = self.app.config.as_ref();
+        let mut functions = vec![];
+        if app.function_calling_support {
+            // Compute the set of tool names enabled by the role filter, drawn
+            // from BOTH the tool_scope pool and the agent's pool so that an
+            // explicit `enabled_tools` list (e.g. from a graph LLM node) can
+            // narrow the agent's own custom tools too.
+            let role_filter: Option<HashSet<String>> = role.enabled_tools().map(|enabled_tools| {
+                let mut declaration_names: HashSet<String> = self
+                    .tool_scope
+                    .functions
+                    .declarations()
+                    .iter()
+                    .filter(|v| {
+                        !v.name.starts_with(MCP_INVOKE_META_FUNCTION_NAME_PREFIX)
+                            && !v.name.starts_with(MCP_SEARCH_META_FUNCTION_NAME_PREFIX)
+                            && !v.name.starts_with(MCP_DESCRIBE_META_FUNCTION_NAME_PREFIX)
+                    })
+                    .map(|v| v.name.to_string())
+                    .collect();
+
+                if let Some(agent) = &self.agent {
+                    declaration_names.extend(
+                        agent
+                            .functions()
+                            .declarations()
+                            .iter()
+                            .filter(|v| {
+                                !v.name.starts_with(MCP_INVOKE_META_FUNCTION_NAME_PREFIX)
+                                    && !v.name.starts_with(MCP_SEARCH_META_FUNCTION_NAME_PREFIX)
+                                    && !v.name.starts_with(MCP_DESCRIBE_META_FUNCTION_NAME_PREFIX)
+                            })
+                            .map(|v| v.name.to_string()),
+                    );
+                }
+
+                let mut tool_names: HashSet<String> = Default::default();
+                if enabled_tools == "all" {
+                    tool_names.extend(declaration_names);
+                } else {
+                    for item in enabled_tools.split(',') {
+                        let item = item.trim();
+                        if item.is_empty() {
+                            continue;
+                        }
+
+                        if let Some(values) = app.mapping_tools.get(item) {
+                            tool_names.extend(
+                                values
+                                    .split(',')
+                                    .map(|v| v.to_string())
+                                    .filter(|v| declaration_names.contains(v)),
+                            )
+                        } else if declaration_names.contains(item) {
+                            tool_names.insert(item.to_string());
+                        }
+                    }
+                }
+                tool_names
+            });
+
+            if let Some(ref tool_names) = role_filter {
+                functions = self
+                    .tool_scope
+                    .functions
+                    .declarations()
+                    .iter()
+                    .filter_map(|v| {
+                        if tool_names.contains(&v.name) {
+                            Some(v.clone())
+                        } else {
+                            None
+                        }
+                    })
+                    .collect();
+            }
+
+            if self.agent.is_none() {
+                let existing: HashSet<String> = functions.iter().map(|f| f.name.clone()).collect();
+                let builtin_functions: Vec<FunctionDeclaration> = self
+                    .tool_scope
+                    .functions
+                    .declarations()
+                    .iter()
+                    .filter(|v| {
+                        v.name.starts_with(USER_FUNCTION_PREFIX) && !existing.contains(&v.name)
+                    })
+                    .cloned()
+                    .collect();
+                functions.extend(builtin_functions);
+            }
+
+            if let Some(agent) = &self.agent {
+                let mut agent_functions: Vec<FunctionDeclaration> = agent
+                    .functions()
+                    .declarations()
+                    .to_vec()
+                    .into_iter()
+                    .filter(|v| {
+                        !v.name.starts_with(MCP_INVOKE_META_FUNCTION_NAME_PREFIX)
+                            && !v.name.starts_with(MCP_SEARCH_META_FUNCTION_NAME_PREFIX)
+                            && !v.name.starts_with(MCP_DESCRIBE_META_FUNCTION_NAME_PREFIX)
+                    })
+                    .collect();
+
+                if let Some(ref tool_names) = role_filter {
+                    agent_functions.retain(|v| tool_names.contains(&v.name));
+                }
+
+                let tool_names: HashSet<String> = agent_functions
+                    .iter()
+                    .filter_map(|v| {
+                        if v.agent {
+                            None
+                        } else {
+                            Some(v.name.to_string())
+                        }
+                    })
+                    .collect();
+                agent_functions.extend(
+                    functions
+                        .into_iter()
+                        .filter(|v| !tool_names.contains(&v.name)),
+                );
+                functions = agent_functions;
+            }
+        }
+
+        functions
+    }
+
+    pub fn select_enabled_mcp_servers(&self, role: &Role) -> Vec<FunctionDeclaration> {
+        let app = self.app.config.as_ref();
+        let mut mcp_functions = vec![];
+        if app.mcp_server_support {
+            let role_filter: Option<HashSet<String>> =
+                role.enabled_mcp_servers().map(|enabled_mcp_servers| {
+                    let mut mcp_declaration_names: HashSet<String> = self
+                        .tool_scope
+                        .functions
+                        .declarations()
+                        .iter()
+                        .filter(|v| {
+                            v.name.starts_with(MCP_INVOKE_META_FUNCTION_NAME_PREFIX)
+                                || v.name.starts_with(MCP_SEARCH_META_FUNCTION_NAME_PREFIX)
+                                || v.name.starts_with(MCP_DESCRIBE_META_FUNCTION_NAME_PREFIX)
+                        })
+                        .map(|v| v.name.to_string())
+                        .collect();
+                    if let Some(agent) = &self.agent {
+                        mcp_declaration_names.extend(
+                            agent
+                                .functions()
+                                .declarations()
+                                .iter()
+                                .filter(|v| {
+                                    v.name.starts_with(MCP_INVOKE_META_FUNCTION_NAME_PREFIX)
+                                        || v.name.starts_with(MCP_SEARCH_META_FUNCTION_NAME_PREFIX)
+                                        || v.name
+                                            .starts_with(MCP_DESCRIBE_META_FUNCTION_NAME_PREFIX)
+                                })
+                                .map(|v| v.name.to_string()),
+                        );
+                    }
+
+                    let mut server_names: HashSet<String> = Default::default();
+                    if enabled_mcp_servers == "all" {
+                        server_names.extend(mcp_declaration_names);
+                    } else {
+                        for item in enabled_mcp_servers.split(',') {
+                            let item = item.trim();
+                            if item.is_empty() {
+                                continue;
+                            }
+
+                            let item_invoke_name =
+                                format!("{}_{item}", MCP_INVOKE_META_FUNCTION_NAME_PREFIX);
+                            let item_search_name =
+                                format!("{}_{item}", MCP_SEARCH_META_FUNCTION_NAME_PREFIX);
+                            let item_describe_name =
+                                format!("{}_{item}", MCP_DESCRIBE_META_FUNCTION_NAME_PREFIX);
+                            if let Some(values) = app.mapping_mcp_servers.get(item) {
+                                server_names.extend(
+                                    values
+                                        .split(',')
+                                        .flat_map(|v| {
+                                            vec![
+                                                format!(
+                                                    "{}_{}",
+                                                    MCP_INVOKE_META_FUNCTION_NAME_PREFIX,
+                                                    v.to_string()
+                                                ),
+                                                format!(
+                                                    "{}_{}",
+                                                    MCP_SEARCH_META_FUNCTION_NAME_PREFIX,
+                                                    v.to_string()
+                                                ),
+                                                format!(
+                                                    "{}_{}",
+                                                    MCP_DESCRIBE_META_FUNCTION_NAME_PREFIX,
+                                                    v.to_string()
+                                                ),
+                                            ]
+                                        })
+                                        .filter(|v| mcp_declaration_names.contains(v)),
+                                )
+                            } else if mcp_declaration_names.contains(&item_invoke_name) {
+                                server_names.insert(item_invoke_name);
+                                server_names.insert(item_search_name);
+                                server_names.insert(item_describe_name);
+                            }
+                        }
+                    }
+                    server_names
+                });
+
+            if let Some(ref server_names) = role_filter {
+                mcp_functions = self
+                    .tool_scope
+                    .functions
+                    .declarations()
+                    .iter()
+                    .filter_map(|v| {
+                        if server_names.contains(&v.name) {
+                            Some(v.clone())
+                        } else {
+                            None
+                        }
+                    })
+                    .collect();
+            }
+
+            if let Some(agent) = &self.agent {
+                let mut agent_functions: Vec<FunctionDeclaration> = agent
+                    .functions()
+                    .declarations()
+                    .to_vec()
+                    .into_iter()
+                    .filter(|v| {
+                        v.name.starts_with(MCP_INVOKE_META_FUNCTION_NAME_PREFIX)
+                            || v.name.starts_with(MCP_SEARCH_META_FUNCTION_NAME_PREFIX)
+                            || v.name.starts_with(MCP_DESCRIBE_META_FUNCTION_NAME_PREFIX)
+                    })
+                    .collect();
+
+                if let Some(ref server_names) = role_filter {
+                    agent_functions.retain(|v| server_names.contains(&v.name));
+                }
+
+                let tool_names: HashSet<String> = agent_functions
+                    .iter()
+                    .filter_map(|v| {
+                        if v.agent {
+                            None
+                        } else {
+                            Some(v.name.to_string())
+                        }
+                    })
+                    .collect();
+                agent_functions.extend(
+                    mcp_functions
+                        .into_iter()
+                        .filter(|v| !tool_names.contains(&v.name)),
+                );
+                mcp_functions = agent_functions;
+            }
+        }
+
+        mcp_functions
+    }
+
+    pub fn select_functions(&self, role: &Role) -> Option<Vec<FunctionDeclaration>> {
+        let mut functions = vec![];
+        functions.extend(self.select_enabled_functions(role));
+        functions.extend(self.select_enabled_mcp_servers(role));
+
+        if functions.is_empty() {
+            None
+        } else {
+            Some(functions)
+        }
+    }
+
+    pub fn retrieve_role(&self, app: &AppConfig, name: &str) -> Result<Role> {
+        let names = paths::list_roles(false);
+        let mut role = if names.contains(&name.to_string()) {
+            let path = paths::role_file(name);
+            let content = read_to_string(&path)?;
+            Role::new(name, &content)
+        } else {
+            Role::builtin(name)?
+        };
+        let current_model = self.current_model().clone();
+        match role.model_id() {
+            Some(model_id) => {
+                if current_model.id() != model_id {
+                    let model = Model::retrieve_model(app, model_id, ModelType::Chat)?;
+                    role.set_model(model);
+                } else {
+                    role.set_model(current_model);
+                }
+            }
+            None => {
+                role.set_model(current_model);
+                if role.temperature().is_none() {
+                    role.set_temperature(app.temperature);
+                }
+                if role.top_p().is_none() {
+                    role.set_top_p(app.top_p);
+                }
+            }
+        }
+        Ok(role)
+    }
+
+    /// Returns `Ok(true)` if a role-like was mutated, `Ok(false)` if
+    /// the model was set on `ctx.model` directly (no role-like active).
+    pub fn set_model_on_role_like(&mut self, app: &AppConfig, model_id: &str) -> Result<bool> {
+        let model = Model::retrieve_model(app, model_id, ModelType::Chat)?;
+        match self.role_like_mut() {
+            Some(role_like) => {
+                role_like.set_model(model);
+                Ok(true)
+            }
+            None => {
+                self.model = model;
+                Ok(false)
+            }
+        }
+    }
+
+    #[allow(dead_code)]
+    pub fn reload_current_model(&mut self, app: &AppConfig, model_id: &str) -> Result<()> {
+        let model = Model::retrieve_model(app, model_id, ModelType::Chat)?;
+        self.model = model;
+        Ok(())
+    }
+
+    pub fn use_prompt(&mut self, _app: &AppConfig, prompt: &str) -> Result<()> {
+        let mut role = Role::new(TEMP_ROLE_NAME, prompt);
+        role.set_model(self.current_model().clone());
+        self.use_role_obj(role)
+    }
+
+    pub fn edit_config(&self) -> Result<()> {
+        let config_path = paths::config_file();
+        let editor = self.app.config.editor()?;
+        edit_file(&editor, &config_path)?;
+        println!(
+            "NOTE: Remember to restart {} if there are changes made to '{}'",
+            env!("CARGO_CRATE_NAME"),
+            config_path.display(),
+        );
+        Ok(())
+    }
+
+    pub fn edit_mcp_config(&self) -> Result<()> {
+        let mcp_path = paths::mcp_config_file();
+        let editor = self.app.config.editor()?;
+        edit_file(&editor, &mcp_path)?;
+        println!(
+            "NOTE: Remember to restart {} for changes to '{}' to take effect",
+            env!("CARGO_CRATE_NAME"),
+            mcp_path.display(),
+        );
+
+        Ok(())
+    }
+
+    pub fn new_role(&self, app: &AppConfig, name: &str) -> Result<()> {
+        if self.macro_flag {
+            bail!("No role");
+        }
+        let ans = Confirm::new("Create a new role?")
+            .with_default(true)
+            .prompt()?;
+        if ans {
+            self.upsert_role(app, name)?;
+        } else {
+            bail!("No role");
+        }
+        Ok(())
+    }
+
+    pub fn save_role(&mut self, name: Option<&str>) -> Result<()> {
+        let mut role_name = match &self.role {
+            Some(role) => {
+                if role.has_args() {
+                    bail!("Unable to save the role with arguments (whose name contains '#')")
+                }
+                match name {
+                    Some(v) => v.to_string(),
+                    None => role.name().to_string(),
+                }
+            }
+            None => bail!("No role"),
+        };
+        if role_name == TEMP_ROLE_NAME {
+            role_name = Text::new("Role name:")
+                .with_validator(|input: &str| {
+                    let input = input.trim();
+                    if input.is_empty() {
+                        Ok(Validation::Invalid("This name is required".into()))
+                    } else if input == TEMP_ROLE_NAME {
+                        Ok(Validation::Invalid("This name is reserved".into()))
+                    } else {
+                        Ok(Validation::Valid)
+                    }
+                })
+                .prompt()?;
+        }
+        let role_path = paths::role_file(&role_name);
+        if let Some(role) = self.role.as_mut() {
+            role.save(&role_name, &role_path, self.working_mode.is_repl())?;
+        }
+        Ok(())
+    }
+
+    pub fn edit_session(&mut self, app: &AppConfig) -> Result<()> {
+        let name = match &self.session {
+            Some(session) => session.name().to_string(),
+            None => bail!("No session"),
+        };
+        let session_path = self.session_file(&name);
+        self.save_session(Some(&name))?;
+        let editor = app.editor()?;
+        edit_file(&editor, &session_path).with_context(|| {
+            format!(
+                "Failed to edit '{}' with '{}'",
+                session_path.display(),
+                editor
+            )
+        })?;
+        self.session = Some(Session::load_from_ctx(self, app, &name, &session_path)?);
+        self.discontinuous_last_message();
+        Ok(())
+    }
+
+    pub fn edit_agent_config(&self, app: &AppConfig) -> Result<()> {
+        let agent_name = match &self.agent {
+            Some(agent) => agent.name(),
+            None => bail!("No agent"),
+        };
+        let config_path = paths::agent_config_file(agent_name);
+        let graph_path = paths::agent_graph_file(agent_name);
+        let target_path = if !config_path.exists() && graph_path.exists() {
+            graph_path
+        } else {
+            config_path
+        };
+
+        ensure_parent_exists(&target_path)?;
+        if !target_path.exists() {
+            fs::write(
+                &target_path,
+                "# see https://github.com/Dark-Alex-17/loki/blob/main/config.agent.example.yaml\n",
+            )
+            .with_context(|| format!("Failed to write to '{}'", target_path.display()))?;
+        }
+
+        let editor = app.editor()?;
+        edit_file(&editor, &target_path)?;
+        println!(
+            "NOTE: Remember to reload the agent if there are changes made to '{}'",
+            target_path.display()
+        );
+
+        Ok(())
+    }
+
+    pub fn new_macro(&self, app: &AppConfig, name: &str) -> Result<()> {
+        if self.macro_flag {
+            bail!("No macro");
+        }
+        let ans = Confirm::new("Create a new macro?")
+            .with_default(true)
+            .prompt()?;
+        if ans {
+            let macro_path = paths::macro_file(name);
+            ensure_parent_exists(&macro_path)?;
+            let editor = app.editor()?;
+            edit_file(&editor, &macro_path)?;
+        } else {
+            bail!("No macro");
+        }
+        Ok(())
+    }
+
+    pub fn delete(&self, kind: &str) -> Result<()> {
+        let (dir, file_ext) = match kind {
+            "role" => (paths::roles_dir(), Some(".md")),
+            "session" => (self.sessions_dir(), Some(".yaml")),
+            "rag" => (paths::rags_dir(), Some(".yaml")),
+            "macro" => (paths::macros_dir(), Some(".yaml")),
+            "agent-data" => (paths::agents_data_dir(), None),
+            _ => bail!("Unknown kind '{kind}'"),
+        };
+        let names = match read_dir(&dir) {
+            Ok(rd) => {
+                let mut names = vec![];
+                for entry in rd.flatten() {
+                    let name = entry.file_name();
+                    match file_ext {
+                        Some(file_ext) => {
+                            if let Some(name) = name.to_string_lossy().strip_suffix(file_ext) {
+                                names.push(name.to_string());
+                            }
+                        }
+                        None => {
+                            if entry.path().is_dir() {
+                                names.push(name.to_string_lossy().to_string());
+                            }
+                        }
+                    }
+                }
+                names.sort_unstable();
+                names
+            }
+            Err(_) => vec![],
+        };
+
+        if names.is_empty() {
+            bail!("No {kind} to delete")
+        }
+
+        let select_names = MultiSelect::new(&format!("Select {kind} to delete:"), names)
+            .with_validator(|list: &[ListOption<&String>]| {
+                if list.is_empty() {
+                    Ok(Validation::Invalid(
+                        "At least one item must be selected".into(),
+                    ))
+                } else {
+                    Ok(Validation::Valid)
+                }
+            })
+            .prompt()?;
+
+        for name in select_names {
+            match file_ext {
+                Some(ext) => {
+                    let path = dir.join(format!("{name}{ext}"));
+                    remove_file(&path).with_context(|| {
+                        format!("Failed to delete {kind} at '{}'", path.display())
+                    })?;
+                }
+                None => {
+                    let path = dir.join(name);
+                    remove_dir_all(&path).with_context(|| {
+                        format!("Failed to delete {kind} at '{}'", path.display())
+                    })?;
+                }
+            }
+        }
+        println!("✓ Successfully deleted {kind}.");
+        Ok(())
+    }
+
+    pub fn rag_sources(&self) -> Result<String> {
+        match self.rag.as_ref() {
+            Some(rag) => match rag.get_last_sources() {
+                Some(v) => Ok(v),
+                None => bail!("No sources"),
+            },
+            None => bail!("No RAG"),
+        }
+    }
+
+    pub async fn update(&mut self, data: &str, abort_signal: AbortSignal) -> Result<()> {
+        let (key, raw_value) = match data.split_once(char::is_whitespace) {
+            Some((k, v)) => (k, v.trim()),
+            None => bail!("Usage: .set <key> <value>. If value is null, unset key."),
+        };
+
+        if raw_value.is_empty() {
+            bail!("Usage: .set <key> <value>. If value is null, unset key.");
+        }
+
+        let value = match key {
+            "continuation_prompt" => raw_value,
+            _ => {
+                if raw_value.contains(char::is_whitespace) {
+                    bail!("Usage: .set <key> <value>. If value is null, unset key.");
+                }
+                raw_value
+            }
+        };
+        match key {
+            "temperature" => {
+                let value = super::parse_value(value)?;
+                if !self.set_temperature_on_role_like(value) {
+                    self.update_app_config(|app| app.temperature = value);
+                }
+            }
+            "top_p" => {
+                let value = super::parse_value(value)?;
+                if !self.set_top_p_on_role_like(value) {
+                    self.update_app_config(|app| app.top_p = value);
+                }
+            }
+            "enabled_tools" => {
+                let value = super::parse_value(value)?;
+                if !self.set_enabled_tools_on_role_like(value.clone()) {
+                    self.update_app_config(|app| app.enabled_tools = value);
+                }
+            }
+            "enabled_mcp_servers" => {
+                let value: Option<String> = super::parse_value(value)?;
+                if let Some(servers) = value.as_ref() {
+                    let Some(mcp_config) = &self.app.mcp_config else {
+                        bail!(
+                            "No MCP servers are configured. Please configure MCP servers first before setting 'enabled_mcp_servers'."
+                        );
+                    };
+                    if mcp_config.mcp_servers.is_empty() {
+                        bail!(
+                            "No MCP servers are configured. Please configure MCP servers first before setting 'enabled_mcp_servers'."
+                        );
+                    }
+
+                    if !servers.split(',').all(|s| {
+                        let server = s.trim();
+                        server == "all" || mcp_config.mcp_servers.contains_key(server)
+                    }) {
+                        bail!(
+                            "Some of the specified MCP servers in 'enabled_mcp_servers' are not fully configured. Please check your MCP server configuration."
+                        );
+                    }
+                }
+                if !self.set_enabled_mcp_servers_on_role_like(value.clone()) {
+                    self.update_app_config(|app| app.enabled_mcp_servers = value.clone());
+                }
+                if self.app.config.mcp_server_support {
+                    let app = Arc::clone(&self.app.config);
+                    self.bootstrap_tools(app.as_ref(), true, abort_signal.clone())
+                        .await?;
+                }
+            }
+            "max_output_tokens" => {
+                let value = super::parse_value(value)?;
+                if !self.set_max_output_tokens_on_role_like(value) {
+                    self.model.set_max_tokens(value, true);
+                }
+            }
+            "save_session" => {
+                let value = super::parse_value(value)?;
+                if !self.set_save_session_on_session(value) {
+                    self.update_app_config(|app| app.save_session = value);
+                }
+            }
+            "compression_threshold" => {
+                let value = super::parse_value(value)?;
+                if !self.set_compression_threshold_on_session(value) {
+                    self.update_app_config(|app| {
+                        app.compression_threshold = value.unwrap_or_default();
+                    });
+                }
+            }
+            "rag_reranker_model" => {
+                let value = super::parse_value(value)?;
+                let app = Arc::clone(&self.app.config);
+                if !self.set_rag_reranker_model(app.as_ref(), value.clone())? {
+                    self.update_app_config(|app| app.rag_reranker_model = value);
+                }
+            }
+            "rag_top_k" => {
+                let value = value.parse().with_context(|| "Invalid value")?;
+                if !self.set_rag_top_k(value)? {
+                    self.update_app_config(|app| app.rag_top_k = value);
+                }
+            }
+            "dry_run" => {
+                let value = value.parse().with_context(|| "Invalid value")?;
+                self.update_app_config(|app| app.dry_run = value);
+            }
+            "function_calling_support" => {
+                let value = value.parse().with_context(|| "Invalid value")?;
+                if value && self.tool_scope.functions.is_empty() {
+                    bail!("Function calling cannot be enabled because no functions are installed.")
+                }
+                self.update_app_config(|app| app.function_calling_support = value);
+            }
+            "mcp_server_support" => {
+                let value = value.parse().with_context(|| "Invalid value")?;
+                self.update_app_config(|app| app.mcp_server_support = value);
+                let app = Arc::clone(&self.app.config);
+                self.bootstrap_tools(app.as_ref(), value, abort_signal.clone())
+                    .await?;
+            }
+            "stream" => {
+                let value = value.parse().with_context(|| "Invalid value")?;
+                self.update_app_config(|app| app.stream = value);
+            }
+            "save" => {
+                let value = value.parse().with_context(|| "Invalid value")?;
+                self.update_app_config(|app| app.save = value);
+            }
+            "highlight" => {
+                let value = value.parse().with_context(|| "Invalid value")?;
+                self.update_app_config(|app| app.highlight = value);
+            }
+            "auto_continue" => {
+                let value: bool = value.parse().with_context(|| "Invalid value")?;
+                if value && !self.app.config.function_calling_support {
+                    bail!(
+                        "Cannot enable auto_continue: function calling is disabled. Set 'function_calling_support: true' first."
+                    );
+                }
+                if let Some(session) = self.session.as_mut() {
+                    session.set_auto_continue(Some(value));
+                } else {
+                    self.update_app_config(|app| app.auto_continue = value);
+                }
+                if value
+                    && self.app.config.function_calling_support
+                    && !self.tool_scope.functions.contains("todo__init")
+                {
+                    self.tool_scope.functions.append_todo_functions();
+                }
+            }
+            "max_auto_continues" => {
+                let value: usize = value.parse().with_context(|| "Invalid value")?;
+                if let Some(session) = self.session.as_mut() {
+                    session.set_max_auto_continues(Some(value));
+                } else {
+                    self.update_app_config(|app| app.max_auto_continues = value);
+                }
+            }
+            "inject_todo_instructions" => {
+                let value: bool = value.parse().with_context(|| "Invalid value")?;
+                if let Some(session) = self.session.as_mut() {
+                    session.set_inject_todo_instructions(Some(value));
+                } else {
+                    self.update_app_config(|app| app.inject_todo_instructions = value);
+                }
+            }
+            "continuation_prompt" => {
+                let value: Option<String> = super::parse_value(value)?;
+                if let Some(session) = self.session.as_mut() {
+                    session.set_continuation_prompt(value);
+                } else {
+                    self.update_app_config(|app| app.continuation_prompt = value);
+                }
+            }
+            _ => bail!("Unknown key '{key}'"),
+        }
+        Ok(())
+    }
+
+    /// Returns `Ok(true)` if the active RAG was mutated, `Ok(false)` if
+    /// no RAG is active (caller should fall back to the `AppConfig` default).
+    pub fn set_rag_reranker_model(
+        &mut self,
+        app: &AppConfig,
+        value: Option<String>,
+    ) -> Result<bool> {
+        if let Some(id) = &value {
+            Model::retrieve_model(app, id, ModelType::Reranker)?;
+        }
+        match &self.rag {
+            Some(_) => {
+                let mut rag = self.rag.as_ref().expect("checked above").as_ref().clone();
+                rag.set_reranker_model(value)?;
+                self.rag = Some(Arc::new(rag));
+                Ok(true)
+            }
+            None => Ok(false),
+        }
+    }
+
+    pub fn set_rag_top_k(&mut self, value: usize) -> Result<bool> {
+        match &self.rag {
+            Some(_) => {
+                let mut rag = self.rag.as_ref().expect("checked above").as_ref().clone();
+                rag.set_top_k(value)?;
+                self.rag = Some(Arc::new(rag));
+                Ok(true)
+            }
+            None => Ok(false),
+        }
+    }
+
+    pub fn repl_complete(
+        &self,
+        cmd: &str,
+        args: &[&str],
+        _line: &str,
+    ) -> Vec<(String, Option<String>)> {
+        let app = self.app.config.as_ref();
+        let mut values: Vec<(String, Option<String>)> = vec![];
+        let filter = args.last().unwrap_or(&"");
+        if args.len() == 1 {
+            values = match cmd {
+                ".role" => super::map_completion_values(paths::list_roles(true)),
+                ".model" => list_models(app, ModelType::Chat)
+                    .into_iter()
+                    .map(|v| (v.id(), Some(v.description())))
+                    .collect(),
+                ".session" => {
+                    if args[0].starts_with("_/") {
+                        super::map_completion_values(
+                            self.list_autoname_sessions()
+                                .iter()
+                                .rev()
+                                .map(|v| format!("_/{v}"))
+                                .collect::<Vec<String>>(),
+                        )
+                    } else {
+                        super::map_completion_values(self.list_sessions())
+                    }
+                }
+                ".rag" => super::map_completion_values(paths::list_rags()),
+                ".agent" => super::map_completion_values(list_agents()),
+                ".install" => {
+                    let mut values: Vec<String> =
+                        AssetCategory::NAMES.iter().map(|s| s.to_string()).collect();
+                    values.push("remote".to_string());
+                    super::map_completion_values(values)
+                }
+                ".macro" => super::map_completion_values(paths::list_macros()),
+                ".starter" => match &self.agent {
+                    Some(agent) => agent
+                        .conversation_starters()
+                        .iter()
+                        .enumerate()
+                        .map(|(i, v)| ((i + 1).to_string(), Some(v.to_string())))
+                        .collect(),
+                    None => vec![],
+                },
+                ".set" => {
+                    let mut values = vec![
+                        "auto_continue",
+                        "continuation_prompt",
+                        "temperature",
+                        "top_p",
+                        "enabled_tools",
+                        "enabled_mcp_servers",
+                        "inject_todo_instructions",
+                        "max_auto_continues",
+                        "save_session",
+                        "compression_threshold",
+                        "rag_reranker_model",
+                        "rag_top_k",
+                        "max_output_tokens",
+                        "dry_run",
+                        "function_calling_support",
+                        "mcp_server_support",
+                        "stream",
+                        "save",
+                        "highlight",
+                    ];
+                    values.sort_unstable();
+                    values
+                        .into_iter()
+                        .map(|v| (format!("{v} "), None))
+                        .collect()
+                }
+                ".delete" => super::map_completion_values(vec![
+                    "role",
+                    "session",
+                    "rag",
+                    "macro",
+                    "agent-data",
+                ]),
+                ".vault" => {
+                    let mut values = vec!["add", "get", "update", "delete", "list"];
+                    values.sort_unstable();
+                    values
+                        .into_iter()
+                        .map(|v| (format!("{v} "), None))
+                        .collect()
+                }
+                _ => vec![],
+            };
+        } else if cmd == ".install" && args.first() == Some(&"remote") && args.len() >= 2 {
+            let prev = args.get(args.len() - 2).copied().unwrap_or("");
+            if prev == "--filter" {
+                values = super::map_completion_values(
+                    InstallFilter::NAMES.iter().map(|s| s.to_string()).collect(),
+                );
+            } else {
+                let has_filter = args.iter().enumerate().any(|(i, a)| {
+                    a.starts_with("--filter=") || (*a == "--filter" && i < args.len() - 1)
+                });
+                let has_force = args.contains(&"--force");
+                let mut available: Vec<&str> = vec![];
+
+                if !has_filter {
+                    available.push("--filter");
+                }
+                if !has_force {
+                    available.push("--force");
+                }
+
+                values = super::map_completion_values(available);
+            }
+        } else if cmd == ".set" && args.len() == 2 {
+            let candidates = match args[0] {
+                "max_output_tokens" => match self.current_model().max_output_tokens() {
+                    Some(v) => vec![v.to_string()],
+                    None => vec![],
+                },
+                "dry_run" => super::complete_bool(app.dry_run),
+                "stream" => super::complete_bool(app.stream),
+                "save" => super::complete_bool(app.save),
+                "function_calling_support" => super::complete_bool(app.function_calling_support),
+                "enabled_tools" => {
+                    let mut prefix = String::new();
+                    let mut ignores = HashSet::new();
+                    if let Some((v, _)) = args[1].rsplit_once(',') {
+                        ignores = v.split(',').collect();
+                        prefix = format!("{v},");
+                    }
+                    let mut values = vec![];
+                    if prefix.is_empty() {
+                        values.push("all".to_string());
+                    }
+                    values.extend(
+                        self.tool_scope
+                            .functions
+                            .declarations()
+                            .iter()
+                            .filter(|v| {
+                                !v.name.starts_with("user__")
+                                    && !v.name.starts_with("mcp_")
+                                    && !v.name.starts_with("todo__")
+                                    && !v.name.starts_with("agent__")
+                            })
+                            .map(|v| v.name.clone()),
+                    );
+                    values.extend(app.mapping_tools.keys().map(|v| v.to_string()));
+                    values
+                        .into_iter()
+                        .filter(|v| !ignores.contains(v.as_str()))
+                        .map(|v| format!("{prefix}{v}"))
+                        .collect()
+                }
+                "mcp_server_support" => super::complete_bool(app.mcp_server_support),
+                "enabled_mcp_servers" => {
+                    let mut prefix = String::new();
+                    let mut ignores = HashSet::new();
+                    if let Some((v, _)) = args[1].rsplit_once(',') {
+                        ignores = v.split(',').collect();
+                        prefix = format!("{v},");
+                    }
+                    let mut values = vec![];
+                    if prefix.is_empty() {
+                        values.push("all".to_string());
+                    }
+
+                    if let Some(mcp_config) = &self.app.mcp_config {
+                        values.extend(mcp_config.mcp_servers.keys().map(|v| v.to_string()));
+                    }
+                    values.extend(app.mapping_mcp_servers.keys().map(|v| v.to_string()));
+                    values.sort();
+                    values.dedup();
+                    values
+                        .into_iter()
+                        .filter(|v| !ignores.contains(v.as_str()))
+                        .map(|v| format!("{prefix}{v}"))
+                        .collect()
+                }
+                "save_session" => {
+                    let save_session = if let Some(session) = &self.session {
+                        session.save_session()
+                    } else {
+                        app.save_session
+                    };
+                    super::complete_option_bool(save_session)
+                }
+                "rag_reranker_model" => list_models(app, ModelType::Reranker)
+                    .iter()
+                    .map(|v| v.id())
+                    .collect(),
+                "highlight" => super::complete_bool(app.highlight),
+                "auto_continue" => {
+                    let config = self.auto_continue_config();
+                    super::complete_bool(config.enabled)
+                }
+                "max_auto_continues" => {
+                    let config = self.auto_continue_config();
+                    vec![config.max_continues.to_string()]
+                }
+                "inject_todo_instructions" => {
+                    let config = self.auto_continue_config();
+                    super::complete_bool(config.inject_instructions)
+                }
+                "continuation_prompt" => vec!["null".to_string()],
+                _ => vec![],
+            };
+            values = candidates.into_iter().map(|v| (v, None)).collect();
+        } else if cmd == ".vault" && args.len() == 2 {
+            values = self
+                .app
+                .vault
+                .list_secrets(false)
+                .unwrap_or_default()
+                .into_iter()
+                .map(|v| (v, None))
+                .collect();
+        } else if cmd == ".agent" {
+            if args.len() == 2 {
+                let dir = paths::agent_data_dir(args[0]).join(SESSIONS_DIR_NAME);
+                values = list_file_names(dir, ".yaml")
+                    .into_iter()
+                    .map(|v| (v, None))
+                    .collect();
+            }
+            values.extend(super::complete_agent_variables(args[0]));
+        };
+        fuzzy_filter(values, |v| v.0.as_str(), filter)
+    }
+
+    async fn rebuild_tool_scope(
+        &mut self,
+        app: &AppConfig,
+        enabled_mcp_servers: Option<String>,
+        abort_signal: AbortSignal,
+    ) -> Result<()> {
+        let mut mcp_runtime = McpRuntime::new();
+
+        if app.mcp_server_support
+            && let Some(mcp_config) = &self.app.mcp_config
+        {
+            let server_ids: Vec<String> = match &enabled_mcp_servers {
+                Some(servers) if servers == "all" => {
+                    mcp_config.mcp_servers.keys().cloned().collect()
+                }
+                Some(servers) => {
+                    let mut ids = Vec::new();
+                    for item in servers.split(',').map(|s| s.trim()) {
+                        if mcp_config.mcp_servers.contains_key(item) {
+                            ids.push(item.to_string());
+                        } else if let Some(mapped) = app.mapping_mcp_servers.get(item) {
+                            for mapped_id in mapped.split(',').map(|s| s.trim()) {
+                                if mcp_config.mcp_servers.contains_key(mapped_id) {
+                                    ids.push(mapped_id.to_string());
+                                }
+                            }
+                        }
+                    }
+                    ids
+                }
+                None => vec![],
+            };
+
+            if !server_ids.is_empty() {
+                let app_ref = &self.app;
+                let acquire_all = async {
+                    let mut handles = Vec::new();
+                    for id in &server_ids {
+                        if let Some(spec) = mcp_config.mcp_servers.get(id) {
+                            let handle = app_ref
+                                .mcp_factory
+                                .acquire(id, spec, app_ref.mcp_log_path.as_deref())
+                                .await?;
+                            handles.push((id.clone(), handle));
+                        }
+                    }
+                    Ok::<_, Error>(handles)
+                };
+                let handles = abortable_run_with_spinner(
+                    acquire_all,
+                    "Loading MCP servers",
+                    abort_signal.clone(),
+                )
+                .await?;
+                for (id, handle) in handles {
+                    mcp_runtime.insert(id, handle);
+                }
+            }
+        }
+
+        let mut functions = Functions::init(app.visible_tools.as_ref().unwrap_or(&Vec::new()))?;
+        if self.working_mode.is_repl() {
+            functions.append_user_interaction_functions();
+        }
+        if self.agent.is_none()
+            && app.function_calling_support
+            && self.auto_continue_config().enabled
+        {
+            functions.append_todo_functions();
+        }
+        if !mcp_runtime.is_empty() {
+            functions.append_mcp_meta_functions(mcp_runtime.server_names());
+        }
+
+        let tool_tracker = self.tool_scope.tool_tracker.clone();
+        self.tool_scope = ToolScope {
+            functions,
+            mcp_runtime,
+            tool_tracker,
+        };
+        Ok(())
+    }
+
+    pub async fn use_role(
+        &mut self,
+        app: &AppConfig,
+        name: &str,
+        abort_signal: AbortSignal,
+    ) -> Result<()> {
+        let role = self.retrieve_role(app, name)?;
+        if let Some(session) = self.session.as_mut() {
+            session.guard_empty()?;
+        }
+
+        let mcp_servers = if app.mcp_server_support {
+            role.enabled_mcp_servers()
+        } else {
+            if role.enabled_mcp_servers().is_some() {
+                eprintln!(
+                    "{}",
+                    formatdoc!(
+                        "
+                        This role uses MCP servers, but MCP support is disabled.
+                        To enable it, exit the role and set 'mcp_server_support: true', then try again
+                        "
+                    )
+                );
+            }
+            None
+        };
+
+        self.rebuild_tool_scope(app, mcp_servers, abort_signal)
+            .await?;
+        self.use_role_obj(role)
+    }
+
+    pub async fn use_session(
+        &mut self,
+        app: &AppConfig,
+        session_name: Option<&str>,
+        abort_signal: AbortSignal,
+    ) -> Result<()> {
+        if self.session.is_some() {
+            bail!(
+                "Already in a session, please run '.exit session' first to exit the current session."
+            );
+        }
+        let mut session;
+        match session_name {
+            None | Some(TEMP_SESSION_NAME) => {
+                let session_file = self.session_file(TEMP_SESSION_NAME);
+                if session_file.exists() {
+                    remove_file(session_file).with_context(|| {
+                        format!("Failed to cleanup previous '{TEMP_SESSION_NAME}' session")
+                    })?;
+                }
+                session = Some(Session::new_from_ctx(self, app, TEMP_SESSION_NAME));
+            }
+            Some(name) => {
+                let session_path = self.session_file(name);
+                if !session_path.exists() {
+                    session = Some(Session::new_from_ctx(self, app, name));
+                } else {
+                    session = Some(Session::load_from_ctx(self, app, name, &session_path)?);
+                }
+            }
+        }
+        let mut new_session = false;
+        if let Some(session) = session.as_mut() {
+            let mcp_servers = if app.mcp_server_support {
+                session.enabled_mcp_servers()
+            } else {
+                if session.enabled_mcp_servers().is_some() {
+                    eprintln!(
+                        "{}",
+                        formatdoc!(
+                            "
+                            This session uses MCP servers, but MCP support is disabled.
+                            To enable it, exit the session and set 'mcp_server_support: true', then try again
+                            "
+                        )
+                    );
+                }
+                None
+            };
+
+            self.rebuild_tool_scope(app, mcp_servers, abort_signal.clone())
+                .await?;
+
+            if session.is_empty() {
+                new_session = true;
+                if let Some(LastMessage {
+                    input,
+                    output,
+                    continuous,
+                }) = &self.last_message
+                    && (*continuous && !output.is_empty())
+                    && self.agent.is_some() == input.with_agent()
+                {
+                    let ans = Confirm::new(
+                        "Start a session that incorporates the last question and answer?",
+                    )
+                    .with_default(false)
+                    .prompt()?;
+                    if ans {
+                        session.add_message(input, output)?;
+                    }
+                }
+            }
+        }
+        self.session = session;
+        self.init_agent_session_variables(new_session)?;
+        Ok(())
+    }
+
+    pub async fn use_agent(
+        &mut self,
+        app: &AppConfig,
+        agent_name: &str,
+        session_name: Option<&str>,
+        abort_signal: AbortSignal,
+    ) -> Result<()> {
+        if !app.function_calling_support {
+            bail!("Please enable function calling support before using the agent.");
+        }
+        if self.agent.is_some() {
+            bail!("Already in an agent, please run '.exit agent' first to exit the current agent.");
+        }
+
+        let current_model = self.current_model().clone();
+        let agent = Agent::init(
+            app,
+            &self.app,
+            &current_model,
+            self.info_flag,
+            agent_name,
+            abort_signal.clone(),
+        )
+        .await?;
+
+        let is_graph_agent = graph::agent_has_graph(agent_name);
+        if is_graph_agent && session_name.is_some() {
+            bail!(
+                "Graph-based agent '{agent_name}' does not support sessions. \
+                 The graph manages its own state; re-run without a session."
+            );
+        }
+
+        let mcp_servers = if app.mcp_server_support {
+            (!agent.mcp_server_names().is_empty()).then(|| agent.mcp_server_names().join(","))
+        } else {
+            if !agent.mcp_server_names().is_empty() {
+                bail!(
+                    "This agent uses MCP servers, but MCP support is disabled.\nTo enable it, set 'mcp_server_support: true', then try again."
+                );
+            }
+            None
+        };
+
+        self.rebuild_tool_scope(app, mcp_servers, abort_signal.clone())
+            .await?;
+
+        if !agent.model().supports_function_calling() {
+            eprintln!(
+                "Warning: The model '{}' does not support function calling. Agent tools (including todo, spawning, and user interaction) will not be available.",
+                agent.model().id()
+            );
+        }
+
+        // Graph agents manage their own state; never engage a session,
+        // not even an inherited app-level `agent_session` default.
+        let session_name = session_name.map(|v| v.to_string()).or_else(|| {
+            if self.macro_flag || is_graph_agent {
+                None
+            } else {
+                agent.agent_session().map(|v| v.to_string())
+            }
+        });
+
+        if self.session.is_some() {
+            bail!(
+                "Already in a session, please run '.exit session' first to exit the current session."
+            );
+        }
+
+        let should_init_supervisor = agent.can_spawn_agents();
+        let max_concurrent = agent.max_concurrent_agents();
+        let max_depth = agent.max_agent_depth();
+        let supervisor = should_init_supervisor
+            .then(|| Arc::new(RwLock::new(Supervisor::new(max_concurrent, max_depth))));
+
+        self.rag = agent.rag();
+        self.agent = Some(agent);
+        self.supervisor = supervisor;
+        self.inbox = None;
+        self.escalation_queue = None;
+        self.self_agent_id = None;
+        self.parent_supervisor = None;
+        self.current_depth = 0;
+        self.auto_continue_count = 0;
+        self.todo_list = TodoList::default();
+
+        if let Some(session_name) = session_name.as_deref() {
+            self.use_session(app, Some(session_name), abort_signal)
+                .await?;
+        } else {
+            self.init_agent_shared_variables()?;
+        }
+        self.agent_variables = None;
+
+        Ok(())
+    }
+
+    pub fn exit_agent(&mut self, app: &AppConfig) -> Result<()> {
+        self.exit_session()?;
+        let mut functions = Functions::init(app.visible_tools.as_ref().unwrap_or(&Vec::new()))?;
+        if self.working_mode.is_repl() {
+            functions.append_user_interaction_functions();
+        }
+        let tool_tracker = self.tool_scope.tool_tracker.clone();
+        self.tool_scope = ToolScope {
+            functions,
+            mcp_runtime: McpRuntime::default(),
+            tool_tracker,
+        };
+
+        if self.agent.take().is_some() {
+            if let Some(supervisor) = self.supervisor.clone() {
+                supervisor.read().cancel_all();
+            }
+            self.supervisor = None;
+            self.parent_supervisor = None;
+            self.self_agent_id = None;
+            self.inbox = None;
+            self.escalation_queue = None;
+            self.current_depth = 0;
+            self.auto_continue_count = 0;
+            self.todo_list = TodoList::default();
+            self.rag.take();
+            self.discontinuous_last_message();
+        }
+        Ok(())
+    }
+
+    pub async fn edit_role(&mut self, app: &AppConfig, abort_signal: AbortSignal) -> Result<()> {
+        let role_name;
+        if let Some(session) = self.session.as_ref() {
+            if let Some(name) = session.role_name().map(|v| v.to_string()) {
+                if session.is_empty() {
+                    role_name = Some(name);
+                } else {
+                    bail!("Cannot perform this operation because you are in a non-empty session")
+                }
+            } else {
+                bail!("No role")
+            }
+        } else {
+            role_name = self.role.as_ref().map(|v| v.name().to_string());
+        }
+        let name = role_name.ok_or_else(|| anyhow::anyhow!("No role"))?;
+        self.upsert_role(app, &name)?;
+        self.use_role(app, &name, abort_signal).await
+    }
+
+    fn upsert_role(&self, app: &AppConfig, name: &str) -> Result<()> {
+        let role_path = paths::role_file(name);
+        ensure_parent_exists(&role_path)?;
+        let editor = app.editor()?;
+        edit_file(&editor, &role_path)?;
+        if self.working_mode.is_repl() {
+            println!("✓ Saved the role to '{}'.", role_path.display());
+        }
+        Ok(())
+    }
+
+    pub async fn apply_prelude(
+        &mut self,
+        app: &AppConfig,
+        abort_signal: AbortSignal,
+    ) -> Result<()> {
+        if self.macro_flag || !self.state().is_empty() {
+            return Ok(());
+        }
+        let prelude = match self.working_mode {
+            WorkingMode::Repl => app.repl_prelude.as_ref(),
+            WorkingMode::Cmd => app.cmd_prelude.as_ref(),
+        };
+        let prelude = match prelude {
+            Some(v) => {
+                if v.is_empty() {
+                    return Ok(());
+                }
+                v.to_string()
+            }
+            None => return Ok(()),
+        };
+
+        let err_msg = || format!("Invalid prelude '{prelude}");
+        match prelude.split_once(':') {
+            Some(("role", name)) => {
+                self.use_role(app, name, abort_signal)
+                    .await
+                    .with_context(err_msg)?;
+            }
+            Some(("session", name)) => {
+                self.use_session(app, Some(name), abort_signal)
+                    .await
+                    .with_context(err_msg)?;
+            }
+            Some((session_name, role_name)) => {
+                self.use_session(app, Some(session_name), abort_signal.clone())
+                    .await
+                    .with_context(err_msg)?;
+                if let Some(true) = self.session.as_ref().map(|v| v.is_empty()) {
+                    self.use_role(app, role_name, abort_signal)
+                        .await
+                        .with_context(err_msg)?;
+                }
+            }
+            _ => {
+                bail!("{}", err_msg())
+            }
+        }
+        Ok(())
+    }
+
+    pub fn maybe_autoname_session(&mut self) -> bool {
+        if let Some(session) = self.session.as_mut()
+            && session.need_autoname()
+        {
+            session.set_autonaming(true);
+            true
+        } else {
+            false
+        }
+    }
+
+    fn enabled_mcp_servers_for_current_scope(
+        &self,
+        app: &AppConfig,
+        start_mcp_servers: bool,
+    ) -> Option<String> {
+        if !start_mcp_servers || !app.mcp_server_support {
+            return None;
+        }
+        if let Some(agent) = self.agent.as_ref() {
+            return (!agent.mcp_server_names().is_empty())
+                .then(|| agent.mcp_server_names().join(","));
+        }
+        if let Some(session) = self.session.as_ref() {
+            return session.enabled_mcp_servers();
+        }
+        if let Some(role) = self.role.as_ref() {
+            return role.enabled_mcp_servers();
+        }
+        app.enabled_mcp_servers.clone()
+    }
+
+    pub async fn bootstrap_tools(
+        &mut self,
+        app: &AppConfig,
+        start_mcp_servers: bool,
+        abort_signal: AbortSignal,
+    ) -> Result<()> {
+        let enabled_mcp_servers =
+            self.enabled_mcp_servers_for_current_scope(app, start_mcp_servers);
+
+        self.rebuild_tool_scope(app, enabled_mcp_servers, abort_signal)
+            .await
+    }
+
+    pub async fn compress_session(&mut self) -> Result<()> {
+        match self.session.as_ref() {
+            Some(session) => {
+                if !session.has_user_messages() {
+                    bail!("No need to compress since there are no messages in the session")
+                }
+            }
+            None => bail!("No session"),
+        }
+
+        let prompt = self
+            .app
+            .config
+            .summarization_prompt
+            .clone()
+            .unwrap_or_else(|| SUMMARIZATION_PROMPT.into());
+        let input = Input::from_str(self, &prompt, None);
+        let summary = input.fetch_chat_text().await?;
+        let summary_context_prompt = self
+            .app
+            .config
+            .summary_context_prompt
+            .clone()
+            .unwrap_or_else(|| SUMMARY_CONTEXT_PROMPT.into());
+
+        let todo_prefix = if self.auto_continue_config().enabled && !self.todo_list.is_empty() {
+            format!(
+                "[ACTIVE TODO LIST]\n{}\n\n",
+                self.todo_list.render_for_model()
+            )
+        } else {
+            String::new()
+        };
+
+        if let Some(session) = self.session.as_mut() {
+            session.compress(format!("{todo_prefix}{summary_context_prompt}{summary}"));
+        }
+        self.discontinuous_last_message();
+        Ok(())
+    }
+
+    pub async fn autoname_session(&mut self, app: &AppConfig) -> Result<()> {
+        let text = match self
+            .session
+            .as_ref()
+            .and_then(|session| session.chat_history_for_autonaming())
+        {
+            Some(v) => v,
+            None => bail!("No chat history"),
+        };
+        let role = self.retrieve_role(app, CREATE_TITLE_ROLE)?;
+        let input = Input::from_str(self, &text, Some(role));
+        let text = input.fetch_chat_text().await?;
+        if let Some(session) = self.session.as_mut() {
+            session.set_autoname(&text);
+        }
+        Ok(())
+    }
+
+    pub async fn use_rag(&mut self, rag: Option<&str>, abort_signal: AbortSignal) -> Result<()> {
+        if self.agent.is_some() {
+            bail!("Cannot perform this operation because you are using a agent")
+        }
+
+        let app = self.app.config.clone();
+        let rag_cache = self.rag_cache();
+        let working_mode = self.working_mode;
+
+        let rag: Arc<Rag> = match rag {
+            None => {
+                let rag_path = self.rag_file(super::TEMP_RAG_NAME);
+                if rag_path.exists() {
+                    remove_file(&rag_path).with_context(|| {
+                        format!("Failed to cleanup previous '{}' rag", super::TEMP_RAG_NAME)
+                    })?;
+                }
+                Arc::new(Rag::init(&app, super::TEMP_RAG_NAME, &rag_path, &[], abort_signal).await?)
+            }
+            Some(name) => {
+                let rag_path = self.rag_file(name);
+                let key = RagKey::Named(name.to_string());
+
+                rag_cache
+                    .load_with(key, || {
+                        let app = app.clone();
+                        let rag_path = rag_path.clone();
+                        let abort_signal = abort_signal.clone();
+                        async move {
+                            if !rag_path.exists() {
+                                if working_mode.is_cmd() {
+                                    bail!("Unknown RAG '{name}'");
+                                }
+                                Rag::init(&app, name, &rag_path, &[], abort_signal.clone()).await
+                            } else {
+                                Rag::load(&app, name, &rag_path)
+                            }
+                        }
+                    })
+                    .await?
+            }
+        };
+        self.rag = Some(rag);
+        Ok(())
+    }
+
+    pub async fn edit_rag_docs(&mut self, abort_signal: AbortSignal) -> Result<()> {
+        let mut rag = match self.rag.clone() {
+            Some(v) => v.as_ref().clone(),
+            None => bail!("No RAG"),
+        };
+
+        let document_paths = rag.document_paths();
+        let temp_file = temp_file(&format!("-rag-{}", rag.name()), ".txt");
+        tokio::fs::write(&temp_file, &document_paths.join("\n"))
+            .await
+            .with_context(|| format!("Failed to write to '{}'", temp_file.display()))?;
+        let editor = self.app.config.editor()?;
+        edit_file(&editor, &temp_file)?;
+        let new_document_paths = tokio::fs::read_to_string(&temp_file)
+            .await
+            .with_context(|| format!("Failed to read '{}'", temp_file.display()))?;
+        let new_document_paths = new_document_paths
+            .split('\n')
+            .filter_map(|v| {
+                let v = v.trim();
+                if v.is_empty() {
+                    None
+                } else {
+                    Some(v.to_string())
+                }
+            })
+            .collect::<Vec<_>>();
+        if new_document_paths.is_empty() || new_document_paths == document_paths {
+            bail!("No changes")
+        }
+
+        let key = if self.agent.is_some() {
+            RagKey::Agent(rag.name().to_string())
+        } else {
+            RagKey::Named(rag.name().to_string())
+        };
+        self.rag_cache().invalidate(&key);
+
+        rag.refresh_document_paths(&new_document_paths, false, &self.app.config, abort_signal)
+            .await?;
+        self.rag = Some(Arc::new(rag));
+        Ok(())
+    }
+
+    pub async fn rebuild_rag(&mut self, abort_signal: AbortSignal) -> Result<()> {
+        let mut rag = match self.rag.clone() {
+            Some(v) => v.as_ref().clone(),
+            None => bail!("No RAG"),
+        };
+
+        let key = if self.agent.is_some() {
+            RagKey::Agent(rag.name().to_string())
+        } else {
+            RagKey::Named(rag.name().to_string())
+        };
+        self.rag_cache().invalidate(&key);
+
+        let document_paths = rag.document_paths().to_vec();
+        rag.refresh_document_paths(&document_paths, true, &self.app.config, abort_signal)
+            .await?;
+        self.rag = Some(Arc::new(rag));
+        Ok(())
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::super::mcp_factory::McpFactory;
+    use super::*;
+    use crate::config::AppState;
+    use crate::function::ToolCall;
+    use crate::mcp::{McpServer, McpServersConfig, McpTransportType};
+    use crate::utils;
+    use crate::utils::get_env_name;
+    use crate::vault::Vault;
+    use serial_test::serial;
+    use std::env;
+    use std::fs::{create_dir_all, remove_dir_all, write};
+    use std::path::PathBuf;
+    use std::time::{SystemTime, UNIX_EPOCH};
+
+    struct TestConfigDirGuard {
+        key: String,
+        previous: Option<std::ffi::OsString>,
+        path: PathBuf,
+    }
+
+    impl TestConfigDirGuard {
+        fn new() -> Self {
+            let key = get_env_name("config_dir");
+            let previous = env::var_os(&key);
+            let unique = SystemTime::now()
+                .duration_since(UNIX_EPOCH)
+                .unwrap()
+                .as_nanos();
+            let path = env::temp_dir().join(format!("loki-request-context-tests-{unique}"));
+            create_dir_all(&path).unwrap();
+            unsafe {
+                env::set_var(&key, &path);
+            }
+            Self {
+                key,
+                previous,
+                path,
+            }
+        }
+    }
+
+    impl Drop for TestConfigDirGuard {
+        fn drop(&mut self) {
+            if let Some(previous) = &self.previous {
+                unsafe {
+                    env::set_var(&self.key, previous);
+                }
+            } else {
+                unsafe {
+                    env::remove_var(&self.key);
+                }
+            }
+            let _ = remove_dir_all(&self.path);
+        }
+    }
+
+    fn default_app_state() -> Arc<AppState> {
+        Arc::new(AppState::test_default())
+    }
+
+    fn create_test_ctx() -> RequestContext {
+        RequestContext::new(default_app_state(), WorkingMode::Cmd)
+    }
+
+    #[test]
+    fn new_creates_clean_state() {
+        let ctx = RequestContext::new(default_app_state(), WorkingMode::Cmd);
+
+        assert!(ctx.role.is_none());
+        assert!(ctx.session.is_none());
+        assert!(ctx.agent.is_none());
+        assert!(ctx.rag.is_none());
+        assert!(ctx.supervisor.is_none());
+        assert!(ctx.tool_scope.mcp_runtime.is_empty());
+        assert_eq!(ctx.current_depth, 0);
+    }
+
+    #[test]
+    fn update_app_config_persists_changes() {
+        let mut ctx = RequestContext::new(default_app_state(), WorkingMode::Cmd);
+        let previous = Arc::clone(&ctx.app.config);
+
+        ctx.update_app_config(|app| {
+            app.save = true;
+            app.compression_threshold = 1234;
+        });
+
+        assert!(ctx.app.config.save);
+        assert_eq!(ctx.app.config.compression_threshold, 1234);
+        assert!(!Arc::ptr_eq(&ctx.app.config, &previous));
+    }
+
+    #[test]
+    fn use_role_obj_sets_role() {
+        let mut ctx = create_test_ctx();
+        let role = Role::new("test", "test prompt");
+        ctx.use_role_obj(role).unwrap();
+        assert!(ctx.role.is_some());
+        assert_eq!(ctx.role.as_ref().unwrap().name(), "test");
+    }
+
+    #[test]
+    fn exit_role_clears_role() {
+        let mut ctx = create_test_ctx();
+        let role = Role::new("test", "prompt");
+        ctx.use_role_obj(role).unwrap();
+        assert!(ctx.role.is_some());
+        ctx.exit_role().unwrap();
+        assert!(ctx.role.is_none());
+    }
+
+    #[test]
+    fn use_prompt_creates_temp_role() {
+        let mut ctx = create_test_ctx();
+        let app = ctx.app.config.clone();
+        ctx.use_prompt(&app, "you are a pirate").unwrap();
+        assert!(ctx.role.is_some());
+        assert_eq!(ctx.role.as_ref().unwrap().name(), "temp");
+        assert!(
+            ctx.role
+                .as_ref()
+                .unwrap()
+                .prompt()
+                .contains("you are a pirate")
+        );
+    }
+
+    #[test]
+    fn extract_role_returns_standalone_role() {
+        let mut ctx = create_test_ctx();
+        let app = ctx.app.config.clone();
+        let role = Role::new("myrole", "my prompt");
+        ctx.use_role_obj(role).unwrap();
+        let extracted = ctx.extract_role(&app);
+        assert_eq!(extracted.name(), "myrole");
+    }
+
+    #[test]
+    fn extract_role_returns_default_when_nothing_active() {
+        let ctx = create_test_ctx();
+        let app = ctx.app.config.clone();
+        let extracted = ctx.extract_role(&app);
+        assert_eq!(extracted.name(), "");
+    }
+
+    #[test]
+    fn exit_session_clears_session() {
+        let mut ctx = create_test_ctx();
+        ctx.session = Some(Session::default());
+        assert!(ctx.session.is_some());
+        ctx.exit_session().unwrap();
+        assert!(ctx.session.is_none());
+    }
+
+    #[test]
+    fn empty_session_clears_messages() {
+        let mut ctx = create_test_ctx();
+        ctx.session = Some(Session::default());
+        ctx.empty_session().unwrap();
+        assert!(ctx.session.is_some());
+        assert!(ctx.session.as_ref().unwrap().is_empty());
+    }
+
+    #[test]
+    fn maybe_autoname_session_returns_false_when_no_session() {
+        let mut ctx = create_test_ctx();
+        assert!(!ctx.maybe_autoname_session());
+    }
+
+    #[test]
+    #[serial]
+    fn exit_agent_clears_all_agent_state() {
+        let _guard = TestConfigDirGuard::new();
+        let mut ctx = create_test_ctx();
+        let app = ctx.app.config.clone();
+        let agent_name = format!(
+            "test_agent_{}",
+            SystemTime::now()
+                .duration_since(UNIX_EPOCH)
+                .unwrap()
+                .as_nanos()
+        );
+        let agent_dir = paths::agent_data_dir(&agent_name);
+        create_dir_all(&agent_dir).unwrap();
+        write(
+            agent_dir.join("config.yaml"),
+            format!("name: {agent_name}\ninstructions: hi\n"),
+        )
+        .unwrap();
+
+        tokio::runtime::Builder::new_current_thread()
+            .enable_all()
+            .build()
+            .unwrap()
+            .block_on(async {
+                ctx.use_agent(&app, &agent_name, None, utils::create_abort_signal())
+                    .await
+                    .unwrap();
+            });
+
+        assert!(ctx.agent.is_some());
+
+        ctx.exit_agent(&app).unwrap();
+
+        assert!(ctx.agent.is_none());
+        assert!(ctx.rag.is_none());
+    }
+
+    #[test]
+    fn current_depth_default_is_zero() {
+        let ctx = create_test_ctx();
+        assert_eq!(ctx.current_depth, 0);
+    }
+
+    #[test]
+    fn current_depth_can_be_set() {
+        let mut ctx = create_test_ctx();
+        ctx.current_depth = 3;
+        assert_eq!(ctx.current_depth, 3);
+    }
+
+    #[test]
+    fn supervisor_defaults_to_none() {
+        let ctx = create_test_ctx();
+        assert!(ctx.supervisor.is_none());
+    }
+
+    #[test]
+    fn inbox_defaults_to_none() {
+        let ctx = create_test_ctx();
+        assert!(ctx.inbox.is_none());
+    }
+
+    #[test]
+    fn escalation_queue_defaults_to_none() {
+        let ctx = create_test_ctx();
+        assert!(ctx.root_escalation_queue().is_none());
+    }
+
+    fn app_state_with_mcp_config(mcp_server_support: bool, server_names: &[&str]) -> Arc<AppState> {
+        let app_config = AppConfig {
+            mcp_server_support,
+            ..AppConfig::default()
+        };
+
+        let mcp_config = if server_names.is_empty() {
+            None
+        } else {
+            let mut servers = IndexMap::new();
+            for name in server_names {
+                servers.insert(
+                    name.to_string(),
+                    McpServer {
+                        transport_type: McpTransportType::Stdio,
+                        command: Some("echo".to_string()),
+                        args: None,
+                        env: None,
+                        cwd: None,
+                        url: None,
+                        headers: None,
+                    },
+                );
+            }
+            Some(McpServersConfig {
+                mcp_servers: servers,
+            })
+        };
+
+        Arc::new(AppState {
+            config: Arc::new(app_config),
+            vault: Arc::new(Vault::default()),
+            mcp_factory: Arc::new(McpFactory::default()),
+            rag_cache: Arc::new(RagCache::default()),
+            mcp_config,
+            mcp_log_path: None,
+            mcp_registry: None,
+            functions: Functions::default(),
+        })
+    }
+
+    fn run_async<F: Future>(f: F) -> F::Output {
+        tokio::runtime::Builder::new_current_thread()
+            .enable_all()
+            .build()
+            .unwrap()
+            .block_on(f)
+    }
+
+    #[test]
+    #[serial]
+    fn rebuild_tool_scope_mcp_disabled_skips_servers() {
+        let app_state = app_state_with_mcp_config(false, &["github", "slack"]);
+        let mut ctx = RequestContext::new(app_state, WorkingMode::Cmd);
+        let app = ctx.app.config.clone();
+        let abort = utils::create_abort_signal();
+
+        run_async(ctx.rebuild_tool_scope(&app, Some("all".to_string()), abort)).unwrap();
+
+        assert!(ctx.tool_scope.mcp_runtime.is_empty());
+    }
+
+    #[test]
+    #[serial]
+    fn rebuild_tool_scope_no_enabled_servers_yields_empty_runtime() {
+        let app_state = app_state_with_mcp_config(true, &["github"]);
+        let mut ctx = RequestContext::new(app_state, WorkingMode::Cmd);
+        let app = ctx.app.config.clone();
+        let abort = utils::create_abort_signal();
+
+        run_async(ctx.rebuild_tool_scope(&app, None, abort)).unwrap();
+
+        assert!(ctx.tool_scope.mcp_runtime.is_empty());
+    }
+
+    #[test]
+    #[serial]
+    fn rebuild_tool_scope_no_mcp_config_yields_empty_runtime() {
+        let app_state = app_state_with_mcp_config(true, &[]);
+        let mut ctx = RequestContext::new(app_state, WorkingMode::Cmd);
+        let app = ctx.app.config.clone();
+        let abort = utils::create_abort_signal();
+
+        run_async(ctx.rebuild_tool_scope(&app, Some("all".to_string()), abort)).unwrap();
+
+        assert!(ctx.tool_scope.mcp_runtime.is_empty());
+    }
+
+    #[test]
+    #[serial]
+    fn rebuild_tool_scope_preserves_tool_tracker() {
+        let app_state = app_state_with_mcp_config(false, &[]);
+        let mut ctx = RequestContext::new(app_state, WorkingMode::Cmd);
+        let dummy = ToolCall {
+            name: "test_tool".to_string(),
+            ..Default::default()
+        };
+        ctx.tool_scope.tool_tracker.record_call(dummy);
+
+        let app = ctx.app.config.clone();
+        let abort = utils::create_abort_signal();
+        run_async(ctx.rebuild_tool_scope(&app, None, abort)).unwrap();
+
+        let check_call = ToolCall {
+            name: "test_tool".to_string(),
+            ..Default::default()
+        };
+        assert!(
+            ctx.tool_scope
+                .tool_tracker
+                .check_loop(&check_call)
+                .is_none()
+        );
+    }
+
+    #[test]
+    #[serial]
+    fn rebuild_tool_scope_repl_mode_appends_user_interaction_functions() {
+        let app_state = app_state_with_mcp_config(false, &[]);
+        let mut ctx = RequestContext::new(app_state, WorkingMode::Repl);
+        let app = ctx.app.config.clone();
+        let abort = utils::create_abort_signal();
+
+        run_async(ctx.rebuild_tool_scope(&app, None, abort)).unwrap();
+
+        let names: Vec<String> = ctx
+            .tool_scope
+            .functions
+            .declarations()
+            .iter()
+            .map(|f| f.name.clone())
+            .collect();
+        assert!(
+            names.iter().any(|n| n.starts_with("user__")),
+            "REPL mode should include user interaction functions, got: {names:?}"
+        );
+    }
+
+    #[test]
+    #[serial]
+    fn rebuild_tool_scope_cmd_mode_no_user_interaction_functions() {
+        let app_state = app_state_with_mcp_config(false, &[]);
+        let mut ctx = RequestContext::new(app_state, WorkingMode::Cmd);
+        let app = ctx.app.config.clone();
+        let abort = utils::create_abort_signal();
+
+        run_async(ctx.rebuild_tool_scope(&app, None, abort)).unwrap();
+
+        let names: Vec<String> = ctx
+            .tool_scope
+            .functions
+            .declarations()
+            .iter()
+            .map(|f| f.name.clone())
+            .collect();
+        assert!(
+            !names.iter().any(|n| n.starts_with("user__")),
+            "CMD mode should NOT include user interaction functions, got: {names:?}"
+        );
+    }
+
+    #[test]
+    fn select_functions_returns_none_when_no_tools_enabled() {
+        let ctx = create_test_ctx();
+        let role = Role::default();
+        assert!(ctx.select_functions(&role).is_none());
+    }
+
+    #[test]
+    fn select_functions_returns_none_when_function_calling_disabled() {
+        let app_state = {
+            let config = AppConfig {
+                function_calling_support: false,
+                ..AppConfig::default()
+            };
+            Arc::new(AppState {
+                config: Arc::new(config),
+                vault: Arc::new(Vault::default()),
+                mcp_factory: Arc::new(McpFactory::default()),
+                rag_cache: Arc::new(RagCache::default()),
+                mcp_config: None,
+                mcp_log_path: None,
+                mcp_registry: None,
+                functions: Functions::default(),
+            })
+        };
+        let ctx = RequestContext::new(app_state, WorkingMode::Cmd);
+        let mut role = Role::new("r", "p");
+        role.set_enabled_tools(Some("all".to_string()));
+        assert!(ctx.select_functions(&role).is_none());
+    }
+
+    #[test]
+    fn select_functions_all_enabled_tools_returns_all_non_mcp() {
+        let mut ctx = create_test_ctx();
+        ctx.tool_scope.functions.append_todo_functions();
+        ctx.tool_scope.functions.append_user_interaction_functions();
+
+        let mut role = Role::new("r", "p");
+        role.set_enabled_tools(Some("all".to_string()));
+
+        let fns = ctx.select_functions(&role).unwrap();
+        let names: Vec<&str> = fns.iter().map(|f| f.name.as_str()).collect();
+        assert!(names.contains(&"todo__init"));
+        assert!(names.contains(&"user__ask"));
+    }
+
+    #[test]
+    fn select_functions_comma_separated_filters() {
+        let mut ctx = create_test_ctx();
+        ctx.tool_scope.functions.append_todo_functions();
+
+        let mut role = Role::new("r", "p");
+        role.set_enabled_tools(Some("todo__init, todo__add".to_string()));
+
+        let fns = ctx.select_functions(&role).unwrap();
+        let names: Vec<&str> = fns.iter().map(|f| f.name.as_str()).collect();
+        assert!(names.contains(&"todo__init"));
+        assert!(names.contains(&"todo__add"));
+        assert!(!names.contains(&"todo__done"));
+    }
+
+    #[test]
+    fn select_enabled_mcp_servers_returns_empty_when_mcp_disabled() {
+        let app_state = {
+            let config = AppConfig {
+                mcp_server_support: false,
+                ..AppConfig::default()
+            };
+            Arc::new(AppState {
+                config: Arc::new(config),
+                vault: Arc::new(Vault::default()),
+                mcp_factory: Arc::new(McpFactory::default()),
+                rag_cache: Arc::new(RagCache::default()),
+                mcp_config: None,
+                mcp_log_path: None,
+                mcp_registry: None,
+                functions: Functions::default(),
+            })
+        };
+        let ctx = RequestContext::new(app_state, WorkingMode::Cmd);
+        let mut role = Role::new("r", "p");
+        role.set_enabled_mcp_servers(Some("all".to_string()));
+        let result = ctx.select_enabled_mcp_servers(&role);
+        assert!(result.is_empty());
+    }
+
+    #[test]
+    fn select_enabled_mcp_servers_all_returns_all_mcp_functions() {
+        let mut ctx = create_test_ctx();
+        ctx.tool_scope
+            .functions
+            .append_mcp_meta_functions(vec!["github".into(), "slack".into()]);
+
+        let mut role = Role::new("r", "p");
+        role.set_enabled_mcp_servers(Some("all".to_string()));
+
+        let fns = ctx.select_enabled_mcp_servers(&role);
+        let names: Vec<&str> = fns.iter().map(|f| f.name.as_str()).collect();
+        assert!(names.contains(&"mcp_invoke_github"));
+        assert!(names.contains(&"mcp_search_github"));
+        assert!(names.contains(&"mcp_invoke_slack"));
+    }
+
+    #[test]
+    fn select_enabled_mcp_servers_comma_filters() {
+        let mut ctx = create_test_ctx();
+        ctx.tool_scope
+            .functions
+            .append_mcp_meta_functions(vec!["github".into(), "slack".into()]);
+
+        let mut role = Role::new("r", "p");
+        role.set_enabled_mcp_servers(Some("github".to_string()));
+
+        let fns = ctx.select_enabled_mcp_servers(&role);
+        let names: Vec<&str> = fns.iter().map(|f| f.name.as_str()).collect();
+        assert!(names.contains(&"mcp_invoke_github"));
+        assert!(!names.contains(&"mcp_invoke_slack"));
+    }
+
+    #[test]
+    fn state_empty_context() {
+        let ctx = create_test_ctx();
+        assert_eq!(ctx.state(), StateFlags::empty());
+    }
+
+    #[test]
+    fn state_with_role_only() {
+        let mut ctx = create_test_ctx();
+        ctx.role = Some(Role::new("r", "p"));
+        assert!(ctx.state().contains(StateFlags::ROLE));
+        assert!(!ctx.state().contains(StateFlags::SESSION));
+    }
+
+    #[test]
+    fn state_with_empty_session() {
+        let mut ctx = create_test_ctx();
+        ctx.session = Some(Session::default());
+        assert!(ctx.state().contains(StateFlags::SESSION_EMPTY));
+        assert!(!ctx.state().contains(StateFlags::SESSION));
+    }
+
+    #[test]
+    fn state_flags_combine_role_and_session() {
+        let mut ctx = create_test_ctx();
+        ctx.session = Some(Session::default());
+        ctx.role = Some(Role::new("r", "p"));
+        let state = ctx.state();
+        assert!(state.contains(StateFlags::SESSION_EMPTY));
+    }
+
+    #[test]
+    fn role_info_errors_when_no_role() {
+        let ctx = create_test_ctx();
+        assert!(ctx.role_info().is_err());
+    }
+
+    #[test]
+    fn role_info_succeeds_with_role() {
+        let mut ctx = create_test_ctx();
+        ctx.role = Some(Role::new("test", "be helpful"));
+        let info = ctx.role_info().unwrap();
+        assert!(info.contains("be helpful"));
+    }
+
+    #[test]
+    fn agent_info_errors_when_no_agent() {
+        let ctx = create_test_ctx();
+        assert!(ctx.agent_info().is_err());
+    }
+
+    #[test]
+    fn rag_info_errors_when_no_rag() {
+        let ctx = create_test_ctx();
+        assert!(ctx.rag_info().is_err());
+    }
+
+    #[test]
+    #[serial]
+    fn use_role_obj_errors_when_agent_active() {
+        let _guard = TestConfigDirGuard::new();
+        let mut ctx = create_test_ctx();
+        let app = ctx.app.config.clone();
+        let agent_name = format!(
+            "test_agent_{}",
+            SystemTime::now()
+                .duration_since(UNIX_EPOCH)
+                .unwrap()
+                .as_nanos()
+        );
+        let agent_dir = paths::agent_data_dir(&agent_name);
+        create_dir_all(&agent_dir).unwrap();
+        write(
+            agent_dir.join("config.yaml"),
+            format!("name: {agent_name}\ninstructions: hi\n"),
+        )
+        .unwrap();
+
+        tokio::runtime::Builder::new_current_thread()
+            .enable_all()
+            .build()
+            .unwrap()
+            .block_on(async {
+                ctx.use_agent(&app, &agent_name, None, crate::utils::create_abort_signal())
+                    .await
+                    .unwrap();
+            });
+
+        let result = ctx.use_role_obj(Role::new("r", "p"));
+        assert!(result.is_err());
+        assert!(result.unwrap_err().to_string().contains("using a agent"));
+    }
+
+    #[test]
+    fn exit_rag_clears_rag() {
+        let mut ctx = create_test_ctx();
+        assert!(ctx.rag.is_none());
+        ctx.exit_rag().unwrap();
+        assert!(ctx.rag.is_none());
+    }
+
+    #[test]
+    fn discontinuous_last_message_sets_continuous_false() {
+        let mut ctx = create_test_ctx();
+        let input = Input::from_str(&ctx, "test", None);
+        ctx.last_message = Some(LastMessage::new(input, "reply".to_string()));
+        assert!(ctx.last_message.as_ref().unwrap().continuous);
+        ctx.discontinuous_last_message();
+        assert!(!ctx.last_message.as_ref().unwrap().continuous);
+    }
+
+    #[test]
+    fn discontinuous_last_message_noop_when_none() {
+        let mut ctx = create_test_ctx();
+        assert!(ctx.last_message.is_none());
+        ctx.discontinuous_last_message();
+        assert!(ctx.last_message.is_none());
+    }
+
+    #[test]
+    fn before_chat_completion_sets_last_message() {
+        let mut ctx = create_test_ctx();
+        let input = Input::from_str(&ctx, "hello", None);
+        ctx.before_chat_completion(&input).unwrap();
+        assert!(ctx.last_message.is_some());
+        let lm = ctx.last_message.as_ref().unwrap();
+        assert_eq!(lm.output, "");
+        assert!(lm.continuous);
+    }
+
+    #[test]
+    fn role_like_mut_returns_none_when_empty() {
+        let mut ctx = create_test_ctx();
+        assert!(ctx.role_like_mut().is_none());
+    }
+
+    #[test]
+    fn role_like_mut_returns_role_when_only_role() {
+        let mut ctx = create_test_ctx();
+        ctx.role = Some(Role::new("r", "p"));
+        assert!(ctx.role_like_mut().is_some());
+    }
+
+    #[test]
+    fn role_like_mut_prefers_session_over_role() {
+        let mut ctx = create_test_ctx();
+        ctx.role = Some(Role::new("r", "p"));
+        ctx.session = Some(Session::default());
+        let rl = ctx.role_like_mut().unwrap();
+        rl.set_temperature(Some(0.5));
+        assert_eq!(ctx.session.as_ref().unwrap().temperature(), Some(0.5));
+    }
+
+    #[test]
+    fn working_mode_cmd() {
+        let ctx = RequestContext::new(default_app_state(), WorkingMode::Cmd);
+        assert!(ctx.working_mode.is_cmd());
+        assert!(!ctx.working_mode.is_repl());
+    }
+
+    #[test]
+    fn working_mode_repl() {
+        let ctx = RequestContext::new(default_app_state(), WorkingMode::Repl);
+        assert!(ctx.working_mode.is_repl());
+        assert!(!ctx.working_mode.is_cmd());
+    }
+
+    #[test]
+    fn session_file_returns_yaml_path() {
+        let ctx = create_test_ctx();
+        let path = ctx.session_file("my-session");
+        assert!(path.to_string_lossy().ends_with("my-session.yaml"));
+    }
+
+    #[test]
+    fn session_file_with_subdir() {
+        let ctx = create_test_ctx();
+        let path = ctx.session_file("subdir/my-session");
+        let path_str = path.to_string_lossy();
+        assert!(path_str.contains("subdir"));
+        assert!(path_str.ends_with("my-session.yaml"));
+    }
+
+    #[test]
+    fn is_compressing_session_false_when_no_session() {
+        let ctx = create_test_ctx();
+        assert!(!ctx.is_compressing_session());
+    }
+
+    #[test]
+    fn is_compressing_session_false_with_default_session() {
+        let mut ctx = create_test_ctx();
+        ctx.session = Some(Session::default());
+        assert!(!ctx.is_compressing_session());
+    }
+
+    #[test]
+    #[serial]
+    fn retrieve_role_from_markdown_file() {
+        let _guard = TestConfigDirGuard::new();
+        let roles_dir = paths::roles_dir();
+        create_dir_all(&roles_dir).unwrap();
+        write(
+            roles_dir.join("pirate.md"),
+            "You are a pirate. Speak only in pirate language.",
+        )
+        .unwrap();
+
+        let ctx = create_test_ctx();
+        let role = ctx.retrieve_role(&ctx.app.config, "pirate").unwrap();
+        assert_eq!(role.name(), "pirate");
+        assert!(role.prompt().contains("pirate"));
+    }
+
+    #[test]
+    #[serial]
+    fn retrieve_role_builtin_exists() {
+        let _guard = TestConfigDirGuard::new();
+        let ctx = create_test_ctx();
+        let names = paths::list_roles(true);
+        if !names.is_empty() {
+            let role = ctx.retrieve_role(&ctx.app.config, &names[0]);
+            assert!(role.is_ok());
+        }
+    }
+
+    #[test]
+    #[serial]
+    fn retrieve_role_nonexistent_errors() {
+        let _guard = TestConfigDirGuard::new();
+        let ctx = create_test_ctx();
+        let result = ctx.retrieve_role(&ctx.app.config, "definitely_not_a_real_role_xyz");
+        assert!(result.is_err());
+    }
+
+    #[test]
+    #[serial]
+    fn retrieve_role_no_model_id_inherits_current_model() {
+        let _guard = TestConfigDirGuard::new();
+        let roles_dir = paths::roles_dir();
+        create_dir_all(&roles_dir).unwrap();
+        write(roles_dir.join("simple.md"), "You are helpful.").unwrap();
+
+        let ctx = create_test_ctx();
+        let role = ctx.retrieve_role(&ctx.app.config, "simple").unwrap();
+        assert_eq!(role.model().id(), ctx.current_model().id());
+    }
+
+    #[test]
+    #[serial]
+    fn list_roles_finds_markdown_files() {
+        let _guard = TestConfigDirGuard::new();
+        let roles_dir = paths::roles_dir();
+        create_dir_all(&roles_dir).unwrap();
+        write(roles_dir.join("alpha.md"), "Alpha role").unwrap();
+        write(roles_dir.join("beta.md"), "Beta role").unwrap();
+        write(roles_dir.join("not_a_role.txt"), "ignored").unwrap();
+
+        let names = paths::list_roles(false);
+        assert!(names.contains(&"alpha".to_string()));
+        assert!(names.contains(&"beta".to_string()));
+        assert!(!names.contains(&"not_a_role".to_string()));
+    }
+
+    #[test]
+    #[serial]
+    fn list_roles_empty_dir() {
+        let _guard = TestConfigDirGuard::new();
+        let roles_dir = paths::roles_dir();
+        create_dir_all(&roles_dir).unwrap();
+        let names = paths::list_roles(false);
+        assert!(names.is_empty());
+    }
+
+    #[test]
+    #[serial]
+    fn session_new_from_ctx_captures_state() {
+        let _guard = TestConfigDirGuard::new();
+        let ctx = create_test_ctx();
+        let session = Session::new_from_ctx(&ctx, &ctx.app.config, "test-session");
+        assert_eq!(session.name(), "test-session");
+        assert!(session.is_empty());
+    }
+
+    #[test]
+    #[serial]
+    fn session_save_creates_file() {
+        let _guard = TestConfigDirGuard::new();
+        let ctx = create_test_ctx();
+        let mut session = Session::new_from_ctx(&ctx, &ctx.app.config, "save-test");
+        let session_path = ctx.session_file("save-test");
+        ensure_parent_exists(&session_path).unwrap();
+
+        session.save("save-test", &session_path, false).unwrap();
+        assert!(session_path.exists());
+    }
+
+    #[test]
+    #[serial]
+    fn use_session_errors_when_already_in_session() {
+        let _guard = TestConfigDirGuard::new();
+        let mut ctx = create_test_ctx();
+        ctx.session = Some(Session::default());
+
+        let app = ctx.app.config.clone();
+        let abort = utils::create_abort_signal();
+        let result = run_async(ctx.use_session(&app, Some("new"), abort));
+        assert!(result.is_err());
+        assert!(
+            result
+                .unwrap_err()
+                .to_string()
+                .contains("Already in a session")
+        );
+    }
+
+    #[test]
+    #[serial]
+    fn use_session_creates_temp_session() {
+        let _guard = TestConfigDirGuard::new();
+        let sessions_dir = paths::local_path("sessions");
+        create_dir_all(&sessions_dir).unwrap();
+
+        let mut ctx = create_test_ctx();
+        let app = ctx.app.config.clone();
+        let abort = utils::create_abort_signal();
+        run_async(ctx.use_session(&app, None, abort)).unwrap();
+
+        assert!(ctx.session.is_some());
+        assert_eq!(ctx.session.as_ref().unwrap().name(), TEMP_SESSION_NAME);
+    }
+
+    #[test]
+    #[serial]
+    fn use_session_creates_named_session() {
+        let _guard = TestConfigDirGuard::new();
+        let sessions_dir = paths::local_path("sessions");
+        create_dir_all(&sessions_dir).unwrap();
+
+        let mut ctx = create_test_ctx();
+        let app = ctx.app.config.clone();
+        let abort = utils::create_abort_signal();
+        run_async(ctx.use_session(&app, Some("my-session"), abort)).unwrap();
+
+        assert!(ctx.session.is_some());
+        assert_eq!(ctx.session.as_ref().unwrap().name(), "my-session");
+    }
+
+    #[test]
+    #[serial]
+    fn exit_session_roundtrip() {
+        let _guard = TestConfigDirGuard::new();
+        let sessions_dir = paths::local_path("sessions");
+        create_dir_all(&sessions_dir).unwrap();
+
+        let mut ctx = create_test_ctx();
+        let app = ctx.app.config.clone();
+        let abort = utils::create_abort_signal();
+        run_async(ctx.use_session(&app, Some("roundtrip"), abort.clone())).unwrap();
+        assert!(ctx.session.is_some());
+
+        ctx.exit_session().unwrap();
+        assert!(ctx.session.is_none());
+    }
+
+    #[test]
+    #[serial]
+    fn use_role_obj_and_exit_role_full_cycle() {
+        let _guard = TestConfigDirGuard::new();
+        let mut ctx = create_test_ctx();
+
+        ctx.use_role_obj(Role::new("test-role", "test prompt"))
+            .unwrap();
+        assert!(ctx.role.is_some());
+        assert_eq!(ctx.role.as_ref().unwrap().name(), "test-role");
+
+        let _ = ctx.exit_role();
+        assert!(ctx.role.is_none());
+    }
+
+    #[test]
+    #[serial]
+    fn use_role_obj_twice_replaces_role() {
+        let _guard = TestConfigDirGuard::new();
+        let mut ctx = create_test_ctx();
+
+        ctx.use_role_obj(Role::new("first", "prompt 1")).unwrap();
+        assert_eq!(ctx.role.as_ref().unwrap().name(), "first");
+
+        ctx.use_role_obj(Role::new("second", "prompt 2")).unwrap();
+        assert_eq!(ctx.role.as_ref().unwrap().name(), "second");
+    }
+
+    #[test]
+    #[serial]
+    fn list_macros_finds_yaml_files() {
+        let _guard = TestConfigDirGuard::new();
+        let macros_dir = paths::macros_dir();
+        create_dir_all(&macros_dir).unwrap();
+        write(macros_dir.join("greet.yaml"), "steps:\n  - \".help\"").unwrap();
+        write(macros_dir.join("build.yaml"), "steps:\n  - \".help\"").unwrap();
+
+        let names = paths::list_macros();
+        assert!(names.contains(&"greet".to_string()));
+        assert!(names.contains(&"build".to_string()));
+    }
+
+    #[test]
+    #[serial]
+    fn list_rags_finds_yaml_files() {
+        let _guard = TestConfigDirGuard::new();
+        let rags_dir = paths::rags_dir();
+        create_dir_all(&rags_dir).unwrap();
+        write(rags_dir.join("docs.yaml"), "embedding_model: test").unwrap();
+
+        let names = paths::list_rags();
+        assert!(names.contains(&"docs".to_string()));
+    }
+
+    #[test]
+    #[serial]
+    fn list_rags_empty_dir() {
+        let _guard = TestConfigDirGuard::new();
+        let rags_dir = paths::rags_dir();
+        create_dir_all(&rags_dir).unwrap();
+        assert!(paths::list_rags().is_empty());
+    }
+
+    #[test]
+    #[serial]
+    fn use_agent_errors_when_already_in_session() {
+        let _guard = TestConfigDirGuard::new();
+        let mut ctx = create_test_ctx();
+        ctx.session = Some(Session::default());
+
+        let app = ctx.app.config.clone();
+        let agent_name = format!(
+            "test_agent_{}",
+            SystemTime::now()
+                .duration_since(UNIX_EPOCH)
+                .unwrap()
+                .as_nanos()
+        );
+        let agent_dir = paths::agent_data_dir(&agent_name);
+        create_dir_all(&agent_dir).unwrap();
+        write(
+            agent_dir.join("config.yaml"),
+            format!("name: {agent_name}\ninstructions: hi\n"),
+        )
+        .unwrap();
+
+        let abort = utils::create_abort_signal();
+        let result = run_async(ctx.use_agent(&app, &agent_name, Some("test_session"), abort));
+        assert!(result.is_err());
+        assert!(
+            result
+                .unwrap_err()
+                .to_string()
+                .contains("Already in a session")
+        );
+        assert!(
+            ctx.agent.is_none(),
+            "Agent should not be set when session check fails"
+        );
+    }
+
+    #[test]
+    #[serial]
+    fn use_agent_errors_when_already_in_session_even_without_session_name() {
+        let _guard = TestConfigDirGuard::new();
+        let mut ctx = create_test_ctx();
+        ctx.session = Some(Session::default());
+
+        let app = ctx.app.config.clone();
+        let agent_name = format!(
+            "test_agent_{}",
+            SystemTime::now()
+                .duration_since(UNIX_EPOCH)
+                .unwrap()
+                .as_nanos()
+        );
+        let agent_dir = paths::agent_data_dir(&agent_name);
+        create_dir_all(&agent_dir).unwrap();
+        write(
+            agent_dir.join("config.yaml"),
+            format!("name: {agent_name}\ninstructions: hi\n"),
+        )
+        .unwrap();
+
+        let abort = utils::create_abort_signal();
+        let result = run_async(ctx.use_agent(&app, &agent_name, None, abort));
+        assert!(result.is_err());
+        assert!(
+            result
+                .unwrap_err()
+                .to_string()
+                .contains("Already in a session")
+        );
+        assert!(
+            ctx.agent.is_none(),
+            "Agent should not be set when session check fails"
+        );
+    }
+
+    #[test]
+    #[serial]
+    fn use_agent_errors_when_graph_agent_given_explicit_session() {
+        let _guard = TestConfigDirGuard::new();
+        let mut ctx = create_test_ctx();
+
+        let app = ctx.app.config.clone();
+        let agent_name = format!(
+            "test_graph_agent_{}",
+            SystemTime::now()
+                .duration_since(UNIX_EPOCH)
+                .unwrap()
+                .as_nanos()
+        );
+        let agent_dir = paths::agent_data_dir(&agent_name);
+        create_dir_all(&agent_dir).unwrap();
+        write(
+            agent_dir.join("graph.yaml"),
+            format!(
+                "name: {agent_name}\nversion: \"1.0\"\nstart: done\nnodes:\n  done:\n    type: end\n    output: ok\n"
+            ),
+        )
+        .unwrap();
+
+        let abort = utils::create_abort_signal();
+        let result = run_async(ctx.use_agent(&app, &agent_name, Some("test_session"), abort));
+
+        assert!(result.is_err());
+        assert!(
+            result
+                .unwrap_err()
+                .to_string()
+                .contains("does not support sessions")
+        );
+        assert!(
+            ctx.agent.is_none(),
+            "Agent should not be set when the graph-agent session guard fails"
+        );
+    }
+
+    #[test]
+    #[serial]
+    fn use_agent_skips_inherited_session_for_graph_agent() {
+        let _guard = TestConfigDirGuard::new();
+        let mut ctx = create_test_ctx();
+        ctx.update_app_config(|app| app.agent_session = Some("inherited".to_string()));
+
+        let app = ctx.app.config.clone();
+        let agent_name = format!(
+            "test_graph_agent_{}",
+            SystemTime::now()
+                .duration_since(UNIX_EPOCH)
+                .unwrap()
+                .as_nanos()
+        );
+        let agent_dir = paths::agent_data_dir(&agent_name);
+        create_dir_all(&agent_dir).unwrap();
+        write(
+            agent_dir.join("graph.yaml"),
+            format!(
+                "name: {agent_name}\nversion: \"1.0\"\nstart: done\nnodes:\n  done:\n    type: end\n    output: ok\n"
+            ),
+        )
+        .unwrap();
+
+        let abort = utils::create_abort_signal();
+        run_async(ctx.use_agent(&app, &agent_name, None, abort)).unwrap();
+
+        assert!(ctx.agent.is_some(), "Graph agent should load successfully");
+        assert!(
+            ctx.session.is_none(),
+            "Graph agent must not engage a session, not even an inherited default"
+        );
+    }
+
+    fn first_file(dir: &Path) -> Option<PathBuf> {
+        for entry in read_dir(dir).ok()?.flatten() {
+            let path = entry.path();
+            if path.is_dir() {
+                if let Some(found) = first_file(&path) {
+                    return Some(found);
+                }
+            } else {
+                return Some(path);
+            }
+        }
+        None
+    }
+
+    #[test]
+    fn asset_category_parse_maps_known_names() {
+        assert_eq!(AssetCategory::parse("agents"), Some(AssetCategory::Agents));
+        assert_eq!(AssetCategory::parse("macros"), Some(AssetCategory::Macros));
+        assert_eq!(
+            AssetCategory::parse("functions"),
+            Some(AssetCategory::Functions)
+        );
+        assert_eq!(
+            AssetCategory::parse("mcp_config"),
+            Some(AssetCategory::McpConfig)
+        );
+        assert_eq!(AssetCategory::parse("roles"), None);
+        assert_eq!(AssetCategory::parse(""), None);
+    }
+
+    #[test]
+    #[serial]
+    fn install_builtin_agents_force_overwrites_only_with_force() {
+        let _guard = TestConfigDirGuard::new();
+
+        Agent::install_builtin_agents(false).unwrap();
+        let file =
+            first_file(&paths::agents_data_dir()).expect("bundled agents should be installed");
+
+        write(&file, "SENTINEL").unwrap();
+        Agent::install_builtin_agents(false).unwrap();
+        assert_eq!(
+            read_to_string(&file).unwrap(),
+            "SENTINEL",
+            "non-force install must not overwrite an existing file"
+        );
+
+        Agent::install_builtin_agents(true).unwrap();
+        assert_ne!(
+            read_to_string(&file).unwrap(),
+            "SENTINEL",
+            "force install must overwrite the existing file"
+        );
+    }
+
+    #[test]
+    #[serial]
+    fn install_functions_force_preserves_user_mcp_json() {
+        let _guard = TestConfigDirGuard::new();
+
+        Functions::install_builtin_global_tools(false).unwrap();
+        let mcp = paths::mcp_config_file();
+        assert!(mcp.exists(), "mcp.json should be installed on first run");
+
+        write(&mcp, "USER_MCP_CONFIG").unwrap();
+        Functions::install_builtin_global_tools(true).unwrap();
+        assert_eq!(
+            read_to_string(&mcp).unwrap(),
+            "USER_MCP_CONFIG",
+            "force install must NOT overwrite the user's mcp.json"
+        );
+    }
+
+    #[test]
+    #[serial]
+    fn install_mcp_config_overwrites_existing() {
+        let _guard = TestConfigDirGuard::new();
+
+        Functions::install_mcp_config().unwrap();
+        let mcp = paths::mcp_config_file();
+        assert!(mcp.exists(), "install_mcp_config should create mcp.json");
+
+        write(&mcp, "USER_MCP_CONFIG").unwrap();
+        Functions::install_mcp_config().unwrap();
+        assert_ne!(
+            read_to_string(&mcp).unwrap(),
+            "USER_MCP_CONFIG",
+            "install_mcp_config must overwrite the existing mcp.json"
+        );
+    }
+}
diff --git a/src/config/role.rs b/src/config/role.rs
index ebf57eb..bcf1e2d 100644
--- a/src/config/role.rs
+++ b/src/config/role.rs
@@ -55,6 +55,14 @@ pub struct Role {
     enabled_tools: Option<String>,
     #[serde(skip_serializing_if = "Option::is_none")]
     enabled_mcp_servers: Option<String>,
+    #[serde(skip_serializing_if = "Option::is_none")]
+    auto_continue: Option<bool>,
+    #[serde(skip_serializing_if = "Option::is_none")]
+    max_auto_continues: Option<usize>,
+    #[serde(skip_serializing_if = "Option::is_none")]
+    inject_todo_instructions: Option<bool>,
+    #[serde(skip_serializing_if = "Option::is_none")]
+    continuation_prompt: Option<String>,
 
     #[serde(skip)]
     model: Model,
@@ -90,6 +98,14 @@ impl Role {
                     "enabled_mcp_servers" => {
                         role.enabled_mcp_servers = value.as_str().map(|v| v.to_string())
                     }
+                    "auto_continue" => role.auto_continue = value.as_bool(),
+                    "max_auto_continues" => {
+                        role.max_auto_continues = value.as_u64().map(|v| v as usize)
+                    }
+                    "inject_todo_instructions" => role.inject_todo_instructions = value.as_bool(),
+                    "continuation_prompt" => {
+                        role.continuation_prompt = value.as_str().map(|v| v.to_string())
+                    }
                     _ => (),
                 }
             }
@@ -131,6 +147,20 @@ impl Role {
         if let Some(enabled_mcp_servers) = self.enabled_mcp_servers() {
             metadata.push(format!("enabled_mcp_servers: {enabled_mcp_servers}"));
         }
+        if let Some(auto_continue) = self.auto_continue {
+            metadata.push(format!("auto_continue: {auto_continue}"));
+        }
+        if let Some(max_auto_continues) = self.max_auto_continues {
+            metadata.push(format!("max_auto_continues: {max_auto_continues}"));
+        }
+        if let Some(inject_todo_instructions) = self.inject_todo_instructions {
+            metadata.push(format!(
+                "inject_todo_instructions: {inject_todo_instructions}"
+            ));
+        }
+        if let Some(continuation_prompt) = &self.continuation_prompt {
+            metadata.push(format!("continuation_prompt: {continuation_prompt}"));
+        }
         if metadata.is_empty() {
             format!("{}\n", self.prompt)
         } else if self.prompt.is_empty() {
@@ -225,6 +255,26 @@ impl Role {
         self.prompt.contains(INPUT_PLACEHOLDER)
     }
 
+    pub fn auto_continue(&self) -> Option<bool> {
+        self.auto_continue
+    }
+
+    pub fn max_auto_continues(&self) -> Option<usize> {
+        self.max_auto_continues
+    }
+
+    pub fn inject_todo_instructions(&self) -> Option<bool> {
+        self.inject_todo_instructions
+    }
+
+    pub fn continuation_prompt(&self) -> Option<&str> {
+        self.continuation_prompt.as_deref()
+    }
+
+    pub fn append_to_prompt(&mut self, text: &str) {
+        self.prompt.push_str(text);
+    }
+
     pub fn echo_messages(&self, input: &Input) -> String {
         let input_markdown = input.render();
         if self.is_empty_prompt() {
@@ -374,6 +424,100 @@ fn parse_structure_prompt(prompt: &str) -> (&str, Vec<(&str, &str)>) {
 mod tests {
     use super::*;
 
+    #[test]
+    fn role_new_parses_prompt() {
+        let role = Role::new("test", "You are a helpful assistant");
+        assert_eq!(role.name(), "test");
+        assert_eq!(role.prompt(), "You are a helpful assistant");
+    }
+
+    #[test]
+    fn role_new_parses_metadata() {
+        let content =
+            "---\nmodel: openai:gpt-4\ntemperature: 0.7\ntop_p: 0.9\n---\nYou are helpful";
+        let role = Role::new("test", content);
+        assert_eq!(role.model_id(), Some("openai:gpt-4"));
+        assert_eq!(role.temperature(), Some(0.7));
+        assert_eq!(role.top_p(), Some(0.9));
+        assert_eq!(role.prompt(), "You are helpful");
+    }
+
+    #[test]
+    fn role_new_parses_enabled_tools() {
+        let content = "---\nenabled_tools: tool1,tool2\n---\nPrompt";
+        let role = Role::new("test", content);
+        assert_eq!(role.enabled_tools(), Some("tool1,tool2".to_string()));
+    }
+
+    #[test]
+    fn role_new_parses_enabled_mcp_servers() {
+        let content = "---\nenabled_mcp_servers: github,jira\n---\nPrompt";
+        let role = Role::new("test", content);
+        assert_eq!(role.enabled_mcp_servers(), Some("github,jira".to_string()));
+    }
+
+    #[test]
+    fn role_new_no_metadata_has_none_fields() {
+        let role = Role::new("test", "Just a prompt");
+        assert_eq!(role.model_id(), None);
+        assert_eq!(role.temperature(), None);
+        assert_eq!(role.top_p(), None);
+        assert_eq!(role.enabled_tools(), None);
+        assert_eq!(role.enabled_mcp_servers(), None);
+    }
+
+    #[test]
+    fn role_builtin_shell_loads() {
+        let role = Role::builtin("shell").unwrap();
+        assert_eq!(role.name(), "shell");
+        assert!(!role.prompt().is_empty());
+    }
+
+    #[test]
+    fn role_builtin_code_loads() {
+        let role = Role::builtin("code").unwrap();
+        assert_eq!(role.name(), "code");
+        assert!(!role.prompt().is_empty());
+    }
+
+    #[test]
+    fn role_builtin_nonexistent_errors() {
+        let result = Role::builtin("nonexistent_role_xyz");
+        assert!(result.is_err());
+    }
+
+    #[test]
+    fn role_default_has_empty_fields() {
+        let role = Role::default();
+        assert_eq!(role.name(), "");
+        assert_eq!(role.prompt(), "");
+        assert_eq!(role.model_id(), None);
+    }
+
+    #[test]
+    fn role_set_model_updates_model() {
+        let mut role = Role::new("test", "prompt");
+        let model = Model::default();
+        role.set_model(model.clone());
+        assert_eq!(role.model().id(), model.id());
+    }
+
+    #[test]
+    fn role_set_temperature_works() {
+        let mut role = Role::new("test", "prompt");
+        role.set_temperature(Some(0.5));
+        assert_eq!(role.temperature(), Some(0.5));
+    }
+
+    #[test]
+    fn role_export_includes_metadata() {
+        let content = "---\ntemperature: 0.8\n---\nMy prompt";
+        let role = Role::new("test", content);
+        let exported = role.export();
+        assert!(exported.contains("temperature"));
+        assert!(exported.contains("My prompt"));
+    }
+
     #[test]
     fn test_parse_structure_prompt1() {
         let prompt = r#"
diff --git a/src/config/session.rs b/src/config/session.rs
index cb0cecf..254334f 100644
--- a/src/config/session.rs
+++ b/src/config/session.rs
@@ -32,6 +32,14 @@ pub struct Session {
     save_session: Option<bool>,
     #[serde(skip_serializing_if = "Option::is_none")]
     compression_threshold: Option<usize>,
+    #[serde(skip_serializing_if = "Option::is_none")]
+    auto_continue: Option<bool>,
+    #[serde(skip_serializing_if = "Option::is_none")]
+    max_auto_continues: Option<usize>,
+    #[serde(skip_serializing_if = "Option::is_none")]
+    inject_todo_instructions: Option<bool>,
+    #[serde(skip_serializing_if = "Option::is_none")]
+    continuation_prompt: Option<String>,
 
     #[serde(skip_serializing_if = "Option::is_none")]
     role_name: Option<String>,
@@ -67,11 +75,11 @@ pub struct Session {
 }
 
 impl Session {
-    pub fn new(config: &Config, name: &str) -> Self {
-        let role = config.extract_role();
+    pub fn new_from_ctx(ctx: &RequestContext, app: &AppConfig, name: &str) -> Self {
+        let role = ctx.extract_role(app);
         let mut session = Self {
             name: name.to_string(),
-            save_session: config.save_session,
+            save_session: app.save_session,
             ..Default::default()
         };
         session.set_role(role);
@@ -79,13 +87,18 @@ impl Session {
         session
     }
 
-    pub fn load(config: &Config, name: &str, path: &Path) -> Result<Self> {
+    pub fn load_from_ctx(
+        ctx: &RequestContext,
+        app: &AppConfig,
+        name: &str,
+        path: &Path,
+    ) -> Result<Self> {
         let content = read_to_string(path)
             .with_context(|| format!("Failed to load session {} at {}", name, path.display()))?;
         let mut session: Self =
             serde_yaml::from_str(&content).with_context(|| format!("Invalid session {name}"))?;
 
-        session.model = Model::retrieve_model(config, &session.model_id, ModelType::Chat)?;
+        session.model = Model::retrieve_model(app, &session.model_id, ModelType::Chat)?;
 
         if let Some(autoname) = name.strip_prefix("_/") {
             session.name = TEMP_SESSION_NAME.to_string();
@@ -99,7 +112,7 @@ impl Session {
         }
 
         if let Some(role_name) = &session.role_name
-            && let Ok(role) = config.retrieve_role(role_name)
+            && let Ok(role) = ctx.retrieve_role(app, role_name)
         {
             session.role_prompt = role.prompt().to_string();
         }
@@ -165,6 +178,18 @@ impl Session {
         if let Some(save_session) = self.save_session() {
             data["save_session"] = save_session.into();
         }
+        if let Some(auto_continue) = self.auto_continue() {
+            data["auto_continue"] = auto_continue.into();
+        }
+        if let Some(max_auto_continues) = self.max_auto_continues() {
+            data["max_auto_continues"] = max_auto_continues.into();
+        }
+        if let Some(inject_todo_instructions) = self.inject_todo_instructions() {
+            data["inject_todo_instructions"] = inject_todo_instructions.into();
+        }
+        if let Some(continuation_prompt) = self.continuation_prompt() {
+            data["continuation_prompt"] = continuation_prompt.into();
+        }
         let (tokens, percent) = self.tokens_usage();
         data["total_tokens"] = tokens.into();
         if let Some(max_input_tokens) = self.model().max_input_tokens() {
@@ -220,6 +245,22 @@ impl Session {
             items.push(("compression_threshold", compression_threshold.to_string()));
         }
 
+        if let Some(auto_continue) = self.auto_continue() {
+            items.push(("auto_continue", auto_continue.to_string()));
+        }
+        if let Some(max_auto_continues) = self.max_auto_continues() {
+            items.push(("max_auto_continues", max_auto_continues.to_string()));
+        }
+        if let Some(inject_todo_instructions) = self.inject_todo_instructions() {
+            items.push((
+                "inject_todo_instructions",
+                inject_todo_instructions.to_string(),
+            ));
+        }
+        if let Some(continuation_prompt) = self.continuation_prompt() {
+            items.push(("continuation_prompt", continuation_prompt.to_string()));
+        }
+
         if let Some(max_input_tokens) = self.model().max_input_tokens() {
             items.push(("max_input_tokens", max_input_tokens.to_string()));
         }
@@ -330,6 +371,50 @@ impl Session {
         }
     }
 
+    pub fn auto_continue(&self) -> Option<bool> {
+        self.auto_continue
+    }
+
+    pub fn max_auto_continues(&self) -> Option<usize> {
+        self.max_auto_continues
+    }
+
+    pub fn set_auto_continue(&mut self, value: Option<bool>) {
+        if self.auto_continue != value {
+            self.auto_continue = value;
+            self.dirty = true;
+        }
+    }
+
+    pub fn set_max_auto_continues(&mut self, value: Option<usize>) {
+        if self.max_auto_continues != value {
+            self.max_auto_continues = value;
+            self.dirty = true;
+        }
+    }
+
+    pub fn inject_todo_instructions(&self) -> Option<bool> {
+        self.inject_todo_instructions
+    }
+
+    pub fn continuation_prompt(&self) -> Option<&str> {
+        self.continuation_prompt.as_deref()
+    }
+
+    pub fn set_inject_todo_instructions(&mut self, value: Option<bool>) {
+        if self.inject_todo_instructions != value {
+            self.inject_todo_instructions = value;
+            self.dirty = true;
+        }
+    }
+
+    pub fn set_continuation_prompt(&mut self, value: Option<String>) {
+        if self.continuation_prompt != value {
+            self.continuation_prompt = value;
+            self.dirty = true;
+        }
+    }
+
     pub fn needs_compression(&self, global_compression_threshold: usize) -> bool {
         if self.compressing {
             return false;
@@ -543,15 +628,6 @@ impl Session {
         let mut messages = self.messages.clone();
         if input.continue_output().is_some() {
             return messages;
-        } else if input.regenerate() {
-            while let Some(last) = messages.last() {
-                if !last.role.is_user() {
-                    messages.pop();
-                } else {
-                    break;
-                }
-            }
-            return messages;
         }
         let mut need_add_msg = true;
         let len = messages.len();
@@ -664,3 +740,174 @@ impl AutoName {
         !self.naming && self.chat_history.is_some() && self.name.is_none()
     }
 }
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use crate::client::{Message, MessageContent, MessageRole, Model};
+    use crate::config::{AppConfig, AppState, RequestContext, WorkingMode};
+    use crate::function::Functions;
+    use std::sync::Arc;
+
+    #[test]
+    fn session_default_is_empty() {
+        let session = Session::default();
+        assert!(session.is_empty());
+        assert_eq!(session.name(), "");
+        assert_eq!(session.role_name(), None);
+        assert!(!session.dirty());
+    }
+
+    #[test]
+    fn session_new_from_ctx_captures_save_session() {
+        let app_config = Arc::new(AppConfig::default());
+        let app_state = Arc::new(AppState {
+            config: app_config.clone(),
+            vault: Arc::new(Vault::default()),
+            mcp_factory: Arc::new(mcp_factory::McpFactory::default()),
+            rag_cache: Arc::new(rag_cache::RagCache::default()),
+            mcp_config: None,
+            mcp_log_path: None,
+            mcp_registry: None,
+            functions: Functions::default(),
+        });
+        let ctx = RequestContext::new(app_state, WorkingMode::Cmd);
+        let session = Session::new_from_ctx(&ctx, &app_config, "test-session");
+
+        assert_eq!(session.name(), "test-session");
+        assert_eq!(session.save_session(), app_config.save_session);
+        assert!(session.is_empty());
+        assert!(!session.dirty());
+    }
+
+    #[test]
+    fn session_set_role_captures_role_info() {
+        let mut session = Session::default();
+        let content = "---\ntemperature: 0.5\n---\nYou are a coder";
+        let mut role = Role::new("coder", content);
+        role.set_model(Model::default());
+
+        session.set_role(role);
+
+        assert_eq!(session.role_name(), Some("coder"));
+        assert_eq!(session.temperature(), Some(0.5));
+        assert!(session.dirty());
+    }
+
+    #[test]
+    fn session_clear_role() {
+        let mut session = Session::default();
+        let mut role = Role::new("test", "prompt");
+        role.set_model(Model::default());
+        session.set_role(role);
+
+        assert_eq!(session.role_name(), Some("test"));
+
+        session.clear_role();
+
+        assert_eq!(session.role_name(), None);
+    }
+
+    #[test]
+    fn session_guard_empty_passes_when_empty() {
+        let session = Session::default();
+        assert!(session.guard_empty().is_ok());
+    }
+
+    #[test]
+    fn session_needs_compression_threshold() {
+        let session = Session::default();
+        assert!(!session.needs_compression(4000));
+    }
+
+    #[test]
+    fn session_needs_compression_returns_false_when_compressing() {
+        let mut session = Session::default();
+        session.set_compressing(true);
+        assert!(!session.needs_compression(0));
+    }
+
+    #[test]
+    fn session_needs_compression_returns_false_when_threshold_zero() {
+        let session = Session::default();
+        assert!(!session.needs_compression(0));
+    }
+
+    #[test]
+    fn session_set_compressing_flag() {
+        let mut session = Session::default();
+        assert!(!session.compressing());
+        session.set_compressing(true);
+        assert!(session.compressing());
+        session.set_compressing(false);
+        assert!(!session.compressing());
+    }
+
+    #[test]
+    fn session_set_save_session_this_time() {
+        let mut session = Session::default();
+        assert!(!session.save_session_this_time);
+        session.set_save_session_this_time();
+        assert!(session.save_session_this_time);
+    }
+
+    #[test]
+    fn session_save_session_returns_configured_value() {
+        let mut session = Session::default();
+        assert_eq!(session.save_session(), None);
+        session.set_save_session(Some(true));
+        assert_eq!(session.save_session(), Some(true));
+        session.set_save_session(Some(false));
+        assert_eq!(session.save_session(), Some(false));
+        session.set_save_session(None);
+        assert_eq!(session.save_session(), None);
+    }
+
+    #[test]
+    fn session_compress_moves_messages() {
+        let mut session = Session::default();
+        session.messages.push(Message::new(
+            MessageRole::System,
+            MessageContent::Text("system prompt".to_string()),
+        ));
+        session.messages.push(Message::new(
+            MessageRole::User,
+            MessageContent::Text("hello".to_string()),
+        ));
+
+        assert_eq!(session.messages.len(), 2);
+        assert!(session.compressed_messages.is_empty());
+
+        session.compress("Summary of conversation".to_string());
+
+        assert!(!session.compressed_messages.is_empty());
+        assert_eq!(session.messages.len(), 1);
+        assert!(session.dirty());
+    }
+
+    #[test]
+    fn session_is_not_empty_after_compress() {
+        let mut session = Session::default();
+        session.messages.push(Message::new(
+            MessageRole::User,
+            MessageContent::Text("hello".to_string()),
+        ));
+
+        session.compress("Summary".to_string());
+
+        assert!(!session.is_empty());
+    }
+
+    #[test]
+    fn session_need_autoname_default_false() {
+        let session = Session::default();
+        assert!(!session.need_autoname());
+    }
+
+    #[test]
+    fn session_set_autonaming_doesnt_panic_without_autoname() {
+        let mut session = Session::default();
+        session.set_autonaming(true);
+        assert!(!session.need_autoname());
+    }
+}
diff --git a/src/config/tool_scope.rs b/src/config/tool_scope.rs
new file mode 100644
index 0000000..9836ca5
--- /dev/null
+++ b/src/config/tool_scope.rs
@@ -0,0 +1,192 @@
+use crate::function::{Functions, ToolCallTracker};
+use crate::mcp::{CatalogItem, ConnectedServer, McpRegistry};
+
+use anyhow::{Context, Result, anyhow};
+use bm25::{Document, Language, SearchEngineBuilder};
+use rmcp::model::{CallToolRequestParams, CallToolResult};
+use serde_json::{Value, json};
+use std::collections::HashMap;
+use std::sync::Arc;
+
+#[derive(Clone)]
+pub struct ToolScope {
+    pub functions: Functions,
+    pub mcp_runtime: McpRuntime,
+    pub tool_tracker: ToolCallTracker,
+}
+
+impl Default for ToolScope {
+    fn default() -> Self {
+        Self {
+            functions: Functions::default(),
+            mcp_runtime: McpRuntime::default(),
+            tool_tracker: ToolCallTracker::default(),
+        }
+    }
+}
+
+#[derive(Default, Clone)]
+pub struct McpRuntime {
+    pub servers: HashMap<String, Arc<ConnectedServer>>,
+}
+
+impl McpRuntime {
+    pub fn new() -> Self {
+        Self::default()
+    }
+
+    pub fn is_empty(&self) -> bool {
+        self.servers.is_empty()
+    }
+
+    pub fn insert(&mut self, name: String, handle: Arc<ConnectedServer>) {
+        self.servers.insert(name, handle);
+    }
+
+    pub fn get(&self, name: &str) -> Option<&Arc<ConnectedServer>> {
+        self.servers.get(name)
+    }
+
+    pub fn server_names(&self) -> Vec<String> {
+        self.servers.keys().cloned().collect()
+    }
+
+    pub fn sync_from_registry(&mut self, registry: &McpRegistry) {
+        self.servers.clear();
+        for (name, handle) in registry.running_servers() {
+            self.servers.insert(name.clone(), Arc::clone(handle));
+        }
+    }
+
+    async fn catalog_items(&self, server: &str) -> Result<HashMap<String, CatalogItem>> {
+        let server_handle = self
+            .get(server)
+            .cloned()
+            .with_context(|| format!("{server} MCP server not found in runtime"))?;
+        let tools = server_handle.list_tools(None).await?;
+        let mut items = HashMap::new();
+
+        for tool in tools.tools {
+            let item = CatalogItem {
+                name: tool.name.to_string(),
+                server: server.to_string(),
+                description: tool.description.unwrap_or_default().to_string(),
+            };
+            items.insert(item.name.clone(), item);
+        }
+
+        Ok(items)
+    }
+
+    pub async fn search(
+        &self,
+        server: &str,
+        query: &str,
+        top_k: usize,
+    ) -> Result<Vec<CatalogItem>> {
+        let items = self.catalog_items(server).await?;
+        let docs = items.values().map(|item| Document {
+            id: item.name.clone(),
+            contents: format!(
+                "{}\n{}\nserver:{}",
+                item.name, item.description, item.server
+            ),
+        });
+        let engine = SearchEngineBuilder::<String>::with_documents(Language::English, docs).build();
+
+        Ok(engine
+            .search(query, top_k.min(20))
+            .into_iter()
+            .filter_map(|result| items.get(&result.document.id))
+            .take(top_k)
+            .cloned()
+            .collect())
+    }
+
+    pub async fn describe(&self, server: &str, tool: &str) -> Result<Value> {
+        let server_handle = self
+            .get(server)
+            .cloned()
+            .with_context(|| format!("{server} MCP server not found in runtime"))?;
+
+        let tool_schema = server_handle
+            .list_tools(None)
+            .await?
+            .tools
+            .into_iter()
+            .find(|item| item.name == tool)
+            .ok_or_else(|| anyhow!("{tool} not found in {server} MCP server catalog"))?
+            .input_schema;
+
+        Ok(json!({
+            "type": "object",
+            "properties": {
+                "tool": {
+                    "type": "string",
+                },
+                "arguments": tool_schema
+            }
+        }))
+    }
+
+    pub async fn invoke(
+        &self,
+        server: &str,
+        tool: &str,
+        arguments: Value,
+    ) -> Result<CallToolResult> {
+        let server_handle = self
+            .get(server)
+            .cloned()
+            .with_context(|| format!("Invoked MCP server does not exist: {server}"))?;
+
+        let mut request = CallToolRequestParams::new(tool.to_owned());
+        request.arguments = arguments.as_object().cloned();
+
+        server_handle.call_tool(request).await.map_err(Into::into)
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use crate::function::ToolCall;
+
+    #[test]
+    fn mcp_runtime_new_is_empty() {
+        let runtime = McpRuntime::new();
+        assert!(runtime.is_empty());
+        assert!(runtime.server_names().is_empty());
+    }
+
+    #[test]
+    fn mcp_runtime_default_is_empty() {
+        let runtime = McpRuntime::default();
+        assert!(runtime.is_empty());
+    }
+
+    #[test]
+    fn mcp_runtime_get_returns_none_for_missing_server() {
+        let runtime = McpRuntime::new();
+        assert!(runtime.get("nonexistent").is_none());
+    }
+
+    #[test]
+    fn tool_scope_default_has_empty_mcp_runtime() {
+        let scope = ToolScope::default();
+        assert!(scope.mcp_runtime.is_empty());
+    }
+
+    #[test]
+    fn tool_scope_default_has_empty_functions() {
+        let scope = ToolScope::default();
+        assert!(scope.functions.is_empty());
+    }
+
+    #[test]
+    fn tool_scope_default_tracker_has_no_loops() {
+        let scope = ToolScope::default();
+        let dummy_call = ToolCall::default();
+        assert!(scope.tool_tracker.check_loop(&dummy_call).is_none());
+    }
+}
diff --git a/src/config/update.rs b/src/config/update.rs
new file mode 100644
index 0000000..6fb45d4
--- /dev/null
+++ b/src/config/update.rs
@@ -0,0 +1,244 @@
+use crate::utils::warning_text;
+use anyhow::{Context, Result, bail};
+use dunce::canonicalize;
+use inquire::Confirm;
+use is_terminal::IsTerminal;
+use self_update::Status;
+use self_update::backends::github::Update;
+use std::fs::OpenOptions;
+use std::path::Path;
+use std::{env, fs, io, process};
+
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+enum InstallSource {
+    Cargo,
+    Homebrew,
+    Manual,
+}
+
+impl InstallSource {
+    fn is_package_managed(self) -> bool {
+        matches!(self, InstallSource::Cargo | InstallSource::Homebrew)
+    }
+
+    fn label(self) -> &'static str {
+        match self {
+            InstallSource::Cargo => "Cargo",
+            InstallSource::Homebrew => "Homebrew",
+            InstallSource::Manual => "manually-installed",
+        }
+    }
+}
+
+fn classify_install_path(path: &Path) -> InstallSource {
+    let components: Vec<&str> = path
+        .components()
+        .filter_map(|c| c.as_os_str().to_str())
+        .collect();
+
+    if components
+        .windows(2)
+        .any(|w| w[0] == ".cargo" && w[1] == "bin")
+    {
+        return InstallSource::Cargo;
+    }
+
+    if components.contains(&"Cellar") {
+        return InstallSource::Homebrew;
+    }
+    let path_str = path.to_string_lossy();
+    if path_str.starts_with("/opt/homebrew/") || path_str.starts_with("/home/linuxbrew/.linuxbrew/")
+    {
+        return InstallSource::Homebrew;
+    }
+
+    InstallSource::Manual
+}
+
+fn normalize_version(requested: Option<String>) -> Option<String> {
+    let raw = requested?;
+    let trimmed = raw.trim();
+    if trimmed.is_empty() || trimmed.eq_ignore_ascii_case("latest") {
+        return None;
+    }
+    match trimmed.chars().next() {
+        Some('v' | 'V') => Some(trimmed.to_string()),
+        Some(c) if c.is_ascii_digit() => Some(format!("v{trimmed}")),
+        _ => Some(trimmed.to_string()),
+    }
+}
+
+fn is_dir_writable(dir: &Path) -> bool {
+    let probe = dir.join(format!(".loki-update-write-test-{}", process::id()));
+    match OpenOptions::new().write(true).create_new(true).open(&probe) {
+        Ok(_) => {
+            let _ = fs::remove_file(&probe);
+            true
+        }
+        Err(_) => false,
+    }
+}
+
+pub fn run_self_update(requested: Option<String>, force: bool) -> Result<()> {
+    let target_tag = normalize_version(requested);
+
+    let exe_path = env::current_exe()
+        .context("Could not determine the path of the running loki executable")?;
+    let resolved = canonicalize(&exe_path).unwrap_or_else(|_| exe_path.clone());
+    let source = classify_install_path(&resolved);
+
+    if source.is_package_managed() {
+        let body = match source {
+            InstallSource::Homebrew => format!(
+                "Loki appears to be installed via Homebrew ({}).\n\
+                 Updating in place replaces the binary inside Homebrew's Cellar; `brew` will\n\
+                 then report a version that no longer matches the file on disk, and a later\n\
+                 `brew upgrade`/`brew reinstall` may overwrite it or fail.\n\
+                 The clean way to update is:  brew upgrade loki",
+                exe_path.display()
+            ),
+            InstallSource::Cargo => format!(
+                "Loki appears to be installed via `cargo install` ({}).\n\
+                 Updating in place leaves Cargo's records out of sync with the binary on disk.\n\
+                 The clean way to update is:  cargo install --locked loki-ai",
+                exe_path.display()
+            ),
+            InstallSource::Manual => unreachable!("Manual installs are not package-managed"),
+        };
+        println!("{} {body}", warning_text("WARNING:"));
+
+        if force {
+            println!("--force specified; updating anyway.");
+        } else if io::stdin().is_terminal() {
+            let proceed = Confirm::new("Update anyway?")
+                .with_default(false)
+                .prompt()?;
+            if !proceed {
+                println!("Update cancelled.");
+                return Ok(());
+            }
+        } else {
+            bail!(
+                "Refusing to update a {} install. Re-run with --force to override.",
+                source.label()
+            );
+        }
+    }
+
+    if let Some(parent) = exe_path.parent()
+        && !is_dir_writable(parent)
+    {
+        bail!(
+            "No write permission for '{}'. Re-run with elevated permissions (e.g. sudo), \
+             or update Loki through your package manager.",
+            parent.display()
+        );
+    }
+
+    let interactive = io::stdin().is_terminal();
+    let mut builder = Update::configure();
+    builder
+        .repo_owner("Dark-Alex-17")
+        .repo_name("loki")
+        .bin_name("loki")
+        .current_version(env!("CARGO_PKG_VERSION"))
+        .no_confirm(true)
+        .show_download_progress(interactive);
+    if let Some(tag) = &target_tag {
+        builder.target_version_tag(tag.as_str());
+    }
+    let status = builder
+        .build()
+        .context("Failed to configure the self-update")?
+        .update()
+        .context("Self-update failed")?;
+
+    match status {
+        Status::UpToDate(version) => {
+            println!("Loki is already up to date (v{version}).");
+        }
+        Status::Updated(version) => {
+            println!("Loki updated to v{version}. Restart loki to use the new version.");
+        }
+    }
+    Ok(())
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use std::path::PathBuf;
+
+    #[test]
+    fn classify_cargo_install() {
+        assert_eq!(
+            classify_install_path(&PathBuf::from("/home/u/.cargo/bin/loki")),
+            InstallSource::Cargo
+        );
+    }
+
+    #[test]
+    fn classify_homebrew_opt_prefix() {
+        assert_eq!(
+            classify_install_path(&PathBuf::from("/opt/homebrew/bin/loki")),
+            InstallSource::Homebrew
+        );
+    }
+
+    #[test]
+    fn classify_homebrew_cellar() {
+        assert_eq!(
+            classify_install_path(&PathBuf::from("/usr/local/Cellar/loki/0.3.0/bin/loki")),
+            InstallSource::Homebrew
+        );
+    }
+
+    #[test]
+    fn classify_homebrew_linuxbrew() {
+        assert_eq!(
+            classify_install_path(&PathBuf::from("/home/linuxbrew/.linuxbrew/bin/loki")),
+            InstallSource::Homebrew
+        );
+    }
+
+    #[test]
+    fn classify_manual_usr_local_bin() {
+        assert_eq!(
+            classify_install_path(&PathBuf::from("/usr/local/bin/loki")),
+            InstallSource::Manual
+        );
+    }
+
+    #[test]
+    fn classify_manual_local_bin() {
+        assert_eq!(
+            classify_install_path(&PathBuf::from("/home/u/.local/bin/loki")),
+            InstallSource::Manual
+        );
+    }
+
+    #[test]
+    fn normalize_version_latest_and_empty_are_none() {
+        assert_eq!(normalize_version(None), None);
+        assert_eq!(normalize_version(Some(String::new())), None);
+        assert_eq!(normalize_version(Some("   ".to_string())), None);
+        assert_eq!(normalize_version(Some("latest".to_string())), None);
+        assert_eq!(normalize_version(Some("LATEST".to_string())), None);
+    }
+
+    #[test]
+    fn normalize_version_prepends_v_for_bare_semver() {
+        assert_eq!(
+            normalize_version(Some("0.4.0".to_string())),
+            Some("v0.4.0".to_string())
+        );
+        assert_eq!(
+            normalize_version(Some("v0.4.0".to_string())),
+            Some("v0.4.0".to_string())
+        );
+        assert_eq!(
+            normalize_version(Some("  v0.4.0  ".to_string())),
+            Some("v0.4.0".to_string())
+        );
+    }
+}
diff --git a/src/function/mod.rs b/src/function/mod.rs
index 4384982..0a7d5ef 100644
--- a/src/function/mod.rs
+++ b/src/function/mod.rs
@@ -3,16 +3,17 @@ pub(crate) mod todo;
 pub(crate) mod user_interaction;
 
 use crate::{
-    config::{Agent, Config, GlobalConfig},
+    config::{Agent, RequestContext},
     utils::*,
 };
 
 use crate::config::ensure_parent_exists;
+use crate::config::paths;
 use crate::mcp::{
     MCP_DESCRIBE_META_FUNCTION_NAME_PREFIX, MCP_INVOKE_META_FUNCTION_NAME_PREFIX,
     MCP_SEARCH_META_FUNCTION_NAME_PREFIX,
 };
-use crate::parsers::{bash, python};
+use crate::parsers::{bash, python, typescript};
 use anyhow::{Context, Result, anyhow, bail};
 use indexmap::IndexMap;
 use indoc::formatdoc;
@@ -50,17 +51,25 @@ enum BinaryType<'a> {
 }
 
 #[derive(Debug, Clone, Copy, PartialEq, Eq, AsRefStr)]
-enum Language {
+pub enum Language {
     Bash,
     Python,
+    TypeScript,
     Unsupported,
 }
 
 impl From<&String> for Language {
     fn from(s: &String) -> Self {
-        match s.to_lowercase().as_str() {
+        Language::from_extension(s)
+    }
+}
+
+impl Language {
+    pub fn from_extension(ext: &str) -> Self {
+        match ext.to_lowercase().as_str() {
             "sh" => Language::Bash,
             "py" => Language::Python,
+            "ts" => Language::TypeScript,
             _ => Language::Unsupported,
         }
     }
@@ -72,6 +81,7 @@ impl Language {
         match self {
             Language::Bash => "bash",
             Language::Python => "python",
+            Language::TypeScript => "npx tsx",
             Language::Unsupported => "sh",
         }
     }
@@ -80,13 +90,45 @@ impl Language {
         match self {
             Language::Bash => "sh",
             Language::Python => "py",
+            Language::TypeScript => "ts",
             _ => "sh",
         }
     }
 }
 
+impl Language {
+    pub fn direct_invoker(self) -> Option<(&'static str, &'static [&'static str])> {
+        match self {
+            Language::Bash => Some(("bash", &[])),
+            Language::Python => Some(("python3", &[])),
+            Language::TypeScript => Some(("npx", &["tsx"])),
+            Language::Unsupported => None,
+        }
+    }
+}
+
+fn extract_shebang_runtime(path: &Path) -> Option<String> {
+    let file = File::open(path).ok()?;
+    let reader = io::BufReader::new(file);
+    let first_line = io::BufRead::lines(reader).next()?.ok()?;
+    let shebang = first_line.strip_prefix("#!")?;
+    let cmd = shebang.trim();
+    if cmd.is_empty() {
+        return None;
+    }
+    if let Some(after_env) = cmd.strip_prefix("/usr/bin/env ") {
+        let runtime = after_env.trim();
+        if runtime.is_empty() {
+            return None;
+        }
+        Some(runtime.to_string())
+    } else {
+        Some(cmd.to_string())
+    }
+}
+
 pub async fn eval_tool_calls(
-    config: &GlobalConfig,
+    ctx: &mut RequestContext,
     mut calls: Vec<ToolCall>,
 ) -> Result<Vec<ToolResult>> {
     let mut output = vec![];
@@ -99,9 +141,7 @@ pub async fn eval_tool_calls(
     }
     let mut is_all_null = true;
     for call in calls {
-        if let Some(checker) = &config.read().tool_call_tracker
-            && let Some(msg) = checker.check_loop(&call.clone())
-        {
+        if let Some(msg) = ctx.tool_scope.tool_tracker.check_loop(&call.clone()) {
             let dup_msg = format!("{{\"tool_call_loop_alert\":{}}}", &msg.trim());
             println!(
                 "{}",
@@ -112,7 +152,7 @@ pub async fn eval_tool_calls(
             is_all_null = false;
             continue;
         }
-        let mut result = call.eval(config).await?;
+        let mut result = call.eval(ctx).await?;
         if result.is_null() {
             result = json!("DONE");
         } else {
@@ -125,16 +165,13 @@ pub async fn eval_tool_calls(
     }
 
     if !output.is_empty() {
-        let (has_escalations, summary) = {
-            let cfg = config.read();
-            if cfg.current_depth == 0
-                && let Some(ref queue) = cfg.root_escalation_queue
-                && queue.has_pending()
-            {
-                (true, queue.pending_summary())
-            } else {
-                (false, vec![])
-            }
+        let (has_escalations, summary) = if ctx.current_depth == 0
+            && let Some(queue) = ctx.root_escalation_queue()
+            && queue.has_pending()
+        {
+            (true, queue.pending_summary())
+        } else {
+            (false, vec![])
         };
 
         if has_escalations {
@@ -172,10 +209,10 @@ pub struct Functions {
 }
 
 impl Functions {
-    fn install_global_tools() -> Result<()> {
+    pub fn install_builtin_global_tools(force: bool) -> Result<()> {
         info!(
             "Installing global built-in functions in {}",
-            Config::functions_dir().display()
+            paths::functions_dir().display()
         );
 
         for file in FunctionAssets::iter() {
@@ -189,15 +226,15 @@ impl Functions {
                 anyhow!("Failed to load embedded function file: {}", file.as_ref())
             })?;
             let content = unsafe { std::str::from_utf8_unchecked(&embedded_file.data) };
-            let file_path = Config::functions_dir().join(file.as_ref());
-            let file_extension = file_path
+            let file_path = paths::functions_dir().join(file.as_ref());
+            #[cfg_attr(not(unix), expect(unused))]
+            let is_script = file_path
                 .extension()
                 .and_then(OsStr::to_str)
-                .map(|s| s.to_lowercase());
-            #[cfg_attr(not(unix), expect(unused))]
-            let is_script = matches!(file_extension.as_deref(), Some("sh") | Some("py"));
+                .is_some_and(|ext| Language::from_extension(ext) != Language::Unsupported);
 
-            if file_path.exists() {
+            let force_this = force && file.as_ref() != "mcp.json";
+            if file_path.exists() && !force_this {
                 debug!(
                     "Function file already exists, skipping: {}",
                     file_path.display()
@@ -220,8 +257,23 @@ impl Functions {
         Ok(())
     }
 
+    pub fn install_mcp_config() -> Result<()> {
+        let file_path = paths::mcp_config_file();
+        let embedded = FunctionAssets::get("mcp.json")
+            .ok_or_else(|| anyhow!("Failed to load embedded mcp.json"))?;
+        let content = unsafe { std::str::from_utf8_unchecked(&embedded.data) };
+
+        ensure_parent_exists(&file_path)?;
+
+        info!("Reinstalling MCP config file: {}", file_path.display());
+
+        let mut config_file = File::create(&file_path)?;
+        config_file.write_all(content.as_bytes())?;
+
+        Ok(())
+    }
+
     pub fn init(visible_tools: &[String]) -> Result<Self> {
-        Self::install_global_tools()?;
         Self::clear_global_functions_bin_dir()?;
 
         let declarations = Self {
@@ -230,7 +282,7 @@ impl Functions {
 
         info!(
             "Building global function binaries in {}",
-            Config::functions_bin_dir().display()
+            paths::functions_bin_dir().display()
         );
         Self::build_global_function_binaries(visible_tools, None)?;
 
@@ -238,7 +290,6 @@ impl Functions {
     }
 
     pub fn init_agent(name: &str, global_tools: &[String]) -> Result<Self> {
-        Self::install_global_tools()?;
         Self::clear_agent_bin_dir(name)?;
 
         let global_tools_declarations = if !global_tools.is_empty() {
@@ -247,7 +298,7 @@ impl Functions {
 
             info!(
                 "Building global function binaries required by agent: {name} in {}",
-                Config::functions_bin_dir().display()
+                paths::functions_bin_dir().display()
             );
             Self::build_global_function_binaries(global_tools, Some(name))?;
             tools_declarations
@@ -255,7 +306,7 @@ impl Functions {
             debug!("No global tools found for agent: {}", name);
             Vec::new()
         };
-        let agent_script_declarations = match Config::agent_functions_file(name) {
+        let agent_script_declarations = match paths::agent_functions_file(name) {
             Ok(path) if path.exists() => {
                 info!(
                     "Loading functions script for agent: {name} from {}",
@@ -266,7 +317,7 @@ impl Functions {
 
                 info!(
                     "Building function binary for agent: {name} in {}",
-                    Config::agent_bin_dir(name).display()
+                    paths::agent_bin_dir(name).display()
                 );
                 Self::build_agent_tool_binaries(name)?;
                 script_declarations
@@ -318,14 +369,6 @@ impl Functions {
             .extend(user_interaction::user_interaction_function_declarations());
     }
 
-    pub fn clear_mcp_meta_functions(&mut self) {
-        self.declarations.retain(|d| {
-            !d.name.starts_with(MCP_INVOKE_META_FUNCTION_NAME_PREFIX)
-                && !d.name.starts_with(MCP_SEARCH_META_FUNCTION_NAME_PREFIX)
-                && !d.name.starts_with(MCP_DESCRIBE_META_FUNCTION_NAME_PREFIX)
-        });
-    }
-
     pub fn append_mcp_meta_functions(&mut self, mcp_servers: Vec<String>) {
         let mut invoke_function_properties = IndexMap::new();
         invoke_function_properties.insert(
@@ -429,7 +472,7 @@ impl Functions {
     fn build_global_tool_declarations(
         enabled_tools: &[String],
     ) -> Result<Vec<FunctionDeclaration>> {
-        let global_tools_directory = Config::global_tools_dir();
+        let global_tools_directory = paths::global_tools_dir();
         let mut function_declarations = Vec::new();
 
         for tool in enabled_tools {
@@ -473,6 +516,11 @@ impl Functions {
                         file_name,
                         tools_file_path.parent(),
                     ),
+                    Language::TypeScript => typescript::generate_typescript_declarations(
+                        tool_file,
+                        file_name,
+                        tools_file_path.parent(),
+                    ),
                     Language::Unsupported => {
                         bail!("Unsupported tool file extension: {}", language.as_ref())
                     }
@@ -513,14 +561,21 @@ impl Functions {
                 bail!("Unsupported tool file extension: {}", language.as_ref());
             }
 
-            Self::build_binaries(binary_name, language, BinaryType::Tool(agent_name))?;
+            let tool_path = paths::global_tools_dir().join(tool);
+            let custom_runtime = extract_shebang_runtime(&tool_path);
+            Self::build_binaries(
+                binary_name,
+                language,
+                BinaryType::Tool(agent_name),
+                custom_runtime.as_deref(),
+            )?;
         }
 
         Ok(())
     }
 
     fn clear_agent_bin_dir(name: &str) -> Result<()> {
-        let agent_bin_directory = Config::agent_bin_dir(name);
+        let agent_bin_directory = paths::agent_bin_dir(name);
         if !agent_bin_directory.exists() {
             debug!(
                 "Creating agent bin directory: {}",
@@ -539,7 +594,7 @@ impl Functions {
     }
 
     fn clear_global_functions_bin_dir() -> Result<()> {
-        let bin_dir = Config::functions_bin_dir();
+        let bin_dir = paths::functions_bin_dir();
         if !bin_dir.exists() {
             fs::create_dir_all(&bin_dir)?;
         }
@@ -554,8 +609,9 @@ impl Functions {
     }
 
     fn build_agent_tool_binaries(name: &str) -> Result<()> {
+        let tools_file = paths::agent_functions_file(name)?;
         let language = Language::from(
-            &Config::agent_functions_file(name)?
+            &tools_file
                 .extension()
                 .and_then(OsStr::to_str)
                 .map(|s| s.to_lowercase())
@@ -568,7 +624,8 @@ impl Functions {
             bail!("Unsupported tool file extension: {}", language.as_ref());
         }
 
-        Self::build_binaries(name, language, BinaryType::Agent)
+        let custom_runtime = extract_shebang_runtime(&tools_file);
+        Self::build_binaries(name, language, BinaryType::Agent, custom_runtime.as_deref())
     }
 
     #[cfg(windows)]
@@ -576,22 +633,23 @@ impl Functions {
         binary_name: &str,
         language: Language,
         binary_type: BinaryType,
+        custom_runtime: Option<&str>,
     ) -> Result<()> {
         use native::runtime;
         let (binary_file, binary_script_file) = match binary_type {
             BinaryType::Tool(None) => (
-                Config::functions_bin_dir().join(format!("{binary_name}.cmd")),
-                Config::functions_bin_dir()
+                paths::functions_bin_dir().join(format!("{binary_name}.cmd")),
+                paths::functions_bin_dir()
                     .join(format!("run-{binary_name}.{}", language.to_extension())),
             ),
             BinaryType::Tool(Some(agent_name)) => (
-                Config::agent_bin_dir(agent_name).join(format!("{binary_name}.cmd")),
-                Config::agent_bin_dir(agent_name)
+                paths::agent_bin_dir(agent_name).join(format!("{binary_name}.cmd")),
+                paths::agent_bin_dir(agent_name)
                     .join(format!("run-{binary_name}.{}", language.to_extension())),
             ),
             BinaryType::Agent => (
-                Config::agent_bin_dir(binary_name).join(format!("{binary_name}.cmd")),
-                Config::agent_bin_dir(binary_name)
+                paths::agent_bin_dir(binary_name).join(format!("{binary_name}.cmd")),
+                paths::agent_bin_dir(binary_name)
                     .join(format!("run-{binary_name}.{}", language.to_extension())),
             ),
         };
@@ -613,36 +671,40 @@ impl Functions {
             )
         })?;
         let content_template = unsafe { std::str::from_utf8_unchecked(&embedded_file.data) };
+        let to_script_path = |p: &str| -> String { p.replace('\\', "/") };
         let content = match binary_type {
             BinaryType::Tool(None) => {
-                let root_dir = Config::functions_dir();
+                let root_dir = paths::functions_dir();
                 let tool_path = format!(
                     "{}/{binary_name}",
-                    &Config::global_tools_dir().to_string_lossy()
+                    &paths::global_tools_dir().to_string_lossy()
                 );
                 content_template
                     .replace("{function_name}", binary_name)
-                    .replace("{root_dir}", &root_dir.to_string_lossy())
-                    .replace("{tool_path}", &tool_path)
+                    .replace("{root_dir}", &to_script_path(&root_dir.to_string_lossy()))
+                    .replace("{tool_path}", &to_script_path(&tool_path))
             }
             BinaryType::Tool(Some(agent_name)) => {
-                let root_dir = Config::agent_data_dir(agent_name);
+                let root_dir = paths::agent_data_dir(agent_name);
                 let tool_path = format!(
                     "{}/{binary_name}",
-                    &Config::global_tools_dir().to_string_lossy()
+                    &paths::global_tools_dir().to_string_lossy()
                 );
                 content_template
                     .replace("{function_name}", binary_name)
-                    .replace("{root_dir}", &root_dir.to_string_lossy())
-                    .replace("{tool_path}", &tool_path)
+                    .replace("{root_dir}", &to_script_path(&root_dir.to_string_lossy()))
+                    .replace("{tool_path}", &to_script_path(&tool_path))
             }
             BinaryType::Agent => content_template
                 .replace("{agent_name}", binary_name)
-                .replace("{config_dir}", &Config::config_dir().to_string_lossy()),
+                .replace(
+                    "{config_dir}",
+                    &to_script_path(&paths::config_dir().to_string_lossy()),
+                ),
         }
         .replace(
             "{prompt_utils_file}",
-            &Config::bash_prompt_utils_file().to_string_lossy(),
+            &to_script_path(&paths::bash_prompt_utils_file().to_string_lossy()),
         );
         if binary_script_file.exists() {
             fs::remove_file(&binary_script_file)?;
@@ -656,40 +718,48 @@ impl Functions {
             binary_file.display()
         );
 
-        let run = match language {
-            Language::Bash => {
-                let shell = runtime::bash_path().ok_or_else(|| anyhow!("Shell not found"))?;
-                format!("{shell} --noprofile --norc")
+        let run = if let Some(rt) = custom_runtime {
+            rt.to_string()
+        } else {
+            match language {
+                Language::Bash => {
+                    let shell = runtime::bash_path().ok_or_else(|| anyhow!("Shell not found"))?;
+                    format!("{shell} --noprofile --norc")
+                }
+                Language::Python if Path::new(".venv").exists() => {
+                    let executable_path = env::current_dir()?
+                        .join(".venv")
+                        .join("Scripts")
+                        .join("activate.bat");
+                    let canonicalized_path = dunce::canonicalize(&executable_path)?;
+                    format!(
+                        "call \"{}\" && {}",
+                        canonicalized_path.to_string_lossy(),
+                        language.to_cmd()
+                    )
+                }
+                Language::Python => {
+                    let executable_path = which::which("python")
+                        .or_else(|_| which::which("python3"))
+                        .map_err(|_| anyhow!("Python executable not found in PATH"))?;
+                    let canonicalized_path = dunce::canonicalize(&executable_path)?;
+                    canonicalized_path.to_string_lossy().into_owned()
+                }
+                Language::TypeScript => {
+                    let npx_path = which::which("npx").map_err(|_| {
+                        anyhow!("npx executable not found in PATH (required for TypeScript tools)")
+                    })?;
+                    let canonicalized_path = dunce::canonicalize(&npx_path)?;
+                    format!("{} tsx", canonicalized_path.to_string_lossy())
+                }
+                _ => bail!("Unsupported language: {}", language.as_ref()),
             }
-            Language::Python if Path::new(".venv").exists() => {
-                let executable_path = env::current_dir()?
-                    .join(".venv")
-                    .join("Scripts")
-                    .join("activate.bat");
-                let canonicalized_path = fs::canonicalize(&executable_path)?;
-                format!(
-                    "call \"{}\" && {}",
-                    canonicalized_path.to_string_lossy(),
-                    language.to_cmd()
-                )
-            }
-            Language::Python => {
-                let executable_path = which::which("python")
-                    .or_else(|_| which::which("python3"))
-                    .map_err(|_| anyhow!("Python executable not found in PATH"))?;
-                let canonicalized_path = fs::canonicalize(&executable_path)?;
-                canonicalized_path.to_string_lossy().into_owned()
-            }
-            _ => bail!("Unsupported language: {}", language.as_ref()),
         };
         let bin_dir = binary_file
             .parent()
-            .expect("Failed to get parent directory of binary file")
-            .canonicalize()?
-            .to_string_lossy()
-            .into_owned();
-        let wrapper_binary = binary_script_file
-            .canonicalize()?
+            .expect("Failed to get parent directory of binary file");
+        let canonical_bin_dir = dunce::canonicalize(bin_dir)?.to_string_lossy().into_owned();
+        let wrapper_binary = dunce::canonicalize(&binary_script_file)?
             .to_string_lossy()
             .into_owned();
         let content = formatdoc!(
@@ -697,7 +767,7 @@ impl Functions {
 						@echo off
 						setlocal
 
-						set "bin_dir={bin_dir}"
+						set "bin_dir={canonical_bin_dir}"
 
 						{run} "{wrapper_binary}" %*"#,
         );
@@ -713,15 +783,16 @@ impl Functions {
         binary_name: &str,
         language: Language,
         binary_type: BinaryType,
+        custom_runtime: Option<&str>,
     ) -> Result<()> {
         use std::os::unix::prelude::PermissionsExt;
 
         let binary_file = match binary_type {
-            BinaryType::Tool(None) => Config::functions_bin_dir().join(binary_name),
+            BinaryType::Tool(None) => paths::functions_bin_dir().join(binary_name),
             BinaryType::Tool(Some(agent_name)) => {
-                Config::agent_bin_dir(agent_name).join(binary_name)
+                paths::agent_bin_dir(agent_name).join(binary_name)
             }
-            BinaryType::Agent => Config::agent_bin_dir(binary_name).join(binary_name),
+            BinaryType::Agent => paths::agent_bin_dir(binary_name).join(binary_name),
         };
         info!(
             "Building binary for function: {} ({})",
@@ -741,12 +812,12 @@ impl Functions {
             )
         })?;
         let content_template = unsafe { std::str::from_utf8_unchecked(&embedded_file.data) };
-        let content = match binary_type {
+        let mut content = match binary_type {
             BinaryType::Tool(None) => {
-                let root_dir = Config::functions_dir();
+                let root_dir = paths::functions_dir();
                 let tool_path = format!(
                     "{}/{binary_name}",
-                    &Config::global_tools_dir().to_string_lossy()
+                    &paths::global_tools_dir().to_string_lossy()
                 );
                 content_template
                     .replace("{function_name}", binary_name)
@@ -754,10 +825,10 @@ impl Functions {
                     .replace("{tool_path}", &tool_path)
             }
             BinaryType::Tool(Some(agent_name)) => {
-                let root_dir = Config::agent_data_dir(agent_name);
+                let root_dir = paths::agent_data_dir(agent_name);
                 let tool_path = format!(
                     "{}/{binary_name}",
-                    &Config::global_tools_dir().to_string_lossy()
+                    &paths::global_tools_dir().to_string_lossy()
                 );
                 content_template
                     .replace("{function_name}", binary_name)
@@ -766,19 +837,50 @@ impl Functions {
             }
             BinaryType::Agent => content_template
                 .replace("{agent_name}", binary_name)
-                .replace("{config_dir}", &Config::config_dir().to_string_lossy()),
+                .replace("{config_dir}", &paths::config_dir().to_string_lossy()),
         }
         .replace(
             "{prompt_utils_file}",
-            &Config::bash_prompt_utils_file().to_string_lossy(),
+            &paths::bash_prompt_utils_file().to_string_lossy(),
         );
-        if binary_file.exists() {
-            fs::remove_file(&binary_file)?;
-        }
-        let mut file = File::create(&binary_file)?;
-        file.write_all(content.as_bytes())?;
 
-        fs::set_permissions(&binary_file, fs::Permissions::from_mode(0o755))?;
+        if let Some(rt) = custom_runtime
+            && let Some(newline_pos) = content.find('\n')
+        {
+            content = format!("#!/usr/bin/env {rt}{}", &content[newline_pos..]);
+        }
+
+        if language == Language::TypeScript {
+            let bin_dir = binary_file
+                .parent()
+                .expect("Failed to get parent directory of binary file");
+            let script_file = bin_dir.join(format!("run-{binary_name}.ts"));
+            if script_file.exists() {
+                fs::remove_file(&script_file)?;
+            }
+            let mut sf = File::create(&script_file)?;
+            sf.write_all(content.as_bytes())?;
+            fs::set_permissions(&script_file, fs::Permissions::from_mode(0o755))?;
+
+            let ts_runtime = custom_runtime.unwrap_or("tsx");
+            let wrapper = format!(
+                "#!/bin/sh\nexec {ts_runtime} \"{}\" \"$@\"\n",
+                script_file.display()
+            );
+            if binary_file.exists() {
+                fs::remove_file(&binary_file)?;
+            }
+            let mut wf = File::create(&binary_file)?;
+            wf.write_all(wrapper.as_bytes())?;
+            fs::set_permissions(&binary_file, fs::Permissions::from_mode(0o755))?;
+        } else {
+            if binary_file.exists() {
+                fs::remove_file(&binary_file)?;
+            }
+            let mut file = File::create(&binary_file)?;
+            file.write_all(content.as_bytes())?;
+            fs::set_permissions(&binary_file, fs::Permissions::from_mode(0o755))?;
+        }
 
         Ok(())
     }
@@ -869,16 +971,15 @@ impl ToolCall {
         self
     }
 
-    pub async fn eval(&self, config: &GlobalConfig) -> Result<Value> {
-        let (call_name, cmd_name, mut cmd_args, envs) = match &config.read().agent {
-            Some(agent) => self.extract_call_config_from_agent(config, agent)?,
-            None => self.extract_call_config_from_config(config)?,
+    pub async fn eval(&self, ctx: &mut RequestContext) -> Result<Value> {
+        let agent = ctx.agent.clone();
+        let functions = ctx.tool_scope.functions.clone();
+        let current_depth = ctx.current_depth;
+        let agent_name = agent.as_ref().map(|agent| agent.name().to_owned());
+        let (call_name, cmd_name, mut cmd_args, envs) = match agent.as_ref() {
+            Some(agent) => self.extract_call_config_from_agent(&functions, agent)?,
+            None => self.extract_call_config_from_ctx(&functions)?,
         };
-        let agent_name = config
-            .read()
-            .agent
-            .as_ref()
-            .map(|agent| agent.name().to_owned());
 
         let json_data = if self.arguments.is_object() {
             self.arguments.clone()
@@ -898,20 +999,22 @@ impl ToolCall {
 
         let prompt = format!("Call {cmd_name} {}", cmd_args.join(" "));
 
-        if *IS_STDOUT_TERMINAL && config.read().current_depth == 0 {
+        if *IS_STDOUT_TERMINAL && current_depth == 0 {
             println!("{}", dimmed_text(&prompt));
         }
 
         let output = match cmd_name.as_str() {
             _ if cmd_name.starts_with(MCP_SEARCH_META_FUNCTION_NAME_PREFIX) => {
-                Self::search_mcp_tools(config, &cmd_name, &json_data).unwrap_or_else(|e| {
-                    let error_msg = format!("MCP search failed: {e}");
-                    eprintln!("{}", warning_text(&format!("⚠️ {error_msg} ⚠️")));
-                    json!({"tool_call_error": error_msg})
-                })
+                Self::search_mcp_tools(ctx, &cmd_name, &json_data)
+                    .await
+                    .unwrap_or_else(|e| {
+                        let error_msg = format!("MCP search failed: {e}");
+                        eprintln!("{}", warning_text(&format!("⚠️ {error_msg} ⚠️")));
+                        json!({"tool_call_error": error_msg})
+                    })
             }
             _ if cmd_name.starts_with(MCP_DESCRIBE_META_FUNCTION_NAME_PREFIX) => {
-                Self::describe_mcp_tool(config, &cmd_name, json_data)
+                Self::describe_mcp_tool(ctx, &cmd_name, json_data)
                     .await
                     .unwrap_or_else(|e| {
                         let error_msg = format!("MCP describe failed: {e}");
@@ -920,7 +1023,7 @@ impl ToolCall {
                     })
             }
             _ if cmd_name.starts_with(MCP_INVOKE_META_FUNCTION_NAME_PREFIX) => {
-                Self::invoke_mcp_tool(config, &cmd_name, &json_data)
+                Self::invoke_mcp_tool(ctx, &cmd_name, &json_data)
                     .await
                     .unwrap_or_else(|e| {
                         let error_msg = format!("MCP tool invocation failed: {e}");
@@ -929,14 +1032,14 @@ impl ToolCall {
                     })
             }
             _ if cmd_name.starts_with(TODO_FUNCTION_PREFIX) => {
-                todo::handle_todo_tool(config, &cmd_name, &json_data).unwrap_or_else(|e| {
+                todo::handle_todo_tool(ctx, &cmd_name, &json_data).unwrap_or_else(|e| {
                     let error_msg = format!("Todo tool failed: {e}");
                     eprintln!("{}", warning_text(&format!("⚠️ {error_msg} ⚠️")));
                     json!({"tool_call_error": error_msg})
                 })
             }
             _ if cmd_name.starts_with(SUPERVISOR_FUNCTION_PREFIX) => {
-                supervisor::handle_supervisor_tool(config, &cmd_name, &json_data)
+                supervisor::handle_supervisor_tool(ctx, &cmd_name, &json_data)
                     .await
                     .unwrap_or_else(|e| {
                         let error_msg = format!("Supervisor tool failed: {e}");
@@ -945,7 +1048,7 @@ impl ToolCall {
                     })
             }
             _ if cmd_name.starts_with(USER_FUNCTION_PREFIX) => {
-                user_interaction::handle_user_tool(config, &cmd_name, &json_data)
+                user_interaction::handle_user_tool(ctx, &cmd_name, &json_data)
                     .await
                     .unwrap_or_else(|e| {
                         let error_msg = format!("User interaction failed: {e}");
@@ -968,7 +1071,7 @@ impl ToolCall {
     }
 
     async fn describe_mcp_tool(
-        config: &GlobalConfig,
+        ctx: &RequestContext,
         cmd_name: &str,
         json_data: Value,
     ) -> Result<Value> {
@@ -978,18 +1081,19 @@ impl ToolCall {
             .ok_or_else(|| anyhow!("Missing 'tool' in arguments"))?
             .as_str()
             .ok_or_else(|| anyhow!("Invalid 'tool' in arguments"))?;
-        let registry_arc = {
-            let cfg = config.read();
-            cfg.mcp_registry
-                .clone()
-                .with_context(|| "MCP is not configured")?
-        };
-
-        let result = registry_arc.describe(&server_id, tool).await?;
+        let result = ctx
+            .tool_scope
+            .mcp_runtime
+            .describe(&server_id, tool)
+            .await?;
         Ok(serde_json::to_value(result)?)
     }
 
-    fn search_mcp_tools(config: &GlobalConfig, cmd_name: &str, json_data: &Value) -> Result<Value> {
+    async fn search_mcp_tools(
+        ctx: &RequestContext,
+        cmd_name: &str,
+        json_data: &Value,
+    ) -> Result<Value> {
         let server = cmd_name.replace(&format!("{MCP_SEARCH_META_FUNCTION_NAME_PREFIX}_"), "");
         let query = json_data
             .get("query")
@@ -1002,15 +1106,12 @@ impl ToolCall {
             .unwrap_or_else(|| Value::from(8u64))
             .as_u64()
             .ok_or_else(|| anyhow!("Invalid 'top_k' in arguments"))? as usize;
-        let registry_arc = {
-            let cfg = config.read();
-            cfg.mcp_registry
-                .clone()
-                .with_context(|| "MCP is not configured")?
-        };
 
-        let catalog_items = registry_arc
-            .search_tools_server(&server, query, top_k)
+        let catalog_items = ctx
+            .tool_scope
+            .mcp_runtime
+            .search(&server, query, top_k)
+            .await?
             .into_iter()
             .map(|it| serde_json::to_value(&it).unwrap_or_default())
             .collect();
@@ -1018,7 +1119,7 @@ impl ToolCall {
     }
 
     async fn invoke_mcp_tool(
-        config: &GlobalConfig,
+        ctx: &RequestContext,
         cmd_name: &str,
         json_data: &Value,
     ) -> Result<Value> {
@@ -1032,20 +1133,18 @@ impl ToolCall {
             .get("arguments")
             .cloned()
             .unwrap_or_else(|| json!({}));
-        let registry_arc = {
-            let cfg = config.read();
-            cfg.mcp_registry
-                .clone()
-                .with_context(|| "MCP is not configured")?
-        };
 
-        let result = registry_arc.invoke(&server, tool, arguments).await?;
+        let result = ctx
+            .tool_scope
+            .mcp_runtime
+            .invoke(&server, tool, arguments)
+            .await?;
         Ok(serde_json::to_value(result)?)
     }
 
     fn extract_call_config_from_agent(
         &self,
-        config: &GlobalConfig,
+        functions: &Functions,
         agent: &Agent,
     ) -> Result<CallConfig> {
         let function_name = self.name.clone();
@@ -1068,13 +1167,13 @@ impl ToolCall {
                     ))
                 }
             }
-            None => self.extract_call_config_from_config(config),
+            None => self.extract_call_config_from_ctx(functions),
         }
     }
 
-    fn extract_call_config_from_config(&self, config: &GlobalConfig) -> Result<CallConfig> {
+    fn extract_call_config_from_ctx(&self, functions: &Functions) -> Result<CallConfig> {
         let function_name = self.name.clone();
-        match config.read().functions.contains(&function_name) {
+        match functions.contains(&function_name) {
             true => Ok((
                 function_name.clone(),
                 function_name,
@@ -1096,12 +1195,12 @@ pub fn run_llm_function(
     let mut command_name = cmd_name.clone();
     if let Some(agent_name) = agent_name {
         command_name = cmd_args[0].clone();
-        let dir = Config::agent_bin_dir(&agent_name);
+        let dir = paths::agent_bin_dir(&agent_name);
         if dir.exists() {
             bin_dirs.push(dir);
         }
     } else {
-        bin_dirs.push(Config::functions_bin_dir());
+        bin_dirs.push(paths::functions_bin_dir());
     }
     let current_path = env::var("PATH").context("No PATH environment variable")?;
     let prepend_path = bin_dirs
@@ -1111,12 +1210,26 @@ pub fn run_llm_function(
         .join("");
     envs.insert("PATH".into(), format!("{prepend_path}{current_path}"));
 
-    let temp_file = temp_file("-eval-", "");
-    envs.insert("LLM_OUTPUT".into(), temp_file.display().to_string());
+    let tmp_file = temp_file("-eval-", "");
+    envs.insert("LLM_OUTPUT".into(), tmp_file.display().to_string());
 
     #[cfg(windows)]
     let cmd_name = polyfill_cmd_name(&cmd_name, &bin_dirs);
 
+    #[cfg(windows)]
+    let cmd_args = {
+        let mut args = cmd_args;
+        if let Some(json_data) = args.pop() {
+            let tool_data_file = temp_file("-tool-data-", ".json");
+            fs::write(&tool_data_file, &json_data)?;
+            envs.insert(
+                "LLM_TOOL_DATA_FILE".into(),
+                tool_data_file.display().to_string(),
+            );
+        }
+        args
+    };
+
     envs.insert("CLICOLOR_FORCE".into(), "1".into());
     envs.insert("FORCE_COLOR".into(), "1".into());
 
@@ -1183,9 +1296,9 @@ pub fn run_llm_function(
         return Ok(Some(error_json.to_string()));
     }
     let mut output = None;
-    if temp_file.exists() {
+    if tmp_file.exists() {
         let contents =
-            fs::read_to_string(temp_file).context("Failed to retrieve tool call output")?;
+            fs::read_to_string(tmp_file).context("Failed to retrieve tool call output")?;
         if !contents.is_empty() {
             debug!("Tool {command_name} output: {}", contents);
             output = Some(contents);
@@ -1303,3 +1416,354 @@ impl ToolCallTracker {
         self.last_calls.push_back(call);
     }
 }
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use serde_json::json;
+
+    fn call(name: &str, id: Option<&str>) -> ToolCall {
+        ToolCall::new(name.to_string(), json!({}), id.map(|s| s.to_string()))
+    }
+
+    fn call_with_args(name: &str, args: Value) -> ToolCall {
+        ToolCall::new(name.to_string(), args, Some("id1".to_string()))
+    }
+
+    #[test]
+    fn toolcall_new_sets_fields() {
+        let tc = ToolCall::new("my_tool".into(), json!({"x": 1}), Some("call-1".into()));
+        assert_eq!(tc.name, "my_tool");
+        assert_eq!(tc.arguments, json!({"x": 1}));
+        assert_eq!(tc.id, Some("call-1".to_string()));
+        assert!(tc.thought_signature.is_none());
+    }
+
+    #[test]
+    fn toolcall_default_has_empty_fields() {
+        let tc = ToolCall::default();
+        assert_eq!(tc.name, "");
+        assert_eq!(tc.arguments, Value::Null);
+        assert!(tc.id.is_none());
+        assert!(tc.thought_signature.is_none());
+    }
+
+    #[test]
+    fn direct_invoker_maps_each_language() {
+        assert_eq!(
+            Language::Bash.direct_invoker(),
+            Some(("bash", &[] as &[&str]))
+        );
+        assert_eq!(
+            Language::Python.direct_invoker(),
+            Some(("python3", &[] as &[&str]))
+        );
+        assert_eq!(
+            Language::TypeScript.direct_invoker(),
+            Some(("npx", &["tsx"] as &[&str]))
+        );
+        assert_eq!(Language::Unsupported.direct_invoker(), None);
+    }
+
+    #[test]
+    fn toolcall_with_thought_signature() {
+        let tc = ToolCall::new("t".into(), json!({}), None)
+            .with_thought_signature(Some("sig123".into()));
+        assert_eq!(tc.thought_signature, Some("sig123".to_string()));
+    }
+
+    #[test]
+    fn toolcall_with_thought_signature_none() {
+        let tc = ToolCall::new("t".into(), json!({}), None).with_thought_signature(None);
+        assert!(tc.thought_signature.is_none());
+    }
+
+    #[test]
+    fn dedup_keeps_unique_ids() {
+        let calls = vec![call("tool_a", Some("id-1")), call("tool_b", Some("id-2"))];
+        let result = ToolCall::dedup(calls);
+        assert_eq!(result.len(), 2);
+    }
+
+    #[test]
+    fn dedup_keeps_calls_without_ids() {
+        let calls = vec![call("tool_a", None), call("tool_b", None)];
+        let result = ToolCall::dedup(calls);
+        assert_eq!(result.len(), 2);
+    }
+
+    #[test]
+    fn dedup_removes_duplicate_ids_keeps_last() {
+        let calls = vec![call("tool_a", Some("id-1")), call("tool_b", Some("id-1"))];
+        let result = ToolCall::dedup(calls);
+        assert_eq!(result.len(), 1);
+        assert_eq!(result[0].name, "tool_b");
+    }
+
+    #[test]
+    fn dedup_empty_input_returns_empty() {
+        let result = ToolCall::dedup(vec![]);
+        assert!(result.is_empty());
+    }
+
+    #[test]
+    fn dedup_mixed_with_and_without_ids() {
+        let calls = vec![
+            call("a", Some("id-1")),
+            call("b", None),
+            call("c", Some("id-1")),
+            call("d", None),
+        ];
+        let result = ToolCall::dedup(calls);
+        assert_eq!(result.len(), 3);
+        assert_eq!(result[0].name, "b");
+        assert_eq!(result[1].name, "c");
+        assert_eq!(result[2].name, "d");
+    }
+
+    #[test]
+    fn tracker_default_values() {
+        let tracker = ToolCallTracker::default();
+        assert_eq!(tracker.max_repeats, 2);
+        assert_eq!(tracker.chain_len, 3);
+        assert!(tracker.last_calls.is_empty());
+    }
+
+    #[test]
+    fn tracker_no_loop_on_fresh_tracker() {
+        let tracker = ToolCallTracker::default();
+        assert!(tracker.check_loop(&call("tool", None)).is_none());
+    }
+
+    #[test]
+    fn tracker_no_loop_below_threshold() {
+        let mut tracker = ToolCallTracker::new(3, 5);
+        let c = call_with_args("tool", json!({"a": 1}));
+        tracker.record_call(c.clone());
+        tracker.record_call(c.clone());
+        assert!(tracker.check_loop(&c).is_none());
+    }
+
+    #[test]
+    fn tracker_detects_loop_at_max_repeats() {
+        let mut tracker = ToolCallTracker::new(2, 3);
+        let c = call_with_args("tool", json!({"a": 1}));
+        tracker.record_call(c.clone());
+        tracker.record_call(c.clone());
+        let result = tracker.check_loop(&c);
+        assert!(result.is_some());
+        assert!(result.unwrap().contains("loop"));
+    }
+
+    #[test]
+    fn tracker_different_args_no_loop() {
+        let mut tracker = ToolCallTracker::new(2, 3);
+        tracker.record_call(call_with_args("tool", json!({"a": 1})));
+        tracker.record_call(call_with_args("tool", json!({"a": 2})));
+        let new_call = call_with_args("tool", json!({"a": 3}));
+        assert!(tracker.check_loop(&new_call).is_none());
+    }
+
+    #[test]
+    fn tracker_different_names_no_loop() {
+        let mut tracker = ToolCallTracker::new(2, 3);
+        tracker.record_call(call_with_args("tool_a", json!({})));
+        tracker.record_call(call_with_args("tool_b", json!({})));
+        let new_call = call_with_args("tool_a", json!({}));
+        assert!(tracker.check_loop(&new_call).is_none());
+    }
+
+    #[test]
+    fn tracker_chain_detection() {
+        let mut tracker = ToolCallTracker::new(2, 3);
+        let c = call_with_args("tool", json!({"x": "same"}));
+        tracker.record_call(c.clone());
+        tracker.record_call(c.clone());
+        tracker.record_call(c.clone());
+        let result = tracker.check_loop(&c);
+        assert!(result.is_some());
+    }
+
+    #[test]
+    fn tracker_record_call_respects_capacity() {
+        let mut tracker = ToolCallTracker::new(2, 2);
+        for i in 0..10 {
+            tracker.record_call(call_with_args(&format!("tool_{i}"), json!({})));
+        }
+        assert!(tracker.last_calls.len() <= 2 * 2);
+    }
+
+    #[test]
+    fn tracker_loop_message_contains_call_history() {
+        let mut tracker = ToolCallTracker::new(2, 3);
+        let c = call_with_args("repeat_tool", json!({"k": "v"}));
+        tracker.record_call(c.clone());
+        tracker.record_call(c.clone());
+        tracker.record_call(c.clone());
+        let msg = tracker.check_loop(&c).unwrap();
+        assert!(msg.contains("call_history"));
+        assert!(msg.contains("repeat_tool"));
+    }
+
+    #[test]
+    fn prefix_constants_are_correct() {
+        assert_eq!(TODO_FUNCTION_PREFIX, "todo__");
+        assert_eq!(SUPERVISOR_FUNCTION_PREFIX, "agent__");
+        assert_eq!(USER_FUNCTION_PREFIX, "user__");
+        assert_eq!(MCP_INVOKE_META_FUNCTION_NAME_PREFIX, "mcp_invoke");
+        assert_eq!(MCP_SEARCH_META_FUNCTION_NAME_PREFIX, "mcp_search");
+        assert_eq!(MCP_DESCRIBE_META_FUNCTION_NAME_PREFIX, "mcp_describe");
+    }
+
+    #[test]
+    fn functions_default_is_empty() {
+        let f = Functions::default();
+        assert!(f.is_empty());
+        assert!(f.declarations().is_empty());
+    }
+
+    #[test]
+    fn functions_append_todo_adds_declarations() {
+        let mut f = Functions::default();
+        f.append_todo_functions();
+        assert!(!f.is_empty());
+        assert!(f.contains("todo__init"));
+        assert!(f.contains("todo__add"));
+        assert!(f.contains("todo__done"));
+        assert!(f.contains("todo__list"));
+        assert!(f.contains("todo__clear"));
+    }
+
+    #[test]
+    fn functions_append_supervisor_adds_declarations() {
+        let mut f = Functions::default();
+        f.append_supervisor_functions();
+        assert!(f.contains("agent__spawn"));
+        assert!(f.contains("agent__check"));
+        assert!(f.contains("agent__collect"));
+        assert!(f.contains("agent__list"));
+        assert!(f.contains("agent__cancel"));
+        assert!(f.contains("agent__reply_escalation"));
+    }
+
+    #[test]
+    fn functions_append_teammate_adds_declarations() {
+        let mut f = Functions::default();
+        f.append_teammate_functions();
+        assert!(f.contains("agent__send_message"));
+        assert!(f.contains("agent__check_inbox"));
+    }
+
+    #[test]
+    fn functions_append_user_interaction_adds_declarations() {
+        let mut f = Functions::default();
+        f.append_user_interaction_functions();
+        assert!(f.contains("user__ask"));
+        assert!(f.contains("user__confirm"));
+        assert!(f.contains("user__input"));
+        assert!(f.contains("user__checkbox"));
+    }
+
+    #[test]
+    fn functions_append_mcp_meta_creates_three_per_server() {
+        let mut f = Functions::default();
+        f.append_mcp_meta_functions(vec!["github".to_string()]);
+        assert_eq!(f.declarations().len(), 3);
+        assert!(f.contains("mcp_invoke_github"));
+        assert!(f.contains("mcp_search_github"));
+        assert!(f.contains("mcp_describe_github"));
+    }
+
+    #[test]
+    fn functions_append_mcp_meta_multiple_servers() {
+        let mut f = Functions::default();
+        f.append_mcp_meta_functions(vec!["github".into(), "slack".into()]);
+        assert_eq!(f.declarations().len(), 6);
+        assert!(f.contains("mcp_invoke_github"));
+        assert!(f.contains("mcp_invoke_slack"));
+    }
+
+    #[test]
+    fn functions_append_mcp_meta_empty_servers() {
+        let mut f = Functions::default();
+        f.append_mcp_meta_functions(vec![]);
+        assert!(f.is_empty());
+    }
+
+    #[test]
+    fn functions_find_returns_declaration() {
+        let mut f = Functions::default();
+        f.append_todo_functions();
+        let decl = f.find("todo__init");
+        assert!(decl.is_some());
+        assert_eq!(decl.unwrap().name, "todo__init");
+    }
+
+    #[test]
+    fn functions_find_returns_none_for_missing() {
+        let f = Functions::default();
+        assert!(f.find("nonexistent").is_none());
+    }
+
+    #[test]
+    fn functions_contains_true_for_existing() {
+        let mut f = Functions::default();
+        f.append_todo_functions();
+        assert!(f.contains("todo__init"));
+    }
+
+    #[test]
+    fn functions_contains_false_for_missing() {
+        let f = Functions::default();
+        assert!(!f.contains("todo__init"));
+    }
+
+    #[test]
+    fn functions_mcp_invoke_declaration_has_tool_and_arguments_params() {
+        let mut f = Functions::default();
+        f.append_mcp_meta_functions(vec!["srv".to_string()]);
+        let decl = f.find("mcp_invoke_srv").unwrap();
+        let props = decl.parameters.properties.as_ref().unwrap();
+        assert!(props.contains_key("tool"));
+        assert!(props.contains_key("arguments"));
+        let required = decl.parameters.required.as_ref().unwrap();
+        assert!(required.contains(&"tool".to_string()));
+    }
+
+    #[test]
+    fn functions_mcp_search_declaration_has_query_and_top_k_params() {
+        let mut f = Functions::default();
+        f.append_mcp_meta_functions(vec!["srv".to_string()]);
+        let decl = f.find("mcp_search_srv").unwrap();
+        let props = decl.parameters.properties.as_ref().unwrap();
+        assert!(props.contains_key("query"));
+        assert!(props.contains_key("top_k"));
+    }
+
+    #[test]
+    fn functions_mcp_describe_declaration_has_tool_param() {
+        let mut f = Functions::default();
+        f.append_mcp_meta_functions(vec!["srv".to_string()]);
+        let decl = f.find("mcp_describe_srv").unwrap();
+        let props = decl.parameters.properties.as_ref().unwrap();
+        assert!(props.contains_key("tool"));
+    }
+
+    #[test]
+    fn functions_supervisor_includes_task_queue_tools() {
+        let mut f = Functions::default();
+        f.append_supervisor_functions();
+        assert!(f.contains("agent__task_create"));
+        assert!(f.contains("agent__task_list"));
+        assert!(f.contains("agent__task_complete"));
+        assert!(f.contains("agent__task_fail"));
+    }
+
+    #[test]
+    fn tool_result_stores_call_and_output() {
+        let tc = call("my_tool", Some("id-1"));
+        let result = ToolResult::new(tc.clone(), json!({"result": "ok"}));
+        assert_eq!(result.call.name, "my_tool");
+        assert_eq!(result.output, json!({"result": "ok"}));
+    }
+}
diff --git a/src/function/supervisor.rs b/src/function/supervisor.rs
index ec73f20..fa76afd 100644
--- a/src/function/supervisor.rs
+++ b/src/function/supervisor.rs
@@ -1,12 +1,12 @@
 use super::{FunctionDeclaration, JsonSchema};
 use crate::client::{Model, ModelType, call_chat_completions};
-use crate::config::{Config, GlobalConfig, Input, Role, RoleLike};
-use crate::supervisor::escalation::EscalationQueue;
+use crate::config::{Agent, AppState, Input, RequestContext, Role, RoleLike};
 use crate::supervisor::mailbox::{Envelope, EnvelopePayload, Inbox};
-use crate::supervisor::{AgentExitStatus, AgentHandle, AgentResult};
+use crate::supervisor::{AgentExitStatus, AgentHandle, AgentResult, Supervisor};
 use crate::utils::{AbortSignal, create_abort_signal};
 
-use anyhow::{Result, anyhow, bail};
+use crate::graph;
+use anyhow::{Context, Result, anyhow, bail};
 use chrono::Utc;
 use indexmap::IndexMap;
 use log::debug;
@@ -14,6 +14,8 @@ use parking_lot::RwLock;
 use serde_json::{Value, json};
 use std::pin::Pin;
 use std::sync::Arc;
+use std::time::Duration;
+use tokio::time;
 use uuid::Uuid;
 
 pub const SUPERVISOR_FUNCTION_PREFIX: &str = "agent__";
@@ -300,7 +302,7 @@ pub fn teammate_function_declarations() -> Vec<FunctionDeclaration> {
 }
 
 pub async fn handle_supervisor_tool(
-    config: &GlobalConfig,
+    ctx: &mut RequestContext,
     cmd_name: &str,
     args: &Value,
 ) -> Result<Value> {
@@ -309,42 +311,56 @@ pub async fn handle_supervisor_tool(
         .unwrap_or(cmd_name);
 
     match action {
-        "spawn" => handle_spawn(config, args).await,
-        "check" => handle_check(config, args).await,
-        "collect" => handle_collect(config, args).await,
-        "list" => handle_list(config),
-        "cancel" => handle_cancel(config, args),
-        "send_message" => handle_send_message(config, args),
-        "check_inbox" => handle_check_inbox(config),
-        "task_create" => handle_task_create(config, args),
-        "task_list" => handle_task_list(config),
-        "task_complete" => handle_task_complete(config, args).await,
-        "task_fail" => handle_task_fail(config, args),
-        "reply_escalation" => handle_reply_escalation(config, args),
+        "spawn" => handle_spawn(ctx, args).await,
+        "check" => handle_check(ctx, args).await,
+        "collect" => handle_collect(ctx, args).await,
+        "list" => handle_list(ctx),
+        "cancel" => handle_cancel(ctx, args),
+        "send_message" => handle_send_message(ctx, args),
+        "check_inbox" => handle_check_inbox(ctx),
+        "task_create" => handle_task_create(ctx, args),
+        "task_list" => handle_task_list(ctx),
+        "task_complete" => handle_task_complete(ctx, args).await,
+        "task_fail" => handle_task_fail(ctx, args),
+        "reply_escalation" => handle_reply_escalation(ctx, args),
         _ => bail!("Unknown supervisor action: {action}"),
     }
 }
 
-fn run_child_agent(
-    child_config: GlobalConfig,
+pub fn run_child_agent(
+    mut child_ctx: RequestContext,
     initial_input: Input,
     abort_signal: AbortSignal,
 ) -> Pin<Box<dyn Future<Output = Result<String>> + Send>> {
     Box::pin(async move {
+        if graph::active_agent_graph_name(&child_ctx).is_some() {
+            return graph::run_active_agent_graph(
+                &mut child_ctx,
+                &initial_input.text(),
+                abort_signal,
+            )
+            .await;
+        }
+
         let mut accumulated_output = String::new();
         let mut input = initial_input;
+        let app = Arc::clone(&child_ctx.app.config);
 
         loop {
             let client = input.create_client()?;
-            child_config.write().before_chat_completion(&input)?;
+            child_ctx.before_chat_completion(&input)?;
 
-            let (output, tool_results) =
-                call_chat_completions(&input, false, false, client.as_ref(), abort_signal.clone())
-                    .await?;
+            let (output, tool_results) = call_chat_completions(
+                &input,
+                false,
+                false,
+                client.as_ref(),
+                &mut child_ctx,
+                abort_signal.clone(),
+            )
+            .await?;
 
-            child_config
-                .write()
-                .after_chat_completion(&input, &output, &tool_results)?;
+            child_ctx.after_chat_completion(app.as_ref(), &input, &output, &tool_results)?;
 
             if !output.is_empty() {
                 if !accumulated_output.is_empty() {
@@ -360,7 +376,7 @@ fn run_child_agent(
             input = input.merge_tool_results(output, tool_results);
         }
 
-        if let Some(ref supervisor) = child_config.read().supervisor {
+        if let Some(supervisor) = child_ctx.supervisor.clone() {
             supervisor.read().cancel_all();
         }
 
@@ -368,7 +384,150 @@ fn run_child_agent(
     })
 }
 
-async fn handle_spawn(config: &GlobalConfig, args: &Value) -> Result<Value> {
+/// Spawn an agent synchronously from a graph node and return its accumulated
+/// output. This is similar to `handle_spawn` but runs the child agent in the
+/// current task (no tokio::spawn, no supervisor handle registration) so the
+/// graph executor can sequence agent nodes directly.
+pub async fn run_agent_for_graph(
+    parent_ctx: &mut RequestContext,
+    agent_name: &str,
+    prompt: &str,
+) -> Result<String> {
+    let short_uuid = &Uuid::new_v4().to_string()[..8];
+    let agent_id = format!("graph_agent_{agent_name}_{short_uuid}");
+    let current_depth = parent_ctx.current_depth + 1;
+
+    if let Some(supervisor) = parent_ctx.supervisor.as_ref().cloned() {
+        let max_depth = supervisor.read().max_depth();
+        if current_depth > max_depth {
+            bail!("Max agent depth exceeded ({current_depth}/{max_depth})");
+        }
+    }
+
+    if !parent_ctx.app.config.function_calling_support {
+        bail!("Function calling support must be enabled to spawn agents.");
+    }
+
+    let child_inbox = Arc::new(Inbox::new());
+    parent_ctx.ensure_root_escalation_queue();
+    let child_abort = create_abort_signal();
+
+    let app_config = Arc::clone(&parent_ctx.app.config);
+    let current_model = parent_ctx.current_model().clone();
+    let info_flag = parent_ctx.info_flag;
+    let child_app_state = Arc::new(AppState {
+        config: Arc::new(app_config.as_ref().clone()),
+        vault: parent_ctx.app.vault.clone(),
+        mcp_factory: parent_ctx.app.mcp_factory.clone(),
+        rag_cache: parent_ctx.app.rag_cache.clone(),
+        mcp_config: parent_ctx.app.mcp_config.clone(),
+        mcp_log_path: parent_ctx.app.mcp_log_path.clone(),
+        mcp_registry: parent_ctx.app.mcp_registry.clone(),
+        functions: parent_ctx.app.functions.clone(),
+    });
+
+    let agent = Agent::init(
+        app_config.as_ref(),
+        child_app_state.as_ref(),
+        &current_model,
+        info_flag,
+        agent_name,
+        child_abort.clone(),
+    )
+    .await?;
+
+    let agent_mcp_servers = agent.mcp_server_names().to_vec();
+    let session = agent.agent_session().map(|v| v.to_string());
+    let should_init_supervisor = agent.can_spawn_agents();
+    let agent_max_concurrent = agent.max_concurrent_agents();
+    let agent_max_depth = agent.max_agent_depth();
+
+    let mut child_ctx = RequestContext::new_for_child(
+        Arc::clone(&child_app_state),
+        parent_ctx,
+        current_depth,
+        Arc::clone(&child_inbox),
+        agent_id.clone(),
+    );
+    child_ctx.rag = agent.rag();
+    child_ctx.agent = Some(agent);
+    if should_init_supervisor {
+        child_ctx.supervisor = Some(Arc::new(RwLock::new(Supervisor::new(
+            agent_max_concurrent,
+            agent_max_depth,
+        ))));
+    }
+
+    if let Some(session) = session {
+        child_ctx
+            .use_session(app_config.as_ref(), Some(&session), child_abort.clone())
+            .await?;
+        sync_agent_functions_to_ctx(&mut child_ctx)?;
+    } else {
+        populate_agent_mcp_runtime(&mut child_ctx, &agent_mcp_servers).await?;
+        sync_agent_functions_to_ctx(&mut child_ctx)?;
+        child_ctx.init_agent_shared_variables()?;
+    }
+
+    let input = Input::from_str(&child_ctx, prompt, None);
+
+    debug!("Spawning agent '{agent_name}' for graph node as '{agent_id}'");
+
+    run_child_agent(child_ctx, input, child_abort).await
+}
+
+async fn populate_agent_mcp_runtime(ctx: &mut RequestContext, server_ids: &[String]) -> Result<()> {
+    if !ctx.app.config.mcp_server_support {
+        return Ok(());
+    }
+
+    let app = Arc::clone(&ctx.app);
+    let server_specs = app
+        .mcp_config
+        .as_ref()
+        .map(|mcp_config| {
+            server_ids
+                .iter()
+                .filter_map(|id| {
+                    mcp_config
+                        .mcp_servers
+                        .get(id)
+                        .cloned()
+                        .map(|spec| (id.clone(), spec))
+                })
+                .collect::<Vec<_>>()
+        })
+        .unwrap_or_default();
+
+    for (id, spec) in server_specs {
+        let handle = app
+            .mcp_factory
+            .acquire(&id, &spec, app.mcp_log_path.as_deref())
+            .await?;
+        ctx.tool_scope.mcp_runtime.insert(id, handle);
+    }
+
+    Ok(())
+}
+
+fn sync_agent_functions_to_ctx(ctx: &mut RequestContext) -> Result<()> {
+    let server_names = ctx.tool_scope.mcp_runtime.server_names();
+    let functions = {
+        let agent = ctx
+            .agent
+            .as_mut()
+            .with_context(|| "Agent should be initialized")?;
+        if !server_names.is_empty() {
+            agent.append_mcp_meta_functions(server_names);
+        }
+        agent.functions().clone()
+    };
+
+    ctx.tool_scope.functions = functions;
+    Ok(())
+}
+
+async fn handle_spawn(ctx: &mut RequestContext, args: &Value) -> Result<Value> {
     let agent_name = args
         .get("agent")
         .and_then(Value::as_str)
@@ -385,10 +544,10 @@ async fn handle_spawn(config: &GlobalConfig, args: &Value) -> Result<Value> {
     let agent_id = format!("agent_{agent_name}_{short_uuid}");
 
     let (max_depth, current_depth) = {
-        let cfg = config.read();
-        let supervisor = cfg
+        let supervisor = ctx
             .supervisor
             .as_ref()
+            .cloned()
             .ok_or_else(|| anyhow!("No supervisor active; Agent spawning not enabled"))?;
         let sup = supervisor.read();
         if sup.active_count() >= sup.max_concurrent() {
@@ -401,7 +560,7 @@ async fn handle_spawn(config: &GlobalConfig, args: &Value) -> Result<Value> {
                 ),
             }));
         }
-        (sup.max_depth(), cfg.current_depth + 1)
+        (sup.max_depth(), ctx.current_depth + 1)
     };
 
     if current_depth > max_depth {
@@ -413,37 +572,70 @@ async fn handle_spawn(config: &GlobalConfig, args: &Value) -> Result<Value> {
 
     let child_inbox = Arc::new(Inbox::new());
 
-    {
-        let mut cfg = config.write();
-        if cfg.root_escalation_queue.is_none() {
-            cfg.root_escalation_queue = Some(Arc::new(EscalationQueue::new()));
-        }
-    }
-
-    let child_config: GlobalConfig = {
-        let mut child_cfg = config.read().clone();
-
-        child_cfg.parent_supervisor = child_cfg.supervisor.clone();
-        child_cfg.agent = None;
-        child_cfg.session = None;
-        child_cfg.rag = None;
-        child_cfg.supervisor = None;
-        child_cfg.last_message = None;
-        child_cfg.tool_call_tracker = None;
-
-        child_cfg.stream = false;
-        child_cfg.save = false;
-        child_cfg.current_depth = current_depth;
-        child_cfg.inbox = Some(Arc::clone(&child_inbox));
-        child_cfg.self_agent_id = Some(agent_id.clone());
-
-        Arc::new(RwLock::new(child_cfg))
-    };
+    ctx.ensure_root_escalation_queue();
 
     let child_abort = create_abort_signal();
-    Config::use_agent(&child_config, &agent_name, None, child_abort.clone()).await?;
 
-    let input = Input::from_str(&child_config, &prompt, None);
+    if !ctx.app.config.function_calling_support {
+        bail!("Please enable function calling support before using the agent.");
+    }
+
+    let app_config = Arc::clone(&ctx.app.config);
+    let current_model = ctx.current_model().clone();
+    let info_flag = ctx.info_flag;
+    let child_app_state = Arc::new(AppState {
+        config: Arc::new(app_config.as_ref().clone()),
+        vault: ctx.app.vault.clone(),
+        mcp_factory: ctx.app.mcp_factory.clone(),
+        rag_cache: ctx.app.rag_cache.clone(),
+        mcp_config: ctx.app.mcp_config.clone(),
+        mcp_log_path: ctx.app.mcp_log_path.clone(),
+        mcp_registry: ctx.app.mcp_registry.clone(),
+        functions: ctx.app.functions.clone(),
+    });
+    let agent = Agent::init(
+        app_config.as_ref(),
+        child_app_state.as_ref(),
+        &current_model,
+        info_flag,
+        &agent_name,
+        child_abort.clone(),
+    )
+    .await?;
+
+    let agent_mcp_servers = agent.mcp_server_names().to_vec();
+    let session = agent.agent_session().map(|v| v.to_string());
+    let should_init_supervisor = agent.can_spawn_agents();
+    let max_concurrent = agent.max_concurrent_agents();
+    let max_depth = agent.max_agent_depth();
+    let mut child_ctx = RequestContext::new_for_child(
+        Arc::clone(&child_app_state),
+        ctx,
+        current_depth,
+        Arc::clone(&child_inbox),
+        agent_id.clone(),
+    );
+    child_ctx.rag = agent.rag();
+    child_ctx.agent = Some(agent);
+    if should_init_supervisor {
+        child_ctx.supervisor = Some(Arc::new(RwLock::new(Supervisor::new(
+            max_concurrent,
+            max_depth,
+        ))));
+    }
+
+    if let Some(session) = session {
+        child_ctx
+            .use_session(app_config.as_ref(), Some(&session), child_abort.clone())
+            .await?;
+        sync_agent_functions_to_ctx(&mut child_ctx)?;
+    } else {
+        populate_agent_mcp_runtime(&mut child_ctx, &agent_mcp_servers).await?;
+        sync_agent_functions_to_ctx(&mut child_ctx)?;
+        child_ctx.init_agent_shared_variables()?;
+    }
+
+    let input = Input::from_str(&child_ctx, &prompt, None);
 
     debug!("Spawning child agent '{agent_name}' as '{agent_id}'");
 
@@ -452,7 +644,7 @@ async fn handle_spawn(config: &GlobalConfig, args: &Value) -> Result<Value> {
     let spawn_abort = child_abort.clone();
 
     let join_handle = tokio::spawn(async move {
-        let result = run_child_agent(child_config, input, spawn_abort).await;
+        let result = run_child_agent(child_ctx, input, spawn_abort).await;
 
         match result {
             Ok(output) => Ok(AgentResult {
@@ -479,15 +671,13 @@ async fn handle_spawn(config: &GlobalConfig, args: &Value) -> Result<Value> {
         join_handle,
     };
 
-    {
-        let cfg = config.read();
-        let supervisor = cfg
-            .supervisor
-            .as_ref()
-            .ok_or_else(|| anyhow!("No supervisor active"))?;
-        let mut sup = supervisor.write();
-        sup.register(handle)?;
-    }
+    let supervisor = ctx
+        .supervisor
+        .as_ref()
+        .cloned()
+        .ok_or_else(|| anyhow!("No supervisor active"))?;
+    let mut sup = supervisor.write();
+    sup.register(handle)?;
 
     Ok(json!({
         "status": "ok",
@@ -497,29 +687,43 @@ async fn handle_spawn(config: &GlobalConfig, args: &Value) -> Result<Value> {
     }))
 }
 
-async fn handle_check(config: &GlobalConfig, args: &Value) -> Result<Value> {
+async fn handle_check(ctx: &mut RequestContext, args: &Value) -> Result<Value> {
     let id = args
         .get("id")
         .and_then(Value::as_str)
         .ok_or_else(|| anyhow!("'id' is required"))?;
 
     let is_finished = {
-        let cfg = config.read();
-        let supervisor = cfg
+        let supervisor = ctx
             .supervisor
             .as_ref()
+            .cloned()
             .ok_or_else(|| anyhow!("No supervisor active"))?;
         let sup = supervisor.read();
         sup.is_finished(id)
     };
 
     match is_finished {
-        Some(true) => handle_collect(config, args).await,
-        Some(false) => Ok(json!({
-            "status": "pending",
-            "id": id,
-            "message": "Agent is still running"
-        })),
+        Some(true) => handle_collect(ctx, args).await,
+        Some(false) => {
+            let mut result = json!({
+                "status": "pending",
+                "id": id,
+                "message": "Agent is still running"
+            });
+
+            if let Some(queue) = ctx.root_escalation_queue()
+                && queue.has_pending()
+            {
+                let summary = queue.pending_summary();
+                result["pending_escalations"] = json!(summary);
+                result["message"] = json!(
+                    "Agent is still running. Child agents have pending escalations that need your reply via agent__reply_escalation."
+                );
+            }
+
+            Ok(result)
+        }
         None => Ok(json!({
             "status": "error",
             "message": format!("No agent found with id '{id}'")
@@ -527,18 +731,54 @@ async fn handle_check(config: &GlobalConfig, args: &Value) -> Result<Value> {
     }
 }
 
-async fn handle_collect(config: &GlobalConfig, args: &Value) -> Result<Value> {
+async fn handle_collect(ctx: &mut RequestContext, args: &Value) -> Result<Value> {
     let id = args
         .get("id")
         .and_then(Value::as_str)
         .ok_or_else(|| anyhow!("'id' is required"))?;
 
+    let supervisor = ctx
+        .supervisor
+        .as_ref()
+        .cloned()
+        .ok_or_else(|| anyhow!("No supervisor active"))?;
+
+    {
+        let sup = supervisor.read();
+        if sup.is_finished(id).is_none() {
+            return Ok(json!({
+                "status": "error",
+                "message": format!("Agent '{id}' not found. Use agent__check to verify it exists and is finished.")
+            }));
+        }
+    }
+
+    loop {
+        let is_finished = {
+            let sup = supervisor.read();
+            sup.is_finished(id).unwrap_or(false)
+        };
+
+        if is_finished {
+            break;
+        }
+
+        if let Some(queue) = ctx.root_escalation_queue()
+            && queue.has_pending()
+        {
+            let summary = queue.pending_summary();
+            return Ok(json!({
+                "status": "pending",
+                "id": id,
+                "message": format!("Agent '{id}' is still running, but child agents have pending escalations that need your reply. Reply via agent__reply_escalation, then call agent__collect again."),
+                "pending_escalations": summary,
+            }));
+        }
+
+        time::sleep(Duration::from_millis(200)).await;
+    }
+
     let handle = {
-        let cfg = config.read();
-        let supervisor = cfg
-            .supervisor
-            .as_ref()
-            .ok_or_else(|| anyhow!("No supervisor active"))?;
         let mut sup = supervisor.write();
         sup.take(id)
     };
@@ -551,7 +791,7 @@ async fn handle_collect(config: &GlobalConfig, args: &Value) -> Result<Value> {
                 .map_err(|e| anyhow!("Agent task panicked: {e}"))?
                 .map_err(|e| anyhow!("Agent failed: {e}"))?;
 
-            let output = summarize_output(config, &result.agent_name, &result.output).await?;
+            let output = summarize_output(ctx, &result.agent_name, &result.output).await?;
 
             Ok(json!({
                 "status": "completed",
@@ -563,16 +803,16 @@ async fn handle_collect(config: &GlobalConfig, args: &Value) -> Result<Value> {
         }
         None => Ok(json!({
             "status": "error",
-            "message": format!("Agent '{id}' not found. Use agent__check to verify it exists and is finished.")
+            "message": format!("Agent '{id}' completed but could not be collected. It may have been collected by another call.")
         })),
     }
 }
 
-fn handle_list(config: &GlobalConfig) -> Result<Value> {
-    let cfg = config.read();
-    let supervisor = cfg
+fn handle_list(ctx: &mut RequestContext) -> Result<Value> {
+    let supervisor = ctx
         .supervisor
         .as_ref()
+        .cloned()
         .ok_or_else(|| anyhow!("No supervisor active"))?;
     let sup = supervisor.read();
 
@@ -596,16 +836,16 @@ fn handle_list(config: &GlobalConfig) -> Result<Value> {
     }))
 }
 
-fn handle_cancel(config: &GlobalConfig, args: &Value) -> Result<Value> {
+fn handle_cancel(ctx: &mut RequestContext, args: &Value) -> Result<Value> {
     let id = args
         .get("id")
         .and_then(Value::as_str)
         .ok_or_else(|| anyhow!("'id' is required"))?;
 
-    let cfg = config.read();
-    let supervisor = cfg
+    let supervisor = ctx
         .supervisor
         .as_ref()
+        .cloned()
         .ok_or_else(|| anyhow!("No supervisor active"))?;
     let mut sup = supervisor.write();
 
@@ -624,7 +864,7 @@ fn handle_cancel(config: &GlobalConfig, args: &Value) -> Result<Value> {
     }
 }
 
-fn handle_send_message(config: &GlobalConfig, args: &Value) -> Result<Value> {
+fn handle_send_message(ctx: &mut RequestContext, args: &Value) -> Result<Value> {
     let id = args
         .get("id")
         .and_then(Value::as_str)
@@ -634,24 +874,19 @@ fn handle_send_message(config: &GlobalConfig, args: &Value) -> Result<Value> {
         .and_then(Value::as_str)
         .ok_or_else(|| anyhow!("'message' is required"))?;
 
-    let cfg = config.read();
-
-    // Determine sender identity: self_agent_id (child), agent name (parent), or "parent"
-    let sender = cfg
+    let sender = ctx
         .self_agent_id
         .clone()
-        .or_else(|| cfg.agent.as_ref().map(|a| a.name().to_string()))
+        .or_else(|| ctx.agent.as_ref().map(|a| a.name().to_string()))
         .unwrap_or_else(|| "parent".to_string());
 
-    // Try local supervisor first (parent -> child routing)
-    let inbox = cfg
+    let inbox = ctx
         .supervisor
         .as_ref()
         .and_then(|sup| sup.read().inbox(id).cloned());
 
-    // Fall back to parent_supervisor (sibling -> sibling routing)
     let inbox = inbox.or_else(|| {
-        cfg.parent_supervisor
+        ctx.parent_supervisor
             .as_ref()
             .and_then(|sup| sup.read().inbox(id).cloned())
     });
@@ -679,9 +914,8 @@ fn handle_send_message(config: &GlobalConfig, args: &Value) -> Result<Value> {
     }
 }
 
-fn handle_check_inbox(config: &GlobalConfig) -> Result<Value> {
-    let cfg = config.read();
-    match &cfg.inbox {
+fn handle_check_inbox(ctx: &mut RequestContext) -> Result<Value> {
+    match ctx.inbox.as_ref() {
         Some(inbox) => {
             let messages: Vec<Value> = inbox
                 .drain()
@@ -707,7 +941,7 @@ fn handle_check_inbox(config: &GlobalConfig) -> Result<Value> {
     }
 }
 
-fn handle_reply_escalation(config: &GlobalConfig, args: &Value) -> Result<Value> {
+fn handle_reply_escalation(ctx: &mut RequestContext, args: &Value) -> Result<Value> {
     let escalation_id = args
         .get("escalation_id")
         .and_then(Value::as_str)
@@ -717,12 +951,10 @@ fn handle_reply_escalation(config: &GlobalConfig, args: &Value) -> Result<Value>
         .and_then(Value::as_str)
         .ok_or_else(|| anyhow!("'reply' is required"))?;
 
-    let queue = {
-        let cfg = config.read();
-        cfg.root_escalation_queue
-            .clone()
-            .ok_or_else(|| anyhow!("No escalation queue available"))?
-    };
+    let queue = ctx
+        .escalation_queue
+        .clone()
+        .ok_or_else(|| anyhow!("No escalation queue available"))?;
 
     match queue.take(escalation_id) {
         Some(request) => {
@@ -742,7 +974,7 @@ fn handle_reply_escalation(config: &GlobalConfig, args: &Value) -> Result<Value>
     }
 }
 
-fn handle_task_create(config: &GlobalConfig, args: &Value) -> Result<Value> {
+fn handle_task_create(ctx: &mut RequestContext, args: &Value) -> Result<Value> {
     let subject = args
         .get("subject")
         .and_then(Value::as_str)
@@ -768,10 +1000,10 @@ fn handle_task_create(config: &GlobalConfig, args: &Value) -> Result<Value> {
         bail!("'prompt' is required when 'agent' is set");
     }
 
-    let cfg = config.read();
-    let supervisor = cfg
+    let supervisor = ctx
         .supervisor
         .as_ref()
+        .cloned()
         .ok_or_else(|| anyhow!("No supervisor active"))?;
     let mut sup = supervisor.write();
 
@@ -805,11 +1037,11 @@ fn handle_task_create(config: &GlobalConfig, args: &Value) -> Result<Value> {
     Ok(result)
 }
 
-fn handle_task_list(config: &GlobalConfig) -> Result<Value> {
-    let cfg = config.read();
-    let supervisor = cfg
+fn handle_task_list(ctx: &mut RequestContext) -> Result<Value> {
+    let supervisor = ctx
         .supervisor
         .as_ref()
+        .cloned()
         .ok_or_else(|| anyhow!("No supervisor active"))?;
     let sup = supervisor.read();
 
@@ -834,17 +1066,17 @@ fn handle_task_list(config: &GlobalConfig) -> Result<Value> {
     Ok(json!({ "tasks": tasks }))
 }
 
-async fn handle_task_complete(config: &GlobalConfig, args: &Value) -> Result<Value> {
+async fn handle_task_complete(ctx: &mut RequestContext, args: &Value) -> Result<Value> {
     let task_id = args
         .get("task_id")
         .and_then(Value::as_str)
         .ok_or_else(|| anyhow!("'task_id' is required"))?;
 
     let (newly_runnable, dispatchable) = {
-        let cfg = config.read();
-        let supervisor = cfg
+        let supervisor = ctx
             .supervisor
             .as_ref()
+            .cloned()
             .ok_or_else(|| anyhow!("No supervisor active"))?;
         let mut sup = supervisor.write();
 
@@ -884,7 +1116,7 @@ async fn handle_task_complete(config: &GlobalConfig, args: &Value) -> Result<Val
             "agent": agent,
             "prompt": prompt,
         });
-        match handle_spawn(config, &spawn_args).await {
+        match handle_spawn(ctx, &spawn_args).await {
             Ok(result) => {
                 let agent_id = result
                     .get("id")
@@ -916,16 +1148,16 @@ async fn handle_task_complete(config: &GlobalConfig, args: &Value) -> Result<Val
     Ok(result)
 }
 
-fn handle_task_fail(config: &GlobalConfig, args: &Value) -> Result<Value> {
+fn handle_task_fail(ctx: &mut RequestContext, args: &Value) -> Result<Value> {
     let task_id = args
         .get("task_id")
         .and_then(Value::as_str)
         .ok_or_else(|| anyhow!("'task_id' is required"))?;
 
-    let cfg = config.read();
-    let supervisor = cfg
+    let supervisor = ctx
         .supervisor
         .as_ref()
+        .cloned()
         .ok_or_else(|| anyhow!("No supervisor active"))?;
     let mut sup = supervisor.write();
 
@@ -958,17 +1190,12 @@ Rules:
 - Use bullet points for multiple findings
 - If the output contains a final answer or conclusion, lead with it"#;
 
-async fn summarize_output(config: &GlobalConfig, agent_name: &str, output: &str) -> Result<String> {
-    let (threshold, summarization_model_id) = {
-        let cfg = config.read();
-        match cfg.agent.as_ref() {
-            Some(agent) => (
-                agent.summarization_threshold(),
-                agent.summarization_model().map(|s| s.to_string()),
-            ),
-            None => return Ok(output.to_string()),
-        }
+async fn summarize_output(ctx: &RequestContext, agent_name: &str, output: &str) -> Result<String> {
+    let Some(agent) = ctx.agent.as_ref() else {
+        return Ok(output.to_string());
     };
+    let threshold = agent.summarization_threshold();
+    let summarization_model_id = agent.summarization_model().map(|s| s.to_string());
 
     if output.len() < threshold {
         debug!(
@@ -987,12 +1214,11 @@ async fn summarize_output(config: &GlobalConfig, agent_name: &str, output: &str)
         threshold
     );
 
-    let model = {
-        let cfg = config.read();
-        match summarization_model_id {
-            Some(ref model_id) => Model::retrieve_model(&cfg, model_id, ModelType::Chat)?,
-            None => cfg.current_model().clone(),
+    let model = match summarization_model_id {
+        Some(ref model_id) => {
+            Model::retrieve_model(ctx.app.config.as_ref(), model_id, ModelType::Chat)?
         }
+        None => ctx.current_model().clone(),
     };
 
     let mut role = Role::new("summarizer", SUMMARIZATION_PROMPT);
@@ -1002,7 +1228,7 @@ async fn summarize_output(config: &GlobalConfig, agent_name: &str, output: &str)
         "Summarize the following sub-agent output from '{}':\n\n{}",
         agent_name, output
     );
-    let input = Input::from_str(config, &user_message, Some(role));
+    let input = Input::from_str(ctx, &user_message, Some(role));
 
     let summary = input.fetch_chat_text().await?;
 
@@ -1015,3 +1241,497 @@ async fn summarize_output(config: &GlobalConfig, agent_name: &str, output: &str)
 
     Ok(summary)
 }
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use crate::config::{AppState, WorkingMode};
+    use crate::supervisor::escalation::{EscalationQueue, EscalationRequest};
+    use serde_json::json;
+
+    fn default_app_state() -> Arc<AppState> {
+        Arc::new(AppState::test_default())
+    }
+
+    fn ctx_with_supervisor(max_concurrent: usize, max_depth: usize) -> RequestContext {
+        let mut ctx = RequestContext::new(default_app_state(), WorkingMode::Cmd);
+        ctx.supervisor = Some(Arc::new(RwLock::new(Supervisor::new(
+            max_concurrent,
+            max_depth,
+        ))));
+        ctx
+    }
+
+    fn register_fake_agent(ctx: &mut RequestContext, id: &str, name: &str) {
+        let rt = tokio::runtime::Runtime::new().unwrap();
+        let id_owned = id.to_string();
+        let name_owned = name.to_string();
+        let join_handle = rt.spawn(async move {
+            Ok(AgentResult {
+                id: id_owned,
+                agent_name: name_owned,
+                output: "fake output".into(),
+                exit_status: AgentExitStatus::Completed,
+            })
+        });
+        std::mem::forget(rt);
+
+        let handle = AgentHandle {
+            id: id.to_string(),
+            agent_name: name.to_string(),
+            depth: 1,
+            inbox: Arc::new(Inbox::new()),
+            abort_signal: create_abort_signal(),
+            join_handle,
+        };
+        ctx.supervisor
+            .as_ref()
+            .unwrap()
+            .write()
+            .register(handle)
+            .unwrap();
+    }
+
+    fn run_async<F: Future>(f: F) -> F::Output {
+        tokio::runtime::Builder::new_current_thread()
+            .enable_all()
+            .build()
+            .unwrap()
+            .block_on(f)
+    }
+
+    #[test]
+    fn handle_list_empty_supervisor() {
+        let mut ctx = ctx_with_supervisor(4, 3);
+        let result = handle_list(&mut ctx).unwrap();
+        assert_eq!(result["active_count"], 0);
+        assert_eq!(result["max_concurrent"], 4);
+        assert!(result["agents"].as_array().unwrap().is_empty());
+    }
+
+    #[test]
+    fn handle_list_with_agents() {
+        let mut ctx = ctx_with_supervisor(4, 3);
+        register_fake_agent(&mut ctx, "a1", "explore");
+        register_fake_agent(&mut ctx, "a2", "coder");
+        let result = handle_list(&mut ctx).unwrap();
+        assert_eq!(result["active_count"], 2);
+        let agents = result["agents"].as_array().unwrap();
+        assert_eq!(agents.len(), 2);
+    }
+
+    #[test]
+    fn handle_list_no_supervisor_errors() {
+        let mut ctx = RequestContext::new(default_app_state(), WorkingMode::Cmd);
+        let result = handle_list(&mut ctx);
+        assert!(result.is_err());
+    }
+
+    #[test]
+    fn handle_check_unknown_agent() {
+        let mut ctx = ctx_with_supervisor(4, 3);
+        let result = run_async(handle_check(&mut ctx, &json!({"id": "nonexistent"})));
+        let val = result.unwrap();
+        assert_eq!(val["status"], "error");
+    }
+
+    #[test]
+    fn handle_check_pending_agent() {
+        let rt = tokio::runtime::Builder::new_current_thread()
+            .enable_all()
+            .build()
+            .unwrap();
+
+        rt.block_on(async {
+            let mut ctx = ctx_with_supervisor(4, 3);
+            let inbox = Arc::new(Inbox::new());
+            let abort = create_abort_signal();
+            let join_handle = tokio::spawn(async {
+                time::sleep(Duration::from_secs(60)).await;
+                Ok(AgentResult {
+                    id: "slow".into(),
+                    agent_name: "test".into(),
+                    output: String::new(),
+                    exit_status: AgentExitStatus::Completed,
+                })
+            });
+            let handle = AgentHandle {
+                id: "slow".into(),
+                agent_name: "test".into(),
+                depth: 1,
+                inbox,
+                abort_signal: abort,
+                join_handle,
+            };
+            ctx.supervisor
+                .as_ref()
+                .unwrap()
+                .write()
+                .register(handle)
+                .unwrap();
+
+            let result = handle_check(&mut ctx, &json!({"id": "slow"}))
+                .await
+                .unwrap();
+            assert_eq!(result["status"], "pending");
+        });
+    }
+
+    #[test]
+    fn handle_cancel_registered_agent() {
+        let mut ctx = ctx_with_supervisor(4, 3);
+        register_fake_agent(&mut ctx, "a1", "explore");
+        let result = handle_cancel(&mut ctx, &json!({"id": "a1"})).unwrap();
+        assert_eq!(result["status"], "ok");
+        assert_eq!(ctx.supervisor.as_ref().unwrap().read().active_count(), 0);
+    }
+
+    #[test]
+    fn handle_cancel_unknown_agent() {
+        let mut ctx = ctx_with_supervisor(4, 3);
+        let result = handle_cancel(&mut ctx, &json!({"id": "missing"})).unwrap();
+        assert_eq!(result["status"], "error");
+    }
+
+    #[test]
+    fn handle_cancel_no_supervisor_errors() {
+        let mut ctx = RequestContext::new(default_app_state(), WorkingMode::Cmd);
+        let result = handle_cancel(&mut ctx, &json!({"id": "x"}));
+        assert!(result.is_err());
+    }
+
+    #[test]
+    fn handle_send_message_to_registered_agent() {
+        let mut ctx = ctx_with_supervisor(4, 3);
+        register_fake_agent(&mut ctx, "a1", "explore");
+        let result = handle_send_message(
+            &mut ctx,
+            &json!({"id": "a1", "message": "hello from parent"}),
+        )
+        .unwrap();
+        assert_eq!(result["status"], "ok");
+
+        let inbox = ctx
+            .supervisor
+            .as_ref()
+            .unwrap()
+            .read()
+            .inbox("a1")
+            .unwrap()
+            .clone();
+        let msgs = inbox.drain();
+        assert_eq!(msgs.len(), 1);
+        match &msgs[0].payload {
+            EnvelopePayload::Text { content } => assert_eq!(content, "hello from parent"),
+            _ => panic!("expected text payload"),
+        }
+    }
+
+    #[test]
+    fn handle_send_message_to_unknown_agent() {
+        let mut ctx = ctx_with_supervisor(4, 3);
+        let result =
+            handle_send_message(&mut ctx, &json!({"id": "missing", "message": "hi"})).unwrap();
+        assert_eq!(result["status"], "error");
+    }
+
+    #[test]
+    fn handle_check_inbox_with_messages() {
+        let mut ctx = ctx_with_supervisor(4, 3);
+        let inbox = Arc::new(Inbox::new());
+        inbox.deliver(Envelope {
+            from: "sibling".into(),
+            to: "me".into(),
+            payload: EnvelopePayload::Text {
+                content: "hey".into(),
+            },
+            timestamp: Utc::now(),
+        });
+        ctx.inbox = Some(inbox);
+
+        let result = handle_check_inbox(&mut ctx).unwrap();
+        assert_eq!(result["count"], 1);
+        let messages = result["messages"].as_array().unwrap();
+        assert_eq!(messages[0]["from"], "sibling");
+    }
+
+    #[test]
+    fn handle_check_inbox_no_inbox() {
+        let mut ctx = ctx_with_supervisor(4, 3);
+        let result = handle_check_inbox(&mut ctx).unwrap();
+        assert_eq!(result["count"], 0);
+    }
+
+    #[test]
+    fn handle_check_inbox_empty_inbox() {
+        let mut ctx = ctx_with_supervisor(4, 3);
+        ctx.inbox = Some(Arc::new(Inbox::new()));
+        let result = handle_check_inbox(&mut ctx).unwrap();
+        assert_eq!(result["count"], 0);
+    }
+
+    #[test]
+    fn handle_reply_escalation_success() {
+        let mut ctx = ctx_with_supervisor(4, 3);
+        let queue = Arc::new(EscalationQueue::new());
+        let (tx, rx) = tokio::sync::oneshot::channel();
+        queue.submit(EscalationRequest {
+            id: "esc_1".into(),
+            from_agent_id: "a1".into(),
+            from_agent_name: "explore".into(),
+            question: "What do?".into(),
+            options: None,
+            reply_tx: tx,
+        });
+        ctx.escalation_queue = Some(queue);
+
+        let result = handle_reply_escalation(
+            &mut ctx,
+            &json!({"escalation_id": "esc_1", "reply": "do X"}),
+        )
+        .unwrap();
+        assert_eq!(result["status"], "ok");
+        assert_eq!(rx.blocking_recv().unwrap(), "do X");
+    }
+
+    #[test]
+    fn handle_reply_escalation_missing_id() {
+        let mut ctx = ctx_with_supervisor(4, 3);
+        ctx.escalation_queue = Some(Arc::new(EscalationQueue::new()));
+        let result = handle_reply_escalation(
+            &mut ctx,
+            &json!({"escalation_id": "missing", "reply": "whatever"}),
+        )
+        .unwrap();
+        assert_eq!(result["status"], "error");
+    }
+
+    #[test]
+    fn handle_reply_escalation_no_queue_errors() {
+        let mut ctx = ctx_with_supervisor(4, 3);
+        let result =
+            handle_reply_escalation(&mut ctx, &json!({"escalation_id": "x", "reply": "y"}));
+        assert!(result.is_err());
+    }
+
+    #[test]
+    fn handle_task_create_simple() {
+        let mut ctx = ctx_with_supervisor(4, 3);
+        let result = handle_task_create(&mut ctx, &json!({"subject": "Do research"})).unwrap();
+        assert_eq!(result["status"], "ok");
+        assert!(result["task_id"].as_str().is_some());
+    }
+
+    #[test]
+    fn handle_task_create_with_dependencies() {
+        let mut ctx = ctx_with_supervisor(4, 3);
+        handle_task_create(&mut ctx, &json!({"subject": "Step 1"})).unwrap();
+        let result =
+            handle_task_create(&mut ctx, &json!({"subject": "Step 2", "blocked_by": ["1"]}))
+                .unwrap();
+        assert_eq!(result["status"], "ok");
+    }
+
+    #[test]
+    fn handle_task_create_with_dispatch_agent() {
+        let mut ctx = ctx_with_supervisor(4, 3);
+        let result = handle_task_create(
+            &mut ctx,
+            &json!({"subject": "Auto task", "agent": "coder", "prompt": "do it"}),
+        )
+        .unwrap();
+        assert_eq!(result["status"], "ok");
+        assert_eq!(result["auto_dispatch"], true);
+    }
+
+    #[test]
+    fn handle_task_create_agent_without_prompt_errors() {
+        let mut ctx = ctx_with_supervisor(4, 3);
+        let result = handle_task_create(&mut ctx, &json!({"subject": "Bad", "agent": "coder"}));
+        assert!(result.is_err());
+    }
+
+    #[test]
+    fn handle_task_list_empty() {
+        let mut ctx = ctx_with_supervisor(4, 3);
+        let result = handle_task_list(&mut ctx).unwrap();
+        assert!(result["tasks"].as_array().unwrap().is_empty());
+    }
+
+    #[test]
+    fn handle_task_list_with_tasks() {
+        let mut ctx = ctx_with_supervisor(4, 3);
+        handle_task_create(&mut ctx, &json!({"subject": "A"})).unwrap();
+        handle_task_create(&mut ctx, &json!({"subject": "B"})).unwrap();
+        let result = handle_task_list(&mut ctx).unwrap();
+        assert_eq!(result["tasks"].as_array().unwrap().len(), 2);
+    }
+
+    #[test]
+    fn handle_task_complete_unblocks_dependents() {
+        let mut ctx = ctx_with_supervisor(4, 3);
+        handle_task_create(&mut ctx, &json!({"subject": "Step 1"})).unwrap();
+        handle_task_create(&mut ctx, &json!({"subject": "Step 2", "blocked_by": ["1"]})).unwrap();
+
+        let result = run_async(handle_task_complete(&mut ctx, &json!({"task_id": "1"}))).unwrap();
+        assert_eq!(result["status"], "ok");
+        let newly_runnable = result["newly_runnable"].as_array().unwrap();
+        assert_eq!(newly_runnable.len(), 1);
+        assert_eq!(newly_runnable[0]["id"], "2");
+    }
+
+    #[test]
+    fn handle_task_fail_marks_failed() {
+        let mut ctx = ctx_with_supervisor(4, 3);
+        handle_task_create(&mut ctx, &json!({"subject": "Doomed"})).unwrap();
+        let result = handle_task_fail(&mut ctx, &json!({"task_id": "1"})).unwrap();
+        assert_eq!(result["status"], "ok");
+    }
+
+    #[test]
+    fn handle_task_fail_reports_blocked_dependents() {
+        let mut ctx = ctx_with_supervisor(4, 3);
+        handle_task_create(&mut ctx, &json!({"subject": "A"})).unwrap();
+        handle_task_create(&mut ctx, &json!({"subject": "B", "blocked_by": ["1"]})).unwrap();
+        let result = handle_task_fail(&mut ctx, &json!({"task_id": "1"})).unwrap();
+        let deps = result["blocked_dependents"].as_array().unwrap();
+        assert_eq!(deps.len(), 1);
+    }
+
+    #[test]
+    fn handle_task_fail_missing_task() {
+        let mut ctx = ctx_with_supervisor(4, 3);
+        let result = handle_task_fail(&mut ctx, &json!({"task_id": "nonexistent"})).unwrap();
+        assert_eq!(result["status"], "error");
+    }
+
+    #[test]
+    fn dispatch_unknown_action_errors() {
+        let mut ctx = ctx_with_supervisor(4, 3);
+        let result = run_async(handle_supervisor_tool(&mut ctx, "agent__bogus", &json!({})));
+        assert!(result.is_err());
+        assert!(
+            result
+                .unwrap_err()
+                .to_string()
+                .contains("Unknown supervisor action")
+        );
+    }
+
+    #[test]
+    fn dispatch_routes_list() {
+        let mut ctx = ctx_with_supervisor(4, 3);
+        let result =
+            run_async(handle_supervisor_tool(&mut ctx, "agent__list", &json!({}))).unwrap();
+        assert!(result["active_count"].is_number());
+    }
+
+    #[test]
+    fn dispatch_routes_task_list() {
+        let mut ctx = ctx_with_supervisor(4, 3);
+        let result = run_async(handle_supervisor_tool(
+            &mut ctx,
+            "agent__task_list",
+            &json!({}),
+        ))
+        .unwrap();
+        assert!(result["tasks"].is_array());
+    }
+
+    #[test]
+    fn new_for_child_inherits_escalation_queue() {
+        let mut parent = ctx_with_supervisor(4, 3);
+        let queue = parent.ensure_root_escalation_queue();
+
+        let child = RequestContext::new_for_child(
+            default_app_state(),
+            &parent,
+            2,
+            Arc::new(Inbox::new()),
+            "child_1".into(),
+        );
+
+        assert!(child.escalation_queue.is_some());
+        assert!(Arc::ptr_eq(
+            child.escalation_queue.as_ref().unwrap(),
+            &queue
+        ));
+    }
+
+    #[test]
+    fn new_for_child_sets_depth_and_id() {
+        let parent = ctx_with_supervisor(4, 3);
+        let child = RequestContext::new_for_child(
+            default_app_state(),
+            &parent,
+            3,
+            Arc::new(Inbox::new()),
+            "child_xyz".into(),
+        );
+        assert_eq!(child.current_depth, 3);
+        assert_eq!(child.self_agent_id, Some("child_xyz".to_string()));
+    }
+
+    #[test]
+    fn new_for_child_has_inbox() {
+        let parent = ctx_with_supervisor(4, 3);
+        let inbox = Arc::new(Inbox::new());
+        let child = RequestContext::new_for_child(
+            default_app_state(),
+            &parent,
+            1,
+            Arc::clone(&inbox),
+            "c1".into(),
+        );
+        assert!(child.inbox.is_some());
+        assert!(Arc::ptr_eq(child.inbox.as_ref().unwrap(), &inbox));
+    }
+
+    #[test]
+    fn new_for_child_inherits_parent_supervisor() {
+        let parent = ctx_with_supervisor(4, 3);
+        let child = RequestContext::new_for_child(
+            default_app_state(),
+            &parent,
+            1,
+            Arc::new(Inbox::new()),
+            "c1".into(),
+        );
+        assert!(child.parent_supervisor.is_some());
+        assert!(child.supervisor.is_none());
+    }
+
+    #[test]
+    fn new_for_child_starts_with_empty_scope() {
+        let parent = ctx_with_supervisor(4, 3);
+        let child = RequestContext::new_for_child(
+            default_app_state(),
+            &parent,
+            1,
+            Arc::new(Inbox::new()),
+            "c1".into(),
+        );
+        assert!(child.tool_scope.functions.is_empty());
+        assert!(child.tool_scope.mcp_runtime.is_empty());
+        assert!(child.role.is_none());
+        assert!(child.session.is_none());
+        assert!(child.agent.is_none());
+    }
+
+    #[test]
+    fn ensure_root_escalation_queue_creates_on_first_call() {
+        let mut ctx = ctx_with_supervisor(4, 3);
+        assert!(ctx.escalation_queue.is_none());
+        let q = ctx.ensure_root_escalation_queue();
+        assert!(!q.has_pending());
+        assert!(ctx.escalation_queue.is_some());
+    }
+
+    #[test]
+    fn ensure_root_escalation_queue_returns_same_on_second_call() {
+        let mut ctx = ctx_with_supervisor(4, 3);
+        let q1 = ctx.ensure_root_escalation_queue();
+        let q2 = ctx.ensure_root_escalation_queue();
+        assert!(Arc::ptr_eq(&q1, &q2));
+    }
+}
diff --git a/src/function/todo.rs b/src/function/todo.rs
index d37fa5c..9415849 100644
--- a/src/function/todo.rs
+++ b/src/function/todo.rs
@@ -1,5 +1,5 @@
 use super::{FunctionDeclaration, JsonSchema};
-use crate::config::GlobalConfig;
+use crate::config::RequestContext;
 
 use anyhow::{Result, bail};
 use indexmap::IndexMap;
@@ -89,38 +89,34 @@ pub fn todo_function_declarations() -> Vec<FunctionDeclaration> {
     ]
 }
 
-pub fn handle_todo_tool(config: &GlobalConfig, cmd_name: &str, args: &Value) -> Result<Value> {
+pub fn handle_todo_tool(ctx: &mut RequestContext, cmd_name: &str, args: &Value) -> Result<Value> {
     let action = cmd_name
         .strip_prefix(TODO_FUNCTION_PREFIX)
         .unwrap_or(cmd_name);
 
+    if !ctx.app.config.function_calling_support {
+        bail!("Cannot use todo tools: function calling is disabled.");
+    }
+    let auto_config = ctx.auto_continue_config();
+    if !auto_config.enabled {
+        bail!(
+            "Auto-continue is not enabled. Set 'auto_continue: true' in your config to use todo tools."
+        );
+    }
+
     match action {
         "init" => {
             let goal = args.get("goal").and_then(Value::as_str).unwrap_or_default();
-            let mut cfg = config.write();
-            let agent = cfg.agent.as_mut();
-            match agent {
-                Some(agent) => {
-                    agent.init_todo_list(goal);
-                    Ok(json!({"status": "ok", "message": "Initialized new todo list"}))
-                }
-                None => bail!("No active agent"),
-            }
+            ctx.init_todo_list(goal);
+            Ok(json!({"status": "ok", "message": "Initialized new todo list"}))
         }
         "add" => {
             let task = args.get("task").and_then(Value::as_str).unwrap_or_default();
             if task.is_empty() {
                 return Ok(json!({"error": "task description is required"}));
             }
-            let mut cfg = config.write();
-            let agent = cfg.agent.as_mut();
-            match agent {
-                Some(agent) => {
-                    let id = agent.add_todo(task);
-                    Ok(json!({"status": "ok", "id": id}))
-                }
-                None => bail!("No active agent"),
-            }
+            let id = ctx.add_todo(task);
+            Ok(json!({"status": "ok", "id": id}))
         }
         "done" => {
             let id = args
@@ -132,50 +128,26 @@ pub fn handle_todo_tool(config: &GlobalConfig, cmd_name: &str, args: &Value) ->
                 .map(|v| v as usize);
             match id {
                 Some(id) => {
-                    let mut cfg = config.write();
-                    let agent = cfg.agent.as_mut();
-                    match agent {
-                        Some(agent) => {
-                            if agent.mark_todo_done(id) {
-                                Ok(
-                                    json!({"status": "ok", "message": format!("Marked todo {id} as done")}),
-                                )
-                            } else {
-                                Ok(json!({"error": format!("Todo {id} not found")}))
-                            }
-                        }
-                        None => bail!("No active agent"),
+                    if ctx.mark_todo_done(id) {
+                        Ok(json!({"status": "ok", "message": format!("Marked todo {id} as done")}))
+                    } else {
+                        Ok(json!({"error": format!("Todo {id} not found")}))
                     }
                 }
                 None => Ok(json!({"error": "id is required and must be a number"})),
             }
         }
         "list" => {
-            let cfg = config.read();
-            let agent = cfg.agent.as_ref();
-            match agent {
-                Some(agent) => {
-                    let list = agent.todo_list();
-                    if list.is_empty() {
-                        Ok(json!({"goal": "", "todos": []}))
-                    } else {
-                        Ok(serde_json::to_value(list)
-                            .unwrap_or(json!({"error": "serialization failed"})))
-                    }
-                }
-                None => bail!("No active agent"),
+            let list = &ctx.todo_list;
+            if list.is_empty() {
+                Ok(json!({"goal": "", "todos": []}))
+            } else {
+                Ok(serde_json::to_value(list).unwrap_or(json!({"error": "serialization failed"})))
             }
         }
         "clear" => {
-            let mut cfg = config.write();
-            let agent = cfg.agent.as_mut();
-            match agent {
-                Some(agent) => {
-                    agent.clear_todo_list();
-                    Ok(json!({"status": "ok", "message": "Todo list cleared"}))
-                }
-                None => bail!("No active agent"),
-            }
+            ctx.clear_todo_list();
+            Ok(json!({"status": "ok", "message": "Todo list cleared"}))
         }
         _ => bail!("Unknown todo action: {action}"),
     }
diff --git a/src/function/user_interaction.rs b/src/function/user_interaction.rs
index a7de6e6..92c407c 100644
--- a/src/function/user_interaction.rs
+++ b/src/function/user_interaction.rs
@@ -1,8 +1,8 @@
 use super::{FunctionDeclaration, JsonSchema};
-use crate::config::GlobalConfig;
+use crate::config::RequestContext;
 use crate::supervisor::escalation::{EscalationRequest, new_escalation_id};
 
-use anyhow::{Result, anyhow};
+use anyhow::{Result, anyhow, bail};
 use indexmap::IndexMap;
 use inquire::{Confirm, MultiSelect, Select, Text};
 use serde_json::{Value, json};
@@ -120,7 +120,7 @@ pub fn user_interaction_function_declarations() -> Vec<FunctionDeclaration> {
 }
 
 pub async fn handle_user_tool(
-    config: &GlobalConfig,
+    ctx: &mut RequestContext,
     cmd_name: &str,
     args: &Value,
 ) -> Result<Value> {
@@ -128,12 +128,12 @@ pub async fn handle_user_tool(
         .strip_prefix(USER_FUNCTION_PREFIX)
         .unwrap_or(cmd_name);
 
-    let depth = config.read().current_depth;
+    let depth = ctx.current_depth;
 
     if depth == 0 {
         handle_direct(action, args)
     } else {
-        handle_escalated(config, action, args).await
+        handle_escalated(ctx, action, args).await
     }
 }
 
@@ -155,7 +155,10 @@ fn handle_direct_ask(args: &Value) -> Result<Value> {
     let mut options = parse_options(args)?;
     options.push(CUSTOM_MULTI_CHOICE_ANSWER_OPTION.to_string());
 
-    let mut answer = Select::new(question, options).prompt()?;
+    let mut answer = Select::new(question, options)
+        .without_filtering()
+        .with_help_message("↑↓ to move, enter to select")
+        .prompt()?;
 
     if answer == CUSTOM_MULTI_CHOICE_ANSWER_OPTION {
         answer = Text::new("Custom response:").prompt()?
@@ -198,43 +201,38 @@ fn handle_direct_checkbox(args: &Value) -> Result<Value> {
     Ok(json!({ "answers": answers }))
 }
 
-async fn handle_escalated(config: &GlobalConfig, action: &str, args: &Value) -> Result<Value> {
+async fn handle_escalated(ctx: &RequestContext, action: &str, args: &Value) -> Result<Value> {
     let question = args
         .get("question")
         .and_then(Value::as_str)
         .ok_or_else(|| anyhow!("'question' is required"))?
         .to_string();
 
-    let options: Option<Vec<String>> = args.get("options").and_then(Value::as_array).map(|arr| {
-        arr.iter()
-            .filter_map(Value::as_str)
-            .map(String::from)
-            .collect()
-    });
-
-    let (from_agent_id, from_agent_name, root_queue, timeout_secs) = {
-        let cfg = config.read();
-        let agent_id = cfg
-            .self_agent_id
-            .clone()
-            .unwrap_or_else(|| "unknown".to_string());
-        let agent_name = cfg
-            .agent
-            .as_ref()
-            .map(|a| a.name().to_string())
-            .unwrap_or_else(|| "unknown".to_string());
-        let queue = cfg
-            .root_escalation_queue
-            .clone()
-            .ok_or_else(|| anyhow!("No escalation queue available; cannot reach parent agent"))?;
-        let timeout = cfg
-            .agent
-            .as_ref()
-            .map(|a| a.escalation_timeout())
-            .unwrap_or(DEFAULT_ESCALATION_TIMEOUT_SECS);
-        (agent_id, agent_name, queue, timeout)
+    let options: Option<Vec<String>> = if args.get("options").is_some() {
+        Some(parse_options(args)?)
+    } else {
+        None
     };
 
+    let from_agent_id = ctx
+        .self_agent_id
+        .clone()
+        .unwrap_or_else(|| "unknown".to_string());
+    let from_agent_name = ctx
+        .agent
+        .as_ref()
+        .map(|a| a.name().to_string())
+        .unwrap_or_else(|| "unknown".to_string());
+    let root_queue = ctx
+        .root_escalation_queue()
+        .cloned()
+        .ok_or_else(|| anyhow!("No escalation queue available; cannot reach parent agent"))?;
+    let timeout_secs = ctx
+        .agent
+        .as_ref()
+        .map(|a| a.escalation_timeout())
+        .unwrap_or(DEFAULT_ESCALATION_TIMEOUT_SECS);
+
     let escalation_id = new_escalation_id();
     let (tx, rx) = oneshot::channel();
 
@@ -266,13 +264,24 @@ async fn handle_escalated(config: &GlobalConfig, action: &str, args: &Value) ->
 }
 
 fn parse_options(args: &Value) -> Result<Vec<String>> {
-    args.get("options")
-        .and_then(Value::as_array)
-        .map(|arr| {
-            arr.iter()
-                .filter_map(Value::as_str)
-                .map(String::from)
-                .collect()
-        })
-        .ok_or_else(|| anyhow!("'options' is required and must be an array of strings"))
+    let raw = args
+        .get("options")
+        .ok_or_else(|| anyhow!("'options' is required and must be an array of strings"))?;
+
+    let arr: Vec<Value> = match raw {
+        Value::Array(arr) => arr.clone(),
+        Value::String(s) => serde_json::from_str::<Vec<Value>>(s).map_err(|_| {
+            anyhow!(
+                "'options' was a string but did not parse as a JSON array. \
+                 Pass options as a native JSON array, e.g. [\"yes\", \"no\"]."
+            )
+        })?,
+        _ => bail!("'options' is required and must be an array of strings"),
+    };
+
+    Ok(arr
+        .iter()
+        .filter_map(Value::as_str)
+        .map(String::from)
+        .collect())
 }
diff --git a/src/graph/agent.rs b/src/graph/agent.rs
new file mode 100644
index 0000000..de95cfd
--- /dev/null
+++ b/src/graph/agent.rs
@@ -0,0 +1,272 @@
+use super::state::StateManager;
+use super::structured;
+use super::types::AgentNode;
+use crate::config::RequestContext;
+use crate::function::supervisor::run_agent_for_graph;
+use anyhow::{Context, Result};
+use serde_json::Value;
+use std::time::Duration;
+use tokio::time::timeout;
+
+const OUTPUT_KEY: &str = "output";
+const DEFAULT_TIMEOUT_SECS: u64 = 300;
+
+pub struct AgentNodeExecutor;
+
+impl AgentNodeExecutor {
+    pub async fn execute(
+        node: &AgentNode,
+        state_manager: &mut StateManager,
+        parent_ctx: &mut RequestContext,
+    ) -> Result<String> {
+        let prompt = state_manager
+            .interpolate(&node.prompt)
+            .with_context(|| format!("Failed to interpolate prompt for agent '{}'", node.agent))?;
+
+        let timeout_dur = Duration::from_secs(node.timeout.unwrap_or(DEFAULT_TIMEOUT_SECS));
+
+        let raw = timeout(
+            timeout_dur,
+            run_agent_for_graph(parent_ctx, &node.agent, &prompt),
+        )
+        .await
+        .with_context(|| {
+            format!(
+                "Agent '{}' timed out after {}s",
+                node.agent,
+                timeout_dur.as_secs()
+            )
+        })?
+        .with_context(|| format!("Agent '{}' failed", node.agent))?;
+
+        let output_value = match &node.output_schema {
+            Some(schema) => structured::extract(&raw, schema, parent_ctx)
+                .await
+                .with_context(|| {
+                    format!(
+                        "Agent '{}' output failed structured-output extraction",
+                        node.agent
+                    )
+                })?,
+            None => Value::String(raw.clone()),
+        };
+
+        apply_state_updates(node, state_manager, &output_value);
+
+        Ok(raw)
+    }
+}
+
+fn apply_state_updates(node: &AgentNode, state_manager: &mut StateManager, output: &Value) {
+    if node.output_schema.is_some()
+        && let Some(obj) = output.as_object()
+    {
+        for (k, v) in obj {
+            state_manager.state_mut().set(k.clone(), v.clone());
+        }
+    }
+
+    let Some(updates) = &node.state_updates else {
+        return;
+    };
+    let prev_output = state_manager.state().get(OUTPUT_KEY).cloned();
+    state_manager
+        .state_mut()
+        .set(OUTPUT_KEY.into(), output.clone());
+
+    for (key, template) in updates {
+        let value = state_manager.interpolate_lenient(template);
+        state_manager
+            .state_mut()
+            .set(key.clone(), Value::String(value));
+    }
+
+    match prev_output {
+        Some(v) => state_manager.state_mut().set(OUTPUT_KEY.into(), v),
+        None => {
+            state_manager
+                .state_mut()
+                .set(OUTPUT_KEY.into(), Value::Null);
+        }
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::super::types::AgentNode;
+    use super::*;
+    use serde_json::json;
+    use std::collections::HashMap;
+
+    fn manager_with(pairs: &[(&str, Value)]) -> StateManager {
+        let mut map = HashMap::new();
+        for (k, v) in pairs {
+            map.insert((*k).into(), v.clone());
+        }
+        StateManager::new(map)
+    }
+
+    fn node_with(prompt: &str, updates: Option<HashMap<String, String>>) -> AgentNode {
+        AgentNode {
+            agent: "test_agent".into(),
+            prompt: prompt.into(),
+            state_updates: updates,
+            output_schema: None,
+            timeout: None,
+        }
+    }
+
+    #[test]
+    fn state_updates_use_output_placeholder() {
+        let node = {
+            let mut u = HashMap::new();
+            u.insert("findings".into(), "{{output}}".into());
+            node_with("hi", Some(u))
+        };
+        let mut state = manager_with(&[]);
+
+        apply_state_updates(&node, &mut state, &json!("agent finished its work"));
+
+        assert_eq!(
+            state.state().get("findings"),
+            Some(&json!("agent finished its work"))
+        );
+    }
+
+    #[test]
+    fn state_updates_can_reference_existing_keys_and_output() {
+        let node = {
+            let mut u = HashMap::new();
+            u.insert("summary".into(), "{{topic}}: {{output}}".into());
+            node_with("hi", Some(u))
+        };
+        let mut state = manager_with(&[("topic", json!("auth"))]);
+
+        apply_state_updates(&node, &mut state, &json!("JWT vs sessions"));
+
+        assert_eq!(
+            state.state().get("summary"),
+            Some(&json!("auth: JWT vs sessions"))
+        );
+    }
+
+    #[test]
+    fn output_key_is_cleaned_up_after_state_updates() {
+        let node = {
+            let mut u = HashMap::new();
+            u.insert("findings".into(), "{{output}}".into());
+            node_with("hi", Some(u))
+        };
+        let mut state = manager_with(&[]);
+
+        apply_state_updates(&node, &mut state, &json!("anything"));
+
+        assert_eq!(state.state().get("output"), Some(&Value::Null));
+    }
+
+    #[test]
+    fn pre_existing_output_value_is_preserved() {
+        let node = {
+            let mut u = HashMap::new();
+            u.insert("greeting".into(), "{{output}}".into());
+            node_with("hi", Some(u))
+        };
+        let mut state = manager_with(&[("output", json!("preserved"))]);
+
+        apply_state_updates(&node, &mut state, &json!("new agent output"));
+
+        assert_eq!(
+            state.state().get("greeting"),
+            Some(&json!("new agent output"))
+        );
+        assert_eq!(state.state().get("output"), Some(&json!("preserved")));
+    }
+
+    #[test]
+    fn no_state_updates_is_a_noop() {
+        let node = node_with("hi", None);
+        let mut state = manager_with(&[("k", json!("v"))]);
+
+        apply_state_updates(&node, &mut state, &json!("ignored"));
+
+        assert_eq!(state.state().get("k"), Some(&json!("v")));
+        assert!(state.state().get("output").is_none());
+    }
+
+    #[test]
+    fn interpolate_lenient_on_state_updates_handles_missing_keys() {
+        let node = {
+            let mut u = HashMap::new();
+            u.insert("decorated".into(), "[{{missing}}] {{output}}".into());
+            node_with("hi", Some(u))
+        };
+        let mut state = manager_with(&[]);
+
+        apply_state_updates(&node, &mut state, &json!("DATA"));
+
+        assert_eq!(state.state().get("decorated"), Some(&json!("[] DATA")));
+    }
+
+    fn node_with_schema(
+        prompt: &str,
+        updates: Option<HashMap<String, String>>,
+        schema: Value,
+    ) -> AgentNode {
+        let mut n = node_with(prompt, updates);
+        n.output_schema = Some(schema);
+        n
+    }
+
+    #[test]
+    fn output_schema_auto_merges_top_level_keys() {
+        let node = node_with_schema("hi", None, json!({"type": "object"}));
+        let mut state = manager_with(&[]);
+        let output = json!({"goal": "do X", "summary": "details"});
+
+        apply_state_updates(&node, &mut state, &output);
+
+        assert_eq!(state.state().get("goal"), Some(&json!("do X")));
+        assert_eq!(state.state().get("summary"), Some(&json!("details")));
+    }
+
+    #[test]
+    fn output_schema_preserves_nested_value_types() {
+        let node = node_with_schema("hi", None, json!({"type": "object"}));
+        let mut state = manager_with(&[]);
+        let output = json!({
+            "tags": ["a", "b"],
+            "config": { "key": "value" },
+            "count": 42
+        });
+
+        apply_state_updates(&node, &mut state, &output);
+
+        assert_eq!(state.state().get("tags"), Some(&json!(["a", "b"])));
+        assert_eq!(state.state().get("config"), Some(&json!({"key": "value"})));
+        assert_eq!(state.state().get("count"), Some(&json!(42)));
+    }
+
+    #[test]
+    fn output_schema_explicit_state_updates_override_auto_merge() {
+        let mut u = HashMap::new();
+        u.insert("goal".into(), "renamed-{{output.goal}}".into());
+        let node = node_with_schema("hi", Some(u), json!({"type": "object"}));
+        let mut state = manager_with(&[]);
+        let output = json!({"goal": "do X"});
+
+        apply_state_updates(&node, &mut state, &output);
+
+        assert_eq!(state.state().get("goal"), Some(&json!("renamed-do X")));
+    }
+
+    #[test]
+    fn no_schema_does_not_auto_merge() {
+        let node = node_with("hi", None);
+        let mut state = manager_with(&[]);
+        let output = json!({"goal": "do X"});
+
+        apply_state_updates(&node, &mut state, &output);
+
+        assert!(state.state().get("goal").is_none());
+    }
+}
diff --git a/src/graph/dispatch.rs b/src/graph/dispatch.rs
new file mode 100644
index 0000000..a65b36f
--- /dev/null
+++ b/src/graph/dispatch.rs
@@ -0,0 +1,47 @@
+use super::{GraphExecutor, GraphParser, agent_has_graph};
+use crate::config::RequestContext;
+use crate::config::paths;
+use crate::utils::AbortSignal;
+use anyhow::{Context, Result, anyhow};
+use log::info;
+use serde_json::Value;
+
+pub fn active_agent_graph_name(ctx: &RequestContext) -> Option<String> {
+    let name = ctx.agent.as_ref()?.name().to_string();
+    agent_has_graph(&name).then_some(name)
+}
+
+pub async fn run_active_agent_graph(
+    ctx: &mut RequestContext,
+    prompt: &str,
+    abort_signal: AbortSignal,
+) -> Result<String> {
+    let agent_name =
+        active_agent_graph_name(ctx).ok_or_else(|| anyhow!("Active agent has no graph.yaml"))?;
+
+    info!("Agent '{agent_name}' has graph.yaml; routing to graph executor");
+
+    let agent_dir = paths::agent_data_dir(&agent_name);
+    let graph_path = paths::agent_graph_file(&agent_name);
+
+    let parser = GraphParser::new(&agent_dir);
+    let mut graph = parser
+        .load_from_file(&graph_path)
+        .with_context(|| format!("Failed to load graph.yaml for agent '{agent_name}'"))?;
+
+    graph
+        .initial_state
+        .insert("initial_prompt".into(), Value::String(prompt.to_string()));
+
+    let executor = GraphExecutor::new(graph, agent_dir);
+    let output = executor
+        .execute(ctx, abort_signal)
+        .await
+        .with_context(|| format!("Graph execution failed for agent '{agent_name}'"))?;
+
+    if let Some(supervisor) = ctx.supervisor.clone() {
+        supervisor.read().cancel_all();
+    }
+
+    Ok(output)
+}
diff --git a/src/graph/executor.rs b/src/graph/executor.rs
new file mode 100644
index 0000000..46398c6
--- /dev/null
+++ b/src/graph/executor.rs
@@ -0,0 +1,796 @@
+use super::agent::AgentNodeExecutor;
+use super::llm::{LlmExecutionOutcome, LlmNodeExecutor};
+use super::logging::{GraphLogger, narrate_node_complete, narrate_node_failed};
+use super::map::MapNodeExecutor;
+use super::rag::RagNodeExecutor;
+use super::script::ScriptExecutor;
+use super::staging::BranchWrites;
+use super::state::StateManager;
+use super::types::{EndNode, Graph, Node, NodeType};
+use super::user_interaction::{ApprovalNodeExecutor, InputNodeExecutor};
+use super::validator::{AgentValidationContext, GraphValidator};
+use crate::config::{RenderMode, RequestContext};
+use crate::utils::AbortSignal;
+use anyhow::{Context, Result, anyhow, bail};
+use futures_util::future::join_all;
+use serde_json::Value;
+use std::collections::{HashMap, HashSet};
+use std::path::PathBuf;
+use std::sync::Arc;
+use std::time::{Duration, Instant};
+use tokio::sync::Semaphore;
+
+pub struct GraphExecutor {
+    graph: Graph,
+    base_dir: PathBuf,
+}
+
+impl GraphExecutor {
+    pub fn new(graph: Graph, base_dir: impl Into<PathBuf>) -> Self {
+        Self {
+            graph,
+            base_dir: base_dir.into(),
+        }
+    }
+
+    pub async fn execute(
+        self,
+        ctx: &mut RequestContext,
+        abort_signal: AbortSignal,
+    ) -> Result<String> {
+        let is_nested = ctx.current_depth > 0;
+        let mut logger = GraphLogger::with_visibility(
+            &self.graph.name,
+            self.graph.settings.log_state_snapshots,
+            is_nested,
+        );
+        let result = self.run(&mut logger, ctx, abort_signal).await;
+        if let Err(e) = &result {
+            logger.graph_error(e);
+        }
+        result
+    }
+
+    async fn run(
+        self,
+        logger: &mut GraphLogger,
+        ctx: &mut RequestContext,
+        abort_signal: AbortSignal,
+    ) -> Result<String> {
+        let GraphExecutor { graph, base_dir } = self;
+
+        if graph.settings.validate_before_run {
+            let mut validator = GraphValidator::new(&base_dir);
+            if let Some(agent) = &ctx.agent {
+                validator = validator.with_agent_context(AgentValidationContext::from_agent(
+                    agent,
+                    Arc::clone(&ctx.app.config),
+                ));
+            }
+            let result = validator.validate(&graph);
+            for w in &result.warnings {
+                logger.validation_warning(w.node_id.as_deref(), &w.message);
+            }
+            result.into_result()?;
+        }
+
+        let mut state = StateManager::new(graph.initial_state.clone());
+        let agent_envs = ctx
+            .agent
+            .as_ref()
+            .map(|a| a.variable_envs())
+            .unwrap_or_default();
+        let script_executor = ScriptExecutor::new(&base_dir).with_envs(agent_envs);
+        let max_iterations = graph.settings.max_loop_iterations;
+        let graph_timeout = graph.settings.timeout.map(Duration::from_secs);
+        let max_concurrency = graph.settings.max_concurrency;
+        let graph = Arc::new(graph);
+        let start = Instant::now();
+
+        let mut frontier: HashSet<String> = HashSet::from([graph.start.clone()]);
+        logger.graph_start(&graph.start, graph.nodes.len());
+
+        loop {
+            if frontier.is_empty() {
+                bail!(
+                    "Graph '{}' frontier emptied without reaching an End node",
+                    graph.name
+                );
+            }
+
+            if abort_signal.aborted() {
+                bail!(
+                    "Graph '{}' aborted before super-step with frontier {:?}",
+                    graph.name,
+                    sorted_frontier(&frontier)
+                );
+            }
+            if let Some(t) = graph_timeout
+                && start.elapsed() > t
+            {
+                bail!(
+                    "Graph '{}' timed out after {}s before super-step with frontier {:?}",
+                    graph.name,
+                    t.as_secs(),
+                    sorted_frontier(&frontier)
+                );
+            }
+
+            // Loop-count and visit tracking on live state, BEFORE forking.
+            // This counts every entry to a node toward max_loop_iterations
+            // regardless of how many parallel branches converged on it.
+            for node_id in &frontier {
+                state.state_mut().visit_node(node_id);
+                let visits = state.state().loop_count(node_id);
+                if visits > max_iterations {
+                    bail!(
+                        "Node '{}' visited {} times (max_loop_iterations={}). \
+                         Possible infinite loop.",
+                        node_id,
+                        visits,
+                        max_iterations
+                    );
+                }
+            }
+
+            for node_id in &frontier {
+                let node = graph.get_node(node_id).ok_or_else(|| {
+                    anyhow!("Node '{}' not found in graph '{}'", node_id, graph.name)
+                })?;
+                let visits = state.state().loop_count(node_id);
+                logger.node_entry(node, visits);
+            }
+            let snapshot_label = if frontier.len() == 1 {
+                frontier.iter().next().cloned().unwrap_or_default()
+            } else {
+                format!("super-step {{{}}}", sorted_frontier(&frontier).join(","))
+            };
+            logger.state_snapshot(&snapshot_label, &state);
+
+            let snapshot = state.read_snapshot();
+            let semaphore = Arc::new(Semaphore::new(max_concurrency));
+
+            let frontier_size = frontier.len();
+            let in_super_step = frontier_size > 1;
+            let silent = logger.silent();
+
+            if in_super_step {
+                let mut branches = sorted_frontier(&frontier);
+                branches.sort();
+                logger.super_step_start(&branches);
+            }
+
+            let mut branch_tasks = Vec::with_capacity(frontier_size);
+            for node_id in &frontier {
+                let node = graph
+                    .get_node(node_id)
+                    .ok_or_else(|| {
+                        anyhow!("Node '{}' not found in graph '{}'", node_id, graph.name)
+                    })?
+                    .clone();
+                logger.node_start(&node, in_super_step);
+                let branch_state = state.fork_for_branch_state();
+                let mut branch_ctx = ctx.fork_for_branch();
+                if in_super_step {
+                    branch_ctx.render_mode = RenderMode::Silent;
+                }
+                let script_exec_clone = script_executor.clone();
+                let graph_clone = Arc::clone(&graph);
+                let current = node_id.clone();
+                let sem_clone = semaphore.clone();
+                let abort_clone = abort_signal.clone();
+
+                let task = tokio::spawn(async move {
+                    let _permit = sem_clone
+                        .acquire()
+                        .await
+                        .expect("semaphore should not be closed");
+                    if abort_clone.aborted() {
+                        narrate_node_failed(
+                            silent,
+                            &node,
+                            Duration::default(),
+                            "aborted",
+                            in_super_step,
+                        );
+                        return (
+                            current.clone(),
+                            branch_state,
+                            Err(anyhow!("branch aborted")),
+                            Duration::default(),
+                        );
+                    }
+                    let node_start = Instant::now();
+                    let mut state = branch_state;
+                    let mut ctx = branch_ctx;
+                    let step_ctx = StepContext {
+                        graph: graph_clone.as_ref(),
+                        script_executor: &script_exec_clone,
+                        max_concurrency,
+                        abort_signal: &abort_clone,
+                    };
+                    let result = step(&node, &mut state, &mut ctx, &step_ctx, &current).await;
+                    let elapsed = node_start.elapsed();
+                    match &result {
+                        Ok(StepResult::Continue(targets)) => {
+                            let route = if targets.is_empty() {
+                                None
+                            } else {
+                                Some(targets.join(", "))
+                            };
+                            narrate_node_complete(
+                                silent,
+                                &node,
+                                elapsed,
+                                route.as_deref(),
+                                in_super_step,
+                            );
+                        }
+                        Ok(StepResult::End(_)) => {
+                            narrate_node_complete(
+                                silent,
+                                &node,
+                                elapsed,
+                                Some("END"),
+                                in_super_step,
+                            );
+                        }
+                        Err(e) => {
+                            narrate_node_failed(
+                                silent,
+                                &node,
+                                elapsed,
+                                &e.to_string(),
+                                in_super_step,
+                            );
+                        }
+                    }
+                    (current, state, result, elapsed)
+                });
+                branch_tasks.push(task);
+            }
+
+            let joined = join_all(branch_tasks).await;
+
+            let mut branch_writes: Vec<BranchWrites> = Vec::new();
+            let mut next_frontier: HashSet<String> = HashSet::new();
+            let mut end_results: Vec<(String, StateManager, String)> = Vec::new();
+
+            for join_result in joined {
+                let (node_id, branch_state, step_result, elapsed) =
+                    join_result.map_err(|e| anyhow!("Branch task panicked: {e}"))?;
+                logger.record_timing(&node_id, elapsed);
+
+                let step_outcome = step_result.with_context(|| format!("at node '{node_id}'"))?;
+
+                match step_outcome {
+                    StepResult::Continue(targets) => {
+                        for target in &targets {
+                            logger.routing(&node_id, target);
+                        }
+                        let diff = branch_state.diff_against(snapshot.as_ref());
+                        branch_writes.push(BranchWrites {
+                            node_id: node_id.clone(),
+                            invocation_index: 0,
+                            writes: diff,
+                        });
+                        next_frontier.extend(targets);
+                    }
+                    StepResult::End(output) => {
+                        end_results.push((node_id.clone(), branch_state, output));
+                    }
+                }
+            }
+
+            if end_results.len() > 1 {
+                let mut ids: Vec<String> =
+                    end_results.iter().map(|(id, _, _)| id.clone()).collect();
+                ids.sort();
+                bail!(
+                    "super-step ended with multiple End targets ({}). \
+                     Fan-out branches must converge at a join node before \
+                     terminating. To fix: route all parallel branches to a \
+                     single shared next-node, then terminate from there.",
+                    ids.join(", ")
+                );
+            }
+
+            // Sort by (node_id, invocation_index) so non-commutative reducers
+            // like Concat/Merge produce deterministic output across runs.
+            branch_writes.sort_by(|a, b| {
+                a.node_id
+                    .cmp(&b.node_id)
+                    .then(a.invocation_index.cmp(&b.invocation_index))
+            });
+            state.apply_branch_writes(branch_writes, &graph.reducers)?;
+
+            if let Some((node_id, end_state, output)) = end_results.into_iter().next() {
+                let diff = end_state.diff_against(snapshot.as_ref());
+                state.apply_branch_writes(
+                    vec![BranchWrites {
+                        node_id: node_id.clone(),
+                        invocation_index: 0,
+                        writes: diff,
+                    }],
+                    &graph.reducers,
+                )?;
+                logger.graph_complete(&node_id, start.elapsed());
+                return Ok(output);
+            }
+
+            if in_super_step {
+                logger.super_step_end(&sorted_frontier(&next_frontier));
+            }
+            frontier = next_frontier;
+        }
+    }
+}
+
+fn sorted_frontier(frontier: &HashSet<String>) -> Vec<String> {
+    let mut v: Vec<String> = frontier.iter().cloned().collect();
+    v.sort();
+    v
+}
+
+pub(super) struct StepContext<'a> {
+    pub graph: &'a Graph,
+    pub script_executor: &'a ScriptExecutor,
+    pub max_concurrency: usize,
+    pub abort_signal: &'a AbortSignal,
+}
+
+impl StepContext<'_> {
+    pub fn graph_name(&self) -> &str {
+        &self.graph.name
+    }
+}
+
+enum StepResult {
+    // The set of next-node ids the executor should add to the next super-step's
+    // frontier. A `Vec` of length 1 for sequential routing (default) and the
+    // full target list for fan-out (`next: [a, b, ...]`). Dynamic single-route
+    // decisions (script `_next`, approval routes, LLM/RAG fallback) always emit
+    // a single-element vec.
+    Continue(Vec<String>),
+    End(String),
+}
+
+async fn step(
+    node: &Node,
+    state: &mut StateManager,
+    ctx: &mut RequestContext,
+    step_ctx: &StepContext<'_>,
+    current: &str,
+) -> Result<StepResult> {
+    match &node.node_type {
+        NodeType::Agent(agent_node) => {
+            AgentNodeExecutor::execute(agent_node, state, ctx).await?;
+            let targets = static_next_targets(node, current, "agent")?;
+            Ok(StepResult::Continue(targets))
+        }
+        NodeType::Script(script_node) => {
+            let dynamic = match step_ctx.script_executor.execute(script_node, state).await {
+                Ok(n) => n,
+                Err(e) => {
+                    if let Some(fallback) = &script_node.fallback {
+                        warn!(
+                            "[graph:{}] script '{}' failed, routing to fallback '{}': {}",
+                            step_ctx.graph_name(),
+                            current,
+                            fallback,
+                            e
+                        );
+                        return Ok(StepResult::Continue(vec![fallback.clone()]));
+                    }
+                    return Err(e);
+                }
+            };
+            let targets = match dynamic {
+                Some(n) => vec![n],
+                None => static_next_targets(node, current, "script")?,
+            };
+            Ok(StepResult::Continue(targets))
+        }
+        NodeType::Approval(approval_node) => {
+            let next = ApprovalNodeExecutor::execute(approval_node, state, ctx).await?;
+            Ok(StepResult::Continue(vec![next]))
+        }
+        NodeType::Input(input_node) => {
+            let next_id = first_next_target(node);
+            let next = InputNodeExecutor::execute(input_node, next_id, state, ctx).await?;
+            Ok(StepResult::Continue(vec![next]))
+        }
+        NodeType::Llm(llm_node) => {
+            let outcome = LlmNodeExecutor::execute(llm_node, state, ctx).await?;
+            let targets = match outcome {
+                LlmExecutionOutcome::Continue => static_next_targets(node, current, "llm")?,
+                LlmExecutionOutcome::FellBack(target) => vec![target],
+            };
+            Ok(StepResult::Continue(targets))
+        }
+        NodeType::Rag(rag_node) => {
+            RagNodeExecutor::execute(rag_node, current, state, ctx).await?;
+            let targets = static_next_targets(node, current, "rag")?;
+            Ok(StepResult::Continue(targets))
+        }
+        NodeType::End(end_node) => Ok(StepResult::End(resolve_end_output(end_node, state))),
+        NodeType::Map(map_node) => {
+            let targets = static_next_targets(node, current, "map")?;
+            MapNodeExecutor::execute(map_node, state, ctx, step_ctx, current).await?;
+            Ok(StepResult::Continue(targets))
+        }
+    }
+}
+
+fn static_next_targets(node: &Node, current: &str, kind: &str) -> Result<Vec<String>> {
+    node.next
+        .as_ref()
+        .map(|t| t.as_slice().to_vec())
+        .ok_or_else(|| anyhow!("{kind} node '{current}' has no `next` and is not an end node"))
+}
+
+fn first_next_target(node: &Node) -> Option<&str> {
+    node.next
+        .as_ref()
+        .and_then(|t| t.as_slice().first().map(|s| s.as_str()))
+}
+
+fn resolve_end_output(end_node: &EndNode, state: &mut StateManager) -> String {
+    apply_simple_state_updates(end_node.state_updates.as_ref(), state);
+    state.interpolate_lenient(&end_node.output)
+}
+
+fn apply_simple_state_updates(updates: Option<&HashMap<String, String>>, state: &mut StateManager) {
+    let Some(updates) = updates else {
+        return;
+    };
+    for (key, template) in updates {
+        let value = state.interpolate_lenient(template);
+        state.state_mut().set(key.clone(), Value::String(value));
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use serde_json::json;
+
+    fn state_with(pairs: &[(&str, Value)]) -> StateManager {
+        let mut map = HashMap::new();
+        for (k, v) in pairs {
+            map.insert((*k).into(), v.clone());
+        }
+        StateManager::new(map)
+    }
+
+    fn end_node(output: &str, updates: Option<HashMap<String, String>>) -> EndNode {
+        EndNode {
+            output: output.into(),
+            state_updates: updates,
+        }
+    }
+
+    #[test]
+    fn resolve_end_output_interpolates_template_against_state() {
+        let mut state = state_with(&[("name", json!("alice"))]);
+
+        let node = end_node("done: {{name}}", None);
+
+        assert_eq!(resolve_end_output(&node, &mut state), "done: alice");
+    }
+
+    #[test]
+    fn resolve_end_output_applies_state_updates_before_interpolation() {
+        let mut updates = HashMap::new();
+        updates.insert("summary".into(), "completed for {{user}}".into());
+        let node = end_node("RESULT: {{summary}}", Some(updates));
+
+        let mut state = state_with(&[("user", json!("bob"))]);
+
+        assert_eq!(
+            resolve_end_output(&node, &mut state),
+            "RESULT: completed for bob"
+        );
+        assert_eq!(
+            state.state().get("summary"),
+            Some(&json!("completed for bob"))
+        );
+    }
+
+    #[test]
+    fn resolve_end_output_with_empty_template_returns_empty_string() {
+        let mut state = state_with(&[]);
+
+        let node = end_node("", None);
+
+        assert_eq!(resolve_end_output(&node, &mut state), "");
+    }
+
+    #[test]
+    fn resolve_end_output_lenient_on_missing_keys() {
+        let mut state = state_with(&[]);
+
+        let node = end_node("hello {{unknown}}!", None);
+
+        assert_eq!(resolve_end_output(&node, &mut state), "hello !");
+    }
+
+    #[test]
+    fn apply_simple_state_updates_does_nothing_when_none() {
+        let mut state = state_with(&[("k", json!("v"))]);
+
+        apply_simple_state_updates(None, &mut state);
+
+        assert_eq!(state.state().get("k"), Some(&json!("v")));
+    }
+
+    #[test]
+    fn apply_simple_state_updates_overwrites_existing_values() {
+        let mut updates = HashMap::new();
+        updates.insert("k".into(), "new-{{k}}".into());
+        let mut state = state_with(&[("k", json!("old"))]);
+
+        apply_simple_state_updates(Some(&updates), &mut state);
+
+        assert_eq!(state.state().get("k"), Some(&json!("new-old")));
+    }
+}
+
+#[cfg(test)]
+mod integration_tests {
+    use super::*;
+    use crate::config::{AppState, WorkingMode};
+    use crate::utils::{create_abort_signal, temp_file};
+    use std::fs;
+
+    fn cmd_available(name: &str) -> bool {
+        which::which(name).is_ok()
+    }
+
+    struct TestWorkspace {
+        dir: PathBuf,
+    }
+
+    impl TestWorkspace {
+        fn new() -> Self {
+            let dir = temp_file("-graph-integration-", "");
+            fs::create_dir_all(&dir).unwrap();
+            Self { dir }
+        }
+
+        fn write_script(&self, name: &str, contents: &str) {
+            fs::write(self.dir.join(name), contents).unwrap();
+        }
+    }
+
+    impl Drop for TestWorkspace {
+        fn drop(&mut self) {
+            let _ = fs::remove_dir_all(&self.dir);
+        }
+    }
+
+    fn make_ctx() -> RequestContext {
+        RequestContext::new(Arc::new(AppState::test_default()), WorkingMode::Cmd)
+    }
+
+    #[tokio::test]
+    async fn static_fan_out_merges_branch_writes_via_append_reducer() {
+        if !cmd_available("bash") {
+            eprintln!("skipping: bash not available");
+            return;
+        }
+        let ws = TestWorkspace::new();
+        ws.write_script("dispatcher.sh", "#!/bin/bash\necho '{}'\n");
+        ws.write_script(
+            "worker_a.sh",
+            "#!/bin/bash\necho '{\"results\": \"alpha\"}'\n",
+        );
+        ws.write_script(
+            "worker_b.sh",
+            "#!/bin/bash\necho '{\"results\": \"beta\"}'\n",
+        );
+
+        let yaml = r#"
+name: static_fan_out_test
+start: dispatcher
+reducers:
+  results: append
+nodes:
+  dispatcher:
+    type: script
+    script: dispatcher.sh
+    state_updates: {}
+    next: [worker_a, worker_b]
+  worker_a:
+    type: script
+    script: worker_a.sh
+    state_updates: {}
+    next: join
+  worker_b:
+    type: script
+    script: worker_b.sh
+    state_updates: {}
+    next: join
+  join:
+    type: end
+    output: "{{results}}"
+"#;
+        let graph: Graph = serde_yaml::from_str(yaml).unwrap();
+        let mut ctx = make_ctx();
+        let abort = create_abort_signal();
+        let result = GraphExecutor::new(graph, &ws.dir)
+            .execute(&mut ctx, abort)
+            .await
+            .unwrap_or_else(|e| panic!("executor failed: {e:#}"));
+
+        let parsed: Value = serde_json::from_str(&result)
+            .unwrap_or_else(|_| panic!("expected JSON array, got: {result}"));
+        let arr = parsed.as_array().expect("results should be an array");
+        assert_eq!(arr.len(), 2, "expected 2 elements, got: {result}");
+        let strs: Vec<&str> = arr.iter().filter_map(|v| v.as_str()).collect();
+        assert!(strs.contains(&"alpha"), "missing 'alpha' in {strs:?}");
+        assert!(strs.contains(&"beta"), "missing 'beta' in {strs:?}");
+    }
+
+    #[tokio::test]
+    async fn map_over_list_collects_outputs_in_input_order() {
+        if !cmd_available("python3") {
+            eprintln!("skipping: python3 not available");
+            return;
+        }
+        let ws = TestWorkspace::new();
+        ws.write_script(
+            "doubler.py",
+            r#"#!/usr/bin/env python3
+import os, json
+state = json.loads(os.environ.get("GRAPH_STATE", "{}"))
+val = state["item"]
+print(json.dumps({"output": val * 2}))
+"#,
+        );
+
+        let yaml = r#"
+name: map_input_order_test
+start: fan_out
+initial_state:
+  items: [1, 2, 3, 4, 5]
+nodes:
+  fan_out:
+    type: map
+    over: "{{items}}"
+    as: item
+    branch: doubler
+    collect_into: doubled
+    next: done
+  doubler:
+    type: script
+    script: doubler.py
+    state_updates: {}
+  done:
+    type: end
+    output: "{{doubled}}"
+"#;
+        let graph: Graph = serde_yaml::from_str(yaml).unwrap();
+        let mut ctx = make_ctx();
+        let abort = create_abort_signal();
+        let result = GraphExecutor::new(graph, &ws.dir)
+            .execute(&mut ctx, abort)
+            .await
+            .unwrap_or_else(|e| panic!("executor failed: {e:#}"));
+
+        let parsed: Value = serde_json::from_str(&result)
+            .unwrap_or_else(|_| panic!("expected JSON array, got: {result}"));
+        let arr = parsed.as_array().expect("doubled should be an array");
+        let nums: Vec<i64> = arr
+            .iter()
+            .map(|v| v.as_i64().expect("each item should be int"))
+            .collect();
+
+        assert_eq!(
+            nums,
+            vec![2, 4, 6, 8, 10],
+            "map outputs should be in input order, not finish order"
+        );
+    }
+
+    #[tokio::test]
+    async fn parallel_branch_error_aborts_super_step() {
+        if !cmd_available("bash") {
+            eprintln!("skipping: bash not available");
+            return;
+        }
+        let ws = TestWorkspace::new();
+        ws.write_script("dispatcher.sh", "#!/bin/bash\necho '{}'\n");
+        ws.write_script(
+            "worker_ok.sh",
+            "#!/bin/bash\necho '{\"results\": \"ok\"}'\n",
+        );
+        ws.write_script(
+            "worker_fail.sh",
+            "#!/bin/bash\necho 'simulated failure' >&2\nexit 1\n",
+        );
+
+        let yaml = r#"
+name: branch_error_test
+start: dispatcher
+reducers:
+  results: append
+nodes:
+  dispatcher:
+    type: script
+    script: dispatcher.sh
+    state_updates: {}
+    next: [worker_ok, worker_fail]
+  worker_ok:
+    type: script
+    script: worker_ok.sh
+    state_updates: {}
+    next: join
+  worker_fail:
+    type: script
+    script: worker_fail.sh
+    state_updates: {}
+    next: join
+  join:
+    type: end
+    output: "{{results}}"
+"#;
+        let graph: Graph = serde_yaml::from_str(yaml).unwrap();
+        let mut ctx = make_ctx();
+        let abort = create_abort_signal();
+        let result = GraphExecutor::new(graph, &ws.dir)
+            .execute(&mut ctx, abort)
+            .await;
+
+        assert!(result.is_err(), "expected branch error to propagate");
+        let err = format!("{:#}", result.unwrap_err());
+        assert!(
+            err.contains("worker_fail"),
+            "error should mention failing node: {err}"
+        );
+    }
+
+    #[tokio::test]
+    async fn multi_end_in_super_step_is_rejected() {
+        if !cmd_available("bash") {
+            eprintln!("skipping: bash not available");
+            return;
+        }
+        let ws = TestWorkspace::new();
+        ws.write_script("dispatcher.sh", "#!/bin/bash\necho '{}'\n");
+
+        let yaml = r#"
+name: multi_end_test
+start: dispatcher
+nodes:
+  dispatcher:
+    type: script
+    script: dispatcher.sh
+    state_updates: {}
+    next: [end_a, end_b]
+  end_a:
+    type: end
+    output: "from a"
+  end_b:
+    type: end
+    output: "from b"
+"#;
+        let graph: Graph = serde_yaml::from_str(yaml).unwrap();
+        let mut ctx = make_ctx();
+        let abort = create_abort_signal();
+        let result = GraphExecutor::new(graph, &ws.dir)
+            .execute(&mut ctx, abort)
+            .await;
+
+        assert!(result.is_err(), "expected multi-End to be rejected");
+        let err = format!("{:#}", result.unwrap_err());
+        assert!(
+            err.contains("multiple End targets"),
+            "error should explain multi-End cause: {err}"
+        );
+        assert!(
+            err.contains("end_a") && err.contains("end_b"),
+            "error should list both End nodes: {err}"
+        );
+    }
+}
diff --git a/src/graph/llm.rs b/src/graph/llm.rs
new file mode 100644
index 0000000..704490f
--- /dev/null
+++ b/src/graph/llm.rs
@@ -0,0 +1,616 @@
+use super::state::StateManager;
+use super::structured;
+use super::types::LlmNode;
+use crate::client::{Model, ModelType, call_chat_completions};
+use crate::config::{Input, RequestContext, Role, RoleLike};
+use crate::utils::create_abort_signal;
+use anyhow::{Context, Error, Result, anyhow, bail};
+use serde_json::Value;
+use std::collections::HashSet;
+use std::sync::Arc;
+use std::time::Duration;
+use tokio::time::timeout;
+
+const OUTPUT_KEY: &str = "output";
+
+#[derive(Debug, PartialEq, Eq)]
+pub(super) enum LlmExecutionOutcome {
+    Continue,
+    FellBack(String),
+}
+
+pub struct LlmNodeExecutor;
+
+impl LlmNodeExecutor {
+    pub(super) async fn execute(
+        node: &LlmNode,
+        state_manager: &mut StateManager,
+        parent_ctx: &mut RequestContext,
+    ) -> Result<LlmExecutionOutcome> {
+        let result = run(node, state_manager, parent_ctx).await;
+        let (output, failure_reason) = match result {
+            Ok(raw) => match &node.output_schema {
+                Some(schema) => match structured::extract(&raw, schema, parent_ctx).await {
+                    Ok(value) => (value, None),
+                    Err(e) => {
+                        warn!("llm node structured extraction failed: {e}");
+                        (
+                            Value::String(format!("LLM node structured-extraction failed: {e}")),
+                            Some(format!("structured-extraction failed: {e}")),
+                        )
+                    }
+                },
+                None => (Value::String(raw), None),
+            },
+            Err(e) => {
+                warn!("llm node failed: {e}");
+                (
+                    Value::String(format!("LLM node failed: {e}")),
+                    Some(format!("LLM call failed: {e:#}")),
+                )
+            }
+        };
+
+        apply_state_updates_with_output(node, state_manager, &output);
+        outcome_from(failure_reason.as_deref(), node.fallback.as_deref())
+    }
+}
+
+fn outcome_from(
+    failure_reason: Option<&str>,
+    fallback: Option<&str>,
+) -> Result<LlmExecutionOutcome> {
+    match (failure_reason, fallback) {
+        (None, _) => Ok(LlmExecutionOutcome::Continue),
+        (Some(_), Some(fb)) => Ok(LlmExecutionOutcome::FellBack(fb.to_string())),
+        (Some(reason), None) => bail!(
+            "LLM node failed and no fallback declared: {reason}. \
+             Add a `fallback:` route on the node to route on failure, \
+             or fix the underlying error."
+        ),
+    }
+}
+
+async fn run(
+    node: &LlmNode,
+    state_manager: &mut StateManager,
+    parent_ctx: &mut RequestContext,
+) -> Result<String> {
+    let mut instructions: Option<String> = match &node.instructions {
+        Some(s) => Some(
+            state_manager
+                .interpolate(s)
+                .context("Failed to interpolate llm node instructions")?,
+        ),
+        None => None,
+    };
+    let mut prompt = state_manager
+        .interpolate(&node.prompt)
+        .context("Failed to interpolate llm node prompt")?;
+
+    if let Some(schema) = &node.output_schema {
+        let hint = format_schema_hint(schema);
+        match instructions.as_mut() {
+            Some(s) => {
+                s.push_str("\n\n");
+                s.push_str(&hint);
+            }
+            None => {
+                prompt.push_str("\n\n");
+                prompt.push_str(&hint);
+            }
+        }
+    }
+
+    let (regular_tools, mcp_servers) = categorize_tools(node.tools.as_deref());
+    validate_tools_subset(&regular_tools, &mcp_servers, parent_ctx)?;
+
+    let role = build_inline_role(
+        node,
+        instructions.as_deref(),
+        &regular_tools,
+        &mcp_servers,
+        parent_ctx,
+    )?;
+
+    let saved_role = parent_ctx.role.clone();
+    parent_ctx.role = Some(role);
+    let result = match node.timeout {
+        Some(secs) => match timeout(
+            Duration::from_secs(secs),
+            run_with_retries(node, &prompt, parent_ctx),
+        )
+        .await
+        {
+            Ok(r) => r,
+            Err(_) => Err(anyhow!("llm node timed out after {secs}s")),
+        },
+        None => run_with_retries(node, &prompt, parent_ctx).await,
+    };
+    parent_ctx.role = saved_role;
+    result
+}
+
+async fn run_with_retries(
+    node: &LlmNode,
+    prompt: &str,
+    ctx: &mut RequestContext,
+) -> Result<String> {
+    let mut last_err: Option<Error> = None;
+    for attempt in 1..=node.max_attempts {
+        match run_chat_loop(node, prompt, ctx).await {
+            Ok(out) => return Ok(out),
+            Err(e) if is_transient(&e) && attempt < node.max_attempts => {
+                warn!("llm node attempt {attempt} failed (transient): {e}; retrying");
+                last_err = Some(e);
+            }
+            Err(e) => return Err(e),
+        }
+    }
+    Err(last_err.unwrap_or_else(|| anyhow!("llm node exhausted retries")))
+}
+
+async fn run_chat_loop(node: &LlmNode, prompt: &str, ctx: &mut RequestContext) -> Result<String> {
+    let abort = create_abort_signal();
+    let app_cfg = Arc::clone(&ctx.app.config);
+    let role_for_input = ctx.role.clone();
+    let mut input = Input::from_str(ctx, prompt, role_for_input);
+    let mut accumulated = String::new();
+
+    for turn in 0..node.max_iterations {
+        let client = input.create_client()?;
+        ctx.before_chat_completion(&input)?;
+        let (output, tool_results) =
+            call_chat_completions(&input, false, false, client.as_ref(), ctx, abort.clone())
+                .await?;
+        ctx.after_chat_completion(app_cfg.as_ref(), &input, &output, &tool_results)?;
+
+        if !output.is_empty() {
+            if !accumulated.is_empty() {
+                accumulated.push('\n');
+            }
+            accumulated.push_str(&output);
+        }
+
+        if tool_results.is_empty() {
+            return Ok(accumulated);
+        }
+
+        if turn + 1 == node.max_iterations {
+            bail!(
+                "llm node hit max_iterations ({}) before LLM concluded",
+                node.max_iterations
+            );
+        }
+
+        input = input.merge_tool_results(output, tool_results);
+    }
+
+    bail!("llm node ended without producing output")
+}
+
+fn build_inline_role(
+    node: &LlmNode,
+    instructions: Option<&str>,
+    regular_tools: &[String],
+    mcp_servers: &[String],
+    parent_ctx: &RequestContext,
+) -> Result<Role> {
+    let mut role = Role::new("llm_node", instructions.unwrap_or(""));
+
+    let model = match &node.model {
+        Some(model_id) => {
+            Model::retrieve_model(parent_ctx.app.config.as_ref(), model_id, ModelType::Chat)
+                .with_context(|| format!("Unknown model '{model_id}' on llm node"))?
+        }
+        None => parent_ctx.current_model().clone(),
+    };
+    role.set_model(model);
+
+    if let Some(t) = node.temperature {
+        role.set_temperature(Some(t));
+    }
+    if let Some(p) = node.top_p {
+        role.set_top_p(Some(p));
+    }
+
+    if node.tools.as_deref().unwrap_or_default().is_empty() {
+        role.set_enabled_tools(Some(String::new()));
+        role.set_enabled_mcp_servers(Some(String::new()));
+    } else {
+        if !regular_tools.is_empty() {
+            role.set_enabled_tools(Some(regular_tools.join(",")));
+        } else {
+            role.set_enabled_tools(Some(String::new()));
+        }
+        if !mcp_servers.is_empty() {
+            role.set_enabled_mcp_servers(Some(mcp_servers.join(",")));
+        } else {
+            role.set_enabled_mcp_servers(Some(String::new()));
+        }
+    }
+
+    Ok(role)
+}
+
+fn categorize_tools(entries: Option<&[String]>) -> (Vec<String>, Vec<String>) {
+    let mut regular = Vec::new();
+    let mut mcp = Vec::new();
+    let Some(entries) = entries else {
+        return (regular, mcp);
+    };
+
+    for e in entries {
+        if let Some(server) = e.strip_prefix("mcp:") {
+            mcp.push(server.to_string());
+        } else {
+            regular.push(e.clone());
+        }
+    }
+
+    (regular, mcp)
+}
+
+fn validate_tools_subset(
+    regular: &[String],
+    mcp_servers: &[String],
+    parent_ctx: &RequestContext,
+) -> Result<()> {
+    let agent = parent_ctx
+        .agent
+        .as_ref()
+        .ok_or_else(|| anyhow!("llm node requires an active agent"))?;
+
+    if !regular.is_empty() {
+        let known: HashSet<&str> = agent
+            .functions()
+            .declarations()
+            .iter()
+            .map(|d| d.name.as_str())
+            .collect();
+        for name in regular {
+            if !known.contains(name.as_str()) {
+                let mut avail: Vec<&str> = known.iter().copied().collect();
+                avail.sort();
+                bail!(
+                    "llm node references unknown tool '{name}'. Agent '{}' provides: {}",
+                    agent.name(),
+                    avail.join(", ")
+                );
+            }
+        }
+    }
+
+    if !mcp_servers.is_empty() {
+        let known: HashSet<&str> = agent
+            .mcp_server_names()
+            .iter()
+            .map(|s| s.as_str())
+            .collect();
+        for server in mcp_servers {
+            if !known.contains(server.as_str()) {
+                let mut avail: Vec<&str> = known.iter().copied().collect();
+                avail.sort();
+                bail!(
+                    "llm node references unknown MCP server 'mcp:{server}'. \
+                     Agent '{}' has MCP servers: [{}]",
+                    agent.name(),
+                    avail.join(", ")
+                );
+            }
+        }
+    }
+
+    Ok(())
+}
+
+fn is_transient(err: &Error) -> bool {
+    let s = format!("{err:#}");
+    s.contains("timed out")
+        || s.contains("rate limit")
+        || s.contains("429")
+        || s.contains("Connection reset")
+        || s.contains("Connection refused")
+        || s.contains("produced no output")
+}
+
+fn apply_state_updates_with_output(
+    node: &LlmNode,
+    state_manager: &mut StateManager,
+    output: &Value,
+) {
+    if node.output_schema.is_some()
+        && let Some(obj) = output.as_object()
+    {
+        for (k, v) in obj {
+            state_manager.state_mut().set(k.clone(), v.clone());
+        }
+    }
+
+    let Some(updates) = &node.state_updates else {
+        return;
+    };
+    let prev_output = state_manager.state().get(OUTPUT_KEY).cloned();
+    state_manager
+        .state_mut()
+        .set(OUTPUT_KEY.into(), output.clone());
+
+    for (key, template) in updates {
+        let value = state_manager.interpolate_lenient(template);
+        state_manager
+            .state_mut()
+            .set(key.clone(), Value::String(value));
+    }
+
+    match prev_output {
+        Some(v) => state_manager.state_mut().set(OUTPUT_KEY.into(), v),
+        None => {
+            state_manager
+                .state_mut()
+                .set(OUTPUT_KEY.into(), Value::Null);
+        }
+    }
+}
+
+fn format_schema_hint(schema: &Value) -> String {
+    let schema_json = serde_json::to_string_pretty(schema).unwrap_or_else(|_| schema.to_string());
+    format!(
+        "Respond with a JSON object that matches this schema. Output ONLY the JSON \
+         object with no surrounding prose or markdown fences.\n\nSchema:\n{schema_json}"
+    )
+}
+
+#[cfg(test)]
+mod tests {
+    use super::super::types::*;
+    use super::*;
+    use serde_json::json;
+    use std::collections::HashMap;
+
+    fn manager_with(pairs: &[(&str, Value)]) -> StateManager {
+        let mut map = HashMap::new();
+        for (k, v) in pairs {
+            map.insert((*k).into(), v.clone());
+        }
+        StateManager::new(map)
+    }
+
+    fn node_with(updates: Option<HashMap<String, String>>) -> LlmNode {
+        LlmNode {
+            instructions: Some("sys".into()),
+            prompt: "user".into(),
+            tools: None,
+            model: None,
+            temperature: None,
+            top_p: None,
+            fallback: None,
+            max_attempts: 1,
+            max_iterations: 10,
+            state_updates: updates,
+            output_schema: None,
+            timeout: None,
+        }
+    }
+
+    #[test]
+    fn state_updates_expose_output_during_evaluation() {
+        let mut u = HashMap::new();
+        u.insert("response".into(), "{{output}}".into());
+        let node = node_with(Some(u));
+        let mut state = manager_with(&[]);
+
+        apply_state_updates_with_output(&node, &mut state, &json!("the answer"));
+
+        assert_eq!(state.state().get("response"), Some(&json!("the answer")));
+    }
+
+    #[test]
+    fn state_updates_can_mix_existing_keys_with_output() {
+        let mut u = HashMap::new();
+        u.insert("summary".into(), "{{topic}}: {{output}}".into());
+        let node = node_with(Some(u));
+        let mut state = manager_with(&[("topic", json!("LOINC"))]);
+
+        apply_state_updates_with_output(&node, &mut state, &json!("abc"));
+
+        assert_eq!(state.state().get("summary"), Some(&json!("LOINC: abc")));
+    }
+
+    #[test]
+    fn output_key_is_cleared_after_state_updates() {
+        let mut u = HashMap::new();
+        u.insert("k".into(), "{{output}}".into());
+        let node = node_with(Some(u));
+        let mut state = manager_with(&[]);
+
+        apply_state_updates_with_output(&node, &mut state, &json!("anything"));
+
+        assert_eq!(state.state().get(OUTPUT_KEY), Some(&json!(null)));
+    }
+
+    #[test]
+    fn pre_existing_output_value_is_restored() {
+        let mut u = HashMap::new();
+        u.insert("greeting".into(), "{{output}}".into());
+        let node = node_with(Some(u));
+        let mut state = manager_with(&[("output", json!("preserved"))]);
+
+        apply_state_updates_with_output(&node, &mut state, &json!("new"));
+
+        assert_eq!(state.state().get("greeting"), Some(&json!("new")));
+        assert_eq!(state.state().get(OUTPUT_KEY), Some(&json!("preserved")));
+    }
+
+    #[test]
+    fn no_state_updates_is_a_noop() {
+        let node = node_with(None);
+        let mut state = manager_with(&[("k", json!("v"))]);
+
+        apply_state_updates_with_output(&node, &mut state, &json!("x"));
+
+        assert_eq!(state.state().get("k"), Some(&json!("v")));
+        assert!(state.state().get(OUTPUT_KEY).is_none());
+    }
+
+    #[test]
+    fn outcome_from_success_is_continue() {
+        assert_eq!(
+            outcome_from(None, Some("fb")).unwrap(),
+            LlmExecutionOutcome::Continue
+        );
+        assert_eq!(
+            outcome_from(None, None).unwrap(),
+            LlmExecutionOutcome::Continue
+        );
+    }
+
+    #[test]
+    fn outcome_from_failure_with_fallback_is_fell_back() {
+        assert_eq!(
+            outcome_from(Some("HTTP 404"), Some("fb")).unwrap(),
+            LlmExecutionOutcome::FellBack("fb".to_string())
+        );
+    }
+
+    #[test]
+    fn outcome_from_failure_without_fallback_propagates_error() {
+        let err = outcome_from(Some("HTTP 404"), None).unwrap_err();
+        let msg = format!("{err:#}");
+        assert!(msg.contains("no fallback declared"), "got: {msg}");
+        assert!(msg.contains("HTTP 404"), "got: {msg}");
+    }
+
+    fn node_with_schema(updates: Option<HashMap<String, String>>, schema: Value) -> LlmNode {
+        let mut n = node_with(updates);
+        n.output_schema = Some(schema);
+        n
+    }
+
+    #[test]
+    fn output_schema_auto_merges_top_level_keys() {
+        let node = node_with_schema(None, json!({"type": "object"}));
+        let mut state = manager_with(&[]);
+        let output = json!({"goal": "do X", "summary": "details"});
+
+        apply_state_updates_with_output(&node, &mut state, &output);
+
+        assert_eq!(state.state().get("goal"), Some(&json!("do X")));
+        assert_eq!(state.state().get("summary"), Some(&json!("details")));
+    }
+
+    #[test]
+    fn output_schema_preserves_nested_value_types() {
+        let node = node_with_schema(None, json!({"type": "object"}));
+        let mut state = manager_with(&[]);
+        let output = json!({
+            "tags": ["a", "b"],
+            "config": { "key": "value" },
+            "count": 42
+        });
+
+        apply_state_updates_with_output(&node, &mut state, &output);
+
+        assert_eq!(state.state().get("tags"), Some(&json!(["a", "b"])));
+        assert_eq!(state.state().get("config"), Some(&json!({"key": "value"})));
+        assert_eq!(state.state().get("count"), Some(&json!(42)));
+    }
+
+    #[test]
+    fn output_schema_explicit_state_updates_override_auto_merge() {
+        let mut u = HashMap::new();
+        u.insert("goal".into(), "renamed-{{output.goal}}".into());
+        let node = node_with_schema(Some(u), json!({"type": "object"}));
+        let mut state = manager_with(&[]);
+        let output = json!({"goal": "do X"});
+
+        apply_state_updates_with_output(&node, &mut state, &output);
+
+        assert_eq!(state.state().get("goal"), Some(&json!("renamed-do X")));
+    }
+
+    #[test]
+    fn output_schema_skips_auto_merge_for_non_object() {
+        let node = node_with_schema(None, json!({"type": "array"}));
+        let mut state = manager_with(&[]);
+        let output = json!([1, 2, 3]);
+
+        apply_state_updates_with_output(&node, &mut state, &output);
+
+        assert!(state.state().get("0").is_none());
+        assert!(state.state().get(OUTPUT_KEY).is_none());
+    }
+
+    #[test]
+    fn no_schema_does_not_auto_merge() {
+        let node = node_with(None);
+        let mut state = manager_with(&[]);
+        let output = json!({"goal": "do X"});
+
+        apply_state_updates_with_output(&node, &mut state, &output);
+
+        assert!(state.state().get("goal").is_none());
+    }
+
+    #[test]
+    fn format_schema_hint_includes_schema_and_instruction() {
+        let schema = json!({"type": "object", "properties": {"goal": {"type": "string"}}});
+
+        let hint = format_schema_hint(&schema);
+
+        assert!(hint.contains("Schema:"));
+        assert!(hint.contains("\"goal\""));
+        assert!(hint.contains("JSON"));
+        assert!(hint.contains("ONLY"));
+    }
+
+    #[test]
+    fn categorize_tools_splits_mcp_and_regular() {
+        let entries = vec![
+            "read_query".to_string(),
+            "mcp:pubmed-search".to_string(),
+            "web_search_loki".to_string(),
+            "mcp:github".to_string(),
+        ];
+
+        let (regular, mcp) = categorize_tools(Some(&entries));
+
+        assert_eq!(regular, vec!["read_query", "web_search_loki"]);
+        assert_eq!(mcp, vec!["pubmed-search", "github"]);
+    }
+
+    #[test]
+    fn categorize_tools_with_none_returns_empty() {
+        let (regular, mcp) = categorize_tools(None);
+
+        assert!(regular.is_empty());
+        assert!(mcp.is_empty());
+    }
+
+    #[test]
+    fn categorize_tools_with_empty_returns_empty() {
+        let (regular, mcp) = categorize_tools(Some(&[]));
+
+        assert!(regular.is_empty());
+        assert!(mcp.is_empty());
+    }
+
+    #[test]
+    fn is_transient_matches_expected_signatures() {
+        assert!(is_transient(&anyhow!("request timed out after 30s")));
+        assert!(is_transient(&anyhow!("rate limit reached")));
+        assert!(is_transient(&anyhow!("429 too many requests")));
+        assert!(is_transient(&anyhow!("Connection reset by peer")));
+        assert!(is_transient(&anyhow!("Connection refused")));
+        assert!(is_transient(&anyhow!("llm produced no output")));
+    }
+
+    #[test]
+    fn is_transient_rejects_non_transient_errors() {
+        assert!(!is_transient(&anyhow!("Unknown model 'foo'")));
+        assert!(!is_transient(&anyhow!(
+            "llm node references unknown tool 'bad'"
+        )));
+        assert!(!is_transient(&anyhow!("hit max_iterations")));
+        assert!(!is_transient(&anyhow!("authentication failed")));
+    }
+}
diff --git a/src/graph/logging.rs b/src/graph/logging.rs
new file mode 100644
index 0000000..782a761
--- /dev/null
+++ b/src/graph/logging.rs
@@ -0,0 +1,312 @@
+use super::state::StateManager;
+use super::types::{Node, NodeType};
+use crate::utils::dimmed_text;
+use chrono::Local;
+use indexmap::IndexMap;
+use std::cmp::Reverse;
+use std::time::Duration;
+
+fn ts() -> String {
+    Local::now().format("%H:%M:%S").to_string()
+}
+
+fn fmt_secs(elapsed: Duration) -> String {
+    let secs = elapsed.as_secs_f64();
+    if secs < 1.0 {
+        format!("{}ms", elapsed.as_millis())
+    } else {
+        format!("{secs:.2}s")
+    }
+}
+
+#[derive(Debug, Clone, Default)]
+struct NodeTiming {
+    count: usize,
+    total: Duration,
+    max: Duration,
+}
+
+impl NodeTiming {
+    fn record(&mut self, elapsed: Duration) {
+        self.count += 1;
+        self.total += elapsed;
+        if elapsed > self.max {
+            self.max = elapsed;
+        }
+    }
+}
+
+pub struct GraphLogger {
+    graph_name: String,
+    log_state_snapshots: bool,
+    silent: bool,
+    timings: IndexMap<String, NodeTiming>,
+}
+
+impl GraphLogger {
+    pub fn with_visibility(graph_name: &str, log_state_snapshots: bool, silent: bool) -> Self {
+        Self {
+            graph_name: graph_name.to_string(),
+            log_state_snapshots,
+            silent,
+            timings: IndexMap::new(),
+        }
+    }
+
+    pub fn graph_start(&self, start_node: &str, node_count: usize) {
+        info!(
+            "[graph:{}] start at '{}' ({} nodes)",
+            self.graph_name, start_node, node_count
+        );
+        if !self.silent {
+            eprintln!(
+                "{}",
+                dimmed_text(&format!(
+                    "▸ graph: {} (start: {start_node})",
+                    self.graph_name
+                ))
+            );
+        }
+    }
+
+    pub fn graph_complete(&self, end_node: &str, elapsed: Duration) {
+        info!(
+            "[graph:{}] end '{}' (elapsed {:?})",
+            self.graph_name, end_node, elapsed
+        );
+        if !self.silent {
+            eprintln!(
+                "{}",
+                dimmed_text(&format!("▸ graph done in {:.2}s", elapsed.as_secs_f64()))
+            );
+        }
+        self.log_performance_summary();
+    }
+
+    pub fn graph_error(&self, error: &anyhow::Error) {
+        error!("[graph:{}] execution failed: {error:#}", self.graph_name);
+    }
+
+    pub fn node_entry(&self, node: &Node, visit: usize) {
+        debug!(
+            "[graph:{}] entering '{}' (visit {visit})",
+            self.graph_name, node.id
+        );
+    }
+
+    pub fn silent(&self) -> bool {
+        self.silent
+    }
+
+    pub fn node_start(&self, node: &Node, in_super_step: bool) {
+        narrate_node_start(self.silent, node, in_super_step);
+    }
+
+    pub fn super_step_start(&self, branches: &[String]) {
+        if self.silent {
+            return;
+        }
+        eprintln!(
+            "{}",
+            dimmed_text(&format!(
+                "▸ {} super-step start: {}",
+                ts(),
+                branches.join(", ")
+            ))
+        );
+    }
+
+    pub fn super_step_end(&self, targets: &[String]) {
+        if self.silent {
+            return;
+        }
+        let route = if targets.is_empty() {
+            String::new()
+        } else {
+            format!(" -> {}", targets.join(", "))
+        };
+        eprintln!(
+            "{}",
+            dimmed_text(&format!("▸ {} super-step end{route}", ts()))
+        );
+    }
+
+    pub fn record_timing(&mut self, node_id: &str, elapsed: Duration) {
+        self.timings
+            .entry(node_id.to_string())
+            .or_default()
+            .record(elapsed);
+    }
+
+    pub fn routing(&self, from: &str, to: &str) {
+        debug!("[graph:{}] {from} -> {to}", self.graph_name);
+    }
+
+    pub fn validation_warning(&self, node_id: Option<&str>, message: &str) {
+        match node_id {
+            Some(id) => warn!("[graph:{}] [{id}] {message}", self.graph_name),
+            None => warn!("[graph:{}] {message}", self.graph_name),
+        }
+    }
+
+    pub fn state_snapshot(&self, node_id: &str, state: &StateManager) {
+        if !self.log_state_snapshots {
+            return;
+        }
+        let snapshot = state.snapshot();
+        let mut keys: Vec<&str> = snapshot.keys().map(String::as_str).collect();
+        keys.sort_unstable();
+
+        debug!(
+            "[graph:{}] [{node_id}] state: {} bytes, keys={:?}",
+            self.graph_name,
+            state.size_bytes(),
+            keys
+        );
+        trace!(
+            "[graph:{}] [{node_id}] full state: {:?}",
+            self.graph_name, snapshot
+        );
+    }
+
+    fn log_performance_summary(&self) {
+        if self.timings.is_empty() {
+            return;
+        }
+        let mut rows: Vec<(&String, &NodeTiming)> = self.timings.iter().collect();
+        rows.sort_by_key(|b| Reverse(b.1.total));
+
+        info!(
+            "[graph:{}] performance summary (slowest first):",
+            self.graph_name
+        );
+
+        for (node_id, t) in rows {
+            let avg = t.total / t.count.max(1) as u32;
+            info!(
+                "[graph:{}]   {node_id}: {} visit(s), total {}ms, avg {}ms, max {}ms",
+                self.graph_name,
+                t.count,
+                t.total.as_millis(),
+                avg.as_millis(),
+                t.max.as_millis(),
+            );
+        }
+    }
+}
+
+pub fn narrate_node_start(silent: bool, node: &Node, in_super_step: bool) {
+    if silent {
+        return;
+    }
+    let indent = if in_super_step { "  " } else { "" };
+    let label = node_type_label(node);
+    eprintln!(
+        "{}",
+        dimmed_text(&format!("▸ {} {indent}{} ({label}) start", ts(), node.id))
+    );
+}
+
+pub fn narrate_node_complete(
+    silent: bool,
+    node: &Node,
+    elapsed: Duration,
+    next_target: Option<&str>,
+    in_super_step: bool,
+) {
+    if silent {
+        return;
+    }
+    let indent = if in_super_step { "  " } else { "" };
+    let label = node_type_label(node);
+    let dur = fmt_secs(elapsed);
+    let route = next_target.map(|t| format!(" -> {t}")).unwrap_or_default();
+    eprintln!(
+        "{}",
+        dimmed_text(&format!(
+            "▸ {} {indent}{} ({label}) done in {dur}{route}",
+            ts(),
+            node.id
+        ))
+    );
+}
+
+pub fn narrate_node_failed(
+    silent: bool,
+    node: &Node,
+    elapsed: Duration,
+    err: &str,
+    in_super_step: bool,
+) {
+    if silent {
+        return;
+    }
+    let indent = if in_super_step { "  " } else { "" };
+    let label = node_type_label(node);
+    let dur = fmt_secs(elapsed);
+    let excerpt: String = err.chars().take(120).collect();
+    eprintln!(
+        "{}",
+        dimmed_text(&format!(
+            "▸ {} {indent}{} ({label}) FAILED in {dur} -- {excerpt}",
+            ts(),
+            node.id
+        ))
+    );
+}
+
+pub(super) fn node_type_label(node: &Node) -> &'static str {
+    match &node.node_type {
+        NodeType::Agent(_) => "agent",
+        NodeType::Script(_) => "script",
+        NodeType::Approval(_) => "approval",
+        NodeType::Input(_) => "input",
+        NodeType::Llm(_) => "llm",
+        NodeType::Rag(_) => "rag",
+        NodeType::End(_) => "end",
+        NodeType::Map(_) => "map",
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn records_and_aggregates_node_timings() {
+        let mut logger = GraphLogger::with_visibility("g", false, false);
+        logger.record_timing("a", Duration::from_millis(100));
+        logger.record_timing("a", Duration::from_millis(300));
+        logger.record_timing("b", Duration::from_millis(50));
+
+        let a = logger.timings.get("a").unwrap();
+        assert_eq!(a.count, 2);
+        assert_eq!(a.total, Duration::from_millis(400));
+        assert_eq!(a.max, Duration::from_millis(300));
+
+        let b = logger.timings.get("b").unwrap();
+        assert_eq!(b.count, 1);
+        assert_eq!(b.total, Duration::from_millis(50));
+    }
+
+    #[test]
+    fn node_timing_max_tracks_largest() {
+        let mut t = NodeTiming::default();
+
+        t.record(Duration::from_millis(10));
+        t.record(Duration::from_millis(80));
+        t.record(Duration::from_millis(40));
+
+        assert_eq!(t.max, Duration::from_millis(80));
+        assert_eq!(t.count, 3);
+        assert_eq!(t.total, Duration::from_millis(130));
+    }
+
+    #[test]
+    fn new_logger_has_no_timings() {
+        let logger = GraphLogger::with_visibility("g", true, false);
+
+        assert!(logger.timings.is_empty());
+        assert!(logger.log_state_snapshots);
+    }
+}
diff --git a/src/graph/map.rs b/src/graph/map.rs
new file mode 100644
index 0000000..403011a
--- /dev/null
+++ b/src/graph/map.rs
@@ -0,0 +1,152 @@
+use super::agent::AgentNodeExecutor;
+use super::executor::StepContext;
+use super::llm::LlmNodeExecutor;
+use super::rag::RagNodeExecutor;
+use super::state::StateManager;
+use super::types::{MapNode, NodeType};
+use crate::config::{RenderMode, RequestContext};
+use crate::graph::type_name;
+use anyhow::{Context, Result, anyhow};
+use futures_util::future::join_all;
+use serde_json::Value;
+use std::collections::HashMap;
+use std::sync::Arc;
+use tokio::sync::Semaphore;
+
+pub(super) struct MapNodeExecutor;
+
+impl MapNodeExecutor {
+    pub(super) async fn execute(
+        node: &MapNode,
+        state: &mut StateManager,
+        ctx: &mut RequestContext,
+        step_ctx: &StepContext<'_>,
+        node_id: &str,
+    ) -> Result<()> {
+        let over_value = state
+            .interpolate_raw(&node.over)
+            .with_context(|| format!("map node '{node_id}': evaluating `over` template"))?;
+
+        let items = over_value.as_array().ok_or_else(|| {
+            anyhow!(
+                "map node '{}': `over` template '{}' must resolve to an array, got {}",
+                node_id,
+                node.over,
+                type_name(&over_value)
+            )
+        })?;
+        let items = items.clone();
+
+        let branch_node = step_ctx
+            .graph
+            .get_node(&node.branch)
+            .ok_or_else(|| {
+                anyhow!(
+                    "map node '{node_id}': branch '{}' not found in graph",
+                    node.branch
+                )
+            })?
+            .clone();
+
+        let max_conc = node
+            .max_concurrency
+            .unwrap_or(step_ctx.max_concurrency)
+            .max(1);
+        let semaphore = Arc::new(Semaphore::new(max_conc));
+        let mut sub_tasks = Vec::with_capacity(items.len());
+
+        for (idx, item) in items.iter().enumerate() {
+            let item = item.clone();
+            let as_name = node.as_name.clone();
+            let branch_clone = branch_node.clone();
+            let mut sub_state = state.fork_for_branch_state();
+            let mut sub_ctx = ctx.fork_for_branch();
+            sub_ctx.render_mode = RenderMode::Silent;
+            let script_clone = step_ctx.script_executor.clone();
+            let sub_branch_id = node.branch.clone();
+            let sem = semaphore.clone();
+            let abort = step_ctx.abort_signal.clone();
+
+            sub_state.state_mut().set(as_name, item);
+
+            let task = tokio::spawn(async move {
+                let _permit = sem
+                    .acquire()
+                    .await
+                    .expect("map semaphore should not be closed");
+                if abort.aborted() {
+                    return (
+                        idx,
+                        sub_state,
+                        Err(anyhow!("map sub-branch [{idx}] aborted")),
+                    );
+                }
+                let mut state = sub_state;
+                let mut ctx = sub_ctx;
+
+                let exec_result: Result<()> = match &branch_clone.node_type {
+                    NodeType::Llm(n) => LlmNodeExecutor::execute(n, &mut state, &mut ctx)
+                        .await
+                        .map(|_| ()),
+                    NodeType::Agent(n) => AgentNodeExecutor::execute(n, &mut state, &mut ctx)
+                        .await
+                        .map(|_| ()),
+                    NodeType::Rag(n) => {
+                        RagNodeExecutor::execute(n, &sub_branch_id, &mut state, &mut ctx).await
+                    }
+                    NodeType::Script(n) => script_clone.execute(n, &mut state).await.map(|_| ()),
+                    _ => Err(anyhow!(
+                        "map branch '{}' has type that cannot run inside a map \
+                         (validator should have caught this; internal error)",
+                        branch_clone.id
+                    )),
+                };
+
+                (idx, state, exec_result)
+            });
+            sub_tasks.push(task);
+        }
+
+        let joined = join_all(sub_tasks).await;
+
+        // Collect outputs keyed by input index so order is preserved regardless of finish order.
+        let mut outputs: HashMap<usize, Value> = HashMap::new();
+        for join_result in joined {
+            let (idx, sub_state, exec_result) =
+                join_result.map_err(|e| anyhow!("map sub-branch panicked: {e}"))?;
+
+            exec_result
+                .with_context(|| format!("map node '{node_id}': sub-branch [{idx}] failed"))?;
+
+            let output_value = sub_state
+                .state()
+                .get(&node.output_key)
+                .cloned()
+                .ok_or_else(|| {
+                    anyhow!(
+                        "map node '{node_id}': sub-branch [{idx}] did not write \
+                         `output_key` '{}'",
+                        node.output_key
+                    )
+                })?;
+
+            outputs.insert(idx, output_value);
+        }
+
+        let mut collected = Vec::with_capacity(items.len());
+        for idx in 0..items.len() {
+            let value = outputs.remove(&idx).ok_or_else(|| {
+                anyhow!(
+                    "map node '{node_id}': internal error: missing result for sub-branch [{idx}]"
+                )
+            })?;
+            collected.push(value);
+        }
+
+        state
+            .state_mut()
+            .set(node.collect_into.clone(), Value::Array(collected));
+
+        Ok(())
+    }
+}
diff --git a/src/graph/mod.rs b/src/graph/mod.rs
new file mode 100644
index 0000000..b5355d8
--- /dev/null
+++ b/src/graph/mod.rs
@@ -0,0 +1,39 @@
+pub mod agent;
+pub mod dispatch;
+pub mod executor;
+pub mod llm;
+pub mod logging;
+pub mod map;
+pub mod parser;
+pub mod rag;
+pub mod reducer;
+pub mod script;
+pub mod staging;
+pub mod state;
+pub mod structured;
+pub mod types;
+pub mod user_interaction;
+pub mod validator;
+
+pub use dispatch::{active_agent_graph_name, run_active_agent_graph};
+pub use executor::GraphExecutor;
+pub use parser::{GraphParser, agent_has_graph};
+use serde_json::Value;
+pub use types::{Graph, NodeType};
+
+pub const GRAPH_SCHEMA_VERSION: &str = "1.0";
+
+pub const DEFAULT_MAX_LOOP_ITERATIONS: usize = 100;
+
+pub const MAX_STATE_SIZE_BYTES: usize = 32 * 1024;
+
+pub(in crate::graph) fn type_name(value: &Value) -> &'static str {
+    match value {
+        Value::Null => "null",
+        Value::Bool(_) => "bool",
+        Value::Number(_) => "number",
+        Value::String(_) => "string",
+        Value::Array(_) => "array",
+        Value::Object(_) => "object",
+    }
+}
diff --git a/src/graph/parser.rs b/src/graph/parser.rs
new file mode 100644
index 0000000..58b6a5f
--- /dev/null
+++ b/src/graph/parser.rs
@@ -0,0 +1,462 @@
+use super::types::Graph;
+use crate::config::paths;
+use anyhow::{Context, Error, Result, anyhow, bail};
+use std::fs::read_to_string;
+use std::path::{Path, PathBuf};
+
+const SUPPORTED_VERSIONS: &[&str] = &["1.0"];
+
+pub struct GraphParser {
+    base_dir: PathBuf,
+}
+
+impl GraphParser {
+    pub fn new(base_dir: impl Into<PathBuf>) -> Self {
+        Self {
+            base_dir: base_dir.into(),
+        }
+    }
+
+    pub fn load_from_file(&self, path: impl AsRef<Path>) -> Result<Graph> {
+        let path = path.as_ref();
+        let full_path = if path.is_absolute() {
+            path.to_path_buf()
+        } else {
+            self.base_dir.join(path)
+        };
+
+        let contents = read_to_string(&full_path)
+            .with_context(|| format!("Failed to read graph file at '{}'", full_path.display()))?;
+
+        self.load_from_string(&contents)
+            .with_context(|| format!("Failed to parse graph file at '{}'", full_path.display()))
+    }
+
+    pub fn load_from_string(&self, yaml: &str) -> Result<Graph> {
+        let mut graph: Graph = serde_yaml::from_str(yaml).map_err(enhance_yaml_error)?;
+
+        validate_schema_version(&graph.version)?;
+
+        for (key, node) in &mut graph.nodes {
+            if node.id.is_empty() {
+                node.id = key.clone();
+            } else if &node.id != key {
+                bail!(
+                    "Node ID mismatch: key '{}' does not match node.id '{}'",
+                    key,
+                    node.id
+                );
+            }
+        }
+
+        validate_structure(&graph)?;
+
+        Ok(graph)
+    }
+}
+
+fn validate_schema_version(version: &str) -> Result<()> {
+    if !SUPPORTED_VERSIONS.contains(&version) {
+        bail!(
+            "Unsupported graph schema version '{}'. Supported versions: {}",
+            version,
+            SUPPORTED_VERSIONS.join(", ")
+        );
+    }
+
+    Ok(())
+}
+
+fn validate_structure(graph: &Graph) -> Result<()> {
+    if graph.name.is_empty() {
+        bail!("Graph must have a non-empty 'name' field");
+    }
+
+    if graph.nodes.is_empty() {
+        bail!("Graph '{}' has no nodes defined", graph.name);
+    }
+
+    if !graph.has_node(&graph.start) {
+        bail!(
+            "Start node '{}' not found in graph '{}'. Available nodes: {}",
+            graph.start,
+            graph.name,
+            graph.node_ids().join(", ")
+        );
+    }
+
+    Ok(())
+}
+
+fn enhance_yaml_error(error: serde_yaml::Error) -> Error {
+    let msg = error.to_string();
+
+    let hint = if msg.contains("missing field") {
+        "\n\nHint: Check that all required fields are present.\n\
+         Top-level required fields: `name`, `start`, `nodes`.\n\
+         Each node requires `type` plus that type's fields:\n\
+         - agent:    `agent`, `prompt`\n\
+         - script:   `script`\n\
+         - approval: `question`, `options`, `routes`, `on_other`\n\
+         - input:    `question`\n\
+         - llm:      `prompt`\n\
+         - rag:      `documents`\n\
+         - end:      (no required fields)"
+    } else if msg.contains("unknown field") || msg.contains("unknown variant") {
+        "\n\nHint: Check for typos in field names or `type:` values.\n\
+         Valid node types: agent, script, approval, input, llm, rag, end."
+    } else if msg.contains("invalid type") {
+        "\n\nHint: Check that field values have the correct type.\n\
+         - Strings should be quoted if they contain special characters\n\
+         - Numbers should not be quoted\n\
+         - Lists use YAML array syntax (- item1)\n\
+         - Maps use YAML object syntax (key: value)"
+    } else {
+        ""
+    };
+
+    anyhow!("YAML parsing error: {}{}", msg, hint)
+}
+
+pub fn agent_has_graph(agent_name: &str) -> bool {
+    paths::agent_graph_file(agent_name).exists()
+}
+
+#[cfg(test)]
+mod tests {
+    use super::super::GRAPH_SCHEMA_VERSION;
+    use super::super::types::NodeType;
+    use super::*;
+    use indoc::formatdoc;
+    use std::fs::File;
+    use std::io::Write;
+    use std::{env, fs, process};
+
+    fn parser() -> GraphParser {
+        GraphParser::new(env::current_dir().unwrap())
+    }
+
+    #[test]
+    fn parses_a_simple_graph() {
+        let yaml = formatdoc! {r#"
+            name: simple_graph
+            version: "1.0"
+            start: node1
+            nodes:
+              node1:
+                id: node1
+                type: agent
+                agent: test_agent
+                prompt: "Hello world"
+                next: node2
+              node2:
+                id: node2
+                type: end
+                output: done
+            "#};
+
+        let graph = parser().load_from_string(&yaml).unwrap();
+
+        assert_eq!(graph.name, "simple_graph");
+        assert_eq!(graph.start, "node1");
+        assert_eq!(graph.nodes.len(), 2);
+        assert_eq!(
+            graph.nodes.get("node1").unwrap().next_target(),
+            Some("node2")
+        );
+    }
+
+    #[test]
+    fn auto_fills_node_ids_from_keys() {
+        let yaml = formatdoc! {r#"
+            name: auto_id_graph
+            version: "1.0"
+            start: node1
+            nodes:
+              node1:
+                type: agent
+                agent: test_agent
+                prompt: Test
+                next: node2
+              node2:
+                type: end
+                output: done
+            "#};
+
+        let graph = parser().load_from_string(&yaml).unwrap();
+
+        assert_eq!(graph.nodes.get("node1").unwrap().id, "node1");
+        assert_eq!(graph.nodes.get("node2").unwrap().id, "node2");
+    }
+
+    #[test]
+    fn rejects_missing_start_node() {
+        let yaml = formatdoc! {r#"
+            name: bad_graph
+            version: "1.0"
+            start: nonexistent
+            nodes:
+              node1:
+                type: end
+            "#};
+
+        let err = parser().load_from_string(&yaml).unwrap_err().to_string();
+
+        assert!(
+            err.contains("Start node 'nonexistent' not found"),
+            "got: {err}"
+        );
+    }
+
+    #[test]
+    fn rejects_empty_graph_name() {
+        let yaml = formatdoc! {r#"
+            name: ""
+            version: "1.0"
+            start: node1
+            nodes:
+              node1:
+                type: end
+            "#};
+
+        let err = parser().load_from_string(&yaml).unwrap_err().to_string();
+
+        assert!(err.contains("non-empty 'name'"), "got: {err}");
+    }
+
+    #[test]
+    fn rejects_no_nodes() {
+        let yaml = formatdoc! {r#"
+            name: empty_graph
+            version: "1.0"
+            start: node1
+            nodes: {}
+            "#, "{}"};
+
+        let err = parser().load_from_string(&yaml).unwrap_err().to_string();
+
+        assert!(err.contains("no nodes defined"), "got: {err}");
+    }
+
+    #[test]
+    fn rejects_unsupported_version() {
+        let yaml = formatdoc! {r#"
+            name: future_graph
+            version: "2.0"
+            start: node1
+            nodes:
+              node1:
+                type: end
+            "#};
+
+        let err = parser().load_from_string(&yaml).unwrap_err().to_string();
+
+        assert!(
+            err.contains("Unsupported graph schema version"),
+            "got: {err}"
+        );
+    }
+
+    #[test]
+    fn rejects_node_id_mismatch() {
+        let yaml = formatdoc! {r#"
+            name: mismatch_graph
+            version: "1.0"
+            start: node1
+            nodes:
+              node1:
+                id: different_id
+                type: end
+            "#};
+
+        let err = parser().load_from_string(&yaml).unwrap_err().to_string();
+
+        assert!(err.contains("Node ID mismatch"), "got: {err}");
+    }
+
+    #[test]
+    fn parses_approval_node_with_routes() {
+        let yaml = formatdoc! {r#"
+            name: approval_graph
+            version: "1.0"
+            start: approval1
+            nodes:
+              approval1:
+                type: approval
+                question: "Proceed with deployment?"
+                options:
+                  - "Yes"
+                  - "No"
+                routes:
+                  "Yes": deploy
+                  "No": cancel
+                on_other: cancel
+              deploy:
+                type: end
+              cancel:
+                type: end
+            "#};
+
+        let graph = parser().load_from_string(&yaml).unwrap();
+
+        let approval = graph.nodes.get("approval1").unwrap();
+        match &approval.node_type {
+            NodeType::Approval(a) => {
+                assert_eq!(a.options.len(), 2);
+                assert_eq!(a.routes.len(), 2);
+                assert_eq!(a.routes.get("Yes").map(|s| s.as_str()), Some("deploy"));
+            }
+            _ => panic!("expected approval node"),
+        }
+    }
+
+    #[test]
+    fn parses_settings_overrides() {
+        let yaml = formatdoc! {r#"
+            name: settings_graph
+            version: "1.0"
+            start: node1
+            settings:
+              max_loop_iterations: 50
+              timeout: 300
+              log_state_snapshots: false
+            nodes:
+              node1:
+                type: end
+            "#};
+
+        let graph = parser().load_from_string(&yaml).unwrap();
+
+        assert_eq!(graph.settings.max_loop_iterations, 50);
+        assert_eq!(graph.settings.timeout, Some(300));
+        assert!(!graph.settings.log_state_snapshots);
+        assert!(graph.settings.validate_before_run);
+    }
+
+    #[test]
+    fn parses_initial_state() {
+        let yaml = formatdoc! {r#"
+            name: state_graph
+            version: "1.0"
+            start: node1
+            initial_state:
+              user_name: "Alice"
+              count: 42
+              enabled: true
+            nodes:
+              node1:
+                type: end
+            "#};
+
+        let graph = parser().load_from_string(&yaml).unwrap();
+
+        assert_eq!(graph.initial_state.len(), 3);
+        assert_eq!(graph.initial_state.get("user_name").unwrap(), "Alice");
+        assert_eq!(
+            graph.initial_state.get("count").unwrap(),
+            &serde_json::json!(42)
+        );
+        assert_eq!(
+            graph.initial_state.get("enabled").unwrap(),
+            &serde_json::json!(true)
+        );
+    }
+
+    #[test]
+    fn uses_default_version_when_absent() {
+        let yaml = formatdoc! {r#"
+            name: no_version
+            start: node1
+            nodes:
+              node1:
+                type: end
+            "#};
+
+        let graph = parser().load_from_string(&yaml).unwrap();
+
+        assert_eq!(graph.version, GRAPH_SCHEMA_VERSION);
+    }
+
+    #[test]
+    fn rejects_unknown_node_type_with_hint() {
+        let yaml = formatdoc! {r#"
+            name: bad_type
+            version: "1.0"
+            start: node1
+            nodes:
+              node1:
+                type: nonsense
+            "#};
+
+        let err = parser().load_from_string(&yaml).unwrap_err().to_string();
+
+        assert!(
+            err.contains("Valid node types") || err.contains("unknown variant"),
+            "got: {err}"
+        );
+    }
+
+    #[test]
+    fn rejects_malformed_yaml() {
+        let yaml = "name: bad\n  bad: indent\nstart: a";
+
+        let result = parser().load_from_string(yaml);
+
+        assert!(result.is_err());
+    }
+
+    #[test]
+    fn missing_required_fields_have_a_hint() {
+        let yaml = formatdoc! {r#"
+            name: missing_start
+            version: "1.0"
+            nodes:
+              node1:
+                type: end
+            "#};
+
+        let err = parser().load_from_string(&yaml).unwrap_err().to_string();
+
+        assert!(err.contains("Hint"), "got: {err}");
+    }
+
+    #[test]
+    fn load_from_file_reads_disk() {
+        let dir = env::temp_dir();
+        let path = dir.join(format!("loki_graph_parser_test_{}.yaml", process::id()));
+        let yaml = formatdoc! {r#"
+            name: disk_graph
+            version: "1.0"
+            start: only
+            nodes:
+              only:
+                type: end
+                output: ok
+            "#};
+        {
+            let mut f = File::create(&path).unwrap();
+            f.write_all(yaml.as_bytes()).unwrap();
+        }
+
+        let graph = GraphParser::new(dir).load_from_file(&path).unwrap();
+
+        assert_eq!(graph.name, "disk_graph");
+
+        let _ = fs::remove_file(&path);
+    }
+
+    #[test]
+    fn load_from_file_errors_on_missing_path() {
+        let err = parser()
+            .load_from_file("/definitely/not/a/real/path/to_any_graph.yaml")
+            .unwrap_err()
+            .to_string();
+
+        assert!(err.contains("Failed to read graph file"), "got: {err}");
+    }
+
+    #[test]
+    fn agent_has_graph_false_for_unknown_agent() {
+        assert!(!agent_has_graph("__nonexistent_agent_for_test__"));
+    }
+}
diff --git a/src/graph/rag.rs b/src/graph/rag.rs
new file mode 100644
index 0000000..2aed523
--- /dev/null
+++ b/src/graph/rag.rs
@@ -0,0 +1,129 @@
+use super::state::StateManager;
+use super::types::RagNode;
+use crate::config::RequestContext;
+use crate::utils::create_abort_signal;
+use anyhow::{Context, Result, anyhow};
+use serde_json::{Map, Value};
+use std::time::Duration;
+use tokio::time::timeout;
+
+const OUTPUT_KEY: &str = "output";
+const DEFAULT_QUERY: &str = "{{initial_prompt}}";
+const DEFAULT_RAG_TIMEOUT_SECS: u64 = 120;
+
+pub struct RagNodeExecutor;
+
+impl RagNodeExecutor {
+    pub(super) async fn execute(
+        node: &RagNode,
+        node_id: &str,
+        state_manager: &mut StateManager,
+        ctx: &mut RequestContext,
+    ) -> Result<()> {
+        let query_template = node.query.as_deref().unwrap_or(DEFAULT_QUERY);
+        let query = state_manager
+            .interpolate(query_template)
+            .context("Failed to interpolate rag node query")?;
+
+        let rag = ctx
+            .agent
+            .as_ref()
+            .and_then(|a| a.graph_rag(node_id))
+            .ok_or_else(|| anyhow!("rag node '{node_id}' has no initialized knowledge base"))?;
+
+        let top_k = node.top_k.unwrap_or_else(|| rag.configured_top_k());
+        let rerank = rag.configured_reranker();
+
+        let timeout_dur = Duration::from_secs(node.timeout.unwrap_or(DEFAULT_RAG_TIMEOUT_SECS));
+        let abort = create_abort_signal();
+        let (context, sources_str, _ids) =
+            timeout(timeout_dur, rag.search(&query, top_k, rerank, abort))
+                .await
+                .with_context(|| {
+                    format!(
+                        "rag node '{node_id}' timed out after {}s",
+                        timeout_dur.as_secs()
+                    )
+                })?
+                .with_context(|| format!("rag node '{node_id}' retrieval failed"))?;
+
+        let output = build_rag_output(context, &sources_str);
+        apply_state_updates(node, state_manager, &output);
+        Ok(())
+    }
+}
+
+/// Assemble the `{{output}}` value as `{ "context": <ctx>, "sources": [...] }`.
+fn build_rag_output(context: String, sources_str: &str) -> Value {
+    let sources: Vec<Value> = sources_str
+        .lines()
+        .map(|line| line.trim().trim_start_matches("- ").trim())
+        .filter(|s| !s.is_empty())
+        .map(|s| Value::String(s.to_string()))
+        .collect();
+    let mut obj = Map::new();
+
+    obj.insert("context".into(), Value::String(context));
+    obj.insert("sources".into(), Value::Array(sources));
+
+    Value::Object(obj)
+}
+
+fn apply_state_updates(node: &RagNode, state_manager: &mut StateManager, output: &Value) {
+    let Some(updates) = &node.state_updates else {
+        return;
+    };
+    let prev_output = state_manager.state().get(OUTPUT_KEY).cloned();
+    state_manager
+        .state_mut()
+        .set(OUTPUT_KEY.into(), output.clone());
+
+    for (key, template) in updates {
+        let value = state_manager.interpolate_lenient(template);
+        state_manager
+            .state_mut()
+            .set(key.clone(), Value::String(value));
+    }
+
+    match prev_output {
+        Some(v) => state_manager.state_mut().set(OUTPUT_KEY.into(), v),
+        None => state_manager
+            .state_mut()
+            .set(OUTPUT_KEY.into(), Value::Null),
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use serde_json::json;
+
+    #[test]
+    fn build_rag_output_splits_bullet_sources_into_array() {
+        let out = build_rag_output("ctx".into(), "- a.md\n- https://x.com/spec");
+
+        assert_eq!(out["context"], json!("ctx"));
+        assert_eq!(out["sources"], json!(["a.md", "https://x.com/spec"]));
+    }
+
+    #[test]
+    fn build_rag_output_handles_empty_sources() {
+        let out = build_rag_output("ctx".into(), "");
+
+        assert_eq!(out["sources"], json!([]));
+    }
+
+    #[test]
+    fn build_rag_output_ignores_blank_lines() {
+        let out = build_rag_output("c".into(), "- a\n\n- b\n");
+
+        assert_eq!(out["sources"], json!(["a", "b"]));
+    }
+
+    #[test]
+    fn build_rag_output_tolerates_unprefixed_lines() {
+        let out = build_rag_output("c".into(), "plain/path");
+
+        assert_eq!(out["sources"], json!(["plain/path"]));
+    }
+}
diff --git a/src/graph/reducer.rs b/src/graph/reducer.rs
new file mode 100644
index 0000000..10eeec6
--- /dev/null
+++ b/src/graph/reducer.rs
@@ -0,0 +1,389 @@
+use super::types::Reducer;
+use crate::graph::type_name;
+use anyhow::{Result, bail};
+use serde_json::{Number, Value};
+
+pub fn apply(reducer: Reducer, current: Option<&Value>, incoming: Value) -> Result<Value> {
+    match reducer {
+        Reducer::Append => apply_append(current, incoming),
+        Reducer::Extend => apply_extend(current, incoming),
+        Reducer::Concat => apply_concat(current, incoming),
+        Reducer::Sum => apply_sum(current, incoming),
+        Reducer::Max => apply_max(current, incoming),
+        Reducer::Min => apply_min(current, incoming),
+        Reducer::Merge => apply_merge(current, incoming),
+        Reducer::Overwrite => Ok(incoming),
+    }
+}
+
+fn apply_append(current: Option<&Value>, incoming: Value) -> Result<Value> {
+    let mut arr = match current {
+        None => Vec::new(),
+        Some(Value::Array(a)) => a.clone(),
+        Some(other) => bail!(
+            "reducer 'append' requires an array (or absent) for the current value, got {}",
+            type_name(other)
+        ),
+    };
+    arr.push(incoming);
+
+    Ok(Value::Array(arr))
+}
+
+fn apply_extend(current: Option<&Value>, incoming: Value) -> Result<Value> {
+    let mut arr = match current {
+        None => Vec::new(),
+        Some(Value::Array(a)) => a.clone(),
+        Some(other) => bail!(
+            "reducer 'extend' requires an array (or absent) for the current value, got {}",
+            type_name(other)
+        ),
+    };
+    match incoming {
+        Value::Array(items) => arr.extend(items),
+        other => bail!(
+            "reducer 'extend' requires an array for the incoming value, got {}",
+            type_name(&other)
+        ),
+    }
+
+    Ok(Value::Array(arr))
+}
+
+fn apply_concat(current: Option<&Value>, incoming: Value) -> Result<Value> {
+    let incoming_str = match incoming {
+        Value::String(s) => s,
+        other => bail!(
+            "reducer 'concat' requires a string for the incoming value, got {}",
+            type_name(&other)
+        ),
+    };
+    let result = match current {
+        None => incoming_str,
+        Some(Value::String(c)) => {
+            if c.is_empty() {
+                incoming_str
+            } else {
+                format!("{c}\n{incoming_str}")
+            }
+        }
+        Some(other) => bail!(
+            "reducer 'concat' requires a string (or absent) for the current value, got {}",
+            type_name(other)
+        ),
+    };
+
+    Ok(Value::String(result))
+}
+
+fn apply_sum(current: Option<&Value>, incoming: Value) -> Result<Value> {
+    let i = number_or_error(&incoming, "sum", "incoming")?;
+    let c = match current {
+        None => 0.0,
+        Some(value) => number_or_error(value, "sum", "current")?,
+    };
+
+    Ok(json_number(c + i))
+}
+
+fn apply_max(current: Option<&Value>, incoming: Value) -> Result<Value> {
+    let i = number_or_error(&incoming, "max", "incoming")?;
+    match current {
+        None => Ok(json_number(i)),
+        Some(value) => {
+            let c = number_or_error(value, "max", "current")?;
+            Ok(json_number(c.max(i)))
+        }
+    }
+}
+
+fn apply_min(current: Option<&Value>, incoming: Value) -> Result<Value> {
+    let i = number_or_error(&incoming, "min", "incoming")?;
+    match current {
+        None => Ok(json_number(i)),
+        Some(value) => {
+            let c = number_or_error(value, "min", "current")?;
+            Ok(json_number(c.min(i)))
+        }
+    }
+}
+
+fn apply_merge(current: Option<&Value>, incoming: Value) -> Result<Value> {
+    let mut map = match current {
+        None => serde_json::Map::new(),
+        Some(Value::Object(m)) => m.clone(),
+        Some(other) => bail!(
+            "reducer 'merge' requires an object (or absent) for the current value, got {}",
+            type_name(other)
+        ),
+    };
+    match incoming {
+        Value::Object(items) => {
+            for (k, v) in items {
+                map.insert(k, v);
+            }
+        }
+        other => bail!(
+            "reducer 'merge' requires an object for the incoming value, got {}",
+            type_name(&other)
+        ),
+    }
+
+    Ok(Value::Object(map))
+}
+
+fn number_or_error(value: &Value, reducer_name: &str, position: &str) -> Result<f64> {
+    match value.as_f64() {
+        Some(n) => Ok(n),
+        None => bail!(
+            "reducer '{reducer_name}' requires a number for the {position} value, got {}",
+            type_name(value)
+        ),
+    }
+}
+
+// Numeric reducers compute in f64 for simplicity. Integer typing is preserved when the result is losslessly
+// representable as i64.
+fn json_number(n: f64) -> Value {
+    if n.fract() == 0.0 && n.is_finite() && n.abs() <= (i64::MAX as f64) {
+        Value::Number(Number::from(n as i64))
+    } else {
+        match Number::from_f64(n) {
+            Some(num) => Value::Number(num),
+            None => Value::Null,
+        }
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use serde_json::json;
+
+    #[test]
+    fn append_to_absent_creates_single_element_array() {
+        let result = apply(Reducer::Append, None, json!("a")).unwrap();
+
+        assert_eq!(result, json!(["a"]));
+    }
+
+    #[test]
+    fn append_pushes_onto_existing_array() {
+        let current = json!(["a", "b"]);
+        let result = apply(Reducer::Append, Some(&current), json!("c")).unwrap();
+
+        assert_eq!(result, json!(["a", "b", "c"]));
+    }
+
+    #[test]
+    fn append_errors_when_current_is_not_array() {
+        let current = json!("not an array");
+
+        let err = apply(Reducer::Append, Some(&current), json!("x"))
+            .unwrap_err()
+            .to_string();
+
+        assert!(err.contains("'append'"), "got: {err}");
+        assert!(err.contains("string"), "got: {err}");
+    }
+
+    #[test]
+    fn extend_concatenates_arrays() {
+        let current = json!([1, 2]);
+
+        let result = apply(Reducer::Extend, Some(&current), json!([3, 4])).unwrap();
+
+        assert_eq!(result, json!([1, 2, 3, 4]));
+    }
+
+    #[test]
+    fn extend_from_absent_with_array() {
+        let result = apply(Reducer::Extend, None, json!([1, 2])).unwrap();
+
+        assert_eq!(result, json!([1, 2]));
+    }
+
+    #[test]
+    fn extend_errors_when_incoming_is_not_array() {
+        let err = apply(Reducer::Extend, None, json!(42))
+            .unwrap_err()
+            .to_string();
+
+        assert!(err.contains("'extend'"), "got: {err}");
+        assert!(err.contains("number"), "got: {err}");
+        assert!(err.contains("incoming"), "got: {err}");
+    }
+
+    #[test]
+    fn concat_joins_strings_with_newline() {
+        let current = json!("first");
+
+        let result = apply(Reducer::Concat, Some(&current), json!("second")).unwrap();
+
+        assert_eq!(result, json!("first\nsecond"));
+    }
+
+    #[test]
+    fn concat_from_absent_yields_incoming() {
+        let result = apply(Reducer::Concat, None, json!("hello")).unwrap();
+
+        assert_eq!(result, json!("hello"));
+    }
+
+    #[test]
+    fn concat_skips_separator_when_current_is_empty_string() {
+        let current = json!("");
+
+        let result = apply(Reducer::Concat, Some(&current), json!("first")).unwrap();
+
+        assert_eq!(result, json!("first"));
+    }
+
+    #[test]
+    fn concat_errors_when_incoming_is_not_string() {
+        let err = apply(Reducer::Concat, None, json!(42))
+            .unwrap_err()
+            .to_string();
+
+        assert!(err.contains("'concat'"), "got: {err}");
+        assert!(err.contains("number"), "got: {err}");
+    }
+
+    #[test]
+    fn sum_adds_numbers() {
+        let current = json!(5);
+
+        let result = apply(Reducer::Sum, Some(&current), json!(7)).unwrap();
+
+        assert_eq!(result, json!(12));
+    }
+
+    #[test]
+    fn sum_starts_from_zero_when_current_absent() {
+        let result = apply(Reducer::Sum, None, json!(3.5)).unwrap();
+
+        assert_eq!(result, json!(3.5));
+    }
+
+    #[test]
+    fn sum_preserves_integer_type_for_whole_results() {
+        let current = json!(2);
+
+        let result = apply(Reducer::Sum, Some(&current), json!(3)).unwrap();
+
+        assert!(result.is_i64(), "expected integer, got {result:?}");
+        assert_eq!(result, json!(5));
+    }
+
+    #[test]
+    fn sum_uses_float_when_result_has_fractional() {
+        let current = json!(1.5);
+        let result = apply(Reducer::Sum, Some(&current), json!(2.25)).unwrap();
+
+        assert_eq!(result, json!(3.75));
+    }
+
+    #[test]
+    fn sum_errors_on_string_incoming() {
+        let err = apply(Reducer::Sum, None, json!("not a number"))
+            .unwrap_err()
+            .to_string();
+
+        assert!(err.contains("'sum'"), "got: {err}");
+        assert!(err.contains("string"), "got: {err}");
+    }
+
+    #[test]
+    fn max_returns_larger_of_two() {
+        let current = json!(5);
+        let result = apply(Reducer::Max, Some(&current), json!(3)).unwrap();
+        assert_eq!(result, json!(5));
+
+        let result = apply(Reducer::Max, Some(&current), json!(10)).unwrap();
+        assert_eq!(result, json!(10));
+    }
+
+    #[test]
+    fn max_yields_incoming_when_current_absent() {
+        let result = apply(Reducer::Max, None, json!(42)).unwrap();
+
+        assert_eq!(result, json!(42));
+    }
+
+    #[test]
+    fn min_returns_smaller_of_two() {
+        let current = json!(5);
+        let result = apply(Reducer::Min, Some(&current), json!(3)).unwrap();
+        assert_eq!(result, json!(3));
+
+        let result = apply(Reducer::Min, Some(&current), json!(10)).unwrap();
+        assert_eq!(result, json!(5));
+    }
+
+    #[test]
+    fn min_errors_on_non_numeric_current() {
+        let current = json!("oops");
+
+        let err = apply(Reducer::Min, Some(&current), json!(1))
+            .unwrap_err()
+            .to_string();
+
+        assert!(err.contains("'min'"), "got: {err}");
+        assert!(err.contains("current"), "got: {err}");
+    }
+
+    #[test]
+    fn merge_unions_objects_with_incoming_winning_collisions() {
+        let current = json!({ "a": 1, "b": 2 });
+        let incoming = json!({ "b": 99, "c": 3 });
+
+        let result = apply(Reducer::Merge, Some(&current), incoming).unwrap();
+
+        assert_eq!(result, json!({ "a": 1, "b": 99, "c": 3 }));
+    }
+
+    #[test]
+    fn merge_from_absent_yields_incoming_object() {
+        let result = apply(Reducer::Merge, None, json!({ "k": "v" })).unwrap();
+
+        assert_eq!(result, json!({ "k": "v" }));
+    }
+
+    #[test]
+    fn merge_errors_when_incoming_is_not_object() {
+        let err = apply(Reducer::Merge, None, json!([1, 2]))
+            .unwrap_err()
+            .to_string();
+
+        assert!(err.contains("'merge'"), "got: {err}");
+        assert!(err.contains("array"), "got: {err}");
+    }
+
+    #[test]
+    fn merge_errors_when_current_is_not_object() {
+        let current = json!("not object");
+
+        let err = apply(Reducer::Merge, Some(&current), json!({ "k": "v" }))
+            .unwrap_err()
+            .to_string();
+
+        assert!(err.contains("'merge'"), "got: {err}");
+        assert!(err.contains("current"), "got: {err}");
+    }
+
+    #[test]
+    fn overwrite_ignores_current_and_returns_incoming() {
+        let current = json!("old");
+
+        let result = apply(Reducer::Overwrite, Some(&current), json!("new")).unwrap();
+
+        assert_eq!(result, json!("new"));
+    }
+
+    #[test]
+    fn overwrite_works_with_absent_current() {
+        let result = apply(Reducer::Overwrite, None, json!(42)).unwrap();
+
+        assert_eq!(result, json!(42));
+    }
+}
diff --git a/src/graph/script.rs b/src/graph/script.rs
new file mode 100644
index 0000000..c7541d1
--- /dev/null
+++ b/src/graph/script.rs
@@ -0,0 +1,557 @@
+use super::state::{StateManager, StateRepresentation};
+use super::types::ScriptNode;
+use crate::config::paths;
+use crate::function::Language;
+use anyhow::{Context, Result, anyhow, bail};
+use serde_json::Value;
+use std::collections::HashMap;
+use std::env;
+use std::path::{Path, PathBuf};
+use std::process::Stdio;
+use std::time::Duration;
+use tokio::process::Command;
+use tokio::time::timeout;
+
+#[cfg(windows)]
+const PATH_SEP: &str = ";";
+#[cfg(not(windows))]
+const PATH_SEP: &str = ":";
+
+#[derive(Clone)]
+pub struct ScriptExecutor {
+    base_dir: PathBuf,
+    extra_envs: HashMap<String, String>,
+}
+
+impl ScriptExecutor {
+    pub fn new(base_dir: impl Into<PathBuf>) -> Self {
+        let base_dir = base_dir.into();
+        let extra_envs = build_default_envs(&base_dir);
+        Self {
+            base_dir,
+            extra_envs,
+        }
+    }
+
+    pub fn with_envs(mut self, envs: HashMap<String, String>) -> Self {
+        self.extra_envs.extend(envs);
+        self
+    }
+
+    pub async fn execute(
+        &self,
+        node: &ScriptNode,
+        state_manager: &mut StateManager,
+    ) -> Result<Option<String>> {
+        let script_path = self.base_dir.join(&node.script);
+        if !script_path.exists() {
+            bail!("Script file not found: '{}'", script_path.display());
+        }
+
+        let language = detect_language(&script_path)?;
+        let state_repr = state_manager.serialize_state()?;
+
+        let mut cmd = build_command(language, &script_path)?;
+        cmd.stdout(Stdio::piped());
+        cmd.stderr(Stdio::piped());
+        cmd.envs(&self.extra_envs);
+        match &state_repr {
+            StateRepresentation::Inline(json) => {
+                cmd.env("GRAPH_STATE", json);
+            }
+            StateRepresentation::File(path) => {
+                cmd.env("GRAPH_STATE_FILE", path);
+            }
+        }
+
+        let timeout_dur = Duration::from_secs(node.timeout);
+        let output = timeout(timeout_dur, cmd.output())
+            .await
+            .with_context(|| {
+                format!(
+                    "Script '{}' timed out after {}s",
+                    script_path.display(),
+                    node.timeout
+                )
+            })?
+            .with_context(|| {
+                format!(
+                    "Failed to spawn script process for '{}'",
+                    script_path.display()
+                )
+            })?;
+
+        if !output.status.success() {
+            let stderr = String::from_utf8_lossy(&output.stderr);
+            bail!(
+                "Script '{}' failed with exit code {:?}:\n{}",
+                script_path.display(),
+                output.status.code(),
+                stderr.trim()
+            );
+        }
+
+        let stdout = String::from_utf8_lossy(&output.stdout);
+        let json_output = stdout.trim();
+        if json_output.is_empty() {
+            bail!(
+                "Script '{}' produced no output (scripts must emit a single JSON object on stdout)",
+                script_path.display()
+            );
+        }
+
+        let next = state_manager
+            .merge_script_output(json_output)
+            .with_context(|| {
+                format!(
+                    "Failed to merge output from script '{}'",
+                    script_path.display()
+                )
+            })?;
+
+        apply_state_updates(node, state_manager);
+
+        Ok(next)
+    }
+}
+
+fn apply_state_updates(node: &ScriptNode, state_manager: &mut StateManager) {
+    let Some(updates) = &node.state_updates else {
+        return;
+    };
+
+    for (key, template) in updates {
+        let value = state_manager.interpolate_lenient(template);
+        state_manager
+            .state_mut()
+            .set(key.clone(), Value::String(value));
+    }
+}
+
+fn build_default_envs(agent_data_dir: &Path) -> HashMap<String, String> {
+    let mut envs = HashMap::new();
+    envs.insert(
+        "LLM_ROOT_DIR".to_string(),
+        paths::config_dir().to_string_lossy().into_owned(),
+    );
+    envs.insert(
+        "LLM_PROMPT_UTILS_FILE".to_string(),
+        paths::bash_prompt_utils_file()
+            .to_string_lossy()
+            .into_owned(),
+    );
+    envs.insert(
+        "LLM_AGENT_DATA_DIR".to_string(),
+        agent_data_dir.to_string_lossy().into_owned(),
+    );
+    envs.insert("CLICOLOR_FORCE".to_string(), "1".to_string());
+    envs.insert("FORCE_COLOR".to_string(), "1".to_string());
+
+    if let Ok(current_path) = env::var("PATH") {
+        let bin_dir = paths::functions_bin_dir();
+        envs.insert(
+            "PATH".to_string(),
+            format!("{}{}{}", bin_dir.display(), PATH_SEP, current_path),
+        );
+    }
+
+    envs
+}
+
+fn detect_language(script_path: &Path) -> Result<Language> {
+    let ext = script_path
+        .extension()
+        .and_then(|e| e.to_str())
+        .ok_or_else(|| anyhow!("Script has no file extension: '{}'", script_path.display()))?
+        .to_string();
+
+    match Language::from(&ext) {
+        Language::Unsupported => bail!(
+            "Unsupported script extension '.{}' for '{}'",
+            ext,
+            script_path.display()
+        ),
+        lang => Ok(lang),
+    }
+}
+
+fn build_command(language: Language, script_path: &Path) -> Result<Command> {
+    let (program, prefix_args) = language.direct_invoker().ok_or_else(|| {
+        anyhow!(
+            "No direct invoker available for script '{}'",
+            script_path.display()
+        )
+    })?;
+    let mut cmd = Command::new(program);
+
+    for arg in prefix_args {
+        cmd.arg(arg);
+    }
+
+    cmd.arg(script_path);
+    Ok(cmd)
+}
+
+#[cfg(test)]
+mod tests {
+    use super::super::MAX_STATE_SIZE_BYTES;
+    use super::*;
+    use crate::utils::temp_file;
+    use indoc::formatdoc;
+    use serde_json::json;
+    use std::collections::HashMap;
+    use std::env::temp_dir;
+    use std::fs;
+
+    fn cmd_available(name: &str) -> bool {
+        which::which(name).is_ok()
+    }
+
+    fn write_script(contents: &str, ext: &str) -> (PathBuf, PathBuf) {
+        let dir = temp_file("-graph-script-test-", "");
+        fs::create_dir_all(&dir).unwrap();
+        let path = dir.join(format!("script.{ext}"));
+        fs::write(&path, contents).unwrap();
+        (dir, path)
+    }
+
+    fn cleanup(dir: &Path) {
+        let _ = fs::remove_dir_all(dir);
+    }
+
+    fn node_for(script_filename: &str, timeout: u64) -> ScriptNode {
+        ScriptNode {
+            script: script_filename.into(),
+            state_updates: None,
+            fallback: None,
+            timeout,
+        }
+    }
+
+    #[tokio::test]
+    async fn bash_script_merges_json_output_into_state() {
+        if !cmd_available("bash") {
+            eprintln!("skipping: bash not available");
+            return;
+        }
+        let (dir, path) = write_script(
+            r#"#!/bin/bash
+echo '{"quality": 0.85, "issues": 3, "_next": "approve"}'
+"#,
+            "sh",
+        );
+        let mut state = StateManager::new(HashMap::new());
+        let executor = ScriptExecutor::new(&dir);
+
+        let next = executor
+            .execute(
+                &node_for(path.file_name().unwrap().to_str().unwrap(), 5),
+                &mut state,
+            )
+            .await
+            .unwrap();
+
+        assert_eq!(next.as_deref(), Some("approve"));
+        assert_eq!(state.state().get("quality"), Some(&json!(0.85)));
+        assert_eq!(state.state().get("issues"), Some(&json!(3)));
+        assert!(state.state().get("_next").is_none());
+        cleanup(&dir);
+    }
+
+    #[tokio::test]
+    async fn bash_script_can_read_state_from_env() {
+        if !cmd_available("bash") || !cmd_available("python3") {
+            eprintln!("skipping: bash or python3 not available");
+            return;
+        }
+        let (dir, path) = write_script(
+            r#"#!/bin/bash
+NAME=$(python3 -c 'import json,os; print(json.loads(os.environ["GRAPH_STATE"])["name"])')
+printf '{"greeting": "hello %s"}' "$NAME"
+"#,
+            "sh",
+        );
+        let mut initial = HashMap::new();
+        initial.insert("name".into(), json!("alice"));
+        let mut state = StateManager::new(initial);
+        let executor = ScriptExecutor::new(&dir);
+
+        let _ = executor
+            .execute(
+                &node_for(path.file_name().unwrap().to_str().unwrap(), 5),
+                &mut state,
+            )
+            .await
+            .unwrap();
+
+        assert_eq!(state.state().get("greeting"), Some(&json!("hello alice")));
+        cleanup(&dir);
+    }
+
+    #[tokio::test]
+    async fn script_without_next_returns_none() {
+        if !cmd_available("bash") {
+            return;
+        }
+        let (dir, path) = write_script(
+            r#"#!/bin/bash
+echo '{"ok": true}'
+"#,
+            "sh",
+        );
+        let mut state = StateManager::new(HashMap::new());
+        let executor = ScriptExecutor::new(&dir);
+
+        let next = executor
+            .execute(
+                &node_for(path.file_name().unwrap().to_str().unwrap(), 5),
+                &mut state,
+            )
+            .await
+            .unwrap();
+
+        assert!(next.is_none());
+        assert_eq!(state.state().get("ok"), Some(&json!(true)));
+        cleanup(&dir);
+    }
+
+    #[tokio::test]
+    async fn state_updates_apply_after_json_merge() {
+        if !cmd_available("bash") {
+            return;
+        }
+        let (dir, path) = write_script(
+            r#"#!/bin/bash
+echo '{"raw": "hello"}'
+"#,
+            "sh",
+        );
+        let mut node = node_for(path.file_name().unwrap().to_str().unwrap(), 5);
+        let mut updates = HashMap::new();
+        updates.insert("decorated".into(), "[{{raw}}]".into());
+        node.state_updates = Some(updates);
+
+        let mut state = StateManager::new(HashMap::new());
+        let executor = ScriptExecutor::new(&dir);
+        executor.execute(&node, &mut state).await.unwrap();
+
+        assert_eq!(state.state().get("raw"), Some(&json!("hello")));
+        assert_eq!(state.state().get("decorated"), Some(&json!("[hello]")));
+        cleanup(&dir);
+    }
+
+    #[tokio::test]
+    async fn missing_script_file_errors_before_spawning() {
+        let mut state = StateManager::new(HashMap::new());
+        let executor = ScriptExecutor::new(temp_dir());
+
+        let err = executor
+            .execute(&node_for("__does_not_exist__.sh", 5), &mut state)
+            .await
+            .unwrap_err()
+            .to_string();
+
+        assert!(err.contains("Script file not found"), "got: {err}");
+    }
+
+    #[tokio::test]
+    async fn empty_stdout_errors() {
+        if !cmd_available("bash") {
+            return;
+        }
+        let (dir, path) = write_script("#!/bin/bash\n", "sh");
+        let mut state = StateManager::new(HashMap::new());
+        let executor = ScriptExecutor::new(&dir);
+
+        let err = executor
+            .execute(
+                &node_for(path.file_name().unwrap().to_str().unwrap(), 5),
+                &mut state,
+            )
+            .await
+            .unwrap_err()
+            .to_string();
+
+        assert!(err.contains("produced no output"), "got: {err}");
+        cleanup(&dir);
+    }
+
+    #[tokio::test]
+    async fn non_json_output_errors() {
+        if !cmd_available("bash") {
+            return;
+        }
+        let (dir, path) = write_script(
+            &formatdoc! {r#"
+                #!/bin/bash
+                echo "not json at all"
+            "#},
+            "sh",
+        );
+        let mut state = StateManager::new(HashMap::new());
+        let executor = ScriptExecutor::new(&dir);
+
+        let err = executor
+            .execute(
+                &node_for(path.file_name().unwrap().to_str().unwrap(), 5),
+                &mut state,
+            )
+            .await
+            .unwrap_err()
+            .to_string();
+
+        assert!(err.contains("merge output"), "got: {err}");
+        cleanup(&dir);
+    }
+
+    #[tokio::test]
+    async fn non_zero_exit_errors_and_includes_stderr() {
+        if !cmd_available("bash") {
+            return;
+        }
+        let (dir, path) = write_script(
+            &formatdoc! {r#"
+                #!/bin/bash
+                echo "bad happened" >&2
+                exit 7
+            "#},
+            "sh",
+        );
+        let mut state = StateManager::new(HashMap::new());
+        let executor = ScriptExecutor::new(&dir);
+
+        let err = executor
+            .execute(
+                &node_for(path.file_name().unwrap().to_str().unwrap(), 5),
+                &mut state,
+            )
+            .await
+            .unwrap_err()
+            .to_string();
+
+        assert!(err.contains("exit code"), "got: {err}");
+        assert!(err.contains("bad happened"), "got: {err}");
+        cleanup(&dir);
+    }
+
+    #[tokio::test]
+    async fn execution_timeout_is_enforced() {
+        if !cmd_available("bash") {
+            return;
+        }
+        let (dir, path) = write_script(
+            r#"#!/bin/bash
+sleep 5
+echo '{"ok":true}'
+"#,
+            "sh",
+        );
+        let mut state = StateManager::new(HashMap::new());
+        let executor = ScriptExecutor::new(&dir);
+
+        let err = executor
+            .execute(
+                &node_for(path.file_name().unwrap().to_str().unwrap(), 1),
+                &mut state,
+            )
+            .await
+            .unwrap_err()
+            .to_string();
+
+        assert!(err.contains("timed out"), "got: {err}");
+        cleanup(&dir);
+    }
+
+    #[tokio::test]
+    async fn large_state_is_delivered_via_file_env_var() {
+        if !cmd_available("bash") || !cmd_available("python3") {
+            return;
+        }
+        let big = "x".repeat(MAX_STATE_SIZE_BYTES + 1024);
+        let mut initial = HashMap::new();
+        initial.insert("blob".into(), json!(big));
+
+        let (dir, path) = write_script(
+            r#"#!/bin/bash
+if [ -n "$GRAPH_STATE_FILE" ]; then
+    LEN=$(python3 -c 'import json,os; print(len(json.load(open(os.environ["GRAPH_STATE_FILE"]))["blob"]))')
+    printf '{"blob_len": %s, "via_file": true}' "$LEN"
+elif [ -n "$GRAPH_STATE" ]; then
+    echo '{"via_file": false}'
+fi
+"#,
+            "sh",
+        );
+
+        let mut state = StateManager::new(initial);
+        let executor = ScriptExecutor::new(&dir);
+        executor
+            .execute(
+                &node_for(path.file_name().unwrap().to_str().unwrap(), 10),
+                &mut state,
+            )
+            .await
+            .unwrap();
+
+        assert_eq!(state.state().get("via_file"), Some(&json!(true)));
+        let len = state.state().get("blob_len").unwrap().as_i64().unwrap();
+        assert_eq!(len as usize, big.len());
+        cleanup(&dir);
+    }
+
+    #[tokio::test]
+    async fn python_script_can_emit_routing_and_state() {
+        if !cmd_available("python3") {
+            eprintln!("skipping: python3 not available");
+            return;
+        }
+        let (dir, path) = write_script(
+            r#"import os, json
+state = json.loads(os.environ["GRAPH_STATE"])
+print(json.dumps({
+    "_next": "next_node",
+    "doubled": state.get("n", 0) * 2,
+}))
+"#,
+            "py",
+        );
+        let mut initial = HashMap::new();
+        initial.insert("n".into(), json!(21));
+        let mut state = StateManager::new(initial);
+
+        let executor = ScriptExecutor::new(&dir);
+        let next = executor
+            .execute(
+                &node_for(path.file_name().unwrap().to_str().unwrap(), 5),
+                &mut state,
+            )
+            .await
+            .unwrap();
+
+        assert_eq!(next.as_deref(), Some("next_node"));
+        assert_eq!(state.state().get("doubled"), Some(&json!(42)));
+        cleanup(&dir);
+    }
+
+    #[tokio::test]
+    async fn unknown_extension_is_rejected() {
+        let (dir, path) = write_script("echo hi", "xyz");
+        let mut state = StateManager::new(HashMap::new());
+        let executor = ScriptExecutor::new(&dir);
+
+        let err = executor
+            .execute(
+                &node_for(path.file_name().unwrap().to_str().unwrap(), 5),
+                &mut state,
+            )
+            .await
+            .unwrap_err()
+            .to_string();
+
+        assert!(
+            err.contains("Unsupported script extension '.xyz'"),
+            "got: {err}"
+        );
+        cleanup(&dir);
+    }
+}
diff --git a/src/graph/staging.rs b/src/graph/staging.rs
new file mode 100644
index 0000000..31522e4
--- /dev/null
+++ b/src/graph/staging.rs
@@ -0,0 +1,9 @@
+use serde_json::Value;
+use std::collections::HashMap;
+
+#[derive(Debug, Clone)]
+pub struct BranchWrites {
+    pub node_id: String,
+    pub invocation_index: usize,
+    pub writes: HashMap<String, Value>,
+}
diff --git a/src/graph/state.rs b/src/graph/state.rs
new file mode 100644
index 0000000..e16f16f
--- /dev/null
+++ b/src/graph/state.rs
@@ -0,0 +1,1021 @@
+use super::MAX_STATE_SIZE_BYTES;
+use super::reducer;
+use super::staging::BranchWrites;
+use super::types::{GraphState, Reducer};
+use crate::utils::temp_file;
+use anyhow::{Context, Result, bail};
+use fancy_regex::Regex;
+use serde_json::Value;
+use std::collections::{BTreeMap, HashMap};
+use std::fs;
+use std::fs::write;
+use std::path::PathBuf;
+use std::sync::{Arc, LazyLock};
+
+static TEMPLATE_VAR_RE: LazyLock<Regex> =
+    LazyLock::new(|| Regex::new(r"\{\{([a-zA-Z0-9_\.\[\]]+)\}\}").expect("invalid template regex"));
+
+pub struct StateManager {
+    state: GraphState,
+    temp_file: Option<PathBuf>,
+}
+
+impl StateManager {
+    pub fn new(initial: HashMap<String, Value>) -> Self {
+        Self {
+            state: GraphState::new(initial),
+            temp_file: None,
+        }
+    }
+
+    pub fn state(&self) -> &GraphState {
+        &self.state
+    }
+
+    pub fn state_mut(&mut self) -> &mut GraphState {
+        &mut self.state
+    }
+
+    pub fn interpolate(&self, template: &str) -> Result<String> {
+        let mut missing = Vec::new();
+        let result = self.interpolate_inner(template, |key| {
+            missing.push(key.to_string());
+            String::new()
+        });
+        if !missing.is_empty() {
+            bail!(
+                "Template interpolation failed: {} not found in state",
+                missing
+                    .iter()
+                    .map(|k| format!("'{k}'"))
+                    .collect::<Vec<_>>()
+                    .join(", ")
+            );
+        }
+        Ok(result)
+    }
+
+    pub fn interpolate_lenient(&self, template: &str) -> String {
+        self.interpolate_inner(template, |_| String::new())
+    }
+
+    fn interpolate_inner<F>(&self, template: &str, mut on_missing: F) -> String
+    where
+        F: FnMut(&str) -> String,
+    {
+        let mut result = template.to_string();
+        for captures in TEMPLATE_VAR_RE.captures_iter(template).flatten() {
+            let full = captures.get(0).unwrap().as_str().to_string();
+            let key = captures.get(1).unwrap().as_str();
+            let replacement = match self.get_nested_value(key) {
+                Some(value) => value_to_string(value),
+                None => on_missing(key),
+            };
+            result = result.replace(&full, &replacement);
+        }
+        result
+    }
+
+    fn get_nested_value(&self, key: &str) -> Option<&Value> {
+        let mut parts = key.split('.');
+        let first = parts.next()?;
+        let (root_key, root_indices) = split_indices(first)?;
+        let mut current = self.state.get(root_key)?;
+        for idx in root_indices {
+            current = current.get(idx)?;
+        }
+
+        for part in parts {
+            let (segment_key, indices) = split_indices(part)?;
+            if !segment_key.is_empty() {
+                current = current.get(segment_key)?;
+            }
+            for idx in indices {
+                current = current.get(idx)?;
+            }
+        }
+
+        Some(current)
+    }
+
+    pub fn serialize_state(&mut self) -> Result<StateRepresentation> {
+        let json = self.state.to_json()?;
+        if json.len() > MAX_STATE_SIZE_BYTES {
+            let path = temp_file("-graph-state-", ".json");
+            write(&path, json.as_bytes()).with_context(|| {
+                format!("Failed to write state to temp file at '{}'", path.display())
+            })?;
+            self.temp_file = Some(path.clone());
+
+            Ok(StateRepresentation::File(path))
+        } else {
+            Ok(StateRepresentation::Inline(json))
+        }
+    }
+
+    #[cfg(test)]
+    pub fn from_json_string(json: &str) -> Result<Self> {
+        let data: HashMap<String, Value> =
+            serde_json::from_str(json).context("Failed to parse state JSON")?;
+        Ok(Self::new(data))
+    }
+
+    pub fn snapshot(&self) -> HashMap<String, Value> {
+        self.state.data().clone()
+    }
+
+    pub fn size_bytes(&self) -> usize {
+        self.state.size_bytes()
+    }
+
+    #[cfg(test)]
+    pub fn is_large(&self) -> bool {
+        self.size_bytes() > MAX_STATE_SIZE_BYTES
+    }
+
+    pub fn merge_script_output(&mut self, json_output: &str) -> Result<Option<String>> {
+        let value: Value =
+            serde_json::from_str(json_output).context("Script output must be valid JSON")?;
+        let obj = value
+            .as_object()
+            .context("Script output must be a JSON object, not array or primitive")?;
+
+        let next_node = obj.get("_next").and_then(|v| v.as_str()).map(String::from);
+
+        let mut merged = serde_json::Map::new();
+        for (k, v) in obj {
+            if k != "_next" {
+                merged.insert(k.clone(), v.clone());
+            }
+        }
+        self.state.merge(&merged);
+
+        Ok(next_node)
+    }
+
+    pub fn cleanup(&mut self) {
+        if let Some(path) = self.temp_file.take() {
+            let _ = fs::remove_file(path);
+        }
+    }
+
+    pub fn fork_for_branch_state(&self) -> Self {
+        Self {
+            state: self.state.clone(),
+            temp_file: None,
+        }
+    }
+
+    pub fn diff_against(&self, snapshot: &GraphState) -> HashMap<String, Value> {
+        let mut diff = HashMap::new();
+        for (k, v) in self.state.data() {
+            if snapshot.get(k) != Some(v) {
+                diff.insert(k.clone(), v.clone());
+            }
+        }
+        diff
+    }
+
+    pub fn read_snapshot(&self) -> Arc<GraphState> {
+        Arc::new(self.state.clone())
+    }
+
+    pub fn apply_branch_writes(
+        &mut self,
+        writes: Vec<BranchWrites>,
+        reducers: &HashMap<String, Reducer>,
+    ) -> Result<()> {
+        let mut by_key: BTreeMap<String, Vec<Value>> = BTreeMap::new();
+        for branch in writes {
+            for (key, value) in branch.writes {
+                by_key.entry(key).or_default().push(value);
+            }
+        }
+
+        for (key, values) in by_key {
+            match reducers.get(&key).copied() {
+                Some(r) => {
+                    let mut current = self.state.get(&key).cloned();
+                    for value in values {
+                        current = Some(reducer::apply(r, current.as_ref(), value)?);
+                    }
+                    if let Some(final_value) = current {
+                        self.state.set(key, final_value);
+                    }
+                }
+                None if values.len() == 1 => {
+                    self.state.set(key, values.into_iter().next().unwrap());
+                }
+                None => {
+                    bail!(
+                        "Key '{key}' was written by {} parallel branches but has no \
+                         reducer declared. Add a reducer for '{key}' to the graph's \
+                         `reducers:` block, or rename one writer.",
+                        values.len()
+                    );
+                }
+            }
+        }
+
+        Ok(())
+    }
+
+    pub fn interpolate_raw(&self, template: &str) -> Result<Value> {
+        let trimmed = template.trim();
+        if let Some(key) = single_reference_key(trimmed) {
+            match self.get_nested_value(key) {
+                Some(value) => Ok(value.clone()),
+                None => bail!("Template interpolation failed: '{key}' not found in state"),
+            }
+        } else {
+            Ok(Value::String(self.interpolate(template)?))
+        }
+    }
+}
+
+impl Drop for StateManager {
+    fn drop(&mut self) {
+        self.cleanup();
+    }
+}
+
+#[derive(Debug, Clone)]
+pub enum StateRepresentation {
+    Inline(String),
+    File(PathBuf),
+}
+
+#[cfg(test)]
+impl StateRepresentation {
+    pub fn as_string(&self) -> Result<String> {
+        match self {
+            StateRepresentation::Inline(s) => Ok(s.clone()),
+            StateRepresentation::File(path) => fs::read_to_string(path)
+                .with_context(|| format!("Failed to read state file at '{}'", path.display())),
+        }
+    }
+
+    pub fn as_file_path(&self) -> Option<&PathBuf> {
+        match self {
+            StateRepresentation::File(path) => Some(path),
+            StateRepresentation::Inline(_) => None,
+        }
+    }
+
+    pub fn is_file(&self) -> bool {
+        matches!(self, StateRepresentation::File(_))
+    }
+}
+
+fn split_indices(segment: &str) -> Option<(&str, Vec<usize>)> {
+    let bracket_start = segment.find('[');
+    let key = match bracket_start {
+        Some(i) => &segment[..i],
+        None => return Some((segment, Vec::new())),
+    };
+    let mut indices = Vec::new();
+    let mut rest = &segment[bracket_start.unwrap()..];
+
+    while !rest.is_empty() {
+        if !rest.starts_with('[') {
+            return None;
+        }
+        let close = rest.find(']')?;
+        let idx: usize = rest[1..close].parse().ok()?;
+        indices.push(idx);
+        rest = &rest[close + 1..];
+    }
+
+    Some((key, indices))
+}
+
+// Returns the inner key when `template` is exactly a single `{{key}}` reference
+// (no surrounding text, no other braces).
+fn single_reference_key(template: &str) -> Option<&str> {
+    let inner = template.strip_prefix("{{")?.strip_suffix("}}")?;
+    if inner.contains("{{") || inner.contains("}}") {
+        return None;
+    }
+    let valid = !inner.is_empty()
+        && inner
+            .chars()
+            .all(|c| c.is_ascii_alphanumeric() || c == '_' || c == '.' || c == '[' || c == ']');
+    valid.then_some(inner)
+}
+
+// Returns the root state keys referenced by any `{{...}}` expressions in the given template string. The "root key" is
+// the identifier before the first `.` or `[`; e.g., for `{{user.name}}` the root is `user`, for `{{items[0]}}` the
+// root is `items`. Used by the validator to compute the static read-set of a node's templated fields without
+// depending on a runtime `StateManager`.
+pub(super) fn template_root_keys(template: &str) -> Vec<String> {
+    TEMPLATE_VAR_RE
+        .captures_iter(template)
+        .flatten()
+        .filter_map(|c| c.get(1))
+        .map(|m| {
+            let inner = m.as_str();
+            let cut = inner.find(['.', '[']).unwrap_or(inner.len());
+            inner[..cut].to_string()
+        })
+        .collect()
+}
+
+fn value_to_string(value: &Value) -> String {
+    match value {
+        Value::String(s) => s.clone(),
+        Value::Number(n) => n.to_string(),
+        Value::Bool(b) => b.to_string(),
+        Value::Null => "null".to_string(),
+        Value::Array(_) => serde_json::to_string(value).unwrap_or_else(|_| String::from("[]")),
+        Value::Object(_) => serde_json::to_string(value).unwrap_or_else(|_| String::from("{}")),
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use serde_json::json;
+
+    fn manager_with(pairs: &[(&str, Value)]) -> StateManager {
+        let mut state = HashMap::new();
+        for (k, v) in pairs {
+            state.insert((*k).to_string(), v.clone());
+        }
+        StateManager::new(state)
+    }
+
+    #[test]
+    fn simple_interpolation_replaces_top_level_keys() {
+        let manager = manager_with(&[("name", json!("Alice")), ("age", json!(30))]);
+
+        let result = manager
+            .interpolate("Hello {{name}}, you are {{age}} years old")
+            .unwrap();
+
+        assert_eq!(result, "Hello Alice, you are 30 years old");
+    }
+
+    #[test]
+    fn nested_interpolation_walks_objects() {
+        let manager =
+            manager_with(&[("user", json!({ "name": "Bob", "email": "bob@example.com" }))]);
+
+        let result = manager
+            .interpolate("User: {{user.name}} ({{user.email}})")
+            .unwrap();
+
+        assert_eq!(result, "User: Bob (bob@example.com)");
+    }
+
+    #[test]
+    fn deep_nested_interpolation_handles_multiple_levels() {
+        let manager = manager_with(&[(
+            "config",
+            json!({
+                "api": { "key": "secret123", "endpoint": "https://api.example.com" }
+            }),
+        )]);
+
+        let result = manager
+            .interpolate("API: {{config.api.endpoint}} with key {{config.api.key}}")
+            .unwrap();
+
+        assert_eq!(result, "API: https://api.example.com with key secret123");
+    }
+
+    #[test]
+    fn strict_interpolation_errors_on_missing_keys() {
+        let manager = manager_with(&[]);
+
+        let err = manager
+            .interpolate("Hello {{name}}")
+            .unwrap_err()
+            .to_string();
+
+        assert!(err.contains("not found"), "got: {err}");
+        assert!(err.contains("name"), "got: {err}");
+    }
+
+    #[test]
+    fn strict_interpolation_collects_all_missing_keys() {
+        let manager = manager_with(&[]);
+
+        let err = manager
+            .interpolate("{{a}} and {{b}}")
+            .unwrap_err()
+            .to_string();
+
+        assert!(err.contains("'a'") && err.contains("'b'"), "got: {err}");
+    }
+
+    #[test]
+    fn lenient_interpolation_substitutes_empty_for_missing() {
+        let manager = manager_with(&[("name", json!("Alice"))]);
+
+        let result = manager.interpolate_lenient("Hello {{name}}, age: {{age}}");
+
+        assert_eq!(result, "Hello Alice, age: ");
+    }
+
+    #[test]
+    fn lenient_interpolation_handles_missing_intermediate() {
+        let manager = manager_with(&[("user", json!({ "name": "Bob" }))]);
+
+        let result = manager.interpolate_lenient("email: {{user.email}}");
+
+        assert_eq!(result, "email: ");
+    }
+
+    #[test]
+    fn interpolates_booleans_numbers_and_null() {
+        let manager = manager_with(&[
+            ("on", json!(true)),
+            ("count", json!(42)),
+            ("nothing", json!(null)),
+        ]);
+
+        assert_eq!(manager.interpolate("{{on}}").unwrap(), "true");
+        assert_eq!(manager.interpolate("{{count}}").unwrap(), "42");
+        assert_eq!(manager.interpolate("{{nothing}}").unwrap(), "null");
+    }
+
+    #[test]
+    fn interpolates_arrays_as_json() {
+        let manager = manager_with(&[("items", json!(["a", "b", "c"]))]);
+
+        let result = manager.interpolate("{{items}}").unwrap();
+
+        assert_eq!(result, r#"["a","b","c"]"#);
+    }
+
+    #[test]
+    fn interpolates_objects_as_json() {
+        let manager = manager_with(&[("data", json!({ "key": "value" }))]);
+
+        let result = manager.interpolate("{{data}}").unwrap();
+
+        assert_eq!(result, r#"{"key":"value"}"#);
+    }
+
+    #[test]
+    fn interpolates_array_indices() {
+        let manager = manager_with(&[("items", json!(["a", "b", "c"]))]);
+
+        assert_eq!(manager.interpolate("{{items[0]}}").unwrap(), "a");
+        assert_eq!(manager.interpolate("{{items[2]}}").unwrap(), "c");
+    }
+
+    #[test]
+    fn interpolates_array_indices_inside_nested_paths() {
+        let manager = manager_with(&[("outer", json!({ "inner": { "arr": ["x", "y", "z"] } }))]);
+
+        let result = manager
+            .interpolate("first={{outer.inner.arr[0]}} last={{outer.inner.arr[2]}}")
+            .unwrap();
+
+        assert_eq!(result, "first=x last=z");
+    }
+
+    #[test]
+    fn interpolates_object_fields_after_array_index() {
+        let manager = manager_with(&[("users", json!([{ "name": "Alice" }, { "name": "Bob" }]))]);
+
+        let result = manager
+            .interpolate("{{users[0].name}} and {{users[1].name}}")
+            .unwrap();
+
+        assert_eq!(result, "Alice and Bob");
+    }
+
+    #[test]
+    fn interpolates_nested_array_indices() {
+        let manager = manager_with(&[("matrix", json!([[1, 2], [3, 4]]))]);
+
+        assert_eq!(manager.interpolate("{{matrix[0][1]}}").unwrap(), "2");
+        assert_eq!(manager.interpolate("{{matrix[1][0]}}").unwrap(), "3");
+    }
+
+    #[test]
+    fn out_of_bounds_array_index_is_missing() {
+        let manager = manager_with(&[("items", json!(["a", "b"]))]);
+
+        let err = manager.interpolate("{{items[5]}}").unwrap_err().to_string();
+
+        assert!(err.contains("not found"), "got: {err}");
+    }
+
+    #[test]
+    fn replaces_all_occurrences_of_same_key() {
+        let manager = manager_with(&[("n", json!("Alice"))]);
+
+        let result = manager.interpolate("{{n}} and {{n}} again").unwrap();
+
+        assert_eq!(result, "Alice and Alice again");
+    }
+
+    #[test]
+    fn passes_through_templates_with_no_variables() {
+        let manager = manager_with(&[]);
+
+        let result = manager.interpolate("No variables here").unwrap();
+
+        assert_eq!(result, "No variables here");
+    }
+
+    #[test]
+    fn from_json_string_round_trips() {
+        let json = r#"{"name": "Alice", "age": 30}"#;
+        let manager = StateManager::from_json_string(json).unwrap();
+
+        let result = manager.interpolate("{{name}} is {{age}}").unwrap();
+
+        assert_eq!(result, "Alice is 30");
+    }
+
+    #[test]
+    fn snapshot_clones_state_data() {
+        let manager = manager_with(&[("k1", json!("v1")), ("k2", json!(42))]);
+
+        let snap = manager.snapshot();
+
+        assert_eq!(snap.len(), 2);
+        assert_eq!(snap.get("k1"), Some(&json!("v1")));
+        assert_eq!(snap.get("k2"), Some(&json!(42)));
+    }
+
+    #[test]
+    fn small_state_serializes_inline() {
+        let mut manager = manager_with(&[("key", json!("value"))]);
+
+        let repr = manager.serialize_state().unwrap();
+
+        assert!(matches!(repr, StateRepresentation::Inline(_)));
+        assert!(!manager.is_large());
+        assert!(!repr.is_file());
+    }
+
+    #[test]
+    fn large_state_spills_to_temp_file() {
+        let big = "x".repeat(MAX_STATE_SIZE_BYTES + 1024);
+        let mut manager = manager_with(&[("blob", json!(big))]);
+        assert!(manager.is_large());
+
+        let repr = manager.serialize_state().unwrap();
+        assert!(repr.is_file(), "expected file representation");
+        let path = repr.as_file_path().unwrap().clone();
+        assert!(path.exists());
+
+        let contents = repr.as_string().unwrap();
+        let parsed: Value = serde_json::from_str(&contents).unwrap();
+        assert_eq!(
+            parsed.get("blob").unwrap().as_str().unwrap().len(),
+            big.len()
+        );
+
+        drop(manager);
+        assert!(!path.exists(), "temp file should be cleaned up on drop");
+    }
+
+    #[test]
+    fn merge_script_output_merges_keys_into_state() {
+        let mut manager = manager_with(&[]);
+        let output = r#"{"quality_score": 0.85, "issues_found": 3, "status": "complete"}"#;
+
+        let next = manager.merge_script_output(output).unwrap();
+
+        assert_eq!(next, None);
+        assert_eq!(manager.state().get("quality_score"), Some(&json!(0.85)));
+        assert_eq!(manager.state().get("issues_found"), Some(&json!(3)));
+        assert_eq!(manager.state().get("status"), Some(&json!("complete")));
+    }
+
+    #[test]
+    fn merge_script_output_extracts_next_key_for_routing() {
+        let mut manager = manager_with(&[]);
+        let output = r#"{"_next": "approval_gate", "quality_score": 0.85}"#;
+
+        let next = manager.merge_script_output(output).unwrap();
+
+        assert_eq!(next.as_deref(), Some("approval_gate"));
+        assert_eq!(manager.state().get("quality_score"), Some(&json!(0.85)));
+        assert!(
+            manager.state().get("_next").is_none(),
+            "_next must not leak into state"
+        );
+    }
+
+    #[test]
+    fn merge_script_output_rejects_invalid_json() {
+        let mut manager = manager_with(&[]);
+
+        let err = manager
+            .merge_script_output("not json")
+            .unwrap_err()
+            .to_string();
+
+        assert!(err.contains("valid JSON"), "got: {err}");
+    }
+
+    #[test]
+    fn merge_script_output_rejects_non_object() {
+        let mut manager = manager_with(&[]);
+
+        let err = manager
+            .merge_script_output("[1, 2, 3]")
+            .unwrap_err()
+            .to_string();
+
+        assert!(err.contains("must be a JSON object"), "got: {err}");
+    }
+
+    #[test]
+    fn merge_script_output_overwrites_existing_state_keys() {
+        let mut manager = manager_with(&[("status", json!("pending"))]);
+
+        let _ = manager
+            .merge_script_output(r#"{"status": "complete"}"#)
+            .unwrap();
+
+        assert_eq!(manager.state().get("status"), Some(&json!("complete")));
+    }
+
+    fn branch(node_id: &str, idx: usize, writes: &[(&str, Value)]) -> BranchWrites {
+        let mut map = HashMap::new();
+        for (k, v) in writes {
+            map.insert((*k).into(), v.clone());
+        }
+        BranchWrites {
+            node_id: node_id.into(),
+            invocation_index: idx,
+            writes: map,
+        }
+    }
+
+    #[test]
+    fn read_snapshot_returns_arc_with_current_state() {
+        let manager = manager_with(&[("k", json!("v"))]);
+
+        let snap = manager.read_snapshot();
+
+        assert_eq!(snap.get("k"), Some(&json!("v")));
+    }
+
+    #[test]
+    fn read_snapshot_is_independent_of_later_mutations() {
+        let mut manager = manager_with(&[("count", json!(1))]);
+        let snap = manager.read_snapshot();
+
+        manager.state_mut().set("count".into(), json!(999));
+
+        assert_eq!(snap.get("count"), Some(&json!(1)));
+        assert_eq!(manager.state().get("count"), Some(&json!(999)));
+    }
+
+    #[test]
+    fn apply_branch_writes_empty_is_noop() {
+        let mut manager = manager_with(&[("k", json!("v"))]);
+        let reducers = HashMap::new();
+
+        manager.apply_branch_writes(vec![], &reducers).unwrap();
+
+        assert_eq!(manager.state().get("k"), Some(&json!("v")));
+    }
+
+    #[test]
+    fn apply_branch_writes_single_writer_no_reducer_overwrites() {
+        let mut manager = manager_with(&[]);
+        let reducers = HashMap::new();
+
+        manager
+            .apply_branch_writes(vec![branch("n", 0, &[("k", json!(42))])], &reducers)
+            .unwrap();
+
+        assert_eq!(manager.state().get("k"), Some(&json!(42)));
+    }
+
+    #[test]
+    fn apply_branch_writes_disjoint_keys_all_land() {
+        let mut manager = manager_with(&[]);
+        let reducers = HashMap::new();
+
+        manager
+            .apply_branch_writes(
+                vec![
+                    branch("a", 0, &[("x", json!(1))]),
+                    branch("b", 0, &[("y", json!(2))]),
+                    branch("c", 0, &[("z", json!(3))]),
+                ],
+                &reducers,
+            )
+            .unwrap();
+
+        assert_eq!(manager.state().get("x"), Some(&json!(1)));
+        assert_eq!(manager.state().get("y"), Some(&json!(2)));
+        assert_eq!(manager.state().get("z"), Some(&json!(3)));
+    }
+
+    #[test]
+    fn apply_branch_writes_three_appends_preserve_input_order() {
+        let mut manager = manager_with(&[]);
+        let mut reducers = HashMap::new();
+        reducers.insert("items".into(), Reducer::Append);
+
+        manager
+            .apply_branch_writes(
+                vec![
+                    branch("a", 0, &[("items", json!("first"))]),
+                    branch("b", 0, &[("items", json!("second"))]),
+                    branch("c", 0, &[("items", json!("third"))]),
+                ],
+                &reducers,
+            )
+            .unwrap();
+
+        assert_eq!(
+            manager.state().get("items"),
+            Some(&json!(["first", "second", "third"]))
+        );
+    }
+
+    #[test]
+    fn apply_branch_writes_collision_without_reducer_bails() {
+        let mut manager = manager_with(&[]);
+        let reducers = HashMap::new();
+
+        let err = manager
+            .apply_branch_writes(
+                vec![
+                    branch("a", 0, &[("k", json!("first"))]),
+                    branch("b", 0, &[("k", json!("second"))]),
+                ],
+                &reducers,
+            )
+            .unwrap_err()
+            .to_string();
+
+        assert!(err.contains("'k'"), "got: {err}");
+        assert!(err.contains("no reducer"), "got: {err}");
+        assert!(err.contains("2 parallel branches"), "got: {err}");
+    }
+
+    #[test]
+    fn apply_branch_writes_sum_reducer_accumulates_with_existing_state() {
+        let mut manager = manager_with(&[("cost", json!(10))]);
+        let mut reducers = HashMap::new();
+        reducers.insert("cost".into(), Reducer::Sum);
+
+        manager
+            .apply_branch_writes(
+                vec![
+                    branch("a", 0, &[("cost", json!(5))]),
+                    branch("b", 0, &[("cost", json!(7))]),
+                ],
+                &reducers,
+            )
+            .unwrap();
+
+        assert_eq!(manager.state().get("cost"), Some(&json!(22)));
+    }
+
+    #[test]
+    fn apply_branch_writes_concat_respects_branch_order() {
+        let mut manager = manager_with(&[]);
+        let mut reducers = HashMap::new();
+        reducers.insert("log".into(), Reducer::Concat);
+
+        manager
+            .apply_branch_writes(
+                vec![
+                    branch("a", 0, &[("log", json!("alpha"))]),
+                    branch("b", 0, &[("log", json!("bravo"))]),
+                ],
+                &reducers,
+            )
+            .unwrap();
+
+        assert_eq!(manager.state().get("log"), Some(&json!("alpha\nbravo")));
+    }
+
+    #[test]
+    fn apply_branch_writes_mixed_keys_with_and_without_reducers() {
+        let mut manager = manager_with(&[]);
+        let mut reducers = HashMap::new();
+        reducers.insert("results".into(), Reducer::Append);
+
+        manager
+            .apply_branch_writes(
+                vec![
+                    branch(
+                        "a",
+                        0,
+                        &[("results", json!("x")), ("status", json!("ok_a"))],
+                    ),
+                    branch("b", 0, &[("results", json!("y"))]),
+                ],
+                &reducers,
+            )
+            .unwrap();
+
+        assert_eq!(manager.state().get("results"), Some(&json!(["x", "y"])));
+        assert_eq!(manager.state().get("status"), Some(&json!("ok_a")));
+    }
+
+    #[test]
+    fn interpolate_raw_pure_ref_returns_typed_number() {
+        let manager = manager_with(&[("count", json!(42))]);
+
+        let result = manager.interpolate_raw("{{count}}").unwrap();
+
+        assert_eq!(result, json!(42));
+        assert!(result.is_i64());
+    }
+
+    #[test]
+    fn interpolate_raw_pure_ref_returns_typed_array() {
+        let manager = manager_with(&[("items", json!(["a", "b", "c"]))]);
+
+        let result = manager.interpolate_raw("{{items}}").unwrap();
+
+        assert_eq!(result, json!(["a", "b", "c"]));
+        assert!(result.is_array());
+    }
+
+    #[test]
+    fn interpolate_raw_pure_ref_returns_typed_object() {
+        let manager = manager_with(&[("user", json!({ "name": "alice", "age": 30 }))]);
+
+        let result = manager.interpolate_raw("{{user}}").unwrap();
+
+        assert_eq!(result, json!({ "name": "alice", "age": 30 }));
+        assert!(result.is_object());
+    }
+
+    #[test]
+    fn interpolate_raw_pure_ref_returns_typed_bool() {
+        let manager = manager_with(&[("flag", json!(true))]);
+
+        let result = manager.interpolate_raw("{{flag}}").unwrap();
+
+        assert_eq!(result, json!(true));
+        assert!(result.is_boolean());
+    }
+
+    #[test]
+    fn interpolate_raw_nested_path_returns_typed_value() {
+        let manager = manager_with(&[("user", json!({ "email": "x@y.com" }))]);
+
+        let result = manager.interpolate_raw("{{user.email}}").unwrap();
+
+        assert_eq!(result, json!("x@y.com"));
+        assert!(result.is_string());
+    }
+
+    #[test]
+    fn interpolate_raw_array_index_returns_typed_value() {
+        let manager = manager_with(&[("items", json!([10, 20, 30]))]);
+
+        let result = manager.interpolate_raw("{{items[1]}}").unwrap();
+
+        assert_eq!(result, json!(20));
+        assert!(result.is_i64());
+    }
+
+    #[test]
+    fn interpolate_raw_missing_pure_ref_errors() {
+        let manager = manager_with(&[]);
+
+        let err = manager
+            .interpolate_raw("{{ghost}}")
+            .unwrap_err()
+            .to_string();
+
+        assert!(err.contains("'ghost'"), "got: {err}");
+        assert!(err.contains("not found"), "got: {err}");
+    }
+
+    #[test]
+    fn interpolate_raw_mixed_template_falls_back_to_string() {
+        let manager = manager_with(&[("name", json!("alice"))]);
+
+        let result = manager.interpolate_raw("Hello {{name}}!").unwrap();
+
+        assert_eq!(result, json!("Hello alice!"));
+        assert!(result.is_string());
+    }
+
+    #[test]
+    fn interpolate_raw_multiple_refs_fall_back_to_string() {
+        let manager = manager_with(&[("a", json!(1)), ("b", json!(2))]);
+
+        let result = manager.interpolate_raw("{{a}}{{b}}").unwrap();
+
+        assert_eq!(result, json!("12"));
+        assert!(result.is_string());
+    }
+
+    #[test]
+    fn interpolate_raw_no_refs_is_literal_string() {
+        let manager = manager_with(&[]);
+
+        let result = manager.interpolate_raw("literal text").unwrap();
+
+        assert_eq!(result, json!("literal text"));
+    }
+
+    #[test]
+    fn interpolate_raw_whitespace_padding_still_resolves_pure_ref() {
+        let manager = manager_with(&[("k", json!("v"))]);
+
+        let result = manager.interpolate_raw("  {{k}}  ").unwrap();
+
+        assert_eq!(result, json!("v"));
+    }
+
+    #[test]
+    fn interpolate_raw_inner_spaces_treated_as_mixed() {
+        let manager = manager_with(&[("k", json!("v"))]);
+        let result = manager.interpolate_raw("{{ k }}").unwrap();
+        assert_eq!(result, json!("{{ k }}"));
+    }
+
+    #[test]
+    fn fork_for_branch_state_copies_data() {
+        let parent = manager_with(&[("a", json!(1)), ("b", json!("x"))]);
+
+        let fork = parent.fork_for_branch_state();
+
+        assert_eq!(fork.state().get("a"), Some(&json!(1)));
+        assert_eq!(fork.state().get("b"), Some(&json!("x")));
+    }
+
+    #[test]
+    fn fork_for_branch_state_isolates_writes_from_parent() {
+        let parent = manager_with(&[("count", json!(10))]);
+        let mut fork = parent.fork_for_branch_state();
+
+        fork.state_mut().set("count".into(), json!(999));
+
+        assert_eq!(fork.state().get("count"), Some(&json!(999)));
+        assert_eq!(parent.state().get("count"), Some(&json!(10)));
+    }
+
+    #[test]
+    fn fork_for_branch_state_does_not_share_temp_file_lifecycle() {
+        let parent = manager_with(&[("k", json!("v"))]);
+        let fork = parent.fork_for_branch_state();
+
+        assert!(fork.temp_file.is_none());
+        // Dropping the fork must not affect the parent's data
+        drop(fork);
+        assert_eq!(parent.state().get("k"), Some(&json!("v")));
+    }
+
+    #[test]
+    fn diff_against_returns_empty_when_unchanged() {
+        let original = manager_with(&[("a", json!(1)), ("b", json!(2))]);
+        let fork = original.fork_for_branch_state();
+
+        let diff = fork.diff_against(original.state());
+
+        assert!(diff.is_empty());
+    }
+
+    #[test]
+    fn diff_against_reports_newly_written_keys() {
+        let original = manager_with(&[]);
+        let mut fork = original.fork_for_branch_state();
+        fork.state_mut().set("new".into(), json!(42));
+
+        let diff = fork.diff_against(original.state());
+
+        assert_eq!(diff.len(), 1);
+        assert_eq!(diff.get("new"), Some(&json!(42)));
+    }
+
+    #[test]
+    fn diff_against_reports_changed_values_only() {
+        let original = manager_with(&[("a", json!(1)), ("b", json!(2)), ("c", json!(3))]);
+        let mut fork = original.fork_for_branch_state();
+        fork.state_mut().set("b".into(), json!(99));
+
+        let diff = fork.diff_against(original.state());
+
+        assert_eq!(diff.len(), 1);
+        assert_eq!(diff.get("b"), Some(&json!(99)));
+        assert!(!diff.contains_key("a"));
+        assert!(!diff.contains_key("c"));
+    }
+
+    #[test]
+    fn diff_against_does_not_report_reverted_writes() {
+        // Branch writes then writes back to the original value; net change = 0.
+        let original = manager_with(&[("x", json!("initial"))]);
+        let mut fork = original.fork_for_branch_state();
+        fork.state_mut().set("x".into(), json!("modified"));
+        fork.state_mut().set("x".into(), json!("initial"));
+
+        let diff = fork.diff_against(original.state());
+
+        assert!(diff.is_empty(), "reverted write should not appear in diff");
+    }
+}
diff --git a/src/graph/structured.rs b/src/graph/structured.rs
new file mode 100644
index 0000000..a590709
--- /dev/null
+++ b/src/graph/structured.rs
@@ -0,0 +1,189 @@
+use crate::client::call_chat_completions;
+use crate::config::{Input, RequestContext, Role, RoleLike};
+use crate::utils::create_abort_signal;
+use anyhow::{Context, Result, bail};
+use serde_json::Value;
+use std::sync::Arc;
+
+const EXTRACTOR_ROLE_NAME: &str = "__structured_output__";
+
+const EXTRACTOR_ROLE_PROMPT: &str = "\
+Extract a JSON object from the user's input that strictly conforms to the provided JSON Schema.
+
+Rules:
+- Output ONLY the JSON object. No prose, no explanation, no markdown fences, no <think> tokens.
+- The first character of your response must be `{` and the last must be `}`.
+- Every key marked `required` in the schema MUST appear in the output.
+- All values MUST match the types specified in the schema.
+- If the input is already a valid JSON object matching the schema, return it unchanged.
+- If a field cannot be determined from the input, use `null` (when allowed) or your best inferred value.
+- Do NOT invent fields not present in the schema.";
+
+pub async fn extract(raw: &str, schema: &Value, parent_ctx: &mut RequestContext) -> Result<Value> {
+    if let Some(parsed) = try_parse_json(raw) {
+        return Ok(parsed);
+    }
+
+    extract_via_extractor(raw, schema, parent_ctx, false).await
+}
+
+async fn extract_via_extractor(
+    raw: &str,
+    schema: &Value,
+    parent_ctx: &mut RequestContext,
+    is_repair: bool,
+) -> Result<Value> {
+    let role = build_extractor_role()?;
+    let prompt = build_extractor_prompt(raw, schema, is_repair);
+
+    let saved_role = parent_ctx.role.clone();
+    parent_ctx.role = Some(role);
+    let result = run_one_shot(&prompt, parent_ctx).await;
+    parent_ctx.role = saved_role;
+
+    let output = result.context("Structured-output extractor LLM call failed")?;
+
+    match try_parse_json(&output) {
+        Some(value) => Ok(value),
+        None if is_repair => bail!(
+            "Structured-output extractor failed to produce valid JSON after repair retry. \
+             Last response:\n{output}"
+        ),
+        None => Box::pin(extract_via_extractor(&output, schema, parent_ctx, true)).await,
+    }
+}
+
+fn build_extractor_role() -> Result<Role> {
+    let mut role = Role::new(EXTRACTOR_ROLE_NAME, EXTRACTOR_ROLE_PROMPT);
+    role.set_enabled_tools(Some(String::new()));
+    role.set_enabled_mcp_servers(Some(String::new()));
+    Ok(role)
+}
+
+fn build_extractor_prompt(raw: &str, schema: &Value, is_repair: bool) -> String {
+    let schema_json = serde_json::to_string_pretty(schema).unwrap_or_else(|_| schema.to_string());
+    if is_repair {
+        format!(
+            "Your previous response was not valid JSON. Output ONLY a JSON object \
+             matching this schema. No prose, no fences.\n\nSchema:\n{schema_json}\n\nInput:\n{raw}"
+        )
+    } else {
+        format!("Schema:\n{schema_json}\n\nInput:\n{raw}")
+    }
+}
+
+async fn run_one_shot(prompt: &str, ctx: &mut RequestContext) -> Result<String> {
+    let abort = create_abort_signal();
+    let app_cfg = Arc::clone(&ctx.app.config);
+    let role_for_input = ctx.role.clone();
+    let input = Input::from_str(ctx, prompt, role_for_input);
+    let client = input.create_client()?;
+    ctx.before_chat_completion(&input)?;
+    let (output, tool_results) =
+        call_chat_completions(&input, false, false, client.as_ref(), ctx, abort).await?;
+    ctx.after_chat_completion(app_cfg.as_ref(), &input, &output, &tool_results)?;
+
+    Ok(output)
+}
+
+fn try_parse_json(raw: &str) -> Option<Value> {
+    let cleaned = strip_code_fences(raw.trim());
+
+    serde_json::from_str(cleaned).ok()
+}
+
+fn strip_code_fences(s: &str) -> &str {
+    let after_open = s
+        .strip_prefix("```json")
+        .or_else(|| s.strip_prefix("```"))
+        .map(str::trim_start)
+        .unwrap_or(s);
+    after_open
+        .strip_suffix("```")
+        .map(str::trim_end)
+        .unwrap_or(after_open)
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use serde_json::json;
+
+    #[test]
+    fn try_parse_json_accepts_plain_object() {
+        let v = try_parse_json(r#"{"a": 1}"#).unwrap();
+
+        assert_eq!(v, json!({"a": 1}));
+    }
+
+    #[test]
+    fn try_parse_json_strips_json_fences() {
+        let raw = "```json\n{\"a\": 1}\n```";
+
+        let v = try_parse_json(raw).unwrap();
+
+        assert_eq!(v, json!({"a": 1}));
+    }
+
+    #[test]
+    fn try_parse_json_strips_bare_fences() {
+        let raw = "```\n{\"a\": 1}\n```";
+
+        let v = try_parse_json(raw).unwrap();
+
+        assert_eq!(v, json!({"a": 1}));
+    }
+
+    #[test]
+    fn try_parse_json_tolerates_whitespace() {
+        let v = try_parse_json("   \n  {\"x\": true}\n\n").unwrap();
+
+        assert_eq!(v, json!({"x": true}));
+    }
+
+    #[test]
+    fn try_parse_json_returns_none_on_prose() {
+        assert!(try_parse_json("Here is the result: it's good").is_none());
+    }
+
+    #[test]
+    fn try_parse_json_returns_none_on_partial_json() {
+        assert!(try_parse_json("{\"a\": ").is_none());
+    }
+
+    #[test]
+    fn try_parse_json_accepts_arrays() {
+        let v = try_parse_json("[1, 2, 3]").unwrap();
+
+        assert_eq!(v, json!([1, 2, 3]));
+    }
+
+    #[test]
+    fn build_extractor_prompt_includes_schema_and_input() {
+        let schema = json!({"type": "object"});
+
+        let prompt = build_extractor_prompt("hello", &schema, false);
+
+        assert!(prompt.contains("Schema:"));
+        assert!(prompt.contains("Input:"));
+        assert!(prompt.contains("hello"));
+    }
+
+    #[test]
+    fn build_extractor_prompt_repair_includes_repair_instruction() {
+        let schema = json!({"type": "object"});
+
+        let prompt = build_extractor_prompt("oops", &schema, true);
+
+        assert!(prompt.contains("previous response"));
+        assert!(prompt.contains("oops"));
+    }
+
+    #[test]
+    fn build_extractor_role_disables_tools_and_mcp() {
+        let role = build_extractor_role().expect("builtin role must exist");
+
+        assert_eq!(role.enabled_tools().as_deref(), Some(""));
+        assert_eq!(role.enabled_mcp_servers().as_deref(), Some(""));
+    }
+}
diff --git a/src/graph/types.rs b/src/graph/types.rs
new file mode 100644
index 0000000..aa0c72f
--- /dev/null
+++ b/src/graph/types.rs
@@ -0,0 +1,1116 @@
+use crate::config::AgentVariable;
+use anyhow::Result;
+use indexmap::IndexMap;
+use serde::{Deserialize, Serialize};
+use serde_json::Value;
+use std::collections::HashMap;
+use std::slice;
+
+#[derive(Debug, Clone, Deserialize, Serialize)]
+pub struct Graph {
+    pub name: String,
+
+    #[serde(default)]
+    pub description: String,
+
+    #[serde(default = "default_schema_version")]
+    pub version: String,
+
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub model: Option<String>,
+
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub temperature: Option<f64>,
+
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub top_p: Option<f64>,
+
+    #[serde(default)]
+    pub global_tools: Vec<String>,
+
+    #[serde(default)]
+    pub mcp_servers: Vec<String>,
+
+    #[serde(default)]
+    pub conversation_starters: Vec<String>,
+
+    #[serde(default)]
+    pub variables: Vec<AgentVariable>,
+
+    #[serde(default)]
+    pub settings: GraphSettings,
+
+    #[serde(default)]
+    pub initial_state: HashMap<String, Value>,
+
+    #[serde(default)]
+    pub reducers: HashMap<String, Reducer>,
+
+    pub start: String,
+
+    pub nodes: IndexMap<String, Node>,
+}
+
+impl Graph {
+    pub fn get_node(&self, id: &str) -> Option<&Node> {
+        self.nodes.get(id)
+    }
+
+    pub fn has_node(&self, id: &str) -> bool {
+        self.nodes.contains_key(id)
+    }
+
+    pub fn node_ids(&self) -> Vec<&str> {
+        self.nodes.keys().map(|s| s.as_str()).collect()
+    }
+
+    pub fn has_agent_node(&self) -> bool {
+        self.nodes
+            .values()
+            .any(|n| matches!(n.node_type, NodeType::Agent(_)))
+    }
+}
+
+fn default_schema_version() -> String {
+    super::GRAPH_SCHEMA_VERSION.to_string()
+}
+
+#[derive(Debug, Clone, Deserialize, Serialize)]
+pub struct GraphSettings {
+    #[serde(default = "default_max_loop_iterations")]
+    pub max_loop_iterations: usize,
+
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub timeout: Option<u64>,
+
+    #[serde(default = "default_true")]
+    pub log_state_snapshots: bool,
+
+    #[serde(default = "default_true")]
+    pub validate_before_run: bool,
+
+    #[serde(default = "default_max_concurrency")]
+    pub max_concurrency: usize,
+}
+
+impl Default for GraphSettings {
+    fn default() -> Self {
+        Self {
+            max_loop_iterations: default_max_loop_iterations(),
+            timeout: None,
+            log_state_snapshots: true,
+            validate_before_run: true,
+            max_concurrency: default_max_concurrency(),
+        }
+    }
+}
+
+fn default_max_loop_iterations() -> usize {
+    super::DEFAULT_MAX_LOOP_ITERATIONS
+}
+
+fn default_true() -> bool {
+    true
+}
+
+fn default_max_concurrency() -> usize {
+    8
+}
+
+#[derive(Debug, Clone, Deserialize, Serialize)]
+pub struct Node {
+    #[serde(default)]
+    pub id: String,
+
+    #[serde(default)]
+    pub description: String,
+
+    #[serde(flatten)]
+    pub node_type: NodeType,
+
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub next: Option<NextTargets>,
+}
+
+#[cfg(test)]
+impl Node {
+    pub fn next_target(&self) -> Option<&str> {
+        match &self.next {
+            None => None,
+            Some(NextTargets::One(s)) => Some(s),
+            Some(NextTargets::Many(v)) if v.len() == 1 => Some(&v[0]),
+            Some(NextTargets::Many(_)) => None,
+        }
+    }
+}
+
+#[derive(Debug, Clone, Deserialize, Serialize)]
+#[serde(untagged)]
+pub enum NextTargets {
+    One(String),
+    Many(Vec<String>),
+}
+
+impl NextTargets {
+    pub fn as_slice(&self) -> &[String] {
+        match self {
+            NextTargets::One(s) => slice::from_ref(s),
+            NextTargets::Many(v) => v.as_slice(),
+        }
+    }
+
+    pub fn is_fan_out(&self) -> bool {
+        matches!(self, NextTargets::Many(v) if v.len() > 1)
+    }
+}
+
+impl From<String> for NextTargets {
+    fn from(s: String) -> Self {
+        NextTargets::One(s)
+    }
+}
+
+impl From<&str> for NextTargets {
+    fn from(s: &str) -> Self {
+        NextTargets::One(s.to_string())
+    }
+}
+
+impl From<Vec<String>> for NextTargets {
+    fn from(v: Vec<String>) -> Self {
+        NextTargets::Many(v)
+    }
+}
+
+#[derive(Debug, Clone, Deserialize, Serialize)]
+#[serde(tag = "type", rename_all = "lowercase")]
+pub enum NodeType {
+    Agent(AgentNode),
+    Script(ScriptNode),
+    Approval(ApprovalNode),
+    Input(InputNode),
+    Llm(LlmNode),
+    Rag(RagNode),
+    End(EndNode),
+    Map(MapNode),
+}
+
+#[derive(Debug, Clone, Deserialize, Serialize)]
+pub struct AgentNode {
+    pub agent: String,
+
+    pub prompt: String,
+
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub state_updates: Option<HashMap<String, String>>,
+
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub output_schema: Option<Value>,
+
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub timeout: Option<u64>,
+}
+
+#[derive(Debug, Clone, Deserialize, Serialize)]
+pub struct ScriptNode {
+    pub script: String,
+
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub state_updates: Option<HashMap<String, String>>,
+
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub fallback: Option<String>,
+
+    #[serde(default = "default_script_timeout")]
+    pub timeout: u64,
+}
+
+fn default_script_timeout() -> u64 {
+    30
+}
+
+#[derive(Debug, Clone, Deserialize, Serialize)]
+pub struct ApprovalNode {
+    pub question: String,
+
+    pub options: Vec<String>,
+
+    pub routes: HashMap<String, String>,
+
+    pub on_other: String,
+
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub state_updates: Option<HashMap<String, String>>,
+}
+
+#[derive(Debug, Clone, Deserialize, Serialize)]
+pub struct InputNode {
+    pub question: String,
+
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub default: Option<String>,
+
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub validation: Option<String>,
+
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub state_updates: Option<HashMap<String, String>>,
+}
+
+#[derive(Debug, Clone, Deserialize, Serialize)]
+pub struct LlmNode {
+    pub prompt: String,
+
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub instructions: Option<String>,
+
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub tools: Option<Vec<String>>,
+
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub model: Option<String>,
+
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub temperature: Option<f64>,
+
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub top_p: Option<f64>,
+
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub fallback: Option<String>,
+
+    #[serde(default = "default_llm_max_attempts")]
+    pub max_attempts: u32,
+
+    #[serde(default = "default_llm_max_iterations")]
+    pub max_iterations: u32,
+
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub state_updates: Option<HashMap<String, String>>,
+
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub output_schema: Option<Value>,
+
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub timeout: Option<u64>,
+}
+
+fn default_llm_max_attempts() -> u32 {
+    1
+}
+
+fn default_llm_max_iterations() -> u32 {
+    10
+}
+
+#[derive(Debug, Clone, Deserialize, Serialize)]
+pub struct RagNode {
+    pub documents: Vec<String>,
+
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub query: Option<String>,
+
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub top_k: Option<usize>,
+
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub embedding_model: Option<String>,
+
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub chunk_size: Option<usize>,
+
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub chunk_overlap: Option<usize>,
+
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub reranker_model: Option<String>,
+
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub batch_size: Option<usize>,
+
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub state_updates: Option<HashMap<String, String>>,
+
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub timeout: Option<u64>,
+}
+
+#[derive(Debug, Clone, Deserialize, Serialize)]
+pub struct EndNode {
+    #[serde(default)]
+    pub output: String,
+
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub state_updates: Option<HashMap<String, String>>,
+}
+
+#[derive(Debug, Clone, Deserialize, Serialize)]
+pub struct MapNode {
+    pub over: String,
+
+    #[serde(rename = "as")]
+    pub as_name: String,
+
+    pub branch: String,
+
+    #[serde(default = "default_map_output_key")]
+    pub output_key: String,
+
+    pub collect_into: String,
+
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub max_concurrency: Option<usize>,
+}
+
+fn default_map_output_key() -> String {
+    "output".to_string()
+}
+
+#[derive(Debug, Clone, Copy, Deserialize, Serialize, PartialEq, Eq)]
+#[serde(rename_all = "lowercase")]
+pub enum Reducer {
+    Append,
+    Extend,
+    Concat,
+    Sum,
+    Max,
+    Min,
+    Merge,
+    Overwrite,
+}
+
+#[derive(Debug, Clone, Default)]
+pub struct GraphState {
+    data: HashMap<String, Value>,
+    history: Vec<String>,
+    loop_counts: HashMap<String, usize>,
+}
+
+impl GraphState {
+    pub fn new(initial: HashMap<String, Value>) -> Self {
+        Self {
+            data: initial,
+            history: Vec::new(),
+            loop_counts: HashMap::new(),
+        }
+    }
+
+    pub fn get(&self, key: &str) -> Option<&Value> {
+        self.data.get(key)
+    }
+
+    pub fn set(&mut self, key: String, value: Value) {
+        self.data.insert(key, value);
+    }
+
+    pub fn merge(&mut self, json_obj: &serde_json::Map<String, Value>) {
+        for (key, value) in json_obj {
+            self.data.insert(key.clone(), value.clone());
+        }
+    }
+
+    pub fn data(&self) -> &HashMap<String, Value> {
+        &self.data
+    }
+
+    pub fn visit_node(&mut self, node_id: &str) {
+        self.history.push(node_id.to_string());
+        *self.loop_counts.entry(node_id.to_string()).or_insert(0) += 1;
+    }
+
+    pub fn loop_count(&self, node_id: &str) -> usize {
+        self.loop_counts.get(node_id).copied().unwrap_or(0)
+    }
+
+    #[cfg(test)]
+    pub fn current_node(&self) -> Option<&str> {
+        self.history.last().map(|s| s.as_str())
+    }
+
+    pub fn to_json(&self) -> Result<String> {
+        serde_json::to_string(&self.data)
+            .map_err(|e| anyhow::anyhow!("Failed to serialize graph state: {}", e))
+    }
+
+    pub fn size_bytes(&self) -> usize {
+        self.to_json().map(|s| s.len()).unwrap_or(0)
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use serde_json::json;
+
+    #[test]
+    fn deserializes_a_simple_graph() {
+        let yaml = r#"
+name: test_graph
+description: A test graph
+version: "1.0"
+start: node1
+nodes:
+  node1:
+    id: node1
+    type: agent
+    agent: test_agent
+    prompt: "Hello {{name}}"
+    state_updates:
+      result: "{{output}}"
+    next: node2
+  node2:
+    id: node2
+    type: end
+    output: "{{result}}"
+"#;
+        let graph: Graph = serde_yaml::from_str(yaml).unwrap();
+        assert_eq!(graph.name, "test_graph");
+        assert_eq!(graph.start, "node1");
+        assert_eq!(graph.nodes.len(), 2);
+        assert!(graph.has_node("node1"));
+        assert!(graph.has_node("node2"));
+        assert!(!graph.has_node("missing"));
+
+        let node1 = graph.get_node("node1").unwrap();
+        assert!(matches!(node1.node_type, NodeType::Agent(_)));
+
+        let node2 = graph.get_node("node2").unwrap();
+        match &node2.node_type {
+            NodeType::End(end) => assert_eq!(end.output, "{{result}}"),
+            _ => panic!("expected End variant"),
+        }
+    }
+
+    #[test]
+    fn deserializes_every_node_type() {
+        let yaml = r#"
+name: all_types
+start: a
+nodes:
+  a:
+    id: a
+    type: agent
+    agent: helper
+    prompt: hi
+    next: s
+  s:
+    id: s
+    type: script
+    script: scripts/decide.py
+    next: ap
+  ap:
+    id: ap
+    type: approval
+    question: ok?
+    options: [yes, no]
+    routes:
+      yes: i
+      no: e
+    on_other: e
+  i:
+    id: i
+    type: input
+    question: name?
+    state_updates:
+      name: "{{input}}"
+    next: e
+  e:
+    id: e
+    type: end
+    output: done
+"#;
+        let graph: Graph = serde_yaml::from_str(yaml).unwrap();
+        assert!(matches!(
+            graph.get_node("a").unwrap().node_type,
+            NodeType::Agent(_)
+        ));
+        assert!(matches!(
+            graph.get_node("s").unwrap().node_type,
+            NodeType::Script(_)
+        ));
+        assert!(matches!(
+            graph.get_node("ap").unwrap().node_type,
+            NodeType::Approval(_)
+        ));
+        assert!(matches!(
+            graph.get_node("i").unwrap().node_type,
+            NodeType::Input(_)
+        ));
+        assert!(matches!(
+            graph.get_node("e").unwrap().node_type,
+            NodeType::End(_)
+        ));
+    }
+
+    #[test]
+    fn graph_settings_have_sensible_defaults() {
+        let yaml = "name: g\nstart: x\nnodes:\n  x:\n    id: x\n    type: end\n    output: ok\n";
+        let graph: Graph = serde_yaml::from_str(yaml).unwrap();
+        assert_eq!(graph.version, super::super::GRAPH_SCHEMA_VERSION);
+        assert_eq!(
+            graph.settings.max_loop_iterations,
+            super::super::DEFAULT_MAX_LOOP_ITERATIONS
+        );
+        assert!(graph.settings.log_state_snapshots);
+        assert!(graph.settings.validate_before_run);
+        assert!(graph.settings.timeout.is_none());
+        assert!(graph.initial_state.is_empty());
+        assert_eq!(graph.description, "");
+    }
+
+    #[test]
+    fn input_node_with_all_fields() {
+        let yaml = r#"
+id: get_key
+type: input
+question: "Enter your API key:"
+default: "{{previous_api_key}}"
+validation: "len(input) > 0"
+state_updates:
+  api_key: "{{input}}"
+next: configure
+"#;
+        let node: Node = serde_yaml::from_str(yaml).unwrap();
+        let next_target = node.next_target().map(str::to_string);
+        let input = match node.node_type {
+            NodeType::Input(i) => i,
+            _ => panic!("expected Input variant"),
+        };
+        assert_eq!(input.question, "Enter your API key:");
+        assert_eq!(input.default.as_deref(), Some("{{previous_api_key}}"));
+        assert_eq!(input.validation.as_deref(), Some("len(input) > 0"));
+        let updates = input.state_updates.unwrap();
+        assert_eq!(
+            updates.get("api_key").map(|s| s.as_str()),
+            Some("{{input}}")
+        );
+        assert_eq!(next_target.as_deref(), Some("configure"));
+    }
+
+    #[test]
+    fn input_node_with_minimal_fields() {
+        let yaml = r#"
+id: ask
+type: input
+question: "Describe the feature:"
+"#;
+        let node: Node = serde_yaml::from_str(yaml).unwrap();
+        let input = match node.node_type {
+            NodeType::Input(i) => i,
+            _ => panic!("expected Input variant"),
+        };
+        assert_eq!(input.question, "Describe the feature:");
+        assert!(input.default.is_none());
+        assert!(input.validation.is_none());
+        assert!(input.state_updates.is_none());
+        assert!(node.next.is_none());
+    }
+
+    #[test]
+    fn script_node_defaults_timeout_to_30() {
+        let yaml = r#"
+id: s
+type: script
+script: scripts/decide.py
+"#;
+        let node: Node = serde_yaml::from_str(yaml).unwrap();
+        let script = match node.node_type {
+            NodeType::Script(s) => s,
+            _ => panic!("expected Script variant"),
+        };
+        assert_eq!(script.timeout, 30);
+        assert!(script.fallback.is_none());
+        assert!(script.state_updates.is_none());
+    }
+
+    #[test]
+    fn approval_node_carries_routes() {
+        let yaml = r#"
+id: approve
+type: approval
+question: "Approve {{filename}}?"
+options: [approve, reject, edit]
+routes:
+  approve: apply
+  reject: end_reject
+  edit: edit_loop
+on_other: edit_loop
+"#;
+        let node: Node = serde_yaml::from_str(yaml).unwrap();
+        let approval = match node.node_type {
+            NodeType::Approval(a) => a,
+            _ => panic!("expected Approval variant"),
+        };
+        assert_eq!(approval.options.len(), 3);
+        assert_eq!(
+            approval.routes.get("approve").map(|s| s.as_str()),
+            Some("apply")
+        );
+        assert_eq!(
+            approval.routes.get("reject").map(|s| s.as_str()),
+            Some("end_reject")
+        );
+    }
+
+    #[test]
+    fn graph_state_basic_operations() {
+        let mut state = GraphState::new(HashMap::new());
+        state.set("key1".to_string(), json!("value1"));
+        assert_eq!(state.get("key1"), Some(&json!("value1")));
+
+        state.visit_node("node1");
+        state.visit_node("node2");
+        state.visit_node("node1");
+
+        assert_eq!(state.loop_count("node1"), 2);
+        assert_eq!(state.loop_count("node2"), 1);
+        assert_eq!(state.loop_count("never"), 0);
+        assert_eq!(state.history.len(), 3);
+        assert_eq!(state.current_node(), Some("node1"));
+    }
+
+    #[test]
+    fn graph_state_merge_overwrites_existing_keys() {
+        let mut state = GraphState::new(HashMap::new());
+        state.set("existing".to_string(), json!("value"));
+        state.set("kept".to_string(), json!("untouched"));
+
+        let mut obj = serde_json::Map::new();
+        obj.insert("new_key".to_string(), json!("new_value"));
+        obj.insert("count".to_string(), json!(42));
+        obj.insert("existing".to_string(), json!("replaced"));
+
+        state.merge(&obj);
+
+        assert_eq!(state.get("existing"), Some(&json!("replaced")));
+        assert_eq!(state.get("kept"), Some(&json!("untouched")));
+        assert_eq!(state.get("new_key"), Some(&json!("new_value")));
+        assert_eq!(state.get("count"), Some(&json!(42)));
+    }
+
+    #[test]
+    fn graph_state_serializes_to_json() {
+        let mut initial = HashMap::new();
+        initial.insert("k".to_string(), json!("v"));
+        let state = GraphState::new(initial);
+        let serialized = state.to_json().unwrap();
+        let parsed: Value = serde_json::from_str(&serialized).unwrap();
+        assert_eq!(parsed.get("k"), Some(&json!("v")));
+        assert!(state.size_bytes() > 0);
+    }
+
+    #[test]
+    fn graph_state_initial_values_are_seeded() {
+        let mut initial = HashMap::new();
+        initial.insert("user".to_string(), json!("alice"));
+        let state = GraphState::new(initial);
+        assert_eq!(state.get("user"), Some(&json!("alice")));
+        assert!(state.history.is_empty());
+    }
+
+    #[test]
+    fn llm_node_with_all_fields() {
+        let yaml = r#"
+id: classify
+type: llm
+instructions: "You are a classifier."
+prompt: "Classify: {{input_text}}"
+tools:
+  - read_query
+  - "mcp:pubmed-search"
+model: anthropic:claude-3-5-haiku-20241022
+temperature: 0.0
+top_p: 0.5
+fallback: skip_classify
+max_attempts: 3
+max_iterations: 5
+state_updates:
+  category: "{{output}}"
+timeout: 30
+next: review
+"#;
+        let node: Node = serde_yaml::from_str(yaml).unwrap();
+        let next_target = node.next_target().map(str::to_string);
+        let llm = match node.node_type {
+            NodeType::Llm(l) => l,
+            _ => panic!("expected Llm variant"),
+        };
+        assert_eq!(llm.instructions.as_deref(), Some("You are a classifier."));
+        assert_eq!(llm.prompt, "Classify: {{input_text}}");
+        let tools = llm.tools.unwrap();
+        assert_eq!(tools, vec!["read_query", "mcp:pubmed-search"]);
+        assert_eq!(
+            llm.model.as_deref(),
+            Some("anthropic:claude-3-5-haiku-20241022")
+        );
+        assert_eq!(llm.temperature, Some(0.0));
+        assert_eq!(llm.top_p, Some(0.5));
+        assert_eq!(llm.fallback.as_deref(), Some("skip_classify"));
+        assert_eq!(llm.max_attempts, 3);
+        assert_eq!(llm.max_iterations, 5);
+        assert_eq!(llm.timeout, Some(30));
+        assert!(llm.state_updates.is_some());
+        assert_eq!(next_target.as_deref(), Some("review"));
+    }
+
+    #[test]
+    fn llm_node_minimal_fields_use_defaults() {
+        let yaml = r#"
+id: pure_text
+type: llm
+instructions: "System."
+prompt: "User."
+next: done
+"#;
+        let node: Node = serde_yaml::from_str(yaml).unwrap();
+        let llm = match node.node_type {
+            NodeType::Llm(l) => l,
+            _ => panic!("expected Llm variant"),
+        };
+        assert_eq!(llm.instructions.as_deref(), Some("System."));
+        assert_eq!(llm.prompt, "User.");
+        assert!(llm.tools.is_none());
+        assert!(llm.model.is_none());
+        assert!(llm.fallback.is_none());
+        assert_eq!(llm.max_attempts, 1);
+        assert_eq!(llm.max_iterations, 10);
+    }
+
+    #[test]
+    fn llm_node_with_just_prompt_succeeds() {
+        let yaml = r#"
+id: pure
+type: llm
+prompt: "User-only — no system prompt."
+"#;
+        let node: Node = serde_yaml::from_str(yaml).unwrap();
+        let llm = match node.node_type {
+            NodeType::Llm(l) => l,
+            _ => panic!("expected Llm variant"),
+        };
+        assert!(llm.instructions.is_none());
+        assert_eq!(llm.prompt, "User-only — no system prompt.");
+    }
+
+    #[test]
+    fn llm_node_missing_prompt_fails() {
+        let yaml = r#"
+id: bad
+type: llm
+instructions: "System only — no user prompt."
+"#;
+        let result: std::result::Result<Node, _> = serde_yaml::from_str(yaml);
+        assert!(result.is_err());
+    }
+
+    #[test]
+    fn graph_parses_agent_level_top_level_fields() {
+        let yaml = r#"
+name: single_file
+start: e
+model: anthropic:claude-sonnet-4-6
+temperature: 0.2
+top_p: 0.9
+global_tools:
+  - web_search_loki.sh
+mcp_servers:
+  - pubmed-search
+conversation_starters:
+  - "Look up 2160-0"
+nodes:
+  e:
+    id: e
+    type: end
+    output: done
+"#;
+        let graph: Graph = serde_yaml::from_str(yaml).unwrap();
+        assert_eq!(graph.model.as_deref(), Some("anthropic:claude-sonnet-4-6"));
+        assert_eq!(graph.temperature, Some(0.2));
+        assert_eq!(graph.top_p, Some(0.9));
+        assert_eq!(graph.global_tools, vec!["web_search_loki.sh"]);
+        assert_eq!(graph.mcp_servers, vec!["pubmed-search"]);
+        assert_eq!(graph.conversation_starters, vec!["Look up 2160-0"]);
+    }
+
+    #[test]
+    fn graph_agent_level_fields_default_when_absent() {
+        let yaml = "name: g\nstart: x\nnodes:\n  x:\n    id: x\n    type: end\n    output: ok\n";
+        let graph: Graph = serde_yaml::from_str(yaml).unwrap();
+        assert!(graph.model.is_none());
+        assert!(graph.temperature.is_none());
+        assert!(graph.top_p.is_none());
+        assert!(graph.global_tools.is_empty());
+        assert!(graph.mcp_servers.is_empty());
+        assert!(graph.conversation_starters.is_empty());
+    }
+
+    #[test]
+    fn node_ids_lists_nodes_in_order() {
+        let yaml = r#"
+name: g
+start: first
+nodes:
+  first:
+    id: first
+    type: agent
+    agent: helper
+    prompt: hi
+    next: last
+  last:
+    id: last
+    type: end
+    output: done
+"#;
+        let graph: Graph = serde_yaml::from_str(yaml).unwrap();
+        assert_eq!(graph.node_ids(), vec!["first", "last"]);
+    }
+
+    #[test]
+    fn has_agent_node_detects_agent_nodes() {
+        let with_agent = r#"
+name: g
+start: a
+nodes:
+  a:
+    id: a
+    type: agent
+    agent: helper
+    prompt: hi
+    next: e
+  e:
+    id: e
+    type: end
+    output: done
+"#;
+        let graph: Graph = serde_yaml::from_str(with_agent).unwrap();
+        assert!(graph.has_agent_node());
+    }
+
+    #[test]
+    fn has_agent_node_false_without_agent_nodes() {
+        let yaml = "name: g\nstart: x\nnodes:\n  x:\n    id: x\n    type: end\n    output: ok\n";
+        let graph: Graph = serde_yaml::from_str(yaml).unwrap();
+        assert!(!graph.has_agent_node());
+    }
+
+    #[test]
+    fn parses_static_fan_out_as_many_next_targets() {
+        let yaml = r#"
+id: triage
+type: llm
+prompt: Classify
+next: [retrieve_local, retrieve_web, retrieve_docs]
+"#;
+        let node: Node = serde_yaml::from_str(yaml).unwrap();
+
+        let targets = node.next.as_ref().expect("next should be present");
+
+        assert!(targets.is_fan_out());
+        assert_eq!(
+            targets.as_slice(),
+            &[
+                "retrieve_local".to_string(),
+                "retrieve_web".to_string(),
+                "retrieve_docs".to_string()
+            ]
+        );
+    }
+
+    #[test]
+    fn parses_single_target_next_as_one_variant() {
+        let yaml = r#"
+id: triage
+type: llm
+prompt: Classify
+next: retrieve
+"#;
+        let node: Node = serde_yaml::from_str(yaml).unwrap();
+
+        let targets = node.next.as_ref().expect("next should be present");
+
+        assert!(!targets.is_fan_out());
+        assert_eq!(node.next_target(), Some("retrieve"));
+    }
+
+    #[test]
+    fn next_target_treats_many_of_one_as_single() {
+        let yaml = r#"
+id: triage
+type: llm
+prompt: Classify
+next: [retrieve]
+"#;
+
+        let node: Node = serde_yaml::from_str(yaml).unwrap();
+
+        assert_eq!(node.next_target(), Some("retrieve"));
+    }
+
+    #[test]
+    fn next_targets_round_trips_through_yaml_for_both_variants() {
+        let one: NextTargets = serde_yaml::from_str(r#""foo""#).unwrap();
+        let reparsed: NextTargets =
+            serde_yaml::from_str(&serde_yaml::to_string(&one).unwrap()).unwrap();
+        assert_eq!(reparsed.as_slice(), &["foo".to_string()]);
+
+        let many: NextTargets = serde_yaml::from_str("[a, b, c]").unwrap();
+        let reparsed: NextTargets =
+            serde_yaml::from_str(&serde_yaml::to_string(&many).unwrap()).unwrap();
+        assert_eq!(
+            reparsed.as_slice(),
+            &["a".to_string(), "b".to_string(), "c".to_string()]
+        );
+    }
+
+    #[test]
+    fn parses_reducers_block_with_all_builtins() {
+        let yaml = r#"
+name: g
+start: e
+reducers:
+  sources: append
+  findings: extend
+  context: concat
+  cost_usd: sum
+  high_score: max
+  low_score: min
+  config: merge
+  forced: overwrite
+nodes:
+  e:
+    type: end
+    output: ok
+"#;
+
+        let graph: Graph = serde_yaml::from_str(yaml).unwrap();
+
+        assert_eq!(graph.reducers.len(), 8);
+        assert_eq!(graph.reducers.get("sources"), Some(&Reducer::Append));
+        assert_eq!(graph.reducers.get("findings"), Some(&Reducer::Extend));
+        assert_eq!(graph.reducers.get("context"), Some(&Reducer::Concat));
+        assert_eq!(graph.reducers.get("cost_usd"), Some(&Reducer::Sum));
+        assert_eq!(graph.reducers.get("high_score"), Some(&Reducer::Max));
+        assert_eq!(graph.reducers.get("low_score"), Some(&Reducer::Min));
+        assert_eq!(graph.reducers.get("config"), Some(&Reducer::Merge));
+        assert_eq!(graph.reducers.get("forced"), Some(&Reducer::Overwrite));
+    }
+
+    #[test]
+    fn reducers_default_to_empty_when_block_absent() {
+        let yaml = "name: g\nstart: x\nnodes:\n  x:\n    type: end\n";
+
+        let graph: Graph = serde_yaml::from_str(yaml).unwrap();
+
+        assert!(graph.reducers.is_empty());
+    }
+
+    #[test]
+    fn max_concurrency_defaults_to_eight() {
+        let yaml = "name: g\nstart: x\nnodes:\n  x:\n    type: end\n";
+
+        let graph: Graph = serde_yaml::from_str(yaml).unwrap();
+
+        assert_eq!(graph.settings.max_concurrency, 8);
+    }
+
+    #[test]
+    fn max_concurrency_can_be_overridden() {
+        let yaml = r#"
+name: g
+start: x
+settings:
+  max_concurrency: 16
+nodes:
+  x:
+    type: end
+"#;
+
+        let graph: Graph = serde_yaml::from_str(yaml).unwrap();
+
+        assert_eq!(graph.settings.max_concurrency, 16);
+    }
+
+    #[test]
+    fn parses_map_node_with_all_fields() {
+        let yaml = r#"
+id: fan_out
+type: map
+over: "{{subjects}}"
+as: subject
+branch: research_subject
+output_key: research_result
+collect_into: research_results
+max_concurrency: 5
+next: rank
+"#;
+        let node: Node = serde_yaml::from_str(yaml).unwrap();
+
+        let map = match node.node_type {
+            NodeType::Map(m) => m,
+            _ => panic!("expected Map variant"),
+        };
+
+        assert_eq!(map.over, "{{subjects}}");
+        assert_eq!(map.as_name, "subject");
+        assert_eq!(map.branch, "research_subject");
+        assert_eq!(map.output_key, "research_result");
+        assert_eq!(map.collect_into, "research_results");
+        assert_eq!(map.max_concurrency, Some(5));
+    }
+
+    #[test]
+    fn map_node_uses_default_output_key_and_no_concurrency_cap() {
+        let yaml = r#"
+id: fan_out
+type: map
+over: "{{items}}"
+as: item
+branch: process
+collect_into: results
+"#;
+        let node: Node = serde_yaml::from_str(yaml).unwrap();
+
+        let map = match node.node_type {
+            NodeType::Map(m) => m,
+            _ => panic!("expected Map variant"),
+        };
+
+        assert_eq!(map.output_key, "output");
+        assert!(map.max_concurrency.is_none());
+    }
+
+    #[test]
+    fn full_graph_with_all_new_phase_a_fields_parses() {
+        let yaml = r#"
+name: deep_research
+start: triage
+settings:
+  max_concurrency: 4
+reducers:
+  sources: append
+  cost_usd: sum
+nodes:
+  triage:
+    type: llm
+    prompt: Classify
+    next: [retrieve_local, retrieve_web]
+  retrieve_local:
+    type: rag
+    documents: ["./docs"]
+    next: synthesize
+  retrieve_web:
+    type: llm
+    prompt: Search web
+    next: synthesize
+  synthesize:
+    type: end
+    output: done
+"#;
+        let graph: Graph = serde_yaml::from_str(yaml).unwrap();
+        assert_eq!(graph.settings.max_concurrency, 4);
+        assert_eq!(graph.reducers.len(), 2);
+        let triage = graph.get_node("triage").unwrap();
+        assert!(triage.next.as_ref().unwrap().is_fan_out());
+        assert_eq!(triage.next.as_ref().unwrap().as_slice().len(), 2);
+    }
+}
diff --git a/src/graph/user_interaction.rs b/src/graph/user_interaction.rs
new file mode 100644
index 0000000..7bef499
--- /dev/null
+++ b/src/graph/user_interaction.rs
@@ -0,0 +1,369 @@
+use super::state::StateManager;
+use super::types::{ApprovalNode, InputNode};
+use crate::config::RequestContext;
+use crate::function::user_interaction::{USER_FUNCTION_PREFIX, handle_user_tool};
+use anyhow::{Context, Result, anyhow, bail};
+use serde_json::{Value, json};
+use std::collections::HashMap;
+
+const CHOICE_KEY: &str = "choice";
+const INPUT_KEY: &str = "input";
+
+pub struct ApprovalNodeExecutor;
+
+impl ApprovalNodeExecutor {
+    pub async fn execute(
+        node: &ApprovalNode,
+        state_manager: &mut StateManager,
+        ctx: &mut RequestContext,
+    ) -> Result<String> {
+        let question = state_manager
+            .interpolate(&node.question)
+            .context("Failed to interpolate approval question")?;
+
+        let response = handle_user_tool(
+            ctx,
+            &format!("{USER_FUNCTION_PREFIX}ask"),
+            &json!({ "question": question, "options": node.options }),
+        )
+        .await
+        .context("user__ask failed")?;
+
+        if let Some(err) = response.get("error").and_then(Value::as_str) {
+            bail!("Approval interaction failed: {err}");
+        }
+
+        let choice = response
+            .get("answer")
+            .and_then(Value::as_str)
+            .context("Approval response missing 'answer' field")?
+            .to_string();
+
+        apply_state_updates_with_var(&node.state_updates, state_manager, CHOICE_KEY, &choice);
+
+        resolve_approval_route(node, &choice)
+    }
+}
+
+pub struct InputNodeExecutor;
+
+impl InputNodeExecutor {
+    pub async fn execute(
+        node: &InputNode,
+        node_next: Option<&str>,
+        state_manager: &mut StateManager,
+        ctx: &mut RequestContext,
+    ) -> Result<String> {
+        let question = build_input_question(node, state_manager)?;
+
+        let response = handle_user_tool(
+            ctx,
+            &format!("{USER_FUNCTION_PREFIX}input"),
+            &json!({ "question": question }),
+        )
+        .await
+        .context("user__input failed")?;
+
+        if let Some(err) = response.get("error").and_then(Value::as_str) {
+            bail!("Input interaction failed: {err}");
+        }
+
+        let raw = response
+            .get("answer")
+            .and_then(Value::as_str)
+            .context("Input response missing 'answer' field")?
+            .to_string();
+
+        let input_text = if raw.is_empty() {
+            node.default
+                .as_ref()
+                .map(|t| state_manager.interpolate_lenient(t))
+                .unwrap_or_default()
+        } else {
+            raw
+        };
+
+        if let Some(expr) = &node.validation
+            && !validate_length(&input_text, expr)?
+        {
+            bail!(
+                "Input failed validation '{}' (got {} chars)",
+                expr,
+                input_text.chars().count()
+            );
+        }
+
+        apply_state_updates_with_var(&node.state_updates, state_manager, INPUT_KEY, &input_text);
+
+        node_next
+            .map(String::from)
+            .ok_or_else(|| anyhow!("Input node has no `next` set"))
+    }
+}
+
+fn build_input_question(node: &InputNode, state_manager: &StateManager) -> Result<String> {
+    let mut question = state_manager
+        .interpolate(&node.question)
+        .context("Failed to interpolate input question")?;
+
+    if let Some(default_template) = &node.default {
+        let default = state_manager.interpolate_lenient(default_template);
+        if !default.is_empty() {
+            question = format!("{question} [default: {default}]");
+        }
+    }
+
+    Ok(question)
+}
+
+fn resolve_approval_route(node: &ApprovalNode, choice: &str) -> Result<String> {
+    if let Some(target) = node.routes.get(choice) {
+        return Ok(target.clone());
+    }
+
+    Ok(node.on_other.clone())
+}
+
+fn apply_state_updates_with_var(
+    updates: &Option<HashMap<String, String>>,
+    state_manager: &mut StateManager,
+    var_name: &str,
+    var_value: &str,
+) {
+    let Some(updates) = updates else {
+        return;
+    };
+    let prev = state_manager.state().get(var_name).cloned();
+    state_manager
+        .state_mut()
+        .set(var_name.into(), Value::String(var_value.to_string()));
+
+    for (key, template) in updates {
+        let value = state_manager.interpolate_lenient(template);
+        state_manager
+            .state_mut()
+            .set(key.clone(), Value::String(value));
+    }
+
+    match prev {
+        Some(v) => state_manager.state_mut().set(var_name.into(), v),
+        None => {
+            state_manager.state_mut().set(var_name.into(), Value::Null);
+        }
+    }
+}
+
+/// Evaluate a `len(input) OP N` expression where OP is one of `>`, `>=`,
+/// `<`, `<=`, `==`. Lengths are byte counts (matches Rust's `str::len`).
+/// Other expressions are rejected at runtime.
+fn validate_length(input: &str, expr: &str) -> Result<bool> {
+    let trimmed = expr.trim();
+    let after_len = trimmed
+        .strip_prefix("len(input)")
+        .map(str::trim)
+        .ok_or_else(|| {
+            anyhow!(
+                "Unsupported validation expression '{expr}'; only `len(input) OP N` is supported"
+            )
+        })?;
+
+    let (op, rhs_str) = if let Some(rest) = after_len.strip_prefix(">=") {
+        (">=", rest)
+    } else if let Some(rest) = after_len.strip_prefix("<=") {
+        ("<=", rest)
+    } else if let Some(rest) = after_len.strip_prefix("==") {
+        ("==", rest)
+    } else if let Some(rest) = after_len.strip_prefix('>') {
+        (">", rest)
+    } else if let Some(rest) = after_len.strip_prefix('<') {
+        ("<", rest)
+    } else {
+        bail!("No comparison operator in validation expression '{expr}'");
+    };
+
+    let rhs: usize = rhs_str
+        .trim()
+        .parse()
+        .with_context(|| format!("Invalid right-hand side in validation '{expr}'"))?;
+
+    let len = input.len();
+    Ok(match op {
+        ">=" => len >= rhs,
+        "<=" => len <= rhs,
+        "==" => len == rhs,
+        ">" => len > rhs,
+        "<" => len < rhs,
+        _ => unreachable!(),
+    })
+}
+
+#[cfg(test)]
+mod tests {
+    use super::super::types::*;
+    use super::*;
+    use serde_json::json;
+
+    fn manager_with(pairs: &[(&str, Value)]) -> StateManager {
+        let mut map = HashMap::new();
+        for (k, v) in pairs {
+            map.insert((*k).into(), v.clone());
+        }
+
+        StateManager::new(map)
+    }
+
+    fn approval(options: &[&str], routes: &[(&str, &str)], on_other: &str) -> ApprovalNode {
+        let mut r = HashMap::new();
+        for (k, v) in routes {
+            r.insert((*k).into(), (*v).into());
+        }
+
+        ApprovalNode {
+            question: "?".into(),
+            options: options.iter().map(|s| (*s).into()).collect(),
+            routes: r,
+            on_other: on_other.into(),
+            state_updates: None,
+        }
+    }
+
+    fn input(question: &str) -> InputNode {
+        InputNode {
+            question: question.into(),
+            default: None,
+            validation: None,
+            state_updates: None,
+        }
+    }
+
+    #[test]
+    fn validate_length_supports_all_comparison_operators() {
+        assert!(validate_length("hello", "len(input) > 0").unwrap());
+        assert!(!validate_length("", "len(input) > 0").unwrap());
+        assert!(validate_length("hello", "len(input) >= 5").unwrap());
+        assert!(!validate_length("hi", "len(input) >= 5").unwrap());
+        assert!(validate_length("hello", "len(input) < 10").unwrap());
+        assert!(!validate_length("hello world!", "len(input) < 10").unwrap());
+        assert!(validate_length("hi", "len(input) <= 2").unwrap());
+        assert!(!validate_length("hello", "len(input) <= 2").unwrap());
+        assert!(validate_length("hello", "len(input) == 5").unwrap());
+        assert!(!validate_length("hello", "len(input) == 3").unwrap());
+    }
+
+    #[test]
+    fn validate_length_handles_whitespace() {
+        assert!(validate_length("hi", "  len(input)   >=   1  ").unwrap());
+    }
+
+    #[test]
+    fn validate_length_rejects_unsupported_expressions() {
+        assert!(validate_length("x", "matches /[a-z]+/").is_err());
+        assert!(validate_length("x", "len(input)").is_err());
+        assert!(validate_length("x", "len(input) >").is_err());
+        assert!(validate_length("x", "len(input) >= abc").is_err());
+    }
+
+    #[test]
+    fn approval_route_lookup_returns_target_on_match() {
+        let node = approval(
+            &["yes", "no"],
+            &[("yes", "deploy"), ("no", "cancel")],
+            "clarify",
+        );
+
+        assert_eq!(resolve_approval_route(&node, "yes").unwrap(), "deploy");
+        assert_eq!(resolve_approval_route(&node, "no").unwrap(), "cancel");
+    }
+
+    #[test]
+    fn approval_route_lookup_falls_back_to_on_other_for_unknown_choice() {
+        let node = approval(
+            &["yes", "no"],
+            &[("yes", "deploy"), ("no", "cancel")],
+            "clarify",
+        );
+
+        assert_eq!(resolve_approval_route(&node, "maybe").unwrap(), "clarify");
+        assert_eq!(
+            resolve_approval_route(&node, "free-form text").unwrap(),
+            "clarify"
+        );
+    }
+
+    #[test]
+    fn state_updates_expose_choice_during_evaluation_only() {
+        let mut updates = HashMap::new();
+        updates.insert("decision".into(), "{{choice}}".into());
+        let mut state = manager_with(&[]);
+
+        apply_state_updates_with_var(&Some(updates), &mut state, CHOICE_KEY, "approve");
+
+        assert_eq!(state.state().get("decision"), Some(&json!("approve")));
+        assert_eq!(state.state().get(CHOICE_KEY), Some(&Value::Null));
+    }
+
+    #[test]
+    fn state_updates_preserve_pre_existing_var_value() {
+        let mut updates = HashMap::new();
+        updates.insert("decision".into(), "{{choice}}".into());
+        let mut state = manager_with(&[("choice", json!("preserved"))]);
+
+        apply_state_updates_with_var(&Some(updates), &mut state, CHOICE_KEY, "approve");
+
+        assert_eq!(state.state().get("decision"), Some(&json!("approve")));
+        assert_eq!(state.state().get(CHOICE_KEY), Some(&json!("preserved")));
+    }
+
+    #[test]
+    fn state_updates_for_input_use_input_key() {
+        let mut updates = HashMap::new();
+        updates.insert("api_key".into(), "{{input}}".into());
+        let mut state = manager_with(&[]);
+
+        apply_state_updates_with_var(&Some(updates), &mut state, INPUT_KEY, "sk-12345");
+
+        assert_eq!(state.state().get("api_key"), Some(&json!("sk-12345")));
+        assert_eq!(state.state().get(INPUT_KEY), Some(&Value::Null));
+    }
+
+    #[test]
+    fn input_question_appends_default_when_present() {
+        let state = manager_with(&[("name", json!("alice"))]);
+        let mut node = input("Hi, what's your name?");
+        node.default = Some("{{name}}".into());
+
+        let q = build_input_question(&node, &state).unwrap();
+
+        assert_eq!(q, "Hi, what's your name? [default: alice]");
+    }
+
+    #[test]
+    fn input_question_omits_default_when_blank_after_interpolation() {
+        let state = manager_with(&[]);
+        let mut node = input("Enter value:");
+        node.default = Some("{{missing}}".into());
+
+        let q = build_input_question(&node, &state).unwrap();
+
+        assert_eq!(q, "Enter value:");
+    }
+
+    #[test]
+    fn input_question_uses_no_default_when_field_absent() {
+        let state = manager_with(&[]);
+        let node = input("Enter value:");
+
+        let q = build_input_question(&node, &state).unwrap();
+
+        assert_eq!(q, "Enter value:");
+    }
+
+    #[test]
+    fn no_state_updates_means_var_never_appears_in_state() {
+        let mut state = manager_with(&[]);
+
+        apply_state_updates_with_var(&None, &mut state, CHOICE_KEY, "approve");
+
+        assert!(state.state().get(CHOICE_KEY).is_none());
+    }
+}
diff --git a/src/graph/validator.rs b/src/graph/validator.rs
new file mode 100644
index 0000000..ca4e749
--- /dev/null
+++ b/src/graph/validator.rs
@@ -0,0 +1,2318 @@
+use super::state::template_root_keys;
+use super::types::{Graph, Node, NodeType};
+use crate::client::{Model, ModelType};
+use crate::config::{Agent, AppConfig, paths};
+use anyhow::{Result, bail};
+use std::collections::{BTreeMap, HashSet, VecDeque};
+use std::path::PathBuf;
+use std::sync::Arc;
+
+#[derive(Debug, Clone)]
+pub struct ValidationError {
+    pub node_id: Option<String>,
+    pub message: String,
+}
+
+impl ValidationError {
+    fn new(message: impl Into<String>) -> Self {
+        Self {
+            node_id: None,
+            message: message.into(),
+        }
+    }
+
+    fn with_node(node_id: impl Into<String>, message: impl Into<String>) -> Self {
+        Self {
+            node_id: Some(node_id.into()),
+            message: message.into(),
+        }
+    }
+}
+
+#[derive(Debug, Default)]
+pub struct ValidationResult {
+    pub errors: Vec<ValidationError>,
+    pub warnings: Vec<ValidationError>,
+}
+
+impl ValidationResult {
+    pub fn is_valid(&self) -> bool {
+        self.errors.is_empty()
+    }
+
+    fn error(&mut self, e: ValidationError) {
+        self.errors.push(e);
+    }
+
+    fn warning(&mut self, w: ValidationError) {
+        self.warnings.push(w);
+    }
+
+    pub fn into_result(self) -> Result<()> {
+        if self.is_valid() {
+            return Ok(());
+        }
+        let lines: Vec<String> = self
+            .errors
+            .iter()
+            .map(|e| match &e.node_id {
+                Some(id) => format!("  [{id}] {}", e.message),
+                None => format!("  {}", e.message),
+            })
+            .collect();
+
+        bail!(
+            "Graph validation failed with {} error(s):\n{}",
+            self.errors.len(),
+            lines.join("\n")
+        );
+    }
+}
+
+pub struct AgentValidationContext {
+    pub tool_names: HashSet<String>,
+    pub mcp_servers: HashSet<String>,
+    pub app_config: Arc<AppConfig>,
+}
+
+impl AgentValidationContext {
+    pub fn from_agent(agent: &Agent, app_config: Arc<AppConfig>) -> Self {
+        Self {
+            tool_names: agent
+                .functions()
+                .declarations()
+                .iter()
+                .map(|d| d.name.clone())
+                .collect(),
+            mcp_servers: agent.mcp_server_names().iter().cloned().collect(),
+            app_config,
+        }
+    }
+}
+
+pub struct GraphValidator {
+    base_dir: PathBuf,
+    agent_ctx: Option<AgentValidationContext>,
+}
+
+impl GraphValidator {
+    pub fn new(base_dir: impl Into<PathBuf>) -> Self {
+        Self {
+            base_dir: base_dir.into(),
+            agent_ctx: None,
+        }
+    }
+
+    pub fn with_agent_context(mut self, ctx: AgentValidationContext) -> Self {
+        self.agent_ctx = Some(ctx);
+        self
+    }
+
+    pub fn validate(&self, graph: &Graph) -> ValidationResult {
+        let mut result = ValidationResult::default();
+        self.validate_node_references(graph, &mut result);
+        self.validate_cycles(graph, &mut result);
+        self.validate_reachability(graph, &mut result);
+        self.validate_terminal_nodes(graph, &mut result);
+        self.validate_scripts(graph, &mut result);
+        self.validate_agents(graph, &mut result);
+        self.validate_approval_routes(graph, &mut result);
+        self.validate_rag_nodes(graph, &mut result);
+        self.validate_llm_nodes(graph, &mut result);
+        self.validate_max_concurrency(graph, &mut result);
+        self.validate_map_branches(graph, &mut result);
+        self.validate_parallel_user_interaction(graph, &mut result);
+        self.validate_parallel_writes(graph, &mut result);
+        self.validate_parallel_reads(graph, &mut result);
+
+        result
+    }
+
+    fn validate_rag_nodes(&self, graph: &Graph, result: &mut ValidationResult) {
+        for (node_id, node) in &graph.nodes {
+            if let NodeType::Rag(r) = &node.node_type {
+                if r.documents.is_empty() {
+                    result.error(ValidationError::with_node(
+                        node_id,
+                        "RAG node has no 'documents'; at least one knowledge source \
+                         is required",
+                    ));
+                }
+                if r.state_updates.is_none() {
+                    result.warning(ValidationError::with_node(
+                        node_id,
+                        "RAG node has no 'state_updates'; its retrieval result will \
+                         not be written to state",
+                    ));
+                }
+            }
+        }
+    }
+
+    fn validate_llm_nodes(&self, graph: &Graph, result: &mut ValidationResult) {
+        let Some(ctx) = &self.agent_ctx else {
+            return;
+        };
+
+        for (node_id, node) in &graph.nodes {
+            let NodeType::Llm(llm) = &node.node_type else {
+                continue;
+            };
+
+            if let Some(tools) = &llm.tools {
+                for entry in tools {
+                    if let Some(server) = entry.strip_prefix("mcp:") {
+                        if !ctx.mcp_servers.contains(server) {
+                            result.error(ValidationError::with_node(
+                                node_id,
+                                format!("llm node references unknown MCP server 'mcp:{server}'"),
+                            ));
+                        }
+                    } else if !ctx.tool_names.contains(entry) {
+                        result.error(ValidationError::with_node(
+                            node_id,
+                            format!("llm node references unknown tool '{entry}'"),
+                        ));
+                    }
+                }
+            }
+
+            if let Some(model_id) = &llm.model
+                && Model::retrieve_model(ctx.app_config.as_ref(), model_id, ModelType::Chat)
+                    .is_err()
+            {
+                result.error(ValidationError::with_node(
+                    node_id,
+                    format!("llm node references unknown model '{model_id}'"),
+                ));
+            }
+        }
+    }
+
+    fn validate_node_references(&self, graph: &Graph, result: &mut ValidationResult) {
+        for (node_id, node) in &graph.nodes {
+            for (target, label) in declared_targets(node) {
+                if !graph.has_node(&target) {
+                    result.error(ValidationError::with_node(
+                        node_id,
+                        format!("References non-existent node '{target}' in {label}"),
+                    ));
+                }
+            }
+        }
+    }
+
+    fn validate_cycles(&self, graph: &Graph, result: &mut ValidationResult) {
+        let mut visited: HashSet<String> = HashSet::new();
+        let mut rec_stack: HashSet<String> = HashSet::new();
+        let mut path: Vec<String> = Vec::new();
+
+        for node_id in graph.node_ids() {
+            if !visited.contains(node_id)
+                && let Some(cycle) =
+                    detect_cycle_dfs(graph, node_id, &mut visited, &mut rec_stack, &mut path)
+            {
+                result.error(ValidationError::new(format!(
+                    "Cycle detected: {}",
+                    cycle.join(" -> ")
+                )));
+                return;
+            }
+        }
+    }
+
+    fn validate_reachability(&self, graph: &Graph, result: &mut ValidationResult) {
+        let reachable = find_reachable_nodes(graph);
+        for node_id in graph.node_ids() {
+            if !reachable.contains(node_id) {
+                result.warning(ValidationError::with_node(
+                    node_id,
+                    "Node is unreachable from the start node via declared edges \
+                     (script `_next` routing is not analyzed)",
+                ));
+            }
+        }
+    }
+
+    fn validate_terminal_nodes(&self, graph: &Graph, result: &mut ValidationResult) {
+        let has_any_end = graph
+            .nodes
+            .values()
+            .any(|n| matches!(n.node_type, NodeType::End(_)));
+
+        if !has_any_end {
+            result.error(ValidationError::new(
+                "Graph has no end nodes; execution would never terminate",
+            ));
+            return;
+        }
+
+        let reachable = find_reachable_nodes(graph);
+        let reachable_end = graph
+            .nodes
+            .iter()
+            .any(|(id, n)| matches!(n.node_type, NodeType::End(_)) && reachable.contains(id));
+        if !reachable_end {
+            result.warning(ValidationError::new(
+                "No end node is reachable from the start node via declared edges \
+                 (a script's `_next` may still route to one)",
+            ));
+        }
+    }
+
+    fn validate_scripts(&self, graph: &Graph, result: &mut ValidationResult) {
+        for (node_id, node) in &graph.nodes {
+            if let NodeType::Script(s) = &node.node_type {
+                let script_path = self.base_dir.join(&s.script);
+                if !script_path.exists() {
+                    result.error(ValidationError::with_node(
+                        node_id,
+                        format!("Script file not found: '{}'", script_path.display()),
+                    ));
+                }
+            }
+        }
+    }
+
+    fn validate_agents(&self, graph: &Graph, result: &mut ValidationResult) {
+        for (node_id, node) in &graph.nodes {
+            if let NodeType::Agent(a) = &node.node_type {
+                let agent_dir = paths::agent_data_dir(&a.agent);
+                let has_config = paths::agent_config_file(&a.agent).exists();
+                let has_graph = paths::agent_graph_file(&a.agent).exists();
+                if !agent_dir.exists() {
+                    result.error(ValidationError::with_node(
+                        node_id,
+                        format!("Agent '{}' not found (directory missing)", a.agent),
+                    ));
+                } else if !has_config && !has_graph {
+                    result.error(ValidationError::with_node(
+                        node_id,
+                        format!(
+                            "Agent '{}' has neither a config.yaml nor a graph.yaml",
+                            a.agent
+                        ),
+                    ));
+                }
+            }
+        }
+    }
+
+    fn validate_approval_routes(&self, graph: &Graph, result: &mut ValidationResult) {
+        for (node_id, node) in &graph.nodes {
+            if let NodeType::Approval(a) = &node.node_type {
+                for option in &a.options {
+                    if !a.routes.contains_key(option) {
+                        result.error(ValidationError::with_node(
+                            node_id,
+                            format!("Approval option '{option}' has no route defined"),
+                        ));
+                    }
+                }
+                for key in a.routes.keys() {
+                    if !a.options.contains(key) {
+                        result.warning(ValidationError::with_node(
+                            node_id,
+                            format!("Route '{key}' has no corresponding option"),
+                        ));
+                    }
+                }
+            }
+        }
+    }
+
+    // Parallel-execution validation.
+    //
+    // The v1 algorithm uses immediate-successor analysis only: a parallel group is the set of `next:` targets of a
+    // single fan-out node. Map nodes are checked separately by `validate_map_branches` (the branch is self-parallel,
+    // but enforcement comes from strict-mode rules on the branch node, not from group membership). Transitive parallel
+    // groups (deeper fan-out chains) are a v2 enhancement; v1 over-reports rather than under-reports. A false positive
+    // forces an unneeded reducer (mild annoyance); a false negative allows silent data races (catastrophic).
+    fn validate_max_concurrency(&self, graph: &Graph, result: &mut ValidationResult) {
+        if graph.settings.max_concurrency == 0 {
+            result.error(ValidationError::new(
+                "settings.max_concurrency must be >= 1 (got 0); a zero cap would \
+                 deadlock the executor",
+            ));
+        }
+
+        for (node_id, node) in &graph.nodes {
+            if let NodeType::Map(m) = &node.node_type
+                && let Some(0) = m.max_concurrency
+            {
+                result.error(ValidationError::with_node(
+                    node_id,
+                    "map node's `max_concurrency` must be >= 1 (got 0); a zero cap \
+                     would deadlock the executor",
+                ));
+            }
+        }
+    }
+
+    fn validate_map_branches(&self, graph: &Graph, result: &mut ValidationResult) {
+        for (map_id, node) in &graph.nodes {
+            let NodeType::Map(m) = &node.node_type else {
+                continue;
+            };
+            let Some(branch) = graph.get_node(&m.branch) else {
+                continue;
+            };
+
+            match &branch.node_type {
+                NodeType::Approval(_) => {
+                    result.error(ValidationError::with_node(
+                        map_id,
+                        format!(
+                            "map node points to branch '{}' which is an approval node; \
+                             approval/input nodes cannot run inside a parallel map branch \
+                             (the CLI would prompt the user N times concurrently)",
+                            m.branch
+                        ),
+                    ));
+                    continue;
+                }
+                NodeType::Input(_) => {
+                    result.error(ValidationError::with_node(
+                        map_id,
+                        format!(
+                            "map node points to branch '{}' which is an input node; \
+                             input nodes cannot run inside a parallel map branch",
+                            m.branch
+                        ),
+                    ));
+                    continue;
+                }
+                NodeType::End(_) => {
+                    result.error(ValidationError::with_node(
+                        map_id,
+                        format!(
+                            "map node points to branch '{}' which is an end node; \
+                             map branches terminate via the map's collect mechanism, \
+                             not via end nodes",
+                            m.branch
+                        ),
+                    ));
+                    continue;
+                }
+                NodeType::Map(_) => {
+                    result.error(ValidationError::with_node(
+                        map_id,
+                        format!(
+                            "map node points to branch '{}' which is itself a map node; \
+                             nested map fan-outs are not supported in v1",
+                            m.branch
+                        ),
+                    ));
+                    continue;
+                }
+                _ => {}
+            }
+
+            if branch.next.is_some() {
+                result.error(ValidationError::with_node(
+                    m.branch.clone(),
+                    format!(
+                        "branch node '{}' has a `next` declared, but map branches must be \
+                         atomic (one node, one execution per item). Remove `next` or \
+                         restructure the workflow so any chaining happens after the map.",
+                        m.branch
+                    ),
+                ));
+            }
+
+            if let Some(updates) = node_state_updates_keys(branch) {
+                for k in &updates {
+                    if k != &m.output_key {
+                        result.error(ValidationError::with_node(
+                            m.branch.clone(),
+                            format!(
+                                "branch node '{}' writes state key '{}' via state_updates, \
+                                 but map branches may only write through their `output_key` \
+                                 ('{}'). Rename the write, or move the side effect outside \
+                                 the map.",
+                                m.branch, k, m.output_key
+                            ),
+                        ));
+                    }
+                }
+            }
+
+            let schema_keys = output_schema_top_level_keys(branch);
+            if !schema_keys.is_empty() {
+                let mut keys_sorted: Vec<String> = schema_keys.into_iter().collect();
+                keys_sorted.sort();
+                result.error(ValidationError::with_node(
+                    m.branch.clone(),
+                    format!(
+                        "branch node '{}' has an `output_schema` with top-level \
+                         properties ({}); map branches must write only through their \
+                         `output_key` ('{}'). Remove `output_schema`, or use state_updates \
+                         to map the output explicitly.",
+                        m.branch,
+                        keys_sorted.join(", "),
+                        m.output_key
+                    ),
+                ));
+            }
+        }
+    }
+
+    fn validate_parallel_user_interaction(&self, graph: &Graph, result: &mut ValidationResult) {
+        for group in compute_parallel_groups(graph) {
+            for node_id in &group {
+                let Some(node) = graph.get_node(node_id) else {
+                    continue;
+                };
+                match &node.node_type {
+                    NodeType::Approval(_) => {
+                        result.error(ValidationError::with_node(
+                            node_id,
+                            "approval node is an immediate target of a fan-out \
+                             (`next: [...]`); approvals must run after the join, \
+                             not inside a parallel branch",
+                        ));
+                    }
+                    NodeType::Input(_) => {
+                        result.error(ValidationError::with_node(
+                            node_id,
+                            "input node is an immediate target of a fan-out \
+                             (`next: [...]`); input nodes must run after the join, \
+                             not inside a parallel branch",
+                        ));
+                    }
+                    _ => {}
+                }
+            }
+        }
+    }
+
+    fn validate_parallel_writes(&self, graph: &Graph, result: &mut ValidationResult) {
+        for group in compute_parallel_groups(graph) {
+            let mut node_writes: Vec<(String, HashSet<String>)> = Vec::new();
+            for node_id in &group {
+                let Some(node) = graph.get_node(node_id) else {
+                    continue;
+                };
+                match write_set_of(node) {
+                    Some(set) => node_writes.push((node_id.clone(), set)),
+                    None => {
+                        result.error(ValidationError::with_node(
+                            node_id,
+                            "script node is in a parallel branch but declares no \
+                             `state_updates`; parallel scripts must declare their writes \
+                             explicitly to avoid silent state collisions",
+                        ));
+                    }
+                }
+            }
+
+            let mut writers_by_key: BTreeMap<String, Vec<String>> = BTreeMap::new();
+            for (nid, ws) in &node_writes {
+                for k in ws {
+                    writers_by_key
+                        .entry(k.clone())
+                        .or_default()
+                        .push(nid.clone());
+                }
+            }
+
+            for (key, mut writers) in writers_by_key {
+                if writers.len() < 2 {
+                    continue;
+                }
+                if graph.reducers.contains_key(&key) {
+                    continue;
+                }
+                writers.sort();
+                result.error(ValidationError::new(format!(
+                    "nodes [{}] all write key '{}' in the same parallel super-step but \
+                     no reducer is declared for '{}'. Add `reducers: {{ {}: <reducer> }}` \
+                     at the graph root (built-ins: append, extend, concat, sum, max, min, \
+                     merge, overwrite), or rename one node's output.",
+                    writers.join(", "),
+                    key,
+                    key,
+                    key,
+                )));
+            }
+        }
+    }
+
+    fn validate_parallel_reads(&self, graph: &Graph, result: &mut ValidationResult) {
+        for group in compute_parallel_groups(graph) {
+            let nodes: Vec<(&String, &Node)> = group
+                .iter()
+                .filter_map(|id| graph.nodes.get(id).map(|n| (id, n)))
+                .collect();
+
+            for (id_a, node_a) in &nodes {
+                let read_set_a = read_set_of(node_a);
+                if read_set_a.is_empty() {
+                    continue;
+                }
+                for (id_b, node_b) in &nodes {
+                    if id_b == id_a {
+                        continue;
+                    }
+                    let Some(write_set_b) = write_set_of(node_b) else {
+                        continue;
+                    };
+                    let mut collisions: Vec<String> =
+                        read_set_a.intersection(&write_set_b).cloned().collect();
+                    if collisions.is_empty() {
+                        continue;
+                    }
+                    collisions.sort();
+                    let keys = collisions
+                        .iter()
+                        .map(|k| format!("`{k}`"))
+                        .collect::<Vec<_>>()
+                        .join(", ");
+                    result.error(ValidationError::with_node(
+                        id_a.as_str(),
+                        format!(
+                            "node '{id_a}' reads state key(s) {keys} which sibling parallel \
+                             branch '{id_b}' writes in the same super-step; parallel branches \
+                             see a state snapshot taken BEFORE the super-step and cannot observe \
+                             each other's writes. Move the dependent read to a later super-step \
+                             (or remove the cross-branch reference)."
+                        ),
+                    ));
+                }
+            }
+        }
+    }
+}
+
+fn declared_targets(node: &Node) -> Vec<(String, &'static str)> {
+    let mut out = Vec::new();
+    if let Some(targets) = &node.next {
+        for target in targets.as_slice() {
+            out.push((target.clone(), "'next'"));
+        }
+    }
+
+    match &node.node_type {
+        NodeType::Approval(a) => {
+            for v in a.routes.values() {
+                out.push((v.clone(), "approval 'routes'"));
+            }
+            out.push((a.on_other.clone(), "approval 'on_other'"));
+        }
+        NodeType::Script(s) => {
+            if let Some(t) = &s.fallback {
+                out.push((t.clone(), "script 'fallback'"));
+            }
+        }
+        NodeType::Llm(l) => {
+            if let Some(t) = &l.fallback {
+                out.push((t.clone(), "llm 'fallback'"));
+            }
+        }
+        NodeType::Map(m) => {
+            out.push((m.branch.clone(), "map 'branch'"));
+        }
+        // `agent`/`input`/`rag` route only via `next` (already collected
+        // above); `end` is terminal. No type-specific routing edges to add.
+        NodeType::Agent(_) | NodeType::Input(_) | NodeType::Rag(_) | NodeType::End(_) => {}
+    }
+    out
+}
+
+fn outgoing_node_ids(node: &Node) -> Vec<String> {
+    declared_targets(node).into_iter().map(|(t, _)| t).collect()
+}
+
+fn find_reachable_nodes(graph: &Graph) -> HashSet<String> {
+    let mut reachable: HashSet<String> = HashSet::new();
+    let mut queue: VecDeque<String> = VecDeque::new();
+
+    if !graph.has_node(&graph.start) {
+        return reachable;
+    }
+
+    reachable.insert(graph.start.clone());
+    queue.push_back(graph.start.clone());
+
+    while let Some(id) = queue.pop_front() {
+        if let Some(node) = graph.get_node(&id) {
+            for next in outgoing_node_ids(node) {
+                if graph.has_node(&next) && reachable.insert(next.clone()) {
+                    queue.push_back(next);
+                }
+            }
+        }
+    }
+    reachable
+}
+
+// v1 parallel-group detection: only the immediate `next` targets of a fan-out node count as a parallel group. Map
+// branches are handled separately by `validate_map_branches` (the branch's self-parallelism is checked via strict-mode
+// rules on the branch node itself, not via group membership).
+//
+// Returns one HashSet per fan-out source; deeper transitive parallelism is intentionally out of scope for v1.
+fn compute_parallel_groups(graph: &Graph) -> Vec<HashSet<String>> {
+    let mut groups = Vec::new();
+    for node in graph.nodes.values() {
+        if let Some(targets) = &node.next
+            && targets.is_fan_out()
+        {
+            groups.push(targets.as_slice().iter().cloned().collect());
+        }
+    }
+    groups
+}
+
+// Computes the set of state keys this node can write to.
+//
+// Sources considered:
+//   - `state_updates` keys (every node type that has them)
+//   - `output_schema` top-level `properties` for `llm` and `agent` (auto-merge)
+fn write_set_of(node: &Node) -> Option<HashSet<String>> {
+    if matches!(node.node_type, NodeType::Script(_)) && node_state_updates_keys(node).is_none() {
+        return None;
+    }
+
+    let mut writes = HashSet::new();
+    if let Some(keys) = node_state_updates_keys(node) {
+        writes.extend(keys);
+    }
+
+    writes.extend(output_schema_top_level_keys(node));
+
+    Some(writes)
+}
+
+// Computes the set of root state keys this node's templated fields read from.
+//
+// "Root key" follows the same definition as `template_root_keys`: for a
+// reference like `{{user.name}}` or `{{items[0]}}`, the root is the bare
+// identifier before the first `.` or `[`.
+fn read_set_of(node: &Node) -> HashSet<String> {
+    let mut reads: HashSet<String> = HashSet::new();
+    let scoped: &[&str] = match &node.node_type {
+        NodeType::Llm(_) | NodeType::Agent(_) | NodeType::Rag(_) => &["output"],
+        NodeType::Approval(_) => &["choice"],
+        NodeType::Input(_) => &["input"],
+        NodeType::Script(_) | NodeType::End(_) | NodeType::Map(_) => &[],
+    };
+
+    for s in primary_templated_fields(node) {
+        for k in template_root_keys(&s) {
+            reads.insert(k);
+        }
+    }
+
+    if let Some(updates) = node_state_updates_map(node) {
+        for v in updates.values() {
+            for k in template_root_keys(v) {
+                if !scoped.contains(&k.as_str()) {
+                    reads.insert(k);
+                }
+            }
+        }
+    }
+
+    reads
+}
+
+fn primary_templated_fields(node: &Node) -> Vec<String> {
+    match &node.node_type {
+        NodeType::Llm(n) => {
+            let mut v = vec![n.prompt.clone()];
+            if let Some(i) = &n.instructions {
+                v.push(i.clone());
+            }
+            v
+        }
+        NodeType::Agent(n) => vec![n.prompt.clone()],
+        NodeType::Rag(n) => {
+            vec![
+                n.query
+                    .clone()
+                    .unwrap_or_else(|| "{{initial_prompt}}".to_string()),
+            ]
+        }
+        NodeType::Approval(n) => vec![n.question.clone()],
+        NodeType::Input(n) => {
+            let mut v = vec![n.question.clone()];
+            if let Some(d) = &n.default {
+                v.push(d.clone());
+            }
+            v
+        }
+        NodeType::End(n) => vec![n.output.clone()],
+        NodeType::Map(n) => vec![n.over.clone()],
+        NodeType::Script(_) => Vec::new(),
+    }
+}
+
+fn node_state_updates_map(node: &Node) -> Option<&std::collections::HashMap<String, String>> {
+    match &node.node_type {
+        NodeType::Llm(n) => n.state_updates.as_ref(),
+        NodeType::Agent(n) => n.state_updates.as_ref(),
+        NodeType::Rag(n) => n.state_updates.as_ref(),
+        NodeType::Approval(n) => n.state_updates.as_ref(),
+        NodeType::Input(n) => n.state_updates.as_ref(),
+        NodeType::Script(n) => n.state_updates.as_ref(),
+        NodeType::End(n) => n.state_updates.as_ref(),
+        NodeType::Map(_) => None,
+    }
+}
+
+fn node_state_updates_keys(node: &Node) -> Option<HashSet<String>> {
+    let updates = match &node.node_type {
+        NodeType::Agent(n) => n.state_updates.as_ref(),
+        NodeType::Script(n) => n.state_updates.as_ref(),
+        NodeType::Approval(n) => n.state_updates.as_ref(),
+        NodeType::Input(n) => n.state_updates.as_ref(),
+        NodeType::Llm(n) => n.state_updates.as_ref(),
+        NodeType::Rag(n) => n.state_updates.as_ref(),
+        NodeType::End(n) => n.state_updates.as_ref(),
+        NodeType::Map(_) => return None,
+    };
+    updates.map(|m| m.keys().cloned().collect())
+}
+
+fn output_schema_top_level_keys(node: &Node) -> HashSet<String> {
+    let schema = match &node.node_type {
+        NodeType::Agent(n) => n.output_schema.as_ref(),
+        NodeType::Llm(n) => n.output_schema.as_ref(),
+        _ => return HashSet::new(),
+    };
+    let Some(schema) = schema else {
+        return HashSet::new();
+    };
+    let Some(properties) = schema.get("properties").and_then(|p| p.as_object()) else {
+        return HashSet::new();
+    };
+    properties.keys().cloned().collect()
+}
+
+fn detect_cycle_dfs(
+    graph: &Graph,
+    node_id: &str,
+    visited: &mut HashSet<String>,
+    rec_stack: &mut HashSet<String>,
+    path: &mut Vec<String>,
+) -> Option<Vec<String>> {
+    visited.insert(node_id.to_string());
+    rec_stack.insert(node_id.to_string());
+    path.push(node_id.to_string());
+
+    if let Some(node) = graph.get_node(node_id) {
+        for next in outgoing_node_ids(node) {
+            if !graph.has_node(&next) {
+                continue;
+            }
+
+            if !visited.contains(&next) {
+                if let Some(cycle) = detect_cycle_dfs(graph, &next, visited, rec_stack, path) {
+                    return Some(cycle);
+                }
+            } else if rec_stack.contains(&next) {
+                let start = path.iter().position(|n| n == &next).unwrap_or(0);
+                let mut cycle: Vec<String> = path[start..].to_vec();
+                cycle.push(next.clone());
+                return Some(cycle);
+            }
+        }
+    }
+
+    path.pop();
+    rec_stack.remove(node_id);
+    None
+}
+
+#[cfg(test)]
+mod tests {
+    use super::super::types::*;
+    use super::*;
+    use indexmap::IndexMap;
+    use std::collections::HashMap;
+    use std::env;
+
+    fn graph_with(nodes: Vec<(&str, Node)>, start: &str) -> Graph {
+        let mut map: IndexMap<String, Node> = IndexMap::new();
+        for (id, node) in nodes {
+            map.insert(id.to_string(), node);
+        }
+
+        Graph {
+            name: "t".into(),
+            description: String::new(),
+            version: "1.0".into(),
+            model: None,
+            temperature: None,
+            top_p: None,
+            global_tools: Vec::new(),
+            mcp_servers: Vec::new(),
+            conversation_starters: Vec::new(),
+            variables: Vec::new(),
+            settings: GraphSettings::default(),
+            initial_state: HashMap::new(),
+            reducers: HashMap::new(),
+            start: start.into(),
+            nodes: map,
+        }
+    }
+
+    fn end_node(id: &str) -> Node {
+        Node {
+            id: id.into(),
+            description: String::new(),
+            node_type: NodeType::End(EndNode {
+                output: String::new(),
+                state_updates: None,
+            }),
+            next: None,
+        }
+    }
+
+    fn approval_node(id: &str, options: &[&str], routes: &[(&str, &str)], on_other: &str) -> Node {
+        let mut r: HashMap<String, String> = HashMap::new();
+        for (k, v) in routes {
+            r.insert((*k).into(), (*v).into());
+        }
+
+        Node {
+            id: id.into(),
+            description: String::new(),
+            node_type: NodeType::Approval(ApprovalNode {
+                question: "?".into(),
+                options: options.iter().map(|s| (*s).into()).collect(),
+                routes: r,
+                on_other: on_other.into(),
+                state_updates: None,
+            }),
+            next: None,
+        }
+    }
+
+    fn script_node(id: &str, script: &str, fallback: Option<&str>) -> Node {
+        Node {
+            id: id.into(),
+            description: String::new(),
+            node_type: NodeType::Script(ScriptNode {
+                script: script.into(),
+                state_updates: None,
+                fallback: fallback.map(String::from),
+                timeout: 30,
+            }),
+            next: None,
+        }
+    }
+
+    fn rag_node(id: &str, documents: &[&str], with_state_updates: bool) -> Node {
+        let state_updates = with_state_updates.then(|| {
+            let mut m: HashMap<String, String> = HashMap::new();
+            m.insert("ctx".into(), "{{output.context}}".into());
+            m
+        });
+
+        Node {
+            id: id.into(),
+            description: String::new(),
+            node_type: NodeType::Rag(RagNode {
+                documents: documents.iter().map(|s| (*s).into()).collect(),
+                query: None,
+                top_k: None,
+                embedding_model: None,
+                chunk_size: None,
+                chunk_overlap: None,
+                reranker_model: None,
+                batch_size: None,
+                state_updates,
+                timeout: None,
+            }),
+            next: Some("end".into()),
+        }
+    }
+
+    fn llm_node(id: &str, fallback: Option<&str>, next: Option<&str>) -> Node {
+        Node {
+            id: id.into(),
+            description: String::new(),
+            node_type: NodeType::Llm(LlmNode {
+                instructions: None,
+                prompt: "p".into(),
+                tools: None,
+                model: None,
+                temperature: None,
+                top_p: None,
+                fallback: fallback.map(String::from),
+                max_attempts: 1,
+                max_iterations: 10,
+                state_updates: None,
+                output_schema: None,
+                timeout: None,
+            }),
+            next: next.map(NextTargets::from),
+        }
+    }
+
+    #[test]
+    fn flags_missing_llm_fallback_target() {
+        let graph = graph_with(
+            vec![
+                ("l", llm_node("l", Some("ghost"), Some("end"))),
+                ("end", end_node("end")),
+            ],
+            "l",
+        );
+
+        let result = validator().validate(&graph);
+
+        assert!(!result.is_valid());
+        assert!(result.errors.iter().any(|e| e.message.contains("ghost")));
+    }
+
+    fn agent_ctx(tools: &[&str], mcp: &[&str]) -> AgentValidationContext {
+        AgentValidationContext {
+            tool_names: tools.iter().map(|s| s.to_string()).collect(),
+            mcp_servers: mcp.iter().map(|s| s.to_string()).collect(),
+            app_config: Arc::new(AppConfig::default()),
+        }
+    }
+
+    fn llm_node_with(id: &str, tools: Option<Vec<&str>>, model: Option<&str>) -> Node {
+        let mut node = llm_node(id, None, Some("end"));
+        if let NodeType::Llm(ref mut n) = node.node_type {
+            n.tools = tools.map(|t| t.iter().map(|s| s.to_string()).collect());
+            n.model = model.map(String::from);
+        }
+
+        node
+    }
+
+    #[test]
+    fn llm_node_unknown_tool_is_an_error() {
+        let graph = graph_with(
+            vec![
+                ("l", llm_node_with("l", Some(vec!["bogus_tool"]), None)),
+                ("end", end_node("end")),
+            ],
+            "l",
+        );
+
+        let result = validator()
+            .with_agent_context(agent_ctx(&["read_query"], &[]))
+            .validate(&graph);
+
+        assert!(!result.is_valid());
+        assert!(
+            result
+                .errors
+                .iter()
+                .any(|e| e.message.contains("bogus_tool"))
+        );
+    }
+
+    #[test]
+    fn llm_node_known_tool_passes() {
+        let graph = graph_with(
+            vec![
+                ("l", llm_node_with("l", Some(vec!["read_query"]), None)),
+                ("end", end_node("end")),
+            ],
+            "l",
+        );
+
+        let result = validator()
+            .with_agent_context(agent_ctx(&["read_query"], &[]))
+            .validate(&graph);
+
+        assert!(result.is_valid());
+    }
+
+    #[test]
+    fn llm_node_unknown_mcp_server_is_an_error() {
+        let graph = graph_with(
+            vec![
+                ("l", llm_node_with("l", Some(vec!["mcp:bogus"]), None)),
+                ("end", end_node("end")),
+            ],
+            "l",
+        );
+
+        let result = validator()
+            .with_agent_context(agent_ctx(&[], &["pubmed-search"]))
+            .validate(&graph);
+
+        assert!(!result.is_valid());
+        assert!(
+            result
+                .errors
+                .iter()
+                .any(|e| e.message.contains("mcp:bogus"))
+        );
+    }
+
+    #[test]
+    fn llm_node_known_mcp_server_passes() {
+        let graph = graph_with(
+            vec![
+                (
+                    "l",
+                    llm_node_with("l", Some(vec!["mcp:pubmed-search"]), None),
+                ),
+                ("end", end_node("end")),
+            ],
+            "l",
+        );
+
+        let result = validator()
+            .with_agent_context(agent_ctx(&[], &["pubmed-search"]))
+            .validate(&graph);
+
+        assert!(result.is_valid());
+    }
+
+    #[test]
+    fn llm_node_unknown_model_is_an_error() {
+        let graph = graph_with(
+            vec![
+                ("l", llm_node_with("l", None, Some("nonexistent:model"))),
+                ("end", end_node("end")),
+            ],
+            "l",
+        );
+
+        let result = validator()
+            .with_agent_context(agent_ctx(&[], &[]))
+            .validate(&graph);
+
+        assert!(!result.is_valid());
+        assert!(
+            result
+                .errors
+                .iter()
+                .any(|e| e.message.contains("nonexistent:model"))
+        );
+    }
+
+    #[test]
+    fn llm_node_validation_skipped_without_agent_context() {
+        let graph = graph_with(
+            vec![
+                ("l", llm_node_with("l", Some(vec!["bogus_tool"]), None)),
+                ("end", end_node("end")),
+            ],
+            "l",
+        );
+
+        let result = validator().validate(&graph);
+
+        assert!(result.is_valid());
+    }
+
+    #[test]
+    fn rag_node_without_documents_errors() {
+        let graph = graph_with(
+            vec![("r", rag_node("r", &[], true)), ("end", end_node("end"))],
+            "r",
+        );
+
+        let result = validator().validate(&graph);
+
+        assert!(!result.is_valid());
+        assert!(
+            result
+                .errors
+                .iter()
+                .any(|e| e.message.contains("no 'documents'") && e.node_id.as_deref() == Some("r"))
+        );
+    }
+
+    #[test]
+    fn rag_node_without_state_updates_warns() {
+        let graph = graph_with(
+            vec![
+                ("r", rag_node("r", &["./docs"], false)),
+                ("end", end_node("end")),
+            ],
+            "r",
+        );
+
+        let result = validator().validate(&graph);
+
+        assert!(result.is_valid());
+        assert!(
+            result
+                .warnings
+                .iter()
+                .any(|w| w.message.contains("no 'state_updates'"))
+        );
+    }
+
+    #[test]
+    fn valid_rag_node_produces_no_findings() {
+        let graph = graph_with(
+            vec![
+                ("r", rag_node("r", &["./docs"], true)),
+                ("end", end_node("end")),
+            ],
+            "r",
+        );
+
+        let result = validator().validate(&graph);
+
+        assert!(result.is_valid());
+        assert!(
+            !result
+                .warnings
+                .iter()
+                .any(|w| w.message.contains("RAG node"))
+        );
+    }
+
+    fn agent_node(id: &str, agent: &str, next: Option<&str>) -> Node {
+        Node {
+            id: id.into(),
+            description: String::new(),
+            node_type: NodeType::Agent(AgentNode {
+                agent: agent.into(),
+                prompt: "hi".into(),
+                state_updates: None,
+                output_schema: None,
+                timeout: None,
+            }),
+            next: next.map(NextTargets::from),
+        }
+    }
+
+    fn validator() -> GraphValidator {
+        GraphValidator::new(env::current_dir().unwrap())
+    }
+
+    #[test]
+    fn valid_simple_graph_passes() {
+        let mut start = end_node("start");
+        start.next = Some("end".into());
+        let graph = graph_with(vec![("start", start), ("end", end_node("end"))], "start");
+
+        let result = validator().validate(&graph);
+
+        assert!(result.is_valid(), "errors: {:?}", result.errors);
+    }
+
+    #[test]
+    fn flags_missing_node_reference_in_next() {
+        let mut n = end_node("n1");
+        n.next = Some("nope".into());
+        let graph = graph_with(vec![("n1", n), ("end", end_node("end"))], "n1");
+
+        let result = validator().validate(&graph);
+
+        assert!(!result.is_valid());
+        assert!(
+            result
+                .errors
+                .iter()
+                .any(|e| e.message.contains("non-existent node 'nope'")
+                    && e.node_id.as_deref() == Some("n1"))
+        );
+    }
+
+    #[test]
+    fn flags_missing_approval_route_target() {
+        let approval = approval_node(
+            "ap",
+            &["yes", "no"],
+            &[("yes", "end"), ("no", "missing")],
+            "end",
+        );
+        let graph = graph_with(vec![("ap", approval), ("end", end_node("end"))], "ap");
+
+        let result = validator().validate(&graph);
+
+        assert!(!result.is_valid());
+        assert!(
+            result
+                .errors
+                .iter()
+                .any(|e| e.message.contains("non-existent node 'missing'"))
+        );
+    }
+
+    #[test]
+    fn flags_missing_approval_on_other_target() {
+        let approval = approval_node("ap", &["yes"], &[("yes", "end")], "missing");
+        let graph = graph_with(vec![("ap", approval), ("end", end_node("end"))], "ap");
+
+        let result = validator().validate(&graph);
+
+        assert!(!result.is_valid());
+        assert!(
+            result
+                .errors
+                .iter()
+                .any(|e| e.message.contains("non-existent node 'missing'")
+                    && e.message.contains("on_other"))
+        );
+    }
+
+    #[test]
+    fn flags_missing_script_fallback_target() {
+        let scr = script_node("s", "does-not-exist.py", Some("nowhere"));
+        let graph = graph_with(vec![("s", scr), ("end", end_node("end"))], "s");
+
+        let result = validator().validate(&graph);
+
+        assert!(
+            result
+                .errors
+                .iter()
+                .any(|e| e.message.contains("non-existent node 'nowhere'"))
+        );
+    }
+
+    #[test]
+    fn detects_two_node_cycle() {
+        let mut a = end_node("a");
+        a.next = Some("b".into());
+        let mut b = end_node("b");
+        b.next = Some("a".into());
+        let graph = graph_with(vec![("a", a), ("b", b)], "a");
+
+        let result = validator().validate(&graph);
+
+        assert!(!result.is_valid());
+        assert!(
+            result
+                .errors
+                .iter()
+                .any(|e| e.message.contains("Cycle detected"))
+        );
+    }
+
+    #[test]
+    fn detects_self_loop_as_cycle() {
+        let mut a = end_node("a");
+        a.next = Some("a".into());
+        let graph = graph_with(vec![("a", a)], "a");
+
+        let result = validator().validate(&graph);
+
+        assert!(
+            result
+                .errors
+                .iter()
+                .any(|e| e.message.contains("Cycle detected"))
+        );
+    }
+
+    #[test]
+    fn warns_on_unreachable_node() {
+        let graph = graph_with(
+            vec![("start", end_node("start")), ("orphan", end_node("orphan"))],
+            "start",
+        );
+
+        let result = validator().validate(&graph);
+
+        assert!(
+            result.warnings.iter().any(
+                |w| w.node_id.as_deref() == Some("orphan") && w.message.contains("unreachable")
+            )
+        );
+    }
+
+    #[test]
+    fn errors_when_graph_has_no_end_node_at_all() {
+        let mut a = agent_node("a", "__no_such_agent__", Some("b"));
+        let b = agent_node("b", "__no_such_agent__", None);
+        a.next = Some("b".into());
+        let graph = graph_with(vec![("a", a), ("b", b)], "a");
+
+        let result = validator().validate(&graph);
+
+        assert!(
+            result
+                .errors
+                .iter()
+                .any(|e| e.message.contains("no end nodes")),
+            "errors: {:?}",
+            result.errors
+        );
+    }
+
+    #[test]
+    fn warns_when_end_exists_but_not_reachable() {
+        let start = Node {
+            id: "start".into(),
+            description: String::new(),
+            node_type: NodeType::Input(InputNode {
+                question: "?".into(),
+                default: None,
+                validation: None,
+                state_updates: None,
+            }),
+            next: None,
+        };
+        let graph = graph_with(
+            vec![("start", start), ("orphan_end", end_node("orphan_end"))],
+            "start",
+        );
+
+        let result = validator().validate(&graph);
+
+        assert!(result.is_valid(), "unexpected errors: {:?}", result.errors);
+        assert!(
+            result
+                .warnings
+                .iter()
+                .any(|w| w.message.contains("No end node is reachable"))
+        );
+    }
+
+    #[test]
+    fn errors_when_script_file_missing() {
+        let scr = script_node("s", "definitely-not-here.py", None);
+        let mut start = end_node("start");
+        start.next = Some("s".into());
+        let graph = graph_with(
+            vec![("start", start), ("s", scr), ("end", end_node("end"))],
+            "start",
+        );
+
+        let result = validator().validate(&graph);
+
+        assert!(
+            result
+                .errors
+                .iter()
+                .any(|e| e.message.contains("Script file not found")
+                    && e.node_id.as_deref() == Some("s"))
+        );
+    }
+
+    #[test]
+    fn errors_when_referenced_agent_missing() {
+        let agent = agent_node("a", "__definitely_no_such_agent__", Some("end"));
+        let graph = graph_with(vec![("a", agent), ("end", end_node("end"))], "a");
+
+        let result = validator().validate(&graph);
+
+        assert!(result.errors.iter().any(|e| {
+            e.message
+                .contains("Agent '__definitely_no_such_agent__' not found")
+        }));
+    }
+
+    #[test]
+    fn errors_when_approval_option_has_no_route() {
+        let approval = approval_node("ap", &["yes", "no"], &[("yes", "end")], "end");
+        let graph = graph_with(vec![("ap", approval), ("end", end_node("end"))], "ap");
+
+        let result = validator().validate(&graph);
+
+        assert!(
+            result
+                .errors
+                .iter()
+                .any(|e| e.message.contains("'no' has no route defined"))
+        );
+    }
+
+    #[test]
+    fn warns_when_approval_has_extra_route() {
+        let approval = approval_node("ap", &["yes"], &[("yes", "end"), ("maybe", "end")], "end");
+        let graph = graph_with(vec![("ap", approval), ("end", end_node("end"))], "ap");
+
+        let result = validator().validate(&graph);
+
+        assert!(result.warnings.iter().any(|w| {
+            w.message
+                .contains("Route 'maybe' has no corresponding option")
+        }));
+    }
+
+    #[test]
+    fn into_result_aggregates_all_errors() {
+        let mut a = end_node("a");
+        a.next = Some("missing1".into());
+        let mut b = end_node("b");
+        b.next = Some("missing2".into());
+        let graph = graph_with(vec![("a", a), ("b", b)], "a");
+
+        let err = validator()
+            .validate(&graph)
+            .into_result()
+            .unwrap_err()
+            .to_string();
+
+        assert!(err.contains("missing1"), "got: {err}");
+        assert!(err.contains("missing2"), "got: {err}");
+        assert!(err.contains("validation failed"), "got: {err}");
+    }
+
+    #[test]
+    fn into_result_returns_ok_when_no_errors() {
+        let mut start = end_node("start");
+        start.next = Some("end".into());
+
+        let graph = graph_with(vec![("start", start), ("end", end_node("end"))], "start");
+
+        assert!(validator().validate(&graph).into_result().is_ok());
+    }
+
+    #[test]
+    fn cycle_detector_treats_fan_out_diamond_as_a_valid_dag() {
+        let mut start = end_node("start");
+        start.next = Some(NextTargets::Many(vec!["a".into(), "b".into()]));
+        let mut a = end_node("a");
+        a.next = Some("join".into());
+        let mut b = end_node("b");
+        b.next = Some("join".into());
+        let mut join = end_node("join");
+        join.next = Some("end".into());
+
+        let graph = graph_with(
+            vec![
+                ("start", start),
+                ("a", a),
+                ("b", b),
+                ("join", join),
+                ("end", end_node("end")),
+            ],
+            "start",
+        );
+
+        let result = validator().validate(&graph);
+        assert!(
+            !result
+                .errors
+                .iter()
+                .any(|e| e.message.contains("Cycle detected")),
+            "fan-out diamond incorrectly reported as cycle: {:?}",
+            result.errors
+        );
+    }
+
+    #[test]
+    fn reachability_visits_every_member_of_many_next_targets() {
+        let mut start = end_node("start");
+        start.next = Some(NextTargets::Many(vec!["a".into(), "b".into(), "c".into()]));
+        let graph = graph_with(
+            vec![
+                ("start", start),
+                ("a", end_node("a")),
+                ("b", end_node("b")),
+                ("c", end_node("c")),
+            ],
+            "start",
+        );
+
+        let result = validator().validate(&graph);
+
+        for orphan in ["a", "b", "c"] {
+            assert!(
+                !result
+                    .warnings
+                    .iter()
+                    .any(|w| w.node_id.as_deref() == Some(orphan)
+                        && w.message.contains("unreachable")),
+                "fan-out target '{orphan}' incorrectly marked unreachable: {:?}",
+                result.warnings
+            );
+        }
+    }
+
+    #[test]
+    fn node_reference_check_catches_missing_member_inside_many() {
+        let mut start = end_node("start");
+        start.next = Some(NextTargets::Many(vec!["a".into(), "ghost".into()]));
+        let graph = graph_with(vec![("start", start), ("a", end_node("a"))], "start");
+
+        let result = validator().validate(&graph);
+
+        assert!(
+            result
+                .errors
+                .iter()
+                .any(|e| e.message.contains("non-existent node 'ghost'")
+                    && e.node_id.as_deref() == Some("start")),
+            "expected error for missing 'ghost' target in Many: {:?}",
+            result.errors
+        );
+    }
+
+    #[test]
+    fn node_reference_check_catches_missing_map_branch_target() {
+        let map = Node {
+            id: "fan".into(),
+            description: String::new(),
+            node_type: NodeType::Map(MapNode {
+                over: "{{items}}".into(),
+                as_name: "item".into(),
+                branch: "no_such_node".into(),
+                output_key: "output".into(),
+                collect_into: "results".into(),
+                max_concurrency: None,
+            }),
+            next: Some("end".into()),
+        };
+        let graph = graph_with(vec![("fan", map), ("end", end_node("end"))], "fan");
+
+        let result = validator().validate(&graph);
+        assert!(
+            result
+                .errors
+                .iter()
+                .any(|e| e.message.contains("non-existent node 'no_such_node'")
+                    && e.message.contains("map 'branch'")),
+            "expected error for missing map branch: {:?}",
+            result.errors
+        );
+    }
+
+    fn map_node_basic(id: &str, branch: &str, next: Option<&str>) -> Node {
+        Node {
+            id: id.into(),
+            description: String::new(),
+            node_type: NodeType::Map(MapNode {
+                over: "{{items}}".into(),
+                as_name: "item".into(),
+                branch: branch.into(),
+                output_key: "output".into(),
+                collect_into: "results".into(),
+                max_concurrency: None,
+            }),
+            next: next.map(NextTargets::from),
+        }
+    }
+
+    fn llm_with_state_updates(id: &str, updates: &[(&str, &str)], next: Option<&str>) -> Node {
+        let mut node = llm_node(id, None, next);
+        if let NodeType::Llm(ref mut n) = node.node_type {
+            let mut map: HashMap<String, String> = HashMap::new();
+            for (k, v) in updates {
+                map.insert((*k).into(), (*v).into());
+            }
+            n.state_updates = Some(map);
+        }
+        node
+    }
+
+    fn llm_with_output_schema(id: &str, properties: &[&str], next: Option<&str>) -> Node {
+        let mut node = llm_node(id, None, next);
+        if let NodeType::Llm(ref mut n) = node.node_type {
+            let mut props = serde_json::Map::new();
+            for k in properties {
+                props.insert((*k).to_string(), serde_json::json!({ "type": "string" }));
+            }
+            n.output_schema = Some(serde_json::json!({
+                "type": "object",
+                "properties": props,
+            }));
+        }
+        node
+    }
+
+    fn script_with_state_updates(id: &str, updates: &[(&str, &str)]) -> Node {
+        let mut node = script_node(id, "Cargo.toml", None);
+        if let NodeType::Script(ref mut n) = node.node_type {
+            let mut map: HashMap<String, String> = HashMap::new();
+            for (k, v) in updates {
+                map.insert((*k).into(), (*v).into());
+            }
+            n.state_updates = Some(map);
+        }
+        node
+    }
+
+    fn fan_out_graph_with_two_workers(worker_a: Node, worker_b: Node) -> Graph {
+        let mut start = end_node("start");
+        start.next = Some(NextTargets::Many(vec![
+            "worker_a".into(),
+            "worker_b".into(),
+        ]));
+        graph_with(
+            vec![
+                ("start", start),
+                ("worker_a", worker_a),
+                ("worker_b", worker_b),
+                ("end", end_node("end")),
+            ],
+            "start",
+        )
+    }
+
+    #[test]
+    fn parallel_writes_to_same_key_without_reducer_errors() {
+        let a = llm_with_state_updates("worker_a", &[("summary", "{{output}}")], Some("end"));
+        let b = llm_with_state_updates("worker_b", &[("summary", "{{output}}")], Some("end"));
+        let graph = fan_out_graph_with_two_workers(a, b);
+
+        let result = validator().validate(&graph);
+
+        assert!(
+            result.errors.iter().any(|e| e
+                .message
+                .contains("nodes [worker_a, worker_b] all write key 'summary'")),
+            "expected reducer-collision error for `summary`: {:?}",
+            result.errors
+        );
+    }
+
+    #[test]
+    fn parallel_writes_to_same_key_with_reducer_pass() {
+        let a = llm_with_state_updates("worker_a", &[("summary", "{{output}}")], Some("end"));
+        let b = llm_with_state_updates("worker_b", &[("summary", "{{output}}")], Some("end"));
+        let mut graph = fan_out_graph_with_two_workers(a, b);
+        graph.reducers.insert("summary".into(), Reducer::Concat);
+
+        let result = validator().validate(&graph);
+
+        assert!(
+            !result
+                .errors
+                .iter()
+                .any(|e| e.message.contains("no reducer is declared")),
+            "expected no reducer-collision error when reducer is declared: {:?}",
+            result.errors
+        );
+    }
+
+    #[test]
+    fn parallel_writes_to_disjoint_keys_pass() {
+        let a = llm_with_state_updates("worker_a", &[("a_out", "{{output}}")], Some("end"));
+        let b = llm_with_state_updates("worker_b", &[("b_out", "{{output}}")], Some("end"));
+        let graph = fan_out_graph_with_two_workers(a, b);
+
+        let result = validator().validate(&graph);
+
+        assert!(
+            !result
+                .errors
+                .iter()
+                .any(|e| e.message.contains("no reducer is declared")),
+            "expected no collision for disjoint keys: {:?}",
+            result.errors
+        );
+    }
+
+    #[test]
+    fn output_schema_top_level_keys_count_as_parallel_writes() {
+        let a = llm_with_output_schema("worker_a", &["summary"], Some("end"));
+        let b = llm_with_output_schema("worker_b", &["summary"], Some("end"));
+        let graph = fan_out_graph_with_two_workers(a, b);
+
+        let result = validator().validate(&graph);
+
+        assert!(
+            result.errors.iter().any(|e| e
+                .message
+                .contains("nodes [worker_a, worker_b] all write key 'summary'")),
+            "output_schema top-level keys should count as writes: {:?}",
+            result.errors
+        );
+    }
+
+    #[test]
+    fn three_parallel_writers_collision_lists_all_writers() {
+        let mut start = end_node("start");
+        start.next = Some(NextTargets::Many(vec!["a".into(), "b".into(), "c".into()]));
+        let graph = graph_with(
+            vec![
+                ("start", start),
+                (
+                    "a",
+                    llm_with_state_updates("a", &[("k", "{{output}}")], Some("end")),
+                ),
+                (
+                    "b",
+                    llm_with_state_updates("b", &[("k", "{{output}}")], Some("end")),
+                ),
+                (
+                    "c",
+                    llm_with_state_updates("c", &[("k", "{{output}}")], Some("end")),
+                ),
+                ("end", end_node("end")),
+            ],
+            "start",
+        );
+
+        let result = validator().validate(&graph);
+
+        assert!(
+            result
+                .errors
+                .iter()
+                .any(|e| e.message.contains("nodes [a, b, c]") && e.message.contains("'k'")),
+            "expected error listing all three writers a, b, c: {:?}",
+            result.errors
+        );
+    }
+
+    #[test]
+    fn approval_node_as_immediate_fan_out_target_errors() {
+        let approval = approval_node("ap", &["yes"], &[("yes", "end")], "end");
+        let other = end_node("other");
+        let mut start = end_node("start");
+        start.next = Some(NextTargets::Many(vec!["ap".into(), "other".into()]));
+        let graph = graph_with(
+            vec![
+                ("start", start),
+                ("ap", approval),
+                ("other", other),
+                ("end", end_node("end")),
+            ],
+            "start",
+        );
+
+        let result = validator().validate(&graph);
+
+        assert!(
+            result
+                .errors
+                .iter()
+                .any(|e| e.message.contains("approval node")
+                    && e.message.contains("fan-out")
+                    && e.node_id.as_deref() == Some("ap")),
+            "expected approval-in-fan-out error: {:?}",
+            result.errors
+        );
+    }
+
+    #[test]
+    fn input_node_as_immediate_fan_out_target_errors() {
+        let input = Node {
+            id: "in".into(),
+            description: String::new(),
+            node_type: NodeType::Input(InputNode {
+                question: "?".into(),
+                default: None,
+                validation: None,
+                state_updates: None,
+            }),
+            next: Some("end".into()),
+        };
+        let other = end_node("other");
+        let mut start = end_node("start");
+        start.next = Some(NextTargets::Many(vec!["in".into(), "other".into()]));
+        let graph = graph_with(
+            vec![
+                ("start", start),
+                ("in", input),
+                ("other", other),
+                ("end", end_node("end")),
+            ],
+            "start",
+        );
+
+        let result = validator().validate(&graph);
+
+        assert!(
+            result
+                .errors
+                .iter()
+                .any(|e| e.message.contains("input node")
+                    && e.message.contains("fan-out")
+                    && e.node_id.as_deref() == Some("in")),
+            "expected input-in-fan-out error: {:?}",
+            result.errors
+        );
+    }
+
+    #[test]
+    fn approval_after_join_passes() {
+        let mut start = end_node("start");
+        start.next = Some(NextTargets::Many(vec!["a".into(), "b".into()]));
+        let mut a = end_node("a");
+        a.next = Some("ap".into());
+        let mut b = end_node("b");
+        b.next = Some("ap".into());
+        let approval = approval_node("ap", &["yes"], &[("yes", "end")], "end");
+        let graph = graph_with(
+            vec![
+                ("start", start),
+                ("a", a),
+                ("b", b),
+                ("ap", approval),
+                ("end", end_node("end")),
+            ],
+            "start",
+        );
+
+        let result = validator().validate(&graph);
+
+        assert!(
+            !result
+                .errors
+                .iter()
+                .any(|e| e.message.contains("fan-out") && e.node_id.as_deref() == Some("ap")),
+            "approval AFTER join should be fine (v1 only checks immediate successors): {:?}",
+            result.errors
+        );
+    }
+
+    #[test]
+    fn map_branch_cannot_be_approval() {
+        let map = map_node_basic("m", "br", Some("end"));
+        let branch = approval_node("br", &["yes"], &[("yes", "end")], "end");
+        let graph = graph_with(
+            vec![("m", map), ("br", branch), ("end", end_node("end"))],
+            "m",
+        );
+
+        let result = validator().validate(&graph);
+
+        assert!(
+            result
+                .errors
+                .iter()
+                .any(|e| e.message.contains("approval node")
+                    && e.message.contains("map branch")
+                    && e.node_id.as_deref() == Some("m")),
+            "expected map-branch-is-approval error: {:?}",
+            result.errors
+        );
+    }
+
+    #[test]
+    fn map_branch_cannot_be_input() {
+        let map = map_node_basic("m", "br", Some("end"));
+        let branch = Node {
+            id: "br".into(),
+            description: String::new(),
+            node_type: NodeType::Input(InputNode {
+                question: "?".into(),
+                default: None,
+                validation: None,
+                state_updates: None,
+            }),
+            next: Some("end".into()),
+        };
+        let graph = graph_with(
+            vec![("m", map), ("br", branch), ("end", end_node("end"))],
+            "m",
+        );
+
+        let result = validator().validate(&graph);
+
+        assert!(
+            result
+                .errors
+                .iter()
+                .any(|e| e.message.contains("input node")
+                    && e.message.contains("map branch")
+                    && e.node_id.as_deref() == Some("m")),
+            "expected map-branch-is-input error: {:?}",
+            result.errors
+        );
+    }
+
+    #[test]
+    fn map_branch_cannot_be_end() {
+        let map = map_node_basic("m", "br", Some("done"));
+        let graph = graph_with(
+            vec![
+                ("m", map),
+                ("br", end_node("br")),
+                ("done", end_node("done")),
+            ],
+            "m",
+        );
+
+        let result = validator().validate(&graph);
+
+        assert!(
+            result.errors.iter().any(|e| e.message.contains("end node")
+                && e.message.contains("collect mechanism")
+                && e.node_id.as_deref() == Some("m")),
+            "expected map-branch-is-end error: {:?}",
+            result.errors
+        );
+    }
+
+    #[test]
+    fn map_branch_cannot_be_another_map() {
+        let outer = map_node_basic("outer", "inner", Some("end"));
+        let inner = map_node_basic("inner", "end", Some("end"));
+        let graph = graph_with(
+            vec![("outer", outer), ("inner", inner), ("end", end_node("end"))],
+            "outer",
+        );
+
+        let result = validator().validate(&graph);
+
+        assert!(
+            result
+                .errors
+                .iter()
+                .any(|e| e.message.contains("itself a map node")
+                    && e.node_id.as_deref() == Some("outer")),
+            "expected nested-map error: {:?}",
+            result.errors
+        );
+    }
+
+    #[test]
+    fn map_branch_cannot_have_next_declared() {
+        let map = map_node_basic("m", "br", Some("end"));
+        let branch = llm_with_state_updates("br", &[("output", "{{output}}")], Some("somewhere"));
+        let graph = graph_with(
+            vec![
+                ("m", map),
+                ("br", branch),
+                ("somewhere", end_node("somewhere")),
+                ("end", end_node("end")),
+            ],
+            "m",
+        );
+
+        let result = validator().validate(&graph);
+
+        assert!(
+            result
+                .errors
+                .iter()
+                .any(|e| e.message.contains("has a `next` declared")
+                    && e.message.contains("atomic")
+                    && e.node_id.as_deref() == Some("br")),
+            "expected branch-has-next error: {:?}",
+            result.errors
+        );
+    }
+
+    #[test]
+    fn map_branch_state_updates_matching_output_key_passes() {
+        let map = map_node_basic("m", "br", Some("end"));
+        let branch = llm_with_state_updates("br", &[("output", "{{output}}")], None);
+        let graph = graph_with(
+            vec![("m", map), ("br", branch), ("end", end_node("end"))],
+            "m",
+        );
+
+        let result = validator().validate(&graph);
+
+        assert!(
+            !result.errors.iter().any(|e| e
+                .message
+                .contains("map branches may only write through their `output_key`")),
+            "valid map branch should not error on writes: {:?}",
+            result.errors
+        );
+    }
+
+    #[test]
+    fn map_branch_state_updates_wrong_key_errors() {
+        let map = map_node_basic("m", "br", Some("end"));
+        let branch = llm_with_state_updates("br", &[("not_output", "{{output}}")], None);
+        let graph = graph_with(
+            vec![("m", map), ("br", branch), ("end", end_node("end"))],
+            "m",
+        );
+
+        let result = validator().validate(&graph);
+
+        assert!(
+            result
+                .errors
+                .iter()
+                .any(|e| e.message.contains("writes state key 'not_output'")
+                    && e.message.contains("'output'")
+                    && e.node_id.as_deref() == Some("br")),
+            "expected wrong-key error: {:?}",
+            result.errors
+        );
+    }
+
+    #[test]
+    fn map_branch_with_output_schema_errors() {
+        let map = map_node_basic("m", "br", Some("end"));
+        let branch = llm_with_output_schema("br", &["foo", "bar"], None);
+        let graph = graph_with(
+            vec![("m", map), ("br", branch), ("end", end_node("end"))],
+            "m",
+        );
+
+        let result = validator().validate(&graph);
+
+        assert!(
+            result
+                .errors
+                .iter()
+                .any(|e| e.message.contains("output_schema")
+                    && e.message.contains("top-level properties")
+                    && e.node_id.as_deref() == Some("br")),
+            "expected output_schema-forbidden error: {:?}",
+            result.errors
+        );
+    }
+
+    #[test]
+    fn script_in_fan_out_without_state_updates_errors() {
+        let a = script_node("worker_a", "Cargo.toml", None);
+        let b = end_node("worker_b");
+        let graph = fan_out_graph_with_two_workers(a, b);
+
+        let result = validator().validate(&graph);
+
+        assert!(
+            result.errors.iter().any(
+                |e| e.message.contains("script node is in a parallel branch")
+                    && e.message.contains("no `state_updates`")
+                    && e.node_id.as_deref() == Some("worker_a")
+            ),
+            "expected script-no-state-updates-in-parallel error: {:?}",
+            result.errors
+        );
+    }
+
+    #[test]
+    fn script_in_fan_out_with_state_updates_passes() {
+        let a = script_with_state_updates("worker_a", &[("result_a", "{{output.x}}")]);
+        let b = end_node("worker_b");
+        let graph = fan_out_graph_with_two_workers(a, b);
+
+        let result = validator().validate(&graph);
+
+        assert!(
+            !result
+                .errors
+                .iter()
+                .any(|e| e.message.contains("script node is in a parallel branch")),
+            "script with state_updates should pass C.6: {:?}",
+            result.errors
+        );
+    }
+
+    #[test]
+    fn script_outside_fan_out_without_state_updates_passes() {
+        let mut start = end_node("start");
+        start.next = Some("s".into());
+        let s = script_node("s", "Cargo.toml", None);
+        let graph = graph_with(
+            vec![("start", start), ("s", s), ("end", end_node("end"))],
+            "start",
+        );
+
+        let result = validator().validate(&graph);
+
+        assert!(
+            !result
+                .errors
+                .iter()
+                .any(|e| e.message.contains("parallel branch")),
+            "script outside fan-out should not trigger C.6: {:?}",
+            result.errors
+        );
+    }
+
+    #[test]
+    fn settings_max_concurrency_zero_errors() {
+        let mut graph = graph_with(vec![("e", end_node("e"))], "e");
+        graph.settings.max_concurrency = 0;
+
+        let result = validator().validate(&graph);
+
+        assert!(
+            result
+                .errors
+                .iter()
+                .any(|e| e.message.contains("settings.max_concurrency must be >= 1")),
+            "expected graph-level max_concurrency=0 error: {:?}",
+            result.errors
+        );
+    }
+
+    #[test]
+    fn settings_max_concurrency_default_is_valid() {
+        let graph = graph_with(vec![("e", end_node("e"))], "e");
+
+        let result = validator().validate(&graph);
+
+        assert!(
+            !result
+                .errors
+                .iter()
+                .any(|e| e.message.contains("max_concurrency")),
+            "default max_concurrency should not error: {:?}",
+            result.errors
+        );
+    }
+
+    #[test]
+    fn map_max_concurrency_zero_errors() {
+        let mut map = map_node_basic("m", "br", Some("end"));
+        if let NodeType::Map(ref mut mm) = map.node_type {
+            mm.max_concurrency = Some(0);
+        }
+        let branch = llm_with_state_updates("br", &[("output", "{{output}}")], None);
+        let graph = graph_with(
+            vec![("m", map), ("br", branch), ("end", end_node("end"))],
+            "m",
+        );
+
+        let result = validator().validate(&graph);
+
+        assert!(
+            result.errors.iter().any(|e| e
+                .message
+                .contains("map node's `max_concurrency` must be >= 1")
+                && e.node_id.as_deref() == Some("m")),
+            "expected map max_concurrency=0 error: {:?}",
+            result.errors
+        );
+    }
+
+    #[test]
+    fn map_max_concurrency_none_is_valid() {
+        let map = map_node_basic("m", "br", Some("end"));
+        let branch = llm_with_state_updates("br", &[("output", "{{output}}")], None);
+        let graph = graph_with(
+            vec![("m", map), ("br", branch), ("end", end_node("end"))],
+            "m",
+        );
+
+        let result = validator().validate(&graph);
+
+        assert!(
+            !result
+                .errors
+                .iter()
+                .any(|e| e.message.contains("max_concurrency")),
+            "map without max_concurrency should not error: {:?}",
+            result.errors
+        );
+    }
+
+    fn llm_with_prompt(id: &str, prompt: &str, next: Option<&str>) -> Node {
+        let mut node = llm_node(id, None, next);
+        if let NodeType::Llm(ref mut n) = node.node_type {
+            n.prompt = prompt.into();
+        }
+        node
+    }
+
+    #[test]
+    fn parallel_read_of_sibling_write_errors() {
+        let reader = llm_with_prompt("worker_a", "Hello {{summary}}!", Some("end"));
+        let writer = llm_with_state_updates("worker_b", &[("summary", "static")], Some("end"));
+        let graph = fan_out_graph_with_two_workers(reader, writer);
+
+        let result = validator().validate(&graph);
+
+        assert!(
+            result
+                .errors
+                .iter()
+                .any(|e| e.message.contains("reads state key(s) `summary`")
+                    && e.message.contains("'worker_b'")),
+            "expected cross-branch read error mentioning `summary` and sibling writer: {:?}",
+            result.errors
+        );
+    }
+
+    #[test]
+    fn parallel_read_of_upstream_key_passes() {
+        let reader_a = llm_with_prompt("worker_a", "Topic is {{topic}}", Some("end"));
+        let reader_b = llm_with_prompt("worker_b", "Also {{topic}}", Some("end"));
+        let graph = fan_out_graph_with_two_workers(reader_a, reader_b);
+
+        let result = validator().validate(&graph);
+
+        assert!(
+            !result
+                .errors
+                .iter()
+                .any(|e| e.message.contains("reads state key")),
+            "upstream `topic` shouldn't trigger cross-branch read error: {:?}",
+            result.errors
+        );
+    }
+
+    #[test]
+    fn scoped_output_var_in_state_updates_not_treated_as_read() {
+        let scoped_user =
+            llm_with_state_updates("worker_a", &[("a_key", "{{output}}")], Some("end"));
+        let writes_output =
+            llm_with_state_updates("worker_b", &[("output", "{{output}}")], Some("end"));
+        let graph = fan_out_graph_with_two_workers(scoped_user, writes_output);
+
+        let result = validator().validate(&graph);
+
+        assert!(
+            !result
+                .errors
+                .iter()
+                .any(|e| e.message.contains("reads state key(s) `output`")
+                    && e.message.contains("worker_a")),
+            "scoped `{{{{output}}}}` inside state_updates value should NOT be treated as a read: {:?}",
+            result.errors
+        );
+    }
+
+    #[test]
+    fn rag_query_reading_sibling_script_write_errors() {
+        let mut rag = rag_node("worker_a", &["./k"], true);
+        if let NodeType::Rag(ref mut n) = rag.node_type {
+            n.query = Some("codes: {{loinc_codes}}\n{{db_result}}".into());
+            if let Some(m) = n.state_updates.as_mut() {
+                m.insert("rag_ctx".into(), "{{output.context}}".into());
+            }
+        }
+        rag.next = Some("end".into());
+        let mut script = script_with_state_updates("worker_b", &[("db_result", "{{output}}")]);
+        script.next = Some("end".into());
+        let graph = fan_out_graph_with_two_workers(rag, script);
+
+        let result = validator().validate(&graph);
+
+        assert!(
+            result
+                .errors
+                .iter()
+                .any(|e| e.message.contains("reads state key(s) `db_result`")
+                    && e.message.contains("'worker_b'")),
+            "expected cross-branch read error for rag query reading db_result: {:?}",
+            result.errors
+        );
+    }
+
+    #[test]
+    fn map_over_reading_sibling_write_errors() {
+        let map_n = Node {
+            id: "fan".into(),
+            description: String::new(),
+            node_type: NodeType::Map(MapNode {
+                over: "{{items}}".into(),
+                as_name: "item".into(),
+                branch: "branch_n".into(),
+                output_key: "output".into(),
+                collect_into: "results".into(),
+                max_concurrency: None,
+            }),
+            next: Some("end".into()),
+        };
+        let branch_n = llm_with_prompt("branch_n", "Process {{item}}", None);
+        let producer = llm_with_state_updates("producer", &[("items", "[1,2,3]")], Some("end"));
+        let mut start = end_node("start");
+        start.next = Some(NextTargets::Many(vec!["fan".into(), "producer".into()]));
+        let graph = graph_with(
+            vec![
+                ("start", start),
+                ("fan", map_n),
+                ("branch_n", branch_n),
+                ("producer", producer),
+                ("end", end_node("end")),
+            ],
+            "start",
+        );
+
+        let result = validator().validate(&graph);
+
+        assert!(
+            result
+                .errors
+                .iter()
+                .any(|e| e.message.contains("reads state key(s) `items`")
+                    && e.message.contains("'producer'")),
+            "expected cross-branch read error for map `over` reading sibling write: {:?}",
+            result.errors
+        );
+    }
+}
diff --git a/src/main.rs b/src/main.rs
index 361622a..f3a7f2f 100644
--- a/src/main.rs
+++ b/src/main.rs
@@ -2,6 +2,7 @@ mod cli;
 mod client;
 mod config;
 mod function;
+mod graph;
 mod rag;
 mod render;
 mod repl;
@@ -15,19 +16,19 @@ mod vault;
 #[macro_use]
 extern crate log;
 
+use crate::cli::Cli;
 use crate::client::{
     ModelType, call_chat_completions, call_chat_completions_streaming, list_models, oauth,
 };
+use crate::config::paths;
 use crate::config::{
-    Agent, CODE_ROLE, Config, EXPLAIN_SHELL_ROLE, GlobalConfig, Input, SHELL_ROLE,
-    TEMP_SESSION_NAME, WorkingMode, ensure_parent_exists, list_agents, load_env_file,
-    macro_execute,
+    Agent, AppConfig, AppState, CODE_ROLE, Config, EXPLAIN_SHELL_ROLE, Input, RequestContext,
+    SHELL_ROLE, TEMP_SESSION_NAME, WorkingMode, ensure_parent_exists, install_builtins,
+    list_agents, load_env_file, macro_execute, sync_models,
 };
 use crate::render::{prompt_theme, render_error};
 use crate::repl::Repl;
 use crate::utils::*;
-
-use crate::cli::Cli;
 use crate::vault::Vault;
 use anyhow::{Result, anyhow, bail};
 use clap::{CommandFactory, Parser};
@@ -40,9 +41,8 @@ use log4rs::append::file::FileAppender;
 use log4rs::config::{Appender, Logger, Root};
 use log4rs::encode::pattern::PatternEncoder;
 use oauth::OAuthProvider;
-use parking_lot::RwLock;
 use std::path::PathBuf;
-use std::{env, mem, process, sync::Arc};
+use std::{env, process, sync::Arc};
 
 #[tokio::main]
 async fn main() -> Result<()> {
@@ -83,63 +83,96 @@ async fn main() -> Result<()> {
 
     let log_path = setup_logger()?;
 
+    if let Some(version) = &cli.update {
+        let version = version.clone();
+        let force = cli.force;
+        return tokio::task::spawn_blocking(move || config::run_self_update(version, force))
+            .await?;
+    }
+
+    install_builtins()?;
+
+    if let Some(category) = cli.install {
+        return config::install_assets(category);
+    }
+
+    if let Some(url) = cli.install_from.as_deref() {
+        return config::install_remote(url, cli.filter, cli.install_force);
+    }
+
     if let Some(client_arg) = &cli.authenticate {
-        let config = Config::init_bare()?;
-        let (client_name, provider) = resolve_oauth_client(client_arg.as_deref(), &config.clients)?;
+        let cfg = Config::load_with_interpolation(true).await?;
+        let app_config = AppConfig::from_config(cfg)?;
+        let (client_name, provider) =
+            resolve_oauth_client(client_arg.as_deref(), &app_config.clients)?;
         oauth::run_oauth_flow(&*provider, &client_name).await?;
         return Ok(());
     }
 
     if vault_flags {
-        return Vault::handle_vault_flags(cli, Config::init_bare()?);
+        let cfg = Config::load_with_interpolation(true).await?;
+        let app_config = AppConfig::from_config(cfg)?;
+        let vault = Vault::init(&app_config);
+        return Vault::handle_vault_flags(cli, &vault);
     }
 
     let abort_signal = create_abort_signal();
     let start_mcp_servers = cli.agent.is_none() && cli.role.is_none();
-    let config = Arc::new(RwLock::new(
-        Config::init(
-            working_mode,
-            info_flag,
-            start_mcp_servers,
+    let cfg = Config::load_with_interpolation(info_flag).await?;
+    let app_config: Arc<AppConfig> = Arc::new(AppConfig::from_config(cfg)?);
+    let app_state: Arc<AppState> = Arc::new(
+        AppState::init(
+            app_config,
             log_path,
+            start_mcp_servers,
             abort_signal.clone(),
         )
         .await?,
-    ));
+    );
+    let ctx = RequestContext::bootstrap(app_state, working_mode, info_flag)?;
 
     {
-        let cfg = config.read();
-        if cfg.highlight {
-            set_global_render_config(prompt_theme(cfg.render_options()?)?)
+        let app = &*ctx.app.config;
+        if app.highlight {
+            set_global_render_config(prompt_theme(app.render_options()?)?)
         }
     }
 
-    if let Err(err) = run(config, cli, text, abort_signal).await {
+    if let Err(err) = run(ctx, cli, text, abort_signal).await {
         render_error(err);
         process::exit(1);
     }
     Ok(())
 }
 
+fn update_app_config(ctx: &mut RequestContext, update: impl FnOnce(&mut AppConfig)) {
+    let mut app_config = (*ctx.app.config).clone();
+    update(&mut app_config);
+
+    let mut app_state = (*ctx.app).clone();
+    app_state.config = Arc::new(app_config);
+    ctx.app = Arc::new(app_state);
+}
+
 async fn run(
-    config: GlobalConfig,
+    mut ctx: RequestContext,
     cli: Cli,
     text: Option<String>,
     abort_signal: AbortSignal,
 ) -> Result<()> {
     if cli.sync_models {
-        let url = config.read().sync_models_url();
-        return Config::sync_models(&url, abort_signal.clone()).await;
+        let url = ctx.app.config.sync_models_url();
+        return sync_models(&url, abort_signal.clone()).await;
     }
 
     if cli.list_models {
-        for model in list_models(&config.read(), ModelType::Chat) {
+        for model in list_models(ctx.app.config.as_ref(), ModelType::Chat) {
             println!("{}", model.id());
         }
         return Ok(());
     }
     if cli.list_roles {
-        let roles = Config::list_roles(true).join("\n");
+        let roles = paths::list_roles(true).join("\n");
         println!("{roles}");
         return Ok(());
     }
@@ -149,24 +182,32 @@ async fn run(
         return Ok(());
     }
     if cli.list_rags {
-        let rags = Config::list_rags().join("\n");
+        let rags = paths::list_rags().join("\n");
         println!("{rags}");
         return Ok(());
     }
     if cli.list_macros {
-        let macros = Config::list_macros().join("\n");
+        let macros = paths::list_macros().join("\n");
         println!("{macros}");
         return Ok(());
     }
 
     if cli.dry_run {
-        config.write().dry_run = true;
+        update_app_config(&mut ctx, |app| app.dry_run = true);
     }
 
     if let Some(agent) = &cli.agent {
         if cli.build_tools {
             info!("Building tools for agent '{agent}'...");
-            Agent::init(&config, agent, abort_signal.clone()).await?;
+            Agent::init(
+                &ctx.app.config,
+                &ctx.app,
+                &ctx.model,
+                ctx.info_flag,
+                agent,
+                abort_signal.clone(),
+            )
+            .await?;
             return Ok(());
         }
 
@@ -175,37 +216,40 @@ async fn run(
             None => TEMP_SESSION_NAME,
         });
         if !cli.agent_variable.is_empty() {
-            config.write().agent_variables = Some(
+            ctx.agent_variables = Some(
                 cli.agent_variable
                     .chunks(2)
                     .map(|v| (v[0].to_string(), v[1].to_string()))
                     .collect(),
             );
         }
-
-        let ret = Config::use_agent(&config, agent, session, abort_signal.clone()).await;
-        config.write().agent_variables = None;
-        ret?;
+        let app = Arc::clone(&ctx.app.config);
+        ctx.use_agent(app.as_ref(), agent, session, abort_signal.clone())
+            .await?;
     } else {
+        let app: Arc<AppConfig> = Arc::clone(&ctx.app.config);
         if let Some(prompt) = &cli.prompt {
-            config.write().use_prompt(prompt)?;
+            ctx.use_prompt(app.as_ref(), prompt)?;
         } else if let Some(name) = &cli.role {
-            Config::use_role_safely(&config, name, abort_signal.clone()).await?;
+            ctx.use_role(app.as_ref(), name, abort_signal.clone())
+                .await?;
         } else if cli.execute {
-            Config::use_role_safely(&config, SHELL_ROLE, abort_signal.clone()).await?;
+            ctx.use_role(app.as_ref(), SHELL_ROLE, abort_signal.clone())
+                .await?;
         } else if cli.code {
-            Config::use_role_safely(&config, CODE_ROLE, abort_signal.clone()).await?;
+            ctx.use_role(app.as_ref(), CODE_ROLE, abort_signal.clone())
+                .await?;
         }
         if let Some(session) = &cli.session {
-            Config::use_session_safely(
-                &config,
+            ctx.use_session(
+                app.as_ref(),
                 session.as_ref().map(|v| v.as_str()),
                 abort_signal.clone(),
             )
             .await?;
         }
         if let Some(rag) = &cli.rag {
-            Config::use_rag(&config, Some(rag), abort_signal.clone()).await?;
+            ctx.use_rag(Some(rag), abort_signal.clone()).await?;
         }
     }
 
@@ -214,106 +258,107 @@ async fn run(
     }
 
     if cli.list_sessions {
-        let sessions = config.read().list_sessions().join("\n");
+        let sessions = ctx.list_sessions().join("\n");
         println!("{sessions}");
         return Ok(());
     }
     if let Some(model_id) = &cli.model {
-        config.write().set_model(model_id)?;
+        let app: Arc<AppConfig> = Arc::clone(&ctx.app.config);
+        ctx.set_model_on_role_like(app.as_ref(), model_id)?;
     }
     if cli.no_stream {
-        config.write().stream = false;
+        update_app_config(&mut ctx, |app| app.stream = false);
     }
     if cli.empty_session {
-        config.write().empty_session()?;
+        ctx.empty_session()?;
     }
     if cli.save_session {
-        config.write().set_save_session_this_time()?;
+        ctx.set_save_session_this_time()?;
     }
     if cli.info {
-        let info = config.read().info()?;
+        let app: Arc<AppConfig> = Arc::clone(&ctx.app.config);
+        let info = ctx.info(app.as_ref())?;
         println!("{info}");
         return Ok(());
     }
-    let is_repl = config.read().working_mode.is_repl();
+    let is_repl = ctx.working_mode.is_repl();
     if cli.rebuild_rag {
-        Config::rebuild_rag(&config, abort_signal.clone()).await?;
+        ctx.rebuild_rag(abort_signal.clone()).await?;
         if is_repl {
             return Ok(());
         }
     }
     if let Some(name) = &cli.macro_name {
-        macro_execute(&config, name, text.as_deref(), abort_signal.clone()).await?;
+        macro_execute(&mut ctx, name, text.as_deref(), abort_signal.clone()).await?;
         return Ok(());
     }
     if cli.execute && !is_repl {
-        let input = create_input(&config, text, &cli.file, abort_signal.clone()).await?;
-        shell_execute(&config, &SHELL, input, abort_signal.clone()).await?;
+        let input = create_input(&ctx, text, &cli.file, abort_signal.clone()).await?;
+        shell_execute(&mut ctx, &SHELL, input, abort_signal.clone()).await?;
         return Ok(());
     }
 
-    apply_prelude_safely(&config, abort_signal.clone()).await?;
+    {
+        let app: Arc<AppConfig> = Arc::clone(&ctx.app.config);
+        ctx.apply_prelude(app.as_ref(), abort_signal.clone())
+            .await?;
+    }
 
     match is_repl {
         false => {
-            let mut input = create_input(&config, text, &cli.file, abort_signal.clone()).await?;
+            let mut input = create_input(&ctx, text, &cli.file, abort_signal.clone()).await?;
             input.use_embeddings(abort_signal.clone()).await?;
-            start_directive(&config, input, cli.code, abort_signal).await
+            start_directive(&mut ctx, input, cli.code, abort_signal).await
         }
         true => {
             if !*IS_STDOUT_TERMINAL {
                 bail!("No TTY for REPL")
             }
-            start_interactive(&config).await
+            start_interactive(ctx).await
         }
     }
 }
 
-async fn apply_prelude_safely(config: &RwLock<Config>, abort_signal: AbortSignal) -> Result<()> {
-    let mut cfg = {
-        let mut guard = config.write();
-        mem::take(&mut *guard)
-    };
-
-    cfg.apply_prelude(abort_signal.clone()).await?;
-
-    {
-        let mut guard = config.write();
-        *guard = cfg;
-    }
-
-    Ok(())
-}
-
 #[async_recursion::async_recursion]
 async fn start_directive(
-    config: &GlobalConfig,
+    ctx: &mut RequestContext,
     input: Input,
     code_mode: bool,
     abort_signal: AbortSignal,
 ) -> Result<()> {
+    let app: Arc<AppConfig> = Arc::clone(&ctx.app.config);
+
+    if graph::active_agent_graph_name(ctx).is_some() {
+        ctx.before_chat_completion(&input)?;
+        let output =
+            graph::run_active_agent_graph(ctx, &input.text(), abort_signal.clone()).await?;
+        app.print_markdown(&output)?;
+        ctx.after_chat_completion(app.as_ref(), &input, &output, &[])?;
+        ctx.exit_session()?;
+        return Ok(());
+    }
+
     let client = input.create_client()?;
     let extract_code = !*IS_STDOUT_TERMINAL && code_mode;
-    config.write().before_chat_completion(&input)?;
+    ctx.before_chat_completion(&input)?;
     let (output, tool_results) = if !input.stream() || extract_code {
         call_chat_completions(
             &input,
             true,
             extract_code,
             client.as_ref(),
+            ctx,
             abort_signal.clone(),
         )
         .await?
     } else {
-        call_chat_completions_streaming(&input, client.as_ref(), abort_signal.clone()).await?
+        call_chat_completions_streaming(&input, client.as_ref(), ctx, abort_signal.clone()).await?
     };
-    config
-        .write()
-        .after_chat_completion(&input, &output, &tool_results)?;
+    ctx.after_chat_completion(app.as_ref(), &input, &output, &tool_results)?;
 
     if !tool_results.is_empty() {
         start_directive(
-            config,
+            ctx,
             input.merge_tool_results(output, tool_results),
             code_mode,
             abort_signal,
@@ -321,35 +366,41 @@ async fn start_directive(
         .await?;
     }
 
-    config.write().exit_session()?;
+    ctx.exit_session()?;
     Ok(())
 }
 
-async fn start_interactive(config: &GlobalConfig) -> Result<()> {
-    let mut repl: Repl = Repl::init(config)?;
+async fn start_interactive(ctx: RequestContext) -> Result<()> {
+    let mut repl: Repl = Repl::init(ctx)?;
     repl.run().await
 }
 
 #[async_recursion::async_recursion]
 async fn shell_execute(
-    config: &GlobalConfig,
+    ctx: &mut RequestContext,
     shell: &Shell,
     mut input: Input,
     abort_signal: AbortSignal,
 ) -> Result<()> {
+    let app: Arc<AppConfig> = Arc::clone(&ctx.app.config);
     let client = input.create_client()?;
-    config.write().before_chat_completion(&input)?;
-    let (eval_str, _) =
-        call_chat_completions(&input, false, true, client.as_ref(), abort_signal.clone()).await?;
+    ctx.before_chat_completion(&input)?;
+    let (eval_str, _) = call_chat_completions(
+        &input,
+        false,
+        true,
+        client.as_ref(),
+        ctx,
+        abort_signal.clone(),
+    )
+    .await?;
 
-    config
-        .write()
-        .after_chat_completion(&input, &eval_str, &[])?;
+    ctx.after_chat_completion(app.as_ref(), &input, &eval_str, &[])?;
     if eval_str.is_empty() {
         bail!("No command generated");
     }
-    if config.read().dry_run {
-        config.read().print_markdown(&eval_str)?;
+    if app.dry_run {
+        app.print_markdown(&eval_str)?;
         return Ok(());
     }
     if *IS_STDOUT_TERMINAL {
@@ -370,7 +421,7 @@ async fn shell_execute(
                 'e' => {
                     debug!("{} {:?}", shell.cmd, &[&shell.arg, &eval_str]);
                     let code = run_command(&shell.cmd, &[&shell.arg, &eval_str], None)?;
-                    if code == 0 && config.read().save_shell_history {
+                    if code == 0 && app.save_shell_history {
                         let _ = append_to_shell_history(&shell.name, &eval_str, code);
                     }
                     process::exit(code);
@@ -379,15 +430,16 @@ async fn shell_execute(
                     let revision = Text::new("Enter your revision:").prompt()?;
                     let text = format!("{}\n{revision}", input.text());
                     input.set_text(text);
-                    return shell_execute(config, shell, input, abort_signal.clone()).await;
+                    return shell_execute(ctx, shell, input, abort_signal.clone()).await;
                 }
                 'd' => {
-                    let role = config.read().retrieve_role(EXPLAIN_SHELL_ROLE)?;
-                    let input = Input::from_str(config, &eval_str, Some(role));
+                    let role = ctx.retrieve_role(app.as_ref(), EXPLAIN_SHELL_ROLE)?;
+                    let input = Input::from_str(ctx, &eval_str, Some(role));
                     if input.stream() {
                         call_chat_completions_streaming(
                             &input,
                             client.as_ref(),
+                            ctx,
                             abort_signal.clone(),
                         )
                         .await?;
@@ -397,6 +449,7 @@ async fn shell_execute(
                             true,
                             false,
                             client.as_ref(),
+                            ctx,
                             abort_signal.clone(),
                         )
                         .await?;
@@ -419,22 +472,16 @@ async fn shell_execute(
 }
 
 async fn create_input(
-    config: &GlobalConfig,
+    ctx: &RequestContext,
     text: Option<String>,
     file: &[String],
     abort_signal: AbortSignal,
 ) -> Result<Input> {
+    let text = text.unwrap_or_default();
     let input = if file.is_empty() {
-        Input::from_str(config, &text.unwrap_or_default(), None)
+        Input::from_str(ctx, &text, None)
     } else {
-        Input::from_files_with_spinner(
-            config,
-            &text.unwrap_or_default(),
-            file.to_vec(),
-            None,
-            abort_signal,
-        )
-        .await?
+        Input::from_files_with_spinner(ctx, &text, file.to_vec(), None, abort_signal).await?
     };
     if input.is_empty() {
         bail!("No input");
@@ -443,7 +490,7 @@ async fn create_input(
 }
 
 fn setup_logger() -> Result<Option<PathBuf>> {
-    let (log_level, log_path) = Config::log_config()?;
+    let (log_level, log_path) = paths::log_config()?;
     if log_level == LevelFilter::Off {
         return Ok(None);
     }
diff --git a/src/mcp/mod.rs b/src/mcp/mod.rs
index 993fd54..61e956a 100644
--- a/src/mcp/mod.rs
+++ b/src/mcp/mod.rs
@@ -1,21 +1,25 @@
-use crate::config::Config;
+mod sse_transport;
+
+use crate::config::AppConfig;
+use crate::config::paths;
 use crate::utils::{AbortSignal, abortable_run_with_spinner};
+use crate::vault::Vault;
 use crate::vault::interpolate_secrets;
 use anyhow::{Context, Result, anyhow};
-use bm25::{Document, Language, SearchEngine, SearchEngineBuilder};
-use futures_util::future::BoxFuture;
 use futures_util::{StreamExt, TryStreamExt, stream};
+use http::{HeaderName, HeaderValue};
+use indexmap::IndexMap;
 use indoc::formatdoc;
-use rmcp::model::{CallToolRequestParams, CallToolResult};
 use rmcp::service::RunningService;
+use rmcp::transport::StreamableHttpClientTransport;
 use rmcp::transport::TokioChildProcess;
+use rmcp::transport::streamable_http_client::StreamableHttpClientTransportConfig;
 use rmcp::{RoleClient, ServiceExt};
 use serde::{Deserialize, Serialize};
-use serde_json::{Value, json};
-use std::borrow::Cow;
+use sse_transport::LegacySseTransport;
 use std::collections::{HashMap, HashSet};
 use std::fs::OpenOptions;
-use std::path::PathBuf;
+use std::path::{Path, PathBuf};
 use std::process::Stdio;
 use std::sync::Arc;
 use tokio::process::Command;
@@ -24,7 +28,7 @@ pub const MCP_INVOKE_META_FUNCTION_NAME_PREFIX: &str = "mcp_invoke";
 pub const MCP_SEARCH_META_FUNCTION_NAME_PREFIX: &str = "mcp_search";
 pub const MCP_DESCRIBE_META_FUNCTION_NAME_PREFIX: &str = "mcp_describe";
 
-type ConnectedServer = RunningService<RoleClient, ()>;
+pub type ConnectedServer = RunningService<RoleClient, ()>;
 
 #[derive(Clone, Debug, Default, Serialize)]
 pub struct CatalogItem {
@@ -35,49 +39,96 @@ pub struct CatalogItem {
 
 #[derive(Debug)]
 struct ServerCatalog {
-    engine: SearchEngine<String>,
     items: HashMap<String, CatalogItem>,
 }
 
-impl ServerCatalog {
-    pub fn build_bm25(items: &HashMap<String, CatalogItem>) -> SearchEngine<String> {
-        let docs = items.values().map(|it| {
-            let contents = format!("{}\n{}\nserver:{}", it.name, it.description, it.server);
-            Document {
-                id: it.name.clone(),
-                contents,
-            }
-        });
-        SearchEngineBuilder::<String>::with_documents(Language::English, docs).build()
-    }
-}
-
 impl Clone for ServerCatalog {
     fn clone(&self) -> Self {
         Self {
-            engine: Self::build_bm25(&self.items),
             items: self.items.clone(),
         }
     }
 }
 
-#[derive(Debug, Clone, Deserialize)]
-struct McpServersConfig {
+#[derive(Debug, Clone, Deserialize, Serialize)]
+pub(crate) struct McpServersConfig {
     #[serde(rename = "mcpServers")]
-    mcp_servers: HashMap<String, McpServer>,
+    pub mcp_servers: IndexMap<String, McpServer>,
 }
 
-#[derive(Debug, Clone, Deserialize)]
-struct McpServer {
-    command: String,
-    args: Option<Vec<String>>,
-    env: Option<HashMap<String, JsonField>>,
-    cwd: Option<String>,
+#[derive(Debug, Clone, Deserialize, Serialize, PartialEq, Eq)]
+#[serde(deny_unknown_fields)]
+pub(crate) struct McpServer {
+    #[serde(rename = "type")]
+    pub transport_type: McpTransportType,
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub command: Option<String>,
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub args: Option<Vec<String>>,
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub env: Option<IndexMap<String, JsonField>>,
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub cwd: Option<String>,
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub url: Option<String>,
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub headers: Option<IndexMap<String, String>>,
 }
 
-#[derive(Debug, Clone, Deserialize)]
+impl McpServer {
+    pub fn is_remote(&self) -> bool {
+        matches!(
+            self.transport_type,
+            McpTransportType::Http | McpTransportType::Sse
+        )
+    }
+
+    pub fn validate(&self, name: &str) -> Result<()> {
+        if self.is_remote() {
+            let type_label = match self.transport_type {
+                McpTransportType::Http => "http",
+                McpTransportType::Sse => "sse",
+                _ => unreachable!(),
+            };
+            if self.url.is_none() {
+                return Err(anyhow!(
+                    "MCP server '{name}' has type \"{type_label}\" but is missing a \"url\" field"
+                ));
+            }
+            if self.command.is_some() || self.args.is_some() || self.cwd.is_some() {
+                return Err(anyhow!(
+                    "MCP server '{name}' has type \"{type_label}\" but also specifies stdio fields \
+                     (command/args/cwd). Remove the stdio fields or change the type to \"stdio\"."
+                ));
+            }
+        } else {
+            if self.command.is_none() {
+                return Err(anyhow!(
+                    "MCP server '{name}' is missing a \"command\" field (required for stdio transport)"
+                ));
+            }
+            if self.url.is_some() || self.headers.is_some() {
+                return Err(anyhow!(
+                    "MCP server '{name}' has type \"stdio\" but also specifies remote fields \
+                     (url/headers). Remove the remote fields or change the type to \"http\" or \"sse\"."
+                ));
+            }
+        }
+        Ok(())
+    }
+}
+
+#[derive(Debug, Clone, Deserialize, Serialize, PartialEq, Eq, Hash)]
+#[serde(rename_all = "lowercase")]
+pub(crate) enum McpTransportType {
+    Stdio,
+    Http,
+    Sse,
+}
+
+#[derive(Debug, Clone, Deserialize, Serialize, PartialEq, Eq)]
 #[serde(untagged)]
-enum JsonField {
+pub(crate) enum JsonField {
     Str(String),
     Bool(bool),
     Int(i64),
@@ -97,31 +148,32 @@ impl McpRegistry {
         start_mcp_servers: bool,
         enabled_mcp_servers: Option<String>,
         abort_signal: AbortSignal,
-        config: &Config,
+        app_config: &AppConfig,
+        vault: &Vault,
     ) -> Result<Self> {
         let mut registry = Self {
             log_path,
             ..Default::default()
         };
-        if !Config::mcp_config_file().try_exists().with_context(|| {
+        if !paths::mcp_config_file().try_exists().with_context(|| {
             format!(
                 "Failed to check MCP config file at {}",
-                Config::mcp_config_file().display()
+                paths::mcp_config_file().display()
             )
         })? {
             debug!(
                 "MCP config file does not exist at {}, skipping MCP initialization",
-                Config::mcp_config_file().display()
+                paths::mcp_config_file().display()
             );
             return Ok(registry);
         }
         let err = || {
             format!(
                 "Failed to load MCP config file at {}",
-                Config::mcp_config_file().display()
+                paths::mcp_config_file().display()
             )
         };
-        let content = tokio::fs::read_to_string(Config::mcp_config_file())
+        let content = tokio::fs::read_to_string(paths::mcp_config_file())
             .await
             .with_context(err)?;
 
@@ -130,7 +182,7 @@ impl McpRegistry {
             return Ok(registry);
         }
 
-        let (parsed_content, missing_secrets) = interpolate_secrets(&content, &config.vault);
+        let (parsed_content, missing_secrets) = interpolate_secrets(&content, vault);
 
         if !missing_secrets.is_empty() {
             return Err(anyhow!(formatdoc!(
@@ -143,9 +195,14 @@ impl McpRegistry {
 
         let mcp_servers_config: McpServersConfig =
             serde_json::from_str(&parsed_content).with_context(err)?;
+
+        for (name, spec) in &mcp_servers_config.mcp_servers {
+            spec.validate(name)?;
+        }
+
         registry.config = Some(mcp_servers_config);
 
-        if start_mcp_servers && config.mcp_server_support {
+        if start_mcp_servers && app_config.mcp_server_support {
             abortable_run_with_spinner(
                 registry.start_select_mcp_servers(enabled_mcp_servers),
                 "Loading MCP servers",
@@ -157,34 +214,6 @@ impl McpRegistry {
         Ok(registry)
     }
 
-    pub async fn reinit(
-        mut registry: McpRegistry,
-        enabled_mcp_servers: Option<String>,
-        abort_signal: AbortSignal,
-    ) -> Result<Self> {
-        debug!("Reinitializing MCP registry");
-
-        let desired_ids = registry.resolve_server_ids(enabled_mcp_servers.clone());
-        let desired_set: HashSet<String> = desired_ids.iter().cloned().collect();
-
-        debug!("Stopping unused MCP servers");
-        abortable_run_with_spinner(
-            registry.stop_unused_servers(&desired_set),
-            "Stopping unused MCP servers",
-            abort_signal.clone(),
-        )
-        .await?;
-
-        abortable_run_with_spinner(
-            registry.start_select_mcp_servers(enabled_mcp_servers),
-            "Loading MCP servers",
-            abort_signal,
-        )
-        .await?;
-
-        Ok(registry)
-    }
-
     async fn start_select_mcp_servers(
         &mut self,
         enabled_mcp_servers: Option<String>,
@@ -229,48 +258,14 @@ impl McpRegistry {
         &self,
         id: String,
     ) -> Result<(String, Arc<ConnectedServer>, ServerCatalog)> {
-        let server = self
+        let spec = self
             .config
             .as_ref()
             .and_then(|c| c.mcp_servers.get(&id))
             .with_context(|| format!("MCP server not found in config: {id}"))?;
-        let mut cmd = Command::new(&server.command);
-        if let Some(args) = &server.args {
-            cmd.args(args);
-        }
-        if let Some(env) = &server.env {
-            let env: HashMap<String, String> = env
-                .iter()
-                .map(|(k, v)| match v {
-                    JsonField::Str(s) => (k.clone(), s.clone()),
-                    JsonField::Bool(b) => (k.clone(), b.to_string()),
-                    JsonField::Int(i) => (k.clone(), i.to_string()),
-                })
-                .collect();
-            cmd.envs(env);
-        }
-        if let Some(cwd) = &server.cwd {
-            cmd.current_dir(cwd);
-        }
 
-        let transport = if let Some(log_path) = self.log_path.as_ref() {
-            cmd.stdin(Stdio::piped()).stdout(Stdio::piped());
+        let service = spawn_mcp_server(spec, self.log_path.as_deref()).await?;
 
-            let log_file = OpenOptions::new()
-                .create(true)
-                .append(true)
-                .open(log_path)?;
-            let (transport, _) = TokioChildProcess::builder(cmd).stderr(log_file).spawn()?;
-            transport
-        } else {
-            TokioChildProcess::new(cmd)?
-        };
-
-        let service = Arc::new(
-            ().serve(transport)
-                .await
-                .with_context(|| format!("Failed to start MCP server: {}", &server.command))?,
-        );
         let tools = service.list_tools(None).await?;
         debug!("Available tools for MCP server {id}: {tools:?}");
 
@@ -290,10 +285,7 @@ impl McpRegistry {
             items_map.insert(it.name.clone(), it);
         });
 
-        let catalog = ServerCatalog {
-            engine: ServerCatalog::build_bm25(&items_map),
-            items: items_map,
-        };
+        let catalog = ServerCatalog { items: items_map };
 
         info!("Started MCP server: {id}");
 
@@ -321,118 +313,529 @@ impl McpRegistry {
         }
     }
 
-    pub async fn stop_unused_servers(&mut self, keep_ids: &HashSet<String>) -> Result<()> {
-        let mut ids_to_remove = Vec::new();
-        for (id, _) in self.servers.iter() {
-            if !keep_ids.contains(id) {
-                ids_to_remove.push(id.clone());
-            }
-        }
-
-        for id in ids_to_remove {
-            if let Some(server) = self.servers.remove(&id) {
-                match Arc::try_unwrap(server) {
-                    Ok(server_inner) => {
-                        server_inner
-                            .cancel()
-                            .await
-                            .with_context(|| format!("Failed to stop MCP server: {id}"))?;
-                        info!("Stopped MCP server: {id}");
-                    }
-                    Err(_) => {
-                        info!("Detaching from MCP server: {id} (still in use)");
-                    }
-                }
-                self.catalogs.remove(&id);
-            }
-        }
-        Ok(())
+    pub fn running_servers(&self) -> &HashMap<String, Arc<ConnectedServer>> {
+        &self.servers
     }
 
     pub fn list_started_servers(&self) -> Vec<String> {
         self.servers.keys().cloned().collect()
     }
 
-    pub fn list_configured_servers(&self) -> Vec<String> {
-        if let Some(config) = &self.config {
-            config.mcp_servers.keys().cloned().collect()
-        } else {
-            vec![]
-        }
-    }
-
-    pub fn search_tools_server(&self, server: &str, query: &str, top_k: usize) -> Vec<CatalogItem> {
-        let Some(catalog) = self.catalogs.get(server) else {
-            return vec![];
-        };
-        let engine = &catalog.engine;
-        let raw = engine.search(query, top_k.min(20));
-
-        raw.into_iter()
-            .filter_map(|r| catalog.items.get(&r.document.id))
-            .take(top_k)
-            .cloned()
-            .collect()
-    }
-
-    pub async fn describe(&self, server_id: &str, tool: &str) -> Result<Value> {
-        let server = self
-            .servers
-            .iter()
-            .filter(|(id, _)| &server_id == id)
-            .map(|(_, s)| s.clone())
-            .next()
-            .ok_or(anyhow!("{server_id} MCP server not found in config"))?;
-
-        let tool_schema = server
-            .list_tools(None)
-            .await?
-            .tools
-            .into_iter()
-            .find(|it| it.name == tool)
-            .ok_or(anyhow!(
-                "{tool} not found in {server_id} MCP server catalog"
-            ))?
-            .input_schema;
-        Ok(json!({
-            "type": "object",
-            "properties": {
-                "tool": {
-                    "type": "string",
-                },
-                "arguments": tool_schema
-            }
-        }))
-    }
-
-    pub fn invoke(
-        &self,
-        server: &str,
-        tool: &str,
-        arguments: Value,
-    ) -> BoxFuture<'static, Result<CallToolResult>> {
-        let server = self
-            .servers
-            .get(server)
-            .cloned()
-            .with_context(|| format!("Invoked MCP server does not exist: {server}"));
-
-        let tool = tool.to_owned();
-        Box::pin(async move {
-            let server = server?;
-            let call_tool_request = CallToolRequestParams {
-                name: Cow::Owned(tool.to_owned()),
-                arguments: arguments.as_object().cloned(),
-                meta: None,
-                task: None,
-            };
-
-            let result = server.call_tool(call_tool_request).await?;
-            Ok(result)
-        })
-    }
-
     pub fn is_empty(&self) -> bool {
         self.servers.is_empty()
     }
+
+    pub fn mcp_config(&self) -> Option<&McpServersConfig> {
+        self.config.as_ref()
+    }
+
+    pub fn log_path(&self) -> Option<&PathBuf> {
+        self.log_path.as_ref()
+    }
+}
+
+pub(crate) async fn spawn_mcp_server(
+    spec: &McpServer,
+    log_path: Option<&Path>,
+) -> Result<Arc<ConnectedServer>> {
+    match spec.transport_type {
+        McpTransportType::Http => {
+            let url = spec.url.as_deref().expect("validated: http spec has url");
+            spawn_http_mcp_server(url, spec.headers.as_ref()).await
+        }
+        McpTransportType::Sse => {
+            let url = spec.url.as_deref().expect("validated: sse spec has url");
+            spawn_sse_mcp_server(url, spec.headers.as_ref()).await
+        }
+        McpTransportType::Stdio => {
+            let command = spec
+                .command
+                .as_deref()
+                .expect("validated: stdio spec has command");
+            spawn_stdio_mcp_server(command, spec, log_path).await
+        }
+    }
+}
+
+async fn spawn_http_mcp_server(
+    url: &str,
+    headers: Option<&IndexMap<String, String>>,
+) -> Result<Arc<ConnectedServer>> {
+    let transport = if let Some(hdrs) = headers
+        && !hdrs.is_empty()
+    {
+        let mut custom = HashMap::new();
+        for (k, v) in hdrs {
+            let name = k
+                .parse::<HeaderName>()
+                .with_context(|| format!("Invalid header name: {k}"))?;
+            let value = v
+                .parse::<HeaderValue>()
+                .with_context(|| format!("Invalid header value for {k}"))?;
+            custom.insert(name, value);
+        }
+        let config = StreamableHttpClientTransportConfig::with_uri(url).custom_headers(custom);
+        StreamableHttpClientTransport::from_config(config)
+    } else {
+        StreamableHttpClientTransport::from_uri(url)
+    };
+    let service = Arc::new(
+        ().serve(transport)
+            .await
+            .with_context(|| format!("Failed to connect to HTTP MCP server: {url}"))?,
+    );
+    Ok(service)
+}
+
+async fn spawn_sse_mcp_server(
+    url: &str,
+    headers: Option<&IndexMap<String, String>>,
+) -> Result<Arc<ConnectedServer>> {
+    let sse = LegacySseTransport::connect(url, headers)
+        .await
+        .with_context(|| format!("Failed to connect to SSE MCP server: {url}"))?;
+    let (sink, stream) = sse.into_parts();
+    let service = Arc::new(
+        ().serve((sink, stream))
+            .await
+            .with_context(|| format!("Failed to initialize SSE MCP server: {url}"))?,
+    );
+    Ok(service)
+}
+
+async fn spawn_stdio_mcp_server(
+    command: &str,
+    spec: &McpServer,
+    log_path: Option<&Path>,
+) -> Result<Arc<ConnectedServer>> {
+    let mut cmd = Command::new(command);
+    if let Some(args) = &spec.args {
+        cmd.args(args);
+    }
+    if let Some(env) = &spec.env {
+        let env: HashMap<String, String> = env
+            .iter()
+            .map(|(k, v)| match v {
+                JsonField::Str(s) => (k.clone(), s.clone()),
+                JsonField::Bool(b) => (k.clone(), b.to_string()),
+                JsonField::Int(i) => (k.clone(), i.to_string()),
+            })
+            .collect();
+        cmd.envs(env);
+    }
+    if let Some(cwd) = &spec.cwd {
+        cmd.current_dir(cwd);
+    }
+
+    let transport = if let Some(log_path) = log_path {
+        cmd.stdin(Stdio::piped()).stdout(Stdio::piped());
+
+        let log_file = OpenOptions::new()
+            .create(true)
+            .append(true)
+            .open(log_path)?;
+        let (transport, _) = TokioChildProcess::builder(cmd).stderr(log_file).spawn()?;
+        transport
+    } else {
+        TokioChildProcess::new(cmd)?
+    };
+
+    let service = Arc::new(
+        ().serve(transport)
+            .await
+            .with_context(|| format!("Failed to start MCP server: {command}"))?,
+    );
+    Ok(service)
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    fn stdio_server(command: &str) -> McpServer {
+        McpServer {
+            transport_type: McpTransportType::Stdio,
+            command: Some(command.to_string()),
+            args: None,
+            env: None,
+            cwd: None,
+            url: None,
+            headers: None,
+        }
+    }
+
+    fn http_server(url: &str) -> McpServer {
+        McpServer {
+            transport_type: McpTransportType::Http,
+            command: None,
+            args: None,
+            env: None,
+            cwd: None,
+            url: Some(url.to_string()),
+            headers: None,
+        }
+    }
+
+    fn sse_server(url: &str) -> McpServer {
+        McpServer {
+            transport_type: McpTransportType::Sse,
+            command: None,
+            args: None,
+            env: None,
+            cwd: None,
+            url: Some(url.to_string()),
+            headers: None,
+        }
+    }
+
+    fn make_registry_with_config(server_names: &[&str]) -> McpRegistry {
+        let mut mcp_servers = IndexMap::new();
+        for name in server_names {
+            mcp_servers.insert(name.to_string(), stdio_server("echo"));
+        }
+        McpRegistry {
+            config: Some(McpServersConfig { mcp_servers }),
+            ..Default::default()
+        }
+    }
+
+    #[test]
+    fn validate_stdio_with_command_succeeds() {
+        let spec = stdio_server("npx");
+        assert!(spec.validate("test").is_ok());
+    }
+
+    #[test]
+    fn validate_stdio_missing_command_fails() {
+        let spec = McpServer {
+            transport_type: McpTransportType::Stdio,
+            command: None,
+            args: None,
+            env: None,
+            cwd: None,
+            url: None,
+            headers: None,
+        };
+        let err = spec.validate("test").unwrap_err();
+        assert!(err.to_string().contains("missing a \"command\" field"));
+    }
+
+    #[test]
+    fn validate_stdio_with_url_fails() {
+        let spec = McpServer {
+            transport_type: McpTransportType::Stdio,
+            command: Some("cmd".into()),
+            args: None,
+            env: None,
+            cwd: None,
+            url: Some("http://localhost".into()),
+            headers: None,
+        };
+        let err = spec.validate("test").unwrap_err();
+        assert!(err.to_string().contains("remote fields"));
+    }
+
+    #[test]
+    fn validate_stdio_with_headers_fails() {
+        let mut headers = IndexMap::new();
+        headers.insert("Auth".into(), "Bearer tok".into());
+        let spec = McpServer {
+            transport_type: McpTransportType::Stdio,
+            command: Some("cmd".into()),
+            args: None,
+            env: None,
+            cwd: None,
+            url: None,
+            headers: Some(headers),
+        };
+        let err = spec.validate("test").unwrap_err();
+        assert!(err.to_string().contains("remote fields"));
+    }
+
+    #[test]
+    fn validate_http_with_url_succeeds() {
+        let spec = http_server("http://localhost:8080");
+        assert!(spec.validate("test").is_ok());
+    }
+
+    #[test]
+    fn validate_http_missing_url_fails() {
+        let spec = McpServer {
+            transport_type: McpTransportType::Http,
+            command: None,
+            args: None,
+            env: None,
+            cwd: None,
+            url: None,
+            headers: None,
+        };
+        let err = spec.validate("test").unwrap_err();
+        assert!(err.to_string().contains("missing a \"url\" field"));
+    }
+
+    #[test]
+    fn validate_http_with_command_fails() {
+        let spec = McpServer {
+            transport_type: McpTransportType::Http,
+            command: Some("npx".into()),
+            args: None,
+            env: None,
+            cwd: None,
+            url: Some("http://localhost".into()),
+            headers: None,
+        };
+        let err = spec.validate("test").unwrap_err();
+        assert!(err.to_string().contains("stdio fields"));
+    }
+
+    #[test]
+    fn validate_http_with_args_fails() {
+        let spec = McpServer {
+            transport_type: McpTransportType::Http,
+            command: None,
+            args: Some(vec!["--flag".into()]),
+            env: None,
+            cwd: None,
+            url: Some("http://localhost".into()),
+            headers: None,
+        };
+        let err = spec.validate("test").unwrap_err();
+        assert!(err.to_string().contains("stdio fields"));
+    }
+
+    #[test]
+    fn validate_http_with_cwd_fails() {
+        let spec = McpServer {
+            transport_type: McpTransportType::Http,
+            command: None,
+            args: None,
+            env: None,
+            cwd: Some("/tmp".into()),
+            url: Some("http://localhost".into()),
+            headers: None,
+        };
+        let err = spec.validate("test").unwrap_err();
+        assert!(err.to_string().contains("stdio fields"));
+    }
+
+    #[test]
+    fn validate_sse_with_url_succeeds() {
+        let spec = sse_server("http://sse.example.com");
+        assert!(spec.validate("test").is_ok());
+    }
+
+    #[test]
+    fn validate_sse_missing_url_fails() {
+        let spec = McpServer {
+            transport_type: McpTransportType::Sse,
+            command: None,
+            args: None,
+            env: None,
+            cwd: None,
+            url: None,
+            headers: None,
+        };
+        let err = spec.validate("test").unwrap_err();
+        assert!(err.to_string().contains("missing a \"url\" field"));
+    }
+
+    #[test]
+    fn is_remote_true_for_http_and_sse() {
+        assert!(http_server("http://x").is_remote());
+        assert!(sse_server("http://x").is_remote());
+    }
+
+    #[test]
+    fn is_remote_false_for_stdio() {
+        assert!(!stdio_server("cmd").is_remote());
+    }
+
+    #[test]
+    fn deserialize_stdio_server_from_json() {
+        let json = r#"{
+            "mcpServers": {
+                "my-server": {
+                    "type": "stdio",
+                    "command": "npx",
+                    "args": ["-y", "@modelcontextprotocol/server"]
+                }
+            }
+        }"#;
+        let config: McpServersConfig = serde_json::from_str(json).unwrap();
+        assert!(config.mcp_servers.contains_key("my-server"));
+        let spec = &config.mcp_servers["my-server"];
+        assert_eq!(spec.transport_type, McpTransportType::Stdio);
+        assert_eq!(spec.command.as_deref(), Some("npx"));
+        assert_eq!(
+            spec.args.as_ref().unwrap(),
+            &["-y", "@modelcontextprotocol/server"]
+        );
+    }
+
+    #[test]
+    fn deserialize_http_server_from_json() {
+        let json = r#"{
+            "mcpServers": {
+                "remote": {
+                    "type": "http",
+                    "url": "http://localhost:8080/mcp",
+                    "headers": {"Authorization": "Bearer tok"}
+                }
+            }
+        }"#;
+        let config: McpServersConfig = serde_json::from_str(json).unwrap();
+        let spec = &config.mcp_servers["remote"];
+        assert_eq!(spec.transport_type, McpTransportType::Http);
+        assert_eq!(spec.url.as_deref(), Some("http://localhost:8080/mcp"));
+        assert_eq!(
+            spec.headers.as_ref().unwrap()["Authorization"],
+            "Bearer tok"
+        );
+    }
+
+    #[test]
+    fn deserialize_env_with_mixed_types() {
+        let json = r#"{
+            "mcpServers": {
+                "s": {
+                    "type": "stdio",
+                    "command": "cmd",
+                    "env": {
+                        "STR_VAR": "hello",
+                        "BOOL_VAR": true,
+                        "INT_VAR": 42
+                    }
+                }
+            }
+        }"#;
+        let config: McpServersConfig = serde_json::from_str(json).unwrap();
+        let env = config.mcp_servers["s"].env.as_ref().unwrap();
+        assert!(matches!(env["STR_VAR"], JsonField::Str(ref s) if s == "hello"));
+        assert!(matches!(env["BOOL_VAR"], JsonField::Bool(true)));
+        assert!(matches!(env["INT_VAR"], JsonField::Int(42)));
+    }
+
+    #[test]
+    fn deserialize_multiple_servers() {
+        let json = r#"{
+            "mcpServers": {
+                "github": { "type": "stdio", "command": "gh-mcp" },
+                "remote-api": { "type": "http", "url": "http://api.example.com" }
+            }
+        }"#;
+        let config: McpServersConfig = serde_json::from_str(json).unwrap();
+        assert_eq!(config.mcp_servers.len(), 2);
+        assert!(config.mcp_servers.contains_key("github"));
+        assert!(config.mcp_servers.contains_key("remote-api"));
+    }
+
+    #[test]
+    fn deserialize_empty_servers_map() {
+        let json = r#"{ "mcpServers": {} }"#;
+        let config: McpServersConfig = serde_json::from_str(json).unwrap();
+        assert!(config.mcp_servers.is_empty());
+    }
+
+    #[test]
+    fn deserialize_server_with_cwd() {
+        let json = r#"{
+            "mcpServers": {
+                "s": {
+                    "type": "stdio",
+                    "command": "cmd",
+                    "cwd": "/tmp/work"
+                }
+            }
+        }"#;
+        let config: McpServersConfig = serde_json::from_str(json).unwrap();
+        assert_eq!(config.mcp_servers["s"].cwd.as_deref(), Some("/tmp/work"));
+    }
+
+    #[test]
+    fn resolve_all_returns_all_configured_servers() {
+        let registry = make_registry_with_config(&["github", "slack", "jira"]);
+        let mut ids = registry.resolve_server_ids(Some("all".to_string()));
+        ids.sort();
+        assert_eq!(ids, vec!["github", "jira", "slack"]);
+    }
+
+    #[test]
+    fn resolve_comma_separated_returns_matching_servers() {
+        let registry = make_registry_with_config(&["github", "slack", "jira"]);
+        let mut ids = registry.resolve_server_ids(Some("github, jira".to_string()));
+        ids.sort();
+        assert_eq!(ids, vec!["github", "jira"]);
+    }
+
+    #[test]
+    fn resolve_single_server_name() {
+        let registry = make_registry_with_config(&["github", "slack"]);
+        let ids = registry.resolve_server_ids(Some("slack".to_string()));
+        assert_eq!(ids, vec!["slack"]);
+    }
+
+    #[test]
+    fn resolve_none_returns_empty() {
+        let registry = make_registry_with_config(&["github"]);
+        let ids = registry.resolve_server_ids(None);
+        assert!(ids.is_empty());
+    }
+
+    #[test]
+    fn resolve_no_config_returns_empty() {
+        let registry = McpRegistry::default();
+        let ids = registry.resolve_server_ids(Some("all".to_string()));
+        assert!(ids.is_empty());
+    }
+
+    #[test]
+    fn resolve_nonexistent_server_filtered_out() {
+        let registry = make_registry_with_config(&["github"]);
+        let ids = registry.resolve_server_ids(Some("github, nonexistent".to_string()));
+        assert_eq!(ids, vec!["github"]);
+    }
+
+    #[test]
+    fn resolve_all_nonexistent_returns_empty() {
+        let registry = make_registry_with_config(&["github"]);
+        let ids = registry.resolve_server_ids(Some("foo, bar".to_string()));
+        assert!(ids.is_empty());
+    }
+
+    #[test]
+    fn resolve_trims_whitespace() {
+        let registry = make_registry_with_config(&["github", "slack"]);
+        let mut ids = registry.resolve_server_ids(Some("  github  ,  slack  ".to_string()));
+        ids.sort();
+        assert_eq!(ids, vec!["github", "slack"]);
+    }
+
+    #[test]
+    fn registry_default_is_empty() {
+        let registry = McpRegistry::default();
+        assert!(registry.is_empty());
+        assert!(registry.list_started_servers().is_empty());
+        assert!(registry.mcp_config().is_none());
+        assert!(registry.log_path().is_none());
+    }
+
+    #[test]
+    fn registry_with_config_reports_config() {
+        let registry = make_registry_with_config(&["github"]);
+        assert!(registry.mcp_config().is_some());
+        assert!(
+            registry
+                .mcp_config()
+                .unwrap()
+                .mcp_servers
+                .contains_key("github")
+        );
+    }
+
+    #[test]
+    fn meta_function_prefixes_are_correct() {
+        assert_eq!(MCP_INVOKE_META_FUNCTION_NAME_PREFIX, "mcp_invoke");
+        assert_eq!(MCP_SEARCH_META_FUNCTION_NAME_PREFIX, "mcp_search");
+        assert_eq!(MCP_DESCRIBE_META_FUNCTION_NAME_PREFIX, "mcp_describe");
+    }
 }
diff --git a/src/mcp/sse_transport.rs b/src/mcp/sse_transport.rs
new file mode 100644
index 0000000..dbe0bf4
--- /dev/null
+++ b/src/mcp/sse_transport.rs
@@ -0,0 +1,284 @@
+use anyhow::{Context, Result, anyhow};
+use eventsource_stream::{EventStream, Eventsource};
+use fmt::{Display, Formatter};
+use futures_util::StreamExt;
+use futures_util::stream::BoxStream;
+use indexmap::IndexMap;
+use mpsc::error::SendError;
+use mpsc::{OwnedPermit, Receiver, Sender, channel};
+use reqwest::header::{HeaderMap, HeaderName, HeaderValue};
+use reqwest::{Client, header};
+use rmcp::model::{ClientJsonRpcMessage, ServerJsonRpcMessage};
+use std::error::Error;
+use std::fmt;
+use std::future::Future;
+use std::pin::Pin;
+use std::task::Poll;
+use tokio::sync::mpsc;
+use tokio::time::Duration;
+use url::Url;
+
+type SseEventStream = EventStream<BoxStream<'static, reqwest::Result<bytes::Bytes>>>;
+
+const CHANNEL_BUF: usize = 64;
+
+pub struct LegacySseTransport {
+    tx: Sender<ClientJsonRpcMessage>,
+    rx: Receiver<ServerJsonRpcMessage>,
+}
+
+impl LegacySseTransport {
+    pub async fn connect(
+        sse_url: &str,
+        headers: Option<&IndexMap<String, String>>,
+    ) -> Result<Self> {
+        let base_url =
+            Url::parse(sse_url).with_context(|| format!("Invalid SSE URL: {sse_url}"))?;
+
+        let mut client_builder = Client::builder();
+        let mut header_map = HeaderMap::new();
+        if let Some(hdrs) = headers {
+            for (k, v) in hdrs {
+                let name = k
+                    .parse::<HeaderName>()
+                    .with_context(|| format!("Invalid header name: {k}"))?;
+                let value = v
+                    .parse::<HeaderValue>()
+                    .with_context(|| format!("Invalid header value for {k}"))?;
+                header_map.insert(name, value);
+            }
+            client_builder = client_builder.default_headers(header_map);
+        }
+        let client = client_builder
+            .build()
+            .context("Failed to build HTTP client")?;
+
+        let response = client
+            .get(sse_url)
+            .header(header::ACCEPT, "text/event-stream")
+            .send()
+            .await
+            .context("Failed to open SSE connection")?
+            .error_for_status()
+            .context("SSE server returned an error status")?;
+        let mut es: SseEventStream = response.bytes_stream().boxed().eventsource();
+
+        let post_endpoint = wait_for_endpoint_event(&mut es, &base_url).await?;
+
+        let (outgoing_tx, outgoing_rx) = channel::<ClientJsonRpcMessage>(CHANNEL_BUF);
+        let (incoming_tx, incoming_rx) = channel::<ServerJsonRpcMessage>(CHANNEL_BUF);
+
+        tokio::spawn(sse_reader_task(es, incoming_tx));
+        tokio::spawn(post_writer_task(client, post_endpoint, outgoing_rx));
+
+        Ok(Self {
+            tx: outgoing_tx,
+            rx: incoming_rx,
+        })
+    }
+
+    pub fn into_parts(
+        self,
+    ) -> (
+        SseSink<ClientJsonRpcMessage>,
+        SseStream<ServerJsonRpcMessage>,
+    ) {
+        (
+            SseSink {
+                tx: PollSender {
+                    tx: self.tx,
+                    permit: None,
+                    acquiring: None,
+                },
+            },
+            SseStream { rx: self.rx },
+        )
+    }
+}
+
+async fn wait_for_endpoint_event(es: &mut SseEventStream, base_url: &Url) -> Result<String> {
+    let timeout = Duration::from_secs(30);
+    tokio::time::timeout(timeout, async {
+        while let Some(event) = es.next().await {
+            match event {
+                Ok(msg) if msg.event == "endpoint" => {
+                    let endpoint = msg.data.trim().to_string();
+                    let resolved = resolve_endpoint(&endpoint, base_url)?;
+                    return Ok(resolved);
+                }
+                Ok(_) => {}
+                Err(e) => {
+                    return Err(anyhow!(
+                        "SSE connection error while waiting for endpoint event: {e}"
+                    ));
+                }
+            }
+        }
+        Err(anyhow!("SSE stream closed before receiving endpoint event"))
+    })
+    .await
+    .map_err(|_| anyhow!("Timed out waiting for endpoint event from SSE server (30s)"))?
+}
+
+fn resolve_endpoint(endpoint: &str, base_url: &Url) -> Result<String> {
+    if endpoint.starts_with("http://") || endpoint.starts_with("https://") {
+        Ok(endpoint.to_string())
+    } else {
+        let mut resolved = base_url.clone();
+        let (path, query) = endpoint.split_once('?').unwrap_or((endpoint, ""));
+        resolved.set_path(path);
+        resolved.set_query(if query.is_empty() { None } else { Some(query) });
+        Ok(resolved.to_string())
+    }
+}
+
+async fn sse_reader_task(mut es: SseEventStream, tx: Sender<ServerJsonRpcMessage>) {
+    while let Some(event) = es.next().await {
+        match event {
+            Ok(msg) if msg.event == "message" => {
+                match serde_json::from_str::<ServerJsonRpcMessage>(&msg.data) {
+                    Ok(rpc_msg) => {
+                        if tx.send(rpc_msg).await.is_err() {
+                            break;
+                        }
+                    }
+                    Err(e) => {
+                        warn!("Failed to parse SSE message as JSON-RPC: {e}");
+                    }
+                }
+            }
+            Ok(_) => {}
+            Err(e) => {
+                error!("SSE stream error: {e}");
+                break;
+            }
+        }
+    }
+}
+
+async fn post_writer_task(
+    client: Client,
+    endpoint: String,
+    mut rx: Receiver<ClientJsonRpcMessage>,
+) {
+    while let Some(msg) = rx.recv().await {
+        let body = match serde_json::to_string(&msg) {
+            Ok(b) => b,
+            Err(e) => {
+                error!("Failed to serialize JSON-RPC message: {e}");
+                continue;
+            }
+        };
+        if let Err(e) = client
+            .post(&endpoint)
+            .header("Content-Type", "application/json")
+            .body(body)
+            .send()
+            .await
+        {
+            error!("Failed to POST message to SSE endpoint: {e}");
+        }
+    }
+}
+
+pub struct SseSink<T> {
+    tx: PollSender<T>,
+}
+
+pub struct SseStream<T> {
+    rx: Receiver<T>,
+}
+
+impl<T: Send + 'static> futures_util::Sink<T> for SseSink<T> {
+    type Error = SseSinkError;
+
+    fn poll_ready(
+        mut self: Pin<&mut Self>,
+        cx: &mut std::task::Context<'_>,
+    ) -> Poll<Result<(), Self::Error>> {
+        self.tx.poll_ready(cx)
+    }
+
+    fn start_send(mut self: Pin<&mut Self>, item: T) -> Result<(), Self::Error> {
+        self.tx.start_send(item)
+    }
+
+    fn poll_flush(
+        self: Pin<&mut Self>,
+        _cx: &mut std::task::Context<'_>,
+    ) -> Poll<Result<(), Self::Error>> {
+        Poll::Ready(Ok(()))
+    }
+
+    fn poll_close(
+        self: Pin<&mut Self>,
+        _cx: &mut std::task::Context<'_>,
+    ) -> Poll<Result<(), Self::Error>> {
+        Poll::Ready(Ok(()))
+    }
+}
+
+impl<T: Send + 'static> futures_util::Stream for SseStream<T> {
+    type Item = T;
+
+    fn poll_next(
+        mut self: Pin<&mut Self>,
+        cx: &mut std::task::Context<'_>,
+    ) -> Poll<Option<Self::Item>> {
+        self.rx.poll_recv(cx)
+    }
+}
+
+#[derive(Debug)]
+pub enum SseSinkError {
+    Closed,
+}
+
+impl Display for SseSinkError {
+    fn fmt(&self, f: &mut Formatter<'_>) -> fmt::Result {
+        match self {
+            SseSinkError::Closed => write!(f, "SSE transport channel closed"),
+        }
+    }
+}
+
+impl Error for SseSinkError {}
+
+type ReserveOwned<T> = Pin<Box<dyn Future<Output = Result<OwnedPermit<T>, SendError<()>>> + Send>>;
+
+struct PollSender<T> {
+    tx: Sender<T>,
+    permit: Option<OwnedPermit<T>>,
+    acquiring: Option<ReserveOwned<T>>,
+}
+
+impl<T: Send + 'static> PollSender<T> {
+    fn poll_ready(&mut self, cx: &mut std::task::Context<'_>) -> Poll<Result<(), SseSinkError>> {
+        if self.permit.is_some() {
+            return Poll::Ready(Ok(()));
+        }
+
+        let fut = self
+            .acquiring
+            .get_or_insert_with(|| Box::pin(self.tx.clone().reserve_owned()));
+
+        match fut.as_mut().poll(cx) {
+            Poll::Ready(Ok(permit)) => {
+                self.acquiring = None;
+                self.permit = Some(permit);
+                Poll::Ready(Ok(()))
+            }
+            Poll::Ready(Err(_)) => {
+                self.acquiring = None;
+                Poll::Ready(Err(SseSinkError::Closed))
+            }
+            Poll::Pending => Poll::Pending,
+        }
+    }
+
+    fn start_send(&mut self, item: T) -> Result<(), SseSinkError> {
+        let permit = self.permit.take().ok_or(SseSinkError::Closed)?;
+        permit.send(item);
+        Ok(())
+    }
+}
diff --git a/src/parsers/common.rs b/src/parsers/common.rs
new file mode 100644
index 0000000..d6a423b
--- /dev/null
+++ b/src/parsers/common.rs
@@ -0,0 +1,281 @@
+use crate::function::{FunctionDeclaration, JsonSchema};
+use anyhow::{Context, Result, anyhow, bail};
+use indexmap::IndexMap;
+use serde_json::Value;
+use tree_sitter::Node;
+
+#[derive(Debug)]
+pub(crate) struct Param {
+    pub name: String,
+    pub ty_hint: String,
+    pub required: bool,
+    pub default: Option<Value>,
+    pub doc_type: Option<String>,
+    pub doc_desc: Option<String>,
+}
+
+pub(crate) trait ScriptedLanguage {
+    fn ts_language(&self) -> tree_sitter::Language;
+
+    fn lang_name(&self) -> &str;
+
+    fn find_functions<'a>(&self, root: Node<'a>, src: &str) -> Vec<(Node<'a>, Node<'a>)>;
+
+    fn function_name<'a>(&self, func_node: Node<'a>, src: &'a str) -> Result<&'a str>;
+
+    fn extract_description(
+        &self,
+        wrapper_node: Node<'_>,
+        func_node: Node<'_>,
+        src: &str,
+    ) -> Option<String>;
+
+    fn extract_params(
+        &self,
+        func_node: Node<'_>,
+        src: &str,
+        description: &str,
+    ) -> Result<Vec<Param>>;
+}
+
+pub(crate) fn build_param(
+    name: &str,
+    mut ty: String,
+    mut required: bool,
+    default: Option<Value>,
+) -> Param {
+    if ty.ends_with('?') {
+        ty.pop();
+        required = false;
+    }
+
+    Param {
+        name: name.to_string(),
+        ty_hint: ty,
+        required,
+        default,
+        doc_type: None,
+        doc_desc: None,
+    }
+}
+
+pub(crate) fn build_parameters_schema(params: &[Param], _description: &str) -> JsonSchema {
+    let mut props: IndexMap<String, JsonSchema> = IndexMap::new();
+    let mut req: Vec<String> = Vec::new();
+
+    for p in params {
+        let name = p.name.replace('-', "_");
+        let mut schema = JsonSchema::default();
+
+        let ty = if !p.ty_hint.is_empty() {
+            p.ty_hint.as_str()
+        } else if let Some(t) = &p.doc_type {
+            t.as_str()
+        } else {
+            "str"
+        };
+
+        if let Some(d) = &p.doc_desc
+            && !d.is_empty()
+        {
+            schema.description = Some(d.clone());
+        }
+
+        apply_type_to_schema(ty, &mut schema);
+
+        if p.default.is_none() && p.required {
+            req.push(name.clone());
+        }
+
+        props.insert(name, schema);
+    }
+
+    JsonSchema {
+        type_value: Some("object".into()),
+        description: None,
+        properties: Some(props),
+        items: None,
+        any_of: None,
+        enum_value: None,
+        default: None,
+        required: if req.is_empty() { None } else { Some(req) },
+    }
+}
+
+pub(crate) fn apply_type_to_schema(ty: &str, s: &mut JsonSchema) {
+    let t = ty.trim_end_matches('?');
+    if let Some(rest) = t.strip_prefix("list[") {
+        s.type_value = Some("array".into());
+        let inner = rest.trim_end_matches(']');
+        let mut item = JsonSchema::default();
+
+        apply_type_to_schema(inner, &mut item);
+
+        if item.type_value.is_none() {
+            item.type_value = Some("string".into());
+        }
+        s.items = Some(Box::new(item));
+
+        return;
+    }
+
+    if let Some(rest) = t.strip_prefix("literal:") {
+        s.type_value = Some("string".into());
+        let vals = rest
+            .split('|')
+            .map(|x| x.trim().trim_matches('"').trim_matches('\'').to_string())
+            .collect::<Vec<_>>();
+        if !vals.is_empty() {
+            s.enum_value = Some(vals);
+        }
+        return;
+    }
+
+    s.type_value = Some(
+        match t {
+            "bool" => "boolean",
+            "int" => "integer",
+            "float" => "number",
+            "str" | "any" | "" => "string",
+            _ => "string",
+        }
+        .into(),
+    );
+}
+
+pub(crate) fn underscore(s: &str) -> String {
+    s.chars()
+        .map(|c| {
+            if c.is_ascii_alphanumeric() {
+                c.to_ascii_lowercase()
+            } else {
+                '_'
+            }
+        })
+        .collect::<String>()
+        .split('_')
+        .filter(|t| !t.is_empty())
+        .collect::<Vec<_>>()
+        .join("_")
+}
+
+pub(crate) fn node_text<'a>(node: Node<'_>, src: &'a str) -> Result<&'a str> {
+    node.utf8_text(src.as_bytes())
+        .map_err(|err| anyhow!("invalid utf-8 in source: {err}"))
+}
+
+pub(crate) fn named_child(node: Node<'_>, index: usize) -> Option<Node<'_>> {
+    let mut cursor = node.walk();
+    node.named_children(&mut cursor).nth(index)
+}
+
+pub(crate) fn generate_declarations<L: ScriptedLanguage>(
+    lang: &L,
+    src: &str,
+    file_name: &str,
+    is_tool: bool,
+) -> Result<Vec<FunctionDeclaration>> {
+    let mut parser = tree_sitter::Parser::new();
+    let language = lang.ts_language();
+    parser.set_language(&language).with_context(|| {
+        format!(
+            "failed to initialize {} tree-sitter parser",
+            lang.lang_name()
+        )
+    })?;
+
+    let tree = parser
+        .parse(src.as_bytes(), None)
+        .ok_or_else(|| anyhow!("failed to parse {}: {file_name}", lang.lang_name()))?;
+
+    if tree.root_node().has_error() {
+        bail!(
+            "failed to parse {}: syntax error in {file_name}",
+            lang.lang_name()
+        );
+    }
+
+    let mut out = Vec::new();
+    for (wrapper, func) in lang.find_functions(tree.root_node(), src) {
+        let func_name = lang.function_name(func, src)?;
+
+        if func_name.starts_with('_') && func_name != "_instructions" {
+            continue;
+        }
+        if is_tool && func_name != "run" {
+            continue;
+        }
+
+        let description = lang
+            .extract_description(wrapper, func, src)
+            .unwrap_or_default();
+        let params = lang
+            .extract_params(func, src, &description)
+            .with_context(|| format!("in function '{func_name}' in {file_name}"))?;
+        let schema = build_parameters_schema(&params, &description);
+
+        let name = if is_tool && func_name == "run" {
+            underscore(file_name)
+        } else {
+            underscore(func_name)
+        };
+
+        let desc_trim = description.trim().to_string();
+        if desc_trim.is_empty() {
+            bail!("Missing or empty description on function: {func_name}");
+        }
+
+        out.push(FunctionDeclaration {
+            name,
+            description: desc_trim,
+            parameters: schema,
+            agent: !is_tool,
+        });
+    }
+    Ok(out)
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn underscore_simple() {
+        assert_eq!(underscore("hello"), "hello");
+    }
+
+    #[test]
+    fn underscore_dashes_to_underscores() {
+        assert_eq!(underscore("my-func-name"), "my_func_name");
+    }
+
+    #[test]
+    fn underscore_spaces_to_underscores() {
+        assert_eq!(underscore("my func"), "my_func");
+    }
+
+    #[test]
+    fn underscore_special_chars_removed() {
+        assert_eq!(underscore("func@name!here"), "func_name_here");
+    }
+
+    #[test]
+    fn underscore_consecutive_specials_collapsed() {
+        assert_eq!(underscore("a---b"), "a_b");
+    }
+
+    #[test]
+    fn underscore_leading_trailing_stripped() {
+        assert_eq!(underscore("-leading-"), "leading");
+    }
+
+    #[test]
+    fn underscore_uppercase_lowered() {
+        assert_eq!(underscore("MyFunc"), "myfunc");
+    }
+
+    #[test]
+    fn underscore_mixed() {
+        assert_eq!(underscore("Get-User Info"), "get_user_info");
+    }
+}
diff --git a/src/parsers/mod.rs b/src/parsers/mod.rs
index 57ae15a..30f20c2 100644
--- a/src/parsers/mod.rs
+++ b/src/parsers/mod.rs
@@ -1,2 +1,4 @@
 pub(crate) mod bash;
+pub(crate) mod common;
 pub(crate) mod python;
+pub(crate) mod typescript;
diff --git a/src/parsers/python.rs b/src/parsers/python.rs
index 147ae9b..de9a089 100644
--- a/src/parsers/python.rs
+++ b/src/parsers/python.rs
@@ -1,206 +1,102 @@
-use crate::function::{FunctionDeclaration, JsonSchema};
-use anyhow::{Context, Result, bail};
-use ast::{Stmt, StmtFunctionDef};
+use crate::function::FunctionDeclaration;
+use crate::parsers::common::{self, Param, ScriptedLanguage};
+use anyhow::{Context, Result, anyhow, bail};
 use indexmap::IndexMap;
-use rustpython_ast::{Constant, Expr, UnaryOp};
-use rustpython_parser::{Mode, ast};
 use serde_json::Value;
 use std::fs::File;
 use std::io::Read;
 use std::path::Path;
+use tree_sitter::Node;
 
-#[derive(Debug)]
-struct Param {
-    name: String,
-    ty_hint: String,
-    required: bool,
-    default: Option<Value>,
-    doc_type: Option<String>,
-    doc_desc: Option<String>,
-}
+pub(crate) struct PythonLanguage;
 
-pub fn generate_python_declarations(
-    mut tool_file: File,
-    file_name: &str,
-    parent: Option<&Path>,
-) -> Result<Vec<FunctionDeclaration>> {
-    let mut src = String::new();
-    tool_file
-        .read_to_string(&mut src)
-        .with_context(|| format!("Failed to load script at '{tool_file:?}'"))?;
-    let suite = parse_suite(&src, file_name)?;
-
-    let is_tool = parent
-        .and_then(|p| p.file_name())
-        .is_some_and(|n| n == "tools");
-    let mut declarations = python_to_function_declarations(file_name, &suite, is_tool)?;
-
-    if is_tool {
-        for d in &mut declarations {
-            d.agent = true;
-        }
+impl ScriptedLanguage for PythonLanguage {
+    fn ts_language(&self) -> tree_sitter::Language {
+        tree_sitter_python::LANGUAGE.into()
     }
 
-    Ok(declarations)
-}
+    fn lang_name(&self) -> &str {
+        "python"
+    }
 
-fn parse_suite(src: &str, filename: &str) -> Result<ast::Suite> {
-    let mod_ast =
-        rustpython_parser::parse(src, Mode::Module, filename).context("failed to parse python")?;
+    fn find_functions<'a>(&self, root: Node<'a>, _src: &str) -> Vec<(Node<'a>, Node<'a>)> {
+        let mut cursor = root.walk();
+        root.named_children(&mut cursor)
+            .filter_map(|stmt| unwrap_function_definition(stmt).map(|fd| (stmt, fd)))
+            .collect()
+    }
 
-    let suite = match mod_ast {
-        ast::Mod::Module(m) => m.body,
-        ast::Mod::Interactive(m) => m.body,
-        ast::Mod::Expression(_) => bail!("expected a module; got a single expression"),
-        _ => bail!("unexpected parse mode/AST variant"),
-    };
+    fn function_name<'a>(&self, func_node: Node<'a>, src: &'a str) -> Result<&'a str> {
+        let name_node = func_node
+            .child_by_field_name("name")
+            .ok_or_else(|| anyhow!("function_definition missing name"))?;
+        common::node_text(name_node, src)
+    }
 
-    Ok(suite)
-}
+    fn extract_description(
+        &self,
+        _wrapper_node: Node<'_>,
+        func_node: Node<'_>,
+        src: &str,
+    ) -> Option<String> {
+        get_docstring_from_function(func_node, src)
+    }
 
-fn python_to_function_declarations(
-    file_name: &str,
-    module: &ast::Suite,
-    is_tool: bool,
-) -> Result<Vec<FunctionDeclaration>> {
-    let mut out = Vec::new();
+    fn extract_params(
+        &self,
+        func_node: Node<'_>,
+        src: &str,
+        description: &str,
+    ) -> Result<Vec<Param>> {
+        let parameters = func_node
+            .child_by_field_name("parameters")
+            .ok_or_else(|| anyhow!("function_definition missing parameters"))?;
+        let mut out = Vec::new();
+        let mut cursor = parameters.walk();
 
-    for stmt in module {
-        if let Stmt::FunctionDef(fd) = stmt {
-            let func_name = fd.name.to_string();
-
-            if func_name.starts_with('_') && func_name != "_instructions" {
-                continue;
+        for param in parameters.named_children(&mut cursor) {
+            match param.kind() {
+                "identifier" => out.push(Param {
+                    name: common::node_text(param, src)?.to_string(),
+                    ty_hint: String::new(),
+                    required: true,
+                    default: None,
+                    doc_type: None,
+                    doc_desc: None,
+                }),
+                "typed_parameter" => out.push(common::build_param(
+                    parameter_name(param, src)?,
+                    get_arg_type(param.child_by_field_name("type"), src)?,
+                    true,
+                    None,
+                )),
+                "default_parameter" => out.push(common::build_param(
+                    parameter_name(param, src)?,
+                    String::new(),
+                    false,
+                    Some(Value::Null),
+                )),
+                "typed_default_parameter" => out.push(common::build_param(
+                    parameter_name(param, src)?,
+                    get_arg_type(param.child_by_field_name("type"), src)?,
+                    false,
+                    Some(Value::Null),
+                )),
+                "list_splat_pattern" | "dictionary_splat_pattern" | "positional_separator" => {
+                    let line = param.start_position().row + 1;
+                    bail!(
+                        "line {line}: *args/*kwargs/positional-only parameters are not supported in tool functions"
+                    )
+                }
+                "keyword_separator" => continue,
+                other => {
+                    let line = param.start_position().row + 1;
+                    bail!("line {line}: unsupported parameter type: {other}")
+                }
             }
-
-            if is_tool && func_name != "run" {
-                continue;
-            }
-
-            let description = get_docstring_from_body(&fd.body).unwrap_or_default();
-            let params = collect_params(fd);
-            let schema = build_parameters_schema(&params, &description);
-            let name = if is_tool && func_name == "run" {
-                underscore(file_name)
-            } else {
-                underscore(&func_name)
-            };
-            let desc_trim = description.trim().to_string();
-            if desc_trim.is_empty() {
-                bail!("Missing or empty description on function: {func_name}");
-            }
-
-            out.push(FunctionDeclaration {
-                name,
-                description: desc_trim,
-                parameters: schema,
-                agent: !is_tool,
-            });
-        }
-    }
-
-    Ok(out)
-}
-
-fn get_docstring_from_body(body: &[Stmt]) -> Option<String> {
-    let first = body.first()?;
-    if let Stmt::Expr(expr_stmt) = first
-        && let Expr::Constant(constant) = &*expr_stmt.value
-        && let Constant::Str(s) = &constant.value
-    {
-        return Some(s.clone());
-    }
-    None
-}
-
-fn collect_params(fd: &StmtFunctionDef) -> Vec<Param> {
-    let mut out = Vec::new();
-
-    for a in fd.args.posonlyargs.iter().chain(fd.args.args.iter()) {
-        let name = a.def.arg.to_string();
-        let mut ty = get_arg_type(a.def.annotation.as_deref());
-        let mut required = a.default.is_none();
-
-        if ty.ends_with('?') {
-            ty.pop();
-            required = false;
         }
 
-        let default = if a.default.is_some() {
-            Some(Value::Null)
-        } else {
-            None
-        };
-
-        out.push(Param {
-            name,
-            ty_hint: ty,
-            required,
-            default,
-            doc_type: None,
-            doc_desc: None,
-        });
-    }
-
-    for a in &fd.args.kwonlyargs {
-        let name = a.def.arg.to_string();
-        let mut ty = get_arg_type(a.def.annotation.as_deref());
-        let mut required = a.default.is_none();
-
-        if ty.ends_with('?') {
-            ty.pop();
-            required = false;
-        }
-
-        let default = if a.default.is_some() {
-            Some(Value::Null)
-        } else {
-            None
-        };
-
-        out.push(Param {
-            name,
-            ty_hint: ty,
-            required,
-            default,
-            doc_type: None,
-            doc_desc: None,
-        });
-    }
-
-    if let Some(vararg) = &fd.args.vararg {
-        let name = vararg.arg.to_string();
-        let inner = get_arg_type(vararg.annotation.as_deref());
-        let ty = if inner.is_empty() {
-            "list[str]".into()
-        } else {
-            format!("list[{inner}]")
-        };
-
-        out.push(Param {
-            name,
-            ty_hint: ty,
-            required: false,
-            default: None,
-            doc_type: None,
-            doc_desc: None,
-        });
-    }
-
-    if let Some(kwarg) = &fd.args.kwarg {
-        let name = kwarg.arg.to_string();
-        out.push(Param {
-            name,
-            ty_hint: "object".into(),
-            required: false,
-            default: None,
-            doc_type: None,
-            doc_desc: None,
-        });
-    }
-
-    if let Some(doc) = get_docstring_from_body(&fd.body) {
-        let meta = parse_docstring_args(&doc);
+        let meta = parse_docstring_args(description);
         for p in &mut out {
             if let Some((t, d)) = meta.get(&p.name) {
                 if !t.is_empty() {
@@ -216,70 +112,209 @@ fn collect_params(fd: &StmtFunctionDef) -> Vec<Param> {
                 }
             }
         }
-    }
 
-    out
-}
-
-fn get_arg_type(annotation: Option<&Expr>) -> String {
-    match annotation {
-        None => "".to_string(),
-        Some(Expr::Name(n)) => n.id.to_string(),
-        Some(Expr::Subscript(sub)) => match &*sub.value {
-            Expr::Name(name) if &name.id == "Optional" => {
-                let inner = get_arg_type(Some(&sub.slice));
-                format!("{inner}?")
-            }
-            Expr::Name(name) if &name.id == "List" => {
-                let inner = get_arg_type(Some(&sub.slice));
-                format!("list[{inner}]")
-            }
-            Expr::Name(name) if &name.id == "Literal" => {
-                let vals = literal_members(&sub.slice);
-                format!("literal:{}", vals.join("|"))
-            }
-            _ => "any".to_string(),
-        },
-        _ => "any".to_string(),
+        Ok(out)
     }
 }
 
-fn expr_to_str(e: &Expr) -> String {
-    match e {
-        Expr::Constant(c) => match &c.value {
-            Constant::Str(s) => s.clone(),
-            Constant::Int(i) => i.to_string(),
-            Constant::Float(f) => f.to_string(),
-            Constant::Bool(b) => b.to_string(),
-            Constant::None => "None".to_string(),
-            Constant::Ellipsis => "...".to_string(),
-            Constant::Bytes(b) => String::from_utf8_lossy(b).into_owned(),
-            Constant::Complex { real, imag } => format!("{real}+{imag}j"),
-            _ => "any".to_string(),
-        },
+pub fn generate_python_declarations(
+    mut tool_file: File,
+    file_name: &str,
+    parent: Option<&Path>,
+) -> Result<Vec<FunctionDeclaration>> {
+    let mut src = String::new();
+    tool_file
+        .read_to_string(&mut src)
+        .with_context(|| format!("Failed to load script at '{tool_file:?}'"))?;
 
-        Expr::Name(n) => n.id.to_string(),
+    let is_tool = parent
+        .and_then(|p| p.file_name())
+        .is_some_and(|n| n == "tools");
 
-        Expr::UnaryOp(u) => {
-            if matches!(u.op, UnaryOp::USub) {
-                let inner = expr_to_str(&u.operand);
-                if inner.parse::<f64>().is_ok() || inner.chars().all(|c| c.is_ascii_digit()) {
-                    return format!("-{inner}");
-                }
-            }
-            "any".to_string()
+    common::generate_declarations(&PythonLanguage, &src, file_name, is_tool)
+}
+
+fn unwrap_function_definition(node: Node<'_>) -> Option<Node<'_>> {
+    match node.kind() {
+        "function_definition" => Some(node),
+        "decorated_definition" => {
+            let mut cursor = node.walk();
+            node.named_children(&mut cursor)
+                .find(|child| child.kind() == "function_definition")
         }
-
-        Expr::Tuple(t) => t.elts.iter().map(expr_to_str).collect::<Vec<_>>().join(","),
-
-        _ => "any".to_string(),
+        _ => None,
     }
 }
 
-fn literal_members(e: &Expr) -> Vec<String> {
-    match e {
-        Expr::Tuple(t) => t.elts.iter().map(expr_to_str).collect(),
-        _ => vec![expr_to_str(e)],
+fn get_docstring_from_function(node: Node<'_>, src: &str) -> Option<String> {
+    let body = node.child_by_field_name("body")?;
+    let mut cursor = body.walk();
+    let first = body.named_children(&mut cursor).next()?;
+    if first.kind() != "expression_statement" {
+        return None;
+    }
+
+    let mut expr_cursor = first.walk();
+    let expr = first.named_children(&mut expr_cursor).next()?;
+    if expr.kind() != "string" {
+        return None;
+    }
+
+    let text = common::node_text(expr, src).ok()?;
+    strip_string_quotes(text)
+}
+
+fn strip_string_quotes(text: &str) -> Option<String> {
+    let quote_offset = text
+        .char_indices()
+        .find_map(|(idx, ch)| (ch == '\'' || ch == '"').then_some(idx))?;
+    let prefix = &text[..quote_offset];
+    if !prefix.chars().all(|ch| ch.is_ascii_alphabetic()) {
+        return None;
+    }
+    if prefix.chars().any(|ch| ch == 'f' || ch == 'F') {
+        return None;
+    }
+
+    let literal = &text[quote_offset..];
+    let quote = if literal.starts_with("\"\"\"") {
+        "\"\"\""
+    } else if literal.starts_with("'''") {
+        "'''"
+    } else if literal.starts_with('"') {
+        "\""
+    } else if literal.starts_with('\'') {
+        "'"
+    } else {
+        return None;
+    };
+
+    if literal.len() < quote.len() * 2 || !literal.ends_with(quote) {
+        return None;
+    }
+
+    Some(literal[quote.len()..literal.len() - quote.len()].to_string())
+}
+
+fn parameter_name<'a>(node: Node<'_>, src: &'a str) -> Result<&'a str> {
+    if let Some(name) = node.child_by_field_name("name") {
+        return common::node_text(name, src);
+    }
+
+    let mut cursor = node.walk();
+    node.named_children(&mut cursor)
+        .find(|child| child.kind() == "identifier")
+        .ok_or_else(|| anyhow!("parameter missing name"))
+        .and_then(|name| common::node_text(name, src))
+}
+
+fn get_arg_type(annotation: Option<Node<'_>>, src: &str) -> Result<String> {
+    let Some(annotation) = annotation else {
+        return Ok(String::new());
+    };
+
+    match annotation.kind() {
+        "type" => get_arg_type(common::named_child(annotation, 0), src),
+        "generic_type" => {
+            let value = annotation
+                .child_by_field_name("type")
+                .or_else(|| common::named_child(annotation, 0))
+                .ok_or_else(|| anyhow!("generic_type missing value"))?;
+            let value_name = if value.kind() == "identifier" {
+                common::node_text(value, src)?
+            } else {
+                return Ok("any".to_string());
+            };
+
+            let inner = annotation
+                .child_by_field_name("type_parameter")
+                .or_else(|| annotation.child_by_field_name("parameters"))
+                .or_else(|| common::named_child(annotation, 1))
+                .ok_or_else(|| anyhow!("generic_type missing inner type"))?;
+
+            match value_name {
+                "Optional" => Ok(format!("{}?", generic_inner_type(inner, src)?)),
+                "List" => Ok(format!("list[{}]", generic_inner_type(inner, src)?)),
+                "Literal" => Ok(format!(
+                    "literal:{}",
+                    literal_members(inner, src)?.join("|")
+                )),
+                _ => Ok("any".to_string()),
+            }
+        }
+        "identifier" => Ok(common::node_text(annotation, src)?.to_string()),
+        "subscript" => {
+            let value = annotation
+                .child_by_field_name("value")
+                .or_else(|| common::named_child(annotation, 0))
+                .ok_or_else(|| anyhow!("subscript missing value"))?;
+            let value_name = if value.kind() == "identifier" {
+                common::node_text(value, src)?
+            } else {
+                return Ok("any".to_string());
+            };
+
+            let inner = annotation
+                .child_by_field_name("subscript")
+                .or_else(|| annotation.child_by_field_name("slice"))
+                .or_else(|| common::named_child(annotation, 1))
+                .ok_or_else(|| anyhow!("subscript missing inner type"))?;
+            match value_name {
+                "Optional" => Ok(format!("{}?", get_arg_type(Some(inner), src)?)),
+                "List" => Ok(format!("list[{}]", get_arg_type(Some(inner), src)?)),
+                "Literal" => Ok(format!(
+                    "literal:{}",
+                    literal_members(inner, src)?.join("|")
+                )),
+                _ => Ok("any".to_string()),
+            }
+        }
+        _ => Ok("any".to_string()),
+    }
+}
+
+fn generic_inner_type(node: Node<'_>, src: &str) -> Result<String> {
+    if node.kind() == "type_parameter" {
+        return get_arg_type(common::named_child(node, 0), src);
+    }
+
+    get_arg_type(Some(node), src)
+}
+
+fn literal_members(node: Node<'_>, src: &str) -> Result<Vec<String>> {
+    if node.kind() == "type" {
+        return literal_members(
+            common::named_child(node, 0).ok_or_else(|| anyhow!("type missing inner literal"))?,
+            src,
+        );
+    }
+
+    if node.kind() == "tuple" || node.kind() == "type_parameter" {
+        let mut cursor = node.walk();
+        let members = node
+            .named_children(&mut cursor)
+            .map(|child| expr_to_str(child, src))
+            .collect::<Result<Vec<_>>>()?;
+
+        return Ok(if members.is_empty() {
+            vec!["any".to_string()]
+        } else {
+            members
+        });
+    }
+
+    Ok(vec![expr_to_str(node, src)?])
+}
+
+fn expr_to_str(node: Node<'_>, src: &str) -> Result<String> {
+    match node.kind() {
+        "type" => expr_to_str(
+            common::named_child(node, 0).ok_or_else(|| anyhow!("type missing expression"))?,
+            src,
+        ),
+        "string" | "integer" | "float" | "true" | "false" | "none" | "identifier"
+        | "unary_operator" => Ok(common::node_text(node, src)?.trim().to_string()),
+        _ => Ok("any".to_string()),
     }
 }
 
@@ -318,102 +353,413 @@ fn parse_docstring_args(doc: &str) -> IndexMap<String, (String, String)> {
     out
 }
 
-fn underscore(s: &str) -> String {
-    s.chars()
-        .map(|c| {
-            if c.is_ascii_alphanumeric() {
-                c.to_ascii_lowercase()
-            } else {
-                '_'
-            }
-        })
-        .collect::<String>()
-        .split('_')
-        .filter(|t| !t.is_empty())
-        .collect::<Vec<_>>()
-        .join("_")
-}
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use crate::function::JsonSchema;
+    use std::fs;
+    use std::time::{SystemTime, UNIX_EPOCH};
 
-fn build_parameters_schema(params: &[Param], _description: &str) -> JsonSchema {
-    let mut props: IndexMap<String, JsonSchema> = IndexMap::new();
-    let mut req: Vec<String> = Vec::new();
-
-    for p in params {
-        let name = p.name.replace('-', "_");
-        let mut schema = JsonSchema::default();
-
-        let ty = if !p.ty_hint.is_empty() {
-            p.ty_hint.as_str()
-        } else if let Some(t) = &p.doc_type {
-            t.as_str()
-        } else {
-            "str"
-        };
-
-        if let Some(d) = &p.doc_desc
-            && !d.is_empty()
-        {
-            schema.description = Some(d.clone());
-        }
-
-        apply_type_to_schema(ty, &mut schema);
-
-        if p.default.is_none() && p.required {
-            req.push(name.clone());
-        }
-
-        props.insert(name, schema);
+    fn parse_source(
+        source: &str,
+        file_name: &str,
+        parent: &Path,
+    ) -> Result<Vec<FunctionDeclaration>> {
+        let unique = SystemTime::now()
+            .duration_since(UNIX_EPOCH)
+            .expect("time went backwards")
+            .as_nanos();
+        let path = std::env::temp_dir().join(format!("loki_python_parser_{file_name}_{unique}.py"));
+        fs::write(&path, source).expect("failed to write temp python source");
+        let file = File::open(&path).expect("failed to open temp python source");
+        let result = generate_python_declarations(file, file_name, Some(parent));
+        let _ = fs::remove_file(&path);
+        result
     }
 
-    JsonSchema {
-        type_value: Some("object".into()),
-        description: None,
-        properties: Some(props),
-        items: None,
-        any_of: None,
-        enum_value: None,
-        default: None,
-        required: if req.is_empty() { None } else { Some(req) },
+    fn properties(schema: &JsonSchema) -> &IndexMap<String, JsonSchema> {
+        schema
+            .properties
+            .as_ref()
+            .expect("missing schema properties")
+    }
+
+    fn property<'a>(schema: &'a JsonSchema, name: &str) -> &'a JsonSchema {
+        properties(schema)
+            .get(name)
+            .unwrap_or_else(|| panic!("missing property: {name}"))
+    }
+
+    #[test]
+    fn test_tool_demo_py() {
+        let source = r#"
+import os
+from typing import List, Literal, Optional
+
+def run(
+    string: str,
+    string_enum: Literal["foo", "bar"],
+    boolean: bool,
+    integer: int,
+    number: float,
+    array: List[str],
+    string_optional: Optional[str] = None,
+    array_optional: Optional[List[str]] = None,
+):
+    """Demonstrates how to create a tool using Python and how to use comments.
+    Args:
+        string: Define a required string property
+        string_enum: Define a required string property with enum
+        boolean: Define a required boolean property
+        integer: Define a required integer property
+        number: Define a required number property
+        array: Define a required string array property
+        string_optional: Define an optional string property
+        array_optional: Define an optional string array property
+    """
+    output = f"""string: {string}
+string_enum: {string_enum}
+string_optional: {string_optional}
+boolean: {boolean}
+integer: {integer}
+number: {number}
+array: {array}
+array_optional: {array_optional}"""
+
+    for key, value in os.environ.items():
+        if key.startswith("LLM_"):
+            output = f"{output}\n{key}: {value}"
+
+    return output
+"#;
+
+        let declarations = parse_source(source, "demo_py", Path::new("tools")).unwrap();
+        assert_eq!(declarations.len(), 1);
+
+        let decl = &declarations[0];
+        assert_eq!(decl.name, "demo_py");
+        assert!(!decl.agent);
+        assert!(decl.description.starts_with("Demonstrates how to create"));
+
+        let params = &decl.parameters;
+        assert_eq!(params.type_value.as_deref(), Some("object"));
+        assert_eq!(
+            params.required.as_ref().unwrap(),
+            &vec![
+                "string".to_string(),
+                "string_enum".to_string(),
+                "boolean".to_string(),
+                "integer".to_string(),
+                "number".to_string(),
+                "array".to_string(),
+            ]
+        );
+
+        assert_eq!(
+            property(params, "string").type_value.as_deref(),
+            Some("string")
+        );
+
+        let string_enum = property(params, "string_enum");
+        assert_eq!(string_enum.type_value.as_deref(), Some("string"));
+        assert_eq!(
+            string_enum.enum_value.as_ref().unwrap(),
+            &vec!["foo".to_string(), "bar".to_string()]
+        );
+
+        assert_eq!(
+            property(params, "boolean").type_value.as_deref(),
+            Some("boolean")
+        );
+        assert_eq!(
+            property(params, "integer").type_value.as_deref(),
+            Some("integer")
+        );
+        assert_eq!(
+            property(params, "number").type_value.as_deref(),
+            Some("number")
+        );
+
+        let array = property(params, "array");
+        assert_eq!(array.type_value.as_deref(), Some("array"));
+        assert_eq!(
+            array.items.as_ref().unwrap().type_value.as_deref(),
+            Some("string")
+        );
+
+        let string_optional = property(params, "string_optional");
+        assert_eq!(string_optional.type_value.as_deref(), Some("string"));
+        assert!(
+            !params
+                .required
+                .as_ref()
+                .unwrap()
+                .contains(&"string_optional".to_string())
+        );
+
+        let array_optional = property(params, "array_optional");
+        assert_eq!(array_optional.type_value.as_deref(), Some("array"));
+        assert_eq!(
+            array_optional.items.as_ref().unwrap().type_value.as_deref(),
+            Some("string")
+        );
+        assert!(
+            !params
+                .required
+                .as_ref()
+                .unwrap()
+                .contains(&"array_optional".to_string())
+        );
+    }
+
+    #[test]
+    fn test_tool_weather() {
+        let source = r#"
+import os
+from pathlib import Path
+from typing import Optional
+from urllib.parse import quote_plus
+from urllib.request import urlopen
+
+
+def run(
+    location: str,
+    llm_output: Optional[str] = None,
+) -> str:
+    """Get the current weather in a given location
+
+    Args:
+        location (str): The city and optionally the state or country (e.g., "London", "San Francisco, CA").
+
+    Returns:
+        str: A single-line formatted weather string from wttr.in (``format=4`` with metric units).
+    """
+    url = f"https://wttr.in/{quote_plus(location)}?format=4&M"
+
+    with urlopen(url, timeout=10) as resp:
+        weather = resp.read().decode("utf-8", errors="replace")
+
+    dest = llm_output if llm_output is not None else os.environ.get("LLM_OUTPUT", "/dev/stdout")
+
+    if dest not in {"-", "/dev/stdout"}:
+        path = Path(dest)
+        path.parent.mkdir(parents=True, exist_ok=True)
+        with path.open("a", encoding="utf-8") as fh:
+            fh.write(weather)
+    else:
+        pass
+
+    return weather
+"#;
+
+        let declarations = parse_source(source, "get_current_weather", Path::new("tools")).unwrap();
+        assert_eq!(declarations.len(), 1);
+
+        let decl = &declarations[0];
+        assert_eq!(decl.name, "get_current_weather");
+        assert!(!decl.agent);
+        assert!(
+            decl.description
+                .starts_with("Get the current weather in a given location")
+        );
+
+        let params = &decl.parameters;
+        assert_eq!(
+            params.required.as_ref().unwrap(),
+            &vec!["location".to_string()]
+        );
+
+        let location = property(params, "location");
+        assert_eq!(location.type_value.as_deref(), Some("string"));
+        assert_eq!(
+            location.description.as_deref(),
+            Some(
+                "The city and optionally the state or country (e.g., \"London\", \"San Francisco, CA\")."
+            )
+        );
+
+        let llm_output = property(params, "llm_output");
+        assert_eq!(llm_output.type_value.as_deref(), Some("string"));
+        assert!(
+            !params
+                .required
+                .as_ref()
+                .unwrap()
+                .contains(&"llm_output".to_string())
+        );
+    }
+
+    #[test]
+    fn test_tool_execute_py_code() {
+        let source = r#"
+import ast
+import io
+from contextlib import redirect_stdout
+
+
+def run(code: str):
+    """Execute the given Python code.
+    Args:
+        code: The Python code to execute, such as `print("hello world")`
+    """
+    output = io.StringIO()
+    with redirect_stdout(output):
+        value = exec_with_return(code, {}, {})
+
+        if value is not None:
+            output.write(str(value))
+
+    return output.getvalue()
+
+
+def exec_with_return(code: str, globals: dict, locals: dict):
+    a = ast.parse(code)
+    last_expression = None
+    if a.body:
+        if isinstance(a_last := a.body[-1], ast.Expr):
+            last_expression = ast.unparse(a.body.pop())
+        elif isinstance(a_last, ast.Assign):
+            last_expression = ast.unparse(a_last.targets[0])
+        elif isinstance(a_last, (ast.AnnAssign, ast.AugAssign)):
+            last_expression = ast.unparse(a_last.target)
+    exec(ast.unparse(a), globals, locals)
+    if last_expression:
+        return eval(last_expression, globals, locals)
+"#;
+
+        let declarations = parse_source(source, "execute_py_code", Path::new("tools")).unwrap();
+        assert_eq!(declarations.len(), 1);
+
+        let decl = &declarations[0];
+        assert_eq!(decl.name, "execute_py_code");
+        assert!(!decl.agent);
+
+        let params = &decl.parameters;
+        assert_eq!(properties(params).len(), 1);
+        let code = property(params, "code");
+        assert_eq!(code.type_value.as_deref(), Some("string"));
+        assert_eq!(
+            code.description.as_deref(),
+            Some("The Python code to execute, such as `print(\"hello world\")`")
+        );
+    }
+
+    #[test]
+    fn test_agent_tools() {
+        let source = r#"
+import urllib.request
+
+def get_ipinfo():
+  """
+  Get the ip info
+  """
+  with urllib.request.urlopen("https://httpbin.org/ip") as response:
+    data = response.read()
+    return data.decode('utf-8')
+"#;
+
+        let declarations = parse_source(source, "tools", Path::new("demo")).unwrap();
+        assert_eq!(declarations.len(), 1);
+
+        let decl = &declarations[0];
+        assert_eq!(decl.name, "get_ipinfo");
+        assert!(decl.agent);
+        assert_eq!(decl.description, "Get the ip info");
+        assert!(properties(&decl.parameters).is_empty());
+    }
+
+    #[test]
+    fn test_reject_varargs() {
+        let source = r#"
+def run(*args):
+    """Has docstring"""
+    return args
+"#;
+
+        let err = parse_source(source, "reject_varargs", Path::new("tools")).unwrap_err();
+        let msg = format!("{err:#}");
+        assert!(msg.contains("*args/*kwargs/positional-only parameters are not supported"));
+        assert!(msg.contains("in function 'run'"));
+    }
+
+    #[test]
+    fn test_reject_kwargs() {
+        let source = r#"
+def run(**kwargs):
+    """Has docstring"""
+    return kwargs
+"#;
+
+        let err = parse_source(source, "reject_kwargs", Path::new("tools")).unwrap_err();
+        let msg = format!("{err:#}");
+        assert!(msg.contains("*args/*kwargs/positional-only parameters are not supported"));
+        assert!(msg.contains("in function 'run'"));
+    }
+
+    #[test]
+    fn test_reject_positional_only() {
+        let source = r#"
+def run(x, /, y):
+    """Has docstring"""
+    return x + y
+"#;
+
+        let err = parse_source(source, "reject_positional_only", Path::new("tools")).unwrap_err();
+        let msg = format!("{err:#}");
+        assert!(msg.contains("*args/*kwargs/positional-only parameters are not supported"));
+        assert!(msg.contains("in function 'run'"));
+    }
+
+    #[test]
+    fn test_missing_docstring() {
+        let source = r#"
+def run(x: str):
+    pass
+"#;
+
+        let err = parse_source(source, "missing_docstring", Path::new("tools")).unwrap_err();
+        assert!(
+            err.to_string()
+                .contains("Missing or empty description on function: run")
+        );
+    }
+
+    #[test]
+    fn test_syntax_error() {
+        let source = "def run(: broken";
+        let err = parse_source(source, "syntax_error", Path::new("tools")).unwrap_err();
+        assert!(err.to_string().contains("failed to parse python"));
+    }
+
+    #[test]
+    fn test_underscore_functions_skipped() {
+        let source = r#"
+def _private():
+    """Private"""
+    return None
+
+def public():
+    """Public"""
+    return None
+"#;
+
+        let declarations = parse_source(source, "tools", Path::new("demo")).unwrap();
+        assert_eq!(declarations.len(), 1);
+        assert_eq!(declarations[0].name, "public");
+    }
+
+    #[test]
+    fn test_instructions_not_skipped() {
+        let source = r#"
+def _instructions():
+    """Help text"""
+    return None
+"#;
+
+        let declarations = parse_source(source, "tools", Path::new("demo")).unwrap();
+        assert_eq!(declarations.len(), 1);
+        assert_eq!(declarations[0].name, "instructions");
+        assert_eq!(declarations[0].description, "Help text");
+        assert!(declarations[0].agent);
     }
 }
-
-fn apply_type_to_schema(ty: &str, s: &mut JsonSchema) {
-    let t = ty.trim_end_matches('?');
-    if let Some(rest) = t.strip_prefix("list[") {
-        s.type_value = Some("array".into());
-        let inner = rest.trim_end_matches(']');
-        let mut item = JsonSchema::default();
-
-        apply_type_to_schema(inner, &mut item);
-
-        if item.type_value.is_none() {
-            item.type_value = Some("string".into());
-        }
-        s.items = Some(Box::new(item));
-
-        return;
-    }
-
-    if let Some(rest) = t.strip_prefix("literal:") {
-        s.type_value = Some("string".into());
-        let vals = rest
-            .split('|')
-            .map(|x| x.trim().trim_matches('"').trim_matches('\'').to_string())
-            .collect::<Vec<_>>();
-        if !vals.is_empty() {
-            s.enum_value = Some(vals);
-        }
-        return;
-    }
-
-    s.type_value = Some(
-        match t {
-            "bool" => "boolean",
-            "int" => "integer",
-            "float" => "number",
-            "str" | "any" | "" => "string",
-            _ => "string",
-        }
-        .into(),
-    );
-}
diff --git a/src/parsers/typescript.rs b/src/parsers/typescript.rs
new file mode 100644
index 0000000..4fbea59
--- /dev/null
+++ b/src/parsers/typescript.rs
@@ -0,0 +1,789 @@
+use crate::function::FunctionDeclaration;
+use crate::parsers::common::{self, Param, ScriptedLanguage};
+use anyhow::{Context, Result, anyhow, bail};
+use indexmap::IndexMap;
+use serde_json::Value;
+use std::fs::File;
+use std::io::Read;
+use std::path::Path;
+use tree_sitter::Node;
+
+pub(crate) struct TypeScriptLanguage;
+
+impl ScriptedLanguage for TypeScriptLanguage {
+    fn ts_language(&self) -> tree_sitter::Language {
+        tree_sitter_typescript::LANGUAGE_TYPESCRIPT.into()
+    }
+
+    fn lang_name(&self) -> &str {
+        "typescript"
+    }
+
+    fn find_functions<'a>(&self, root: Node<'a>, _src: &str) -> Vec<(Node<'a>, Node<'a>)> {
+        let mut cursor = root.walk();
+        root.named_children(&mut cursor)
+            .filter_map(|stmt| match stmt.kind() {
+                "export_statement" => unwrap_exported_function(stmt).map(|fd| (stmt, fd)),
+                _ => None,
+            })
+            .collect()
+    }
+
+    fn function_name<'a>(&self, func_node: Node<'a>, src: &'a str) -> Result<&'a str> {
+        let name_node = func_node
+            .child_by_field_name("name")
+            .ok_or_else(|| anyhow!("function_declaration missing name"))?;
+        common::node_text(name_node, src)
+    }
+
+    fn extract_description(
+        &self,
+        wrapper_node: Node<'_>,
+        func_node: Node<'_>,
+        src: &str,
+    ) -> Option<String> {
+        let text = jsdoc_text(wrapper_node, func_node, src)?;
+        let lines = clean_jsdoc_lines(text);
+        let mut description = Vec::new();
+        for line in lines {
+            if line.starts_with('@') {
+                break;
+            }
+            description.push(line);
+        }
+
+        let description = description.join("\n").trim().to_string();
+        (!description.is_empty()).then_some(description)
+    }
+
+    fn extract_params(
+        &self,
+        func_node: Node<'_>,
+        src: &str,
+        _description: &str,
+    ) -> Result<Vec<Param>> {
+        let parameters = func_node
+            .child_by_field_name("parameters")
+            .ok_or_else(|| anyhow!("function_declaration missing parameters"))?;
+        let mut out = Vec::new();
+        let mut cursor = parameters.walk();
+
+        for param in parameters.named_children(&mut cursor) {
+            match param.kind() {
+                "required_parameter" | "optional_parameter" => {
+                    let name = parameter_name(param, src)?;
+                    let ty = get_arg_type(param.child_by_field_name("type"), src)?;
+                    let required = param.kind() == "required_parameter"
+                        && param.child_by_field_name("value").is_none();
+                    let default = param.child_by_field_name("value").map(|_| Value::Null);
+                    out.push(common::build_param(name, ty, required, default));
+                }
+                "rest_parameter" => {
+                    let line = param.start_position().row + 1;
+                    bail!("line {line}: rest parameters (...) are not supported in tool functions")
+                }
+                "object_pattern" => {
+                    let line = param.start_position().row + 1;
+                    bail!(
+                        "line {line}: destructured object parameters (e.g. '{{ a, b }}: {{ a: string }}') \
+                         are not supported in tool functions. Use flat parameters instead (e.g. 'a: string, b: string')."
+                    )
+                }
+                other => {
+                    let line = param.start_position().row + 1;
+                    bail!("line {line}: unsupported parameter type: {other}")
+                }
+            }
+        }
+
+        let wrapper = match func_node.parent() {
+            Some(parent) if parent.kind() == "export_statement" => parent,
+            _ => func_node,
+        };
+        if let Some(doc) = jsdoc_text(wrapper, func_node, src) {
+            let meta = parse_jsdoc_params(doc);
+            for p in &mut out {
+                if let Some(desc) = meta.get(&p.name)
+                    && !desc.is_empty()
+                {
+                    p.doc_desc = Some(desc.clone());
+                }
+            }
+        }
+
+        Ok(out)
+    }
+}
+
+pub fn generate_typescript_declarations(
+    mut tool_file: File,
+    file_name: &str,
+    parent: Option<&Path>,
+) -> Result<Vec<FunctionDeclaration>> {
+    let mut src = String::new();
+    tool_file
+        .read_to_string(&mut src)
+        .with_context(|| format!("Failed to load script at '{tool_file:?}'"))?;
+
+    let is_tool = parent
+        .and_then(|p| p.file_name())
+        .is_some_and(|n| n == "tools");
+
+    common::generate_declarations(&TypeScriptLanguage, &src, file_name, is_tool)
+}
+
+fn unwrap_exported_function(node: Node<'_>) -> Option<Node<'_>> {
+    node.child_by_field_name("declaration")
+        .filter(|child| child.kind() == "function_declaration")
+        .or_else(|| {
+            let mut cursor = node.walk();
+            node.named_children(&mut cursor)
+                .find(|child| child.kind() == "function_declaration")
+        })
+}
+
+fn jsdoc_text<'a>(wrapper_node: Node<'_>, func_node: Node<'_>, src: &'a str) -> Option<&'a str> {
+    wrapper_node
+        .prev_named_sibling()
+        .or_else(|| func_node.prev_named_sibling())
+        .filter(|node| node.kind() == "comment")
+        .and_then(|node| common::node_text(node, src).ok())
+        .filter(|text| text.trim_start().starts_with("/**"))
+}
+
+fn clean_jsdoc_lines(doc: &str) -> Vec<String> {
+    let trimmed = doc.trim();
+    let inner = trimmed
+        .strip_prefix("/**")
+        .unwrap_or(trimmed)
+        .strip_suffix("*/")
+        .unwrap_or(trimmed);
+
+    inner
+        .lines()
+        .map(|line| {
+            let line = line.trim();
+            let line = line.strip_prefix('*').unwrap_or(line).trim_start();
+            line.to_string()
+        })
+        .collect()
+}
+
+fn parse_jsdoc_params(doc: &str) -> IndexMap<String, String> {
+    let mut out = IndexMap::new();
+
+    for line in clean_jsdoc_lines(doc) {
+        let Some(rest) = line.strip_prefix("@param") else {
+            continue;
+        };
+
+        let mut rest = rest.trim();
+        if rest.starts_with('{')
+            && let Some(end) = rest.find('}')
+        {
+            rest = rest[end + 1..].trim_start();
+        }
+
+        if rest.is_empty() {
+            continue;
+        }
+
+        let name_end = rest.find(char::is_whitespace).unwrap_or(rest.len());
+        let mut name = rest[..name_end].trim();
+        if let Some(stripped) = name.strip_suffix('?') {
+            name = stripped;
+        }
+
+        if name.is_empty() {
+            continue;
+        }
+
+        let mut desc = rest[name_end..].trim();
+        if let Some(stripped) = desc.strip_prefix('-') {
+            desc = stripped.trim_start();
+        }
+
+        out.insert(name.to_string(), desc.to_string());
+    }
+
+    out
+}
+
+fn parameter_name<'a>(node: Node<'_>, src: &'a str) -> Result<&'a str> {
+    if let Some(name) = node.child_by_field_name("name") {
+        return match name.kind() {
+            "identifier" => common::node_text(name, src),
+            "rest_pattern" => {
+                let line = node.start_position().row + 1;
+                bail!("line {line}: rest parameters (...) are not supported in tool functions")
+            }
+            "object_pattern" | "array_pattern" => {
+                let line = node.start_position().row + 1;
+                bail!(
+                    "line {line}: destructured parameters are not supported in tool functions. \
+                     Use flat parameters instead (e.g. 'a: string, b: string')."
+                )
+            }
+            other => {
+                let line = node.start_position().row + 1;
+                bail!("line {line}: unsupported parameter type: {other}")
+            }
+        };
+    }
+
+    let pattern = node
+        .child_by_field_name("pattern")
+        .ok_or_else(|| anyhow!("parameter missing pattern"))?;
+
+    match pattern.kind() {
+        "identifier" => common::node_text(pattern, src),
+        "rest_pattern" => {
+            let line = node.start_position().row + 1;
+            bail!("line {line}: rest parameters (...) are not supported in tool functions")
+        }
+        "object_pattern" | "array_pattern" => {
+            let line = node.start_position().row + 1;
+            bail!(
+                "line {line}: destructured parameters are not supported in tool functions. \
+                 Use flat parameters instead (e.g. 'a: string, b: string')."
+            )
+        }
+        other => {
+            let line = node.start_position().row + 1;
+            bail!("line {line}: unsupported parameter type: {other}")
+        }
+    }
+}
+
+fn get_arg_type(annotation: Option<Node<'_>>, src: &str) -> Result<String> {
+    let Some(annotation) = annotation else {
+        return Ok(String::new());
+    };
+
+    match annotation.kind() {
+        "type_annotation" | "type" => get_arg_type(common::named_child(annotation, 0), src),
+        "predefined_type" => Ok(match common::node_text(annotation, src)? {
+            "string" => "str",
+            "number" => "float",
+            "boolean" => "bool",
+            "any" | "unknown" | "void" | "undefined" => "any",
+            _ => "any",
+        }
+        .to_string()),
+        "type_identifier" | "nested_type_identifier" => Ok("any".to_string()),
+        "generic_type" => {
+            let name = annotation
+                .child_by_field_name("name")
+                .ok_or_else(|| anyhow!("generic_type missing name"))?;
+            let type_name = common::node_text(name, src)?;
+            let type_args = annotation
+                .child_by_field_name("type_arguments")
+                .ok_or_else(|| anyhow!("generic_type missing type arguments"))?;
+            let inner = common::named_child(type_args, 0)
+                .ok_or_else(|| anyhow!("generic_type missing inner type"))?;
+
+            match type_name {
+                "Array" => Ok(format!("list[{}]", get_arg_type(Some(inner), src)?)),
+                _ => Ok("any".to_string()),
+            }
+        }
+        "array_type" => {
+            let inner = common::named_child(annotation, 0)
+                .ok_or_else(|| anyhow!("array_type missing inner type"))?;
+            Ok(format!("list[{}]", get_arg_type(Some(inner), src)?))
+        }
+        "union_type" => resolve_union_type(annotation, src),
+        "literal_type" => resolve_literal_type(annotation, src),
+        "parenthesized_type" => get_arg_type(common::named_child(annotation, 0), src),
+        _ => Ok("any".to_string()),
+    }
+}
+
+fn resolve_union_type(annotation: Node<'_>, src: &str) -> Result<String> {
+    let members = flatten_union_members(annotation);
+    let has_null = members.iter().any(|member| is_nullish_type(*member, src));
+
+    let mut literal_values = Vec::new();
+    let mut all_string_literals = true;
+    for member in &members {
+        match string_literal_member(*member, src) {
+            Some(value) => literal_values.push(value),
+            None => {
+                all_string_literals = false;
+                break;
+            }
+        }
+    }
+
+    if all_string_literals && !literal_values.is_empty() {
+        return Ok(format!("literal:{}", literal_values.join("|")));
+    }
+
+    let mut first_non_null = None;
+    for member in members {
+        if is_nullish_type(member, src) {
+            continue;
+        }
+        first_non_null = Some(get_arg_type(Some(member), src)?);
+        break;
+    }
+
+    let mut ty = first_non_null.unwrap_or_else(|| "any".to_string());
+    if has_null && !ty.ends_with('?') {
+        ty.push('?');
+    }
+    Ok(ty)
+}
+
+fn flatten_union_members(node: Node<'_>) -> Vec<Node<'_>> {
+    let node = if node.kind() == "type" {
+        match common::named_child(node, 0) {
+            Some(inner) => inner,
+            None => return vec![],
+        }
+    } else {
+        node
+    };
+
+    if node.kind() != "union_type" {
+        return vec![node];
+    }
+
+    let mut cursor = node.walk();
+    let mut out = Vec::new();
+    for child in node.named_children(&mut cursor) {
+        out.extend(flatten_union_members(child));
+    }
+    out
+}
+
+fn resolve_literal_type(annotation: Node<'_>, src: &str) -> Result<String> {
+    let inner = common::named_child(annotation, 0)
+        .ok_or_else(|| anyhow!("literal_type missing inner literal"))?;
+
+    match inner.kind() {
+        "string" | "number" | "true" | "false" | "unary_expression" => {
+            Ok(format!("literal:{}", common::node_text(inner, src)?.trim()))
+        }
+        "null" | "undefined" => Ok("any".to_string()),
+        _ => Ok("any".to_string()),
+    }
+}
+
+fn string_literal_member(node: Node<'_>, src: &str) -> Option<String> {
+    let node = if node.kind() == "type" {
+        common::named_child(node, 0)?
+    } else {
+        node
+    };
+
+    if node.kind() != "literal_type" {
+        return None;
+    }
+
+    let inner = common::named_child(node, 0)?;
+    if inner.kind() != "string" {
+        return None;
+    }
+
+    Some(common::node_text(inner, src).ok()?.to_string())
+}
+
+fn is_nullish_type(node: Node<'_>, src: &str) -> bool {
+    let node = if node.kind() == "type" {
+        match common::named_child(node, 0) {
+            Some(inner) => inner,
+            None => return false,
+        }
+    } else {
+        node
+    };
+
+    match node.kind() {
+        "literal_type" => common::named_child(node, 0)
+            .is_some_and(|inner| matches!(inner.kind(), "null" | "undefined")),
+        "predefined_type" => common::node_text(node, src)
+            .map(|text| matches!(text, "undefined" | "void"))
+            .unwrap_or(false),
+        _ => false,
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use crate::function::JsonSchema;
+    use std::fs;
+    use std::time::{SystemTime, UNIX_EPOCH};
+
+    fn parse_ts_source(
+        source: &str,
+        file_name: &str,
+        parent: &Path,
+    ) -> Result<Vec<FunctionDeclaration>> {
+        let unique = SystemTime::now()
+            .duration_since(UNIX_EPOCH)
+            .expect("time")
+            .as_nanos();
+        let path = std::env::temp_dir().join(format!("loki_ts_parser_{file_name}_{unique}.ts"));
+        fs::write(&path, source).expect("write");
+        let file = File::open(&path).expect("open");
+        let result = generate_typescript_declarations(file, file_name, Some(parent));
+        let _ = fs::remove_file(&path);
+        result
+    }
+
+    fn properties(schema: &JsonSchema) -> &IndexMap<String, JsonSchema> {
+        schema
+            .properties
+            .as_ref()
+            .expect("missing schema properties")
+    }
+
+    fn property<'a>(schema: &'a JsonSchema, name: &str) -> &'a JsonSchema {
+        properties(schema)
+            .get(name)
+            .unwrap_or_else(|| panic!("missing property: {name}"))
+    }
+
+    #[test]
+    fn test_ts_tool_demo() {
+        let source = r#"
+/**
+ * Demonstrates how to create a tool using TypeScript.
+ *
+ * @param query - The search query string
+ * @param format - Output format
+ * @param count - Maximum results to return
+ * @param verbose - Enable verbose output
+ * @param tags - List of tags to filter by
+ * @param language - Optional language filter
+ * @param extra_tags - Optional extra tags
+ */
+export function run(
+  query: string,
+  format: "json" | "csv" | "xml",
+  count: number,
+  verbose: boolean,
+  tags: string[],
+  language?: string,
+  extra_tags?: Array<string>,
+): string {
+  return "result";
+}
+"#;
+
+        let declarations = parse_ts_source(source, "demo_ts", Path::new("tools")).unwrap();
+        assert_eq!(declarations.len(), 1);
+
+        let decl = &declarations[0];
+        assert_eq!(decl.name, "demo_ts");
+        assert!(!decl.agent);
+
+        let params = &decl.parameters;
+        assert_eq!(params.type_value.as_deref(), Some("object"));
+        assert_eq!(
+            params.required.as_ref().unwrap(),
+            &vec![
+                "query".to_string(),
+                "format".to_string(),
+                "count".to_string(),
+                "verbose".to_string(),
+                "tags".to_string(),
+            ]
+        );
+
+        assert_eq!(
+            property(params, "query").type_value.as_deref(),
+            Some("string")
+        );
+
+        let format = property(params, "format");
+        assert_eq!(format.type_value.as_deref(), Some("string"));
+        assert_eq!(
+            format.enum_value.as_ref().unwrap(),
+            &vec!["json".to_string(), "csv".to_string(), "xml".to_string()]
+        );
+
+        assert_eq!(
+            property(params, "count").type_value.as_deref(),
+            Some("number")
+        );
+        assert_eq!(
+            property(params, "verbose").type_value.as_deref(),
+            Some("boolean")
+        );
+
+        let tags = property(params, "tags");
+        assert_eq!(tags.type_value.as_deref(), Some("array"));
+        assert_eq!(
+            tags.items.as_ref().unwrap().type_value.as_deref(),
+            Some("string")
+        );
+
+        let language = property(params, "language");
+        assert_eq!(language.type_value.as_deref(), Some("string"));
+        assert!(
+            !params
+                .required
+                .as_ref()
+                .unwrap()
+                .contains(&"language".to_string())
+        );
+
+        let extra_tags = property(params, "extra_tags");
+        assert_eq!(extra_tags.type_value.as_deref(), Some("array"));
+        assert_eq!(
+            extra_tags.items.as_ref().unwrap().type_value.as_deref(),
+            Some("string")
+        );
+        assert!(
+            !params
+                .required
+                .as_ref()
+                .unwrap()
+                .contains(&"extra_tags".to_string())
+        );
+    }
+
+    #[test]
+    fn test_ts_tool_simple() {
+        let source = r#"
+/**
+ * Execute the given code.
+ *
+ * @param code - The code to execute
+ */
+export function run(code: string): string {
+  return eval(code);
+}
+"#;
+
+        let declarations = parse_ts_source(source, "execute_code", Path::new("tools")).unwrap();
+        assert_eq!(declarations.len(), 1);
+
+        let decl = &declarations[0];
+        assert_eq!(decl.name, "execute_code");
+        assert!(!decl.agent);
+
+        let params = &decl.parameters;
+        assert_eq!(params.required.as_ref().unwrap(), &vec!["code".to_string()]);
+        assert_eq!(
+            property(params, "code").type_value.as_deref(),
+            Some("string")
+        );
+    }
+
+    #[test]
+    fn test_ts_agent_tools() {
+        let source = r#"
+/** Get user info by ID */
+export function get_user(id: string): string {
+  return "";
+}
+
+/** List all users */
+export function list_users(): string {
+  return "";
+}
+"#;
+
+        let declarations = parse_ts_source(source, "tools", Path::new("demo")).unwrap();
+        assert_eq!(declarations.len(), 2);
+        assert_eq!(declarations[0].name, "get_user");
+        assert_eq!(declarations[1].name, "list_users");
+        assert!(declarations[0].agent);
+        assert!(declarations[1].agent);
+    }
+
+    #[test]
+    fn test_ts_reject_rest_params() {
+        let source = r#"
+/**
+ * Has rest params
+ */
+export function run(...args: string[]): string {
+  return "";
+}
+"#;
+
+        let err = parse_ts_source(source, "rest_params", Path::new("tools")).unwrap_err();
+        let msg = format!("{err:#}");
+        assert!(msg.contains("rest parameters"));
+        assert!(msg.contains("in function 'run'"));
+    }
+
+    #[test]
+    fn test_ts_missing_jsdoc() {
+        let source = r#"
+export function run(x: string): string {
+  return x;
+}
+"#;
+
+        let err = parse_ts_source(source, "missing_jsdoc", Path::new("tools")).unwrap_err();
+        assert!(
+            err.to_string()
+                .contains("Missing or empty description on function: run")
+        );
+    }
+
+    #[test]
+    fn test_ts_syntax_error() {
+        let source = "export function run(: broken";
+        let err = parse_ts_source(source, "syntax_error", Path::new("tools")).unwrap_err();
+        assert!(err.to_string().contains("failed to parse typescript"));
+    }
+
+    #[test]
+    fn test_ts_underscore_skipped() {
+        let source = r#"
+/** Private helper */
+function _helper(): void {}
+
+/** Public function */
+export function do_stuff(): string {
+  return "";
+}
+"#;
+
+        let declarations = parse_ts_source(source, "tools", Path::new("demo")).unwrap();
+        assert_eq!(declarations.len(), 1);
+        assert_eq!(declarations[0].name, "do_stuff");
+        assert!(declarations[0].agent);
+    }
+
+    #[test]
+    fn test_ts_non_exported_helpers_skipped() {
+        let source = r#"
+#!/usr/bin/env tsx
+
+import { appendFileSync } from 'fs';
+
+/**
+ * Get the current weather in a given location
+ * @param location - The city
+ */
+export function get_current_weather(location: string): string {
+  return fetchSync("https://example.com/" + location);
+}
+
+function fetchSync(url: string): string {
+  return "sunny";
+}
+"#;
+
+        let declarations = parse_ts_source(source, "tools", Path::new("demo")).unwrap();
+        assert_eq!(declarations.len(), 1);
+        assert_eq!(declarations[0].name, "get_current_weather");
+    }
+
+    #[test]
+    fn test_ts_instructions_not_skipped() {
+        let source = r#"
+/** Help text for the agent */
+export function _instructions(): string {
+  return "";
+}
+"#;
+
+        let declarations = parse_ts_source(source, "tools", Path::new("demo")).unwrap();
+        assert_eq!(declarations.len(), 1);
+        assert_eq!(declarations[0].name, "instructions");
+        assert!(declarations[0].agent);
+    }
+
+    #[test]
+    fn test_ts_optional_with_null_union() {
+        let source = r#"
+/**
+ * Fetch data with optional filter
+ *
+ * @param url - The URL to fetch
+ * @param filter - Optional filter string
+ */
+export function run(url: string, filter: string | null): string {
+  return "";
+}
+"#;
+
+        let declarations = parse_ts_source(source, "fetch_data", Path::new("tools")).unwrap();
+        let params = &declarations[0].parameters;
+        assert!(
+            params
+                .required
+                .as_ref()
+                .unwrap()
+                .contains(&"url".to_string())
+        );
+        assert!(
+            !params
+                .required
+                .as_ref()
+                .unwrap()
+                .contains(&"filter".to_string())
+        );
+        assert_eq!(
+            property(params, "filter").type_value.as_deref(),
+            Some("string")
+        );
+    }
+
+    #[test]
+    fn test_ts_optional_with_default() {
+        let source = r#"
+/**
+ * Search with limit
+ *
+ * @param query - Search query
+ * @param limit - Max results
+ */
+export function run(query: string, limit: number = 10): string {
+  return "";
+}
+"#;
+
+        let declarations =
+            parse_ts_source(source, "search_with_limit", Path::new("tools")).unwrap();
+        let params = &declarations[0].parameters;
+        assert!(
+            params
+                .required
+                .as_ref()
+                .unwrap()
+                .contains(&"query".to_string())
+        );
+        assert!(
+            !params
+                .required
+                .as_ref()
+                .unwrap()
+                .contains(&"limit".to_string())
+        );
+        assert_eq!(
+            property(params, "limit").type_value.as_deref(),
+            Some("number")
+        );
+    }
+
+    #[test]
+    fn test_ts_shebang_parses() {
+        let source = r#"#!/usr/bin/env tsx
+
+/**
+ * Get weather
+ * @param location - The city
+ */
+export function run(location: string): string {
+  return location;
+}
+"#;
+
+        let result = parse_ts_source(source, "get_weather", Path::new("tools"));
+        eprintln!("shebang parse result: {result:?}");
+        assert!(result.is_ok(), "shebang should not cause parse failure");
+        let declarations = result.unwrap();
+        assert_eq!(declarations.len(), 1);
+        assert_eq!(declarations[0].name, "get_weather");
+    }
+}
diff --git a/src/rag/mod.rs b/src/rag/mod.rs
index 2f9320d..19cc6f2 100644
--- a/src/rag/mod.rs
+++ b/src/rag/mod.rs
@@ -15,11 +15,38 @@ use inquire::{Confirm, Select, Text, required, validator::Validation};
 use parking_lot::RwLock;
 use serde::{Deserialize, Serialize};
 use serde_json::json;
-use std::{collections::HashMap, env, fmt::Debug, fs, hash::Hash, path::Path, time::Duration};
+use std::{
+    collections::HashMap, env, fmt, fmt::Debug, fs, hash::Hash, path::Path, sync::Arc,
+    time::Duration,
+};
 use tokio::time::sleep;
 
+const RAG_TEMPLATE: &str = r#"Answer the query based on the context while respecting the rules. (user query, some textual context and rules, all inside xml tags)
+
+<context>
+__CONTEXT__
+</context>
+
+<sources>
+__SOURCES__
+</sources>
+
+<rules>
+- If you don't know, just say so.
+- If you are not sure, ask for clarification.
+- Answer in the same language as the user query.
+- If the context appears unreadable or of poor quality, tell the user then answer as best as you can.
+- If the answer is not in the context but you think you know the answer, explain that to the user then answer with your own knowledge.
+- Answer directly and without using xml tags.
+- When using information from the context, cite the relevant source from the <sources> section.
+</rules>
+
+<user_query>
+__INPUT__
+</user_query>"#;
+
 pub struct Rag {
-    config: GlobalConfig,
+    app_config: Arc<AppConfig>,
     name: String,
     path: String,
     embedding_model: Model,
@@ -30,7 +57,7 @@ pub struct Rag {
 }
 
 impl Debug for Rag {
-    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
+    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
         f.debug_struct("Rag")
             .field("name", &self.name)
             .field("path", &self.path)
@@ -43,7 +70,7 @@ impl Debug for Rag {
 impl Clone for Rag {
     fn clone(&self) -> Self {
         Self {
-            config: self.config.clone(),
+            app_config: self.app_config.clone(),
             name: self.name.clone(),
             path: self.path.clone(),
             embedding_model: self.embedding_model.clone(),
@@ -55,9 +82,128 @@ impl Clone for Rag {
     }
 }
 
+#[derive(Debug, Clone, Default)]
+pub struct RagInitConfig {
+    pub embedding_model: Option<String>,
+    pub chunk_size: Option<usize>,
+    pub chunk_overlap: Option<usize>,
+    pub reranker_model: Option<String>,
+    pub top_k: Option<usize>,
+    pub batch_size: Option<usize>,
+}
+
 impl Rag {
+    fn create_embeddings_client(&self, model: Model) -> Result<Box<dyn Client>> {
+        init_client(&self.app_config, model)
+    }
+
+    pub async fn init_with_config(
+        app: &AppConfig,
+        name: &str,
+        save_path: &Path,
+        doc_paths: &[String],
+        config: &RagInitConfig,
+        abort_signal: AbortSignal,
+    ) -> Result<Self> {
+        if doc_paths.is_empty() {
+            bail!("Cannot build RAG knowledge base '{name}' with no documents");
+        }
+        println!("⚙ Initializing RAG...");
+        let data = Self::resolve_init_data(app, config)?;
+        let mut rag = Self::create(app, name, save_path, data)?;
+        let loaders = app.document_loaders.clone();
+        let (spinner, spinner_rx) = Spinner::create("");
+        abortable_run_with_spinner_rx(
+            rag.sync_documents(doc_paths, true, loaders, Some(spinner)),
+            spinner_rx,
+            abort_signal,
+        )
+        .await?;
+        if rag.save()? {
+            println!("✓ Saved RAG to '{}'.", save_path.display());
+        }
+        Ok(rag)
+    }
+
+    fn resolve_init_data(app: &AppConfig, config: &RagInitConfig) -> Result<RagData> {
+        let embedding_model_id = config
+            .embedding_model
+            .clone()
+            .or_else(|| app.rag_embedding_model.clone());
+        let embedding_model_id = match embedding_model_id {
+            Some(value) => {
+                println!("Embedding model: {value}");
+                value
+            }
+            None => {
+                if !*IS_STDOUT_TERMINAL {
+                    bail!(
+                        "RAG knowledge base needs an embedding model. Set `embedding_model` \
+                         on the rag node, or run the agent interactively once."
+                    );
+                }
+                let models = list_models(app, ModelType::Embedding);
+                if models.is_empty() {
+                    bail!("No available embedding model");
+                }
+                select_embedding_model(&models)?
+            }
+        };
+        let embedding_model =
+            Model::retrieve_model(app, &embedding_model_id, ModelType::Embedding)?;
+
+        let chunk_size = match config.chunk_size.or(app.rag_chunk_size) {
+            Some(value) => {
+                println!("Chunk size: {value}");
+                value
+            }
+            None => {
+                if !*IS_STDOUT_TERMINAL {
+                    bail!(
+                        "RAG knowledge base needs a chunk_size. Set `chunk_size` on the \
+                         rag node, or run the agent interactively once."
+                    );
+                }
+                set_chunk_size(&embedding_model)?
+            }
+        };
+        let chunk_overlap = match config.chunk_overlap.or(app.rag_chunk_overlap) {
+            Some(value) => {
+                println!("Chunk overlap: {value}");
+                value
+            }
+            None => {
+                if !*IS_STDOUT_TERMINAL {
+                    bail!(
+                        "RAG knowledge base needs a chunk_overlap. Set `chunk_overlap` on \
+                         the rag node, or run the agent interactively once."
+                    );
+                }
+                set_chunk_overlay(chunk_size / 20)?
+            }
+        };
+
+        let reranker_model = config
+            .reranker_model
+            .clone()
+            .or_else(|| app.rag_reranker_model.clone());
+        let top_k = config.top_k.unwrap_or(app.rag_top_k);
+        let batch_size = config
+            .batch_size
+            .or_else(|| embedding_model.max_batch_size());
+
+        Ok(RagData::new(
+            embedding_model.id(),
+            chunk_size,
+            chunk_overlap,
+            reranker_model,
+            top_k,
+            batch_size,
+        ))
+    }
+
     pub async fn init(
-        config: &GlobalConfig,
+        app: &AppConfig,
         name: &str,
         save_path: &Path,
         doc_paths: &[String],
@@ -67,11 +213,9 @@ impl Rag {
             bail!("Failed to init rag in non-interactive mode");
         }
         println!("⚙ Initializing RAG...");
-        let (embedding_model, chunk_size, chunk_overlap) = Self::create_config(config)?;
-        let (reranker_model, top_k) = {
-            let config = config.read();
-            (config.rag_reranker_model.clone(), config.rag_top_k)
-        };
+        let (embedding_model, chunk_size, chunk_overlap) = Self::create_config(app)?;
+        let reranker_model = app.rag_reranker_model.clone();
+        let top_k = app.rag_top_k;
         let data = RagData::new(
             embedding_model.id(),
             chunk_size,
@@ -80,12 +224,12 @@ impl Rag {
             top_k,
             embedding_model.max_batch_size(),
         );
-        let mut rag = Self::create(config, name, save_path, data)?;
+        let mut rag = Self::create(app, name, save_path, data)?;
         let mut paths = doc_paths.to_vec();
         if paths.is_empty() {
             paths = add_documents()?;
         };
-        let loaders = config.read().document_loaders.clone();
+        let loaders = app.document_loaders.clone();
         let (spinner, spinner_rx) = Spinner::create("");
         abortable_run_with_spinner_rx(
             rag.sync_documents(&paths, true, loaders, Some(spinner)),
@@ -99,20 +243,20 @@ impl Rag {
         Ok(rag)
     }
 
-    pub fn load(config: &GlobalConfig, name: &str, path: &Path) -> Result<Self> {
+    pub fn load(app: &AppConfig, name: &str, path: &Path) -> Result<Self> {
         let err = || format!("Failed to load rag '{name}' at '{}'", path.display());
         let content = fs::read_to_string(path).with_context(err)?;
         let data: RagData = serde_yaml::from_str(&content).with_context(err)?;
-        Self::create(config, name, path, data)
+        Self::create(app, name, path, data)
     }
 
-    pub fn create(config: &GlobalConfig, name: &str, path: &Path, data: RagData) -> Result<Self> {
+    pub fn create(app: &AppConfig, name: &str, path: &Path, data: RagData) -> Result<Self> {
         let hnsw = data.build_hnsw();
         let bm25 = data.build_bm25();
         let embedding_model =
-            Model::retrieve_model(&config.read(), &data.embedding_model, ModelType::Embedding)?;
+            Model::retrieve_model(app, &data.embedding_model, ModelType::Embedding)?;
         let rag = Rag {
-            config: config.clone(),
+            app_config: Arc::new(app.clone()),
             name: name.to_string(),
             path: path.display().to_string(),
             data,
@@ -132,10 +276,10 @@ impl Rag {
         &mut self,
         document_paths: &[String],
         refresh: bool,
-        config: &GlobalConfig,
+        app: &AppConfig,
         abort_signal: AbortSignal,
     ) -> Result<()> {
-        let loaders = config.read().document_loaders.clone();
+        let loaders = app.document_loaders.clone();
         let (spinner, spinner_rx) = Spinner::create("");
         abortable_run_with_spinner_rx(
             self.sync_documents(document_paths, refresh, loaders, Some(spinner)),
@@ -149,22 +293,17 @@ impl Rag {
         Ok(())
     }
 
-    pub fn create_config(config: &GlobalConfig) -> Result<(Model, usize, usize)> {
-        let (embedding_model_id, chunk_size, chunk_overlap) = {
-            let config = config.read();
-            (
-                config.rag_embedding_model.clone(),
-                config.rag_chunk_size,
-                config.rag_chunk_overlap,
-            )
-        };
+    pub fn create_config(app: &AppConfig) -> Result<(Model, usize, usize)> {
+        let embedding_model_id = app.rag_embedding_model.clone();
+        let chunk_size = app.rag_chunk_size;
+        let chunk_overlap = app.rag_chunk_overlap;
         let embedding_model_id = match embedding_model_id {
             Some(value) => {
                 println!("Select embedding model: {value}");
                 value
             }
             None => {
-                let models = list_models(&config.read(), ModelType::Embedding);
+                let models = list_models(app, ModelType::Embedding);
                 if models.is_empty() {
                     bail!("No available embedding model");
                 }
@@ -172,7 +311,7 @@ impl Rag {
             }
         };
         let embedding_model =
-            Model::retrieve_model(&config.read(), &embedding_model_id, ModelType::Embedding)?;
+            Model::retrieve_model(app, &embedding_model_id, ModelType::Embedding)?;
 
         let chunk_size = match chunk_size {
             Some(value) => {
@@ -292,6 +431,14 @@ impl Rag {
         self.name == TEMP_RAG_NAME
     }
 
+    pub fn configured_top_k(&self) -> usize {
+        self.data.top_k
+    }
+
+    pub fn configured_reranker(&self) -> Option<&str> {
+        self.data.reranker_model.as_deref()
+    }
+
     pub async fn search(
         &self,
         text: &str,
@@ -300,7 +447,7 @@ impl Rag {
         abort_signal: AbortSignal,
     ) -> Result<(String, String, Vec<DocumentId>)> {
         let ret = abortable_run_with_spinner(
-            self.hybird_search(text, top_k, rerank_model),
+            self.hybrid_search(text, top_k, rerank_model),
             "Searching",
             abort_signal,
         )
@@ -319,6 +466,29 @@ impl Rag {
         Ok((embeddings, sources, ids))
     }
 
+    pub async fn search_with_template(
+        &self,
+        app: &AppConfig,
+        text: &str,
+        abort_signal: AbortSignal,
+    ) -> Result<String> {
+        let (reranker_model, top_k) = self.get_config();
+        let (embeddings, sources, ids) = self
+            .search(text, top_k, reranker_model.as_deref(), abort_signal)
+            .await?;
+        let rag_template = app.rag_template.as_deref().unwrap_or(RAG_TEMPLATE);
+        let text = if embeddings.is_empty() {
+            text.to_string()
+        } else {
+            rag_template
+                .replace("__CONTEXT__", &embeddings)
+                .replace("__SOURCES__", &sources)
+                .replace("__INPUT__", text)
+        };
+        self.set_last_sources(&ids);
+        Ok(text)
+    }
+
     fn resolve_source(&self, id: &DocumentId) -> String {
         let (file_index, _) = id.split();
         self.data
@@ -537,7 +707,7 @@ impl Rag {
         Ok(())
     }
 
-    async fn hybird_search(
+    async fn hybrid_search(
         &self,
         query: &str,
         top_k: usize,
@@ -560,9 +730,8 @@ impl Rag {
 
         let ids = match rerank_model {
             Some(model_id) => {
-                let model =
-                    Model::retrieve_model(&self.config.read(), model_id, ModelType::Reranker)?;
-                let client = init_client(&self.config, Some(model))?;
+                let model = Model::retrieve_model(&self.app_config, model_id, ModelType::Reranker)?;
+                let client = self.create_embeddings_client(model)?;
                 let ids: IndexSet<DocumentId> = [vector_search_ids, keyword_search_ids]
                     .concat()
                     .into_iter()
@@ -665,7 +834,7 @@ impl Rag {
         data: EmbeddingsData,
         spinner: Option<Spinner>,
     ) -> Result<EmbeddingsOutput> {
-        let embedding_client = init_client(&self.config, Some(self.embedding_model.clone()))?;
+        let embedding_client = self.create_embeddings_client(self.embedding_model.clone())?;
         let EmbeddingsData { texts, query } = data;
         let batch_size = self
             .data
@@ -736,7 +905,7 @@ pub struct RagData {
 }
 
 impl Debug for RagData {
-    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
+    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
         f.debug_struct("RagData")
             .field("embedding_model", &self.embedding_model)
             .field("chunk_size", &self.chunk_size)
@@ -864,7 +1033,7 @@ pub type FileId = usize;
 pub struct DocumentId(usize);
 
 impl Debug for DocumentId {
-    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
+    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
         let (file_index, document_index) = self.split();
         f.write_fmt(format_args!("{file_index}-{document_index}"))
     }
@@ -906,8 +1075,8 @@ impl SelectOption {
     }
 }
 
-impl std::fmt::Display for SelectOption {
-    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
+impl fmt::Display for SelectOption {
+    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
         write!(f, "{} ({})", self.value, self.description)
     }
 }
@@ -1021,10 +1190,7 @@ fn reciprocal_rank_fusion(
 ) -> Vec<DocumentId> {
     let rrf_k = top_k * 2;
     let mut map: IndexMap<DocumentId, f32> = IndexMap::new();
-    for (document_ids, weight) in list_of_document_ids
-        .into_iter()
-        .zip(list_of_weights.into_iter())
-    {
+    for (document_ids, weight) in list_of_document_ids.into_iter().zip(list_of_weights) {
         for (index, &item) in document_ids.iter().enumerate() {
             *map.entry(item).or_default() += (1.0 / ((rrf_k + index + 1) as f32)) * weight;
         }
@@ -1038,3 +1204,241 @@ fn reciprocal_rank_fusion(
         .map(|(v, _)| v)
         .collect()
 }
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn document_id_round_trip() {
+        let id = DocumentId::new(5, 17);
+        let (file, doc) = id.split();
+        assert_eq!(file, 5);
+        assert_eq!(doc, 17);
+    }
+
+    #[test]
+    fn document_id_zero_zero() {
+        let id = DocumentId::new(0, 0);
+        let (file, doc) = id.split();
+        assert_eq!(file, 0);
+        assert_eq!(doc, 0);
+    }
+
+    #[test]
+    fn document_id_large_values() {
+        let id = DocumentId::new(1000, 9999);
+        let (file, doc) = id.split();
+        assert_eq!(file, 1000);
+        assert_eq!(doc, 9999);
+    }
+
+    #[test]
+    fn document_id_debug_format() {
+        let id = DocumentId::new(3, 7);
+        let formatted = format!("{id:?}");
+        assert_eq!(formatted, "3-7");
+    }
+
+    #[test]
+    fn document_id_equality() {
+        let a = DocumentId::new(1, 2);
+        let b = DocumentId::new(1, 2);
+        assert_eq!(a, b);
+    }
+
+    #[test]
+    fn document_id_inequality() {
+        let a = DocumentId::new(1, 2);
+        let b = DocumentId::new(1, 3);
+        assert_ne!(a, b);
+    }
+
+    #[test]
+    fn document_id_ordering() {
+        let a = DocumentId::new(0, 1);
+        let b = DocumentId::new(1, 0);
+        assert!(a < b);
+    }
+
+    #[test]
+    fn rag_document_new() {
+        let doc = RagDocument::new("hello world");
+        assert_eq!(doc.page_content, "hello world");
+        assert!(doc.metadata.is_empty());
+    }
+
+    #[test]
+    fn rag_document_default() {
+        let doc = RagDocument::default();
+        assert_eq!(doc.page_content, "");
+        assert!(doc.metadata.is_empty());
+    }
+
+    #[test]
+    fn rag_data_new_defaults() {
+        let data = RagData::new("model".into(), 1000, 20, None, 5, None);
+        assert_eq!(data.embedding_model, "model");
+        assert_eq!(data.chunk_size, 1000);
+        assert_eq!(data.chunk_overlap, 20);
+        assert_eq!(data.top_k, 5);
+        assert!(data.reranker_model.is_none());
+        assert!(data.files.is_empty());
+        assert!(data.vectors.is_empty());
+        assert!(data.document_paths.is_empty());
+        assert_eq!(data.next_file_id, 0);
+    }
+
+    #[test]
+    fn rag_data_get_returns_document() {
+        let mut data = RagData::new("m".into(), 100, 10, None, 5, None);
+        let file = RagFile {
+            hash: "abc".into(),
+            path: "test.txt".into(),
+            documents: vec![RagDocument::new("first"), RagDocument::new("second")],
+        };
+        data.files.insert(0, file);
+
+        let doc = data.get(DocumentId::new(0, 0)).unwrap();
+        assert_eq!(doc.page_content, "first");
+
+        let doc = data.get(DocumentId::new(0, 1)).unwrap();
+        assert_eq!(doc.page_content, "second");
+    }
+
+    #[test]
+    fn rag_data_get_returns_none_for_missing_file() {
+        let data = RagData::new("m".into(), 100, 10, None, 5, None);
+        assert!(data.get(DocumentId::new(99, 0)).is_none());
+    }
+
+    #[test]
+    fn rag_data_get_returns_none_for_missing_document() {
+        let mut data = RagData::new("m".into(), 100, 10, None, 5, None);
+        let file = RagFile {
+            hash: "abc".into(),
+            path: "test.txt".into(),
+            documents: vec![RagDocument::new("only one")],
+        };
+        data.files.insert(0, file);
+        assert!(data.get(DocumentId::new(0, 5)).is_none());
+    }
+
+    #[test]
+    fn rag_data_del_removes_files_and_vectors() {
+        let mut data = RagData::new("m".into(), 100, 10, None, 5, None);
+        let file = RagFile {
+            hash: "abc".into(),
+            path: "test.txt".into(),
+            documents: vec![RagDocument::new("doc")],
+        };
+        data.files.insert(0, file);
+        let doc_id = DocumentId::new(0, 0);
+        data.vectors.insert(doc_id, vec![0.1, 0.2, 0.3]);
+
+        assert!(data.files.contains_key(&0));
+        assert!(data.vectors.contains_key(&doc_id));
+
+        data.del(vec![0]);
+
+        assert!(!data.files.contains_key(&0));
+        assert!(!data.vectors.contains_key(&doc_id));
+    }
+
+    #[test]
+    fn rag_data_del_nonexistent_is_noop() {
+        let mut data = RagData::new("m".into(), 100, 10, None, 5, None);
+        data.del(vec![99]);
+        assert!(data.files.is_empty());
+    }
+
+    #[test]
+    fn rag_data_add_inserts_files_and_vectors() {
+        let mut data = RagData::new("m".into(), 100, 10, None, 5, None);
+        let file = RagFile {
+            hash: "xyz".into(),
+            path: "new.txt".into(),
+            documents: vec![RagDocument::new("content")],
+        };
+        let doc_id = DocumentId::new(0, 0);
+        let embeddings = vec![vec![0.5, 0.6, 0.7]];
+
+        data.add(1, vec![(0, file)], vec![doc_id], embeddings);
+
+        assert_eq!(data.next_file_id, 1);
+        assert!(data.files.contains_key(&0));
+        assert!(data.vectors.contains_key(&doc_id));
+        assert_eq!(data.vectors[&doc_id], vec![0.5, 0.6, 0.7]);
+    }
+
+    #[test]
+    fn rag_template_contains_placeholders() {
+        assert!(RAG_TEMPLATE.contains("__CONTEXT__"));
+        assert!(RAG_TEMPLATE.contains("__SOURCES__"));
+        assert!(RAG_TEMPLATE.contains("__INPUT__"));
+    }
+
+    #[test]
+    fn get_separators_returns_language_specific() {
+        let rs_seps = get_separators("rs");
+        assert!(rs_seps.iter().any(|s| s.contains("fn ")));
+
+        let py_seps = get_separators("py");
+        assert!(py_seps.iter().any(|s| s.contains("def ")));
+
+        let md_seps = get_separators("md");
+        assert!(md_seps.iter().any(|s| s.contains("# ")));
+    }
+
+    #[test]
+    fn get_separators_unknown_returns_defaults() {
+        let seps = get_separators("xyz");
+        assert_eq!(seps, DEFAULT_SEPARATORS.to_vec());
+    }
+
+    #[test]
+    fn get_separators_all_known_extensions() {
+        let known = [
+            "c", "cc", "cpp", "go", "java", "js", "mjs", "cjs", "php", "proto", "py", "rst", "rb",
+            "rs", "scala", "swift", "md", "mkd", "tex", "htm", "html", "sol",
+        ];
+        for ext in known {
+            let seps = get_separators(ext);
+            assert_ne!(
+                seps,
+                DEFAULT_SEPARATORS.to_vec(),
+                "Extension '{ext}' should have language-specific separators"
+            );
+        }
+    }
+
+    #[test]
+    fn rag_data_build_bm25_empty() {
+        let data = RagData::new("m".into(), 100, 10, None, 5, None);
+        let engine = data.build_bm25();
+        let results = engine.search("anything", 5);
+        assert!(results.is_empty());
+    }
+
+    #[test]
+    fn rag_data_build_bm25_finds_documents() {
+        let mut data = RagData::new("m".into(), 100, 10, None, 5, None);
+        let file = RagFile {
+            hash: "h".into(),
+            path: "test.txt".into(),
+            documents: vec![
+                RagDocument::new("rust programming language"),
+                RagDocument::new("python scripting language"),
+            ],
+        };
+        data.files.insert(0, file);
+
+        let engine = data.build_bm25();
+        let results = engine.search("rust", 5);
+        assert!(!results.is_empty());
+        let top = &results[0];
+        let (file_idx, doc_idx) = top.document.id.split();
+        assert_eq!(file_idx, 0);
+        assert_eq!(doc_idx, 0);
+    }
+}
diff --git a/src/rag/splitter/mod.rs b/src/rag/splitter/mod.rs
index c6bb6ff..edfa500 100644
--- a/src/rag/splitter/mod.rs
+++ b/src/rag/splitter/mod.rs
@@ -171,7 +171,6 @@ impl RecursiveCharacterTextSplitter {
             }
         }
 
-        // Now that we have the separator, split the text
         let splits = split_on_separator(text, &separator, keep_separator);
 
         // Now go merging things, recursively splitting longer texts.
diff --git a/src/render/mod.rs b/src/render/mod.rs
index 15b186e..8bf2baa 100644
--- a/src/render/mod.rs
+++ b/src/render/mod.rs
@@ -8,18 +8,22 @@ pub use self::markdown::{MarkdownRender, RenderOptions};
 use self::stream::{markdown_stream, raw_stream};
 
 use crate::utils::{AbortSignal, IS_STDOUT_TERMINAL, error_text, pretty_error};
-use crate::{client::SseEvent, config::GlobalConfig};
+use crate::{client::SseEvent, config::AppConfig};
 
 use anyhow::Result;
 use tokio::sync::mpsc::UnboundedReceiver;
 
 pub async fn render_stream(
     rx: UnboundedReceiver<SseEvent>,
-    config: &GlobalConfig,
+    app: &AppConfig,
     abort_signal: AbortSignal,
+    silent: bool,
 ) -> Result<()> {
-    let ret = if *IS_STDOUT_TERMINAL && config.read().highlight {
-        let render_options = config.read().render_options()?;
+    if silent {
+        return drain_silently(rx, &abort_signal).await;
+    }
+    let ret = if *IS_STDOUT_TERMINAL && app.highlight {
+        let render_options = app.render_options()?;
         let mut render = MarkdownRender::init(render_options)?;
         markdown_stream(rx, &mut render, &abort_signal).await
     } else {
@@ -28,6 +32,22 @@ pub async fn render_stream(
     ret.map_err(|err| err.context("Failed to reader stream"))
 }
 
+async fn drain_silently(
+    mut rx: UnboundedReceiver<SseEvent>,
+    abort_signal: &AbortSignal,
+) -> Result<()> {
+    loop {
+        if abort_signal.aborted() {
+            break;
+        }
+        match rx.recv().await {
+            Some(SseEvent::Done) | None => break,
+            Some(SseEvent::Text(_)) => {}
+        }
+    }
+    Ok(())
+}
+
 pub fn render_error(err: anyhow::Error) {
     eprintln!("{}", error_text(&pretty_error(&err)));
 }
diff --git a/src/render/stream.rs b/src/render/stream.rs
index 0c0a3e1..5c070a2 100644
--- a/src/render/stream.rs
+++ b/src/render/stream.rs
@@ -2,7 +2,7 @@ use super::{MarkdownRender, SseEvent};
 
 use crate::utils::{AbortSignal, poll_abort_signal, spawn_spinner};
 
-use anyhow::Result;
+use anyhow::{Error, Result};
 use crossterm::{
     cursor, queue, style,
     terminal::{self, disable_raw_mode, enable_raw_mode},
@@ -96,7 +96,7 @@ async fn markdown_stream_inner(
                         match cursor::position() {
                             Ok(pos) => break pos,
                             Err(_) if attempts < 3 => attempts += 1,
-                            Err(e) => return Err(e.into()),
+                            Err(e) => return Err(Error::from(e)),
                         }
                     };
 
diff --git a/src/repl/completer.rs b/src/repl/completer.rs
index dd60a79..cad23d6 100644
--- a/src/repl/completer.rs
+++ b/src/repl/completer.rs
@@ -1,9 +1,11 @@
 use super::{REPL_COMMANDS, ReplCommand};
 
-use crate::{config::GlobalConfig, utils::fuzzy_filter};
+use crate::{config::RequestContext, utils::fuzzy_filter};
 
+use parking_lot::RwLock;
 use reedline::{Completer, Span, Suggestion};
 use std::collections::HashMap;
+use std::sync::Arc;
 
 impl Completer for ReplCompleter {
     fn complete(&mut self, line: &str, pos: usize) -> Vec<Suggestion> {
@@ -27,7 +29,8 @@ impl Completer for ReplCompleter {
             return suggestions;
         }
 
-        let state = self.config.read().state();
+        let ctx = self.ctx.read();
+        let state = ctx.state();
 
         let command_filter = parts
             .iter()
@@ -49,16 +52,12 @@ impl Completer for ReplCompleter {
             let span = Span::new(parts[parts_len - 1].1, pos);
             let args_line = &line[parts[1].1..];
             let args: Vec<&str> = parts.iter().skip(1).map(|(v, _)| *v).collect();
-            suggestions.extend(
-                self.config
-                    .read()
-                    .repl_complete(cmd, &args, args_line)
-                    .iter()
-                    .map(|(value, description)| {
-                        let description = description.as_deref().unwrap_or_default();
-                        create_suggestion(value, description, span)
-                    }),
-            )
+            suggestions.extend(ctx.repl_complete(cmd, &args, args_line).iter().map(
+                |(value, description)| {
+                    let description = description.as_deref().unwrap_or_default();
+                    create_suggestion(value, description, span)
+                },
+            ))
         }
 
         if suggestions.is_empty() {
@@ -80,13 +79,13 @@ impl Completer for ReplCompleter {
 }
 
 pub struct ReplCompleter {
-    config: GlobalConfig,
+    ctx: Arc<RwLock<RequestContext>>,
     commands: Vec<ReplCommand>,
     groups: HashMap<&'static str, usize>,
 }
 
 impl ReplCompleter {
-    pub fn new(config: &GlobalConfig) -> Self {
+    pub fn new(ctx: Arc<RwLock<RequestContext>>) -> Self {
         let mut groups = HashMap::new();
 
         let commands: Vec<ReplCommand> = REPL_COMMANDS.to_vec();
@@ -97,7 +96,7 @@ impl ReplCompleter {
         }
 
         Self {
-            config: config.clone(),
+            ctx,
             commands,
             groups,
         }
@@ -111,12 +110,14 @@ fn create_suggestion(value: &str, description: &str, span: Span) -> Suggestion {
         Some(description.to_string())
     };
     Suggestion {
+        display_override: None,
         value: value.to_string(),
         description,
         style: None,
         extra: None,
         span,
         append_whitespace: false,
+        match_indices: None,
     }
 }
 
diff --git a/src/repl/highlighter.rs b/src/repl/highlighter.rs
index ab6174c..60c6d5f 100644
--- a/src/repl/highlighter.rs
+++ b/src/repl/highlighter.rs
@@ -1,6 +1,6 @@
 use super::REPL_COMMANDS;
 
-use crate::{config::GlobalConfig, utils::NO_COLOR};
+use crate::utils::NO_COLOR;
 
 use nu_ansi_term::{Color, Style};
 use reedline::{Highlighter, StyledText};
@@ -11,7 +11,7 @@ const MATCH_COLOR: Color = Color::Green;
 pub struct ReplHighlighter;
 
 impl ReplHighlighter {
-    pub fn new(_config: &GlobalConfig) -> Self {
+    pub fn new() -> Self {
         Self
     }
 }
diff --git a/src/repl/mod.rs b/src/repl/mod.rs
index a4922aa..ff0ba6b 100644
--- a/src/repl/mod.rs
+++ b/src/repl/mod.rs
@@ -8,19 +8,22 @@ use self::prompt::ReplPrompt;
 
 use crate::client::{call_chat_completions, call_chat_completions_streaming, init_client, oauth};
 use crate::config::{
-    AgentVariables, AssertState, Config, GlobalConfig, Input, LastMessage, StateFlags,
+    AgentVariables, AppConfig, AssertState, Input, LastMessage, RequestContext, StateFlags,
     macro_execute,
 };
+use crate::config::{AssetCategory, paths};
 use crate::render::render_error;
 use crate::utils::{
     AbortSignal, abortable_run_with_spinner, create_abort_signal, dimmed_text, set_text, temp_file,
 };
 
-use crate::mcp::McpRegistry;
-use crate::resolve_oauth_client;
+use crate::{config, graph, resolve_oauth_client};
 use anyhow::{Context, Result, bail};
 use crossterm::cursor::SetCursorStyle;
 use fancy_regex::Regex;
+use indoc::indoc;
+use log::warn;
+use parking_lot::RwLock;
 use reedline::CursorConfig;
 use reedline::{
     ColumnarMenu, EditCommand, EditMode, Emacs, KeyCode, KeyModifiers, Keybindings, Reedline,
@@ -29,11 +32,21 @@ use reedline::{
 };
 use reedline::{MenuBuilder, Signal};
 use std::sync::LazyLock;
-use std::{env, mem, process};
+use std::{env, process, sync::Arc};
+use tokio::task;
 
 const MENU_NAME: &str = "completion_menu";
 
-static REPL_COMMANDS: LazyLock<[ReplCommand; 39]> = LazyLock::new(|| {
+pub const DEFAULT_CONTINUATION_PROMPT: &str = indoc! {"
+    [SYSTEM REMINDER - TODO CONTINUATION]
+    You have incomplete tasks. Rules:
+    1. BEFORE marking a todo done: verify the work compiles/works. No premature completion.
+    2. If a todo is broad (e.g. \"implement X and implement Y\"): break it into specific subtasks FIRST using todo__add, then work on those.\n\
+    3. Each todo should be atomic and be \"single responsibility\" - completable in one focused action.
+    4. Continue with the next pending item now. Call tools immediately."
+};
+
+static REPL_COMMANDS: LazyLock<[ReplCommand; 42]> = LazyLock::new(|| {
     [
         ReplCommand::new(".help", "Show this help guide", AssertState::pass()),
         ReplCommand::new(".info", "Show system info", AssertState::pass()),
@@ -47,6 +60,11 @@ static REPL_COMMANDS: LazyLock<[ReplCommand; 39]> = LazyLock::new(|| {
             "Modify configuration file",
             AssertState::False(StateFlags::AGENT),
         ),
+        ReplCommand::new(
+            ".edit mcp-config",
+            "Modify the MCP servers configuration file",
+            AssertState::False(StateFlags::AGENT),
+        ),
         ReplCommand::new(".model", "Switch LLM model", AssertState::pass()),
         ReplCommand::new(
             ".prompt",
@@ -140,7 +158,7 @@ static REPL_COMMANDS: LazyLock<[ReplCommand; 39]> = LazyLock::new(|| {
         ReplCommand::new(
             ".clear todo",
             "Clear the todo list and stop auto-continuation",
-            AssertState::True(StateFlags::AGENT),
+            AssertState::pass(),
         ),
         ReplCommand::new(
             ".rag",
@@ -200,6 +218,16 @@ static REPL_COMMANDS: LazyLock<[ReplCommand; 39]> = LazyLock::new(|| {
             "View or modify the Loki vault",
             AssertState::pass(),
         ),
+        ReplCommand::new(
+            ".install",
+            "Reinstall bundled assets, or install assets from a remote git repo (.install remote <url>)",
+            AssertState::pass(),
+        ),
+        ReplCommand::new(
+            ".update",
+            "Update Loki to the latest release (or a specified version)",
+            AssertState::pass(),
+        ),
         ReplCommand::new(".exit", "Exit REPL", AssertState::pass()),
     ]
 });
@@ -208,31 +236,31 @@ static MULTILINE_RE: LazyLock<Regex> =
     LazyLock::new(|| Regex::new(r"(?s)^\s*:::\s*(.*)\s*:::\s*$").unwrap());
 
 pub struct Repl {
-    config: GlobalConfig,
+    ctx: Arc<RwLock<RequestContext>>,
     editor: Reedline,
     prompt: ReplPrompt,
     abort_signal: AbortSignal,
 }
 
 impl Repl {
-    pub fn init(config: &GlobalConfig) -> Result<Self> {
-        let editor = Self::create_editor(config)?;
-
-        let prompt = ReplPrompt::new(config);
+    pub fn init(ctx: RequestContext) -> Result<Self> {
+        let app = Arc::clone(&ctx.app.config);
+        let ctx = Arc::new(RwLock::new(ctx));
+        let editor = Self::create_editor(Arc::clone(&ctx), app.as_ref())?;
+        let prompt = ReplPrompt::new(Arc::clone(&ctx));
         let abort_signal = create_abort_signal();
 
         Ok(Self {
-            config: config.clone(),
+            ctx,
             editor,
             prompt,
             abort_signal,
         })
     }
 
+    #[allow(clippy::await_holding_lock)]
     pub async fn run(&mut self) -> Result<()> {
-        if AssertState::False(StateFlags::AGENT | StateFlags::RAG)
-            .assert(self.config.read().state())
-        {
+        if AssertState::False(StateFlags::AGENT | StateFlags::RAG).assert(self.ctx.read().state()) {
             print!(
                 r#"Welcome to {} {}
 Type ".help" for additional help.
@@ -250,7 +278,11 @@ Type ".help" for additional help.
             match sig {
                 Ok(Signal::Success(line)) => {
                     self.abort_signal.reset();
-                    match run_repl_command(&self.config, self.abort_signal.clone(), &line).await {
+                    let result = {
+                        let mut ctx = self.ctx.write();
+                        run_repl_command(&mut ctx, self.abort_signal.clone(), &line).await
+                    };
+                    match result {
                         Ok(exit) => {
                             if exit {
                                 break;
@@ -273,15 +305,15 @@ Type ".help" for additional help.
                 _ => {}
             }
         }
-        self.config.write().exit_session()?;
+        self.ctx.write().exit_session()?;
         Ok(())
     }
 
-    fn create_editor(config: &GlobalConfig) -> Result<Reedline> {
-        let completer = ReplCompleter::new(config);
-        let highlighter = ReplHighlighter::new(config);
+    fn create_editor(ctx: Arc<RwLock<RequestContext>>, app: &AppConfig) -> Result<Reedline> {
+        let completer = ReplCompleter::new(Arc::clone(&ctx));
+        let highlighter = ReplHighlighter::new();
         let menu = Self::create_menu();
-        let edit_mode = Self::create_edit_mode(config);
+        let edit_mode = Self::create_edit_mode(app);
         let cursor_config = CursorConfig {
             vi_insert: Some(SetCursorStyle::BlinkingBar),
             vi_normal: Some(SetCursorStyle::SteadyBlock),
@@ -299,7 +331,7 @@ Type ".help" for additional help.
             .with_validator(Box::new(ReplValidator))
             .with_ansi_colors(true);
 
-        if let Ok(cmd) = config.read().editor() {
+        if let Ok(cmd) = app.editor() {
             let temp_file = temp_file("-repl-", ".md");
             let command = process::Command::new(cmd);
             editor = editor.with_buffer_editor(command, temp_file);
@@ -334,8 +366,8 @@ Type ".help" for additional help.
         );
     }
 
-    fn create_edit_mode(config: &GlobalConfig) -> Box<dyn EditMode> {
-        let edit_mode: Box<dyn EditMode> = if config.read().keybindings == "vi" {
+    fn create_edit_mode(app: &AppConfig) -> Box<dyn EditMode> {
+        let edit_mode: Box<dyn EditMode> = if app.keybindings == "vi" {
             let mut insert_keybindings = default_vi_insert_keybindings();
             Self::extra_keybindings(&mut insert_keybindings);
             Box::new(Vi::new(insert_keybindings, default_vi_normal_keybindings()))
@@ -389,7 +421,7 @@ impl Validator for ReplValidator {
 }
 
 pub async fn run_repl_command(
-    config: &GlobalConfig,
+    ctx: &mut RequestContext,
     abort_signal: AbortSignal,
     mut line: &str,
 ) -> Result<bool> {
@@ -405,66 +437,74 @@ pub async fn run_repl_command(
             }
             ".info" => match args {
                 Some("role") => {
-                    let info = config.read().role_info()?;
+                    let info = ctx.role_info()?;
                     print!("{info}");
                 }
                 Some("session") => {
-                    let info = config.read().session_info()?;
+                    let app = Arc::clone(&ctx.app.config);
+                    let info = ctx.session_info(app.as_ref())?;
                     print!("{info}");
                 }
                 Some("rag") => {
-                    let info = config.read().rag_info()?;
+                    let info = ctx.rag_info()?;
                     print!("{info}");
                 }
                 Some("agent") => {
-                    let info = config.read().agent_info()?;
+                    let info = ctx.agent_info()?;
                     print!("{info}");
                 }
                 Some(_) => unknown_command()?,
                 None => {
-                    let output = config.read().sysinfo()?;
+                    let app = Arc::clone(&ctx.app.config);
+                    let output = ctx.sysinfo(app.as_ref())?;
                     print!("{output}");
                 }
             },
             ".model" => match args {
                 Some(name) => {
-                    config.write().set_model(name)?;
+                    let app = Arc::clone(&ctx.app.config);
+                    ctx.set_model_on_role_like(app.as_ref(), name)?;
                 }
                 None => println!("Usage: .model <name>"),
             },
             ".authenticate" => {
-                let current_model = config.read().current_model().clone();
-                let client = init_client(config, Some(current_model))?;
+                let current_model = ctx.current_model().clone();
+                let app = Arc::clone(&ctx.app.config);
+                let client = init_client(&app, current_model)?;
                 if !client.supports_oauth() {
                     bail!(
                         "Client '{}' doesn't either support OAuth or isn't configured to use it (i.e. uses an API key instead)",
                         client.name()
                     );
                 }
-                let clients = config.read().clients.clone();
+                let clients = ctx.app.config.clients.clone();
                 let (client_name, provider) = resolve_oauth_client(Some(client.name()), &clients)?;
                 oauth::run_oauth_flow(&*provider, &client_name).await?;
             }
             ".prompt" => match args {
                 Some(text) => {
-                    config.write().use_prompt(text)?;
+                    let app = Arc::clone(&ctx.app.config);
+                    ctx.use_prompt(app.as_ref(), text)?;
                 }
                 None => println!("Usage: .prompt <text>..."),
             },
             ".role" => match args {
                 Some(args) => match args.split_once(['\n', ' ']) {
                     Some((name, text)) => {
-                        let role = config.read().retrieve_role(name.trim())?;
-                        let input = Input::from_str(config, text, Some(role));
-                        ask(config, abort_signal.clone(), input, false).await?;
+                        let app = Arc::clone(&ctx.app.config);
+                        let role = ctx.retrieve_role(app.as_ref(), name.trim())?;
+                        let input = Input::from_str(ctx, text, Some(role));
+                        ask(ctx, abort_signal.clone(), input, false).await?;
                     }
                     None => {
                         let name = args;
-                        if !Config::has_role(name) {
-                            config.write().new_role(name)?;
+                        let app = Arc::clone(&ctx.app.config);
+                        if !paths::has_role(name) {
+                            ctx.new_role(app.as_ref(), name)?;
                         }
 
-                        Config::use_role_safely(config, name, abort_signal.clone()).await?;
+                        ctx.use_role(app.as_ref(), name, abort_signal.clone())
+                            .await?;
                     }
                 },
                 None => println!(
@@ -474,11 +514,60 @@ pub async fn run_repl_command(
                 ),
             },
             ".session" => {
-                Config::use_session_safely(config, args, abort_signal.clone()).await?;
-                Config::maybe_autoname_session(config.clone());
+                if let Some(name) = graph::active_agent_graph_name(ctx) {
+                    bail!(
+                        "Graph-based agent '{name}' does not support sessions. \
+                         The graph manages its own state."
+                    );
+                }
+                let app = Arc::clone(&ctx.app.config);
+                ctx.use_session(app.as_ref(), args, abort_signal.clone())
+                    .await?;
+                if ctx.maybe_autoname_session() {
+                    let color = if app.light_theme() {
+                        nu_ansi_term::Color::LightGray
+                    } else {
+                        nu_ansi_term::Color::DarkGray
+                    };
+                    eprintln!("\n📢 {}", color.italic().paint("Autonaming the session."),);
+                    if let Err(err) = ctx.autoname_session(app.as_ref()).await {
+                        warn!("Failed to autonaming the session: {err}");
+                    }
+                    if let Some(session) = ctx.session.as_mut() {
+                        session.set_autonaming(false);
+                    }
+                }
+            }
+            ".install" => {
+                let trimmed = args.map(str::trim).unwrap_or("");
+                let mut parts = trimmed.splitn(2, char::is_whitespace);
+                match parts.next() {
+                    Some("remote") => {
+                        let rest = parts.next().unwrap_or("").trim();
+                        config::install_remote_from_repl_args(rest)?;
+                    }
+                    Some(name) if !name.is_empty() => match AssetCategory::parse(name) {
+                        Some(category) => config::install_assets(category)?,
+                        None => println!(
+                            "Unknown asset category '{name}'. Valid categories: {}",
+                            AssetCategory::NAMES.join(", ")
+                        ),
+                    },
+                    _ => println!(
+                        "Usage: .install <{}> | .install remote <git-url>",
+                        AssetCategory::NAMES.join("|")
+                    ),
+                }
+            }
+            ".update" => {
+                if ctx.macro_flag {
+                    bail!("Cannot perform this operation because you are in a macro")
+                }
+                let version = args.map(|s| s.trim().to_string());
+                task::spawn_blocking(move || config::run_self_update(version, false)).await??;
             }
             ".rag" => {
-                Config::use_rag(config, args, abort_signal.clone()).await?;
+                ctx.use_rag(args, abort_signal.clone()).await?;
             }
             ".agent" => match split_first_arg(args) {
                 Some((agent_name, args)) => {
@@ -497,13 +586,11 @@ pub async fn run_repl_command(
                         bail!("Some variable values are not key=value pairs");
                     }
                     if !variables.is_empty() {
-                        config.write().agent_variables = Some(variables);
+                        ctx.agent_variables = Some(variables.clone());
                     }
-                    let ret =
-                        Config::use_agent(config, agent_name, session_name, abort_signal.clone())
-                            .await;
-                    config.write().agent_variables = None;
-                    ret?;
+                    let app = Arc::clone(&ctx.app.config);
+                    ctx.use_agent(app.as_ref(), agent_name, session_name, abort_signal.clone())
+                        .await?;
                 }
                 None => {
                     println!(r#"Usage: .agent <agent-name> [session-name] [key=value]..."#)
@@ -512,7 +599,7 @@ pub async fn run_repl_command(
             ".starter" => match args {
                 Some(id) => {
                     let mut text = None;
-                    if let Some(agent) = config.read().agent.as_ref() {
+                    if let Some(agent) = ctx.agent.as_ref() {
                         for (i, value) in agent.conversation_starters().iter().enumerate() {
                             if (i + 1).to_string() == id {
                                 text = Some(value.clone());
@@ -522,8 +609,8 @@ pub async fn run_repl_command(
                     match text {
                         Some(text) => {
                             println!("{}", dimmed_text(&format!(">> {text}")));
-                            let input = Input::from_str(config, &text, None);
-                            ask(config, abort_signal.clone(), input, true).await?;
+                            let input = Input::from_str(ctx, &text, None);
+                            ask(ctx, abort_signal.clone(), input, true).await?;
                         }
                         None => {
                             bail!("Invalid starter value");
@@ -531,60 +618,58 @@ pub async fn run_repl_command(
                     }
                 }
                 None => {
-                    let banner = config.read().agent_banner()?;
-                    config.read().print_markdown(&banner)?;
+                    let banner = ctx.agent_banner()?;
+                    ctx.app.config.print_markdown(&banner)?;
                 }
             },
             ".save" => match split_first_arg(args) {
                 Some(("role", name)) => {
-                    config.write().save_role(name)?;
+                    ctx.save_role(name)?;
                 }
                 Some(("session", name)) => {
-                    config.write().save_session(name)?;
+                    ctx.save_session(name)?;
                 }
                 _ => {
                     println!(r#"Usage: .save <role|session> [name]"#)
                 }
             },
             ".edit" => {
-                if config.read().macro_flag {
+                if ctx.macro_flag {
                     bail!("Cannot perform this operation because you are in a macro")
                 }
                 match args {
                     Some("config") => {
-                        config.read().edit_config()?;
+                        ctx.edit_config()?;
                     }
                     Some("role") => {
-                        let mut cfg = {
-                            let mut guard = config.write();
-                            mem::take(&mut *guard)
-                        };
-
-                        cfg.edit_role(abort_signal.clone()).await?;
-
-                        {
-                            let mut guard = config.write();
-                            *guard = cfg;
-                        }
+                        let app = Arc::clone(&ctx.app.config);
+                        ctx.edit_role(app.as_ref(), abort_signal.clone()).await?;
                     }
                     Some("session") => {
-                        config.write().edit_session()?;
+                        let app = Arc::clone(&ctx.app.config);
+                        ctx.edit_session(app.as_ref())?;
                     }
                     Some("rag-docs") => {
-                        Config::edit_rag_docs(config, abort_signal.clone()).await?;
+                        ctx.edit_rag_docs(abort_signal.clone()).await?;
                     }
                     Some("agent-config") => {
-                        config.write().edit_agent_config()?;
+                        let app = Arc::clone(&ctx.app.config);
+                        ctx.edit_agent_config(app.as_ref())?;
+                    }
+                    Some("mcp-config") => {
+                        ctx.edit_mcp_config()?;
                     }
                     _ => {
-                        println!(r#"Usage: .edit <config|role|session|rag-docs|agent-config>"#)
+                        println!(
+                            r#"Usage: .edit <config|mcp-config|role|session|rag-docs|agent-config>"#
+                        )
                     }
                 }
             }
             ".compress" => match args {
                 Some("session") => {
                     abortable_run_with_spinner(
-                        Config::compress_session(config),
+                        ctx.compress_session(),
                         "Compressing",
                         abort_signal.clone(),
                     )
@@ -597,7 +682,7 @@ pub async fn run_repl_command(
             },
             ".empty" => match args {
                 Some("session") => {
-                    config.write().empty_session()?;
+                    ctx.empty_session()?;
                 }
                 _ => {
                     println!(r#"Usage: .empty session"#)
@@ -605,7 +690,7 @@ pub async fn run_repl_command(
             },
             ".rebuild" => match args {
                 Some("rag") => {
-                    Config::rebuild_rag(config, abort_signal.clone()).await?;
+                    ctx.rebuild_rag(abort_signal.clone()).await?;
                 }
                 _ => {
                     println!(r#"Usage: .rebuild rag"#)
@@ -613,7 +698,7 @@ pub async fn run_repl_command(
             },
             ".sources" => match args {
                 Some("rag") => {
-                    let output = Config::rag_sources(config)?;
+                    let output = ctx.rag_sources()?;
                     println!("{output}");
                 }
                 _ => {
@@ -622,10 +707,11 @@ pub async fn run_repl_command(
             },
             ".macro" => match split_first_arg(args) {
                 Some((name, extra)) => {
-                    if !Config::has_macro(name) && extra.is_none() {
-                        config.write().new_macro(name)?;
+                    let app = Arc::clone(&ctx.app.config);
+                    if !paths::has_macro(name) && extra.is_none() {
+                        ctx.new_macro(app.as_ref(), name)?;
                     } else {
-                        macro_execute(config, name, extra, abort_signal.clone()).await?;
+                        macro_execute(ctx, name, extra, abort_signal.clone()).await?;
                     }
                 }
                 None => println!("Usage: .macro <name> <text>..."),
@@ -634,14 +720,14 @@ pub async fn run_repl_command(
                 Some(args) => {
                     let (files, text) = split_args_text(args, cfg!(windows));
                     let input = Input::from_files_with_spinner(
-                        config,
+                        ctx,
                         text,
                         files,
                         None,
                         abort_signal.clone(),
                     )
                     .await?;
-                    ask(config, abort_signal.clone(), input, true).await?;
+                    ask(ctx, abort_signal.clone(), input, true).await?;
                 }
                 None => println!(
                     r#"Usage: .file <file|dir|url|cmd|loader:resource|%%>... [-- <text>...]
@@ -658,8 +744,7 @@ pub async fn run_repl_command(
             ".continue" => {
                 let LastMessage {
                     mut input, output, ..
-                } = match config
-                    .read()
+                } = match ctx
                     .last_message
                     .as_ref()
                     .filter(|v| v.continuous && !v.output.is_empty())
@@ -669,25 +754,21 @@ pub async fn run_repl_command(
                     None => bail!("Unable to continue the response"),
                 };
                 input.set_continue_output(&output);
-                ask(config, abort_signal.clone(), input, true).await?;
+                ask(ctx, abort_signal.clone(), input, true).await?;
             }
             ".regenerate" => {
-                let LastMessage { mut input, .. } = match config
-                    .read()
-                    .last_message
-                    .as_ref()
-                    .filter(|v| v.continuous)
-                    .cloned()
-                {
-                    Some(v) => v,
-                    None => bail!("Unable to regenerate the response"),
-                };
-                input.set_regenerate();
-                ask(config, abort_signal.clone(), input, true).await?;
+                let LastMessage { mut input, .. } =
+                    match ctx.last_message.as_ref().filter(|v| v.continuous).cloned() {
+                        Some(v) => v,
+                        None => bail!("Unable to regenerate the response"),
+                    };
+                let app = Arc::clone(&ctx.app.config);
+                input.set_regenerate(ctx.extract_role(&app));
+                ask(ctx, abort_signal.clone(), input, true).await?;
             }
             ".set" => match args {
                 Some(args) => {
-                    Config::update(config, args, abort_signal).await?;
+                    ctx.update(args, abort_signal).await?;
                 }
                 _ => {
                     println!("Usage: .set <key> <value>...")
@@ -695,15 +776,14 @@ pub async fn run_repl_command(
             },
             ".delete" => match args {
                 Some(args) => {
-                    Config::delete(config, args)?;
+                    ctx.delete(args)?;
                 }
                 _ => {
                     println!("Usage: .delete <role|session|rag|macro|agent-data>")
                 }
             },
             ".copy" => {
-                let output = match config
-                    .read()
+                let output = match ctx
                     .last_message
                     .as_ref()
                     .filter(|v| !v.output.is_empty())
@@ -716,89 +796,29 @@ pub async fn run_repl_command(
             }
             ".exit" => match args {
                 Some("role") => {
-                    config.write().exit_role()?;
-                    config.write().functions.clear_mcp_meta_functions();
-
-                    let registry = config
-                        .write()
-                        .mcp_registry
-                        .take()
-                        .expect("MCP registry should exist");
-                    let enabled_mcp_servers = if config.read().mcp_server_support {
-                        config.read().enabled_mcp_servers.clone()
-                    } else {
-                        None
-                    };
-                    let registry =
-                        McpRegistry::reinit(registry, enabled_mcp_servers, abort_signal.clone())
-                            .await?;
-                    if !registry.is_empty() {
-                        config
-                            .write()
-                            .functions
-                            .append_mcp_meta_functions(registry.list_started_servers());
-                    }
-                    config.write().mcp_registry = Some(registry);
+                    ctx.exit_role()?;
+                    let app = Arc::clone(&ctx.app.config);
+                    ctx.bootstrap_tools(app.as_ref(), true, abort_signal.clone())
+                        .await?;
                 }
                 Some("session") => {
-                    if config.read().agent.is_some() {
-                        config.write().exit_agent_session()?;
-                        config.write().functions.clear_mcp_meta_functions();
-
-                        let registry = config
-                            .write()
-                            .mcp_registry
-                            .take()
-                            .expect("MCP registry should exist");
-                        let enabled_mcp_servers = if config.read().mcp_server_support {
-                            config.read().enabled_mcp_servers.clone()
-                        } else {
-                            None
-                        };
-                        let registry = McpRegistry::reinit(
-                            registry,
-                            enabled_mcp_servers,
-                            abort_signal.clone(),
-                        )
-                        .await?;
-                        if !registry.is_empty() {
-                            config
-                                .write()
-                                .functions
-                                .append_mcp_meta_functions(registry.list_started_servers());
-                        }
-                        config.write().mcp_registry = Some(registry);
+                    if ctx.agent.is_some() {
+                        ctx.exit_agent_session()?;
                     } else {
-                        config.write().exit_session()?;
+                        ctx.exit_session()?;
                     }
+                    let app = Arc::clone(&ctx.app.config);
+                    ctx.bootstrap_tools(app.as_ref(), true, abort_signal.clone())
+                        .await?;
                 }
                 Some("rag") => {
-                    config.write().exit_rag()?;
+                    ctx.exit_rag()?;
                 }
                 Some("agent") => {
-                    config.write().exit_agent()?;
-                    config.write().functions.clear_mcp_meta_functions();
-
-                    let registry = config
-                        .write()
-                        .mcp_registry
-                        .take()
-                        .expect("MCP registry should exist");
-                    let enabled_mcp_servers = if config.read().mcp_server_support {
-                        config.read().enabled_mcp_servers.clone()
-                    } else {
-                        None
-                    };
-                    let registry =
-                        McpRegistry::reinit(registry, enabled_mcp_servers, abort_signal.clone())
-                            .await?;
-                    if !registry.is_empty() {
-                        config
-                            .write()
-                            .functions
-                            .append_mcp_meta_functions(registry.list_started_servers());
-                    }
-                    config.write().mcp_registry = Some(registry);
+                    let app = Arc::clone(&ctx.app.config);
+                    ctx.exit_agent(app.as_ref())?;
+                    ctx.bootstrap_tools(app.as_ref(), true, abort_signal.clone())
+                        .await?;
                 }
                 Some(_) => unknown_command()?,
                 None => {
@@ -810,22 +830,17 @@ pub async fn run_repl_command(
                     bail!("Use '.empty session' instead");
                 }
                 Some("todo") => {
-                    let mut cfg = config.write();
-                    match cfg.agent.as_mut() {
-                        Some(agent) => {
-                            if !agent.auto_continue_enabled() {
-                                bail!(
-                                    "The todo system is not enabled for this agent. Set 'auto_continue: true' in the agent's config.yaml to enable it."
-                                );
-                            }
-                            if agent.todo_list().is_empty() {
-                                println!("Todo list is already empty.");
-                            } else {
-                                agent.clear_todo_list();
-                                println!("Todo list cleared.");
-                            }
-                        }
-                        None => bail!("No active agent"),
+                    let config = ctx.auto_continue_config();
+                    if !config.enabled {
+                        bail!(
+                            "Auto-continue is not enabled. Set 'auto_continue: true' in your config to enable it."
+                        );
+                    }
+                    if ctx.todo_list.is_empty() {
+                        println!("Todo list is already empty.");
+                    } else {
+                        ctx.clear_todo_list();
+                        println!("Todo list cleared.");
                     }
                 }
                 _ => unknown_command()?,
@@ -833,34 +848,34 @@ pub async fn run_repl_command(
             ".vault" => match split_first_arg(args) {
                 Some(("add", name)) => {
                     if let Some(name) = name {
-                        config.read().vault.add_secret(name)?;
+                        ctx.app.vault.add_secret(name)?;
                     } else {
                         println!("Usage: .vault add <name>");
                     }
                 }
                 Some(("get", name)) => {
                     if let Some(name) = name {
-                        config.read().vault.get_secret(name, true)?;
+                        ctx.app.vault.get_secret(name, true)?;
                     } else {
                         println!("Usage: .vault get <name>");
                     }
                 }
                 Some(("update", name)) => {
                     if let Some(name) = name {
-                        config.read().vault.update_secret(name)?;
+                        ctx.app.vault.update_secret(name)?;
                     } else {
                         println!("Usage: .vault update <name>");
                     }
                 }
                 Some(("delete", name)) => {
                     if let Some(name) = name {
-                        config.read().vault.delete_secret(name)?;
+                        ctx.app.vault.delete_secret(name)?;
                     } else {
                         println!("Usage: .vault delete <name>");
                     }
                 }
                 Some(("list", _)) => {
-                    config.read().vault.list_secrets(true)?;
+                    ctx.app.vault.list_secrets(true)?;
                 }
                 None | Some(_) => {
                     println!("Usage: .vault <add|get|update|delete|list> [name]")
@@ -869,20 +884,13 @@ pub async fn run_repl_command(
             _ => unknown_command()?,
         },
         None => {
-            if config
-                .read()
-                .agent
-                .as_ref()
-                .is_some_and(|a| a.continuation_count() > 0)
-            {
-                config.write().agent.as_mut().unwrap().reset_continuation();
-            }
-            let input = Input::from_str(config, line, None);
-            ask(config, abort_signal.clone(), input, true).await?;
+            reset_continuation(ctx);
+            let input = Input::from_str(ctx, line, None);
+            ask(ctx, abort_signal.clone(), input, true).await?;
         }
     }
 
-    if !config.read().macro_flag {
+    if !ctx.macro_flag {
         println!();
     }
 
@@ -891,7 +899,7 @@ pub async fn run_repl_command(
 
 #[async_recursion::async_recursion]
 async fn ask(
-    config: &GlobalConfig,
+    ctx: &mut RequestContext,
     abort_signal: AbortSignal,
     mut input: Input,
     with_embeddings: bool,
@@ -902,54 +910,64 @@ async fn ask(
     if with_embeddings {
         input.use_embeddings(abort_signal.clone()).await?;
     }
-    while config.read().is_compressing_session() {
+    while ctx.is_compressing_session() {
         tokio::time::sleep(std::time::Duration::from_millis(100)).await;
     }
 
+    let app = Arc::clone(&ctx.app.config);
+
+    if graph::active_agent_graph_name(ctx).is_some() {
+        ctx.before_chat_completion(&input)?;
+        let output =
+            graph::run_active_agent_graph(ctx, &input.text(), abort_signal.clone()).await?;
+        app.print_markdown(&output)?;
+        ctx.after_chat_completion(app.as_ref(), &input, &output, &[])?;
+        return Ok(());
+    }
+
     let client = input.create_client()?;
-    config.write().before_chat_completion(&input)?;
+    ctx.before_chat_completion(&input)?;
     let (output, tool_results) = if input.stream() {
-        call_chat_completions_streaming(&input, client.as_ref(), abort_signal.clone()).await?
+        call_chat_completions_streaming(&input, client.as_ref(), ctx, abort_signal.clone()).await?
     } else {
-        call_chat_completions(&input, true, false, client.as_ref(), abort_signal.clone()).await?
+        call_chat_completions(
+            &input,
+            true,
+            false,
+            client.as_ref(),
+            ctx,
+            abort_signal.clone(),
+        )
+        .await?
     };
-    config
-        .write()
-        .after_chat_completion(&input, &output, &tool_results)?;
+    ctx.after_chat_completion(app.as_ref(), &input, &output, &tool_results)?;
     if !tool_results.is_empty() {
         ask(
-            config,
+            ctx,
             abort_signal,
             input.merge_tool_results(output, tool_results),
             false,
         )
         .await
     } else {
-        let should_continue = {
-            let cfg = config.read();
-            if let Some(agent) = &cfg.agent {
-                agent.auto_continue_enabled()
-                    && agent.continuation_count() < agent.max_auto_continues()
-                    && agent.todo_list().has_incomplete()
-            } else {
-                false
-            }
-        };
+        let do_continue = should_continue(ctx);
 
-        if should_continue {
+        if do_continue {
             let full_prompt = {
-                let mut cfg = config.write();
-                let agent = cfg.agent.as_mut().expect("agent checked above");
-                agent.set_last_continuation_response(output.clone());
-                agent.increment_continuation();
-                let count = agent.continuation_count();
-                let max = agent.max_auto_continues();
+                let config = ctx.auto_continue_config();
+                let todo_state = ctx.todo_list.render_for_model();
+                let remaining = ctx.todo_list.incomplete_count();
+                ctx.set_last_continuation_response(output.clone());
+                ctx.increment_auto_continue_count();
+                let count = ctx.auto_continue_count;
+                let max = config.max_continues;
 
-                let todo_state = agent.todo_list().render_for_model();
-                let remaining = agent.todo_list().incomplete_count();
-                let prompt = agent.continuation_prompt();
+                let prompt = config
+                    .continuation_prompt
+                    .as_deref()
+                    .unwrap_or(DEFAULT_CONTINUATION_PROMPT);
 
-                let color = if cfg.light_theme() {
+                let color = if app.light_theme() {
                     nu_ansi_term::Color::LightGray
                 } else {
                     nu_ansi_term::Color::DarkGray
@@ -963,71 +981,66 @@ async fn ask(
 
                 format!("{prompt}\n\n{todo_state}")
             };
-            let continuation_input = Input::from_str(config, &full_prompt, None);
-            ask(config, abort_signal, continuation_input, false).await
+            let continuation_input = Input::from_str(ctx, &full_prompt, None);
+            ask(ctx, abort_signal, continuation_input, false).await
         } else {
-            if config
-                .read()
-                .agent
-                .as_ref()
-                .is_some_and(|a| a.continuation_count() > 0)
-            {
-                config.write().agent.as_mut().unwrap().reset_continuation();
+            reset_continuation(ctx);
+            if ctx.maybe_autoname_session() {
+                let color = if app.light_theme() {
+                    nu_ansi_term::Color::LightGray
+                } else {
+                    nu_ansi_term::Color::DarkGray
+                };
+                eprintln!("\n📢 {}", color.italic().paint("Autonaming the session."),);
+                if let Err(err) = ctx.autoname_session(app.as_ref()).await {
+                    warn!("Failed to autonaming the session: {err}");
+                }
+                if let Some(session) = ctx.session.as_mut() {
+                    session.set_autonaming(false);
+                }
             }
-            Config::maybe_autoname_session(config.clone());
 
-            let needs_compression = {
-                let cfg = config.read();
-                let compression_threshold = cfg.compression_threshold;
-                cfg.session
-                    .as_ref()
-                    .is_some_and(|s| s.needs_compression(compression_threshold))
-            };
+            let needs_compression = ctx
+                .session
+                .as_ref()
+                .is_some_and(|s| s.needs_compression(app.compression_threshold));
 
             if needs_compression {
-                let agent_can_continue_after_compress = {
-                    let cfg = config.read();
-                    cfg.agent.as_ref().is_some_and(|agent| {
-                        agent.auto_continue_enabled()
-                            && agent.continuation_count() < agent.max_auto_continues()
-                            && agent.todo_list().has_incomplete()
-                    })
-                };
+                let agent_can_continue_after_compress = should_continue(ctx);
 
-                {
-                    let mut cfg = config.write();
-                    if let Some(session) = cfg.session.as_mut() {
-                        session.set_compressing(true);
-                    }
+                if let Some(session) = ctx.session.as_mut() {
+                    session.set_compressing(true);
                 }
 
-                let color = if config.read().light_theme() {
+                let color = if app.light_theme() {
                     nu_ansi_term::Color::LightGray
                 } else {
                     nu_ansi_term::Color::DarkGray
                 };
                 eprintln!("\n📢 {}", color.italic().paint("Compressing the session."),);
 
-                if let Err(err) = Config::compress_session(config).await {
-                    log::warn!("Failed to compress the session: {err}");
+                if let Err(err) = ctx.compress_session().await {
+                    warn!("Failed to compress the session: {err}");
                 }
-                if let Some(session) = config.write().session.as_mut() {
+                if let Some(session) = ctx.session.as_mut() {
                     session.set_compressing(false);
                 }
 
                 if agent_can_continue_after_compress {
                     let full_prompt = {
-                        let mut cfg = config.write();
-                        let agent = cfg.agent.as_mut().expect("agent checked above");
-                        agent.increment_continuation();
-                        let count = agent.continuation_count();
-                        let max = agent.max_auto_continues();
+                        let config = ctx.auto_continue_config();
+                        let todo_state = ctx.todo_list.render_for_model();
+                        let remaining = ctx.todo_list.incomplete_count();
+                        ctx.increment_auto_continue_count();
+                        let count = ctx.auto_continue_count;
+                        let max = config.max_continues;
 
-                        let todo_state = agent.todo_list().render_for_model();
-                        let remaining = agent.todo_list().incomplete_count();
-                        let prompt = agent.continuation_prompt();
+                        let prompt = config
+                            .continuation_prompt
+                            .as_deref()
+                            .unwrap_or(DEFAULT_CONTINUATION_PROMPT);
 
-                        let color = if cfg.light_theme() {
+                        let color = if app.light_theme() {
                             nu_ansi_term::Color::LightGray
                         } else {
                             nu_ansi_term::Color::DarkGray
@@ -1041,11 +1054,9 @@ async fn ask(
 
                         format!("{prompt}\n\n{todo_state}")
                     };
-                    let continuation_input = Input::from_str(config, &full_prompt, None);
-                    return ask(config, abort_signal, continuation_input, false).await;
+                    let continuation_input = Input::from_str(ctx, &full_prompt, None);
+                    return ask(ctx, abort_signal, continuation_input, false).await;
                 }
-            } else {
-                Config::maybe_compress_session(config.clone());
             }
 
             Ok(())
@@ -1053,6 +1064,18 @@ async fn ask(
     }
 }
 
+fn should_continue(ctx: &RequestContext) -> bool {
+    let config = ctx.auto_continue_config();
+    ctx.app.config.function_calling_support
+        && config.enabled
+        && ctx.auto_continue_count < config.max_continues
+        && ctx.todo_list.has_incomplete()
+}
+
+fn reset_continuation(ctx: &mut RequestContext) {
+    ctx.reset_continuation_count();
+}
+
 fn unknown_command() -> Result<()> {
     bail!(r#"Unknown command. Type ".help" for additional help."#);
 }
@@ -1240,4 +1263,250 @@ mod tests {
             (vec![".\\file.txt".into(), "C:\\dir\\file.txt".into()], "")
         );
     }
+
+    #[test]
+    fn repl_commands_has_42_entries() {
+        assert_eq!(REPL_COMMANDS.len(), 42);
+    }
+
+    #[test]
+    fn repl_commands_all_start_with_dot() {
+        for cmd in REPL_COMMANDS.iter() {
+            assert!(
+                cmd.name.starts_with('.'),
+                "Command '{}' should start with '.'",
+                cmd.name
+            );
+        }
+    }
+
+    #[test]
+    fn repl_commands_no_empty_descriptions() {
+        for cmd in REPL_COMMANDS.iter() {
+            assert!(
+                !cmd.description.is_empty(),
+                "Command '{}' has empty description",
+                cmd.name
+            );
+        }
+    }
+
+    #[test]
+    fn repl_commands_help_is_always_available() {
+        let help = REPL_COMMANDS.iter().find(|c| c.name == ".help").unwrap();
+        assert!(help.is_valid(StateFlags::empty()));
+        assert!(help.is_valid(StateFlags::ROLE));
+        assert!(help.is_valid(StateFlags::AGENT));
+    }
+
+    #[test]
+    fn repl_commands_exit_is_always_available() {
+        let exit = REPL_COMMANDS.iter().find(|c| c.name == ".exit").unwrap();
+        assert!(exit.is_valid(StateFlags::empty()));
+        assert!(exit.is_valid(StateFlags::all()));
+    }
+
+    #[test]
+    fn repl_commands_info_role_requires_role() {
+        let cmd = REPL_COMMANDS
+            .iter()
+            .find(|c| c.name == ".info role")
+            .unwrap();
+        assert!(cmd.is_valid(StateFlags::ROLE));
+        assert!(!cmd.is_valid(StateFlags::empty()));
+        assert!(!cmd.is_valid(StateFlags::SESSION_EMPTY));
+    }
+
+    #[test]
+    fn repl_commands_session_blocked_when_already_in_session() {
+        let cmd = REPL_COMMANDS.iter().find(|c| c.name == ".session").unwrap();
+        assert!(cmd.is_valid(StateFlags::empty()));
+        assert!(!cmd.is_valid(StateFlags::SESSION));
+        assert!(!cmd.is_valid(StateFlags::SESSION_EMPTY));
+    }
+
+    #[test]
+    fn repl_commands_exit_session_requires_session() {
+        let cmd = REPL_COMMANDS
+            .iter()
+            .find(|c| c.name == ".exit session")
+            .unwrap();
+        assert!(cmd.is_valid(StateFlags::SESSION));
+        assert!(cmd.is_valid(StateFlags::SESSION_EMPTY));
+        assert!(!cmd.is_valid(StateFlags::empty()));
+    }
+
+    #[test]
+    fn repl_commands_exit_agent_requires_agent() {
+        let cmd = REPL_COMMANDS
+            .iter()
+            .find(|c| c.name == ".exit agent")
+            .unwrap();
+        assert!(cmd.is_valid(StateFlags::AGENT));
+        assert!(!cmd.is_valid(StateFlags::empty()));
+    }
+
+    #[test]
+    fn repl_commands_agent_only_when_bare() {
+        let cmd = REPL_COMMANDS.iter().find(|c| c.name == ".agent").unwrap();
+        assert!(cmd.is_valid(StateFlags::empty()));
+        assert!(!cmd.is_valid(StateFlags::ROLE));
+        assert!(!cmd.is_valid(StateFlags::SESSION));
+        assert!(!cmd.is_valid(StateFlags::AGENT));
+    }
+
+    #[test]
+    fn repl_commands_role_blocked_in_session_or_agent() {
+        let cmd = REPL_COMMANDS.iter().find(|c| c.name == ".role").unwrap();
+        assert!(cmd.is_valid(StateFlags::empty()));
+        assert!(!cmd.is_valid(StateFlags::SESSION));
+        assert!(!cmd.is_valid(StateFlags::AGENT));
+    }
+
+    #[test]
+    fn repl_commands_prompt_blocked_in_session_or_agent() {
+        let cmd = REPL_COMMANDS.iter().find(|c| c.name == ".prompt").unwrap();
+        assert!(cmd.is_valid(StateFlags::empty()));
+        assert!(cmd.is_valid(StateFlags::ROLE));
+        assert!(!cmd.is_valid(StateFlags::SESSION));
+        assert!(!cmd.is_valid(StateFlags::AGENT));
+    }
+
+    #[test]
+    fn repl_commands_rag_blocked_in_agent() {
+        let cmd = REPL_COMMANDS.iter().find(|c| c.name == ".rag").unwrap();
+        assert!(cmd.is_valid(StateFlags::empty()));
+        assert!(cmd.is_valid(StateFlags::ROLE));
+        assert!(!cmd.is_valid(StateFlags::AGENT));
+    }
+
+    #[test]
+    fn repl_commands_starter_requires_agent() {
+        let cmd = REPL_COMMANDS.iter().find(|c| c.name == ".starter").unwrap();
+        assert!(cmd.is_valid(StateFlags::AGENT));
+        assert!(!cmd.is_valid(StateFlags::empty()));
+    }
+
+    #[test]
+    fn repl_commands_clear_todo_always_available() {
+        let cmd = REPL_COMMANDS
+            .iter()
+            .find(|c| c.name == ".clear todo")
+            .unwrap();
+        assert!(cmd.is_valid(StateFlags::AGENT));
+        assert!(cmd.is_valid(StateFlags::empty()));
+        assert!(cmd.is_valid(StateFlags::SESSION));
+        assert!(cmd.is_valid(StateFlags::ROLE));
+    }
+
+    #[test]
+    fn repl_commands_edit_role_requires_role_not_session() {
+        let cmd = REPL_COMMANDS
+            .iter()
+            .find(|c| c.name == ".edit role")
+            .unwrap();
+        assert!(cmd.is_valid(StateFlags::ROLE));
+        assert!(!cmd.is_valid(StateFlags::empty()));
+        assert!(!cmd.is_valid(StateFlags::ROLE | StateFlags::SESSION));
+    }
+
+    #[test]
+    fn repl_commands_exit_rag_requires_rag_not_agent() {
+        let cmd = REPL_COMMANDS
+            .iter()
+            .find(|c| c.name == ".exit rag")
+            .unwrap();
+        assert!(cmd.is_valid(StateFlags::RAG));
+        assert!(!cmd.is_valid(StateFlags::empty()));
+        assert!(!cmd.is_valid(StateFlags::RAG | StateFlags::AGENT));
+    }
+
+    #[test]
+    fn parse_command_plain_text_returns_none() {
+        assert!(parse_command("hello world").is_none());
+    }
+
+    #[test]
+    fn parse_command_empty_returns_none() {
+        assert!(parse_command("").is_none());
+    }
+
+    #[test]
+    fn parse_command_whitespace_only_returns_none() {
+        assert!(parse_command("   ").is_none());
+    }
+
+    #[test]
+    fn parse_command_dot_only() {
+        assert_eq!(parse_command("."), Some((".", None)));
+    }
+
+    #[test]
+    fn split_first_arg_none_input() {
+        assert!(split_first_arg(None).is_none());
+    }
+
+    #[test]
+    fn split_first_arg_single_word() {
+        assert_eq!(split_first_arg(Some("role")), Some(("role", None)));
+    }
+
+    #[test]
+    fn split_first_arg_two_words() {
+        assert_eq!(
+            split_first_arg(Some("role test-role")),
+            Some(("role", Some("test-role")))
+        );
+    }
+
+    #[test]
+    fn split_first_arg_with_extra_spaces() {
+        assert_eq!(
+            split_first_arg(Some("session  my-session")),
+            Some(("session", Some("my-session")))
+        );
+    }
+
+    #[test]
+    fn repl_command_is_valid_pass_always_true() {
+        let cmd = ReplCommand::new(".test", "desc", AssertState::pass());
+        assert!(cmd.is_valid(StateFlags::empty()));
+        assert!(cmd.is_valid(StateFlags::all()));
+    }
+
+    #[test]
+    fn repl_command_is_valid_respects_true() {
+        let cmd = ReplCommand::new(".test", "desc", AssertState::True(StateFlags::ROLE));
+        assert!(cmd.is_valid(StateFlags::ROLE));
+        assert!(!cmd.is_valid(StateFlags::empty()));
+    }
+
+    #[test]
+    fn repl_command_is_valid_respects_false() {
+        let cmd = ReplCommand::new(".test", "desc", AssertState::False(StateFlags::AGENT));
+        assert!(cmd.is_valid(StateFlags::empty()));
+        assert!(!cmd.is_valid(StateFlags::AGENT));
+    }
+
+    #[test]
+    fn multiline_regex_captures_content_between_markers() {
+        let input = ":::\nhello world\n:::";
+        let captures = MULTILINE_RE.captures(input).unwrap().unwrap();
+        let content = captures.get(1).unwrap().as_str();
+        assert_eq!(content.trim(), "hello world");
+    }
+
+    #[test]
+    fn multiline_regex_does_not_match_single_marker() {
+        let input = ":::\nhello world";
+        let result = MULTILINE_RE.captures(input).unwrap();
+        assert!(result.is_none());
+    }
+
+    #[test]
+    fn multiline_regex_does_not_match_plain_text() {
+        let input = "hello world";
+        let result = MULTILINE_RE.captures(input).unwrap();
+        assert!(result.is_none());
+    }
 }
diff --git a/src/repl/prompt.rs b/src/repl/prompt.rs
index c57f981..8384321 100644
--- a/src/repl/prompt.rs
+++ b/src/repl/prompt.rs
@@ -1,28 +1,30 @@
-use crate::config::GlobalConfig;
+use crate::config::RequestContext;
 
+use parking_lot::RwLock;
 use reedline::{Prompt, PromptHistorySearch, PromptHistorySearchStatus};
 use std::borrow::Cow;
+use std::sync::Arc;
 
 #[derive(Clone)]
 pub struct ReplPrompt {
-    config: GlobalConfig,
+    ctx: Arc<RwLock<RequestContext>>,
 }
 
 impl ReplPrompt {
-    pub fn new(config: &GlobalConfig) -> Self {
-        Self {
-            config: config.clone(),
-        }
+    pub fn new(ctx: Arc<RwLock<RequestContext>>) -> Self {
+        Self { ctx }
     }
 }
 
 impl Prompt for ReplPrompt {
     fn render_prompt_left(&self) -> Cow<'_, str> {
-        Cow::Owned(self.config.read().render_prompt_left())
+        let ctx = self.ctx.read();
+        Cow::Owned(ctx.render_prompt_left(ctx.app.config.as_ref()))
     }
 
     fn render_prompt_right(&self) -> Cow<'_, str> {
-        Cow::Owned(self.config.read().render_prompt_right())
+        let ctx = self.ctx.read();
+        Cow::Owned(ctx.render_prompt_right(ctx.app.config.as_ref()))
     }
 
     fn render_prompt_indicator(&self, _prompt_mode: reedline::PromptEditMode) -> Cow<'_, str> {
diff --git a/src/supervisor/escalation.rs b/src/supervisor/escalation.rs
index 18a4533..3ad79b3 100644
--- a/src/supervisor/escalation.rs
+++ b/src/supervisor/escalation.rs
@@ -78,3 +78,122 @@ pub fn new_escalation_id() -> String {
     let short = &Uuid::new_v4().to_string()[..8];
     format!("esc_{short}")
 }
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    fn make_request(
+        id: &str,
+        agent_id: &str,
+        question: &str,
+    ) -> (EscalationRequest, oneshot::Receiver<String>) {
+        let (tx, rx) = oneshot::channel();
+        let req = EscalationRequest {
+            id: id.to_string(),
+            from_agent_id: agent_id.to_string(),
+            from_agent_name: "test-agent".to_string(),
+            question: question.to_string(),
+            options: None,
+            reply_tx: tx,
+        };
+        (req, rx)
+    }
+
+    #[test]
+    fn queue_default_has_no_pending() {
+        let queue = EscalationQueue::default();
+        assert!(!queue.has_pending());
+    }
+
+    #[test]
+    fn submit_and_has_pending() {
+        let queue = EscalationQueue::new();
+        let (req, _rx) = make_request("esc_1", "agent_1", "What color?");
+        queue.submit(req);
+        assert!(queue.has_pending());
+    }
+
+    #[test]
+    fn submit_returns_id() {
+        let queue = EscalationQueue::new();
+        let (req, _rx) = make_request("esc_42", "agent_1", "question");
+        let id = queue.submit(req);
+        assert_eq!(id, "esc_42");
+    }
+
+    #[test]
+    fn take_removes_request() {
+        let queue = EscalationQueue::new();
+        let (req, _rx) = make_request("esc_1", "agent_1", "question");
+        queue.submit(req);
+        let taken = queue.take("esc_1");
+        assert!(taken.is_some());
+        assert!(!queue.has_pending());
+    }
+
+    #[test]
+    fn take_nonexistent_returns_none() {
+        let queue = EscalationQueue::new();
+        assert!(queue.take("esc_missing").is_none());
+    }
+
+    #[test]
+    fn pending_summary_contains_fields() {
+        let queue = EscalationQueue::new();
+        let (req, _rx) = make_request("esc_1", "agent_x", "What to do?");
+        queue.submit(req);
+        let summary = queue.pending_summary();
+        assert_eq!(summary.len(), 1);
+        assert_eq!(summary[0]["escalation_id"], "esc_1");
+        assert_eq!(summary[0]["from_agent_id"], "agent_x");
+        assert_eq!(summary[0]["question"], "What to do?");
+    }
+
+    #[test]
+    fn pending_summary_includes_options_when_present() {
+        let queue = EscalationQueue::new();
+        let (tx, _rx) = oneshot::channel();
+        let req = EscalationRequest {
+            id: "esc_1".into(),
+            from_agent_id: "a".into(),
+            from_agent_name: "agent".into(),
+            question: "Pick one".into(),
+            options: Some(vec!["A".into(), "B".into()]),
+            reply_tx: tx,
+        };
+        queue.submit(req);
+        let summary = queue.pending_summary();
+        assert!(summary[0].get("options").is_some());
+    }
+
+    #[test]
+    fn pending_summary_empty_when_no_requests() {
+        let queue = EscalationQueue::new();
+        assert!(queue.pending_summary().is_empty());
+    }
+
+    #[test]
+    fn reply_reaches_receiver() {
+        let queue = EscalationQueue::new();
+        let (req, rx) = make_request("esc_1", "a", "question");
+        queue.submit(req);
+        let taken = queue.take("esc_1").unwrap();
+        taken.reply_tx.send("the answer".into()).unwrap();
+        assert_eq!(rx.blocking_recv().unwrap(), "the answer");
+    }
+
+    #[test]
+    fn new_escalation_id_has_prefix() {
+        let id = new_escalation_id();
+        assert!(id.starts_with("esc_"));
+        assert!(id.len() > 4);
+    }
+
+    #[test]
+    fn new_escalation_id_unique() {
+        let id1 = new_escalation_id();
+        let id2 = new_escalation_id();
+        assert_ne!(id1, id2);
+    }
+}
diff --git a/src/supervisor/mailbox.rs b/src/supervisor/mailbox.rs
index e0853f3..396f4cb 100644
--- a/src/supervisor/mailbox.rs
+++ b/src/supervisor/mailbox.rs
@@ -58,3 +58,122 @@ impl Clone for Inbox {
         }
     }
 }
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use chrono::Utc;
+
+    fn text_envelope(from: &str, to: &str, content: &str) -> Envelope {
+        Envelope {
+            from: from.to_string(),
+            to: to.to_string(),
+            payload: EnvelopePayload::Text {
+                content: content.to_string(),
+            },
+            timestamp: Utc::now(),
+        }
+    }
+
+    fn task_completed_envelope(from: &str, to: &str) -> Envelope {
+        Envelope {
+            from: from.to_string(),
+            to: to.to_string(),
+            payload: EnvelopePayload::TaskCompleted {
+                task_id: "t1".into(),
+                summary: "done".into(),
+            },
+            timestamp: Utc::now(),
+        }
+    }
+
+    fn shutdown_request_envelope(from: &str, to: &str) -> Envelope {
+        Envelope {
+            from: from.to_string(),
+            to: to.to_string(),
+            payload: EnvelopePayload::ShutdownRequest {
+                reason: "all done".into(),
+            },
+            timestamp: Utc::now(),
+        }
+    }
+
+    #[test]
+    fn inbox_new_is_empty() {
+        let inbox = Inbox::new();
+        assert!(inbox.drain().is_empty());
+    }
+
+    #[test]
+    fn inbox_default_is_empty() {
+        let inbox = Inbox::default();
+        assert!(inbox.drain().is_empty());
+    }
+
+    #[test]
+    fn deliver_and_drain() {
+        let inbox = Inbox::new();
+        inbox.deliver(text_envelope("a", "b", "hello"));
+        let msgs = inbox.drain();
+        assert_eq!(msgs.len(), 1);
+        assert_eq!(msgs[0].from, "a");
+    }
+
+    #[test]
+    fn drain_empties_inbox() {
+        let inbox = Inbox::new();
+        inbox.deliver(text_envelope("a", "b", "hello"));
+        inbox.drain();
+        assert!(inbox.drain().is_empty());
+    }
+
+    #[test]
+    fn drain_orders_shutdown_before_task_before_text() {
+        let inbox = Inbox::new();
+        inbox.deliver(text_envelope("a", "b", "msg"));
+        inbox.deliver(task_completed_envelope("a", "b"));
+        inbox.deliver(shutdown_request_envelope("a", "b"));
+
+        let msgs = inbox.drain();
+        assert_eq!(msgs.len(), 3);
+        assert!(matches!(
+            msgs[0].payload,
+            EnvelopePayload::ShutdownRequest { .. }
+        ));
+        assert!(matches!(
+            msgs[1].payload,
+            EnvelopePayload::TaskCompleted { .. }
+        ));
+        assert!(matches!(msgs[2].payload, EnvelopePayload::Text { .. }));
+    }
+
+    #[test]
+    fn clone_preserves_messages() {
+        let inbox = Inbox::new();
+        inbox.deliver(text_envelope("a", "b", "hello"));
+        let cloned = inbox.clone();
+        let msgs = cloned.drain();
+        assert_eq!(msgs.len(), 1);
+    }
+
+    #[test]
+    fn clone_is_independent() {
+        let inbox = Inbox::new();
+        inbox.deliver(text_envelope("a", "b", "hello"));
+        let cloned = inbox.clone();
+        inbox.deliver(text_envelope("a", "b", "second"));
+        let original_msgs = inbox.drain();
+        let cloned_msgs = cloned.drain();
+        assert_eq!(original_msgs.len(), 2);
+        assert_eq!(cloned_msgs.len(), 1);
+    }
+
+    #[test]
+    fn multiple_deliveries() {
+        let inbox = Inbox::new();
+        for i in 0..5 {
+            inbox.deliver(text_envelope("a", "b", &format!("msg {i}")));
+        }
+        assert_eq!(inbox.drain().len(), 5);
+    }
+}
diff --git a/src/supervisor/mod.rs b/src/supervisor/mod.rs
index 4fd7a21..9c0c1c8 100644
--- a/src/supervisor/mod.rs
+++ b/src/supervisor/mod.rs
@@ -126,3 +126,129 @@ impl Debug for Supervisor {
             .finish()
     }
 }
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use crate::utils::create_abort_signal;
+
+    fn make_handle(id: &str, agent_name: &str, depth: usize) -> AgentHandle {
+        let rt = tokio::runtime::Builder::new_current_thread()
+            .enable_all()
+            .build()
+            .unwrap();
+        let join_handle = rt.spawn(async {
+            Ok(AgentResult {
+                id: "done".into(),
+                agent_name: "test".into(),
+                output: "result".into(),
+                exit_status: AgentExitStatus::Completed,
+            })
+        });
+        AgentHandle {
+            id: id.to_string(),
+            agent_name: agent_name.to_string(),
+            depth,
+            inbox: Arc::new(Inbox::new()),
+            abort_signal: create_abort_signal(),
+            join_handle,
+        }
+    }
+
+    #[test]
+    fn supervisor_new_empty() {
+        let sup = Supervisor::new(4, 3);
+        assert_eq!(sup.active_count(), 0);
+        assert_eq!(sup.max_concurrent(), 4);
+        assert_eq!(sup.max_depth(), 3);
+    }
+
+    #[test]
+    fn supervisor_register_increments_count() {
+        let mut sup = Supervisor::new(4, 3);
+        sup.register(make_handle("a1", "explore", 1)).unwrap();
+        assert_eq!(sup.active_count(), 1);
+    }
+
+    #[test]
+    fn supervisor_register_rejects_at_capacity() {
+        let mut sup = Supervisor::new(1, 3);
+        sup.register(make_handle("a1", "explore", 1)).unwrap();
+        let result = sup.register(make_handle("a2", "coder", 1));
+        assert!(result.is_err());
+        assert!(result.unwrap_err().to_string().contains("at capacity"));
+    }
+
+    #[test]
+    fn supervisor_register_rejects_exceeding_depth() {
+        let mut sup = Supervisor::new(4, 2);
+        let result = sup.register(make_handle("a1", "explore", 3));
+        assert!(result.is_err());
+        assert!(result.unwrap_err().to_string().contains("max depth"));
+    }
+
+    #[test]
+    fn supervisor_register_allows_at_max_depth() {
+        let mut sup = Supervisor::new(4, 2);
+        sup.register(make_handle("a1", "explore", 2)).unwrap();
+        assert_eq!(sup.active_count(), 1);
+    }
+
+    #[test]
+    fn supervisor_take_removes_handle() {
+        let mut sup = Supervisor::new(4, 3);
+        sup.register(make_handle("a1", "explore", 1)).unwrap();
+        let taken = sup.take("a1");
+        assert!(taken.is_some());
+        assert_eq!(sup.active_count(), 0);
+    }
+
+    #[test]
+    fn supervisor_take_nonexistent_returns_none() {
+        let mut sup = Supervisor::new(4, 3);
+        assert!(sup.take("missing").is_none());
+    }
+
+    #[test]
+    fn supervisor_list_agents() {
+        let mut sup = Supervisor::new(4, 3);
+        sup.register(make_handle("a1", "explore", 1)).unwrap();
+        sup.register(make_handle("a2", "coder", 1)).unwrap();
+        let list = sup.list_agents();
+        assert_eq!(list.len(), 2);
+        let ids: Vec<&str> = list.iter().map(|(id, _)| *id).collect();
+        assert!(ids.contains(&"a1"));
+        assert!(ids.contains(&"a2"));
+    }
+
+    #[test]
+    fn supervisor_inbox_returns_handle_inbox() {
+        let mut sup = Supervisor::new(4, 3);
+        sup.register(make_handle("a1", "explore", 1)).unwrap();
+        assert!(sup.inbox("a1").is_some());
+        assert!(sup.inbox("missing").is_none());
+    }
+
+    #[test]
+    fn supervisor_task_queue_accessible() {
+        let mut sup = Supervisor::new(4, 3);
+        let id = sup
+            .task_queue_mut()
+            .create("task".into(), "desc".into(), None, None);
+        assert!(!id.is_empty());
+        assert_eq!(sup.task_queue().list().len(), 1);
+    }
+
+    #[test]
+    fn agent_exit_status_equality() {
+        assert_eq!(AgentExitStatus::Completed, AgentExitStatus::Completed);
+        assert_ne!(
+            AgentExitStatus::Completed,
+            AgentExitStatus::Failed("err".into())
+        );
+        assert_eq!(
+            AgentExitStatus::Failed("x".into()),
+            AgentExitStatus::Failed("x".into())
+        );
+    }
+}
diff --git a/src/supervisor/taskqueue.rs b/src/supervisor/taskqueue.rs
index 6387122..e60f676 100644
--- a/src/supervisor/taskqueue.rs
+++ b/src/supervisor/taskqueue.rs
@@ -268,4 +268,87 @@ mod tests {
         assert!(!queue.claim(&id1, "worker-2"));
         assert_eq!(queue.get(&id1).unwrap().status, TaskStatus::InProgress);
     }
+
+    #[test]
+    fn test_fail_sets_status() {
+        let mut queue = TaskQueue::new();
+        let id = queue.create("Task".into(), "".into(), None, None);
+        queue.fail(&id);
+        assert_eq!(queue.get(&id).unwrap().status, TaskStatus::Failed);
+    }
+
+    #[test]
+    fn test_get_returns_none_for_missing() {
+        let queue = TaskQueue::new();
+        assert!(queue.get("nonexistent").is_none());
+    }
+
+    #[test]
+    fn test_dispatch_agent_stored() {
+        let mut queue = TaskQueue::new();
+        let id = queue.create(
+            "Auto task".into(),
+            "desc".into(),
+            Some("coder".into()),
+            Some("implement feature".into()),
+        );
+        let task = queue.get(&id).unwrap();
+        assert_eq!(task.dispatch_agent.as_deref(), Some("coder"));
+        assert_eq!(task.prompt.as_deref(), Some("implement feature"));
+    }
+
+    #[test]
+    fn test_claim_blocked_task_fails() {
+        let mut queue = TaskQueue::new();
+        let id1 = queue.create("A".into(), "".into(), None, None);
+        let id2 = queue.create("B".into(), "".into(), None, None);
+        queue.add_dependency(&id2, &id1).unwrap();
+        assert!(!queue.claim(&id2, "worker"));
+    }
+
+    #[test]
+    fn test_list_sorted_by_id() {
+        let mut queue = TaskQueue::new();
+        queue.create("Third".into(), "".into(), None, None);
+        queue.create("First".into(), "".into(), None, None);
+        queue.create("Second".into(), "".into(), None, None);
+        let tasks = queue.list();
+        let ids: Vec<&str> = tasks.iter().map(|t| t.id.as_str()).collect();
+        assert_eq!(ids, vec!["1", "2", "3"]);
+    }
+
+    #[test]
+    fn test_default_is_empty() {
+        let queue = TaskQueue::default();
+        assert!(queue.list().is_empty());
+    }
+
+    #[test]
+    fn test_dependency_on_nonexistent_task_errors() {
+        let mut queue = TaskQueue::new();
+        let id1 = queue.create("A".into(), "".into(), None, None);
+        let result = queue.add_dependency(&id1, "nonexistent");
+        assert!(result.is_err());
+    }
+
+    #[test]
+    fn test_complete_nonexistent_returns_empty() {
+        let mut queue = TaskQueue::new();
+        let unblocked = queue.complete("nonexistent");
+        assert!(unblocked.is_empty());
+    }
+
+    #[test]
+    fn test_task_node_is_runnable() {
+        let node = TaskNode::new("1".into(), "t".into(), "d".into(), None, None);
+        assert!(node.is_runnable());
+    }
+
+    #[test]
+    fn test_task_node_not_runnable_when_blocked() {
+        let mut node = TaskNode::new("1".into(), "t".into(), "d".into(), None, None);
+        node.blocked_by.insert("2".into());
+        node.status = TaskStatus::Blocked;
+        assert!(!node.is_runnable());
+    }
 }
diff --git a/src/utils/input.rs b/src/utils/input.rs
index 2dd75dc..e267bbd 100644
--- a/src/utils/input.rs
+++ b/src/utils/input.rs
@@ -20,11 +20,9 @@ pub fn read_single_key(valid_chars: &[char], default: char, prompt: &str) -> Res
                 KeyCode::Char('c') if modifiers.contains(KeyModifiers::CONTROL) => {
                     break Err(anyhow::anyhow!("Interrupted"));
                 }
-                KeyCode::Char(c) => {
-                    if valid_chars.contains(&c) {
-                        break Ok(c);
-                    }
+                KeyCode::Char(c) if valid_chars.contains(&c) => {
                     // Invalid character, continue loop
+                    break Ok(c);
                 }
                 KeyCode::Enter => {
                     break Ok(default);
diff --git a/src/utils/logs.rs b/src/utils/logs.rs
index fd6a96f..58c8089 100644
--- a/src/utils/logs.rs
+++ b/src/utils/logs.rs
@@ -1,4 +1,4 @@
-use crate::config::Config;
+use crate::config::paths;
 use colored::Colorize;
 use fancy_regex::Regex;
 use std::fs::File;
@@ -7,7 +7,7 @@ use std::process;
 
 pub async fn tail_logs(no_color: bool) {
     let re = Regex::new(r"^(?P<timestamp>\d{4}-\d{2}-\d{2} \d{2}:\d{2}:\d{2}\.\d{3})\s+<(?P<opid>[^\s>]+)>\s+\[(?P<level>[A-Z]+)\]\s+(?P<logger>[^:]+):(?P<line>\d+)\s+-\s+(?P<message>.*)$").unwrap();
-    let file_path = Config::log_path();
+    let file_path = paths::log_path();
     let file = File::open(&file_path).expect("Cannot open file");
     let mut reader = BufReader::new(file);
 
diff --git a/src/utils/mod.rs b/src/utils/mod.rs
index f0e0648..457190d 100644
--- a/src/utils/mod.rs
+++ b/src/utils/mod.rs
@@ -33,8 +33,7 @@ use fuzzy_matcher::{FuzzyMatcher, skim::SkimMatcherV2};
 use is_terminal::IsTerminal;
 use std::borrow::Cow;
 use std::sync::LazyLock;
-use std::{env, path::PathBuf, process};
-use unicode_segmentation::UnicodeSegmentation;
+use std::{cmp, env, path::PathBuf, process};
 
 pub static CODE_BLOCK_RE: LazyLock<Regex> =
     LazyLock::new(|| Regex::new(r"(?ms)```\w*(.*)```").unwrap());
@@ -74,21 +73,8 @@ pub fn parse_bool(value: &str) -> Option<bool> {
 }
 
 pub fn estimate_token_length(text: &str) -> usize {
-    let words: Vec<&str> = text.unicode_words().collect();
-    let mut output: f32 = 0.0;
-    for word in words {
-        if word.is_ascii() {
-            output += 1.3;
-        } else {
-            let count = word.chars().count();
-            if count == 1 {
-                output += 1.0
-            } else {
-                output += (count as f32) * 0.5;
-            }
-        }
-    }
-    output.ceil() as usize
+    let weighted: usize = text.chars().map(|c| if c.is_ascii() { 1 } else { 2 }).sum();
+    weighted.div_ceil(4)
 }
 
 pub fn strip_think_tag(text: &str) -> Cow<'_, str> {
@@ -123,7 +109,7 @@ where
             Some((v, score))
         })
         .collect();
-    list.sort_unstable_by(|a, b| b.1.cmp(&a.1));
+    list.sort_unstable_by_key(|b| cmp::Reverse(b.1));
     list.into_iter().map(|(v, _)| v).collect()
 }
 
diff --git a/src/utils/path.rs b/src/utils/path.rs
index 8bc6b19..a01989c 100644
--- a/src/utils/path.rs
+++ b/src/utils/path.rs
@@ -241,23 +241,23 @@ fn add_file(files: &mut IndexSet<String>, suffixes: Option<&Vec<String>>, path:
 }
 
 fn is_valid_extension(suffixes: Option<&Vec<String>>, path: &Path) -> bool {
-    let filename_regex = Regex::new(r"^.+\.*").unwrap();
-    if let Some(suffixes) = suffixes
-        && !suffixes.is_empty()
-    {
-        if let Ok(Some(_)) = filename_regex.find(&suffixes.join(",")) {
-            let file_name = path
-                .file_name()
-                .and_then(|v| v.to_str())
-                .expect("invalid filename")
-                .to_string();
-            return suffixes.contains(&file_name);
-        } else if let Some(extension) = path.extension().map(|v| v.to_string_lossy().to_string()) {
-            return suffixes.contains(&extension);
-        }
-        return false;
+    let Some(suffixes) = suffixes else {
+        return true;
+    };
+    if suffixes.is_empty() {
+        return true;
     }
-    true
+
+    let file_name = path.file_name().and_then(|v| v.to_str());
+    let extension = path.extension().and_then(|v| v.to_str());
+
+    suffixes.iter().any(|suffix| {
+        if suffix.contains('.') {
+            Some(suffix.as_str()) == file_name
+        } else {
+            Some(suffix.as_str()) == extension
+        }
+    })
 }
 
 #[cfg(test)]
@@ -352,4 +352,43 @@ mod tests {
             )
         );
     }
+
+    #[test]
+    fn test_is_valid_extension() {
+        let md_ext = vec!["md".to_string()];
+        let md_txt_ext = vec!["md".to_string(), "txt".to_string()];
+        let test_md_filename = vec!["test.md".to_string()];
+        let mixed = vec!["md".to_string(), "test.txt".to_string()];
+
+        assert!(is_valid_extension(None, Path::new("Agents.md")));
+        assert!(is_valid_extension(Some(&vec![]), Path::new("Agents.md")));
+
+        assert!(is_valid_extension(Some(&md_ext), Path::new("Agents.md")));
+        assert!(is_valid_extension(
+            Some(&md_ext),
+            Path::new("/home/atusa/code/loki.wiki/Agents.md")
+        ));
+        assert!(!is_valid_extension(Some(&md_ext), Path::new("notes.txt")));
+        assert!(!is_valid_extension(Some(&md_ext), Path::new("README")));
+
+        assert!(is_valid_extension(Some(&md_txt_ext), Path::new("a.md")));
+        assert!(is_valid_extension(Some(&md_txt_ext), Path::new("a.txt")));
+        assert!(!is_valid_extension(Some(&md_txt_ext), Path::new("a.rs")));
+
+        assert!(is_valid_extension(
+            Some(&test_md_filename),
+            Path::new("dir/test.md")
+        ));
+        assert!(!is_valid_extension(
+            Some(&test_md_filename),
+            Path::new("dir/Agents.md")
+        ));
+
+        assert!(is_valid_extension(Some(&mixed), Path::new("Agents.md")));
+        assert!(is_valid_extension(Some(&mixed), Path::new("dir/test.txt")));
+        assert!(!is_valid_extension(
+            Some(&mixed),
+            Path::new("dir/other.txt")
+        ));
+    }
 }
diff --git a/src/vault/mod.rs b/src/vault/mod.rs
index e170075..1626fbc 100644
--- a/src/vault/mod.rs
+++ b/src/vault/mod.rs
@@ -5,7 +5,7 @@ pub use utils::create_vault_password_file;
 pub use utils::interpolate_secrets;
 
 use crate::cli::Cli;
-use crate::config::Config;
+use crate::config::AppConfig;
 use crate::vault::utils::ensure_password_file_initialized;
 use anyhow::{Context, Result};
 use fancy_regex::Regex;
@@ -26,7 +26,7 @@ pub type GlobalVault = Arc<Vault>;
 
 impl Vault {
     pub fn init_bare() -> Self {
-        let vault_password_file = Config::default().vault_password_file();
+        let vault_password_file = AppConfig::default().vault_password_file();
         let local_provider = LocalProvider {
             password_file: Some(vault_password_file),
             git_branch: None,
@@ -36,7 +36,7 @@ impl Vault {
         Self { local_provider }
     }
 
-    pub fn init(config: &Config) -> Self {
+    pub fn init(config: &AppConfig) -> Self {
         let vault_password_file = config.vault_password_file();
         let mut local_provider = LocalProvider {
             password_file: Some(vault_password_file),
@@ -130,27 +130,69 @@ impl Vault {
         Ok(secrets)
     }
 
-    pub fn handle_vault_flags(cli: Cli, config: Config) -> Result<()> {
+    pub fn handle_vault_flags(cli: Cli, vault: &Vault) -> Result<()> {
         if let Some(secret_name) = cli.add_secret {
-            config.vault.add_secret(&secret_name)?;
+            vault.add_secret(&secret_name)?;
         }
 
         if let Some(secret_name) = cli.get_secret {
-            config.vault.get_secret(&secret_name, true)?;
+            vault.get_secret(&secret_name, true)?;
         }
 
         if let Some(secret_name) = cli.update_secret {
-            config.vault.update_secret(&secret_name)?;
+            vault.update_secret(&secret_name)?;
         }
 
         if let Some(secret_name) = cli.delete_secret {
-            config.vault.delete_secret(&secret_name)?;
+            vault.delete_secret(&secret_name)?;
         }
 
         if cli.list_secrets {
-            config.vault.list_secrets(true)?;
+            vault.list_secrets(true)?;
         }
 
         Ok(())
     }
 }
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn secret_re_matches_double_braces() {
+        let captures = SECRET_RE.captures("{{MY_SECRET}}").unwrap().unwrap();
+        assert_eq!(&captures[1], "MY_SECRET");
+    }
+
+    #[test]
+    fn secret_re_matches_with_surrounding_text() {
+        let text = "key={{API_KEY}} here";
+        let captures = SECRET_RE.captures(text).unwrap().unwrap();
+        assert_eq!(&captures[1], "API_KEY");
+    }
+
+    #[test]
+    fn secret_re_no_match_single_braces() {
+        let result = SECRET_RE.captures("{NOT_SECRET}").unwrap();
+        assert!(result.is_none());
+    }
+
+    #[test]
+    fn secret_re_no_match_plain_text() {
+        let result = SECRET_RE.captures("just plain text").unwrap();
+        assert!(result.is_none());
+    }
+
+    #[test]
+    fn secret_re_matches_with_spaces() {
+        let captures = SECRET_RE.captures("{{ SPACED }}").unwrap().unwrap();
+        assert_eq!(&captures[1], " SPACED ");
+    }
+
+    #[test]
+    fn vault_default_creates_instance() {
+        let vault = Vault::default();
+        assert!(vault.password_file().is_err());
+    }
+}