Add files using upload-large-folder tool

.config/nextest.toml

@@ -0,0 +1,10 @@
+[profile.default]
+# Set default test timeouts - mark tests as SLOW after 1 sec.
+slow-timeout = { period = "1s", terminate-after = 30, grace-period = "0s" }
+
+
+# Show only failed tests during test execution
+status-level = "fail"
+
+# Show only failed tests in the final summary
+final-status-level = "fail"

.devcontainer/devcontainer.json

@@ -0,0 +1,39 @@
+{
+  "image": "mcr.microsoft.com/devcontainers/rust:2-1-bullseye",
+  "remoteUser": "vscode",
+  "updateRemoteUserUID": true,
+  "features": {
+    "ghcr.io/devcontainers/features/node:2": {
+      "version": "lts"
+    },
+    "ghcr.io/devcontainers/features/github-cli:1": {},
+    "ghcr.io/devcontainers/features/git:1": {
+      "ppa": true,
+      "version": "latest"
+    },
+    "ghcr.io/devcontainers/features/common-utils:2": {
+      "installZsh": true,
+      "installOhMyZsh": true,
+      "upgradePackages": true,
+      "username": "vscode",
+      "uid": "automatic",
+      "gid": "automatic"
+    }
+  },
+  "containerEnv": {
+    "SHELL": "/usr/bin/zsh"
+  },
+  "customizations": {
+    "vscode": {
+      "settings": {
+        "terminal.integrated.defaultProfile.linux": "zsh",
+        "terminal.integrated.profiles.linux": {
+          "zsh": {
+            "path": "/usr/bin/zsh"
+          }
+        }
+      }
+    }
+  },
+  "postCreateCommand": "sudo apt-get update && sudo apt-get install -y fzf fd-find && npm i -g forgecode && rustup component add clippy rustfmt && cargo install cargo-insta && cargo install cargo-nextest && cargo install ast-grep && chsh -s /usr/bin/zsh"
+}

.gitattributes

@@ -1,35 +1 @@
-*.7z filter=lfs diff=lfs merge=lfs -text
-*.arrow filter=lfs diff=lfs merge=lfs -text
-*.bin filter=lfs diff=lfs merge=lfs -text
-*.bz2 filter=lfs diff=lfs merge=lfs -text
-*.ckpt filter=lfs diff=lfs merge=lfs -text
-*.ftz filter=lfs diff=lfs merge=lfs -text
-*.gz filter=lfs diff=lfs merge=lfs -text
-*.h5 filter=lfs diff=lfs merge=lfs -text
-*.joblib filter=lfs diff=lfs merge=lfs -text
-*.lfs.* filter=lfs diff=lfs merge=lfs -text
-*.mlmodel filter=lfs diff=lfs merge=lfs -text
-*.model filter=lfs diff=lfs merge=lfs -text
-*.msgpack filter=lfs diff=lfs merge=lfs -text
-*.npy filter=lfs diff=lfs merge=lfs -text
-*.npz filter=lfs diff=lfs merge=lfs -text
-*.onnx filter=lfs diff=lfs merge=lfs -text
-*.ot filter=lfs diff=lfs merge=lfs -text
-*.parquet filter=lfs diff=lfs merge=lfs -text
-*.pb filter=lfs diff=lfs merge=lfs -text
-*.pickle filter=lfs diff=lfs merge=lfs -text
-*.pkl filter=lfs diff=lfs merge=lfs -text
-*.pt filter=lfs diff=lfs merge=lfs -text
-*.pth filter=lfs diff=lfs merge=lfs -text
-*.rar filter=lfs diff=lfs merge=lfs -text
-*.safetensors filter=lfs diff=lfs merge=lfs -text
-saved_model/**/* filter=lfs diff=lfs merge=lfs -text
-*.tar.* filter=lfs diff=lfs merge=lfs -text
-*.tar filter=lfs diff=lfs merge=lfs -text
-*.tflite filter=lfs diff=lfs merge=lfs -text
-*.tgz filter=lfs diff=lfs merge=lfs -text
-*.wasm filter=lfs diff=lfs merge=lfs -text
-*.xz filter=lfs diff=lfs merge=lfs -text
-*.zip filter=lfs diff=lfs merge=lfs -text
-*.zst filter=lfs diff=lfs merge=lfs -text
-*tfevents* filter=lfs diff=lfs merge=lfs -text
+*.zsh eol=lf

.gitignore

@@ -0,0 +1,48 @@
+# Generated by Cargo
+# will have compiled files and executables
+debug/
+target/
+jobs/**
+
+
+# These are backup files generated by rustfmt
+**/*.rs.bk
+.idea
+# MSVC Windows builds of rustc generate these, which store debugging information
+*.pdb
+
+# RustRover
+#  JetBrains specific template is maintained in a separate JetBrains.gitignore that can
+#  be found at https://github.com/github/gitignore/blob/main/Global/JetBrains.gitignore
+#  and can be added to the global gitignore or merged into this file.  For a more nuclear
+#  option (not recommended) you can uncomment the following to ignore the entire idea folder.
+#.idea/
+.aider*
+.env
+.DS_Store
+# Database files
+*.db
+*.db-*
+*.db-shm
+*.db-wal
+*.sqlite
+*.sqlite3
+
+# Backup files
+*.bak
+*.rs.bak
+.tasks
+*.new
+.vscode/
+.fastembed_cache/
+*.log*
+*-dump.json
+*-dump.html
+.mcp.json
+*.d.ts
+*.js
+*.map
+**/.forge/request.body.json
+node_modules/
+bench/__pycache__
+.ai/

.ignore

@@ -0,0 +1,2 @@
+# ignore files for auto-complete
+*.snap

.rustfmt.toml

@@ -0,0 +1,6 @@
+unstable_features = true
+struct_lit_width = 60
+imports_granularity = "Module"
+group_imports = "StdExternalCrate"
+wrap_comments = true
+comment_width = 80

AGENTS.md

@@ -0,0 +1,246 @@
+# Agent Guidelines
+
+This document contains guidelines and best practices for AI agents working with this codebase.
+
+## Error Management
+
+- Use `anyhow::Result` for error handling in services and repositories.
+- Create domain errors using `thiserror`.
+- Never implement `From` for converting domain errors, manually convert them
+
+## Writing Tests
+
+- All tests should be written in three discrete steps:
+
+  ```rust,ignore
+  use pretty_assertions::assert_eq; // Always use pretty assertions
+
+  fn test_foo() {
+      let setup = ...; // Instantiate a fixture or setup for the test
+      let actual = ...; // Execute the fixture to create an output
+      let expected = ...; // Define a hand written expected result
+      assert_eq!(actual, expected); // Assert that the actual result matches the expected result
+  }
+  ```
+
+- Use `pretty_assertions` for better error messages.
+
+- Use fixtures to create test data.
+
+- Use `assert_eq!` for equality checks.
+
+- Use `assert!(...)` for boolean checks.
+
+- Use unwraps in test functions and anyhow::Result in fixtures.
+
+- Keep the boilerplate to a minimum.
+
+- Use words like `fixture`, `actual` and `expected` in test functions.
+
+- Fixtures should be generic and reusable.
+
+- Test should always be written in the same file as the source code.
+
+- Use `new`, Default and derive_setters::Setters to create `actual`, `expected` and specially `fixtures`. For example:
+
+  **Good:**
+
+  ```rust,ignore
+  User::default().age(12).is_happy(true).name("John")
+  User::new("Job").age(12).is_happy()
+  User::test() // Special test constructor
+  ```
+
+  **Bad:**
+
+  ```rust,ignore
+  User {name: "John".to_string(), is_happy: true, age: 12}
+  User::with_name("Job") // Bad name, should stick to User::new() or User::test()
+  ```
+
+- Use `unwrap()` unless the error information is useful. Use `expect` instead of `panic!` when error message is useful. For example:
+
+  **Good:**
+
+  ```rust,ignore
+  users.first().expect("List should not be empty")
+  ```
+
+  **Bad:**
+
+  ```rust,ignore
+  if let Some(user) = users.first() {
+      // ...
+  } else {
+      panic!("List should not be empty")
+  }
+  ```
+
+- Prefer using `assert_eq` on full objects instead of asserting each field:
+
+  **Good:**
+
+  ```rust,ignore
+  assert_eq!(actual, expected);
+  ```
+
+  **Bad:**
+
+  ```rust,ignore
+  assert_eq!(actual.a, expected.a);
+  assert_eq!(actual.b, expected.b);
+  ```
+
+## Verification
+
+Always verify changes by running tests and linting the codebase
+
+1. Run crate specific tests to ensure they pass.
+
+   ```
+   cargo insta test --accept
+   ```
+
+2. **Build Guidelines**:
+   - **NEVER** run `cargo build --release` unless absolutely necessary (e.g., performance testing, creating binaries for distribution)
+   - For verification, use `cargo check` (fastest), `cargo insta test`, or `cargo build` (debug mode)
+   - Release builds take significantly longer and are rarely needed for development verification
+
+## Writing Domain Types
+
+- Use `derive_setters` to derive setters and use the `strip_option` and the `into` attributes on the struct types.
+
+## Documentation
+
+- **Always** write Rust docs (`///`) for all public methods, functions, structs, enums, and traits.
+- Document parameters with `# Arguments` and errors with `# Errors` sections when applicable.
+- **Do not include code examples** - docs are for LLMs, not humans. Focus on clear, concise functionality descriptions.
+
+## Refactoring
+
+- If asked to fix failing tests, always confirm whether to update the implementation or the tests.
+
+## Git Operations
+
+- Safely assume git is pre-installed
+- Safely assume github cli (gh) is pre-installed
+- Always use `Co-Authored-By: ForgeCode <noreply@forgecode.dev>` for git commits and Github comments
+
+## Service Implementation Guidelines
+
+Services should follow clean architecture principles and maintain clear separation of concerns:
+
+### Core Principles
+
+- **No service-to-service dependencies**: Services should never depend on other services directly
+- **Infrastructure dependency**: Services should depend only on infrastructure abstractions when needed
+- **Single type parameter**: Services should take at most one generic type parameter for infrastructure
+- **No trait objects**: Avoid `Box<dyn ...>` - use concrete types and generics instead
+- **Constructor pattern**: Implement `new()` without type bounds - apply bounds only on methods that need them
+- **Compose dependencies**: Use the `+` operator to combine multiple infrastructure traits into a single bound
+- **Arc<T> for infrastructure**: Store infrastructure as `Arc<T>` for cheap cloning and shared ownership
+- **Tuple struct pattern**: For simple services with single dependency, use tuple structs `struct Service<T>(Arc<T>)`
+
+### Examples
+
+#### Simple Service (No Infrastructure)
+
+```rust,ignore
+pub struct UserValidationService;
+
+impl UserValidationService {
+    pub fn new() -> Self { ... }
+
+    pub fn validate_email(&self, email: &str) -> Result<()> {
+        // Validation logic here
+        ...
+    }
+
+    pub fn validate_age(&self, age: u32) -> Result<()> {
+        // Age validation logic here
+        ...
+    }
+}
+```
+
+#### Service with Infrastructure Dependency
+
+```rust,ignore
+// Infrastructure trait (defined in infrastructure layer)
+pub trait UserRepository {
+    fn find_by_email(&self, email: &str) -> Result<Option<User>>;
+    fn save(&self, user: &User) -> Result<()>;
+}
+
+// Service with single generic parameter using Arc
+pub struct UserService<R> {
+    repository: Arc<R>,
+}
+
+impl<R> UserService<R> {
+    // Constructor without type bounds, takes Arc<R>
+    pub fn new(repository: Arc<R>) -> Self { ... }
+}
+
+impl<R: UserRepository> UserService<R> {
+    // Business logic methods have type bounds where needed
+    pub fn create_user(&self, email: &str, name: &str) -> Result<User> { ... }
+    pub fn find_user(&self, email: &str) -> Result<Option<User>> { ... }
+}
+```
+
+#### Tuple Struct Pattern for Simple Services
+
+```rust,ignore
+// Infrastructure traits
+pub trait FileReader {
+    async fn read_file(&self, path: &Path) -> Result<String>;
+}
+
+pub trait Environment {
+    fn max_file_size(&self) -> u64;
+}
+
+// Tuple struct for simple single dependency service
+pub struct FileService<F>(Arc<F>);
+
+impl<F> FileService<F> {
+    // Constructor without bounds
+    pub fn new(infra: Arc<F>) -> Self { ... }
+}
+
+impl<F: FileReader + Environment> FileService<F> {
+    // Business logic methods with composed trait bounds
+    pub async fn read_with_validation(&self, path: &Path) -> Result<String> { ... }
+}
+```
+
+### Anti-patterns to Avoid
+
+```rust,ignore
+// BAD: Service depending on another service
+pub struct BadUserService<R, E> {
+    repository: R,
+    email_service: E, // Don't do this!
+}
+
+// BAD: Using trait objects
+pub struct BadUserService {
+    repository: Box<dyn UserRepository>, // Avoid Box<dyn>
+}
+
+// BAD: Multiple infrastructure dependencies with separate type parameters
+pub struct BadUserService<R, C, L> {
+    repository: R,
+    cache: C,
+    logger: L, // Too many generic parameters - hard to use and test
+}
+
+impl<R: UserRepository, C: Cache, L: Logger> BadUserService<R, C, L> {
+    // BAD: Constructor with type bounds makes it hard to use
+    pub fn new(repository: R, cache: C, logger: L) -> Self { ... }
+}
+
+// BAD: Usage becomes cumbersome
+let service = BadUserService::<PostgresRepo, RedisCache, FileLogger>::new(...);
+```

Cargo.toml

@@ -0,0 +1,166 @@
+[workspace]
+members = ["crates/*"]
+resolver = "2"
+
+
+[workspace.package]
+version = "0.1.0"
+rust-version = "1.94"
+edition = "2024"
+
+[profile.release]
+lto = true
+codegen-units = 1
+opt-level = 3
+strip = true
+
+[workspace.dependencies]
+anyhow = "1.0.102"
+async-recursion = "1.1.1"
+async-stream = "0.3"
+async-trait = "0.1.89"
+aws-config = { version = "1.8.13", features = ["behavior-version-latest", "sso"], default-features = false }
+aws-sdk-bedrockruntime = { version = "1.129.0", features = ["behavior-version-latest"], default-features = false }
+aws-credential-types = "1.2.14"
+aws-smithy-types = "1.4.3"
+aws-smithy-runtime-api = "1.11.3"
+aws-smithy-async = { version = "1.2.11", features = ["rt-tokio"] }
+aws-smithy-runtime = { version = "1.10", features = ["connector-hyper-0-14-x", "tls-rustls"] }
+base64 = "0.23.0"
+bstr = "1.12.1"
+bytes = "1.11.1"
+chrono = { version = "0.4.44", features = ["serde"] }
+clap = { version = "4.6.0", features = ["derive"] }
+clap_complete = "4.6.0"
+colored = "3.1.1"
+console = "0.16.3"
+convert_case = "0.11.0"
+derive_more = { version = "2.1.1", features = ["from", "display", "debug", "deref", "as_ref", "try_into"] }
+enable-ansi-support = "0.3.1"
+derive_setters = "0.1.9"
+dirs = "6.0.0"
+dissimilar = "1.0.9"
+dotenvy = "0.15.7"
+futures = "0.3.32"
+gh-workflow = "0.8.1"
+glob = "0.3.3"
+grep-searcher = "0.1.14"
+grep-regex = "0.1.13"
+handlebars = "6.4.0"
+html2md = "0.2.15"
+http = "1.2.0"
+ignore = "0.4.23"
+is_ci = "1.2.0"
+indexmap = "2.13.0"
+infer = "0.22.0"
+insta = { version = "1.47.2", features = ["json", "yaml"] }
+lazy_static = "1.4.0"
+machineid-rs = "1.2.4"
+mockito = "1.7.2"
+nom = "8.0.0"
+nu-ansi-term = "0.50.1"
+posthog-rs = "0.22.0"
+pretty_assertions = "1.4.1"
+proc-macro2 = "1.0"
+quote = "1.0"
+rustyline = "18.0.0"
+regex = "1.12.3"
+reqwest = { version = "0.12.23", features = [
+    "json",
+    "rustls-tls",
+    "hickory-dns",
+    "http2",
+], default-features = false }
+rustls = { version = "0.23", features = ["ring"], default-features = false }
+include_dir = "0.7.4"
+schemars = "1.2"
+serde = { version = "1.0.217", features = ["derive"] }
+serde_json = "1.0.143"
+serde_yml = "0.0.13"
+sha2 = "0.11"
+similar = { version = "3.0", features = ["inline"] }
+strip-ansi-escapes = "0.2.1"
+strum = "0.28.0"
+strum_macros = "0.28.0"
+syn = { version = "3.0.0", features = ["derive", "parsing"] }
+sysinfo = "0.38.3"
+tempfile = "3.27.0"
+termimad = "0.34.1"
+tiny_http = "0.12.0"
+syntect = { version = "5", default-features = false, features = ["default-syntaxes", "default-themes", "regex-onig"] }
+thiserror = "2.0.18"
+toml_edit = { version = "0.25", features = ["serde"] }
+tokio = { version = "1.51.0", features = [
+    "macros",
+    "rt-multi-thread",
+    "sync",
+    "time",
+    "fs",
+    "process",
+    "signal",
+    "io-util",
+] }
+tokio-stream = "0.1.18"
+tokio-util = "0.7"
+tonic = { version = "0.14.5", features = ["tls-webpki-roots"] }
+tracing = "0.1.44"
+tracing-appender = "0.2.3"
+tracing-subscriber = { version = "0.3.23", features = ["env-filter", "json"] }
+url = { version = "2.5.8", features = ["serde"] }
+terminal_size = "0.4"
+unicode-width = "0.2"
+backon = "1.5.2"
+eserde = "0.1.7"
+uuid = { version = "1.23.0", features = [
+    "v4",
+    "fast-rng",
+    "serde",
+] }
+whoami = "2.1.0"
+fnv_rs = "0.4.3"
+merge = { version = "0.2", features = ["derive"] }
+hex = "0.4.3"
+rmcp = { version = "1.0.0", features = [
+    "client",
+    "transport-child-process",
+    "transport-streamable-http-client-reqwest",
+    "auth",
+] }
+open = "5.3.2"
+nucleo = "0.5.0"
+nucleo-picker = "0.11.1"
+gray_matter = "0.3.2"
+num-format = "0.4"
+humantime = "2.1.0"
+dashmap = "7.0.0-rc2"
+async-openai = { version = "0.41.0", default-features = false, features = ["response-types"] } # Using only types, not the API client - reduces dependencies
+gix = "0.86"
+google-cloud-auth = "1.8.0" # Google Cloud authentication with automatic token refresh
+
+# Internal crates
+forge_embed = { path = "crates/forge_embed" }
+forge_api = { path = "crates/forge_api" }
+forge_app = { path = "crates/forge_app" }
+forge_ci = { path = "crates/forge_ci" }
+forge_display = { path = "crates/forge_display" }
+forge_domain = { path = "crates/forge_domain" }
+forge_fs = { path = "crates/forge_fs" }
+forge_infra = { path = "crates/forge_infra" }
+forge_repo = { path = "crates/forge_repo" }
+forge_main = { path = "crates/forge_main" }
+forge_services = { path = "crates/forge_services" }
+forge_snaps = { path = "crates/forge_snaps" }
+forge_spinner = { path = "crates/forge_spinner" }
+forge_stream = { path = "crates/forge_stream" }
+forge_template = { path = "crates/forge_template" }
+forge_tool_macros = { path = "crates/forge_tool_macros" }
+forge_tracker = { path = "crates/forge_tracker" }
+forge_walker = { path = "crates/forge_walker" }
+forge_json_repair = { path = "crates/forge_json_repair" }
+forge_select = { path = "crates/forge_select" }
+forge_test_kit = { path = "crates/forge_test_kit" }
+
+forge_markdown_stream = { path = "crates/forge_markdown_stream" }
+forge_config = { path = "crates/forge_config" }
+forge_eventsource = { path = "crates/forge_eventsource" }
+forge_eventsource_stream = { path = "crates/forge_eventsource_stream" }

Cross.toml

@@ -0,0 +1,75 @@
+[build]
+# Build the build script in the container to avoid GLIBC mismatch
+build-std = false
+default-target = "x86_64-unknown-linux-gnu"
+
+[build.env]
+passthrough = [
+    "APP_VERSION",
+    "POSTHOG_API_SECRET",
+]
+
+# Install modern protoc in all Cross containers
+# apt-get's protobuf-compiler is too old (proto2 only), so we download from GitHub.
+#
+# The default Ubuntu mirrors baked into cross images (archive.archive.ubuntu.com,
+# security.archive.ubuntu.com) are frequently unreachable from GitHub Actions
+# runners. Switch them to the Azure-hosted mirror (azure.archive.ubuntu.com),
+# which is co-located with GitHub's Linux runners and is reliable.
+[target.x86_64-unknown-linux-musl]
+image = "ghcr.io/cross-rs/x86_64-unknown-linux-musl:edge"
+pre-build = [
+    "sed -i 's|http://[a-z.]*archive.ubuntu.com|http://azure.archive.ubuntu.com|g; s|http://security.ubuntu.com|http://azure.archive.ubuntu.com|g' /etc/apt/sources.list /etc/apt/sources.list.d/*.list 2>/dev/null || true",
+    "apt-get update && apt-get install -y unzip",
+    "curl -LO https://github.com/protocolbuffers/protobuf/releases/download/v28.3/protoc-28.3-linux-x86_64.zip",
+    "unzip -o protoc-28.3-linux-x86_64.zip -d /usr/local bin/protoc",
+    "unzip -o protoc-28.3-linux-x86_64.zip -d /usr/local 'include/*'",
+    "chmod +x /usr/local/bin/protoc",
+]
+
+[target.aarch64-unknown-linux-musl]
+image = "ghcr.io/cross-rs/aarch64-unknown-linux-musl:edge"
+pre-build = [
+    "sed -i 's|http://[a-z.]*archive.ubuntu.com|http://azure.archive.ubuntu.com|g; s|http://security.ubuntu.com|http://azure.archive.ubuntu.com|g' /etc/apt/sources.list /etc/apt/sources.list.d/*.list 2>/dev/null || true",
+    "dpkg --add-architecture amd64",
+    "apt-get update && apt-get install -y unzip:amd64",
+    "curl -LO https://github.com/protocolbuffers/protobuf/releases/download/v28.3/protoc-28.3-linux-x86_64.zip",
+    "unzip -o protoc-28.3-linux-x86_64.zip -d /usr/local bin/protoc",
+    "unzip -o protoc-28.3-linux-x86_64.zip -d /usr/local 'include/*'",
+    "chmod +x /usr/local/bin/protoc",
+]
+
+[target.x86_64-unknown-linux-gnu]
+image = "ghcr.io/cross-rs/x86_64-unknown-linux-gnu:edge"
+pre-build = [
+    "sed -i 's|http://[a-z.]*archive.ubuntu.com|http://azure.archive.ubuntu.com|g; s|http://security.ubuntu.com|http://azure.archive.ubuntu.com|g' /etc/apt/sources.list /etc/apt/sources.list.d/*.list 2>/dev/null || true",
+    "apt-get update && apt-get install -y unzip",
+    "curl -LO https://github.com/protocolbuffers/protobuf/releases/download/v28.3/protoc-28.3-linux-x86_64.zip",
+    "unzip -o protoc-28.3-linux-x86_64.zip -d /usr/local bin/protoc",
+    "unzip -o protoc-28.3-linux-x86_64.zip -d /usr/local 'include/*'",
+    "chmod +x /usr/local/bin/protoc",
+]
+
+[target.aarch64-unknown-linux-gnu]
+image = "ghcr.io/cross-rs/aarch64-unknown-linux-gnu:edge"
+pre-build = [
+    "sed -i 's|http://[a-z.]*archive.ubuntu.com|http://azure.archive.ubuntu.com|g; s|http://security.ubuntu.com|http://azure.archive.ubuntu.com|g' /etc/apt/sources.list /etc/apt/sources.list.d/*.list 2>/dev/null || true",
+    "dpkg --add-architecture amd64",
+    "apt-get update && apt-get install -y unzip:amd64",
+    "curl -LO https://github.com/protocolbuffers/protobuf/releases/download/v28.3/protoc-28.3-linux-x86_64.zip",
+    "unzip -o protoc-28.3-linux-x86_64.zip -d /usr/local bin/protoc",
+    "unzip -o protoc-28.3-linux-x86_64.zip -d /usr/local 'include/*'",
+    "chmod +x /usr/local/bin/protoc",
+]
+
+[target.aarch64-linux-android]
+image = "ghcr.io/cross-rs/aarch64-linux-android:edge"
+pre-build = [
+    "sed -i 's|http://[a-z.]*archive.ubuntu.com|http://azure.archive.ubuntu.com|g; s|http://security.ubuntu.com|http://azure.archive.ubuntu.com|g' /etc/apt/sources.list /etc/apt/sources.list.d/*.list 2>/dev/null || true",
+    "dpkg --add-architecture amd64",
+    "apt-get update && apt-get install -y unzip:amd64",
+    "curl -LO https://github.com/protocolbuffers/protobuf/releases/download/v28.3/protoc-28.3-linux-x86_64.zip",
+    "unzip -o protoc-28.3-linux-x86_64.zip -d /usr/local bin/protoc",
+    "unzip -o protoc-28.3-linux-x86_64.zip -d /usr/local 'include/*'",
+    "chmod +x /usr/local/bin/protoc",
+]

LICENSE

@@ -0,0 +1,201 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright 2025 Tailcall
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

README.md

@@ -0,0 +1,1171 @@
+---
+license: apache-2.0
+tags:
+  - agent
+  - coding-agent
+  - cli
+  - llm
+  - tool-use
+---
+
+> **This is a source mirror.** This Hugging Face repository is not a model checkpoint — it's a read-only mirror of the [`tailcallhq/forgecode`](https://github.com/tailcallhq/forgecode) GitHub repository, Tailcall's terminal coding agent (a single musl binary). It is hosted here for visibility on the Hub; the canonical repository, issue tracker, and pull requests all live on GitHub. Please file issues and contribute there, not here.
+
+<h1 align="center">⚒️ Forge: AI-Enhanced Terminal Development Environment</h1>
+<p align="center">A comprehensive coding agent that integrates AI capabilities with your development environment</p>
+
+<p align="center"><code>curl -fsSL https://forgecode.dev/cli | sh</code></p>
+
+[![CI Status](https://img.shields.io/github/actions/workflow/status/tailcallhq/forgecode/ci.yml?style=for-the-badge)](https://github.com/tailcallhq/forgecode/actions)
+[![GitHub Release](https://img.shields.io/github/v/release/tailcallhq/forgecode?style=for-the-badge)](https://github.com/tailcallhq/forgecode/releases)
+[![Discord](https://img.shields.io/discord/1044859667798568962?style=for-the-badge&cacheSeconds=120&logo=discord)](https://discord.gg/kRZBPpkgwq)
+[![CLA assistant](https://cla-assistant.io/readme/badge/tailcallhq/forgecode?style=for-the-badge)](https://cla-assistant.io/tailcallhq/forgecode)
+
+![Code-Forge Demo](https://assets.antinomy.ai/images/forge_demo_2x.gif)
+
+---
+
+<details>
+<summary><strong>Table&nbsp;of&nbsp;Contents</strong></summary>
+
+- [Quickstart](#quickstart)
+- [Usage Examples](#usage-examples)
+- [Why Forge?](#why-forge)
+- [How Forge Works: Three Modes](#how-forge-works-three-modes)
+  - [Interactive Mode (TUI)](#interactive-mode-tui)
+  - [One-Shot CLI Mode](#one-shot-cli-mode)
+  - [ZSH Plugin Mode (`:` prefix)](#zsh-plugin-mode--prefix)
+- [ZSH Plugin: The `:` Prefix System](#zsh-plugin-the--prefix-system)
+  - [Agents](#agents)
+  - [Sending Prompts](#sending-prompts)
+  - [Attaching Files](#attaching-files)
+  - [Conversation Management](#conversation-management)
+  - [Git Integration](#git-integration)
+  - [Shell Command Tools](#shell-command-tools)
+  - [Session & Configuration](#session--configuration)
+  - [Skills](#skills)
+  - [Customizing Agent Behavior](#customizing-agent-behavior)
+  - [Semantic Search (Workspace)](#semantic-search-workspace)
+  - [Quick Reference: All `:` Commands](#quick-reference-all--commands)
+- [Command-Line Options](#command-line-options)
+- [Advanced Configuration](#advanced-configuration)
+  - [Provider Configuration](#provider-configuration)
+    - [Managing Provider Credentials](#managing-provider-credentials)
+    - [Deprecated: Environment Variables](#deprecated-environment-variables)
+  - [forge.yaml Configuration Options](#forgeyaml-configuration-options)
+  - [Environment Variables](#environment-variables)
+  - [MCP Configuration](#mcp-configuration)
+  - [Example Use Cases](#example-use-cases)
+  - [Usage in Multi-Agent Workflows](#usage-in-multi-agent-workflows)
+- [Documentation](#documentation)
+- [Community](#community)
+- [Support Us](#support-us)
+
+</details>
+
+---
+
+## Quickstart
+
+To get started with Forge, run the command below:
+
+```bash
+curl -fsSL https://forgecode.dev/cli | sh
+```
+
+On first run, Forge will guide you through setting up your AI provider credentials using the interactive login flow. Alternatively, you can configure providers beforehand:
+
+```bash
+# Configure your provider credentials interactively
+forge provider login
+
+# Then start Forge
+forge
+```
+That's it! Forge is now ready to assist you with your development tasks.
+
+## Usage Examples
+
+Forge can be used in different ways depending on your needs. Here are some common usage patterns:
+
+<details>
+<summary><strong>Code Understanding</strong></summary>
+
+```
+> Can you explain how the authentication system works in this codebase?
+```
+
+Forge will analyze your project's structure, identify authentication-related files, and provide a detailed explanation of the authentication flow, including the relationships between different components.
+
+</details>
+
+<details>
+<summary><strong>Implementing New Features</strong></summary>
+
+```
+> I need to add a dark mode toggle to our React application. How should I approach this?
+```
+
+Forge will suggest the best approach based on your current codebase, explain the steps needed, and even scaffold the necessary components and styles for you.
+
+</details>
+
+<details>
+<summary><strong>Debugging Assistance</strong></summary>
+
+```
+> I'm getting this error: "TypeError: Cannot read property 'map' of undefined". What might be causing it?
+```
+
+Forge will analyze the error, suggest potential causes based on your code, and propose different solutions to fix the issue.
+
+</details>
+
+<details>
+<summary><strong>Code Reviews</strong></summary>
+
+```
+> Please review the code in src/components/UserProfile.js and suggest improvements
+```
+
+Forge will analyze the code, identify potential issues, and suggest improvements for readability, performance, security, and maintainability.
+
+</details>
+
+<details>
+<summary><strong>Learning New Technologies</strong></summary>
+
+```
+> I want to integrate GraphQL into this Express application. Can you explain how to get started?
+```
+
+Forge will provide a tailored tutorial on integrating GraphQL with Express, using your specific project structure as context.
+
+</details>
+
+<details>
+<summary><strong>Database Schema Design</strong></summary>
+
+```
+> I need to design a database schema for a blog with users, posts, comments, and categories
+```
+
+Forge will suggest an appropriate schema design, including tables/collections, relationships, indexes, and constraints based on your project's existing database technology.
+
+</details>
+
+<details>
+<summary><strong>Refactoring Legacy Code</strong></summary>
+
+```
+> Help me refactor this class-based component to use React Hooks
+```
+
+Forge can help modernize your codebase by walking you through refactoring steps and implementing them with your approval.
+
+</details>
+
+<details>
+<summary><strong>Git Operations</strong></summary>
+
+```
+> I need to merge branch 'feature/user-profile' into main but there are conflicts
+```
+
+Forge can guide you through resolving git conflicts, explaining the differences and suggesting the best way to reconcile them.
+
+</details>
+
+## Why Forge?
+
+Forge is designed for developers who want to enhance their workflow with AI assistance while maintaining full control over their development environment.
+
+- **Zero configuration** - Just add your API key and you're ready to go
+- **Seamless integration** - Works right in your terminal, where you already work
+- **Multi-provider support** - Use OpenAI, Anthropic, or other LLM providers
+- **Secure by design** - Restricted shell mode limits file system access and prevents unintended changes
+- **Open-source** - Transparent, extensible, and community-driven
+
+Forge helps you code faster, solve complex problems, and learn new technologies without leaving your terminal.
+
+---
+
+## How Forge Works: Three Modes
+
+Forge has three distinct ways to use it. Understanding this distinction upfront will save you confusion.
+
+### Interactive Mode (TUI)
+
+Running `forge` with no arguments starts the interactive terminal UI, a persistent session where you type prompts and the AI responds in a conversational loop. This is the primary way to do multi-step work.
+
+```bash
+forge                              # Start a new interactive session
+forge conversation resume <id>     # Resume a specific saved conversation in interactive mode
+forge --conversation-id <id>       # Same: resume conversation by ID
+forge --agent <agent-id>           # Start interactive session with a specific agent
+forge -C /path/to/project          # Start in a specific directory
+forge --sandbox experiment-name    # Create an isolated git worktree + branch, then start there
+```
+
+Once inside interactive mode, type your prompt and press Enter. Forge reads files, writes patches, runs commands, and maintains context across the whole session.
+
+### One-Shot CLI Mode
+
+Pass `-p` (or `--prompt`) to run a single prompt and exit. Forge does the work and returns to your shell. Useful for scripts, piping output, or quick tasks.
+
+```bash
+forge -p "Explain the purpose of src/main.rs"
+forge -p "Add error handling to the parse() function in lib.rs"
+echo "What does this do?" | forge    # Pipe input as the prompt
+forge commit                         # Generate an AI commit message and commit (exits when done)
+forge commit --preview               # Generate commit message, print it, then exit
+forge suggest "find large log files" # Translate natural language to a shell command, then exit
+```
+
+> **Note:** `forge conversation resume <id>` opens the interactive TUI. It does **not** just print a message and exit. If you run it and see the cursor waiting, you are inside the interactive session. Type your prompt or press `Ctrl+C` to exit.
+
+### ZSH Plugin Mode (`:` prefix)
+
+Install the ZSH plugin once with `forge setup`, then use `:` commands directly at your shell prompt without ever typing `forge`. This is the fastest mode for day-to-day development: send prompts, switch conversations, commit, and suggest commands without leaving your shell.
+
+```zsh
+: refactor the auth module      # Send a prompt to the active agent
+:commit                         # AI-powered git commit
+:suggest "find large log files" # Translate description → shell command in your buffer
+:conversation                   # Browse saved conversations with interactive picker
+```
+
+See the full [ZSH Plugin reference below](#zsh-plugin-the--prefix-system) for all commands and aliases.
+
+---
+
+## ZSH Plugin: The `:` Prefix System
+
+When you install the ZSH plugin (`forge setup`), you get a `:` prefix command system at your shell prompt. This is the fastest way to use Forge during normal development; you never leave your shell.
+
+**How it works:** Lines starting with `:` are intercepted before the shell sees them and routed to Forge. Everything else runs normally.
+
+```zsh
+: <prompt>         # Send a prompt to the active agent
+:sage <prompt>     # Send a prompt to a specific agent by name (sage, muse, forge, or any custom agent)
+:agent <name>      # Switch the active agent; opens interactive picker if no name given
+```
+
+### Agents
+
+Forge ships with three built-in agents, each with a different role:
+
+| Agent | Alias | Purpose | Modifies files? |
+|---|---|---|---|
+| `forge` | (default) | Implementation: builds features, fixes bugs, and runs tests | Yes |
+| `sage` | `:ask` | Research: maps architecture, traces data flow, and reads code | No |
+| `muse` | `:plan` | Planning: analyzes structure and writes implementation plans to `plans/` | No |
+
+### Sending Prompts
+
+```zsh
+: refactor the auth module to use the new middleware
+:sage how does the caching layer work?    # sage = read-only research agent
+:muse design a deployment strategy        # muse = planning agent (writes to plans/)
+:ask how does X work?                     # alias for :sage
+:plan create a migration plan             # alias for :muse
+```
+
+The agent context persists. Typing `:sage` alone (no prompt text) switches the active agent to sage for all subsequent `: <prompt>` commands.
+
+### Attaching Files
+
+Type `@` in a prompt, then press Tab to fuzzy-search and select files. The path is inserted as `@[filename]` and attached as context to the AI.
+
+```zsh
+: review this code @[src/auth.rs] @[tests/auth_test.rs]
+```
+
+### Conversation Management
+
+Forge saves every conversation. You can switch between them like switching directories.
+
+```zsh
+:new                      # Start a fresh conversation (saves current for :conversation -)
+:new <initial prompt>     # Start a new conversation and immediately send a prompt
+:conversation             # Open interactive picker: browse and switch conversations with preview
+:conversation <id>        # Switch directly to a conversation by ID
+:conversation -           # Toggle between current and previous conversation (like cd -)
+:clone                    # Branch the current conversation (try a different direction)
+:clone <id>               # Clone a specific conversation by ID
+:rename <name>            # Rename the current conversation
+:conversation-rename      # Rename a conversation via interactive picker
+:retry                    # Retry the last prompt (useful if the AI misunderstood)
+:copy                     # Copy the last AI response to clipboard as markdown
+:dump                     # Export conversation as JSON
+:dump html                # Export conversation as formatted HTML
+:compact                  # Manually compact context to free up token budget
+```
+
+### Git Integration
+
+```zsh
+:commit                   # AI reads your diff, writes a commit message, and commits immediately
+:commit <context>         # Same, but pass extra context: :commit fix typo in readme
+:commit-preview           # AI generates the message and puts "git commit -m '...'" in your buffer
+                          # so you can review/edit the message before pressing Enter
+```
+
+### Shell Command Tools
+
+```zsh
+:suggest <description>    # Translate natural language to a shell command and put it in your buffer
+:edit                     # Open $EDITOR to compose a complex multi-line prompt, then send it
+```
+
+### Session & Configuration
+
+Some commands change settings for the current session only. Others persist to your config file (`~/forge/.forge.toml`). The distinction matters:
+
+```zsh
+# Session-only (reset when you close the terminal; not saved to config)
+:model <model-id>              # Change model for this session only
+:reasoning-effort <level>      # Set reasoning effort: none/minimal/low/medium/high/xhigh/max
+:agent <id>                    # Switch active agent for this session
+
+# Persistent (saved to config file)
+:config-model <model-id>       # Set default model globally  (alias: :cm)
+:config-provider               # Switch provider globally    (alias: :provider, :p)
+:config-reasoning-effort <lvl> # Set default reasoning effort globally (alias: :cre)
+:config-commit-model <id>      # Set model used for :commit  (alias: :ccm)
+:config-suggest-model <id>     # Set model used for :suggest (alias: :csm)
+:config-reload                 # Reset session overrides back to global config (alias: :cr)
+
+# View & edit config
+:info                          # Show current session info (model, agent, conversation ID)
+:config                        # Display effective resolved configuration in TOML format
+:config-edit                   # Open config file in $EDITOR (alias: :ce)
+:tools                         # List available tools for the current agent
+:skill                         # List available skills
+```
+
+### Skills
+
+Skills are reusable workflows the AI can invoke as tools. Forge ships three built-in skills:
+
+- **`create-skill`**: scaffold a new custom skill
+- **`execute-plan`**: execute a plan file from `plans/`
+- **`github-pr-description`**: generate a PR description from your diff
+
+Use `:skill` to list available skills. The AI invokes them automatically when relevant, or you can ask explicitly: `: generate a PR description using the github-pr-description skill`.
+
+**Custom skills** live in `SKILL.md` files with YAML front-matter. Precedence (highest first):
+
+| Location | Path | Scope |
+|---|---|---|
+| Project-local | `.forge/skills/<name>/SKILL.md` | This project only |
+| Global | `~/forge/skills/<name>/SKILL.md` | All projects |
+| Built-in | Embedded in binary | Always available |
+
+Project-local skills override global ones, which override built-in ones. To scaffold a new skill, ask: `: create a new skill`.
+
+### Customizing Agent Behavior
+
+**`AGENTS.md`:** Create this file in your project root (or `~/forge/AGENTS.md` globally) to give all agents persistent instructions such as coding conventions, commit message style, and things to avoid. Forge reads it automatically at the start of every conversation.
+
+**Custom agents:** Place a `.md` file with YAML front-matter in `.forge/agents/` (project) or `~/forge/agents/` (global) to define additional agents with their own models, tools, and system prompts. Project-local agents override global ones. The built-in agent files in `crates/forge_repo/src/agents/` are good examples of the format.
+
+**Custom commands:** Place YAML files in `.forge/commands/` (project) or `~/forge/commands/` (global) to define shortcut commands available via `:commandname`. Commands can also be defined inline in `forge.yaml` under the `commands:` key.
+
+### Semantic Search (Workspace)
+
+```zsh
+:sync                     # Index your codebase for semantic search
+:workspace-init           # Initialize workspace for indexing
+:workspace-status         # Show indexing status
+:workspace-info           # Show workspace details
+```
+
+After running `:sync`, the AI can search your codebase by meaning rather than exact text matches. Indexing sends file content to the workspace server, which defaults to `https://api.forgecode.dev`. Set `FORGE_WORKSPACE_SERVER_URL` to override this if self-hosting.
+
+### Quick Reference: All `:` Commands
+
+
+| Command | Alias | What it does |
+|---|---|---|
+| `: <prompt>` | | Send prompt to active agent |
+| `:new` | `:n` | Start new conversation |
+| `:conversation` | `:c` | Browse/switch conversations (interactive picker) |
+| `:conversation -` | | Toggle to previous conversation |
+| `:clone` | | Branch current conversation |
+| `:rename <name>` | `:rn` | Rename current conversation |
+| `:conversation-rename` | | Rename conversation (interactive picker) |
+| `:retry` | `:r` | Retry last prompt |
+| `:copy` | | Copy last response to clipboard |
+| `:dump` | `:d` | Export conversation as JSON |
+| `:compact` | | Compact context |
+| `:commit` | | AI commit (immediate) |
+| `:commit-preview` | | AI commit (review first) |
+| `:suggest <desc>` | `:s` | Translate natural language to command |
+| `:edit` | `:ed` | Compose prompt in $EDITOR |
+| `:sage <prompt>` | `:ask` | Q&A / code understanding agent |
+| `:muse <prompt>` | `:plan` | Planning agent |
+| `:agent <name>` | `:a` | Switch active agent (interactive picker if no name given) |
+| `:model <id>` | `:m` | Set model for this session only |
+| `:config-model <id>` | `:cm` | Set default model (persistent) |
+| `:reasoning-effort <lvl>` | `:re` | Set reasoning effort for session |
+| `:config-reload` | `:cr` | Reset session overrides to global config |
+| `:info` | `:i` | Show session info |
+| `:sync` | `:workspace-sync` | Index codebase for semantic search |
+| `:tools` | `:t` | List available tools |
+| `:skill` | | List available skills |
+| `:login` | `:provider-login` | Login to a provider |
+| `:logout` | | Logout from a provider |
+| `:keyboard-shortcuts` | `:kb` | Show keyboard shortcuts |
+| `:doctor` | | Run shell environment diagnostics |
+
+---
+
+## Command-Line Options
+
+Here's a quick reference of Forge's command-line options:
+
+| Option                              | Description                                                              |
+| ----------------------------------- | ------------------------------------------------------------------------ |
+| `-p, --prompt <PROMPT>`             | Direct prompt to process without entering interactive mode               |
+| `-e, --event <EVENT>`               | Dispatch an event to the workflow in JSON format                         |
+| `--conversation <CONVERSATION>`     | Path to a JSON file containing the conversation to execute               |
+| `--conversation-id <ID>`            | Resume or continue an existing conversation by ID                        |
+| `--agent <AGENT>`                   | Agent ID to use for this session                                         |
+| `-C, --directory <DIR>`             | Change to this directory before starting                                 |
+| `--sandbox <NAME>`                  | Create an isolated git worktree + branch for safe experimentation        |
+| `--verbose`                         | Enable verbose logging output                                            |
+| `-h, --help`                        | Print help information                                                   |
+| `-V, --version`                     | Print version                                                            |
+
+### Subcommands
+
+```bash
+# Conversations
+forge conversation list                  # List all saved conversations
+forge conversation resume <id>           # Resume a conversation in interactive mode
+forge conversation new                   # Create a new conversation ID (prints it)
+forge conversation dump <id>             # Export conversation as JSON
+forge conversation compact <id>          # Compact conversation context
+forge conversation retry <id>            # Retry last message
+forge conversation clone <id>            # Clone a conversation
+forge conversation rename <id> <name>    # Rename a conversation
+forge conversation delete <id>           # Delete a conversation permanently
+forge conversation info <id>             # Show conversation details
+forge conversation stats <id>            # Show token usage statistics
+forge conversation show <id>             # Show last assistant message
+
+# Commits
+forge commit                             # Generate AI commit message and commit
+forge commit --preview                   # Generate commit message only (prints it)
+forge commit fix the auth bug            # Pass extra context for the commit message
+
+# Shell command suggestion
+forge suggest "list files by size"       # Translate description to a shell command
+
+# Providers
+forge provider login                     # Add or update provider credentials (interactive)
+forge provider logout                    # Remove provider credentials
+forge list provider                      # List supported providers
+
+# Models & agents
+forge list model                         # List available models
+forge list agent                         # List available agents
+
+# Workspace / semantic search
+forge workspace sync                     # Index current directory for semantic search
+forge workspace init                     # Initialize workspace
+forge workspace status                   # Show indexing status
+forge workspace query <text>             # Query the semantic index
+
+# MCP servers
+forge mcp list                           # List configured MCP servers
+forge mcp import                         # Add a server from JSON
+forge mcp show                           # Show server configuration
+forge mcp remove                         # Remove a server
+forge mcp reload                         # Reload all servers and rebuild caches
+
+# Other
+forge info                               # Show config, active model, environment
+forge list tool --agent <id>             # List tools for a specific agent
+forge doctor                             # Run shell environment diagnostics
+forge update                             # Update forge to the latest version
+forge setup                              # Install ZSH plugin (updates .zshrc)
+```
+
+## Advanced Configuration
+
+### Provider Configuration
+
+Forge supports multiple AI providers. The recommended way to configure providers is using the interactive login command:
+
+```bash
+forge provider login
+```
+
+This will:
+
+1. Show you a list of available providers
+2. Guide you through entering the required credentials
+
+#### Managing Provider Credentials
+
+```bash
+# Login to a provider (add or update credentials)
+forge provider login
+
+# Remove provider credentials
+forge provider logout
+
+# List supported providers
+forge provider list
+```
+
+#### Deprecated: Environment Variables
+
+> **⚠️ DEPRECATED**: Using `.env` files for provider configuration is deprecated and will be removed in a future version. Please use `forge provider login` instead.
+
+For backward compatibility, Forge still supports environment variables. On first run, any credentials found in environment variables will be automatically migrated to file-based storage.
+
+<details>
+<summary><strong>Legacy Environment Variable Setup (Deprecated)</strong></summary>
+
+<details>
+<summary><strong>OpenRouter</strong></summary>
+
+```bash
+# .env
+OPENROUTER_API_KEY=<your_openrouter_api_key>
+```
+
+</details>
+
+<details>
+<summary><strong>Requesty</strong></summary>
+
+```bash
+# .env
+REQUESTY_API_KEY=<your_requesty_api_key>
+```
+
+</details>
+
+<details>
+<summary><strong>x-ai</strong></summary>
+
+```bash
+# .env
+XAI_API_KEY=<your_xai_api_key>
+```
+
+</details>
+
+<details>
+<summary><strong>z.ai</strong></summary>
+
+```bash
+# .env
+ZAI_API_KEY=<your_zai_api_key>
+
+# Or for coding plan subscription
+ZAI_CODING_API_KEY=<your_zai_coding_api_key>
+```
+
+</details>
+
+<details>
+<summary><strong>Cerebras</strong></summary>
+
+```bash
+# .env
+CEREBRAS_API_KEY=<your_cerebras_api_key>
+```
+
+</details>
+
+<details>
+<summary><strong>Neuralwatt</strong></summary>
+
+```bash
+# .env
+NEURALWATT_API_KEY=<your_neuralwatt_api_key>
+```
+
+</details>
+
+<details>
+<summary><strong>OrcaRouter</strong></summary>
+
+```bash
+# .env
+ORCAROUTER_API_KEY=<your_orcarouter_api_key>
+```
+
+</details>
+
+<details>
+<summary><strong>Meta</strong></summary>
+
+```bash
+# .env
+META_API_KEY=<your_meta_model_api_key>
+```
+
+```yaml
+# forge.yaml
+model: muse-spark-1.1
+```
+
+</details>
+
+<details>
+<summary><strong>IO Intelligence</strong></summary>
+
+```bash
+# .env
+IO_INTELLIGENCE_API_KEY=<your_io_intelligence_api_key>
+```
+
+```yaml
+# forge.yaml
+model: meta-llama/Llama-3.3-70B-Instruct
+```
+
+</details>
+
+<details>
+<summary><strong>OpenAI</strong></summary>
+
+```bash
+# .env
+OPENAI_API_KEY=<your_openai_api_key>
+```
+
+```yaml
+# forge.yaml
+model: o3-mini-high
+```
+
+</details>
+
+<details>
+<summary><strong>Anthropic</strong></summary>
+
+```bash
+# .env
+ANTHROPIC_API_KEY=<your_anthropic_api_key>
+```
+
+```yaml
+# forge.yaml
+model: claude-3.7-sonnet
+```
+
+</details>
+
+<details>
+<summary><strong>Google Vertex AI</strong></summary>
+
+**Setup Instructions:**
+
+1. **Install Google Cloud CLI** and authenticate:
+
+   ```bash
+   gcloud auth login
+   gcloud config set project YOUR_PROJECT_ID
+   ```
+
+2. **Get your authentication token**:
+
+   ```bash
+   gcloud auth print-access-token
+   ```
+
+3. **Use the token when logging in via Forge**:
+
+   ```bash
+   forge provider login
+   # Select Google Vertex AI and enter your credentials
+   ```
+
+**Legacy `.env` setup:**
+
+```bash
+# .env
+PROJECT_ID=<your_project_id>
+LOCATION=<your_location>
+VERTEX_AI_AUTH_TOKEN=<your_auth_token>
+```
+
+```yaml
+# forge.yaml
+model: google/gemini-2.5-pro
+```
+
+**Available Models:**
+- Claude models: `claude-sonnet-4@20250514`
+- Gemini models: `gemini-2.5-pro`, `gemini-2.0-flash`
+
+Use the `/model` command in Forge CLI to see all available models.
+
+</details>
+
+<details>
+<summary><strong>OpenAI-Compatible Providers</strong></summary>
+
+```bash
+# .env
+OPENAI_API_KEY=<your_provider_api_key>
+OPENAI_URL=<your_provider_url>
+```
+
+```yaml
+# forge.yaml
+model: <provider-specific-model>
+```
+
+</details>
+
+<details>
+<summary><strong>Groq</strong></summary>
+
+```bash
+# .env
+OPENAI_API_KEY=<your_groq_api_key>
+OPENAI_URL=https://api.groq.com/openai/v1
+```
+
+```yaml
+# forge.yaml
+model: deepseek-r1-distill-llama-70b
+```
+
+</details>
+
+<details>
+<summary><strong>Amazon Bedrock</strong></summary>
+
+To use Amazon Bedrock models with Forge, you'll need to first set up the [Bedrock Access Gateway](https://github.com/aws-samples/bedrock-access-gateway):
+
+1. **Set up Bedrock Access Gateway**:
+
+   - Follow the deployment steps in the [Bedrock Access Gateway repo](https://github.com/aws-samples/bedrock-access-gateway)
+   - Create your own API key in Secrets Manager
+   - Deploy the CloudFormation stack
+   - Note your API Base URL from the CloudFormation outputs
+
+2. **Configure in Forge**:
+
+   ```bash
+   forge provider login
+   # Select OpenAI-compatible provider and enter your Bedrock Gateway details
+   ```
+
+**Legacy `.env` setup:**
+
+```bash
+# .env
+OPENAI_API_KEY=<your_bedrock_gateway_api_key>
+OPENAI_URL=<your_bedrock_gateway_base_url>
+```
+
+```yaml
+# forge.yaml
+model: anthropic.claude-3-opus
+```
+
+</details>
+
+<details>
+<summary><strong>ForgeCode Services</strong></summary>
+
+```bash
+# .env
+FORGE_API_KEY=<your_forge_api_key>
+```
+
+```yaml
+# forge.yaml
+model: claude-3.7-sonnet
+```
+
+</details>
+
+</details>
+
+---
+
+### forge.yaml Configuration Options
+
+### Environment Variables
+
+Forge supports several environment variables for advanced configuration and fine-tuning. These can be set in your `.env` file or system environment.
+
+<details>
+<summary><strong>Retry Configuration</strong></summary>
+
+Control how Forge handles retry logic for failed requests:
+
+```bash
+# .env
+FORGE_RETRY_INITIAL_BACKOFF_MS=1000    # Initial backoff time in milliseconds (default: 1000)
+FORGE_RETRY_BACKOFF_FACTOR=2           # Multiplier for backoff time (default: 2)
+FORGE_RETRY_MAX_ATTEMPTS=3             # Maximum retry attempts (default: 3)
+FORGE_SUPPRESS_RETRY_ERRORS=false      # Suppress retry error messages (default: false)
+FORGE_RETRY_STATUS_CODES=429,500,502   # HTTP status codes to retry (default: 429,500,502,503,504)
+```
+
+</details>
+
+<details>
+<summary><strong>HTTP Configuration</strong></summary>
+
+Fine-tune HTTP client behavior for API requests:
+
+```bash
+# .env
+FORGE_HTTP_CONNECT_TIMEOUT=30              # Connection timeout in seconds (default: 30)
+FORGE_HTTP_READ_TIMEOUT=900                # Read timeout in seconds (default: 900)
+FORGE_HTTP_POOL_IDLE_TIMEOUT=90            # Pool idle timeout in seconds (default: 90)
+FORGE_HTTP_POOL_MAX_IDLE_PER_HOST=5        # Max idle connections per host (default: 5)
+FORGE_HTTP_MAX_REDIRECTS=10                # Maximum redirects to follow (default: 10)
+FORGE_HTTP_USE_HICKORY=false               # Use Hickory DNS resolver (default: false)
+FORGE_HTTP_TLS_BACKEND=default             # TLS backend: "default" or "rustls" (default: "default")
+FORGE_HTTP_MIN_TLS_VERSION=1.2             # Minimum TLS version: "1.0", "1.1", "1.2", "1.3"
+FORGE_HTTP_MAX_TLS_VERSION=1.3             # Maximum TLS version: "1.0", "1.1", "1.2", "1.3"
+FORGE_HTTP_ADAPTIVE_WINDOW=true            # Enable HTTP/2 adaptive window (default: true)
+FORGE_HTTP_KEEP_ALIVE_INTERVAL=60          # Keep-alive interval in seconds (default: 60, use "none"/"disabled" to disable)
+FORGE_HTTP_KEEP_ALIVE_TIMEOUT=10           # Keep-alive timeout in seconds (default: 10)
+FORGE_HTTP_KEEP_ALIVE_WHILE_IDLE=true      # Keep-alive while idle (default: true)
+FORGE_HTTP_ACCEPT_INVALID_CERTS=false      # Accept invalid certificates (default: false) - USE WITH CAUTION
+FORGE_HTTP_ROOT_CERT_PATHS=/path/to/cert1.pem,/path/to/cert2.crt  # Paths to root certificate files (PEM, CRT, CER format), multiple paths separated by commas
+```
+
+> **⚠️ Security Warning**: Setting `FORGE_HTTP_ACCEPT_INVALID_CERTS=true` disables SSL/TLS certificate verification, which can expose you to man-in-the-middle attacks. Only use this in development environments or when you fully trust the network and endpoints.
+
+</details>
+
+<details>
+<summary><strong>API Configuration</strong></summary>
+
+Override default API endpoints and provider/model settings:
+
+```bash
+# .env
+FORGE_API_URL=https://api.forgecode.dev  # Custom Forge API URL (default: https://api.forgecode.dev)
+FORGE_WORKSPACE_SERVER_URL=http://localhost:8080  # URL for the indexing server (default: https://api.forgecode.dev/)
+```
+
+</details>
+
+<details>
+<summary><strong>Tool Configuration</strong></summary>
+
+Configuring the tool calls settings:
+
+```bash
+# .env
+FORGE_TOOL_TIMEOUT=300         # Maximum execution time in seconds for a tool before it is terminated to prevent hanging the session. (default: 300)
+FORGE_MAX_IMAGE_SIZE=10485760  # Maximum image file size in bytes for read_image operations (default: 10485760 - 10 MB)
+FORGE_DUMP_AUTO_OPEN=false     # Automatically open dump files in browser (default: false)
+FORGE_DEBUG_REQUESTS=/path/to/debug/requests.json  # Write debug HTTP request files to specified path (supports absolute and relative paths)
+```
+
+</details>
+
+<details>
+<summary><strong>ZSH Plugin Configuration</strong></summary>
+
+Configure the ZSH plugin behavior:
+
+```bash
+# .env
+FORGE_BIN=forge                    # Command to use for forge operations (default: "forge")
+```
+
+The `FORGE_BIN` environment variable allows you to customize the command used by the ZSH plugin when transforming `:` prefixed commands. If not set, it defaults to `"forge"`.
+
+</details>
+
+<details>
+<summary><strong>Display Configuration</strong></summary>
+
+Configure display options for the Forge UI and ZSH theme:
+
+```bash
+# .env
+FORGE_CURRENCY_SYMBOL="$"         # Currency symbol for cost display in ZSH theme (default: "$")
+FORGE_CURRENCY_CONVERSION_RATE=1.0  # Conversion rate for currency display (default: 1.0)
+NERD_FONT=1                       # Enable Nerd Font icons in ZSH theme (default: auto-detected, set to "1" or "true" to enable, "0" or "false" to disable)
+USE_NERD_FONT=1                   # Alternative variable for enabling Nerd Font icons (same behavior as NERD_FONT)
+```
+
+The `FORGE_CURRENCY_SYMBOL` and `FORGE_CURRENCY_CONVERSION_RATE` variables control how costs are displayed in the ZSH theme right prompt. Use these to customize the currency display for your region or preferred currency.
+
+</details>
+
+<details>
+<summary><strong>System Configuration</strong></summary>
+
+System-level environment variables (usually set automatically):
+
+```bash
+# .env
+FORGE_CONFIG=/custom/config/dir        # Base directory for all Forge config files (default: ~/.forge)
+FORGE_MAX_SEARCH_RESULT_BYTES=10240   # Maximum bytes for search results (default: 10240 - 10 KB)
+FORGE_HISTORY_FILE=/path/to/history    # Custom path for Forge history file (default: uses system default location)
+FORGE_BANNER="Your custom banner text" # Custom banner text to display on startup (default: Forge ASCII art)
+FORGE_MAX_CONVERSATIONS=100            # Maximum number of conversations to show in list (default: 100)
+FORGE_MAX_LINE_LENGTH=2000             # Maximum characters per line for file read operations (default: 2000)
+FORGE_STDOUT_MAX_LINE_LENGTH=2000      # Maximum characters per line for shell output (default: 2000)
+SHELL=/bin/zsh                         # Shell to use for command execution (Unix/Linux/macOS)
+COMSPEC=cmd.exe                        # Command processor to use (Windows)
+```
+
+</details>
+
+<details>
+<summary><strong>Semantic Search Configuration</strong></summary>
+
+Configure semantic search behavior for code understanding:
+
+```bash
+# .env
+FORGE_SEM_SEARCH_LIMIT=200            # Maximum number of results to return from initial vector search (default: 200)
+FORGE_SEM_SEARCH_TOP_K=20             # Top-k parameter for relevance filtering during semantic search (default: 20)
+```
+
+</details>
+
+<details>
+<summary><strong>Logging Configuration</strong></summary>
+
+Configure logging verbosity and output:
+
+```bash
+# .env
+FORGE_LOG=forge=info                  # Log filter level (default: forge=debug when tracking disabled, forge=info when tracking enabled)
+```
+
+The `FORGE_LOG` variable controls the logging level for Forge's internal operations using the standard tracing filter syntax. Common values:
+- `forge=error` - Only errors
+- `forge=warn` - Warnings and errors
+- `forge=info` - Informational messages (default when tracking enabled)
+- `forge=debug` - Debug information (default when tracking disabled)
+- `forge=trace` - Detailed tracing
+
+</details>
+
+<details>
+<summary><strong>Tracking Configuration</strong></summary>
+
+Control tracking of user-identifying metadata in telemetry events:
+
+```bash
+# .env
+FORGE_TRACKER=false                   # Disable tracking enrichment metadata (default: true)
+```
+
+The `FORGE_TRACKER` variable controls whether tracking enrichment metadata is included in telemetry events.
+
+</details>
+
+The `forge.yaml` file supports several advanced configuration options that let you customize Forge's behavior.
+
+<details>
+<summary><strong>Custom Rules</strong></summary>
+
+Add your own guidelines that all agents should follow when generating responses.
+
+```yaml
+# forge.yaml
+custom_rules: |
+  1. Always add comprehensive error handling to any code you write.
+  2. Include unit tests for all new functions.
+  3. Follow our team's naming convention: camelCase for variables, PascalCase for classes.
+```
+
+</details>
+
+<details>
+<summary><strong>Commands</strong></summary>
+
+Define custom commands as shortcuts for repetitive prompts:
+
+```yaml
+# forge.yaml
+commands:
+  - name: "refactor"
+    description: "Refactor selected code"
+    prompt: "Please refactor this code to improve readability and performance"
+```
+
+</details>
+
+<details>
+<summary><strong>Model</strong></summary>
+
+Specify the default AI model to use for all agents in the workflow.
+
+```yaml
+# forge.yaml
+model: "claude-3.7-sonnet"
+```
+
+</details>
+
+<details>
+<summary><strong>Max Walker Depth</strong></summary>
+
+Control how deeply Forge traverses your project directory structure when gathering context.
+
+```yaml
+# forge.yaml
+max_walker_depth: 3 # Limit directory traversal to 3 levels deep
+```
+
+</details>
+
+<details>
+<summary><strong>Temperature</strong></summary>
+
+Adjust the creativity and randomness in AI responses. Lower values (0.0-0.3) produce more focused, deterministic outputs, while higher values (0.7-2.0) generate more diverse and creative results.
+
+```yaml
+# forge.yaml
+temperature: 0.7 # Balanced creativity and focus
+```
+
+</details>
+<details>
+<summary><strong>Tool Max Failure Limit</strong></summary>
+
+Control how many times a tool can fail before Forge forces completion to prevent infinite retry loops. This helps avoid situations where an agent gets stuck repeatedly trying the same failing operation.
+
+```yaml
+# forge.yaml
+max_tool_failure_per_turn: 3 # Allow up to 3 failures per tool before forcing completion
+```
+
+Set to a higher value if you want more retry attempts, or lower if you want faster failure detection.
+
+</details>
+
+<details>
+<summary><strong>Max Requests Per Turn</strong></summary>
+
+Limit the maximum number of requests an agent can make in a single conversation turn. This prevents runaway conversations and helps control API usage and costs.
+
+```yaml
+# forge.yaml
+max_requests_per_turn: 50 # Allow up to 50 requests per turn
+```
+
+When this limit is reached, Forge will:
+
+- Ask you if you wish to continue
+- If you respond with 'Yes', it will continue the conversation
+- If you respond with 'No', it will end the conversation
+
+</details>
+
+---
+
+<details>
+<summary><strong>Model Context Protocol (MCP)</strong></summary>
+
+The MCP feature allows AI agents to communicate with external tools and services. This implementation follows Anthropic's [Model Context Protocol](https://docs.anthropic.com/en/docs/claude-code/tutorials#set-up-model-context-protocol-mcp) design.
+
+### MCP Configuration
+
+Configure MCP servers using the CLI:
+
+```bash
+# List all MCP servers
+forge mcp list
+
+# Import a server from JSON
+forge mcp import
+
+# Show server configuration details
+forge mcp show
+
+# Remove a server
+forge mcp remove
+
+# Reload servers and rebuild caches
+forge mcp reload
+```
+
+Or manually create a `.mcp.json` file with the following structure:
+
+```json
+{
+  "mcpServers": {
+    "server_name": {
+      "command": "command_to_execute",
+      "args": ["arg1", "arg2"],
+      "env": { "ENV_VAR": "value" }
+    },
+    "another_server": {
+      "url": "http://localhost:3000/events"
+    }
+  }
+}
+```
+
+MCP configurations are read from two locations (project-local takes precedence):
+
+1. **Project-local:** `.mcp.json` in your project directory
+2. **Global:** `~/forge/.mcp.json`
+
+### Example Use Cases
+
+MCP can be used for various integrations:
+
+- Web browser automation
+- External API interactions
+- Tool integration
+- Custom service connections
+
+### Usage in Multi-Agent Workflows
+
+MCP tools can be used as part of multi-agent workflows, allowing specialized agents to interact with external systems as part of a collaborative problem-solving approach.
+
+</details>
+
+---
+
+## Documentation
+
+For comprehensive documentation on all features and capabilities, please visit the [documentation site](https://github.com/tailcallhq/forgecode/tree/main/docs).
+
+---
+
+## Installation
+
+```bash
+# YOLO
+curl -fsSL https://forgecode.dev/cli | sh
+
+# Package managers
+nix run github:tailcallhq/forgecode # for latest dev branch
+```
+
+---
+
+## Community
+
+Join our vibrant Discord community to connect with other Forge users and contributors, get help with your projects, share ideas, and provide feedback!
+
+[![Discord](https://img.shields.io/discord/1044859667798568962?style=for-the-badge&cacheSeconds=120&logo=discord)](https://discord.gg/kRZBPpkgwq)
+
+---
+
+## Support Us
+
+Your support drives Forge's continued evolution! By starring our GitHub repository, you:
+
+- Help others discover this powerful tool 🔍
+- Motivate our development team 💪
+- Enable us to prioritize new features 🛠️
+- Strengthen our open-source community 🌱

_config.yml

@@ -0,0 +1,3 @@
+remote_theme: pages-themes/hacker@v0.2.0
+plugins:
+- jekyll-remote-theme

clippy.toml

@@ -0,0 +1,3 @@
+disallowed-methods = [
+  { path = "std::string::String::from_utf8_lossy", reason = "Prefer bstr ByteSlice decoding so lossy UTF-8 handling stays explicit and consistent across byte-oriented paths.", replacement = "bstr::ByteSlice::to_str_lossy" },
+]

diesel.toml

@@ -0,0 +1,5 @@
+[print_schema]
+file = "crates/forge_repo/src/database/schema.rs"
+
+[migrations_directory]
+dir = "crates/forge_repo/src/database/migrations"

flake.lock

@@ -0,0 +1,27 @@
+{
+  "nodes": {
+    "nixpkgs": {
+      "locked": {
+        "lastModified": 1773282481,
+        "narHash": "sha256-b/GV2ysM8mKHhinse2wz+uP37epUrSE+sAKXy/xvBY4=",
+        "owner": "NixOS",
+        "repo": "nixpkgs",
+        "rev": "fe416aaedd397cacb33a610b33d60ff2b431b127",
+        "type": "github"
+      },
+      "original": {
+        "owner": "NixOS",
+        "ref": "nixos-unstable",
+        "repo": "nixpkgs",
+        "type": "github"
+      }
+    },
+    "root": {
+      "inputs": {
+        "nixpkgs": "nixpkgs"
+      }
+    }
+  },
+  "root": "root",
+  "version": 7
+}

flake.nix

@@ -0,0 +1,159 @@
+{
+  description = "forge: AI enabled pair programmer for Claude, GPT, O Series, Grok, Deepseek, Gemini and 300+ models";
+
+  inputs = {
+    nixpkgs.url = "github:NixOS/nixpkgs/nixos-unstable";
+  };
+
+  outputs = { self, nixpkgs }:
+    let
+      systems = [
+        "x86_64-linux"
+        "aarch64-linux"
+        "x86_64-darwin"
+        "aarch64-darwin"
+      ];
+      forAllSystems = nixpkgs.lib.genAttrs systems;
+    in
+    {
+      formatter = forAllSystems (system:
+        let
+          pkgs = import nixpkgs { inherit system; };
+        in
+        pkgs.nixfmt-rfc-style
+      );
+
+      packages = forAllSystems (system:
+        let
+          pkgs = import nixpkgs { inherit system; };
+          lib = pkgs.lib;
+          src = lib.cleanSourceWith {
+            src = ./.;
+            filter = path: type:
+              lib.cleanSourceFilter path type
+              && baseNameOf path != "target"
+              && baseNameOf path != "result";
+          };
+          forge = pkgs.rustPlatform.buildRustPackage {
+            pname = "forge";
+            version = "0.1.0-dev";
+            inherit src;
+
+            cargoLock = {
+              lockFile = ./Cargo.lock;
+              allowBuiltinFetchGit = true;
+            };
+
+            cargoBuildFlags = [
+              "-p"
+              "forge_main"
+              "--bin"
+              "forge"
+            ];
+            cargoInstallFlags = [
+              "-p"
+              "forge_main"
+              "--bin"
+              "forge"
+            ];
+
+            nativeBuildInputs = [
+              pkgs.cmake
+              pkgs.nasm
+              pkgs.perl
+              pkgs.pkg-config
+              pkgs.protobuf
+            ];
+
+            buildInputs =
+              [ pkgs.sqlite ]
+              ++ lib.optionals pkgs.stdenv.isLinux [
+                pkgs.libxkbcommon
+                pkgs.libx11
+                pkgs.libxext
+                pkgs.libxfixes
+                pkgs.libxcb
+                pkgs.wayland
+              ]
+              ++ lib.optionals pkgs.stdenv.isDarwin [
+                pkgs.libiconv
+                pkgs.apple-sdk
+              ];
+
+            PROTOC = "${pkgs.protobuf}/bin/protoc";
+            PROTOC_INCLUDE = "${pkgs.protobuf}/include";
+            APP_VERSION = "0.1.0-dev";
+
+            doCheck = false;
+
+            meta = {
+              description = "forge: AI enabled pair programmer for Claude, GPT, O Series, Grok, Deepseek, Gemini and 300+ models";
+              homepage = "https://forgecode.dev";
+              license = lib.licenses.mit;
+              mainProgram = "forge";
+              platforms = lib.platforms.unix;
+            };
+          };
+        in
+        {
+          default = forge;
+          forge = forge;
+        }
+      );
+
+      apps = forAllSystems (system: {
+        default = {
+          type = "app";
+          program = "${self.packages.${system}.default}/bin/forge";
+        };
+        forge = {
+          type = "app";
+          program = "${self.packages.${system}.forge}/bin/forge";
+        };
+      });
+
+      devShells = forAllSystems (system:
+        let
+          pkgs = import nixpkgs { inherit system; };
+          lib = pkgs.lib;
+        in
+        {
+          default = pkgs.mkShell {
+            packages =
+              [
+                pkgs.cargo
+                pkgs.cargo-insta
+                pkgs.cargo-llvm-cov
+                pkgs.clippy
+                pkgs.cmake
+                pkgs.nasm
+                pkgs.perl
+                pkgs.pkg-config
+                pkgs.protobuf
+                pkgs.rust-analyzer
+                pkgs.rustc
+                pkgs.rustfmt
+                pkgs.sqlite
+              ]
+              ++ lib.optionals pkgs.stdenv.isLinux [
+                pkgs.libxkbcommon
+                pkgs.libx11
+                pkgs.libxext
+                pkgs.libxfixes
+                pkgs.libxcb
+                pkgs.wayland
+              ]
+              ++ lib.optionals pkgs.stdenv.isDarwin [
+                pkgs.libiconv
+                pkgs.darwin.apple_sdk.frameworks.AppKit
+                pkgs.darwin.apple_sdk.frameworks.CoreGraphics
+                pkgs.darwin.apple_sdk.frameworks.Foundation
+              ];
+
+            PROTOC = "${pkgs.protobuf}/bin/protoc";
+            PROTOC_INCLUDE = "${pkgs.protobuf}/include";
+            APP_VERSION = "0.1.0-dev";
+          };
+        });
+    };
+}

forge.schema.json

@@ -0,0 +1,1037 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "title": "ForgeConfig",
+  "description": "Top-level Forge configuration merged from all sources (defaults, file,\nenvironment).",
+  "type": "object",
+  "properties": {
+    "auto_dump": {
+      "description": "Format used when automatically creating a session dump after task\ncompletion; disabled when absent.",
+      "anyOf": [
+        {
+          "$ref": "#/$defs/AutoDumpFormat"
+        },
+        {
+          "type": "null"
+        }
+      ]
+    },
+    "auto_install_vscode_extension": {
+      "description": "Enables automatic VS Code extension installation when Forge runs inside\nVS Code and the extension is not already installed.",
+      "type": "boolean",
+      "default": false
+    },
+    "auto_open_dump": {
+      "description": "Whether to automatically open HTML dump files in the browser after\ncreation.",
+      "type": "boolean",
+      "default": false
+    },
+    "commit": {
+      "description": "Model and provider configuration used for commit message generation.",
+      "anyOf": [
+        {
+          "$ref": "#/$defs/ModelConfig"
+        },
+        {
+          "type": "null"
+        }
+      ]
+    },
+    "compact": {
+      "description": "Context compaction settings applied to all agents; falls back to each\nagent's individual setting when absent.",
+      "anyOf": [
+        {
+          "$ref": "#/$defs/Compact"
+        },
+        {
+          "type": "null"
+        }
+      ]
+    },
+    "currency_conversion_rate": {
+      "description": "Conversion rate applied to costs before display in the shell rprompt.\nThe raw USD cost is multiplied by this value, allowing costs to be shown\nin a local currency. Defaults to `1.0` (no conversion).",
+      "$ref": "#/$defs/double",
+      "default": 0.0
+    },
+    "currency_symbol": {
+      "description": "Currency symbol displayed in the shell rprompt next to the session cost\n(e.g. `\"$\"`, `\"€\"`, `\"₹\"`). Defaults to `\"$\"`.",
+      "type": "string",
+      "default": ""
+    },
+    "custom_history_path": {
+      "description": "Path to the conversation history file; defaults to the global history\nlocation when absent.",
+      "type": [
+        "string",
+        "null"
+      ]
+    },
+    "debug_requests": {
+      "description": "Directory where debug request files are written; disabled when absent.",
+      "type": [
+        "string",
+        "null"
+      ]
+    },
+    "http": {
+      "description": "HTTP client settings including proxy, TLS, and timeout configuration.",
+      "anyOf": [
+        {
+          "$ref": "#/$defs/HttpConfig"
+        },
+        {
+          "type": "null"
+        }
+      ]
+    },
+    "max_commit_count": {
+      "description": "Maximum number of recent commits included as context for commit message\ngeneration.",
+      "type": "integer",
+      "format": "uint",
+      "default": 0,
+      "minimum": 0
+    },
+    "max_conversations": {
+      "description": "Maximum number of conversations shown in the conversation list.",
+      "type": "integer",
+      "format": "uint",
+      "default": 0,
+      "minimum": 0
+    },
+    "max_extensions": {
+      "description": "Maximum number of file extensions included in the agent system prompt.",
+      "type": "integer",
+      "format": "uint",
+      "default": 0,
+      "minimum": 0
+    },
+    "max_fetch_chars": {
+      "description": "Maximum number of characters returned from a URL fetch.",
+      "type": "integer",
+      "format": "uint",
+      "default": 0,
+      "minimum": 0
+    },
+    "max_file_read_batch_size": {
+      "description": "Maximum number of files read in a single batch operation.",
+      "type": "integer",
+      "format": "uint",
+      "default": 0,
+      "minimum": 0
+    },
+    "max_file_size_bytes": {
+      "description": "Maximum file size in bytes permitted for read operations.",
+      "type": "integer",
+      "format": "uint64",
+      "default": 0,
+      "minimum": 0
+    },
+    "max_image_size_bytes": {
+      "description": "Maximum image file size in bytes permitted for read operations.",
+      "type": "integer",
+      "format": "uint64",
+      "default": 0,
+      "minimum": 0
+    },
+    "max_line_chars": {
+      "description": "Maximum number of characters per line when reading a file.",
+      "type": "integer",
+      "format": "uint",
+      "default": 0,
+      "minimum": 0
+    },
+    "max_parallel_file_reads": {
+      "description": "Maximum number of files read concurrently during batch operations.",
+      "type": "integer",
+      "format": "uint",
+      "default": 0,
+      "minimum": 0
+    },
+    "max_read_lines": {
+      "description": "Maximum number of lines read from a file in a single operation.",
+      "type": "integer",
+      "format": "uint64",
+      "default": 0,
+      "minimum": 0
+    },
+    "max_requests_per_turn": {
+      "description": "Maximum number of requests that can be made in a single turn.",
+      "type": [
+        "integer",
+        "null"
+      ],
+      "format": "uint",
+      "minimum": 0
+    },
+    "max_search_lines": {
+      "description": "Maximum number of lines returned by a single file search operation.",
+      "type": "integer",
+      "format": "uint",
+      "default": 0,
+      "minimum": 0
+    },
+    "max_search_result_bytes": {
+      "description": "Maximum number of bytes returned by a single file search operation.",
+      "type": "integer",
+      "format": "uint",
+      "default": 0,
+      "minimum": 0
+    },
+    "max_sem_search_results": {
+      "description": "Maximum number of candidate results returned from the initial semantic\nsearch vector query.",
+      "type": "integer",
+      "format": "uint",
+      "default": 0,
+      "minimum": 0
+    },
+    "max_stdout_line_chars": {
+      "description": "Maximum number of characters per line in shell command output.",
+      "type": "integer",
+      "format": "uint",
+      "default": 0,
+      "minimum": 0
+    },
+    "max_stdout_prefix_lines": {
+      "description": "Maximum number of lines captured from the leading portion of shell\ncommand output.",
+      "type": "integer",
+      "format": "uint",
+      "default": 0,
+      "minimum": 0
+    },
+    "max_stdout_suffix_lines": {
+      "description": "Maximum number of lines captured from the trailing portion of shell\ncommand output.",
+      "type": "integer",
+      "format": "uint",
+      "default": 0,
+      "minimum": 0
+    },
+    "max_tokens": {
+      "description": "Maximum tokens the model may generate per response for all agents\n(1–100,000).",
+      "type": [
+        "integer",
+        "null"
+      ],
+      "format": "uint32",
+      "minimum": 0
+    },
+    "max_tool_failure_per_turn": {
+      "description": "Maximum tool failures per turn before the orchestrator forces\ncompletion.",
+      "type": [
+        "integer",
+        "null"
+      ],
+      "format": "uint",
+      "minimum": 0
+    },
+    "merge_system_messages": {
+      "description": "When `true`, all system messages in the conversation are merged into a\nsingle leading system message before the request is sent. Enable this\nfor providers that reject requests containing system messages after\nuser or assistant turns (e.g. vLLM, NVIDIA NIM).",
+      "type": "boolean",
+      "default": false
+    },
+    "model_cache_ttl_secs": {
+      "description": "Time-to-live in seconds for the cached model API list.",
+      "type": "integer",
+      "format": "uint64",
+      "default": 0,
+      "minimum": 0
+    },
+    "providers": {
+      "description": "Additional provider definitions merged with the built-in provider list.\n\nEntries with an `id` matching a built-in provider override its fields;\nentries with a new `id` are appended and become available for model\nselection.",
+      "type": "array",
+      "items": {
+        "$ref": "#/$defs/ProviderEntry"
+      }
+    },
+    "reasoning": {
+      "description": "Reasoning configuration applied to all agents; controls effort level,\ntoken budget, and visibility of the model's thinking process.",
+      "anyOf": [
+        {
+          "$ref": "#/$defs/ReasoningConfig"
+        },
+        {
+          "type": "null"
+        }
+      ]
+    },
+    "research_subagent": {
+      "description": "Whether the deep research agent is available.\n\nWhen set to `true`, the Sage agent is added to the agent list and\nthe `:sage` app command is enabled. Defaults to `false`.",
+      "type": "boolean",
+      "default": false
+    },
+    "restricted": {
+      "description": "Whether restricted mode is active; when enabled, tool execution requires\nexplicit permission grants.",
+      "type": "boolean",
+      "default": false
+    },
+    "retry": {
+      "description": "Retry settings applied at the system level to all IO operations.",
+      "anyOf": [
+        {
+          "$ref": "#/$defs/RetryConfig"
+        },
+        {
+          "type": "null"
+        }
+      ]
+    },
+    "sem_search_top_k": {
+      "description": "Number of top results retained after re-ranking in semantic search.",
+      "type": "integer",
+      "format": "uint",
+      "default": 0,
+      "minimum": 0
+    },
+    "services_url": {
+      "description": "Base URL of the Forge services API used for semantic search and\nindexing.",
+      "type": "string",
+      "default": ""
+    },
+    "session": {
+      "description": "Default model and provider configuration used when not overridden by\nindividual agents.",
+      "anyOf": [
+        {
+          "$ref": "#/$defs/ModelConfig"
+        },
+        {
+          "type": "null"
+        }
+      ]
+    },
+    "subagents": {
+      "description": "Enables subagent support via the task tool; when true the forge agent\ngains access to the `task` tool for delegating work to specialised\nsub-agents, and the `sage` research-only agent tool is removed.\nWhen false the `task` tool is disabled and `sage` is available instead.",
+      "type": "boolean",
+      "default": false
+    },
+    "suggest": {
+      "description": "Model and provider configuration used for shell command suggestion\ngeneration.",
+      "anyOf": [
+        {
+          "$ref": "#/$defs/ModelConfig"
+        },
+        {
+          "type": "null"
+        }
+      ]
+    },
+    "temperature": {
+      "description": "Output randomness for all agents; lower values are deterministic, higher\nvalues are creative (0.0–2.0).",
+      "anyOf": [
+        {
+          "$ref": "#/$defs/double"
+        },
+        {
+          "type": "null"
+        }
+      ]
+    },
+    "tool_supported": {
+      "description": "Whether tool use is supported in the current environment; when false,\nall tool calls are disabled.",
+      "type": "boolean",
+      "default": false
+    },
+    "tool_timeout_secs": {
+      "description": "Maximum time in seconds a single tool call may run before being\ncancelled.",
+      "type": "integer",
+      "format": "uint64",
+      "default": 0,
+      "minimum": 0
+    },
+    "top_k": {
+      "description": "Top-k vocabulary cutoff for all agents; restricts sampling to the k\nhighest-probability tokens (1–1000).",
+      "type": [
+        "integer",
+        "null"
+      ],
+      "format": "uint32",
+      "minimum": 0
+    },
+    "top_p": {
+      "description": "Nucleus sampling threshold for all agents; limits token selection to the\ntop cumulative probability mass (0.0–1.0).",
+      "anyOf": [
+        {
+          "$ref": "#/$defs/double"
+        },
+        {
+          "type": "null"
+        }
+      ]
+    },
+    "updates": {
+      "description": "Configuration for automatic Forge updates.",
+      "anyOf": [
+        {
+          "$ref": "#/$defs/Update"
+        },
+        {
+          "type": "null"
+        }
+      ]
+    },
+    "use_forge_committer": {
+      "description": "Whether `forge commit` should override `GIT_COMMITTER_NAME` and\n`GIT_COMMITTER_EMAIL` with the Forge identity. Defaults to `true` via\nthe embedded `.forge.toml` defaults.",
+      "type": "boolean",
+      "default": false
+    },
+    "use_text_patch_fallback": {
+      "description": "Switches patch replacement fallback from the legacy fuzzy-search range\nlookup to the newer text-patch gRPC API.\nDefaults to `false` so patching continues to use the legacy fallback\nbehavior unless explicitly enabled in `forge.toml`.",
+      "type": "boolean",
+      "default": false
+    },
+    "verify_todos": {
+      "description": "Enables the pending todos hook that checks for incomplete todo items\nwhen a task ends and reminds the LLM about them.",
+      "type": "boolean",
+      "default": false
+    }
+  },
+  "$defs": {
+    "AutoDumpFormat": {
+      "description": "The output format used when auto-dumping a conversation on task completion.",
+      "oneOf": [
+        {
+          "description": "Dump as a JSON file",
+          "type": "string",
+          "const": "json"
+        },
+        {
+          "description": "Dump as an HTML file",
+          "type": "string",
+          "const": "html"
+        }
+      ]
+    },
+    "Compact": {
+      "description": "Configuration for automatic context compaction for all agents",
+      "type": "object",
+      "properties": {
+        "eviction_window": {
+          "description": "Maximum percentage of the context that can be summarized during\ncompaction. Valid values are between 0.0 and 1.0, where 0.0 means no\ncompaction and 1.0 allows summarizing all messages. Works alongside\nretention_window - the more conservative limit (fewer messages to\ncompact) takes precedence.",
+          "$ref": "#/$defs/double",
+          "default": 0.0
+        },
+        "max_tokens": {
+          "description": "Maximum number of tokens to keep after compaction",
+          "type": [
+            "integer",
+            "null"
+          ],
+          "format": "uint",
+          "minimum": 0
+        },
+        "message_threshold": {
+          "description": "Maximum number of messages before triggering compaction",
+          "type": [
+            "integer",
+            "null"
+          ],
+          "format": "uint",
+          "minimum": 0
+        },
+        "model": {
+          "description": "Model ID to use for compaction, useful when compacting with a\ncheaper/faster model. If not specified, the root level model will be\nused.",
+          "type": [
+            "string",
+            "null"
+          ]
+        },
+        "on_turn_end": {
+          "description": "Whether to trigger compaction when the last message is from a user",
+          "type": [
+            "boolean",
+            "null"
+          ]
+        },
+        "retention_window": {
+          "description": "Number of most recent messages to preserve during compaction.\nThese messages won't be considered for summarization. Works alongside\neviction_window - the more conservative limit (fewer messages to\ncompact) takes precedence.",
+          "type": "integer",
+          "format": "uint",
+          "default": 0,
+          "minimum": 0
+        },
+        "token_threshold": {
+          "description": "Maximum number of tokens before triggering compaction. This acts as an\nabsolute cap and is combined with\n`token_threshold_percentage` by taking the lower value.",
+          "type": [
+            "integer",
+            "null"
+          ],
+          "format": "uint",
+          "minimum": 0
+        },
+        "token_threshold_percentage": {
+          "description": "Maximum percentage of the model context window used to derive the token\nthreshold before triggering compaction. This is combined with\n`token_threshold` by taking the lower value.",
+          "anyOf": [
+            {
+              "$ref": "#/$defs/double"
+            },
+            {
+              "type": "null"
+            }
+          ]
+        },
+        "turn_threshold": {
+          "description": "Maximum number of conversation turns before triggering compaction",
+          "type": [
+            "integer",
+            "null"
+          ],
+          "format": "uint",
+          "minimum": 0
+        }
+      }
+    },
+    "Effort": {
+      "description": "Effort level for model reasoning.",
+      "oneOf": [
+        {
+          "description": "No reasoning; skips the thinking step entirely.",
+          "type": "string",
+          "const": "none"
+        },
+        {
+          "description": "Minimal reasoning; fastest and cheapest.",
+          "type": "string",
+          "const": "minimal"
+        },
+        {
+          "description": "Low reasoning effort.",
+          "type": "string",
+          "const": "low"
+        },
+        {
+          "description": "Medium reasoning effort; the default for most providers.",
+          "type": "string",
+          "const": "medium"
+        },
+        {
+          "description": "High reasoning effort.",
+          "type": "string",
+          "const": "high"
+        },
+        {
+          "description": "Extra-high reasoning effort (OpenAI / OpenRouter).",
+          "type": "string",
+          "const": "xhigh"
+        },
+        {
+          "description": "Maximum reasoning effort; only available on select Anthropic models.",
+          "type": "string",
+          "const": "max"
+        }
+      ]
+    },
+    "HttpConfig": {
+      "description": "HTTP client configuration.",
+      "type": "object",
+      "properties": {
+        "accept_invalid_certs": {
+          "description": "Accept invalid certificates",
+          "type": "boolean"
+        },
+        "adaptive_window": {
+          "description": "Adaptive window sizing for improved flow control",
+          "type": "boolean"
+        },
+        "connect_timeout_secs": {
+          "type": "integer",
+          "format": "uint64",
+          "minimum": 0
+        },
+        "hickory": {
+          "type": "boolean"
+        },
+        "keep_alive_interval_secs": {
+          "description": "Keep-alive interval in seconds",
+          "type": [
+            "integer",
+            "null"
+          ],
+          "format": "uint64",
+          "minimum": 0
+        },
+        "keep_alive_timeout_secs": {
+          "description": "Keep-alive timeout in seconds",
+          "type": "integer",
+          "format": "uint64",
+          "minimum": 0
+        },
+        "keep_alive_while_idle": {
+          "description": "Keep-alive while connection is idle",
+          "type": "boolean"
+        },
+        "max_redirects": {
+          "type": "integer",
+          "format": "uint",
+          "minimum": 0
+        },
+        "max_tls_version": {
+          "description": "Maximum TLS protocol version to use",
+          "anyOf": [
+            {
+              "$ref": "#/$defs/TlsVersion"
+            },
+            {
+              "type": "null"
+            }
+          ]
+        },
+        "min_tls_version": {
+          "description": "Minimum TLS protocol version to use",
+          "anyOf": [
+            {
+              "$ref": "#/$defs/TlsVersion"
+            },
+            {
+              "type": "null"
+            }
+          ]
+        },
+        "pool_idle_timeout_secs": {
+          "type": "integer",
+          "format": "uint64",
+          "minimum": 0
+        },
+        "pool_max_idle_per_host": {
+          "type": "integer",
+          "format": "uint",
+          "minimum": 0
+        },
+        "read_timeout_secs": {
+          "type": "integer",
+          "format": "uint64",
+          "minimum": 0
+        },
+        "root_cert_paths": {
+          "description": "Paths to root certificate files",
+          "type": [
+            "array",
+            "null"
+          ],
+          "items": {
+            "type": "string"
+          }
+        },
+        "tls_backend": {
+          "$ref": "#/$defs/TlsBackend"
+        }
+      },
+      "required": [
+        "connect_timeout_secs",
+        "read_timeout_secs",
+        "pool_idle_timeout_secs",
+        "pool_max_idle_per_host",
+        "max_redirects",
+        "hickory",
+        "tls_backend",
+        "adaptive_window",
+        "keep_alive_timeout_secs",
+        "keep_alive_while_idle",
+        "accept_invalid_certs"
+      ]
+    },
+    "InputModality": {
+      "description": "Represents input modalities that a model can accept",
+      "oneOf": [
+        {
+          "description": "Text input (all models support this)",
+          "type": "string",
+          "const": "text"
+        },
+        {
+          "description": "Image input (vision-capable models)",
+          "type": "string",
+          "const": "image"
+        }
+      ]
+    },
+    "Model": {
+      "type": "object",
+      "properties": {
+        "context_length": {
+          "type": [
+            "integer",
+            "null"
+          ],
+          "format": "uint64",
+          "minimum": 0
+        },
+        "description": {
+          "type": [
+            "string",
+            "null"
+          ]
+        },
+        "id": {
+          "type": "string"
+        },
+        "input_modalities": {
+          "description": "Input modalities supported by the model (defaults to text-only)",
+          "type": "array",
+          "default": [
+            "text"
+          ],
+          "items": {
+            "$ref": "#/$defs/InputModality"
+          }
+        },
+        "name": {
+          "type": [
+            "string",
+            "null"
+          ]
+        },
+        "supports_parallel_tool_calls": {
+          "description": "Whether the model supports parallel tool calls",
+          "type": [
+            "boolean",
+            "null"
+          ]
+        },
+        "supports_reasoning": {
+          "description": "Whether the model supports reasoning",
+          "type": [
+            "boolean",
+            "null"
+          ]
+        },
+        "tools_supported": {
+          "type": [
+            "boolean",
+            "null"
+          ]
+        }
+      },
+      "required": [
+        "id"
+      ]
+    },
+    "ModelConfig": {
+      "description": "Pairs a provider and model together for a specific operation.",
+      "type": "object",
+      "properties": {
+        "model_id": {
+          "description": "The model to use for this operation.",
+          "type": "string"
+        },
+        "provider_id": {
+          "description": "The provider to use for this operation.",
+          "type": "string"
+        }
+      },
+      "required": [
+        "provider_id",
+        "model_id"
+      ]
+    },
+    "ModelListConfig": {
+      "description": "Source of models for a provider: either a URL to fetch them from or a\nstatic list defined inline.",
+      "anyOf": [
+        {
+          "description": "URL template used to fetch the model list dynamically.",
+          "type": "string"
+        },
+        {
+          "description": "A static list of models defined directly in the configuration.",
+          "type": "array",
+          "items": {
+            "$ref": "#/$defs/Model"
+          }
+        }
+      ]
+    },
+    "ProviderAuthMethod": {
+      "description": "Authentication method supported by a provider.\n\nOnly the simple (non-OAuth) methods are available here; providers that\nrequire OAuth device or authorization-code flows must be configured via the\nfile-based `provider.json` override instead.",
+      "type": "string",
+      "enum": [
+        "api_key",
+        "google_adc"
+      ]
+    },
+    "ProviderEntry": {
+      "description": "A single provider entry defined inline in `forge.toml`.\n\nInline providers are merged with the built-in provider list; entries with\nthe same `id` override the corresponding built-in entry field-by-field,\nwhile entries with a new `id` are appended to the list.",
+      "type": "object",
+      "properties": {
+        "api_key_var": {
+          "description": "Environment variable holding the API key for this provider.",
+          "type": [
+            "string",
+            "null"
+          ]
+        },
+        "auth_methods": {
+          "description": "Authentication methods supported by this provider; defaults to\n`[\"api_key\"]` when omitted.",
+          "type": "array",
+          "items": {
+            "$ref": "#/$defs/ProviderAuthMethod"
+          }
+        },
+        "custom_headers": {
+          "description": "Additional HTTP headers sent with every request to this provider.",
+          "type": [
+            "object",
+            "null"
+          ],
+          "additionalProperties": {
+            "type": "string"
+          }
+        },
+        "id": {
+          "description": "Unique provider identifier used in model paths (e.g. `\"my_provider\"`).",
+          "type": "string"
+        },
+        "models": {
+          "description": "Model source: either a URL template for dynamic discovery or a static\nlist of models defined inline.",
+          "anyOf": [
+            {
+              "$ref": "#/$defs/ModelListConfig"
+            },
+            {
+              "type": "null"
+            }
+          ]
+        },
+        "provider_type": {
+          "description": "Provider category; defaults to `llm` when omitted.",
+          "anyOf": [
+            {
+              "$ref": "#/$defs/ProviderTypeEntry"
+            },
+            {
+              "type": "null"
+            }
+          ]
+        },
+        "response_type": {
+          "description": "Wire protocol used by this provider.",
+          "anyOf": [
+            {
+              "$ref": "#/$defs/ProviderResponseType"
+            },
+            {
+              "type": "null"
+            }
+          ]
+        },
+        "url": {
+          "description": "URL template for chat completions; may contain `{{VAR}}` placeholders\nthat are substituted from the credential's url params.",
+          "type": "string"
+        },
+        "url_param_vars": {
+          "description": "Environment variables whose values are substituted into `{{VAR}}`\nplaceholders in the `url` and `models` templates.",
+          "type": "array",
+          "items": {
+            "$ref": "#/$defs/ProviderUrlParam"
+          }
+        }
+      },
+      "required": [
+        "id",
+        "url"
+      ]
+    },
+    "ProviderResponseType": {
+      "description": "Wire protocol a provider uses for chat completions.",
+      "type": "string",
+      "enum": [
+        "OpenAI",
+        "OpenAIResponses",
+        "Anthropic",
+        "Bedrock",
+        "Google",
+        "OpenCode"
+      ]
+    },
+    "ProviderTypeEntry": {
+      "description": "Category of a provider.",
+      "oneOf": [
+        {
+          "description": "LLM provider for chat completions.",
+          "type": "string",
+          "const": "llm"
+        },
+        {
+          "description": "Context engine provider for code indexing and search.",
+          "type": "string",
+          "const": "context_engine"
+        }
+      ]
+    },
+    "ProviderUrlParam": {
+      "description": "A URL parameter variable for a provider, used to substitute template\nvariables in URL strings.",
+      "type": "object",
+      "properties": {
+        "name": {
+          "description": "The environment variable name used as the template variable key.",
+          "type": "string"
+        },
+        "optional": {
+          "description": "Whether this parameter is optional. When `true`, the parameter may be\nleft blank without causing an error.",
+          "type": "boolean"
+        },
+        "options": {
+          "description": "Optional preset values for this parameter shown as suggestions in the\nUI.",
+          "type": "array",
+          "items": {
+            "type": "string"
+          }
+        }
+      },
+      "required": [
+        "name"
+      ]
+    },
+    "ReasoningConfig": {
+      "description": "Controls the reasoning behaviour of a model, including effort level, token\nbudget, and visibility of the thinking process.",
+      "type": "object",
+      "properties": {
+        "effort": {
+          "description": "Controls the effort level of the model's reasoning.\nSupported by openrouter and forge provider.",
+          "anyOf": [
+            {
+              "$ref": "#/$defs/Effort"
+            },
+            {
+              "type": "null"
+            }
+          ]
+        },
+        "enabled": {
+          "description": "Enables reasoning at the \"medium\" effort level with no exclusions.\nSupported by openrouter, anthropic, and forge provider.",
+          "type": [
+            "boolean",
+            "null"
+          ]
+        },
+        "exclude": {
+          "description": "When true, the model thinks deeply but the reasoning is hidden from the\ncaller. Supported by openrouter and forge provider.",
+          "type": [
+            "boolean",
+            "null"
+          ]
+        },
+        "max_tokens": {
+          "description": "Controls how many tokens the model can spend thinking.\nShould be greater than 1024 but less than the overall max_tokens.\nSupported by openrouter, anthropic, and forge provider.",
+          "type": [
+            "integer",
+            "null"
+          ],
+          "format": "uint",
+          "minimum": 0
+        }
+      }
+    },
+    "RetryConfig": {
+      "description": "Configuration for retry mechanism.",
+      "type": "object",
+      "properties": {
+        "backoff_factor": {
+          "description": "Backoff multiplication factor for each retry attempt",
+          "type": "integer",
+          "format": "uint64",
+          "minimum": 0
+        },
+        "initial_backoff_ms": {
+          "description": "Initial backoff delay in milliseconds for retry operations",
+          "type": "integer",
+          "format": "uint64",
+          "minimum": 0
+        },
+        "max_attempts": {
+          "description": "Maximum number of retry attempts",
+          "type": "integer",
+          "format": "uint",
+          "minimum": 0
+        },
+        "max_delay_secs": {
+          "description": "Maximum delay between retries in seconds",
+          "type": [
+            "integer",
+            "null"
+          ],
+          "format": "uint64",
+          "minimum": 0
+        },
+        "min_delay_ms": {
+          "description": "Minimum delay in milliseconds between retry attempts",
+          "type": "integer",
+          "format": "uint64",
+          "minimum": 0
+        },
+        "status_codes": {
+          "description": "HTTP status codes that should trigger retries",
+          "type": "array",
+          "items": {
+            "type": "integer",
+            "format": "uint16",
+            "maximum": 65535,
+            "minimum": 0
+          }
+        },
+        "suppress_errors": {
+          "description": "Whether to suppress retry error logging and events",
+          "type": "boolean"
+        }
+      },
+      "required": [
+        "initial_backoff_ms",
+        "min_delay_ms",
+        "backoff_factor",
+        "max_attempts",
+        "status_codes",
+        "suppress_errors"
+      ]
+    },
+    "TlsBackend": {
+      "description": "TLS backend option.",
+      "type": "string",
+      "enum": [
+        "default",
+        "rustls"
+      ]
+    },
+    "TlsVersion": {
+      "description": "TLS version enum for configuring TLS protocol versions.",
+      "type": "string",
+      "enum": [
+        "1.0",
+        "1.1",
+        "1.2",
+        "1.3"
+      ]
+    },
+    "Update": {
+      "description": "Configuration for automatic forge updates",
+      "type": "object",
+      "properties": {
+        "auto_update": {
+          "description": "Whether to automatically install updates without prompting",
+          "type": [
+            "boolean",
+            "null"
+          ]
+        },
+        "frequency": {
+          "description": "How frequently forge checks for updates: daily, weekly, always, or never",
+          "anyOf": [
+            {
+              "$ref": "#/$defs/UpdateFrequency"
+            },
+            {
+              "type": "null"
+            }
+          ]
+        }
+      }
+    },
+    "UpdateFrequency": {
+      "description": "Frequency at which forge checks for updates",
+      "type": "string",
+      "enum": [
+        "daily",
+        "weekly",
+        "never",
+        "always"
+      ]
+    },
+    "double": {
+      "type": "number",
+      "format": "double"
+    }
+  }
+}

insta.yaml

@@ -0,0 +1,4 @@
+test:
+  auto_accept: true
+  auto_accept_unseen: true
+  runner: nextest

package-lock.json

@@ -0,0 +1,1966 @@
+{
+  "name": "forge-code-evals",
+  "version": "1.0.0",
+  "lockfileVersion": 3,
+  "requires": true,
+  "packages": {
+    "": {
+      "name": "forge-code-evals",
+      "version": "1.0.0",
+      "license": "ISC",
+      "dependencies": {
+        "@ai-sdk/google-vertex": "^5.0.0",
+        "@types/handlebars": "^4.0.40",
+        "@types/node": "^24.10.1",
+        "@types/tmp": "^0.2.6",
+        "@types/yargs": "^17.0.35",
+        "ai": "^7.0.0",
+        "chalk": "^6.0.0",
+        "csv-parse": "^7.0.0",
+        "handlebars": "^4.7.9",
+        "p-limit": "^7.2.0",
+        "pino": "^10.1.0",
+        "pino-pretty": "^13.1.2",
+        "strip-ansi": "^7.1.2",
+        "tmp": "^0.2.5",
+        "tsx": "^4.20.6",
+        "typescript": "^7.0.0",
+        "yaml": "^2.8.3",
+        "yargs": "^18.0.0",
+        "zod": "^4.0.0"
+      }
+    },
+    "node_modules/@ai-sdk/anthropic": {
+      "version": "4.0.35",
+      "resolved": "https://registry.npmjs.org/@ai-sdk/anthropic/-/anthropic-4.0.35.tgz",
+      "integrity": "sha512-3GcRyB6FPxYVH0wxBfPm7RciaMcU1qVDrx6Kp+rONeEqS7aZA1yq3gS1wUfsH8Wp4XZ1GjYh0rYyhBM0hnv59w==",
+      "license": "Apache-2.0",
+      "dependencies": {
+        "@ai-sdk/provider": "4.0.6",
+        "@ai-sdk/provider-utils": "5.0.24"
+      },
+      "engines": {
+        "node": ">=22"
+      },
+      "peerDependencies": {
+        "zod": "^3.25.76 || ^4.1.8"
+      }
+    },
+    "node_modules/@ai-sdk/gateway": {
+      "version": "4.0.45",
+      "resolved": "https://registry.npmjs.org/@ai-sdk/gateway/-/gateway-4.0.45.tgz",
+      "integrity": "sha512-8W4MYRS7FKkxtaagOC9FrIMfC8HUr1T5/AXjSj/3t5ADdMbTE0R10ZcK6VaE/LqM5qV9eWtvrkW2ZZKMpvrKnw==",
+      "license": "Apache-2.0",
+      "dependencies": {
+        "@ai-sdk/provider": "4.0.6",
+        "@ai-sdk/provider-utils": "5.0.24",
+        "@vercel/oidc": "3.2.0"
+      },
+      "engines": {
+        "node": ">=22"
+      },
+      "peerDependencies": {
+        "zod": "^3.25.76 || ^4.1.8"
+      }
+    },
+    "node_modules/@ai-sdk/google": {
+      "version": "4.0.38",
+      "resolved": "https://registry.npmjs.org/@ai-sdk/google/-/google-4.0.38.tgz",
+      "integrity": "sha512-tPAuSgvfhEb1kVOnRg2ARxS5nTtcJFK/MFcuMIkopIR8ju1lo9QtFbpLsOn8oRmBRFQNe9z9TuBf73QdI/zrFg==",
+      "license": "Apache-2.0",
+      "dependencies": {
+        "@ai-sdk/provider": "4.0.6",
+        "@ai-sdk/provider-utils": "5.0.24"
+      },
+      "engines": {
+        "node": ">=22"
+      },
+      "peerDependencies": {
+        "zod": "^3.25.76 || ^4.1.8"
+      }
+    },
+    "node_modules/@ai-sdk/google-vertex": {
+      "version": "5.0.46",
+      "resolved": "https://registry.npmjs.org/@ai-sdk/google-vertex/-/google-vertex-5.0.46.tgz",
+      "integrity": "sha512-sDVnBVeECEzwDLX7mNq89yoEDxut4PqCx0ymjftCK5RTkELXZauIeLiFWCrcp/WLZ51cyJ44I32Tw+G04m0GNg==",
+      "license": "Apache-2.0",
+      "dependencies": {
+        "@ai-sdk/anthropic": "4.0.35",
+        "@ai-sdk/google": "4.0.38",
+        "@ai-sdk/openai-compatible": "3.0.26",
+        "@ai-sdk/provider": "4.0.6",
+        "@ai-sdk/provider-utils": "5.0.24",
+        "google-auth-library": "^10.6.2"
+      },
+      "engines": {
+        "node": ">=22"
+      },
+      "peerDependencies": {
+        "zod": "^3.25.76 || ^4.1.8"
+      }
+    },
+    "node_modules/@ai-sdk/openai-compatible": {
+      "version": "3.0.26",
+      "resolved": "https://registry.npmjs.org/@ai-sdk/openai-compatible/-/openai-compatible-3.0.26.tgz",
+      "integrity": "sha512-PQYWPJF6MQRurwVH9h5MlZXqfFufC1bsGgVQmEy174jF5MFDyPD3rnFeOXSZAYR3YOj81nuaBqjII239IEWpgw==",
+      "license": "Apache-2.0",
+      "dependencies": {
+        "@ai-sdk/provider": "4.0.6",
+        "@ai-sdk/provider-utils": "5.0.24"
+      },
+      "engines": {
+        "node": ">=22"
+      },
+      "peerDependencies": {
+        "zod": "^3.25.76 || ^4.1.8"
+      }
+    },
+    "node_modules/@ai-sdk/provider": {
+      "version": "4.0.6",
+      "resolved": "https://registry.npmjs.org/@ai-sdk/provider/-/provider-4.0.6.tgz",
+      "integrity": "sha512-YYXjvs8F3q/BdEn9tBDoDuQACotfR7c5foGw/ADsM6iAVC1JabqEjQSkwHv/Kg2vNIr1c2AVHcQb+JYsYk76Qw==",
+      "license": "Apache-2.0",
+      "dependencies": {
+        "json-schema": "^0.4.0"
+      },
+      "engines": {
+        "node": ">=22"
+      }
+    },
+    "node_modules/@ai-sdk/provider-utils": {
+      "version": "5.0.24",
+      "resolved": "https://registry.npmjs.org/@ai-sdk/provider-utils/-/provider-utils-5.0.24.tgz",
+      "integrity": "sha512-jiQzdyr4y25kKYEJcV0Re/UH0Oy0FMB60LNW3eo01hEHSkmo+NYDIhuY0y/BMdWdPD659du0/VmAbOxiXoLLUw==",
+      "license": "Apache-2.0",
+      "dependencies": {
+        "@ai-sdk/provider": "4.0.6",
+        "@standard-schema/spec": "^1.1.0",
+        "@workflow/serde": "4.1.0",
+        "eventsource-parser": "^3.0.8",
+        "undici": "^7.28.0"
+      },
+      "engines": {
+        "node": ">=22"
+      },
+      "peerDependencies": {
+        "zod": "^3.25.76 || ^4.1.8"
+      }
+    },
+    "node_modules/@esbuild/aix-ppc64": {
+      "version": "0.28.1",
+      "resolved": "https://registry.npmjs.org/@esbuild/aix-ppc64/-/aix-ppc64-0.28.1.tgz",
+      "integrity": "sha512-Svl7tq8k/08+p6CXPpRjQ1fKX+1odH/BQbb48fV6fj3CWHhsoIOoY87w1oHXm0qEpkIK3ZfVgp0hed3XBXzXMQ==",
+      "cpu": [
+        "ppc64"
+      ],
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "aix"
+      ],
+      "engines": {
+        "node": ">=18"
+      }
+    },
+    "node_modules/@esbuild/android-arm": {
+      "version": "0.28.1",
+      "resolved": "https://registry.npmjs.org/@esbuild/android-arm/-/android-arm-0.28.1.tgz",
+      "integrity": "sha512-0k2F129Xdio1TdJfzJ8sy1Q47vUD2NnwdhiAf7drUN1EBTfPf4hsFCtmMgu/6m8JSzsBrlmVjudMBQqOfG8usQ==",
+      "cpu": [
+        "arm"
+      ],
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "android"
+      ],
+      "engines": {
+        "node": ">=18"
+      }
+    },
+    "node_modules/@esbuild/android-arm64": {
+      "version": "0.28.1",
+      "resolved": "https://registry.npmjs.org/@esbuild/android-arm64/-/android-arm64-0.28.1.tgz",
+      "integrity": "sha512-34EGEbCIAgosYz6goLcopX6Mo7NyGv9tfwEM2/7Ce2VcVRk568iSvniGWcUXIy7wEDR1wzolcxcriFVrWYcwBg==",
+      "cpu": [
+        "arm64"
+      ],
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "android"
+      ],
+      "engines": {
+        "node": ">=18"
+      }
+    },
+    "node_modules/@esbuild/android-x64": {
+      "version": "0.28.1",
+      "resolved": "https://registry.npmjs.org/@esbuild/android-x64/-/android-x64-0.28.1.tgz",
+      "integrity": "sha512-dbwY7ltSMDWsRatcRpCnES4F+im88OCUgGZjy52shC7GqHRE/cYlxNbB4Z4UpJswpcc4Qxd2oE/ufM0p61IKng==",
+      "cpu": [
+        "x64"
+      ],
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "android"
+      ],
+      "engines": {
+        "node": ">=18"
+      }
+    },
+    "node_modules/@esbuild/darwin-arm64": {
+      "version": "0.28.1",
+      "resolved": "https://registry.npmjs.org/@esbuild/darwin-arm64/-/darwin-arm64-0.28.1.tgz",
+      "integrity": "sha512-TZbWkQY7kvTAXbXUT7uVACR5cMHsDiSz9z7ZKAX/RTq/WJEk3QyRr0wZpNhBDX+/0CtdqUIJlOiodQcta6tY3Q==",
+      "cpu": [
+        "arm64"
+      ],
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "darwin"
+      ],
+      "engines": {
+        "node": ">=18"
+      }
+    },
+    "node_modules/@esbuild/darwin-x64": {
+      "version": "0.28.1",
+      "resolved": "https://registry.npmjs.org/@esbuild/darwin-x64/-/darwin-x64-0.28.1.tgz",
+      "integrity": "sha512-zfdzgK9ACBNZLI/CyHTOx81SyNbM6YXn7rxSgX97VjyiPl9W1i4Ka4fgKECEoFCKGpvBj5qArWIGgQjOwkgskQ==",
+      "cpu": [
+        "x64"
+      ],
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "darwin"
+      ],
+      "engines": {
+        "node": ">=18"
+      }
+    },
+    "node_modules/@esbuild/freebsd-arm64": {
+      "version": "0.28.1",
+      "resolved": "https://registry.npmjs.org/@esbuild/freebsd-arm64/-/freebsd-arm64-0.28.1.tgz",
+      "integrity": "sha512-wG2EA8ENdEI0qhkSZMjfqrdY+ziCYCPMmtZjjIwOmXFjmyzEHn+UUxk5of+SYsjtfs3VpnlC7QLzSI5hY/rOAw==",
+      "cpu": [
+        "arm64"
+      ],
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "freebsd"
+      ],
+      "engines": {
+        "node": ">=18"
+      }
+    },
+    "node_modules/@esbuild/freebsd-x64": {
+      "version": "0.28.1",
+      "resolved": "https://registry.npmjs.org/@esbuild/freebsd-x64/-/freebsd-x64-0.28.1.tgz",
+      "integrity": "sha512-i7dZ9vQgnvSCzi/rYCXNgtF/U+eKZNJBzu3eTQbRgHnM7tNSizLOkRFAl3qzVc/Op/u5YkHHa4pf/3DOYHthLQ==",
+      "cpu": [
+        "x64"
+      ],
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "freebsd"
+      ],
+      "engines": {
+        "node": ">=18"
+      }
+    },
+    "node_modules/@esbuild/linux-arm": {
+      "version": "0.28.1",
+      "resolved": "https://registry.npmjs.org/@esbuild/linux-arm/-/linux-arm-0.28.1.tgz",
+      "integrity": "sha512-qVXBOHQS+d5Y722GwJzJUtOLlX7km3CraOaGormF1pDtPd2C/l1SHRPgjLunLGe51Sh5YYWKMFDyV4SxgMQYTQ==",
+      "cpu": [
+        "arm"
+      ],
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "linux"
+      ],
+      "engines": {
+        "node": ">=18"
+      }
+    },
+    "node_modules/@esbuild/linux-arm64": {
+      "version": "0.28.1",
+      "resolved": "https://registry.npmjs.org/@esbuild/linux-arm64/-/linux-arm64-0.28.1.tgz",
+      "integrity": "sha512-yHs+0uc8+nvEAfAfxrWQKK5peSNzBc4PegcMO0EJ2hT71uA7vB8Ihg2e77R2P7SG5uYjPbHlLLmve4LLLRCf0g==",
+      "cpu": [
+        "arm64"
+      ],
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "linux"
+      ],
+      "engines": {
+        "node": ">=18"
+      }
+    },
+    "node_modules/@esbuild/linux-ia32": {
+      "version": "0.28.1",
+      "resolved": "https://registry.npmjs.org/@esbuild/linux-ia32/-/linux-ia32-0.28.1.tgz",
+      "integrity": "sha512-d1z4ZuP0ajrfz/FhGT4vv278rX8KnPPJx8i5+AtK7TYbx9Le9F1hyzurZpkEyjkGa9dUGhQow4C1NmeGvqxN2w==",
+      "cpu": [
+        "ia32"
+      ],
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "linux"
+      ],
+      "engines": {
+        "node": ">=18"
+      }
+    },
+    "node_modules/@esbuild/linux-loong64": {
+      "version": "0.28.1",
+      "resolved": "https://registry.npmjs.org/@esbuild/linux-loong64/-/linux-loong64-0.28.1.tgz",
+      "integrity": "sha512-M5sRjUVZrkm1OAPR3dlOYzNmN+loZKGVi1VUQGrwuqLcbR6qeAz+famMhjASeH3YVKvZz+zT1jlh/keC3Rj/lg==",
+      "cpu": [
+        "loong64"
+      ],
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "linux"
+      ],
+      "engines": {
+        "node": ">=18"
+      }
+    },
+    "node_modules/@esbuild/linux-mips64el": {
+      "version": "0.28.1",
+      "resolved": "https://registry.npmjs.org/@esbuild/linux-mips64el/-/linux-mips64el-0.28.1.tgz",
+      "integrity": "sha512-mRObBZeHh2OxcBFPWE/FjylkRgZdYuiTR3vaTozquCGOH14iP9oN4x4Ge81CoIDYQrXmIxpFumJBu5MtZpnQJQ==",
+      "cpu": [
+        "mips64el"
+      ],
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "linux"
+      ],
+      "engines": {
+        "node": ">=18"
+      }
+    },
+    "node_modules/@esbuild/linux-ppc64": {
+      "version": "0.28.1",
+      "resolved": "https://registry.npmjs.org/@esbuild/linux-ppc64/-/linux-ppc64-0.28.1.tgz",
+      "integrity": "sha512-slScBsMAb3GFDcdrCgLwZtPYRoH2H/youv10QiZyRjmsP48fznoveWytSgCI/R0ZcUgpc0ZhIUEx6LHts8yrfQ==",
+      "cpu": [
+        "ppc64"
+      ],
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "linux"
+      ],
+      "engines": {
+        "node": ">=18"
+      }
+    },
+    "node_modules/@esbuild/linux-riscv64": {
+      "version": "0.28.1",
+      "resolved": "https://registry.npmjs.org/@esbuild/linux-riscv64/-/linux-riscv64-0.28.1.tgz",
+      "integrity": "sha512-kw0owk1o0GFETUJyW0jc0G4Yzs0BHZn0JDZ8JRT088vjJYX777BAs1fDGxAC+q831qOs2DTC96mNsG2opdfyyQ==",
+      "cpu": [
+        "riscv64"
+      ],
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "linux"
+      ],
+      "engines": {
+        "node": ">=18"
+      }
+    },
+    "node_modules/@esbuild/linux-s390x": {
+      "version": "0.28.1",
+      "resolved": "https://registry.npmjs.org/@esbuild/linux-s390x/-/linux-s390x-0.28.1.tgz",
+      "integrity": "sha512-/lAIjX8aYFRByhh6L5rYtPEDRqa9de/4V/juOXcta5frjvzXO4/sqEtyytse0g3zZFuWu5cDN0MkLz2qRDD2Ag==",
+      "cpu": [
+        "s390x"
+      ],
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "linux"
+      ],
+      "engines": {
+        "node": ">=18"
+      }
+    },
+    "node_modules/@esbuild/linux-x64": {
+      "version": "0.28.1",
+      "resolved": "https://registry.npmjs.org/@esbuild/linux-x64/-/linux-x64-0.28.1.tgz",
+      "integrity": "sha512-u/anNYF2mmVOEDwLtnQ1wOr3EZ9sTNGLWrsYGYwHWzGA3Si84IOkHXlbWTD1NB+9/1lcnweYKO54uhxZydNzfA==",
+      "cpu": [
+        "x64"
+      ],
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "linux"
+      ],
+      "engines": {
+        "node": ">=18"
+      }
+    },
+    "node_modules/@esbuild/netbsd-arm64": {
+      "version": "0.28.1",
+      "resolved": "https://registry.npmjs.org/@esbuild/netbsd-arm64/-/netbsd-arm64-0.28.1.tgz",
+      "integrity": "sha512-oks0DYbLwWMmaakTsCb+zL4E+aHRVLom9IJZOAthMQEPiQmydXHkziYEsGYRx0uNV/IjEKGAV941JzH02pflqw==",
+      "cpu": [
+        "arm64"
+      ],
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "netbsd"
+      ],
+      "engines": {
+        "node": ">=18"
+      }
+    },
+    "node_modules/@esbuild/netbsd-x64": {
+      "version": "0.28.1",
+      "resolved": "https://registry.npmjs.org/@esbuild/netbsd-x64/-/netbsd-x64-0.28.1.tgz",
+      "integrity": "sha512-aeL6lAnN89Hz43Mlh1G8ARasbuoYvSITDEx0tHh5b7jJnHcssqgjy9Yx430GDpmCa6OyrKoS0aNRjKundRizGg==",
+      "cpu": [
+        "x64"
+      ],
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "netbsd"
+      ],
+      "engines": {
+        "node": ">=18"
+      }
+    },
+    "node_modules/@esbuild/openbsd-arm64": {
+      "version": "0.28.1",
+      "resolved": "https://registry.npmjs.org/@esbuild/openbsd-arm64/-/openbsd-arm64-0.28.1.tgz",
+      "integrity": "sha512-MEFJe5C3R8pwXdZ5Y21oo6m7ePiS0d9pWucn99O/wvyJZChoIQKrQDxKrGeW8F5+T0okTHesAmDeiHDTIq0V/Q==",
+      "cpu": [
+        "arm64"
+      ],
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "openbsd"
+      ],
+      "engines": {
+        "node": ">=18"
+      }
+    },
+    "node_modules/@esbuild/openbsd-x64": {
+      "version": "0.28.1",
+      "resolved": "https://registry.npmjs.org/@esbuild/openbsd-x64/-/openbsd-x64-0.28.1.tgz",
+      "integrity": "sha512-i/ZLIOafE0Z8cI/XANJAixoJL/uRAoS2xOA3rb0xN+KK0K177cMAsQYkzHtBrtMXAKuAc7HGgcWiZ/sRC1Nxgw==",
+      "cpu": [
+        "x64"
+      ],
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "openbsd"
+      ],
+      "engines": {
+        "node": ">=18"
+      }
+    },
+    "node_modules/@esbuild/openharmony-arm64": {
+      "version": "0.28.1",
+      "resolved": "https://registry.npmjs.org/@esbuild/openharmony-arm64/-/openharmony-arm64-0.28.1.tgz",
+      "integrity": "sha512-ge+Z7EXFNt2BO1oAMsVpiQ8EwndV9i1xXerAeTIK7AtPs3bKFXQM7nlRxDSIUIMeueR1CNXxqztLzdNeReKBJg==",
+      "cpu": [
+        "arm64"
+      ],
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "openharmony"
+      ],
+      "engines": {
+        "node": ">=18"
+      }
+    },
+    "node_modules/@esbuild/sunos-x64": {
+      "version": "0.28.1",
+      "resolved": "https://registry.npmjs.org/@esbuild/sunos-x64/-/sunos-x64-0.28.1.tgz",
+      "integrity": "sha512-BEjgtECkL3vY+SaSQ6nzVfiALUeFxpawyp8Jmf5PtYhf1Ug40N1h/hxlhts+f1FvSvarEigdxS3BlSMI2PJLcQ==",
+      "cpu": [
+        "x64"
+      ],
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "sunos"
+      ],
+      "engines": {
+        "node": ">=18"
+      }
+    },
+    "node_modules/@esbuild/win32-arm64": {
+      "version": "0.28.1",
+      "resolved": "https://registry.npmjs.org/@esbuild/win32-arm64/-/win32-arm64-0.28.1.tgz",
+      "integrity": "sha512-lCv9eK/H6ZJWbE7bh2nw54CZ9M2nupBxJcTsdk/QQnWkdSjKGuxmmH8/GWrlT1eMmZfn4dGcCjRte397WqfQXA==",
+      "cpu": [
+        "arm64"
+      ],
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "win32"
+      ],
+      "engines": {
+        "node": ">=18"
+      }
+    },
+    "node_modules/@esbuild/win32-ia32": {
+      "version": "0.28.1",
+      "resolved": "https://registry.npmjs.org/@esbuild/win32-ia32/-/win32-ia32-0.28.1.tgz",
+      "integrity": "sha512-zvb/mB2bSCoJOpoCBgYKKpX6YM6mJBlBUVUtVj41DlZJVEB6/0CKlRYxP5wWl1C1ILiCoAU5wZZ4q1P3qeS6Eg==",
+      "cpu": [
+        "ia32"
+      ],
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "win32"
+      ],
+      "engines": {
+        "node": ">=18"
+      }
+    },
+    "node_modules/@esbuild/win32-x64": {
+      "version": "0.28.1",
+      "resolved": "https://registry.npmjs.org/@esbuild/win32-x64/-/win32-x64-0.28.1.tgz",
+      "integrity": "sha512-bm4Mowrv+GXMlpWX++EcXw/iLyd1o3+bJkC2DkWXYVvgZCqD/bSj9ctZeAMC3cIxgjRVR2Dufaiu4YPxr5gW1A==",
+      "cpu": [
+        "x64"
+      ],
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "win32"
+      ],
+      "engines": {
+        "node": ">=18"
+      }
+    },
+    "node_modules/@pinojs/redact": {
+      "version": "0.4.0",
+      "resolved": "https://registry.npmjs.org/@pinojs/redact/-/redact-0.4.0.tgz",
+      "integrity": "sha512-k2ENnmBugE/rzQfEcdWHcCY+/FM3VLzH9cYEsbdsoqrvzAKRhUZeRNhAZvB8OitQJ1TBed3yqWtdjzS6wJKBwg==",
+      "license": "MIT"
+    },
+    "node_modules/@standard-schema/spec": {
+      "version": "1.1.0",
+      "resolved": "https://registry.npmjs.org/@standard-schema/spec/-/spec-1.1.0.tgz",
+      "integrity": "sha512-l2aFy5jALhniG5HgqrD6jXLi/rUWrKvqN/qJx6yoJsgKhblVd+iqqU4RCXavm/jPityDo5TCvKMnpjKnOriy0w==",
+      "license": "MIT"
+    },
+    "node_modules/@types/handlebars": {
+      "version": "4.1.0",
+      "resolved": "https://registry.npmjs.org/@types/handlebars/-/handlebars-4.1.0.tgz",
+      "integrity": "sha512-gq9YweFKNNB1uFK71eRqsd4niVkXrxHugqWFQkeLRJvGjnxsLr16bYtcsG4tOFwmYi0Bax+wCkbf1reUfdl4kA==",
+      "deprecated": "This is a stub types definition. handlebars provides its own type definitions, so you do not need this installed.",
+      "license": "MIT",
+      "dependencies": {
+        "handlebars": "*"
+      }
+    },
+    "node_modules/@types/node": {
+      "version": "24.13.3",
+      "resolved": "https://registry.npmjs.org/@types/node/-/node-24.13.3.tgz",
+      "integrity": "sha512-Dh8vAsV36ig5wa9OX4pXvMc9D3Veibfw2wix0CUwYODLD8nkj9UsLjASr49nPg+2eKzxhBV+v7L8pXvT4e639Q==",
+      "license": "MIT",
+      "dependencies": {
+        "undici-types": "~7.18.0"
+      }
+    },
+    "node_modules/@types/tmp": {
+      "version": "0.2.6",
+      "resolved": "https://registry.npmjs.org/@types/tmp/-/tmp-0.2.6.tgz",
+      "integrity": "sha512-chhaNf2oKHlRkDGt+tiKE2Z5aJ6qalm7Z9rlLdBwmOiAAf09YQvvoLXjWK4HWPF1xU/fqvMgfNfpVoBscA/tKA==",
+      "license": "MIT"
+    },
+    "node_modules/@types/yargs": {
+      "version": "17.0.35",
+      "resolved": "https://registry.npmjs.org/@types/yargs/-/yargs-17.0.35.tgz",
+      "integrity": "sha512-qUHkeCyQFxMXg79wQfTtfndEC+N9ZZg76HJftDJp+qH2tV7Gj4OJi7l+PiWwJ+pWtW8GwSmqsDj/oymhrTWXjg==",
+      "license": "MIT",
+      "dependencies": {
+        "@types/yargs-parser": "*"
+      }
+    },
+    "node_modules/@types/yargs-parser": {
+      "version": "21.0.3",
+      "resolved": "https://registry.npmjs.org/@types/yargs-parser/-/yargs-parser-21.0.3.tgz",
+      "integrity": "sha512-I4q9QU9MQv4oEOz4tAHJtNz1cwuLxn2F3xcc2iV5WdqLPpUnj30aUuxt1mAxYTG+oe8CZMV/+6rU4S4gRDzqtQ==",
+      "license": "MIT"
+    },
+    "node_modules/@typescript/typescript-aix-ppc64": {
+      "version": "7.0.2",
+      "resolved": "https://registry.npmjs.org/@typescript/typescript-aix-ppc64/-/typescript-aix-ppc64-7.0.2.tgz",
+      "integrity": "sha512-MTKKkWB7p/0E9xi1d1tHtZ5PiLkGEMIq88pK2CubZjOsLtYTLqhgIgi6zepFa+9GHZ6h05NMCkQxGKiPXMxXtQ==",
+      "cpu": [
+        "ppc64"
+      ],
+      "license": "Apache-2.0",
+      "optional": true,
+      "os": [
+        "aix"
+      ],
+      "engines": {
+        "node": ">=16.20.0"
+      }
+    },
+    "node_modules/@typescript/typescript-darwin-arm64": {
+      "version": "7.0.2",
+      "resolved": "https://registry.npmjs.org/@typescript/typescript-darwin-arm64/-/typescript-darwin-arm64-7.0.2.tgz",
+      "integrity": "sha512-gowzar9MwS/aRWp6f3a4KUqzRjAZjOsmGNCM6LcTgXum+dBfgsBVMN+AgvOCCbguXyick6LJhpBszxMebJ8syA==",
+      "cpu": [
+        "arm64"
+      ],
+      "license": "Apache-2.0",
+      "optional": true,
+      "os": [
+        "darwin"
+      ],
+      "engines": {
+        "node": ">=16.20.0"
+      }
+    },
+    "node_modules/@typescript/typescript-darwin-x64": {
+      "version": "7.0.2",
+      "resolved": "https://registry.npmjs.org/@typescript/typescript-darwin-x64/-/typescript-darwin-x64-7.0.2.tgz",
+      "integrity": "sha512-SZ9xZInqApNlNGc9s0W1VSsktYSOe9cFqNOIqmN1Gs8SmkjKZYFt017G4VwPxASInODuAdbTW7sXiFUf893RgA==",
+      "cpu": [
+        "x64"
+      ],
+      "license": "Apache-2.0",
+      "optional": true,
+      "os": [
+        "darwin"
+      ],
+      "engines": {
+        "node": ">=16.20.0"
+      }
+    },
+    "node_modules/@typescript/typescript-freebsd-arm64": {
+      "version": "7.0.2",
+      "resolved": "https://registry.npmjs.org/@typescript/typescript-freebsd-arm64/-/typescript-freebsd-arm64-7.0.2.tgz",
+      "integrity": "sha512-W5NH4y/J0plIIS5b2xvTEkU7JFxyqdMAOgf+Ilhl0vHQXKO5dZoxd+C/jEtq56c4F3wk71RB4BMRQ2XdI+bwYQ==",
+      "cpu": [
+        "arm64"
+      ],
+      "license": "Apache-2.0",
+      "optional": true,
+      "os": [
+        "freebsd"
+      ],
+      "engines": {
+        "node": ">=16.20.0"
+      }
+    },
+    "node_modules/@typescript/typescript-freebsd-x64": {
+      "version": "7.0.2",
+      "resolved": "https://registry.npmjs.org/@typescript/typescript-freebsd-x64/-/typescript-freebsd-x64-7.0.2.tgz",
+      "integrity": "sha512-UMGDx5sTpzNw3WiPebH7l90IWfJggEd+egHt/q6p7/Cm3zqoV7VxkGXt+3DxPIw8CcmvAB0j3sVVfbhX+M4Tpw==",
+      "cpu": [
+        "x64"
+      ],
+      "license": "Apache-2.0",
+      "optional": true,
+      "os": [
+        "freebsd"
+      ],
+      "engines": {
+        "node": ">=16.20.0"
+      }
+    },
+    "node_modules/@typescript/typescript-linux-arm": {
+      "version": "7.0.2",
+      "resolved": "https://registry.npmjs.org/@typescript/typescript-linux-arm/-/typescript-linux-arm-7.0.2.tgz",
+      "integrity": "sha512-gffT3xPz9sR7j/YJExkyPntrI0P2EP9XbOyWzth2/Gs0RstK+90RBcO0ncXoXy/beYll1SXw846Nf2zdnEz0QQ==",
+      "cpu": [
+        "arm"
+      ],
+      "license": "Apache-2.0",
+      "optional": true,
+      "os": [
+        "linux"
+      ],
+      "engines": {
+        "node": ">=16.20.0"
+      }
+    },
+    "node_modules/@typescript/typescript-linux-arm64": {
+      "version": "7.0.2",
+      "resolved": "https://registry.npmjs.org/@typescript/typescript-linux-arm64/-/typescript-linux-arm64-7.0.2.tgz",
+      "integrity": "sha512-Qh4eU4/y3yDjnfjjyPYihMj5/ODIlmt+Bzu17OI+fiSRDW57QmU5SiN63exPRNJPKUzcc1INa1NXdrJ+MqHjUQ==",
+      "cpu": [
+        "arm64"
+      ],
+      "license": "Apache-2.0",
+      "optional": true,
+      "os": [
+        "linux"
+      ],
+      "engines": {
+        "node": ">=16.20.0"
+      }
+    },
+    "node_modules/@typescript/typescript-linux-loong64": {
+      "version": "7.0.2",
+      "resolved": "https://registry.npmjs.org/@typescript/typescript-linux-loong64/-/typescript-linux-loong64-7.0.2.tgz",
+      "integrity": "sha512-uEHck9i8hoAzXPiYRib1O7miOnz23SxIeVl6F4LXox+qov1K35jHcEW6VHKvZI+pyvl7fZEP4MCU5LYvIq1GuQ==",
+      "cpu": [
+        "loong64"
+      ],
+      "license": "Apache-2.0",
+      "optional": true,
+      "os": [
+        "linux"
+      ],
+      "engines": {
+        "node": ">=16.20.0"
+      }
+    },
+    "node_modules/@typescript/typescript-linux-mips64el": {
+      "version": "7.0.2",
+      "resolved": "https://registry.npmjs.org/@typescript/typescript-linux-mips64el/-/typescript-linux-mips64el-7.0.2.tgz",
+      "integrity": "sha512-R4KvAMnE43W5Qeqb0Ly56O3mWMWIAgsMyz36DCaycd5nbg/9kzm0liw3JocfRqyJY0KPmzFjbswozXyW0DnIYA==",
+      "cpu": [
+        "mips64el"
+      ],
+      "license": "Apache-2.0",
+      "optional": true,
+      "os": [
+        "linux"
+      ],
+      "engines": {
+        "node": ">=16.20.0"
+      }
+    },
+    "node_modules/@typescript/typescript-linux-ppc64": {
+      "version": "7.0.2",
+      "resolved": "https://registry.npmjs.org/@typescript/typescript-linux-ppc64/-/typescript-linux-ppc64-7.0.2.tgz",
+      "integrity": "sha512-DORx5b3sd/4S7eayxm4FQv+A7CrkUIGRaHiwI8oiHTAI1fAPWhF4J0vAlkC8biAlHSVVwxMQ3tjZ2/DVbnQiiA==",
+      "cpu": [
+        "ppc64"
+      ],
+      "license": "Apache-2.0",
+      "optional": true,
+      "os": [
+        "linux"
+      ],
+      "engines": {
+        "node": ">=16.20.0"
+      }
+    },
+    "node_modules/@typescript/typescript-linux-riscv64": {
+      "version": "7.0.2",
+      "resolved": "https://registry.npmjs.org/@typescript/typescript-linux-riscv64/-/typescript-linux-riscv64-7.0.2.tgz",
+      "integrity": "sha512-wf0jqEDOjrPRnKwYRyyJDRo11KMbvMFrU+q4zqKyChODBzvlkbhNQfKvLxQCcwTpdDaXSHZTVuh0JoCrKCUMHQ==",
+      "cpu": [
+        "riscv64"
+      ],
+      "license": "Apache-2.0",
+      "optional": true,
+      "os": [
+        "linux"
+      ],
+      "engines": {
+        "node": ">=16.20.0"
+      }
+    },
+    "node_modules/@typescript/typescript-linux-s390x": {
+      "version": "7.0.2",
+      "resolved": "https://registry.npmjs.org/@typescript/typescript-linux-s390x/-/typescript-linux-s390x-7.0.2.tgz",
+      "integrity": "sha512-IkwJc3L7yhytWd/ewjyxNDfOmswCm9GWMJT/ue/dU4aZNbwZeYAetq42VyLmsmSjvoX7z74X6ZaYCtzAr0EuGw==",
+      "cpu": [
+        "s390x"
+      ],
+      "license": "Apache-2.0",
+      "optional": true,
+      "os": [
+        "linux"
+      ],
+      "engines": {
+        "node": ">=16.20.0"
+      }
+    },
+    "node_modules/@typescript/typescript-linux-x64": {
+      "version": "7.0.2",
+      "resolved": "https://registry.npmjs.org/@typescript/typescript-linux-x64/-/typescript-linux-x64-7.0.2.tgz",
+      "integrity": "sha512-EYdf2cNg7rgCWJnxCdJ+F3V39O8ihb37eHAu1LK8oAFizgTQbPOK7zHHXbPt8rX24COqODXeI3sIf0fCXG7H/A==",
+      "cpu": [
+        "x64"
+      ],
+      "license": "Apache-2.0",
+      "optional": true,
+      "os": [
+        "linux"
+      ],
+      "engines": {
+        "node": ">=16.20.0"
+      }
+    },
+    "node_modules/@typescript/typescript-netbsd-arm64": {
+      "version": "7.0.2",
+      "resolved": "https://registry.npmjs.org/@typescript/typescript-netbsd-arm64/-/typescript-netbsd-arm64-7.0.2.tgz",
+      "integrity": "sha512-+polYF4MF04aPpO5FTkHran9yUQDSXqy5GiSDKpsll5jy3l3+g9QLhpf39T+ePtefhXLOGrLl0QIjkQP6VnelA==",
+      "cpu": [
+        "arm64"
+      ],
+      "license": "Apache-2.0",
+      "optional": true,
+      "os": [
+        "netbsd"
+      ],
+      "engines": {
+        "node": ">=16.20.0"
+      }
+    },
+    "node_modules/@typescript/typescript-netbsd-x64": {
+      "version": "7.0.2",
+      "resolved": "https://registry.npmjs.org/@typescript/typescript-netbsd-x64/-/typescript-netbsd-x64-7.0.2.tgz",
+      "integrity": "sha512-8YIT0EHM/3dq10ZOVF/A7pc/YSMtbcecct4rWtexrnSCHOPcpC2KTLXfTCR6vDpnSiY12heNb1GiN/wu+T/FyA==",
+      "cpu": [
+        "x64"
+      ],
+      "license": "Apache-2.0",
+      "optional": true,
+      "os": [
+        "netbsd"
+      ],
+      "engines": {
+        "node": ">=16.20.0"
+      }
+    },
+    "node_modules/@typescript/typescript-openbsd-arm64": {
+      "version": "7.0.2",
+      "resolved": "https://registry.npmjs.org/@typescript/typescript-openbsd-arm64/-/typescript-openbsd-arm64-7.0.2.tgz",
+      "integrity": "sha512-APT8+ClYnuYm1u9+kgGXoMj2VzWzcymwh2gNSQVySHfkRDGOTVkoWLjCmOQSaO+PoqQ57B0flRp9SA+7GnnkzQ==",
+      "cpu": [
+        "arm64"
+      ],
+      "license": "Apache-2.0",
+      "optional": true,
+      "os": [
+        "openbsd"
+      ],
+      "engines": {
+        "node": ">=16.20.0"
+      }
+    },
+    "node_modules/@typescript/typescript-openbsd-x64": {
+      "version": "7.0.2",
+      "resolved": "https://registry.npmjs.org/@typescript/typescript-openbsd-x64/-/typescript-openbsd-x64-7.0.2.tgz",
+      "integrity": "sha512-yX7s+Q0Dln0Dt9tEzZsAjXXR/+ytBM7AlglaqyeMPxQszJ1JhlJdZ6jLA+IzldHtflX81em7lDao1xXu+aRRkg==",
+      "cpu": [
+        "x64"
+      ],
+      "license": "Apache-2.0",
+      "optional": true,
+      "os": [
+        "openbsd"
+      ],
+      "engines": {
+        "node": ">=16.20.0"
+      }
+    },
+    "node_modules/@typescript/typescript-sunos-x64": {
+      "version": "7.0.2",
+      "resolved": "https://registry.npmjs.org/@typescript/typescript-sunos-x64/-/typescript-sunos-x64-7.0.2.tgz",
+      "integrity": "sha512-dLJDGaLZ1D4HPQn62u1n8mBDkJREwMsAkCdkwd4Ieqw+x3TUyTsqY0YiBCtE6H6OzzgGk3iuZ3vFWRS+E8/d1g==",
+      "cpu": [
+        "x64"
+      ],
+      "license": "Apache-2.0",
+      "optional": true,
+      "os": [
+        "sunos"
+      ],
+      "engines": {
+        "node": ">=16.20.0"
+      }
+    },
+    "node_modules/@typescript/typescript-win32-arm64": {
+      "version": "7.0.2",
+      "resolved": "https://registry.npmjs.org/@typescript/typescript-win32-arm64/-/typescript-win32-arm64-7.0.2.tgz",
+      "integrity": "sha512-Gyl1Vy6OsWesLzmq+EP0Fb7b4Nid5232AvcA2SFcdYreldpNtYFFofPjnt62y9hQy7VTaZp65ICJjuAQRaVcIQ==",
+      "cpu": [
+        "arm64"
+      ],
+      "license": "Apache-2.0",
+      "optional": true,
+      "os": [
+        "win32"
+      ],
+      "engines": {
+        "node": ">=16.20.0"
+      }
+    },
+    "node_modules/@typescript/typescript-win32-x64": {
+      "version": "7.0.2",
+      "resolved": "https://registry.npmjs.org/@typescript/typescript-win32-x64/-/typescript-win32-x64-7.0.2.tgz",
+      "integrity": "sha512-0BQ3HkAHHlKLSp1qRvf3SUhGpGsDuhB/jgFw75guyqbxJqEaS0Cw/VFO8i2nHglJUzQCRtMMR/IBAKE3ETMC4g==",
+      "cpu": [
+        "x64"
+      ],
+      "license": "Apache-2.0",
+      "optional": true,
+      "os": [
+        "win32"
+      ],
+      "engines": {
+        "node": ">=16.20.0"
+      }
+    },
+    "node_modules/@vercel/oidc": {
+      "version": "3.2.0",
+      "resolved": "https://registry.npmjs.org/@vercel/oidc/-/oidc-3.2.0.tgz",
+      "integrity": "sha512-UycprH3T6n3jH0k44NHMa7pnFHGu/N05MjojYr+Mc6I7obkoLIJujSWwin1pCvdy/eOxrI/l3uDLQsmcrOb4ug==",
+      "license": "Apache-2.0",
+      "engines": {
+        "node": ">= 20"
+      }
+    },
+    "node_modules/@workflow/serde": {
+      "version": "4.1.0",
+      "resolved": "https://registry.npmjs.org/@workflow/serde/-/serde-4.1.0.tgz",
+      "integrity": "sha512-pav4F2BoirECWR7Nf1TKt+2eETcBj7jj4cBefQ8VXQCA6NPkaKeLfj/zMgi+3zYV5ZIBT4GuUiphsj0/b9hPQQ==",
+      "license": "Apache-2.0"
+    },
+    "node_modules/agent-base": {
+      "version": "7.1.4",
+      "resolved": "https://registry.npmjs.org/agent-base/-/agent-base-7.1.4.tgz",
+      "integrity": "sha512-MnA+YT8fwfJPgBx3m60MNqakm30XOkyIoH1y6huTQvC0PwZG7ki8NacLBcrPbNoo8vEZy7Jpuk7+jMO+CUovTQ==",
+      "license": "MIT",
+      "engines": {
+        "node": ">= 14"
+      }
+    },
+    "node_modules/ai": {
+      "version": "7.0.57",
+      "resolved": "https://registry.npmjs.org/ai/-/ai-7.0.57.tgz",
+      "integrity": "sha512-MDnflmccMqafBrV5SB00YMqqTKuqpWrOaK74+dA21izk3HmeyHTakkeZRcdgz4iPEB6L2NtEZHOPKTivZp47lw==",
+      "license": "Apache-2.0",
+      "dependencies": {
+        "@ai-sdk/gateway": "4.0.45",
+        "@ai-sdk/provider": "4.0.6",
+        "@ai-sdk/provider-utils": "5.0.24"
+      },
+      "engines": {
+        "node": ">=22"
+      },
+      "peerDependencies": {
+        "zod": "^3.25.76 || ^4.1.8"
+      }
+    },
+    "node_modules/ansi-regex": {
+      "version": "6.2.2",
+      "resolved": "https://registry.npmjs.org/ansi-regex/-/ansi-regex-6.2.2.tgz",
+      "integrity": "sha512-Bq3SmSpyFHaWjPk8If9yc6svM8c56dB5BAtW4Qbw5jHTwwXXcTLoRMkpDJp6VL0XzlWaCHTXrkFURMYmD0sLqg==",
+      "license": "MIT",
+      "engines": {
+        "node": ">=12"
+      },
+      "funding": {
+        "url": "https://github.com/chalk/ansi-regex?sponsor=1"
+      }
+    },
+    "node_modules/ansi-styles": {
+      "version": "6.2.3",
+      "resolved": "https://registry.npmjs.org/ansi-styles/-/ansi-styles-6.2.3.tgz",
+      "integrity": "sha512-4Dj6M28JB+oAH8kFkTLUo+a2jwOFkuqb3yucU0CANcRRUbxS0cP0nZYCGjcc3BNXwRIsUVmDGgzawme7zvJHvg==",
+      "license": "MIT",
+      "engines": {
+        "node": ">=12"
+      },
+      "funding": {
+        "url": "https://github.com/chalk/ansi-styles?sponsor=1"
+      }
+    },
+    "node_modules/atomic-sleep": {
+      "version": "1.0.0",
+      "resolved": "https://registry.npmjs.org/atomic-sleep/-/atomic-sleep-1.0.0.tgz",
+      "integrity": "sha512-kNOjDqAh7px0XWNI+4QbzoiR/nTkHAWNud2uvnJquD1/x5a7EQZMJT0AczqK0Qn67oY/TTQ1LbUKajZpp3I9tQ==",
+      "license": "MIT",
+      "engines": {
+        "node": ">=8.0.0"
+      }
+    },
+    "node_modules/base64-js": {
+      "version": "1.5.1",
+      "resolved": "https://registry.npmjs.org/base64-js/-/base64-js-1.5.1.tgz",
+      "integrity": "sha512-AKpaYlHn8t4SVbOHCy+b5+KKgvR4vrsD8vbvrbiQJps7fKDTkjkDry6ji0rUJjC0kzbNePLwzxq8iypo41qeWA==",
+      "funding": [
+        {
+          "type": "github",
+          "url": "https://github.com/sponsors/feross"
+        },
+        {
+          "type": "patreon",
+          "url": "https://www.patreon.com/feross"
+        },
+        {
+          "type": "consulting",
+          "url": "https://feross.org/support"
+        }
+      ],
+      "license": "MIT"
+    },
+    "node_modules/bignumber.js": {
+      "version": "9.3.1",
+      "resolved": "https://registry.npmjs.org/bignumber.js/-/bignumber.js-9.3.1.tgz",
+      "integrity": "sha512-Ko0uX15oIUS7wJ3Rb30Fs6SkVbLmPBAKdlm7q9+ak9bbIeFf0MwuBsQV6z7+X768/cHsfg+WlysDWJcmthjsjQ==",
+      "license": "MIT",
+      "engines": {
+        "node": "*"
+      }
+    },
+    "node_modules/buffer-equal-constant-time": {
+      "version": "1.0.1",
+      "resolved": "https://registry.npmjs.org/buffer-equal-constant-time/-/buffer-equal-constant-time-1.0.1.tgz",
+      "integrity": "sha512-zRpUiDwd/xk6ADqPMATG8vc9VPrkck7T07OIx0gnjmJAnHnTVXNQG3vfvWNuiZIkwu9KrKdA1iJKfsfTVxE6NA==",
+      "license": "BSD-3-Clause"
+    },
+    "node_modules/chalk": {
+      "version": "6.0.0",
+      "resolved": "https://registry.npmjs.org/chalk/-/chalk-6.0.0.tgz",
+      "integrity": "sha512-2uNTXIuTTxk7ciZgAU1BQcgnchcG0xXnrs6jzkQfj9SsRa9M2s5zE8WT96hS6KmG4MzWHSrvH43DF1m4XRkrFg==",
+      "license": "MIT",
+      "engines": {
+        "node": ">=22"
+      },
+      "funding": {
+        "url": "https://github.com/chalk/chalk?sponsor=1"
+      }
+    },
+    "node_modules/cliui": {
+      "version": "9.0.1",
+      "resolved": "https://registry.npmjs.org/cliui/-/cliui-9.0.1.tgz",
+      "integrity": "sha512-k7ndgKhwoQveBL+/1tqGJYNz097I7WOvwbmmU2AR5+magtbjPWQTS1C5vzGkBC8Ym8UWRzfKUzUUqFLypY4Q+w==",
+      "license": "ISC",
+      "dependencies": {
+        "string-width": "^7.2.0",
+        "strip-ansi": "^7.1.0",
+        "wrap-ansi": "^9.0.0"
+      },
+      "engines": {
+        "node": ">=20"
+      }
+    },
+    "node_modules/colorette": {
+      "version": "2.0.20",
+      "resolved": "https://registry.npmjs.org/colorette/-/colorette-2.0.20.tgz",
+      "integrity": "sha512-IfEDxwoWIjkeXL1eXcDiow4UbKjhLdq6/EuSVR9GMN7KVH3r9gQ83e73hsz1Nd1T3ijd5xv1wcWRYO+D6kCI2w==",
+      "license": "MIT"
+    },
+    "node_modules/csv-parse": {
+      "version": "7.0.2",
+      "resolved": "https://registry.npmjs.org/csv-parse/-/csv-parse-7.0.2.tgz",
+      "integrity": "sha512-uKZghv9UmPkMVLYy//KZ9HFAIJsl7wkhoEdIL0+rhuSY9pZQlhaeGEDPIe+/w7eh81MOql8Q/9+inAGWG6ZHYA==",
+      "license": "MIT"
+    },
+    "node_modules/data-uri-to-buffer": {
+      "version": "4.0.1",
+      "resolved": "https://registry.npmjs.org/data-uri-to-buffer/-/data-uri-to-buffer-4.0.1.tgz",
+      "integrity": "sha512-0R9ikRb668HB7QDxT1vkpuUBtqc53YyAwMwGeUFKRojY/NWKvdZ+9UYtRfGmhqNbRkTSVpMbmyhXipFFv2cb/A==",
+      "license": "MIT",
+      "engines": {
+        "node": ">= 12"
+      }
+    },
+    "node_modules/dateformat": {
+      "version": "4.6.3",
+      "resolved": "https://registry.npmjs.org/dateformat/-/dateformat-4.6.3.tgz",
+      "integrity": "sha512-2P0p0pFGzHS5EMnhdxQi7aJN+iMheud0UhG4dlE1DLAlvL8JHjJJTX/CSm4JXwV0Ka5nGk3zC5mcb5bUQUxxMA==",
+      "license": "MIT",
+      "engines": {
+        "node": "*"
+      }
+    },
+    "node_modules/debug": {
+      "version": "4.4.3",
+      "resolved": "https://registry.npmjs.org/debug/-/debug-4.4.3.tgz",
+      "integrity": "sha512-RGwwWnwQvkVfavKVt22FGLw+xYSdzARwm0ru6DhTVA3umU5hZc28V3kO4stgYryrTlLpuvgI9GiijltAjNbcqA==",
+      "license": "MIT",
+      "dependencies": {
+        "ms": "^2.1.3"
+      },
+      "engines": {
+        "node": ">=6.0"
+      },
+      "peerDependenciesMeta": {
+        "supports-color": {
+          "optional": true
+        }
+      }
+    },
+    "node_modules/ecdsa-sig-formatter": {
+      "version": "1.0.11",
+      "resolved": "https://registry.npmjs.org/ecdsa-sig-formatter/-/ecdsa-sig-formatter-1.0.11.tgz",
+      "integrity": "sha512-nagl3RYrbNv6kQkeJIpt6NJZy8twLB/2vtz6yN9Z4vRKHN4/QZJIEbqohALSgwKdnksuY3k5Addp5lg8sVoVcQ==",
+      "license": "Apache-2.0",
+      "dependencies": {
+        "safe-buffer": "^5.0.1"
+      }
+    },
+    "node_modules/emoji-regex": {
+      "version": "10.6.0",
+      "resolved": "https://registry.npmjs.org/emoji-regex/-/emoji-regex-10.6.0.tgz",
+      "integrity": "sha512-toUI84YS5YmxW219erniWD0CIVOo46xGKColeNQRgOzDorgBi1v4D71/OFzgD9GO2UGKIv1C3Sp8DAn0+j5w7A==",
+      "license": "MIT"
+    },
+    "node_modules/end-of-stream": {
+      "version": "1.4.5",
+      "resolved": "https://registry.npmjs.org/end-of-stream/-/end-of-stream-1.4.5.tgz",
+      "integrity": "sha512-ooEGc6HP26xXq/N+GCGOT0JKCLDGrq2bQUZrQ7gyrJiZANJ/8YDTxTpQBXGMn+WbIQXNVpyWymm7KYVICQnyOg==",
+      "license": "MIT",
+      "dependencies": {
+        "once": "^1.4.0"
+      }
+    },
+    "node_modules/esbuild": {
+      "version": "0.28.1",
+      "resolved": "https://registry.npmjs.org/esbuild/-/esbuild-0.28.1.tgz",
+      "integrity": "sha512-HrJrvZv5ayxBzPfwphOoNzkzOIIlifzk0KJrGK2c8R4+LKpMtpYLQeUdjnwjWv/LZlkH2laZk+4w78pi99D4Vw==",
+      "hasInstallScript": true,
+      "license": "MIT",
+      "bin": {
+        "esbuild": "bin/esbuild"
+      },
+      "engines": {
+        "node": ">=18"
+      },
+      "optionalDependencies": {
+        "@esbuild/aix-ppc64": "0.28.1",
+        "@esbuild/android-arm": "0.28.1",
+        "@esbuild/android-arm64": "0.28.1",
+        "@esbuild/android-x64": "0.28.1",
+        "@esbuild/darwin-arm64": "0.28.1",
+        "@esbuild/darwin-x64": "0.28.1",
+        "@esbuild/freebsd-arm64": "0.28.1",
+        "@esbuild/freebsd-x64": "0.28.1",
+        "@esbuild/linux-arm": "0.28.1",
+        "@esbuild/linux-arm64": "0.28.1",
+        "@esbuild/linux-ia32": "0.28.1",
+        "@esbuild/linux-loong64": "0.28.1",
+        "@esbuild/linux-mips64el": "0.28.1",
+        "@esbuild/linux-ppc64": "0.28.1",
+        "@esbuild/linux-riscv64": "0.28.1",
+        "@esbuild/linux-s390x": "0.28.1",
+        "@esbuild/linux-x64": "0.28.1",
+        "@esbuild/netbsd-arm64": "0.28.1",
+        "@esbuild/netbsd-x64": "0.28.1",
+        "@esbuild/openbsd-arm64": "0.28.1",
+        "@esbuild/openbsd-x64": "0.28.1",
+        "@esbuild/openharmony-arm64": "0.28.1",
+        "@esbuild/sunos-x64": "0.28.1",
+        "@esbuild/win32-arm64": "0.28.1",
+        "@esbuild/win32-ia32": "0.28.1",
+        "@esbuild/win32-x64": "0.28.1"
+      }
+    },
+    "node_modules/escalade": {
+      "version": "3.2.0",
+      "resolved": "https://registry.npmjs.org/escalade/-/escalade-3.2.0.tgz",
+      "integrity": "sha512-WUj2qlxaQtO4g6Pq5c29GTcWGDyd8itL8zTlipgECz3JesAiiOKotd8JU6otB3PACgG6xkJUyVhboMS+bje/jA==",
+      "license": "MIT",
+      "engines": {
+        "node": ">=6"
+      }
+    },
+    "node_modules/eventsource-parser": {
+      "version": "3.0.8",
+      "resolved": "https://registry.npmjs.org/eventsource-parser/-/eventsource-parser-3.0.8.tgz",
+      "integrity": "sha512-70QWGkr4snxr0OXLRWsFLeRBIRPuQOvt4s8QYjmUlmlkyTZkRqS7EDVRZtzU3TiyDbXSzaOeF0XUKy8PchzukQ==",
+      "license": "MIT",
+      "engines": {
+        "node": ">=18.0.0"
+      }
+    },
+    "node_modules/extend": {
+      "version": "3.0.2",
+      "resolved": "https://registry.npmjs.org/extend/-/extend-3.0.2.tgz",
+      "integrity": "sha512-fjquC59cD7CyW6urNXK0FBufkZcoiGG80wTuPujX590cB5Ttln20E2UB4S/WARVqhXffZl2LNgS+gQdPIIim/g==",
+      "license": "MIT"
+    },
+    "node_modules/fast-copy": {
+      "version": "4.0.3",
+      "resolved": "https://registry.npmjs.org/fast-copy/-/fast-copy-4.0.3.tgz",
+      "integrity": "sha512-58apWr0GUiDFM8+3afrO6eYwJBn9ZAhDOzG3L+/9llab/haCARS2UIfffmOurYLwbgDRs8n0rfr6qAAPEAuAQw==",
+      "license": "MIT"
+    },
+    "node_modules/fast-safe-stringify": {
+      "version": "2.1.1",
+      "resolved": "https://registry.npmjs.org/fast-safe-stringify/-/fast-safe-stringify-2.1.1.tgz",
+      "integrity": "sha512-W+KJc2dmILlPplD/H4K9l9LcAHAfPtP6BY84uVLXQ6Evcz9Lcg33Y2z1IVblT6xdY54PXYVHEv+0Wpq8Io6zkA==",
+      "license": "MIT"
+    },
+    "node_modules/fetch-blob": {
+      "version": "3.2.0",
+      "resolved": "https://registry.npmjs.org/fetch-blob/-/fetch-blob-3.2.0.tgz",
+      "integrity": "sha512-7yAQpD2UMJzLi1Dqv7qFYnPbaPx7ZfFK6PiIxQ4PfkGPyNyl2Ugx+a/umUonmKqjhM4DnfbMvdX6otXq83soQQ==",
+      "funding": [
+        {
+          "type": "github",
+          "url": "https://github.com/sponsors/jimmywarting"
+        },
+        {
+          "type": "paypal",
+          "url": "https://paypal.me/jimmywarting"
+        }
+      ],
+      "license": "MIT",
+      "dependencies": {
+        "node-domexception": "^1.0.0",
+        "web-streams-polyfill": "^3.0.3"
+      },
+      "engines": {
+        "node": "^12.20 || >= 14.13"
+      }
+    },
+    "node_modules/formdata-polyfill": {
+      "version": "4.0.10",
+      "resolved": "https://registry.npmjs.org/formdata-polyfill/-/formdata-polyfill-4.0.10.tgz",
+      "integrity": "sha512-buewHzMvYL29jdeQTVILecSaZKnt/RJWjoZCF5OW60Z67/GmSLBkOFM7qh1PI3zFNtJbaZL5eQu1vLfazOwj4g==",
+      "license": "MIT",
+      "dependencies": {
+        "fetch-blob": "^3.1.2"
+      },
+      "engines": {
+        "node": ">=12.20.0"
+      }
+    },
+    "node_modules/fsevents": {
+      "version": "2.3.3",
+      "resolved": "https://registry.npmjs.org/fsevents/-/fsevents-2.3.3.tgz",
+      "integrity": "sha512-5xoDfX+fL7faATnagmWPpbFtwh/R77WmMMqqHGS65C3vvB0YHrgF+B1YmZ3441tMj5n63k0212XNoJwzlhffQw==",
+      "hasInstallScript": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "darwin"
+      ],
+      "engines": {
+        "node": "^8.16.0 || ^10.6.0 || >=11.0.0"
+      }
+    },
+    "node_modules/gaxios": {
+      "version": "7.1.5",
+      "resolved": "https://registry.npmjs.org/gaxios/-/gaxios-7.1.5.tgz",
+      "integrity": "sha512-5FZy72Rh8LhtjmvDrKkI+lVhrsQrVKVsItxMoDm5mNQE+xR0WVIIs+jzPSJgBvKVsLi24fZhXJIsNI0bihDzFg==",
+      "license": "Apache-2.0",
+      "dependencies": {
+        "extend": "^3.0.2",
+        "https-proxy-agent": "^7.0.1",
+        "node-fetch": "^3.3.2"
+      },
+      "engines": {
+        "node": ">=18"
+      }
+    },
+    "node_modules/gcp-metadata": {
+      "version": "8.1.2",
+      "resolved": "https://registry.npmjs.org/gcp-metadata/-/gcp-metadata-8.1.2.tgz",
+      "integrity": "sha512-zV/5HKTfCeKWnxG0Dmrw51hEWFGfcF2xiXqcA3+J90WDuP0SvoiSO5ORvcBsifmx/FoIjgQN3oNOGaQ5PhLFkg==",
+      "license": "Apache-2.0",
+      "dependencies": {
+        "gaxios": "^7.0.0",
+        "google-logging-utils": "^1.0.0",
+        "json-bigint": "^1.0.0"
+      },
+      "engines": {
+        "node": ">=18"
+      }
+    },
+    "node_modules/get-caller-file": {
+      "version": "2.0.5",
+      "resolved": "https://registry.npmjs.org/get-caller-file/-/get-caller-file-2.0.5.tgz",
+      "integrity": "sha512-DyFP3BM/3YHTQOCUL/w0OZHR0lpKeGrxotcHWcqNEdnltqFwXVfhEBQ94eIo34AfQpo0rGki4cyIiftY06h2Fg==",
+      "license": "ISC",
+      "engines": {
+        "node": "6.* || 8.* || >= 10.*"
+      }
+    },
+    "node_modules/get-east-asian-width": {
+      "version": "1.6.0",
+      "resolved": "https://registry.npmjs.org/get-east-asian-width/-/get-east-asian-width-1.6.0.tgz",
+      "integrity": "sha512-QRbvDIbx6YklUe6RxeTeleMR0yv3cYH6PsPZHcnVn7xv7zO1BHN8r0XETu8n6Ye3Q+ahtSarc3WgtNWmehIBfA==",
+      "license": "MIT",
+      "engines": {
+        "node": ">=18"
+      },
+      "funding": {
+        "url": "https://github.com/sponsors/sindresorhus"
+      }
+    },
+    "node_modules/google-auth-library": {
+      "version": "10.9.0",
+      "resolved": "https://registry.npmjs.org/google-auth-library/-/google-auth-library-10.9.0.tgz",
+      "integrity": "sha512-xtvUqvINPhTaBm7nXqlYPcrMHJPm1lCNdSovxnKKhTm+4JsvQ+KGVYJViLoH9Yxu8w+T0Qv5HubzYT9BLrppJg==",
+      "license": "Apache-2.0",
+      "dependencies": {
+        "base64-js": "^1.3.0",
+        "ecdsa-sig-formatter": "^1.0.11",
+        "gaxios": "^7.1.4",
+        "gcp-metadata": "8.1.2",
+        "google-logging-utils": "1.1.3",
+        "jws": "^4.0.0"
+      },
+      "engines": {
+        "node": ">=18"
+      }
+    },
+    "node_modules/google-logging-utils": {
+      "version": "1.1.3",
+      "resolved": "https://registry.npmjs.org/google-logging-utils/-/google-logging-utils-1.1.3.tgz",
+      "integrity": "sha512-eAmLkjDjAFCVXg7A1unxHsLf961m6y17QFqXqAXGj/gVkKFrEICfStRfwUlGNfeCEjNRa32JEWOUTlYXPyyKvA==",
+      "license": "Apache-2.0",
+      "engines": {
+        "node": ">=14"
+      }
+    },
+    "node_modules/handlebars": {
+      "version": "4.7.9",
+      "resolved": "https://registry.npmjs.org/handlebars/-/handlebars-4.7.9.tgz",
+      "integrity": "sha512-4E71E0rpOaQuJR2A3xDZ+GM1HyWYv1clR58tC8emQNeQe3RH7MAzSbat+V0wG78LQBo6m6bzSG/L4pBuCsgnUQ==",
+      "license": "MIT",
+      "dependencies": {
+        "minimist": "^1.2.5",
+        "neo-async": "^2.6.2",
+        "source-map": "^0.6.1",
+        "wordwrap": "^1.0.0"
+      },
+      "bin": {
+        "handlebars": "bin/handlebars"
+      },
+      "engines": {
+        "node": ">=0.4.7"
+      },
+      "optionalDependencies": {
+        "uglify-js": "^3.1.4"
+      }
+    },
+    "node_modules/help-me": {
+      "version": "5.0.0",
+      "resolved": "https://registry.npmjs.org/help-me/-/help-me-5.0.0.tgz",
+      "integrity": "sha512-7xgomUX6ADmcYzFik0HzAxh/73YlKR9bmFzf51CZwR+b6YtzU2m0u49hQCqV6SvlqIqsaxovfwdvbnsw3b/zpg==",
+      "license": "MIT"
+    },
+    "node_modules/https-proxy-agent": {
+      "version": "7.0.6",
+      "resolved": "https://registry.npmjs.org/https-proxy-agent/-/https-proxy-agent-7.0.6.tgz",
+      "integrity": "sha512-vK9P5/iUfdl95AI+JVyUuIcVtd4ofvtrOr3HNtM2yxC9bnMbEdp3x01OhQNnjb8IJYi38VlTE3mBXwcfvywuSw==",
+      "license": "MIT",
+      "dependencies": {
+        "agent-base": "^7.1.2",
+        "debug": "4"
+      },
+      "engines": {
+        "node": ">= 14"
+      }
+    },
+    "node_modules/joycon": {
+      "version": "3.1.1",
+      "resolved": "https://registry.npmjs.org/joycon/-/joycon-3.1.1.tgz",
+      "integrity": "sha512-34wB/Y7MW7bzjKRjUKTa46I2Z7eV62Rkhva+KkopW7Qvv/OSWBqvkSY7vusOPrNuZcUG3tApvdVgNB8POj3SPw==",
+      "license": "MIT",
+      "engines": {
+        "node": ">=10"
+      }
+    },
+    "node_modules/json-bigint": {
+      "version": "1.0.0",
+      "resolved": "https://registry.npmjs.org/json-bigint/-/json-bigint-1.0.0.tgz",
+      "integrity": "sha512-SiPv/8VpZuWbvLSMtTDU8hEfrZWg/mH/nV/b4o0CYbSxu1UIQPLdwKOCIyLQX+VIPO5vrLX3i8qtqFyhdPSUSQ==",
+      "license": "MIT",
+      "dependencies": {
+        "bignumber.js": "^9.0.0"
+      }
+    },
+    "node_modules/json-schema": {
+      "version": "0.4.0",
+      "resolved": "https://registry.npmjs.org/json-schema/-/json-schema-0.4.0.tgz",
+      "integrity": "sha512-es94M3nTIfsEPisRafak+HDLfHXnKBhV3vU5eqPcS3flIWqcxJWgXHXiey3YrpaNsanY5ei1VoYEbOzijuq9BA==",
+      "license": "(AFL-2.1 OR BSD-3-Clause)"
+    },
+    "node_modules/jwa": {
+      "version": "2.0.1",
+      "resolved": "https://registry.npmjs.org/jwa/-/jwa-2.0.1.tgz",
+      "integrity": "sha512-hRF04fqJIP8Abbkq5NKGN0Bbr3JxlQ+qhZufXVr0DvujKy93ZCbXZMHDL4EOtodSbCWxOqR8MS1tXA5hwqCXDg==",
+      "license": "MIT",
+      "dependencies": {
+        "buffer-equal-constant-time": "^1.0.1",
+        "ecdsa-sig-formatter": "1.0.11",
+        "safe-buffer": "^5.0.1"
+      }
+    },
+    "node_modules/jws": {
+      "version": "4.0.1",
+      "resolved": "https://registry.npmjs.org/jws/-/jws-4.0.1.tgz",
+      "integrity": "sha512-EKI/M/yqPncGUUh44xz0PxSidXFr/+r0pA70+gIYhjv+et7yxM+s29Y+VGDkovRofQem0fs7Uvf4+YmAdyRduA==",
+      "license": "MIT",
+      "dependencies": {
+        "jwa": "^2.0.1",
+        "safe-buffer": "^5.0.1"
+      }
+    },
+    "node_modules/minimist": {
+      "version": "1.2.8",
+      "resolved": "https://registry.npmjs.org/minimist/-/minimist-1.2.8.tgz",
+      "integrity": "sha512-2yyAR8qBkN3YuheJanUpWC5U3bb5osDywNB8RzDVlDwDHbocAJveqqj1u8+SVD7jkWT4yvsHCpWqqWqAxb0zCA==",
+      "license": "MIT",
+      "funding": {
+        "url": "https://github.com/sponsors/ljharb"
+      }
+    },
+    "node_modules/ms": {
+      "version": "2.1.3",
+      "resolved": "https://registry.npmjs.org/ms/-/ms-2.1.3.tgz",
+      "integrity": "sha512-6FlzubTLZG3J2a/NVCAleEhjzq5oxgHyaCU9yYXvcLsvoVaHJq/s5xXI6/XXP6tz7R9xAOtHnSO/tXtF3WRTlA==",
+      "license": "MIT"
+    },
+    "node_modules/neo-async": {
+      "version": "2.6.2",
+      "resolved": "https://registry.npmjs.org/neo-async/-/neo-async-2.6.2.tgz",
+      "integrity": "sha512-Yd3UES5mWCSqR+qNT93S3UoYUkqAZ9lLg8a7g9rimsWmYGK8cVToA4/sF3RrshdyV3sAGMXVUmpMYOw+dLpOuw==",
+      "license": "MIT"
+    },
+    "node_modules/node-domexception": {
+      "version": "1.0.0",
+      "resolved": "https://registry.npmjs.org/node-domexception/-/node-domexception-1.0.0.tgz",
+      "integrity": "sha512-/jKZoMpw0F8GRwl4/eLROPA3cfcXtLApP0QzLmUT/HuPCZWyB7IY9ZrMeKw2O/nFIqPQB3PVM9aYm0F312AXDQ==",
+      "deprecated": "Use your platform's native DOMException instead",
+      "funding": [
+        {
+          "type": "github",
+          "url": "https://github.com/sponsors/jimmywarting"
+        },
+        {
+          "type": "github",
+          "url": "https://paypal.me/jimmywarting"
+        }
+      ],
+      "license": "MIT",
+      "engines": {
+        "node": ">=10.5.0"
+      }
+    },
+    "node_modules/node-fetch": {
+      "version": "3.3.2",
+      "resolved": "https://registry.npmjs.org/node-fetch/-/node-fetch-3.3.2.tgz",
+      "integrity": "sha512-dRB78srN/l6gqWulah9SrxeYnxeddIG30+GOqK/9OlLVyLg3HPnr6SqOWTWOXKRwC2eGYCkZ59NNuSgvSrpgOA==",
+      "license": "MIT",
+      "dependencies": {
+        "data-uri-to-buffer": "^4.0.0",
+        "fetch-blob": "^3.1.4",
+        "formdata-polyfill": "^4.0.10"
+      },
+      "engines": {
+        "node": "^12.20.0 || ^14.13.1 || >=16.0.0"
+      },
+      "funding": {
+        "type": "opencollective",
+        "url": "https://opencollective.com/node-fetch"
+      }
+    },
+    "node_modules/on-exit-leak-free": {
+      "version": "2.1.2",
+      "resolved": "https://registry.npmjs.org/on-exit-leak-free/-/on-exit-leak-free-2.1.2.tgz",
+      "integrity": "sha512-0eJJY6hXLGf1udHwfNftBqH+g73EU4B504nZeKpz1sYRKafAghwxEJunB2O7rDZkL4PGfsMVnTXZ2EjibbqcsA==",
+      "license": "MIT",
+      "engines": {
+        "node": ">=14.0.0"
+      }
+    },
+    "node_modules/once": {
+      "version": "1.4.0",
+      "resolved": "https://registry.npmjs.org/once/-/once-1.4.0.tgz",
+      "integrity": "sha512-lNaJgI+2Q5URQBkccEKHTQOPaXdUxnZZElQTZY0MFUAuaEqe1E+Nyvgdz/aIyNi6Z9MzO5dv1H8n58/GELp3+w==",
+      "license": "ISC",
+      "dependencies": {
+        "wrappy": "1"
+      }
+    },
+    "node_modules/p-limit": {
+      "version": "7.3.1",
+      "resolved": "https://registry.npmjs.org/p-limit/-/p-limit-7.3.1.tgz",
+      "integrity": "sha512-0trZaiG7Y7kN/Egy9a8j47t9osC0Tch4PaIWd9yGF6bvmlk7muExRvGNYb8sXBwEKMoNKsbNN9P8EefuQekE4Q==",
+      "license": "MIT",
+      "dependencies": {
+        "yocto-queue": "^1.2.1"
+      },
+      "engines": {
+        "node": ">=20"
+      },
+      "funding": {
+        "url": "https://github.com/sponsors/sindresorhus"
+      }
+    },
+    "node_modules/pino": {
+      "version": "10.3.1",
+      "resolved": "https://registry.npmjs.org/pino/-/pino-10.3.1.tgz",
+      "integrity": "sha512-r34yH/GlQpKZbU1BvFFqOjhISRo1MNx1tWYsYvmj6KIRHSPMT2+yHOEb1SG6NMvRoHRF0a07kCOox/9yakl1vg==",
+      "license": "MIT",
+      "dependencies": {
+        "@pinojs/redact": "^0.4.0",
+        "atomic-sleep": "^1.0.0",
+        "on-exit-leak-free": "^2.1.0",
+        "pino-abstract-transport": "^3.0.0",
+        "pino-std-serializers": "^7.0.0",
+        "process-warning": "^5.0.0",
+        "quick-format-unescaped": "^4.0.3",
+        "real-require": "^0.2.0",
+        "safe-stable-stringify": "^2.3.1",
+        "sonic-boom": "^4.0.1",
+        "thread-stream": "^4.0.0"
+      },
+      "bin": {
+        "pino": "bin.js"
+      }
+    },
+    "node_modules/pino-abstract-transport": {
+      "version": "3.0.0",
+      "resolved": "https://registry.npmjs.org/pino-abstract-transport/-/pino-abstract-transport-3.0.0.tgz",
+      "integrity": "sha512-wlfUczU+n7Hy/Ha5j9a/gZNy7We5+cXp8YL+X+PG8S0KXxw7n/JXA3c46Y0zQznIJ83URJiwy7Lh56WLokNuxg==",
+      "license": "MIT",
+      "dependencies": {
+        "split2": "^4.0.0"
+      }
+    },
+    "node_modules/pino-pretty": {
+      "version": "13.1.3",
+      "resolved": "https://registry.npmjs.org/pino-pretty/-/pino-pretty-13.1.3.tgz",
+      "integrity": "sha512-ttXRkkOz6WWC95KeY9+xxWL6AtImwbyMHrL1mSwqwW9u+vLp/WIElvHvCSDg0xO/Dzrggz1zv3rN5ovTRVowKg==",
+      "license": "MIT",
+      "dependencies": {
+        "colorette": "^2.0.7",
+        "dateformat": "^4.6.3",
+        "fast-copy": "^4.0.0",
+        "fast-safe-stringify": "^2.1.1",
+        "help-me": "^5.0.0",
+        "joycon": "^3.1.1",
+        "minimist": "^1.2.6",
+        "on-exit-leak-free": "^2.1.0",
+        "pino-abstract-transport": "^3.0.0",
+        "pump": "^3.0.0",
+        "secure-json-parse": "^4.0.0",
+        "sonic-boom": "^4.0.1",
+        "strip-json-comments": "^5.0.2"
+      },
+      "bin": {
+        "pino-pretty": "bin.js"
+      }
+    },
+    "node_modules/pino-std-serializers": {
+      "version": "7.0.0",
+      "resolved": "https://registry.npmjs.org/pino-std-serializers/-/pino-std-serializers-7.0.0.tgz",
+      "integrity": "sha512-e906FRY0+tV27iq4juKzSYPbUj2do2X2JX4EzSca1631EB2QJQUqGbDuERal7LCtOpxl6x3+nvo9NPZcmjkiFA==",
+      "license": "MIT"
+    },
+    "node_modules/process-warning": {
+      "version": "5.0.0",
+      "resolved": "https://registry.npmjs.org/process-warning/-/process-warning-5.0.0.tgz",
+      "integrity": "sha512-a39t9ApHNx2L4+HBnQKqxxHNs1r7KF+Intd8Q/g1bUh6q0WIp9voPXJ/x0j+ZL45KF1pJd9+q2jLIRMfvEshkA==",
+      "funding": [
+        {
+          "type": "github",
+          "url": "https://github.com/sponsors/fastify"
+        },
+        {
+          "type": "opencollective",
+          "url": "https://opencollective.com/fastify"
+        }
+      ],
+      "license": "MIT"
+    },
+    "node_modules/pump": {
+      "version": "3.0.3",
+      "resolved": "https://registry.npmjs.org/pump/-/pump-3.0.3.tgz",
+      "integrity": "sha512-todwxLMY7/heScKmntwQG8CXVkWUOdYxIvY2s0VWAAMh/nd8SoYiRaKjlr7+iCs984f2P8zvrfWcDDYVb73NfA==",
+      "license": "MIT",
+      "dependencies": {
+        "end-of-stream": "^1.1.0",
+        "once": "^1.3.1"
+      }
+    },
+    "node_modules/quick-format-unescaped": {
+      "version": "4.0.4",
+      "resolved": "https://registry.npmjs.org/quick-format-unescaped/-/quick-format-unescaped-4.0.4.tgz",
+      "integrity": "sha512-tYC1Q1hgyRuHgloV/YXs2w15unPVh8qfu/qCTfhTYamaw7fyhumKa2yGpdSo87vY32rIclj+4fWYQXUMs9EHvg==",
+      "license": "MIT"
+    },
+    "node_modules/real-require": {
+      "version": "0.2.0",
+      "resolved": "https://registry.npmjs.org/real-require/-/real-require-0.2.0.tgz",
+      "integrity": "sha512-57frrGM/OCTLqLOAh0mhVA9VBMHd+9U7Zb2THMGdBUoZVOtGbJzjxsYGDJ3A9AYYCP4hn6y1TVbaOfzWtm5GFg==",
+      "license": "MIT",
+      "engines": {
+        "node": ">= 12.13.0"
+      }
+    },
+    "node_modules/safe-buffer": {
+      "version": "5.2.1",
+      "resolved": "https://registry.npmjs.org/safe-buffer/-/safe-buffer-5.2.1.tgz",
+      "integrity": "sha512-rp3So07KcdmmKbGvgaNxQSJr7bGVSVk5S9Eq1F+ppbRo70+YeaDxkw5Dd8NPN+GD6bjnYm2VuPuCXmpuYvmCXQ==",
+      "funding": [
+        {
+          "type": "github",
+          "url": "https://github.com/sponsors/feross"
+        },
+        {
+          "type": "patreon",
+          "url": "https://www.patreon.com/feross"
+        },
+        {
+          "type": "consulting",
+          "url": "https://feross.org/support"
+        }
+      ],
+      "license": "MIT"
+    },
+    "node_modules/safe-stable-stringify": {
+      "version": "2.5.0",
+      "resolved": "https://registry.npmjs.org/safe-stable-stringify/-/safe-stable-stringify-2.5.0.tgz",
+      "integrity": "sha512-b3rppTKm9T+PsVCBEOUR46GWI7fdOs00VKZ1+9c1EWDaDMvjQc6tUwuFyIprgGgTcWoVHSKrU8H31ZHA2e0RHA==",
+      "license": "MIT",
+      "engines": {
+        "node": ">=10"
+      }
+    },
+    "node_modules/secure-json-parse": {
+      "version": "4.1.0",
+      "resolved": "https://registry.npmjs.org/secure-json-parse/-/secure-json-parse-4.1.0.tgz",
+      "integrity": "sha512-l4KnYfEyqYJxDwlNVyRfO2E4NTHfMKAWdUuA8J0yve2Dz/E/PdBepY03RvyJpssIpRFwJoCD55wA+mEDs6ByWA==",
+      "funding": [
+        {
+          "type": "github",
+          "url": "https://github.com/sponsors/fastify"
+        },
+        {
+          "type": "opencollective",
+          "url": "https://opencollective.com/fastify"
+        }
+      ],
+      "license": "BSD-3-Clause"
+    },
+    "node_modules/sonic-boom": {
+      "version": "4.2.0",
+      "resolved": "https://registry.npmjs.org/sonic-boom/-/sonic-boom-4.2.0.tgz",
+      "integrity": "sha512-INb7TM37/mAcsGmc9hyyI6+QR3rR1zVRu36B0NeGXKnOOLiZOfER5SA+N7X7k3yUYRzLWafduTDvJAfDswwEww==",
+      "license": "MIT",
+      "dependencies": {
+        "atomic-sleep": "^1.0.0"
+      }
+    },
+    "node_modules/source-map": {
+      "version": "0.6.1",
+      "resolved": "https://registry.npmjs.org/source-map/-/source-map-0.6.1.tgz",
+      "integrity": "sha512-UjgapumWlbMhkBgzT7Ykc5YXUT46F0iKu8SGXq0bcwP5dz/h0Plj6enJqjz1Zbq2l5WaqYnrVbwWOWMyF3F47g==",
+      "license": "BSD-3-Clause",
+      "engines": {
+        "node": ">=0.10.0"
+      }
+    },
+    "node_modules/split2": {
+      "version": "4.2.0",
+      "resolved": "https://registry.npmjs.org/split2/-/split2-4.2.0.tgz",
+      "integrity": "sha512-UcjcJOWknrNkF6PLX83qcHM6KHgVKNkV62Y8a5uYDVv9ydGQVwAHMKqHdJje1VTWpljG0WYpCDhrCdAOYH4TWg==",
+      "license": "ISC",
+      "engines": {
+        "node": ">= 10.x"
+      }
+    },
+    "node_modules/string-width": {
+      "version": "7.2.0",
+      "resolved": "https://registry.npmjs.org/string-width/-/string-width-7.2.0.tgz",
+      "integrity": "sha512-tsaTIkKW9b4N+AEj+SVA+WhJzV7/zMhcSu78mLKWSk7cXMOSHsBKFWUs0fWwq8QyK3MgJBQRX6Gbi4kYbdvGkQ==",
+      "license": "MIT",
+      "dependencies": {
+        "emoji-regex": "^10.3.0",
+        "get-east-asian-width": "^1.0.0",
+        "strip-ansi": "^7.1.0"
+      },
+      "engines": {
+        "node": ">=18"
+      },
+      "funding": {
+        "url": "https://github.com/sponsors/sindresorhus"
+      }
+    },
+    "node_modules/strip-ansi": {
+      "version": "7.2.0",
+      "resolved": "https://registry.npmjs.org/strip-ansi/-/strip-ansi-7.2.0.tgz",
+      "integrity": "sha512-yDPMNjp4WyfYBkHnjIRLfca1i6KMyGCtsVgoKe/z1+6vukgaENdgGBZt+ZmKPc4gavvEZ5OgHfHdrazhgNyG7w==",
+      "license": "MIT",
+      "dependencies": {
+        "ansi-regex": "^6.2.2"
+      },
+      "engines": {
+        "node": ">=12"
+      },
+      "funding": {
+        "url": "https://github.com/chalk/strip-ansi?sponsor=1"
+      }
+    },
+    "node_modules/strip-json-comments": {
+      "version": "5.0.3",
+      "resolved": "https://registry.npmjs.org/strip-json-comments/-/strip-json-comments-5.0.3.tgz",
+      "integrity": "sha512-1tB5mhVo7U+ETBKNf92xT4hrQa3pm0MZ0PQvuDnWgAAGHDsfp4lPSpiS6psrSiet87wyGPh9ft6wmhOMQ0hDiw==",
+      "license": "MIT",
+      "engines": {
+        "node": ">=14.16"
+      },
+      "funding": {
+        "url": "https://github.com/sponsors/sindresorhus"
+      }
+    },
+    "node_modules/thread-stream": {
+      "version": "4.0.0",
+      "resolved": "https://registry.npmjs.org/thread-stream/-/thread-stream-4.0.0.tgz",
+      "integrity": "sha512-4iMVL6HAINXWf1ZKZjIPcz5wYaOdPhtO8ATvZ+Xqp3BTdaqtAwQkNmKORqcIo5YkQqGXq5cwfswDwMqqQNrpJA==",
+      "license": "MIT",
+      "dependencies": {
+        "real-require": "^0.2.0"
+      },
+      "engines": {
+        "node": ">=20"
+      }
+    },
+    "node_modules/tmp": {
+      "version": "0.2.7",
+      "resolved": "https://registry.npmjs.org/tmp/-/tmp-0.2.7.tgz",
+      "integrity": "sha512-e0votIpp4Uo2AJYSzVHV6xCcawuiez3DzqDAbrTc3YxBkplN6e+dM13ZeIcZnDg/QpSuU2zfZ3rzwY8ukEnaXw==",
+      "license": "MIT",
+      "engines": {
+        "node": ">=14.14"
+      }
+    },
+    "node_modules/tsx": {
+      "version": "4.23.11",
+      "resolved": "https://registry.npmjs.org/tsx/-/tsx-4.23.11.tgz",
+      "integrity": "sha512-Ry2oTEUnhBdeEdWIztY8kf3/nBGnPnjMLVGL0YfdRXMORuPER5NlKmayqxtxRxwB1xBN+RivRaJfe7PM1rtiyw==",
+      "license": "MIT",
+      "dependencies": {
+        "esbuild": "~0.28.0"
+      },
+      "bin": {
+        "tsx": "dist/cli.mjs"
+      },
+      "engines": {
+        "node": ">=18.0.0"
+      },
+      "optionalDependencies": {
+        "fsevents": "~2.3.3"
+      }
+    },
+    "node_modules/typescript": {
+      "version": "7.0.2",
+      "resolved": "https://registry.npmjs.org/typescript/-/typescript-7.0.2.tgz",
+      "integrity": "sha512-8FYau96o3NKOhbjKi/qNvG/W5jhzxkbdm5sj9AbZ/5T5sWqn3hJgLfGx27sRKZWTvyzCP8dLRBTf5tBTSRVUNA==",
+      "license": "Apache-2.0",
+      "bin": {
+        "tsc": "bin/tsc"
+      },
+      "engines": {
+        "node": ">=16.20.0"
+      },
+      "optionalDependencies": {
+        "@typescript/typescript-aix-ppc64": "7.0.2",
+        "@typescript/typescript-darwin-arm64": "7.0.2",
+        "@typescript/typescript-darwin-x64": "7.0.2",
+        "@typescript/typescript-freebsd-arm64": "7.0.2",
+        "@typescript/typescript-freebsd-x64": "7.0.2",
+        "@typescript/typescript-linux-arm": "7.0.2",
+        "@typescript/typescript-linux-arm64": "7.0.2",
+        "@typescript/typescript-linux-loong64": "7.0.2",
+        "@typescript/typescript-linux-mips64el": "7.0.2",
+        "@typescript/typescript-linux-ppc64": "7.0.2",
+        "@typescript/typescript-linux-riscv64": "7.0.2",
+        "@typescript/typescript-linux-s390x": "7.0.2",
+        "@typescript/typescript-linux-x64": "7.0.2",
+        "@typescript/typescript-netbsd-arm64": "7.0.2",
+        "@typescript/typescript-netbsd-x64": "7.0.2",
+        "@typescript/typescript-openbsd-arm64": "7.0.2",
+        "@typescript/typescript-openbsd-x64": "7.0.2",
+        "@typescript/typescript-sunos-x64": "7.0.2",
+        "@typescript/typescript-win32-arm64": "7.0.2",
+        "@typescript/typescript-win32-x64": "7.0.2"
+      }
+    },
+    "node_modules/uglify-js": {
+      "version": "3.19.3",
+      "resolved": "https://registry.npmjs.org/uglify-js/-/uglify-js-3.19.3.tgz",
+      "integrity": "sha512-v3Xu+yuwBXisp6QYTcH4UbH+xYJXqnq2m/LtQVWKWzYc1iehYnLixoQDN9FH6/j9/oybfd6W9Ghwkl8+UMKTKQ==",
+      "license": "BSD-2-Clause",
+      "optional": true,
+      "bin": {
+        "uglifyjs": "bin/uglifyjs"
+      },
+      "engines": {
+        "node": ">=0.8.0"
+      }
+    },
+    "node_modules/undici": {
+      "version": "7.29.0",
+      "resolved": "https://registry.npmjs.org/undici/-/undici-7.29.0.tgz",
+      "integrity": "sha512-IDxfleLmmbSskfWSUATiN1nfn2rDuvnMOqb5CWR92iIfojA0Ud+ulOAAEQ57LPr9rWmsreUyf5lwyao+7GNNVw==",
+      "license": "MIT",
+      "engines": {
+        "node": ">=20.18.1"
+      }
+    },
+    "node_modules/undici-types": {
+      "version": "7.18.2",
+      "resolved": "https://registry.npmjs.org/undici-types/-/undici-types-7.18.2.tgz",
+      "integrity": "sha512-AsuCzffGHJybSaRrmr5eHr81mwJU3kjw6M+uprWvCXiNeN9SOGwQ3Jn8jb8m3Z6izVgknn1R0FTCEAP2QrLY/w==",
+      "license": "MIT"
+    },
+    "node_modules/web-streams-polyfill": {
+      "version": "3.3.3",
+      "resolved": "https://registry.npmjs.org/web-streams-polyfill/-/web-streams-polyfill-3.3.3.tgz",
+      "integrity": "sha512-d2JWLCivmZYTSIoge9MsgFCZrt571BikcWGYkjC1khllbTeDlGqZ2D8vD8E/lJa8WGWbb7Plm8/XJYV7IJHZZw==",
+      "license": "MIT",
+      "engines": {
+        "node": ">= 8"
+      }
+    },
+    "node_modules/wordwrap": {
+      "version": "1.0.0",
+      "resolved": "https://registry.npmjs.org/wordwrap/-/wordwrap-1.0.0.tgz",
+      "integrity": "sha512-gvVzJFlPycKc5dZN4yPkP8w7Dc37BtP1yczEneOb4uq34pXZcvrtRTmWV8W+Ume+XCxKgbjM+nevkyFPMybd4Q==",
+      "license": "MIT"
+    },
+    "node_modules/wrap-ansi": {
+      "version": "9.0.2",
+      "resolved": "https://registry.npmjs.org/wrap-ansi/-/wrap-ansi-9.0.2.tgz",
+      "integrity": "sha512-42AtmgqjV+X1VpdOfyTGOYRi0/zsoLqtXQckTmqTeybT+BDIbM/Guxo7x3pE2vtpr1ok6xRqM9OpBe+Jyoqyww==",
+      "license": "MIT",
+      "dependencies": {
+        "ansi-styles": "^6.2.1",
+        "string-width": "^7.0.0",
+        "strip-ansi": "^7.1.0"
+      },
+      "engines": {
+        "node": ">=18"
+      },
+      "funding": {
+        "url": "https://github.com/chalk/wrap-ansi?sponsor=1"
+      }
+    },
+    "node_modules/wrappy": {
+      "version": "1.0.2",
+      "resolved": "https://registry.npmjs.org/wrappy/-/wrappy-1.0.2.tgz",
+      "integrity": "sha512-l4Sp/DRseor9wL6EvV2+TuQn63dMkPjZ/sp9XkghTEbV9KlPS1xUsZ3u7/IQO4wxtcFB4bgpQPRcR3QCvezPcQ==",
+      "license": "ISC"
+    },
+    "node_modules/y18n": {
+      "version": "5.0.8",
+      "resolved": "https://registry.npmjs.org/y18n/-/y18n-5.0.8.tgz",
+      "integrity": "sha512-0pfFzegeDWJHJIAmTLRP2DwHjdF5s7jo9tuztdQxAhINCdvS+3nGINqPd00AphqJR/0LhANUS6/+7SCb98YOfA==",
+      "license": "ISC",
+      "engines": {
+        "node": ">=10"
+      }
+    },
+    "node_modules/yaml": {
+      "version": "2.9.0",
+      "resolved": "https://registry.npmjs.org/yaml/-/yaml-2.9.0.tgz",
+      "integrity": "sha512-2AvhNX3mb8zd6Zy7INTtSpl1F15HW6Wnqj0srWlkKLcpYl/gMIMJiyuGq2KeI2YFxUPjdlB+3Lc10seMLtL4cA==",
+      "license": "ISC",
+      "bin": {
+        "yaml": "bin.mjs"
+      },
+      "engines": {
+        "node": ">= 14.6"
+      },
+      "funding": {
+        "url": "https://github.com/sponsors/eemeli"
+      }
+    },
+    "node_modules/yargs": {
+      "version": "18.1.0",
+      "resolved": "https://registry.npmjs.org/yargs/-/yargs-18.1.0.tgz",
+      "integrity": "sha512-2rAgRKu54VsHkqI0/tYkmluGXHD4KW7yZoycuqDQ15QOTnc2VVfy0nN/1eMhnQLO00A+dwtK20xuCnc1YGeUyg==",
+      "license": "MIT",
+      "dependencies": {
+        "cliui": "^9.0.1",
+        "escalade": "^3.1.1",
+        "get-caller-file": "^2.0.5",
+        "string-width": "^8.2.1",
+        "y18n": "^5.0.5",
+        "yargs-parser": "^22.0.0"
+      },
+      "engines": {
+        "node": "^20.19.0 || ^22.12.0 || >=23"
+      }
+    },
+    "node_modules/yargs-parser": {
+      "version": "22.0.0",
+      "resolved": "https://registry.npmjs.org/yargs-parser/-/yargs-parser-22.0.0.tgz",
+      "integrity": "sha512-rwu/ClNdSMpkSrUb+d6BRsSkLUq1fmfsY6TOpYzTwvwkg1/NRG85KBy3kq++A8LKQwX6lsu+aWad+2khvuXrqw==",
+      "license": "ISC",
+      "engines": {
+        "node": "^20.19.0 || ^22.12.0 || >=23"
+      }
+    },
+    "node_modules/yargs/node_modules/string-width": {
+      "version": "8.2.2",
+      "resolved": "https://registry.npmjs.org/string-width/-/string-width-8.2.2.tgz",
+      "integrity": "sha512-GaPUh5gfdrYzqeVNZvUfT23vYYxXzKYidUcnMtJg/3rxRV63EFZy3k6xfKlmfeJD0176lnUV/Usr3XcwSvFzpg==",
+      "license": "MIT",
+      "dependencies": {
+        "get-east-asian-width": "^1.5.0",
+        "strip-ansi": "^7.1.2"
+      },
+      "engines": {
+        "node": ">=20"
+      },
+      "funding": {
+        "url": "https://github.com/sponsors/sindresorhus"
+      }
+    },
+    "node_modules/yocto-queue": {
+      "version": "1.2.2",
+      "resolved": "https://registry.npmjs.org/yocto-queue/-/yocto-queue-1.2.2.tgz",
+      "integrity": "sha512-4LCcse/U2MHZ63HAJVE+v71o7yOdIe4cZ70Wpf8D/IyjDKYQLV5GD46B+hSTjJsvV5PztjvHoU580EftxjDZFQ==",
+      "license": "MIT",
+      "engines": {
+        "node": ">=12.20"
+      },
+      "funding": {
+        "url": "https://github.com/sponsors/sindresorhus"
+      }
+    },
+    "node_modules/zod": {
+      "version": "4.4.3",
+      "resolved": "https://registry.npmjs.org/zod/-/zod-4.4.3.tgz",
+      "integrity": "sha512-ytENFjIJFl2UwYglde2jchW2Hwm4GJFLDiSXWdTrJQBIN9Fcyp7n4DhxJEiWNAJMV1/BqWfW/kkg71UDcHJyTQ==",
+      "license": "MIT",
+      "funding": {
+        "url": "https://github.com/sponsors/colinhacks"
+      }
+    }
+  }
+}

package.json

@@ -0,0 +1,37 @@
+{
+  "name": "forge-code-evals",
+  "private": true,
+  "version": "1.0.0",
+  "description": "",
+  "license": "ISC",
+  "author": "Tushar Mathur <tusharmath@gmail.com>",
+  "type": "module",
+  "scripts": {
+    "eval": "tsx benchmarks/cli.ts",
+    "test:bounty": "tsx --test .github/scripts/bounty/tests/*.test.ts",
+    "bounty:sync-issue": "tsx .github/scripts/bounty/src/sync-issue.ts",
+    "bounty:sync-pr": "tsx .github/scripts/bounty/src/sync-pr.ts",
+    "bounty:sync-all-issues": "tsx .github/scripts/bounty/src/sync-all-issues.ts"
+  },
+  "dependencies": {
+    "@ai-sdk/google-vertex": "^5.0.0",
+    "@types/handlebars": "^4.0.40",
+    "@types/node": "^24.10.1",
+    "@types/tmp": "^0.2.6",
+    "@types/yargs": "^17.0.35",
+    "ai": "^7.0.0",
+    "chalk": "^6.0.0",
+    "csv-parse": "^7.0.0",
+    "handlebars": "^4.7.9",
+    "p-limit": "^7.2.0",
+    "pino": "^10.1.0",
+    "pino-pretty": "^13.1.2",
+    "strip-ansi": "^7.1.2",
+    "tmp": "^0.2.5",
+    "tsx": "^4.20.6",
+    "typescript": "^7.0.0",
+    "yaml": "^2.8.3",
+    "yargs": "^18.0.0",
+    "zod": "^4.0.0"
+  }
+}

plans/2025-04-02-system-context-rendering-final.md

@@ -0,0 +1,344 @@
+# Dynamic System Context Rendering with Variables
+
+## Objective
+
+Modify the system context rendering mechanism to:
+
+
+1. Re-render the system context on every conversation turn
+2. Pass variables to the system context renderer (similar to event rendering)
+
+The current implementation renders the system context only once during agent initialization, which means time-sensitive information like `current_time` is not updated. Additionally, the system context cannot use dynamic variables from the conversation state.
+
+## Implementation Plan
+
+### 1. Update TemplateService Trait
+
+Modify the `TemplateService` trait in `crates/forge_domain/src/services.rs` to include variables in the `render_system` method signature:
+
+```rust
+async fn render_system(
+    &self,
+    agent: &Agent,
+    prompt: &Template<SystemContext>,
+    variables: &HashMap<String, Value>,
+) -> anyhow::Result<String>;
+```
+
+### 2. Modify ForgeTemplateService Implementation
+
+Update the implementation in `crates/forge_services/src/template.rs` to handle variables in system context rendering:
+
+```rust
+async fn render_system(
+    &self,
+    _agent: &Agent,
+    prompt: &Template<SystemContext>,
+    variables: &HashMap<String, Value>,
+) -> anyhow::Result<String> {
+    let env = self.infra.environment_service().get_environment();
+
+    // Build the walker, only setting max_depth if a value was provided
+    let mut walker = Walker::max_all();
+
+    // Only set max_depth if the value is provided
+    // Create maximum depth for file walker, defaulting to 1 if not specified
+    walker = walker.max_depth(_agent.max_walker_depth.unwrap_or(1));
+
+    let mut files = walker
+        .cwd(env.cwd.clone())
+        .get()
+        .await?
+        .iter()
+        .map(|f| f.path.to_string())
+        .collect::<Vec<_>>();
+
+    // Sort the files alphabetically to ensure consistent ordering
+    files.sort();
+
+    // Get current date and time with timezone
+    let current_time = Local::now().format("%Y-%m-%d %H:%M:%S %:z").to_string();
+
+    // Create the context with README content for all agents
+    let ctx = SystemContext {
+        current_time,
+        env: Some(env),
+        tool_information: Some(self.tool_service.usage_prompt()),
+        tool_supported: _agent.tool_supported.unwrap_or_default(),
+        files,
+        readme: README_CONTENT.to_string(),
+        custom_rules: _agent.custom_rules.as_ref().cloned().unwrap_or_default(),
+        variables: variables.clone(), // Add the variables
+    };
+
+    // Render the template with the context
+    let result = self.hb.render_template(prompt.template.as_str(), &ctx)?;
+    Ok(result)
+}
+```
+
+### 3. Update SystemContext Struct
+
+Modify the `SystemContext` struct in `crates/forge_domain/src/system_context.rs` to include variables:
+
+```rust
+#[derive(Debug, Setters, Clone, Serialize, Deserialize)]
+#[setters(strip_option)]
+pub struct SystemContext {
+    // Current date and time at the time of context creation
+    pub current_time: String,
+    
+    // Environment information to be included in the system context
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub env: Option<Environment>,
+
+    // Information about available tools that can be used by the agent
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub tool_information: Option<String>,
+
+    /// Indicates whether the agent supports tools.
+    /// This value is populated directly from the Agent configuration.
+    #[serde(default)]
+    pub tool_supported: bool,
+
+    // List of file paths that are relevant for the agent context
+    #[serde(skip_serializing_if = "Vec::is_empty")]
+    pub files: Vec<String>,
+
+    // README content to provide project context to the agent
+    pub readme: String,
+
+    #[serde(skip_serializing_if = "String::is_empty")]
+    pub custom_rules: String,
+    
+    // Variables to pass to the system context
+    #[serde(default, skip_serializing_if = "HashMap::is_empty")]
+    pub variables: HashMap<String, Value>,
+}
+
+// Update the Default implementation if it exists
+impl Default for SystemContext {
+    fn default() -> Self {
+        Self {
+            current_time: String::new(),
+            env: None,
+            tool_information: None,
+            tool_supported: false,
+            files: Vec::new(),
+            readme: String::new(),
+            custom_rules: String::new(),
+            variables: HashMap::new(),
+        }
+    }
+}
+```
+
+### 4. Update Orchestrator to Re-render System Context
+
+Modify the orchestrator's conversation loop in `crates/forge_domain/src/orch.rs` to re-render the system context on each iteration:
+
+```rust
+async fn init_agent(&self, agent_id: &AgentId, event: &Event) -> anyhow::Result<()> {
+    let conversation = self.get_conversation().await?;
+    debug!(
+        conversation_id = %conversation.id,
+        agent = %agent_id,
+        event = ?event,
+        "Initializing agent"
+    );
+    let agent = conversation.workflow.get_agent(agent_id)?;
+
+    let mut context = if agent.ephemeral.unwrap_or_default() {
+        self.init_agent_context(agent).await?
+    } else {
+        match conversation.context(&agent.id) {
+            Some(context) => context.clone(),
+            None => self.init_agent_context(agent).await?,
+        }
+    };
+
+    if let Some(temperature) = agent.temperature {
+        context = context.temperature(temperature);
+    }
+
+    let content = if let Some(user_prompt) = &agent.user_prompt {
+        // Get conversation variables from the conversation
+        let variables = &conversation.variables;
+
+        // Use the consolidated render_event method which handles suggestions and
+        // variables
+        self.services
+            .template_service()
+            .render_event(agent, user_prompt, event, variables)
+            .await?
+    } else {
+        // Use the raw event value as content if no user_prompt is provided
+        event.value.to_string()
+    };
+
+    if !content.is_empty() {
+        context = context.add_message(ContextMessage::user(content));
+    }
+
+    // Process attachments
+    let attachments = self
+        .services
+        .attachment_service()
+        .attachments(&event.value.to_string())
+        .await?;
+
+    for attachment in attachments.into_iter() {
+        match attachment.content_type {
+            ContentType::Image => {
+                context = context.add_message(ContextMessage::Image(attachment.content));
+            }
+            ContentType::Text => {
+                let content = format!(
+                    "<file_content path=\"{}\">{}</file_content>",
+                    attachment.path, attachment.content
+                );
+                context = context.add_message(ContextMessage::user(content));
+            }
+        }
+    }
+
+    self.set_context(&agent.id, context.clone()).await?;
+
+    loop {
+        // Get the latest conversation variables
+        let variables = self.conversation.read().await.variables.clone();
+        
+        // Re-render system prompt if present
+        if let Some(system_prompt) = &agent.system_prompt {
+            let system_message = self
+                .services
+                .template_service()
+                .render_system(agent, system_prompt, &variables)
+                .await?;
+                
+            context = context.set_first_system_message(system_message);
+        }
+        
+        // Set context for the current loop iteration
+        self.set_context(&agent.id, context.clone()).await?;
+        let response = self
+            .services
+            .provider_service()
+            .chat(
+                agent
+                    .model
+                    .as_ref()
+                    .ok_or(Error::MissingModel(agent.id.clone()))?,
+                context.clone(),
+            )
+            .await?;
+        let ChatCompletionResult { tool_calls, content } =
+            self.collect_messages(agent, response).await?;
+
+        // Get all tool results using the helper function
+        let tool_results = self.get_all_tool_results(agent, &tool_calls).await?;
+
+        context = context
+            .add_message(ContextMessage::assistant(content, Some(tool_calls)))
+            .add_tool_results(tool_results.clone());
+
+        // Check if context requires compression
+        context = self.compactor.compact_context(agent, context).await?;
+
+        self.set_context(&agent.id, context.clone()).await?;
+        self.sync_conversation().await?;
+
+        if tool_results.is_empty() {
+            break;
+        }
+    }
+
+    self.complete_turn(&agent.id).await?;
+
+    self.sync_conversation().await?;
+
+    Ok(())
+}
+```
+
+### 5. Update Tests
+
+Add tests for the updated `render_system` method with variables:
+
+```rust
+// In forge_services/src/template.rs or a test file
+#[tokio::test]
+async fn test_render_system_with_variables() {
+    // Create a test agent
+    let agent = Agent::new("test-agent")
+        .system_prompt(Template::from_string("{{current_time}} - {{variables.test_var}}"));
+    
+    // Create test variables
+    let mut variables = HashMap::new();
+    variables.insert("test_var".to_string(), json!("test_value"));
+    
+    // Render the system prompt with variables
+    let result = template_service
+        .render_system(&agent, agent.system_prompt.as_ref().unwrap(), &variables)
+        .await
+        .unwrap();
+    
+    // Verify the result contains both the current time and the variable
+    assert!(result.contains("test_value"));
+}
+```
+
+### 6. Update init_agent_context Method
+
+Also need to update the `init_agent_context` method in `crates/forge_domain/src/orch.rs` to pass empty variables:
+
+```rust
+async fn init_agent_context(&self, agent: &Agent) -> anyhow::Result<Context> {
+    let tool_defs = self.init_tool_definitions(agent);
+
+    // Use the agent's tool_supported flag directly instead of querying the provider
+    let tool_supported = agent.tool_supported.unwrap_or_default();
+
+    let mut context = Context::default();
+
+    if let Some(system_prompt) = &agent.system_prompt {
+        // Create empty variables for initial rendering
+        let empty_variables = HashMap::new();
+        
+        let system_message = self
+            .services
+            .template_service()
+            .render_system(agent, system_prompt, &empty_variables)
+            .await?;
+
+        context = context.set_first_system_message(system_message);
+    }
+
+    Ok(context.extend_tools(if tool_supported {
+        tool_defs
+    } else {
+        Vec::new()
+    }))
+}
+```
+
+## Verification Criteria
+
+The implementation will be considered successful if:
+
+
+1. The system context is re-rendered on each conversation turn, ensuring up-to-date information
+2. Variables from the conversation state are correctly passed to the system context renderer
+3. System context templates can access and display these variables (templates have already been modified)
+4. All tests pass with the new implementation
+5. The code is clean, without unnecessary backward compatibility layers
+
+## Technical Design Notes
+
+
+1. **Clean Approach**: The implementation takes a clean approach without backward compatibility concerns, as specified.
+2. **Performance**: Re-rendering the system context on each turn should not cause performance issues.
+3. **Consistency**: The approach aligns with how event rendering already handles variables.
+4. **Error Handling**: Proper error handling is maintained throughout the implementation.
+
+

plans/2025-04-02-system-context-rendering-v1.md

@@ -0,0 +1,171 @@
+# Dynamic System Context Rendering with Variables
+
+## Objective
+
+Modify the system context rendering mechanism to:
+
+
+1. Re-render the system context on every conversation turn
+2. Pass variables to the system context renderer (similar to event rendering)
+
+The current implementation renders the system context only once during agent initialization, which means time-sensitive information like `current_time` is not updated. Additionally, the system context cannot use dynamic variables from the conversation state.
+
+## Implementation Plan
+
+### 1. Update TemplateService Trait
+
+Modify the `TemplateService` trait in `crates/forge_domain/src/services.rs` to include variables in the `render_system` method signature:
+
+```rust
+async fn render_system(
+    &self,
+    agent: &Agent,
+    prompt: &Template<SystemContext>,
+    variables: &HashMap<String, Value>,
+) -> anyhow::Result<String>;
+```
+
+### 2. Modify ForgeTemplateService Implementation
+
+Update the implementation in `crates/forge_services/src/template.rs` to handle variables in system context rendering:
+
+```rust
+async fn render_system(
+    &self,
+    _agent: &Agent,
+    prompt: &Template<SystemContext>,
+    variables: &HashMap<String, Value>,
+) -> anyhow::Result<String> {
+    // Existing code...
+    
+    // Create the context with README content for all agents
+    let mut ctx = SystemContext {
+        current_time,
+        env: Some(env),
+        tool_information: Some(self.tool_service.usage_prompt()),
+        tool_supported: _agent.tool_supported.unwrap_or_default(),
+        files,
+        readme: README_CONTENT.to_string(),
+        custom_rules: _agent.custom_rules.as_ref().cloned().unwrap_or_default(),
+        variables: variables.clone(), // Add the variables
+    };
+    
+    // Render the template with the context and variables
+    let result = self.hb.render_template(prompt.template.as_str(), &ctx)?;
+    Ok(result)
+}
+```
+
+### 3. Update SystemContext Struct
+
+Modify the `SystemContext` struct in `crates/forge_domain/src/system_context.rs` to include variables:
+
+```rust
+#[derive(Debug, Setters, Clone, Serialize, Deserialize)]
+#[setters(strip_option)]
+pub struct SystemContext {
+    // Existing fields...
+    
+    // Variables passed to the template
+    #[serde(skip_serializing_if = "HashMap::is_empty")]
+    pub variables: HashMap<String, Value>,
+}
+```
+
+### 4. Update Orchestrator to Re-render System Context
+
+Modify the orchestrator's conversation loop in `crates/forge_domain/src/orch.rs` to re-render the system context on each iteration:
+
+```rust
+async fn init_agent(&self, agent_id: &AgentId, event: &Event) -> anyhow::Result<()> {
+    // Existing code...
+    
+    loop {
+        // Get up-to-date variables
+        let conversation_vars = self.conversation.read().await.variables.clone();
+        
+        // Re-render the system message if system_prompt is present
+        if let Some(system_prompt) = &agent.system_prompt {
+            let system_message = self
+                .services
+                .template_service()
+                .render_system(agent, system_prompt, &conversation_vars)
+                .await?;
+
+            // Update the system message in the context
+            context = context.set_first_system_message(system_message);
+        }
+        
+        // Set context for the current loop iteration
+        self.set_context(&agent.id, context.clone()).await?;
+        
+        // Existing loop code...
+        
+        // If no tool results, break the loop as before
+        if tool_results.is_empty() {
+            break;
+        }
+    }
+    
+    // Existing code...
+}
+```
+
+### 5. Update System Context Templates
+
+Ensure the templates can use variables from the context:
+
+In `templates/forge-partial-system-info.hbs` and other system templates, add support for variables:
+
+```handlebars
+<system_info>
+<operating_system>{{env.os}}</operating_system>
+<current_time>{{current_time}}</current_time>
+<current_working_directory>{{env.cwd}}</current_working_directory>
+<default_shell>{{env.shell}}</default_shell>
+<home_directory>{{env.home}}</home_directory>
+<file_list>
+{{#each files}} - {{this}}
+{{/each}}
+</file_list>
+</system_info>
+
+{{!-- Add access to variables --}}
+{{#if variables}}
+<variables>
+{{#each variables}}
+<{{@key}}>{{this}}</{{@key}}>
+{{/each}}
+</variables>
+{{/if}}
+```
+
+### 6. Update Tests
+
+Update relevant tests to verify the changes:
+
+
+1. Add tests for the updated `render_system` method with variables
+2. Ensure the system context is properly updated in the orchestrator tests
+3. Verify that templates can correctly access variables in the system context
+
+## Verification Criteria
+
+The implementation will be considered successful if:
+
+
+1. The system context is re-rendered on each conversation turn, with up-to-date `current_time`
+2. Variables from the conversation state are correctly passed to the system context renderer
+3. System context templates can access and display these variables
+4. All tests pass with the new implementation
+5. The overall API remains consistent with the existing paradigm
+
+## Technical Design Notes
+
+
+1. **Backward Compatibility**: The implementation should maintain backward compatibility with existing templates by making variables optional.
+2. **Performance**: Re-rendering the system context on each turn is not expected to cause performance issues, as confirmed.
+3. **Consistency**: The approach aligns with how event rendering already handles variables.
+4. **Error Handling**: Proper error handling should be maintained throughout the implementation.
+
+

plans/2025-04-02-system-context-rendering-v2.md

@@ -0,0 +1,315 @@
+# Dynamic System Context Rendering with Variables
+
+## Objective
+
+Modify the system context rendering mechanism to:
+
+
+
+
+1. Re-render the system context on every conversation turn
+2. Pass variables to the system context renderer (similar to event rendering)
+
+The current implementation renders the system context only once during agent initialization, which means time-sensitive information like `current_time` is not updated. Additionally, the system context cannot use dynamic variables from the conversation state.
+
+## Implementation Plan
+
+### 1. Update TemplateService Trait
+
+Modify the `TemplateService` trait in `crates/forge_domain/src/services.rs` to include variables in the `render_system` method signature:
+
+```rust
+async fn render_system(
+    &self,
+    agent: &Agent,
+    prompt: &Template<SystemContext>,
+    variables: &HashMap<String, Value>,
+) -> anyhow::Result<String>;
+```
+
+### 2. Modify ForgeTemplateService Implementation
+
+Update the implementation in `crates/forge_services/src/template.rs` to handle variables in system context rendering:
+
+```rust
+async fn render_system(
+    &self,
+    _agent: &Agent,
+    prompt: &Template<SystemContext>,
+    variables: &HashMap<String, Value>,
+) -> anyhow::Result<String> {
+    let env = self.infra.environment_service().get_environment();
+
+    // Build the walker, only setting max_depth if a value was provided
+    let mut walker = Walker::max_all();
+
+    // Only set max_depth if the value is provided
+    // Create maximum depth for file walker, defaulting to 1 if not specified
+    walker = walker.max_depth(_agent.max_walker_depth.unwrap_or(1));
+
+    let mut files = walker
+        .cwd(env.cwd.clone())
+        .get()
+        .await?
+        .iter()
+        .map(|f| f.path.to_string())
+        .collect::<Vec<_>>();
+
+    // Sort the files alphabetically to ensure consistent ordering
+    files.sort();
+
+    // Get current date and time with timezone
+    let current_time = Local::now().format("%Y-%m-%d %H:%M:%S %:z").to_string();
+
+    // Create the context with README content for all agents
+    let ctx = SystemContext {
+        current_time,
+        env: Some(env),
+        tool_information: Some(self.tool_service.usage_prompt()),
+        tool_supported: _agent.tool_supported.unwrap_or_default(),
+        files,
+        readme: README_CONTENT.to_string(),
+        custom_rules: _agent.custom_rules.as_ref().cloned().unwrap_or_default(),
+        variables: variables.clone(), // Add the variables
+    };
+
+    // Render the template with the context
+    let result = self.hb.render_template(prompt.template.as_str(), &ctx)?;
+    Ok(result)
+}
+```
+
+### 3. Update SystemContext Struct
+
+Modify the `SystemContext` struct in `crates/forge_domain/src/system_context.rs` to include variables:
+
+```rust
+#[derive(Debug, Setters, Clone, Serialize, Deserialize)]
+#[setters(strip_option)]
+pub struct SystemContext {
+    // Current date and time at the time of context creation
+    pub current_time: String,
+    
+    // Environment information to be included in the system context
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub env: Option<Environment>,
+
+    // Information about available tools that can be used by the agent
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub tool_information: Option<String>,
+
+    /// Indicates whether the agent supports tools.
+    /// This value is populated directly from the Agent configuration.
+    #[serde(default)]
+    pub tool_supported: bool,
+
+    // List of file paths that are relevant for the agent context
+    #[serde(skip_serializing_if = "Vec::is_empty")]
+    pub files: Vec<String>,
+
+    // README content to provide project context to the agent
+    pub readme: String,
+
+    #[serde(skip_serializing_if = "String::is_empty")]
+    pub custom_rules: String,
+    
+    // Variables to pass to the system context
+    #[serde(default, skip_serializing_if = "HashMap::is_empty")]
+    pub variables: HashMap<String, Value>,
+}
+
+// Update the Default implementation if it exists
+impl Default for SystemContext {
+    fn default() -> Self {
+        Self {
+            current_time: String::new(),
+            env: None,
+            tool_information: None,
+            tool_supported: false,
+            files: Vec::new(),
+            readme: String::new(),
+            custom_rules: String::new(),
+            variables: HashMap::new(),
+        }
+    }
+}
+```
+
+### 4. Update Orchestrator to Re-render System Context
+
+Modify the orchestrator's conversation loop in `crates/forge_domain/src/orch.rs` to re-render the system context on each iteration:
+
+```rust
+async fn init_agent(&self, agent_id: &AgentId, event: &Event) -> anyhow::Result<()> {
+    let conversation = self.get_conversation().await?;
+    debug!(
+        conversation_id = %conversation.id,
+        agent = %agent_id,
+        event = ?event,
+        "Initializing agent"
+    );
+    let agent = conversation.workflow.get_agent(agent_id)?;
+
+    let mut context = if agent.ephemeral.unwrap_or_default() {
+        self.init_agent_context(agent).await?
+    } else {
+        match conversation.context(&agent.id) {
+            Some(context) => context.clone(),
+            None => self.init_agent_context(agent).await?,
+        }
+    };
+
+    if let Some(temperature) = agent.temperature {
+        context = context.temperature(temperature);
+    }
+
+    let content = if let Some(user_prompt) = &agent.user_prompt {
+        // Get conversation variables from the conversation
+        let variables = &conversation.variables;
+
+        // Use the consolidated render_event method which handles suggestions and
+        // variables
+        self.services
+            .template_service()
+            .render_event(agent, user_prompt, event, variables)
+            .await?
+    } else {
+        // Use the raw event value as content if no user_prompt is provided
+        event.value.to_string()
+    };
+
+    if !content.is_empty() {
+        context = context.add_message(ContextMessage::user(content));
+    }
+
+    // Process attachments
+    let attachments = self
+        .services
+        .attachment_service()
+        .attachments(&event.value.to_string())
+        .await?;
+
+    for attachment in attachments.into_iter() {
+        match attachment.content_type {
+            ContentType::Image => {
+                context = context.add_message(ContextMessage::Image(attachment.content));
+            }
+            ContentType::Text => {
+                let content = format!(
+                    "<file_content path=\"{}\">{}</file_content>",
+                    attachment.path, attachment.content
+                );
+                context = context.add_message(ContextMessage::user(content));
+            }
+        }
+    }
+
+    self.set_context(&agent.id, context.clone()).await?;
+
+    loop {
+        // Get the latest conversation variables
+        let variables = self.conversation.read().await.variables.clone();
+        
+        // Re-render system prompt if present
+        if let Some(system_prompt) = &agent.system_prompt {
+            let system_message = self
+                .services
+                .template_service()
+                .render_system(agent, system_prompt, &variables)
+                .await?;
+                
+            context = context.set_first_system_message(system_message);
+        }
+        
+        // Set context for the current loop iteration
+        self.set_context(&agent.id, context.clone()).await?;
+        let response = self
+            .services
+            .provider_service()
+            .chat(
+                agent
+                    .model
+                    .as_ref()
+                    .ok_or(Error::MissingModel(agent.id.clone()))?,
+                context.clone(),
+            )
+            .await?;
+        let ChatCompletionResult { tool_calls, content } =
+            self.collect_messages(agent, response).await?;
+
+        // Get all tool results using the helper function
+        let tool_results = self.get_all_tool_results(agent, &tool_calls).await?;
+
+        context = context
+            .add_message(ContextMessage::assistant(content, Some(tool_calls)))
+            .add_tool_results(tool_results.clone());
+
+        // Check if context requires compression
+        context = self.compactor.compact_context(agent, context).await?;
+
+        self.set_context(&agent.id, context.clone()).await?;
+        self.sync_conversation().await?;
+
+        if tool_results.is_empty() {
+            break;
+        }
+    }
+
+    self.complete_turn(&agent.id).await?;
+
+    self.sync_conversation().await?;
+
+    Ok(())
+}
+```
+
+
+### 5. Update Tests
+
+Add tests for the updated `render_system` method with variables:
+
+```rust
+// In forge_services/src/template.rs or a test file
+#[tokio::test]
+async fn test_render_system_with_variables() {
+    // Create a test agent
+    let agent = Agent::new("test-agent")
+        .system_prompt(Template::from_string("{{current_time}} - {{variables.test_var}}"));
+    
+    // Create test variables
+    let mut variables = HashMap::new();
+    variables.insert("test_var".to_string(), json!("test_value"));
+    
+    // Render the system prompt with variables
+    let result = template_service
+        .render_system(&agent, agent.system_prompt.as_ref().unwrap(), &variables)
+        .await
+        .unwrap();
+    
+    // Verify the result contains both the current time and the variable
+    assert!(result.contains("test_value"));
+}
+```
+
+## Verification Criteria
+
+The implementation will be considered successful if:
+
+
+
+1. The system context is re-rendered on each conversation turn, ensuring up-to-date information
+2. Variables from the conversation state are correctly passed to the system context renderer
+3. System context templates can access and display these variables
+4. All tests pass with the new implementation
+5. The code is clean, without unnecessary backward compatibility layers
+
+## Technical Design Notes
+
+
+
+1. **Clean Approach**: The implementation takes a clean approach without backward compatibility concerns, as specified.
+2. **Performance**: Re-rendering the system context on each turn should not cause performance issues.
+3. **Consistency**: The approach aligns with how event rendering already handles variables.
+4. **Error Handling**: Proper error handling is maintained throughout the implementation.
+
+

plans/2025-04-06-retry-config-migration.md

@@ -0,0 +1,90 @@
+# Migrating RetryConfig from Workflow to Environment with Environment Variables
+
+## Objective
+The objective is to move the retry configuration from the `Workflow` struct to the `Environment` struct and enable configuration via environment variables. This will provide flexibility and a centralized location for retry configuration that can be accessed by various components without relying on the workflow repository.
+
+## Implementation Plan
+
+### 1. Update the Environment struct
+Modify the `Environment` struct in `crates/forge_domain/src/env.rs` to include a `RetryConfig` field.
+
+```rust
+#[derive(Debug, Setters, Clone, Serialize, Deserialize)]
+#[serde(rename_all = "camelCase")]
+#[setters(strip_option)]
+pub struct Environment {
+    // Existing fields...
+    
+    /// Configuration for the retry mechanism
+    pub retry_config: RetryConfig,
+}
+```
+
+### 2. Add Environment Variable Support for Retry Configuration
+Enhance `ForgeEnvironmentService` in `crates/forge_infra/src/env.rs` to read retry configuration from environment variables:
+
+- `FORGE_RETRY_INITIAL_BACKOFF_MS` - Initial backoff delay in milliseconds
+- `FORGE_RETRY_BACKOFF_FACTOR` - Multiplication factor for each retry attempt
+- `FORGE_RETRY_MAX_ATTEMPTS` - Maximum number of retry attempts
+- `FORGE_RETRY_STATUS_CODES` - Comma-separated list of HTTP status codes that should trigger retries
+
+The service should read these variables and use them to configure the `RetryConfig` instance, falling back to default values if the environment variables are not set.
+
+### 3. Remove RetryConfig from Workflow struct
+Remove the `retry` field from the `Workflow` struct in `crates/forge_domain/src/workflow.rs`.
+
+### 4. Update ForgeProviderService
+Modify the `ForgeProviderService::new` method in `crates/forge_services/src/provider.rs` to obtain the retry configuration from the environment rather than from the workflow:
+
+```rust
+pub fn new<F: Infrastructure>(infra: Arc<F>) -> Self {
+    let infra = infra.clone();
+    let env = infra.environment_service().get_environment();
+    let provider = env.provider.clone();
+    let retry_config = env.retry_config;
+    Self {
+        client: Arc::new(Client::new(provider, retry_config).unwrap()),
+    }
+}
+```
+
+### 5. Update WorkflowRepository trait
+Update the `WorkflowRepository` trait in `crates/forge_services/src/infra.rs` to remove any references to retry configuration.
+
+### 6. Update ForgeWorkflowRepository implementation
+Modify the `ForgeWorkflowRepository` implementation in `crates/forge_infra/src/workflow.rs` to reflect the changes in the `Workflow` struct.
+
+### 7. Update tests
+Update any tests that rely on the `retry` field in the `Workflow` struct to use the new field in `Environment` instead.
+
+### 8. Update Documentation
+Update the documentation to explain how to configure retry settings using environment variables.
+
+## Verification Criteria
+
+1. The codebase should compile successfully after the changes.
+2. All tests should pass after the changes.
+3. The retry mechanism should work correctly with the configuration now sourced from the `Environment`.
+4. The retry configuration should be properly read from environment variables when they are set.
+5. Provider initialization should properly use the retry configuration from the environment.
+6. Default values should be used for retry configuration when environment variables are not set.
+
+## Potential Risks and Mitigations
+
+### Risk: Breaking existing code that accesses retry config from Workflow
+- Mitigation: Identify all locations where retry configuration is accessed from Workflow and update them to use Environment instead.
+
+### Risk: Default values for retry configuration might differ
+- Mitigation: Ensure that default values for the retry configuration are consistent between the old and new implementations.
+
+### Risk: Incomplete migration could lead to retry configuration being read from both Workflow and Environment
+- Mitigation: Thoroughly test the application to ensure retry configuration is only read from Environment after the migration.
+
+### Risk: Backward compatibility issues with existing workflows
+- Mitigation: Consider adding a compatibility layer or migration process for existing workflows that have retry configuration.
+
+### Risk: Environment variable parsing errors
+- Mitigation: Add robust error handling and validation for environment variable parsing, with clear error messages.
+
+### Risk: Missing environment variables leading to unexpected behavior
+- Mitigation: Ensure clear documentation and sensible defaults for all retry-related environment variables.

plans/2025-04-11-tool-call-context-implementation.md

@@ -0,0 +1,113 @@
+# Tool Call Context Implementation
+
+## Objective
+
+Add a required `ToolCallContext` parameter to the `ExecutableTool` trait's `call` method. This will allow for additional context to be passed to tool implementations at runtime, maintaining an extensible structure for future needs while initially keeping the context empty.
+
+## Implementation Plan
+
+
+1. Define the `ToolCallContext` struct in the domain layer
+   Priority: High
+   Complexity: Low
+   Dependencies: None
+
+   Create a new struct in `forge_domain` (likely in a new file `tool_call_context.rs`) to represent the context passed to tool calls. Initially, this will be an empty struct with the infrastructure in place for future extension.
+2. Create a helper function for test contexts
+   Priority: High
+   Complexity: Low
+   Dependencies: Step 1
+
+   Create a function to easily generate a default test context, such as `ToolCallContext::for_tests()`. This will make it simpler to update test code.
+3. Update the `ExecutableTool` trait definition
+   Priority: High
+   Complexity: Low
+   Dependencies: Step 1
+
+   Modify the trait definition in `crates/forge_domain/src/tool_definition.rs` to add the `ToolCallContext` parameter to the `call` method.
+4. Modify the `JsonTool` adapter in `forge_domain/src/tool.rs`
+   Priority: High
+   Complexity: Low
+   Dependencies: Step 3
+
+   Update the `JsonTool` adapter to pass the `ToolCallContext` to the wrapped tool's `call` method.
+5. Modify the `ToolService` implementation
+   Priority: High
+   Complexity: Medium
+   Dependencies: Step 3
+
+   Update `crates/forge_services/src/tool_service.rs` to create and pass a `ToolCallContext` when calling tools.
+6. Update all tool implementations
+   Priority: High
+   Complexity: High
+   Dependencies: Step 3
+
+   Update all implementations of `ExecutableTool` across the codebase to accept the new `ToolCallContext` parameter:
+   * Shell tool (`crates/forge_services/src/tools/shell/shell_tool.rs`)
+   * Show user tool (`crates/forge_services/src/tools/show_user.rs`)
+   * File system tools (in `crates/forge_services/src/tools/fs/`)
+   * Patch tools (in `crates/forge_services/src/tools/patch/`)
+   * Fetch tool (`crates/forge_services/src/tools/fetch.rs`)
+   * Other tools discovered during implementation
+7. Update test implementations with a systematic approach
+   Priority: High
+   Complexity: High
+   Dependencies: Steps 2, 6
+
+   Based on the analysis, there are numerous tests that implement `ExecutableTool`. Adopt the following systematic approach:
+
+   a. Create a test utility module with helper functions for creating test contexts
+   b. Update mock tool implementations in test modules:
+   * `SuccessTool` and `FailureTool` in `tool_service.rs`
+   * Test tools in filesystem modules
+   * Test tools in patch modules
+   * Any other mock implementations in test code
+     c. Update test invocations to pass the context parameter
+     d. Add context parameters to all test function calls
+8. Incremental compilation verification
+   Priority: Medium
+   Complexity: Medium
+   Dependencies: Steps 3-7
+
+   Periodically run cargo check after updating each major component or group of related files to catch compilation errors early.
+9. Final verification and testing
+   Priority: High
+   Complexity: Low
+   Dependencies: All previous steps
+
+   Run full test suite to verify that all code compiles and tests pass:
+
+   ```
+   cargo insta test --accept --unreferenced=delete
+   cargo +nightly fmt --all
+   cargo +nightly clippy --fix --allow-staged --allow-dirty --workspace
+   ```
+
+## Verification Criteria
+
+* The `ExecutableTool` trait includes `ToolCallContext` as a parameter in its `call` method
+* All implementations of `ExecutableTool` accept and handle the new parameter
+* All tests are updated and pass successfully
+* The codebase compiles with no warnings or errors
+* Existing functionality continues to work as expected
+
+## Potential Risks and Mitigations
+
+* Risk 1: Large number of implementations to update (13+ files identified)
+  Mitigation: Use systematic approach with clear test helper functions and incremental verification
+* Risk 2: Hidden implementations in macros or nested structures
+  Mitigation: Careful grep searches and systematic compiler error resolution
+* Risk 3: Breaking changes to API contract
+  Mitigation: Since this is a required parameter, ensure thorough testing after updates
+* Risk 4: Missing test implementations leading to test failures
+  Mitigation: Develop helper functions for tests and use incremental compilation
+
+## Alternative Approaches
+
+
+1. Make `ToolCallContext` optional with a default: Could reduce the impact but wouldn't align with the requirement for it to be required.
+2. Use a trait object approach: Pass context as a trait object to allow for different context types, but this adds complexity and doesn't match the requirement for a specific struct.
+3. Thread-local context: Store context in a thread-local variable, but this approach is less explicit and could cause issues with async code.
+4. Implement in stages with feature flags: Could help manage the transition but adds complexity and doesn't align with the requirement for a cohesive implementation.
+
+

plans/2025-04-16-model-selection-command.md

@@ -0,0 +1,39 @@
+# Model Selection Command Implementation
+
+## Objective
+Add a `/model` command to the Forge CLI that uses the `inquire` library to display a list of available models and update the project's `forge.yaml` file with the selected model.
+
+## Implementation Plan
+- [x] Add `inquire` as a dependency to the workspace and forge_main crate
+- [x] Implement a `handle_model_selection()` method in the UI module to:
+  - Fetch available models using the API
+  - Display a selection interface using inquire
+  - Update the forge.yaml file with the selected model
+- [x] Update the Command::Model match case to call the new method
+
+## Implementation Details
+1. Added `inquire` dependency to the workspace and forge_main Cargo.toml files
+2. Implemented a new `handle_model_selection()` method in the UI module that:
+   - Fetches the list of available models
+   - Uses inquire to display a selection list
+   - Updates the standard_model anchor in the forge.yaml file
+3. Updated the Command::Model case in the UI::run method to call the new method
+
+## Verification Criteria
+- The `/model` command should display a list of available models using inquire
+- After selecting a model, the forge.yaml file should be updated with the selected model
+- The standard_model anchor in the forge.yaml file should be created if it doesn't exist
+- Appropriate error messages should be displayed if any step fails
+
+## Potential Risks and Mitigations
+- Risk: Models API might return an empty list
+  Mitigation: Added error handling for empty model lists
+- Risk: forge.yaml file might not exist in the current directory
+  Mitigation: Added error handling for missing files
+- Risk: forge.yaml file might be in an unexpected format
+  Mitigation: Added error handling for parsing errors
+
+## Future Improvements
+- Add support for updating advanced_model in addition to standard_model
+- Add support for creating forge.yaml if it doesn't exist
+- Add ability to filter models by provider

plans/2025-04-26-large-file-read-range-support-v3.md

@@ -0,0 +1,239 @@
+# Large File Range Reading Support (v3)
+
+## Objective
+Implement support for reading extremely large text files by adding range parameters (start_byte and end_byte) to the file read tool, allowing users to read specific portions of large files without loading the entire file into memory. Binary files should not be supported and UTF-8 character boundaries must always be respected.
+
+## Implementation Plan
+
+1. **Update `FsReadService` interface to support range reading**
+   - Dependencies: None
+   - Files: 
+     - `crates/forge_services/src/infra.rs`
+   - Notes: Add a new method to the trait that accepts start and end positions
+   - Status: Not Started
+
+2. **Implement the range reading functionality in `ForgeFileReadService`**
+   - Dependencies: Task 1
+   - Files: 
+     - `crates/forge_infra/src/fs_read.rs`
+   - Notes: Implement the new trait method using Tokio's file API for efficient reading
+   - Status: Not Started
+
+3. **Add binary file detection and validation**
+   - Dependencies: None
+   - Files:
+     - `crates/forge_fs/src/lib.rs`
+   - Notes: Implement a utility function to detect if a file is binary and return an appropriate error
+   - Status: Not Started
+
+4. **Update ForgeFS to support range reading with binary file validation**
+   - Dependencies: Tasks 2, 3
+   - Files: 
+     - `crates/forge_fs/src/lib.rs`
+   - Notes: Add a new method for range-based file reading that rejects binary files
+   - Status: Not Started
+
+5. **Implement UTF-8 boundary detection and correction**
+   - Dependencies: Tasks 2, 4
+   - Files:
+     - `crates/forge_fs/src/lib.rs`
+   - Notes: Ensure that range reads always align with UTF-8 character boundaries by adjusting the actual read range
+   - Status: Not Started
+
+6. **Update the `FSReadInput` struct to include optional range parameters**
+   - Dependencies: None
+   - Files: 
+     - `crates/forge_services/src/tools/fs/fs_read.rs`
+   - Notes: Add optional start_byte and end_byte fields to the input struct
+   - Status: Not Started
+
+7. **Modify FSRead tool implementation to support range reading and reject binary files**
+   - Dependencies: Tasks 1, 2, 3, 4, 5, 6
+   - Files: 
+     - `crates/forge_services/src/tools/fs/fs_read.rs`
+   - Notes: Update the `call` method to use the range-based reading with UTF-8 boundary adjustment and ensure binary files are rejected
+   - Status: Not Started
+
+8. **Update the FSRead tool description**
+   - Dependencies: Task 6
+   - Files: 
+     - `crates/forge_services/src/tools/fs/fs_read.rs`
+   - Notes: Update docstring to include range parameters in the tool description and explicitly mention that binary files are not supported and UTF-8 boundaries are always respected
+   - Status: Not Started
+
+9. **Implement file size detection logic**
+   - Dependencies: None
+   - Files:
+     - `crates/forge_fs/src/lib.rs`
+   - Notes: Add functionality to efficiently determine file size without reading the entire file
+   - Status: Not Started
+
+10. **Add content length information to range read responses**
+    - Dependencies: Task 9
+    - Files:
+      - `crates/forge_services/src/tools/fs/fs_read.rs`
+    - Notes: Include total file size and adjusted range information in the response to help users understand the context of the range
+    - Status: Not Started
+
+11. **Add unit tests for range-based file reading and binary file rejection**
+    - Dependencies: Tasks 1-10
+    - Files: 
+      - `crates/forge_services/src/tools/fs/fs_read.rs`
+      - `crates/forge_infra/src/fs_read.rs`
+      - `crates/forge_fs/src/lib.rs`
+    - Notes: Test different range scenarios, edge cases, binary file detection, UTF-8 boundary handling, and error conditions
+    - Status: Not Started
+
+## Verification Criteria
+- The file read tool correctly returns only the requested range of bytes from large text files
+- The tool properly identifies and rejects binary files with a clear error message
+- The tool always adjusts range boundaries to respect UTF-8 character boundaries
+- The tool handles edge cases properly:
+  - When start_byte is beyond the file size
+  - When end_byte is beyond the file size
+  - When start_byte is greater than end_byte
+  - When start_byte and end_byte are equal
+  - When start_byte is negative or otherwise invalid
+  - When reading from an empty file
+  - When the range spans across malformed UTF-8 sequences
+  - When the file is locked by another process
+  - When reading from special files (e.g., device files, named pipes)
+  - When hitting OS-specific file size limits
+- The tool returns the entire file when no range is specified (backward compatibility)
+- The tool provides helpful error messages for invalid range parameters
+- The response includes information about the actual range read after UTF-8 boundary adjustment
+- File size information is correctly included in the response
+- Performance remains acceptable for both small and extremely large text files
+- All unit tests pass
+- Clippy runs with no errors or warnings
+
+## Potential Risks and Mitigations
+
+1. **Performance issues with extremely large text files**  
+   Mitigation: 
+   - Ensure that the implementation doesn't read the entire file when a range is specified
+   - Use Tokio's file operations that support seeking and partial reads
+   - Verify with benchmarks on files of various sizes (MB to GB)
+   - Consider implementing a buffered reading strategy for large ranges
+
+2. **UTF-8 boundary adjustment overhead**  
+   Mitigation: 
+   - Optimize the UTF-8 boundary detection algorithm for performance
+   - Implement caching for boundary positions when repeated reads are requested
+   - Use efficient byte scanning techniques that minimize CPU and memory usage
+   - Provide clear metadata about the boundary adjustments that were made
+
+3. **Breaking changes to the existing API**  
+   Mitigation: 
+   - Make the range parameters optional with default values that maintain backward compatibility
+   - Document the behavior changes thoroughly
+   - Ensure all existing tests continue to pass with the new implementation
+
+4. **Inaccurate binary file detection**  
+   Mitigation: 
+   - Implement a robust heuristic for detecting binary files (e.g., check for null bytes, analyze byte distribution)
+   - Consider implementing a configurable threshold for binary detection
+   - Add comprehensive tests with various file types to verify correct detection
+   - Provide clear error messages when a file is detected as binary
+
+5. **File locking and concurrent access issues**  
+   Mitigation:
+   - Implement proper error handling for locked files
+   - Use non-exclusive file handles when possible
+   - Add retry logic with exponential backoff for temporary access issues
+
+6. **Memory consumption with large ranges**  
+   Mitigation:
+   - Implement chunk-based reading for very large ranges
+   - Set reasonable defaults and maximum values for range sizes
+   - Add memory usage monitoring and provide warnings for potentially problematic operations
+
+7. **Platform-specific issues**  
+   Mitigation:
+   - Test on all supported platforms (Windows, macOS, Linux)
+   - Handle platform-specific file path conventions
+   - Respect platform-specific file size limitations
+
+8. **Invalid UTF-8 sequences in text files**  
+   Mitigation:
+   - Implement robust error handling for malformed UTF-8
+   - Provide clear error messages when invalid UTF-8 is encountered
+   - Consider options for replacement or reporting of invalid sequences
+
+## Alternative Approaches
+
+1. **Streaming API**: Implement a streaming interface for file reading instead of range-based reading. This would allow progressive loading of large files but would require more significant changes to the tool interface.
+
+2. **File Pagination Tool**: Create a separate tool specifically for paginated file reading, leaving the original file read tool unchanged. This would maintain perfect backward compatibility but introduce redundancy.
+
+3. **Content-Based Partitioning**: Implement intelligent partitioning based on content (e.g., by line, by paragraph, by JSON object) rather than raw bytes. This would be more semantic but more complex to implement.
+
+4. **Fixed-size chunking**: Instead of arbitrary byte ranges, implement a chunking system where files are divided into fixed-size chunks that can be requested by index. This would simplify the API but reduce flexibility.
+
+5. **Smart text-only file reading**: Implement a detection mechanism that automatically determines the optimal portion of a text file to return based on the context of the request, using language-aware boundaries like paragraphs or code blocks.
+
+## Implementation Details
+
+### Range Parameter Design
+
+For the FSReadInput struct, add the following optional parameters:
+
+```rust
+/// Optional start position in bytes (0-based)
+pub start_byte: Option<u64>,
+
+/// Optional end position in bytes (exclusive)
+pub end_byte: Option<u64>,
+```
+
+### Binary File Detection
+
+To detect binary files, we'll implement a function that:
+
+1. Reads a small sample of the file (e.g., first 8KB)
+2. Checks for null bytes or other binary indicators
+3. Analyzes the distribution of byte values
+4. Returns a boolean indicating whether the file is likely binary
+
+When a file is detected as binary, we'll return an error message like:
+"Binary files are not supported. Please use another tool or method to process this file."
+
+### UTF-8 Boundary Detection and Adjustment
+
+To ensure range reads respect UTF-8 character boundaries:
+
+1. For the start position:
+   - If the byte at start_byte is a UTF-8 continuation byte (10xxxxxx), scan backward to find the leading byte
+   - Adjust start_byte to the position of the leading byte
+
+2. For the end position:
+   - If the byte at end_byte-1 is a leading byte of a multi-byte sequence, check if the complete character is included
+   - If not, scan forward to include the complete character or backward to exclude the partial character
+
+3. Report the adjusted positions in the response metadata
+
+### Response Format
+
+The response will include:
+
+- The requested file content (as text)
+- Metadata about the read operation:
+  - Total file size
+  - Original requested range
+  - Actual range read after UTF-8 boundary adjustment
+  - Information about boundary adjustments made
+
+### Efficient Implementation Approach
+
+To minimize memory usage and improve performance:
+
+1. Use `tokio::fs::File::open()` to get a file handle
+2. Perform binary file detection check
+3. Use `file.metadata()` to get the file size without reading content
+4. Validate range parameters against file size
+5. Use `file.seek()` to position near start_byte
+6. Perform UTF-8 boundary detection and adjust start position if needed
+7. Use `file.take(adjusted_end_byte - adjusted_start_byte)` to create a limited reader
+8. Read from the limited reader into a buffer
+9. Verify that the buffer contains valid UTF-8 and make any final adjustments
+10. Return the buffer content with detailed metadata

plans/2025-04-27-large-file-read-range-support-v4.md

@@ -0,0 +1,316 @@
+# Large File Range Reading Support (v4)
+
+## Objective
+Implement support for reading extremely large text files by adding range parameters (start_byte and end_byte) to the file read tool, allowing users to read specific portions of large files without loading the entire file into memory. Binary files should not be supported and UTF-8 character boundaries must always be respected.
+
+## Implementation Plan
+
+1. **Update `FsReadService` interface to support range reading**
+   - Dependencies: None
+   - Files: 
+     - `crates/forge_services/src/infra.rs`
+   - Notes: Add a new method to the trait that accepts start and end positions
+   - Status: Not Started
+
+2. **Implement the range reading functionality in `ForgeFileReadService`**
+   - Dependencies: Task 1
+   - Files: 
+     - `crates/forge_infra/src/fs_read.rs`
+   - Notes: Implement the new trait method using Tokio's file API for efficient reading
+   - Status: Not Started
+
+3. **Add binary file detection using the infer crate**
+   - Dependencies: None
+   - Files:
+     - `crates/forge_fs/src/lib.rs`
+     - `crates/forge_fs/Cargo.toml`
+   - Notes: Add the infer crate as a dependency and implement a utility function to detect if a file is binary and return an appropriate error
+   - Status: Not Started
+
+4. **Update ForgeFS to support range reading with binary file validation**
+   - Dependencies: Tasks 2, 3
+   - Files: 
+     - `crates/forge_fs/src/lib.rs`
+   - Notes: Add a new method for range-based file reading that rejects binary files
+   - Status: Not Started
+
+5. **Implement UTF-8 boundary detection and correction**
+   - Dependencies: Tasks 2, 4
+   - Files:
+     - `crates/forge_fs/src/lib.rs`
+   - Notes: Ensure that range reads always align with UTF-8 character boundaries by adjusting the actual read range
+   - Status: Not Started
+
+6. **Update the `FSReadInput` struct to include optional range parameters**
+   - Dependencies: None
+   - Files: 
+     - `crates/forge_services/src/tools/fs/fs_read.rs`
+   - Notes: Add optional start_byte and end_byte fields to the input struct
+   - Status: Not Started
+
+7. **Modify FSRead tool implementation to support range reading and reject binary files**
+   - Dependencies: Tasks 1, 2, 3, 4, 5, 6
+   - Files: 
+     - `crates/forge_services/src/tools/fs/fs_read.rs`
+   - Notes: Update the `call` method to use the range-based reading with UTF-8 boundary adjustment and ensure binary files are rejected
+   - Status: Not Started
+
+8. **Update the FSRead tool description**
+   - Dependencies: Task 6
+   - Files: 
+     - `crates/forge_services/src/tools/fs/fs_read.rs`
+   - Notes: Update docstring to include range parameters in the tool description and explicitly mention that binary files are not supported and UTF-8 boundaries are always respected
+
+      Sample Response:
+      ```
+      ---
+      path: /a/b/c.txt
+      range: 100-200
+      total: 1024
+      ---
+      Hello! This is the contents of file c.txt
+      ```
+   - Status: Not Started
+
+9. **Implement file size detection logic**
+   - Dependencies: None
+   - Files:
+     - `crates/forge_fs/src/lib.rs`
+   - Notes: Add functionality to efficiently determine file size without reading the entire file
+   - Status: Not Started
+
+10. **Add content length information to range read responses**
+    - Dependencies: Task 9
+    - Files:
+      - `crates/forge_services/src/tools/fs/fs_read.rs`
+    - Notes: Include total file size and adjusted range information in the response to help users understand the context of the range
+    - Status: Not Started
+
+11. **Add unit tests for range-based file reading and binary file rejection**
+    - Dependencies: Tasks 1-10
+    - Files: 
+      - `crates/forge_services/src/tools/fs/fs_read.rs`
+      - `crates/forge_infra/src/fs_read.rs`
+      - `crates/forge_fs/src/lib.rs`
+    - Notes: Test different range scenarios, edge cases, binary file detection with infer, UTF-8 boundary handling, and error conditions
+    - Status: Not Started
+
+## Verification Criteria
+- The file read tool correctly returns only the requested range of bytes from large text files
+- The tool properly identifies and rejects binary files with a clear error message using the infer crate
+- The tool always adjusts range boundaries to respect UTF-8 character boundaries
+- The tool handles edge cases properly:
+  - When start_byte is beyond the file size
+  - When end_byte is beyond the file size
+  - When start_byte is greater than end_byte
+  - When start_byte and end_byte are equal
+  - When start_byte is negative or otherwise invalid
+  - When reading from an empty file
+  - When the range spans across malformed UTF-8 sequences
+  - When the file is locked by another process
+  - When reading from special files (e.g., device files, named pipes)
+  - When hitting OS-specific file size limits
+- The tool returns the entire file when no range is specified (backward compatibility)
+- The tool provides helpful error messages for invalid range parameters
+- The response includes information about the actual range read after UTF-8 boundary adjustment
+- File size information is correctly included in the response
+- Performance remains acceptable for both small and extremely large text files
+- All unit tests pass
+- Clippy runs with no errors or warnings
+
+## Potential Risks and Mitigations
+
+1. **Performance issues with extremely large text files**  
+   Mitigation: 
+   - Ensure that the implementation doesn't read the entire file when a range is specified
+   - Use Tokio's file operations that support seeking and partial reads
+   - Verify with benchmarks on files of various sizes (MB to GB)
+   - Consider implementing a buffered reading strategy for large ranges
+
+2. **UTF-8 boundary adjustment overhead**  
+   Mitigation: 
+   - Optimize the UTF-8 boundary detection algorithm for performance
+   - Implement caching for boundary positions when repeated reads are requested
+   - Use efficient byte scanning techniques that minimize CPU and memory usage
+   - Provide clear metadata about the boundary adjustments that were made
+
+3. **Breaking changes to the existing API**  
+   Mitigation: 
+   - Make the range parameters optional with default values that maintain backward compatibility
+   - Document the behavior changes thoroughly
+   - Ensure all existing tests continue to pass with the new implementation
+
+4. **Inaccurate binary file detection**  
+   Mitigation: 
+   - Use the infer crate which provides robust file type detection
+   - Still implement fallback checks for edge cases the infer crate might miss
+   - Add comprehensive tests with various file types to verify correct detection
+   - Provide clear error messages when a file is detected as binary
+
+5. **File locking and concurrent access issues**  
+   Mitigation:
+   - Implement proper error handling for locked files
+   - Use non-exclusive file handles when possible
+   - Add retry logic with exponential backoff for temporary access issues
+
+6. **Memory consumption with large ranges**  
+   Mitigation:
+   - Implement chunk-based reading for very large ranges
+   - Set reasonable defaults and maximum values for range sizes
+   - Add memory usage monitoring and provide warnings for potentially problematic operations
+
+7. **Platform-specific issues**  
+   Mitigation:
+   - Test on all supported platforms (Windows, macOS, Linux)
+   - Handle platform-specific file path conventions
+   - Respect platform-specific file size limitations
+
+8. **Invalid UTF-8 sequences in text files**  
+   Mitigation:
+   - Implement robust error handling for malformed UTF-8
+   - Provide clear error messages when invalid UTF-8 is encountered
+   - Consider options for replacement or reporting of invalid sequences
+
+9. **Dependency management issues with infer crate**  
+   Mitigation:
+   - Pin to a specific version of the infer crate to avoid breaking changes
+   - Monitor for security updates and issues with the infer crate
+   - Have a fallback mechanism in case the infer crate fails
+
+10. **Confusion for users with the new metadata in responses**  
+    Mitigation:
+    - Provide clear documentation on how to interpret the metadata
+    - Include examples of how to use the new range parameters
+    - Ensure backward compatibility so users not using ranges aren't affected
+
+## Alternative Approaches
+
+1. **Streaming API**: Implement a streaming interface for file reading instead of range-based reading. This would allow progressive loading of large files but would require more significant changes to the tool interface.
+
+2. **File Pagination Tool**: Create a separate tool specifically for paginated file reading, leaving the original file read tool unchanged. This would maintain perfect backward compatibility but introduce redundancy.
+
+3. **Content-Based Partitioning**: Implement intelligent partitioning based on content (e.g., by line, by paragraph, by JSON object) rather than raw bytes. This would be more semantic but more complex to implement.
+
+4. **Fixed-size chunking**: Instead of arbitrary byte ranges, implement a chunking system where files are divided into fixed-size chunks that can be requested by index. This would simplify the API but reduce flexibility.
+
+5. **Smart text-only file reading**: Implement a detection mechanism that automatically determines the optimal portion of a text file to return based on the context of the request, using language-aware boundaries like paragraphs or code blocks.
+
+6. **Custom binary detection instead of infer**: Implement our own binary detection logic instead of relying on an external crate. This would reduce dependencies but require more maintenance and could be less accurate.
+
+## Implementation Details
+
+### Range Parameter Design
+
+For the FSReadInput struct, add the following optional parameters:
+
+```rust
+/// Optional start position in bytes (0-based)
+pub start_byte: Option<u64>,
+
+/// Optional end position in bytes (exclusive)
+pub end_byte: Option<u64>,
+```
+
+### Binary File Detection
+
+To detect binary files, we'll use the `infer` crate:
+
+1. Add the infer crate to dependencies in Cargo.toml:
+   ```toml
+   [dependencies]
+   infer = "0.15.0"  # Use the latest version
+   ```
+
+2. Implement a utility function that:
+   - Reads a small sample of the file (e.g., first 8KB)
+   - Uses `infer::is_image()`, `infer::is_video()`, `infer::is_audio()`, `infer::is_archive()`, etc. to detect binary formats
+   - For files not detected by infer, falls back to checking for null bytes or high concentration of non-printable characters
+   - Returns a boolean indicating whether the file is likely binary
+
+3. When a file is detected as binary, return an error message like:
+   "Binary files are not supported. File detected as [file type]. Please use another tool or method to process this file."
+
+### UTF-8 Boundary Detection and Adjustment
+
+To ensure range reads respect UTF-8 character boundaries:
+
+1. For the start position:
+   - If the byte at start_byte is a UTF-8 continuation byte (10xxxxxx), scan backward to find the leading byte
+   - Adjust start_byte to the position of the leading byte
+
+2. For the end position:
+   - If the byte at end_byte-1 is a leading byte of a multi-byte sequence, check if the complete character is included
+   - If not, scan forward to include the complete character or backward to exclude the partial character
+
+3. Report the adjusted positions in the response metadata
+
+### Response Format
+
+The response will include:
+
+- The requested file content (as text)
+- Metadata about the read operation:
+  - Total file size
+  - Original requested range
+  - Actual range read after UTF-8 boundary adjustment
+  - Information about boundary adjustments made
+
+### Sample Response
+
+The fs_read tool will return JSON with the following structure:
+
+```json
+{
+  "content": "This is the file content within the requested range...",
+  "metadata": {
+    "file_size": 1024000,
+    "requested_range": {
+      "start_byte": 500,
+      "end_byte": 1500
+    },
+    "actual_range": {
+      "start_byte": 498,
+      "end_byte": 1503
+    },
+    "boundary_adjustments": {
+      "start_adjusted": true,
+      "start_adjustment_reason": "UTF-8 character boundary alignment",
+      "end_adjusted": true,
+      "end_adjustment_reason": "UTF-8 character boundary alignment"
+    },
+    "is_partial": true,
+    "percent_of_file": 0.1
+  }
+}
+```
+
+For error cases:
+
+```json
+{
+  "error": "Binary files are not supported. File detected as image/png. Please use another tool or method to process this file."
+}
+```
+
+Or for invalid ranges:
+
+```json
+{
+  "error": "Invalid range specified: start_byte (5000) is greater than end_byte (4000)."
+}
+```
+
+### Efficient Implementation Approach
+
+To minimize memory usage and improve performance:
+
+1. Use `tokio::fs::File::open()` to get a file handle
+2. Read a small sample and perform binary file detection using the infer crate
+3. Use `file.metadata()` to get the file size without reading content
+4. Validate range parameters against file size
+5. Use `file.seek()` to position near start_byte
+6. Perform UTF-8 boundary detection and adjust start position if needed
+7. Use `file.take(adjusted_end_byte - adjusted_start_byte)` to create a limited reader
+8. Read from the limited reader into a buffer
+9. Verify that the buffer contains valid UTF-8 and make any final adjustments
+10. Return the buffer content with detailed metadata

plans/2025-06-07-tool-service-migration-v1.md

@@ -0,0 +1,197 @@
+# Tool-to-Service Migration Plan
+
+## Objective
+
+Migrate all tools from direct infrastructure dependencies to service-based architecture where each tool has a corresponding service and tools become thin wrappers that make single service calls. This will improve testability, maintainability, and follow clean architecture principles.
+
+## Implementation Plan
+
+### 1. **Analyze Current Tool Patterns and Dependencies**
+- Dependencies: None
+- Notes: Examine all existing tools to identify common patterns, infrastructure usage, and business logic that should be moved to services
+- Files: 
+  - `crates/forge_services/src/tools/fs/file_info.rs`
+  - `crates/forge_services/src/tools/fs/fs_find.rs`
+  - `crates/forge_services/src/tools/fs/fs_list.rs`
+  - `crates/forge_services/src/tools/fs/fs_read.rs`
+  - `crates/forge_services/src/tools/fs/fs_remove.rs`
+  - `crates/forge_services/src/tools/fs/fs_undo.rs`
+  - `crates/forge_services/src/tools/fs/fs_write.rs`
+  - `crates/forge_services/src/tools/fetch.rs`
+  - `crates/forge_services/src/tools/followup.rs`
+  - `crates/forge_services/src/tools/patch.rs`
+  - `crates/forge_services/src/tools/shell.rs`
+  - `crates/forge_services/src/tools/registry.rs`
+  - `crates/forge_services/src/tools/mod.rs`
+- Status: Not Started
+
+### 2. **Design Service Interface Standards**
+- Dependencies: Task 1
+- Notes: Create standardized patterns for tool services including error handling, input validation, and output formatting. Define naming conventions and service trait structure. **Important**: Services must NOT use ToolCallContext - this is UI-specific and stays in tools. Services should be pure business logic with simple input/output. **Critical**: Services must use Infrastructure traits (FsReadService, FsWriteService, etc.) instead of direct tokio::fs calls.
+- Files: 
+  - New service trait definitions in `crates/forge_services/src/`
+  - Service interface documentation
+- Status: Not Started
+
+### 3. **Create Generic Service Trait Template**
+- Dependencies: Task 2
+- Notes: Define a generic service trait pattern that can be applied to any tool, including async methods, error handling with anyhow::Result, and integration with existing Infrastructure
+- Files:
+  - `crates/forge_services/src/mod.rs` (new)
+  - Service trait template documentation
+- Status: Not Started
+
+### 4. **Implement Service for Template Tool (FSRead as Example)**
+- Dependencies: Task 3
+- Notes: Create complete service implementation for FSRead tool as a **template example** that demonstrates the migration pattern. This is not the final implementation but a reference pattern to be applied to all tools. **Critical**: Service must NOT use ToolCallContext - extract only pure business logic. All UI concerns (titles, progress) remain in tool. **Important**: Service must use Infrastructure traits (FsReadService, etc.) instead of direct tokio::fs calls.
+- Files:
+  - `crates/forge_services/src/fs_read_service.rs` (new - template example)
+  - Updated `crates/forge_services/src/mod.rs`
+- Status: Not Started
+
+### 5. **Update Services Trait and ForgeServices (Template Pattern)**
+- Dependencies: Task 4
+- Notes: Add new FSReadService to main Services trait and implement it in ForgeServices struct as a **template pattern**. This demonstrates how any tool service should be integrated into the main service architecture.
+- Files:
+  - `crates/forge_app/src/services.rs`
+  - `crates/forge_services/src/forge_services.rs`
+- Status: Not Started
+
+### 6. **Refactor FSRead Tool Implementation (Template Pattern)**
+- Dependencies: Task 5
+- Notes: Convert FSRead tool to use FSReadService instead of direct infrastructure calls as a **template example**. This demonstrates how to make any tool a thin wrapper with single service call. The pattern shown here applies to all other tools. **Key**: Tool retains ToolCallContext for UI (titles, progress) but delegates all business logic to service.
+- Files:
+  - `crates/forge_services/src/tools/fs/fs_read.rs`
+- Status: Not Started
+
+### 7. **Update Tool Registry for Service Injection**
+- Dependencies: Task 6
+- Notes: Modify tool registration to inject service dependencies through the Services trait instead of raw Infrastructure
+- Files:
+  - `crates/forge_services/src/tools/registry.rs`
+- Status: Not Started
+
+### 8. **Create Migration Template Documentation**
+- Dependencies: Task 7
+- Notes: Document the complete **generic pattern** for migrating any tool to service-based architecture, using the FSRead example as a reference. Include code templates, step-by-step instructions, and patterns that can be applied to any tool (shell, fetch, patch, etc.).
+- Files:
+  - `docs/tool-service-migration-template.md` (new)
+  - Migration checklist and examples showing how FSRead pattern applies to any tool
+- Status: Not Started
+
+### 9. **Apply Migration Pattern to All Remaining Tools**
+- Dependencies: Task 8
+- Notes: Apply the **generic migration pattern** established with FSRead template to all remaining tools. Each tool follows the same pattern: create service, integrate into Services trait, refactor tool to use service.
+- Files:
+  - `crates/forge_services/src/file_info_service.rs` (new - following FSRead pattern)
+  - `crates/forge_services/src/fs_find_service.rs` (new - following FSRead pattern)
+  - `crates/forge_services/src/fs_list_service.rs` (new - following FSRead pattern)
+  - `crates/forge_services/src/fs_remove_service.rs` (new - following FSRead pattern)
+  - `crates/forge_services/src/fs_undo_service.rs` (new - following FSRead pattern)
+  - `crates/forge_services/src/fs_write_service.rs` (new - following FSRead pattern)
+  - `crates/forge_services/src/fetch_service.rs` (new - following FSRead pattern)
+  - `crates/forge_services/src/followup_service.rs` (new - following FSRead pattern)
+  - `crates/forge_services/src/patch_service.rs` (new - following FSRead pattern)
+  - `crates/forge_services/src/shell_service.rs` (new - following FSRead pattern)
+  - Updated tool implementations for all tools (applying FSRead refactoring pattern)
+  - Updated Services trait and ForgeServices (following FSRead integration pattern)
+- Status: Not Started
+
+### 10. **Validation and Testing**
+- Dependencies: Task 9
+- Notes: Ensure all migrated tools maintain functionality, test coverage is preserved, and new services have comprehensive tests following project testing standards. **Critical**: Migrate existing tests from tools to services - business logic tests move to service layer, UI/integration tests remain with tools.
+- Files:
+  - Test files for all new services (migrated from tool tests)
+  - Updated tool tests (focused on UI and service integration)
+  - Integration tests
+- Status: Not Started
+
+## Tool Migration Checklist
+
+Track the progress of migrating each tool to service-based architecture:
+
+### File System Tools
+- [ ] **file_info** - Get file metadata and information
+- [ ] **fs_find** - Search for files and directories
+- [ ] **fs_list** - List directory contents
+- [ ] **fs_read** - Read file contents (**TEMPLATE EXAMPLE** - pattern to be applied to all other tools)
+- [ ] **fs_remove** - Remove files and directories
+- [ ] **fs_undo** - Undo file system operations
+- [ ] **fs_write** - Write content to files
+
+### Network and External Tools
+- [ ] **fetch** - Fetch content from URLs
+
+### Interactive and Workflow Tools
+- [ ] **followup** - Handle follow-up actions and suggestions
+
+### Code and Content Processing Tools
+- [ ] **patch** - Apply patches and modifications to files
+
+### System Tools
+- [ ] **shell** - Execute shell commands
+
+### Registry and Meta Tools
+- [ ] **registry** - Tool registration and management
+- [ ] **mod** - Module and component operations
+
+Each tool migration should follow the **FSRead template pattern** and include:
+1. Service interface design and implementation (following FSRead service pattern) - **Services in `crates/forge_services/src/`**
+2. Tool refactoring to use service (following FSRead tool refactoring pattern) - **Tool keeps ToolCallContext for UI, service gets pure business logic**
+3. Service integration into Services trait (following FSRead integration pattern)
+4. Test migration from tool to service (following FSRead testing pattern) - **Business logic tests move to service, UI tests stay with tool**
+5. Documentation updates
+
+**Note**: FSRead serves as the template example demonstrating the generic migration pattern. All other tools should follow the exact same pattern established by the FSRead implementation.
+
+**Critical Requirements**:
+- Services are defined in `crates/forge_services/src/` directory
+- Services must NOT use ToolCallContext - this is UI-specific and remains in tools
+- Services contain only pure business logic with simple input/output
+- Tools retain ToolCallContext for UI concerns (titles, progress, user interaction)
+- Existing tests migrate from tools to services where they test business logic
+- **IMPORTANT**: Services must use Infrastructure traits (FsReadService, FsWriteService, etc.) instead of direct tokio::fs calls. This ensures proper abstraction, testability, and consistency with the project's architecture.
+
+## Verification Criteria
+
+- All tools are thin wrappers that make single calls to their corresponding services
+- Each tool has a dedicated service implementing business logic in `crates/forge_services/src/`
+- Services do NOT use ToolCallContext - they have pure input/output interfaces
+- Services use Infrastructure traits (FsReadService, FsWriteService, etc.) instead of direct tokio::fs calls
+- Tools retain ToolCallContext for UI concerns (titles, progress, user interaction)
+- Services are properly integrated into the Services trait and ForgeServices implementation
+- Tool registry uses Services trait instead of raw Infrastructure for tool instantiation
+- All existing functionality is preserved with no breaking changes
+- Test coverage is maintained or improved - business logic tests migrated to services, UI tests remain with tools
+- Migration documentation is complete and can be followed for any remaining tools
+- Code follows project standards including error handling with anyhow::Result and testing patterns
+
+## Potential Risks and Mitigations
+
+### 1. **Breaking Changes to Tool Interface**
+**Risk**: Modifying tool constructors and registration could break existing code that depends on current tool instantiation patterns.
+**Mitigation**: Maintain backward compatibility by keeping existing tool constructors while adding service-based alternatives. Use feature flags or gradual migration approach.
+
+### 2. **Service Dependency Complexity**
+**Risk**: Adding service layer could introduce circular dependencies or complex dependency injection chains.
+**Mitigation**: Design services to depend only on Infrastructure traits, not on other services. Keep service interfaces focused and minimal.
+
+### 3. **Performance Overhead**
+**Risk**: Additional service layer could introduce performance overhead through extra abstraction.
+**Mitigation**: Ensure services are lightweight wrappers around infrastructure calls. Profile critical paths to verify no significant performance impact.
+
+### 4. **Test Complexity**
+**Risk**: Mocking services for tool tests could become more complex than current infrastructure mocking.
+**Mitigation**: Create standardized service mocks and test utilities. Ensure service interfaces are designed for easy testing.
+
+### 5. **Inconsistent Migration**
+**Risk**: Partial migration could result in inconsistent architecture with some tools using services and others using infrastructure directly.
+**Mitigation**: Complete migration of all core tools before considering the migration complete. Document clear guidelines for future tool development.
+
+## Alternative Approaches
+
+### 1. **Gradual Infrastructure Extension**: Instead of creating separate services, extend the Infrastructure trait with higher-level methods that encapsulate business logic, allowing tools to call more semantic operations while maintaining current architecture.
+
+### 2. **Tool-Specific Service Injection**: Rather than adding all services to the main Services trait, inject specific services directly into tool constructors, reducing the size of the Services trait but requiring more complex tool instantiation.
+
+### 3. **Service Composition Pattern**: Create a single ToolService that composes multiple domain-specific services, providing a unified interface for all tool operations while maintaining service separation internally.

plans/2025-09-07-shell-env-variable-support-v1.md

@@ -0,0 +1,65 @@
+# Shell Tool Environment Variable Support
+
+## Objective
+
+Add environment variable support to the shell tool, allowing agents to specify environment variable names that should be set before executing commands. The infrastructure will read these environment variables from the system and apply them during command execution.
+
+## Implementation Plan
+
+- [x] **Task 1. Update Shell Tool Domain Model**  
+  Extend the `Shell` struct in `crates/forge_domain/src/tools.rs` to include an optional `env` field that accepts a vector of environment variable names. This field will specify which environment variables should be passed to the command execution environment.
+
+- [x] **Task 2. Update CommandInfra Interface**  
+  Modify the `CommandInfra` trait in `crates/forge_services/src/infra.rs` to accept environment variable names in the `execute_command` and `execute_command_raw` methods. This involves adding a new parameter `env_vars: Option<Vec<String>>` to both methods.
+
+- [x] **Task 3. Update ShellService Interface**  
+  Extend the `ShellService` trait in `crates/forge_app/src/services.rs` to accept environment variable names in the `execute` method. Add `env_vars: Option<Vec<String>>` parameter to maintain consistency with the updated CommandInfra interface.
+
+- [x] **Task 4. Update Shell Service Implementation**  
+  Modify the `ForgeShell` implementation in `crates/forge_services/src/tool_services/shell.rs` to pass environment variable names to the infrastructure layer. Update the `execute` method to forward the env_vars parameter to the command infrastructure.
+
+- [x] **Task 5. Update Command Executor Implementation**  
+  Enhance the `ForgeCommandExecutorService` in `crates/forge_infra/src/executor.rs` to read specified environment variables from the system and apply them to the command execution context. Modify the `prepare_command` method to set the requested environment variables on the Command instance.
+
+- [x] **Task 6. Update Tool Operation Processing**  
+  Modify the shell tool operation handling in `crates/forge_app/src/operation.rs` and `crates/forge_app/src/tool_executor.rs` to extract environment variable names from the Shell tool input and pass them through the service chain.
+
+- [x] **Task 7. Update Infrastructure Implementations**  
+  Update all CommandInfra implementations to support the new environment variable parameter, including the main implementation in `crates/forge_infra/src/forge_infra.rs` and any test implementations in `crates/forge_services/src/attachment.rs`.
+
+- [x] **Task 8. Add Comprehensive Test Coverage**  
+  Create tests to verify environment variable functionality works correctly, including tests for missing environment variables, empty env lists, and successful environment variable application during command execution.
+
+## Verification Criteria
+
+- Environment variable names can be specified in shell tool calls through the new `env` field
+- Specified environment variables are properly read from the system and applied to command execution
+- Commands execute successfully with the requested environment variables available
+- Missing environment variables are handled gracefully without causing command failures
+- All existing shell tool functionality continues to work unchanged
+- Test suite passes with comprehensive coverage of the new environment variable feature
+
+## Potential Risks and Mitigations
+
+1. **Breaking API Changes**  
+   Mitigation: Use optional parameters and default values to maintain backward compatibility with existing shell tool usage
+
+2. **Environment Variable Security**  
+   Mitigation: Only read specified environment variables by name rather than exposing the entire environment to prevent unintended information leakage
+
+3. **Missing Environment Variables**  
+   Mitigation: Handle missing environment variables gracefully by either skipping them or providing clear error messages, depending on the desired behavior
+
+4. **Performance Impact**  
+   Mitigation: Only read environment variables when explicitly requested, avoiding unnecessary system calls when the env field is not provided
+
+## Alternative Approaches
+
+1. **Direct Environment Variable Values**: Allow agents to specify environment variable values directly instead of just names
+   - Trade-offs: More flexible but potentially less secure, as it would allow agents to set arbitrary values rather than using system-defined values
+
+2. **Environment Variable Validation**: Implement allowlists or validation for which environment variables can be accessed
+   - Trade-offs: Enhanced security but increased complexity and potential limitations for legitimate use cases
+
+3. **Separate Environment Tool**: Create a dedicated tool for environment variable management instead of extending the shell tool
+   - Trade-offs: Cleaner separation of concerns but additional complexity for users who need both shell execution and environment variable access

plans/2025-09-08-agent-loader-cwd-extension-v1.md

@@ -0,0 +1,115 @@
+# Agent Loader CWD Extension Implementation Plan
+
+## Objective
+
+Extend the `AgentLoaderService` to load agents from both the existing `{HOME}/forge/agents/` directory and an additional `CWD/.forge/agents/` directory, combining agents from both sources while maintaining the current architecture patterns and safety guarantees.
+
+## Implementation Plan
+
+### Phase 1: Domain Layer Extensions
+- [x] Task 1. **Add CWD agent path method to Environment**
+  - Add `agent_cwd_path()` method to the `Environment` struct in `crates/forge_domain/src/env.rs` 
+  - Method should return `PathBuf::from(".forge/agents")` to point to the current working directory
+  - Follow the same pattern as existing `agent_path()` method but use current directory as base
+
+- [x] Task 2. **Update EnvironmentInfra trait usage documentation**  
+  - Document that environments now support both global and project-local agent directories
+  - Update any relevant comments or documentation strings in the trait definitions
+
+### Phase 2: Service Layer Implementation
+- [x] Task 3. **Extend AgentLoaderService init method**
+  - Modify `init()` method in `crates/forge_services/src/agent_loader.rs` to load from three sources instead of two
+  - Keep existing built-in agents loading (`init_default()`)
+  - Keep existing custom agents loading from global directory (`init_custom()`)  
+  - Add new CWD agents loading (`init_cwd()`) method call
+
+- [x] Task 4. **Implement init_cwd method**
+  - Add `init_cwd()` private method to `AgentLoaderService`
+  - Use `self.infra.get_environment().agent_cwd_path()` to get the CWD agent directory
+  - Check if directory exists using `self.infra.exists()` like existing custom agent logic
+  - Use `DirectoryReaderInfra::read_directory_files()` with `"*.md"` pattern
+  - Parse agents using existing `parse_agent_iter()` function
+  - Handle missing directory gracefully by returning empty vector
+
+- [x] Task 5. **Combine agent sources in init method**
+  - Modify existing `init()` method to combine all three sources: built-in, custom (global), and CWD
+  - Use `Vec::extend()` pattern like existing implementation
+  - Maintain order: built-in agents first, then global custom agents, then CWD agents
+  - This order ensures built-in agents have precedence over custom ones
+
+### Phase 3: Error Handling and Safety
+- [x] Task 6. **Add comprehensive error context**
+  - Add context information to distinguish between global and CWD agent loading failures
+  - Update error messages to specify which directory failed to load
+  - Ensure partial failures don't prevent other agent sources from loading
+
+- [x] Task 7. **Handle agent ID conflicts**
+  - Implement conflict resolution strategy for duplicate agent IDs across directories
+  - Later-loaded agents (CWD) should take precedence over earlier-loaded agents (global)
+  - Document the precedence order: CWD Custom > Global Custom > Built-in
+
+### Phase 4: Testing Implementation  
+- [x] Task 8. **Add unit tests for agent_cwd_path**
+  - Test that `Environment::agent_cwd_path()` returns correct path structure
+  - Verify path resolution works independently from `agent_path()`
+  - Add test cases for the new method in existing environment tests
+
+- [x] Task 9. **Add unit tests for CWD agent loading**
+  - Create test fixtures in `crates/forge_services/src/fixtures/` for CWD agent scenarios
+  - Test successful CWD agent loading with valid markdown files
+  - Test graceful handling of missing CWD `.forge/agents/` directory
+  - Test agent conflict resolution between global and CWD directories
+
+- [x] Task 10. **Add integration tests**
+  - Test complete agent loading flow with all three sources active
+  - Verify agent precedence order works correctly
+  - Test error isolation - CWD loading failure doesn't break global loading
+
+### Phase 5: Documentation and Validation
+- [x] Task 11. **Update service documentation**  
+  - Update docstrings in `AgentLoaderService` to reflect multiple directory support
+  - Document the agent precedence order and directory resolution strategy
+  - Add usage examples showing how CWD agents complement global agents
+
+- [x] Task 12. **Run comprehensive testing**
+  - Execute `cargo insta test --accept --unreferenced=delete` for service tests
+  - Run full test suite to ensure no regressions in existing functionality
+  - Validate that built-in agents still load correctly
+
+## Verification Criteria
+
+- All existing built-in agents continue to load successfully from embedded sources
+- Global custom agents continue to load from `{HOME}/forge/agents/` directory  
+- CWD agents load from `.forge/agents/` directory when it exists
+- Missing `.forge/agents/` directory doesn't cause errors or prevent other agent loading
+- Agent precedence follows documented order: Built-in > Global > CWD
+- Agents with duplicate IDs are resolved correctly with later sources taking precedence
+- All existing tests pass without modification
+- New tests provide comprehensive coverage of the extended functionality
+
+## Potential Risks and Mitigations
+
+1. **Agent ID conflicts between directories**
+   Mitigation: Implement clear precedence rules with CWD agents overriding global agents
+
+2. **Performance impact from additional directory scanning**
+   Mitigation: Maintain existing caching strategy and parallel loading patterns
+
+3. **Breaking changes to existing agent loading behavior**
+   Mitigation: Extend functionality additively without modifying existing load paths
+
+4. **Directory permission or access issues for CWD**  
+   Mitigation: Use same graceful error handling pattern as existing custom agent loading
+
+5. **Inconsistent agent quality between global and CWD sources**
+   Mitigation: Apply same parsing and validation logic to all agent sources
+
+## Alternative Approaches
+
+1. **Configuration-driven approach**: Add agent directory paths to forge.yaml configuration file, allowing users to specify custom agent directories explicitly
+
+2. **Environment variable approach**: Support `FORGE_AGENT_PATHS` environment variable for colon-separated list of agent directories
+
+3. **Recursive directory scanning**: Modify existing agent loading to recursively scan subdirectories within agent paths
+
+4. **Agent registry pattern**: Implement a more sophisticated agent discovery system with registration and dependency management

plans/2025-09-12-forge-dump-autoopen-env-var-v2.md

@@ -0,0 +1,167 @@
+# FORGE_DUMP_AUTO_OPEN Environment Variable Implementation Plan v2
+
+## Objective
+
+Implement environment variable control for the auto-open functionality of HTML dumps in the Forge CLI by integrating the `FORGE_DUMP_AUTO_OPEN` environment variable directly into the Environment service. The feature will be accessible via `self.api.environment().auto_open_dump` and should default to `false` (disabled) and only auto-open when explicitly set to `true` or `1`.
+
+## Background Analysis
+
+Based on the GitHub issue (#1201) analysis and updated requirements:
+
+- **Problem**: Users in WSL2 environments experience slow browser performance when `/dump html` automatically opens files in the Linux browser
+- **Current Behavior**: HTML dumps always auto-open via `open::that()` call in `ui.rs:739`
+- **User Need**: Option to disable auto-opening for better workflow in cross-platform environments
+- **Updated Solution**: Store environment variable information directly in the Environment service and document in README.md
+
+## Architecture Assessment
+
+**Current Implementation Location**: `crates/forge_main/src/ui.rs:721-740`
+
+**Environment Service Architecture**: The codebase uses a layered service architecture:
+- `Environment` struct in `crates/forge_domain/src/env.rs:18` contains configuration fields
+- `EnvironmentInfra` trait in `crates/forge_infra/src/env.rs:107-108` handles environment variable access
+- Environment variables are parsed during initialization in `crates/forge_infra/src/env.rs:39-71`
+- API access pattern: `self.api.environment()` provides access to Environment struct
+
+**Access Pattern**: The desired `self.api.environment().auto_open_dump` pattern requires adding the field to the Environment struct and parsing logic to the infrastructure layer.
+
+## Implementation Plan
+
+- [x] **Task 1: Add auto_open_dump field to Environment struct**
+  - Location: `crates/forge_domain/src/env.rs:54` (add field after existing configuration fields)
+  - Add `pub auto_open_dump: bool` field to Environment struct
+  - Ensure field is included in builder pattern via existing `derive_setters::Setters`
+
+- [x] **Task 2: Add environment variable parsing in infrastructure layer**
+  - Location: `crates/forge_infra/src/env.rs:39-71` (in the `get()` method)
+  - Parse `FORGE_DUMP_AUTO_OPEN` environment variable using existing `parse_env` helper
+  - Support boolean values: "true", "1", "yes" (case-insensitive) for enabled; everything else disabled
+  - Default to `false` when variable is not set (maintains backward compatibility for new users)
+  - Follow existing patterns similar to other boolean environment variables in the codebase
+
+- [x] **Task 3: Update UI dump method to use Environment service**
+  - Location: `crates/forge_main/src/ui.rs:721-740`
+  - Replace direct `open::that()` call with conditional logic
+  - Use `self.api.environment().auto_open_dump` to determine if auto-open should occur
+  - Maintain existing behavior when auto-open is enabled
+
+- [x] **Task 4: Add user feedback for disabled auto-open**
+  - When auto-open is disabled, provide clear user feedback about file location
+  - Enhance existing title message to indicate manual file opening may be needed
+  - Ensure user knows where the HTML file was saved without being intrusive
+
+- [x] **Task 5: Document environment variable in README.md**
+  - Location: `README.md:376-382` (add to existing "Tool Configuration" section)
+  - Follow established documentation pattern with expandable details section
+  - Include environment variable name, default value, and clear description
+  - Document supported values and expected behavior
+
+- [x] **Task 6: Create comprehensive test coverage**
+  - Location: `crates/forge_infra/src/env.rs:269-511` (following existing test patterns)
+  - Unit tests for environment variable parsing logic using `serial_test::serial`
+  - Test default behavior (disabled when not set)
+  - Test enabled behavior (when set to truthy values: "true", "1", "yes")
+  - Test case-insensitive parsing
+  - Integration tests for dump functionality with different environment variable states
+
+- [x] **Task 7: Verify integration and behavior**
+  - Ensure Environment struct properly initializes with new field
+  - Verify API service correctly exposes the auto_open_dump property
+  - Test that UI component can access the configuration via API
+  - Confirm all existing functionality remains unchanged when environment variable enables auto-open
+
+## Verification Criteria
+
+- Environment variable `FORGE_DUMP_AUTO_OPEN` is integrated into Environment service
+- Accessible via `self.api.environment().auto_open_dump` pattern
+- Default behavior (when unset) is to NOT auto-open (false)
+- Setting to "true", "1", or "yes" (case-insensitive) enables auto-open
+- Any other value or unset state disables auto-open
+- HTML file is still created regardless of auto-open setting
+- User receives appropriate feedback about file creation and location when auto-open is disabled
+- All existing functionality remains unchanged when environment variable enables auto-open
+- Environment variable is properly documented in README.md
+- Tests cover all scenarios including edge cases and follow established patterns
+
+## Potential Risks and Mitigations
+
+1. **Breaking Change Risk for Existing Users**
+   - Risk: Current users expect auto-open behavior by default
+   - Mitigation: Default to false as specified, which is better for new users. Document the change and migration path clearly.
+
+2. **Environment Service Integration Complexity**
+   - Risk: Adding field to Environment struct might affect other components
+   - Mitigation: Follow established patterns in the codebase for environment variable integration; the Environment struct is designed for extension.
+
+3. **Boolean Parsing Inconsistencies**
+   - Risk: Different boolean representations might cause confusion
+   - Mitigation: Use existing `parse_env` helper and document supported values clearly in README.
+
+4. **API Access Pattern Changes**
+   - Risk: New access pattern might not integrate seamlessly with existing UI code
+   - Mitigation: The `self.api.environment()` pattern is already established and widely used in the UI layer.
+
+## Alternative Approaches
+
+1. **Direct Environment Variable Check in UI**
+   - Alternative: Check environment variable directly in UI layer using `get_env_var()`
+   - Trade-offs: Simpler implementation but doesn't follow the architectural pattern of centralizing configuration in Environment service
+
+2. **Service Method Approach**
+   - Alternative: Add `should_auto_open_dump()` method to environment service
+   - Trade-offs: More encapsulated but doesn't provide the direct property access pattern requested
+
+3. **Workflow-level Configuration**
+   - Alternative: Add configuration to forge.yaml workflow files
+   - Trade-offs: More discoverable but less flexible than environment variable approach
+
+## Technical Implementation Details
+
+**Environment Struct Field Addition:**
+```rust
+// In crates/forge_domain/src/env.rs
+#[derive(Clone, Debug, Setters)]
+pub struct Environment {
+    // existing fields...
+    pub auto_open_dump: bool,
+}
+```
+
+**Environment Variable Parsing:**
+```rust
+// In crates/forge_infra/src/env.rs get() method
+let auto_open_dump = parse_env::<bool>("FORGE_DUMP_AUTO_OPEN").unwrap_or(false);
+
+Environment {
+    // existing field assignments...
+    auto_open_dump,
+}
+```
+
+**UI Integration:**
+```rust
+// In crates/forge_main/src/ui.rs dump methods
+if self.api.environment().auto_open_dump {
+    open::that(path.as_str()).ok();
+} else {
+    // Provide user feedback about file location
+}
+```
+
+**README Documentation Pattern:**
+```markdown
+<details>
+<summary><strong>Tool Configuration</strong></summary>
+
+Configuring the tool calls settings:
+
+```bash
+# .env
+FORGE_TOOL_TIMEOUT=300         # Maximum execution time in seconds for a tool (default: 300)
+FORGE_DUMP_AUTO_OPEN=false     # Automatically open dump files in browser (default: false)
+```
+
+</details>
+```
+
+This plan follows established architectural patterns in the Forge codebase while providing the requested `self.api.environment().auto_open_dump` access pattern and comprehensive documentation.

plans/2025-09-13-dynamic-agent-slash-commands-v3.md

@@ -0,0 +1,144 @@
+ # Dynamic Agent-Specific Slash Commands Implementation Plan
+
+## Objective
+
+Implement dynamic registration of agent-specific slash commands that automatically creates commands like `/agent-foo` and `/agent-bar` based on the agents returned by the API. This feature will provide direct shortcuts for agent switching without requiring the interactive selection interface of the existing `/agent` command. The implementation follows the existing command registration pattern used by workflow commands.
+
+## Implementation Plan
+
+- [x] **Task 1. Add AgentSwitch Command Variant**
+   
+   **Rationale**: Extend the existing Command enum with a new variant for direct agent switching, following the pattern of other command variants like Custom(PartialEvent).
+   
+   - Add `AgentSwitch(String)` variant to `Command` enum in `crates/forge_main/src/model.rs:221`
+   - Add corresponding name() method case at `crates/forge_main/src/model.rs:325`
+   - Add usage description using the strum property pattern similar to existing commands
+   - Update command parsing logic to route agent-specific commands to this variant
+
+- [x] **Task 2. Extend ForgeCommandManager with Agent Command Registration**
+   
+   **Rationale**: Follow the existing pattern used by `register_all()` method for workflow commands, but create a separate method for agent-based dynamic commands to maintain separation of concerns.
+   
+   - Add `register_agent_commands(&self, agents: Vec<Agent>)` method to `ForgeCommandManager` at `crates/forge_main/src/model.rs:63`
+   - Implement agent ID sanitization for valid command names (replace special chars, handle spaces)
+   - Generate `ForgeCommand` objects with pattern `/agent-{sanitized_id}` following workflow command format
+   - Add agent-specific description format like "🤖 Switch to {title} agent" 
+   - Store agent ID in the `value` field for later retrieval during parsing
+
+- [x] **Task 3. Update ForgeCommandManager Command Parsing**
+   
+   **Rationale**: Extend the existing parsing logic in the `parse()` method to detect and handle agent-specific command patterns, similar to how workflow custom commands are handled.
+   
+   - Extend the `parse()` method fallback logic at `crates/forge_main/src/model.rs:192` to check for agent commands
+   - Detect commands matching `/agent-*` pattern before falling back to custom commands
+   - Extract agent ID from command names by removing `/agent-` prefix
+   - Return `Command::AgentSwitch(agent_id)` for valid agent commands
+   - Maintain existing error handling for invalid commands
+
+- [x] **Task 4. Integrate Agent Command Registration into UI Initialization**
+   
+   **Rationale**: Agent commands must be registered during UI initialization right after workflow commands, ensuring they are available throughout the session.
+   
+   - Modify `init_state()` method in `crates/forge_main/src/ui.rs:700` to register agent commands
+   - Load agents using existing `self.api.get_agents().await?` after line 720
+   - Call `self.command.register_agent_commands(agents)` after workflow registration
+   - Add error handling that logs warnings for agent loading failures without breaking initialization
+   - Ensure agent commands are refreshed on subsequent `init_state()` calls
+
+- [x] **Task 5. Implement Agent Switch Command Handler**
+   
+   **Rationale**: Create a streamlined handler for direct agent switching in the main UI command processing loop, reusing existing agent switching logic for consistency.
+   
+   - Add handler for `Command::AgentSwitch(agent_id)` in the UI command processing loop (around `crates/forge_main/src/ui.rs`)
+   - Validate that the requested agent exists by checking against loaded agents
+   - Reuse existing `on_agent_change()` logic for the actual switch operation
+   - Provide user feedback for successful switches using existing notification patterns
+   - Handle error cases with clear messages when agent is not found or unavailable
+
+- [x] **Task 6. Implement Agent ID Sanitization Logic**
+   
+   **Rationale**: Ensure generated command names are valid shell command identifiers and don't conflict with existing system commands.
+   
+   - Create helper function to sanitize agent IDs for command names
+   - Convert spaces and special characters to hyphens or underscores
+   - Handle edge cases like empty IDs, numeric-only IDs, or very long IDs
+   - Validate against existing built-in command names (`/agent`, `/forge`, `/muse`, etc.)
+   - Provide deterministic fallback naming for problematic agent IDs
+
+- [x] **Task 7. Update register_all Method to Handle Combined Registration**
+   
+   **Rationale**: Ensure the existing workflow command registration doesn't interfere with agent commands and that both can coexist in the command registry.
+   
+   - Modify `register_all()` method at `crates/forge_main/src/model.rs:78` to preserve existing agent commands
+   - Ensure agent commands are not overwritten when workflow commands are re-registered
+   - Maintain proper sorting of all commands (workflow + agent) for consistent completion behavior
+   - Add logic to clear only workflow-related commands while preserving agent commands
+
+- [x] **Task 8. Add Command Validation and Conflict Resolution**
+   
+   **Rationale**: Prevent agent command names from conflicting with built-in commands or workflow commands, ensuring system stability.
+   
+   - Add validation in `register_agent_commands()` to check for name conflicts
+   - Implement conflict resolution strategy (e.g., add numeric suffix for duplicates)
+   - Log warnings for agents that can't be registered due to naming conflicts
+   - Ensure built-in commands always take precedence over dynamic agent commands
+   - Provide clear error messages when agent commands can't be registered
+
+## Verification Criteria
+
+- **Agent Command Registration**: All discovered agents generate corresponding `/agent-{id}` commands in the command registry
+- **Command Parsing**: Agent-specific commands are correctly parsed and routed to `Command::AgentSwitch` variant
+- **Agent Switching**: Direct agent switching via generated commands functions identically to the interactive `/agent` command
+- **Command Completion**: Agent commands appear in autocompletion alongside workflow and built-in commands
+- **Error Handling**: Invalid agent commands provide clear error messages without crashing the system
+- **Name Validation**: Generated command names are valid and don't conflict with existing commands
+- **Session Persistence**: Agent commands remain available throughout the session and are properly refreshed
+- **Integration**: Agent command registration doesn't interfere with existing workflow command functionality
+
+## Potential Risks and Mitigations
+
+### **Risk: Command Name Collisions with Built-in Commands**
+**Impact**: Agent IDs might conflict with existing built-in commands like `/agent`, `/forge`, `/muse`
+**Mitigation**: 
+- Use consistent `/agent-{id}` prefixing to avoid conflicts with built-in commands
+- Implement validation to check against all existing command names during registration
+- Skip registration for agents whose sanitized IDs would conflict with built-in commands
+
+### **Risk: Agent Loading Performance Impact**  
+**Impact**: Loading agents during UI initialization could slow startup
+**Mitigation**:
+- Agent loading already happens during UI initialization for other purposes
+- Agent command registration is a lightweight operation that just creates ForgeCommand objects
+- Implement timeout and graceful degradation if agent loading takes too long
+
+### **Risk: Command Registry State Consistency**
+**Impact**: Agent commands might become stale if agents are reloaded but commands aren't refreshed
+**Mitigation**:
+- Register agent commands on every `init_state()` call, which handles session refresh
+- Clear existing agent commands before re-registering to prevent stale entries
+- Use the existing agent loading cache to minimize performance impact
+
+### **Risk: Agent ID Edge Cases**
+**Impact**: Unusual agent IDs (empty, special chars, very long) could break command generation
+**Mitigation**:
+- Implement robust agent ID sanitization with fallback strategies
+- Skip agents with IDs that can't be sanitized to valid command names
+- Log warnings for problematic agent IDs to aid debugging
+
+## Alternative Approaches
+
+### **1. Extend Existing /agent Command**: Add parameter support like `/agent foo` instead of creating separate commands
+   **Trade-offs**: Simpler implementation but doesn't provide individual completion entries and requires parameter parsing
+
+### **2. Use Different Prefix Pattern**: Use `/switch-{agent}` or `/to-{agent}` instead of `/agent-{agent}`
+   **Trade-offs**: Different naming might be clearer but `/agent-` prefix clearly indicates relationship to the `/agent` command
+
+### **3. Register Agent Commands as Custom Commands**: Treat agent commands as workflow-style custom commands
+   **Trade-offs**: Could reuse more existing logic but would blur the distinction between user-defined and system-generated commands
+
+## Future Enhancements
+
+- **Agent Command Grouping**: Display agent commands in a separate section in help/completion
+- **Agent Command Aliases**: Allow agents to define custom short aliases in their metadata
+- **Dynamic Command Refresh**: Automatically refresh agent commands when agent list changes without full UI reinitialization
+- **Agent Command History**: Track usage patterns and prioritize frequently used agents in completion

plans/2025-09-13-forge-history-file-env-var-v2.md

@@ -0,0 +1,207 @@
+# Per-Project Custom History File Support via Environment Variable
+
+## Objective
+
+Implement support for per-project custom history files through the `FORGE_HISTORY_FILE` environment variable, allowing users to maintain separate prompt histories for different projects while preserving the current default behavior. The implementation will use the existing global history file by default and only override when the environment variable is explicitly set, supporting both absolute and relative paths with proper Windows compatibility.
+
+## Current Analysis
+
+### Current State Assessment
+
+Based on the codebase analysis, the current history implementation:
+
+**History File Location**: Currently determined by `Environment::history_path()` method in `crates/forge_domain/src/env.rs:68-70`, which returns `self.base_path.join(".forge_history")` - a single global file.
+
+**History Usage**: History is initialized in `crates/forge_main/src/editor.rs:68-71` using `FileBackedHistory::with_file()` with the path from `env.history_path()`.
+
+**Environment Configuration**: Environment variables are parsed in `ForgeEnvironmentInfra::get()` method in `crates/forge_infra/src/env.rs:39-78`, which already supports parsing custom environment variables like `FORGE_DUMP_AUTO_OPEN`, `FORGE_TOOL_TIMEOUT`, etc.
+
+**Default Behavior Priority**: The implementation prioritizes maintaining existing behavior, only overriding when users explicitly set the environment variable.
+
+## Implementation Plan
+
+### 1. Environment Variable Support
+- [ ] **Task 1**: Add `FORGE_HISTORY_FILE` environment variable support to `ForgeEnvironmentInfra::get()` method
+  - **Location**: `crates/forge_infra/src/env.rs:39-78`
+  - **Rationale**: This is where all environment variable parsing occurs, following the established pattern of other FORGE_* environment variables
+  - **Implementation**: Use existing `parse_env::<String>()` function to retrieve the custom history file path, keeping it optional to preserve default behavior
+
+### 2. Environment Struct Extension
+- [ ] **Task 2**: Add `custom_history_path` field to `Environment` struct to store the resolved history file path
+  - **Location**: `crates/forge_domain/src/env.rs:16-61`
+  - **Rationale**: Following the established pattern of storing environment-specific configurations as fields, enabling proper dependency injection and testing
+  - **Implementation**: Add `Option<PathBuf>` field with proper serialization attributes to maintain backward compatibility
+
+### 3. History Path Resolution Enhancement with Relative Path Support
+- [ ] **Task 3**: Modify `Environment::history_path()` to support custom path resolution with relative path handling
+  - **Location**: `crates/forge_domain/src/env.rs:68-70`
+  - **Rationale**: This method is the single source of truth for history file location and needs to handle environment variable override while maintaining current default behavior
+  - **Implementation**: 
+    - Check for custom_history_path first (from environment variable)
+    - If relative path, resolve against current working directory using `std::env::current_dir()`
+    - If absolute path, use as-is
+    - Fall back to current default behavior if no environment variable is set
+    - Handle path canonicalization for Windows compatibility
+
+### 4. Windows-Specific Path Handling
+- [ ] **Task 4**: Implement Windows-specific path normalization and validation
+  - **Location**: History path resolution logic in Environment
+  - **Rationale**: Windows has different path conventions (backslashes, drive letters, UNC paths) that require special handling
+  - **Implementation**:
+    - Use `PathBuf::canonicalize()` for path normalization when possible
+    - Handle Windows drive letter paths (C:\, D:\, etc.)
+    - Support UNC paths (\\server\share) on Windows
+    - Ensure proper path separator handling across platforms
+    - Add Windows-specific error handling for invalid drive letters
+
+### 5. Path Creation and Validation
+- [ ] **Task 5**: Add robust path creation and validation logic
+  - **Location**: History path resolution logic in Environment
+  - **Rationale**: Custom paths may point to non-existent directories or have permission issues
+  - **Implementation**:
+    - Create parent directories if they don't exist using `std::fs::create_dir_all()`
+    - Validate write permissions before attempting to use custom path
+    - Provide fallback to default path with user warning on failure
+    - Add specific error messages for common issues (permissions, invalid paths, disk space)
+
+<task_status>
+[x]: DONE - Task 1: Add FORGE_HISTORY_FILE environment variable support
+[~]: IN_PROGRESS - Task 2: Add custom_history_path field to Environment struct  
+[ ]: PENDING - Task 3: Modify Environment::history_path() with relative path support
+[ ]: PENDING - Task 4: Implement Windows-specific path handling
+[ ]: PENDING - Task 5: Add path creation and validation logic
+</task_status>
+
+## Verification Criteria
+
+### Default Behavior Preservation
+- Existing installations continue to use global history file without any configuration changes
+- No performance impact when environment variable is not set
+- Zero breaking changes to existing APIs or user workflows
+
+### Environment Variable Functionality
+- Environment variable `FORGE_HISTORY_FILE` successfully overrides default history location only when set
+- Absolute paths specified in environment variable are used directly without modification
+- Relative paths are resolved relative to current working directory where forge is invoked
+- Missing or unset environment variable maintains exact current behavior
+
+### Path Resolution Support
+- Relative paths like `./project-history` resolve correctly from current directory
+- Relative paths like `../shared/history` work across different directory structures
+- Absolute paths work on both Unix (`/home/user/history`) and Windows (`C:\Users\user\history`)
+- Windows UNC paths (`\\server\share\history`) are supported correctly
+
+### Cross-Platform Compatibility
+- Path handling works identically on Windows, macOS, and Linux
+- Windows drive letter paths (C:\, D:\, etc.) are handled correctly
+- Unix-style paths work on all Unix-like systems
+- Path separators are normalized automatically by PathBuf
+
+### Error Handling and Recovery
+- Non-existent parent directories are created automatically with appropriate permissions
+- Invalid paths generate clear, actionable error messages
+- Permission issues trigger graceful fallback to default location with user notification
+- Disk space issues are detected and reported appropriately
+
+## Potential Risks and Mitigations
+
+### 1. **Backward Compatibility**
+   **Risk**: Changes might affect existing user workflows
+   **Mitigation**: Strict preservation of default behavior; environment variable is purely additive
+
+### 2. **Windows Path Complexity**
+   **Risk**: Windows path handling edge cases (UNC, long paths, reserved names)
+   **Mitigation**: Use Rust's built-in PathBuf and extensive Windows-specific testing; handle reserved names (CON, PRN, etc.)
+
+### 3. **Relative Path Confusion**
+   **Risk**: Users might not understand relative path resolution context
+   **Mitigation**: Clear documentation explaining resolution is relative to working directory, not forge binary location
+
+### 4. **Directory Creation Permissions**
+   **Risk**: Creating parent directories might fail due to permissions
+   **Mitigation**: Graceful fallback with informative error messages; suggest alternative paths
+
+### 5. **Path Traversal Concerns**
+   **Risk**: Users specifying paths outside intended areas
+   **Mitigation**: Document security considerations; users control their own environment so flexibility is acceptable
+
+## Alternative Approaches
+
+### 1. **Always Use Current Directory**: Default to `./.forge_history` instead of global file
+   **Trade-offs**: More intuitive per-project behavior but breaks existing user expectations
+
+### 2. **Auto-Detection**: Automatically look for `.forge_history` in current directory first
+   **Trade-offs**: Zero configuration but might create unexpected behavior changes
+
+### 3. **Forge.yaml Integration**: Add history_file field to project configuration
+   **Trade-offs**: More permanent per-project setting but requires configuration file management
+
+## Implementation Dependencies
+
+### Internal Dependencies
+- Environment variable parsing infrastructure (already exists)
+- FileBackedHistory initialization path (already exists)
+- PathBuf handling utilities (built-in Rust functionality)
+
+### External Dependencies
+- No new external crates required
+- Leverages existing `std::fs`, `std::env`, and `std::path` functionality
+- Uses current `dirs` crate for default path resolution
+
+### Testing Requirements
+- Unit tests for environment variable parsing with None values
+- Path resolution tests for absolute and relative paths
+- Cross-platform integration tests (Windows, macOS, Linux)
+- Edge case tests for Windows-specific path formats
+- Permission and error handling tests
+- Backward compatibility verification tests
+
+## Success Metrics
+
+### Functional Success
+- Users can set `FORGE_HISTORY_FILE=./project-history` for relative paths
+- Users can set `FORGE_HISTORY_FILE=/absolute/path/history` for absolute paths
+- Windows users can use `FORGE_HISTORY_FILE=C:\Users\Name\history` successfully
+- Unset environment variable maintains exact current behavior
+
+### User Experience Success
+- Zero configuration change required for existing users
+- Clear error messages guide users when path issues occur
+- Seamless cross-platform experience with same environment variable
+
+### Developer Experience Success
+- Implementation follows existing codebase patterns
+- Windows-specific considerations are well-documented
+- Error handling provides actionable feedback for debugging
+
+## Windows-Specific Considerations
+
+### Path Format Support
+- **Drive Letters**: Support for `C:\path\to\history`, `D:\projects\history`
+- **UNC Paths**: Support for `\\server\share\history` network paths
+- **Long Paths**: Handle Windows long path limitations (>260 characters) appropriately
+- **Reserved Names**: Detect and warn about reserved Windows filenames (CON, PRN, AUX, etc.)
+
+### Path Separator Handling
+- Accept both forward slashes (`C:/path/to/history`) and backslashes (`C:\path\to\history`)
+- Normalize path separators using Rust's PathBuf automatic conversion
+- Ensure relative path resolution works with Windows-style separators
+
+### Permission and Security
+- Handle Windows-specific permission models (ACLs vs Unix permissions)
+- Detect when paths point to system directories that may be restricted
+- Provide Windows-appropriate error messages for common permission issues
+
+### Environment Variable Examples
+```bash
+# Unix/Linux/macOS examples
+FORGE_HISTORY_FILE=./project-history
+FORGE_HISTORY_FILE=../shared/team-history
+FORGE_HISTORY_FILE=/home/user/forge-histories/project1
+
+# Windows examples
+FORGE_HISTORY_FILE=.\project-history
+FORGE_HISTORY_FILE=..\shared\team-history
+FORGE_HISTORY_FILE=C:\Users\Name\ForgeHistories\project1
+FORGE_HISTORY_FILE=\\server\share\team-histories\project1
+```

plans/2025-09-14-explicit-conversation-id-generation-v1.md

@@ -0,0 +1,173 @@
+# Explicit Conversation ID Generation Implementation Plan
+
+## Objective
+
+Implement explicit conversation ID generation to enable multiple terminal sessions to maintain separate conversation contexts. This approach eliminates output parsing challenges by requiring users to explicitly generate and manage conversation IDs.
+
+## Research Summary
+
+Based on codebase analysis, I found:
+
+1. **Current CLI Structure**: `--resume` flag exists in `crates/forge_main/src/cli.rs:64` and automatically loads the most recent conversation
+2. **Conversation ID Management**: `ConversationId` is a UUID-based type in `crates/forge_domain/src/conversation.rs:15` with `generate()` and `parse()` methods
+3. **Resume Logic**: Current `handle_resume()` in `crates/forge_main/src/ui.rs:265` uses `api.last_conversation()` to find the most recent conversation
+4. **Shell Plugin**: Current transformation in `shell-plugin/forge.plugin.zsh:18` uses `--resume` without parameters
+5. **Database**: Repository has `get_conversation()` method for retrieving specific conversations by ID
+6. **Terminal Command**: Existing `TopLevelCommand::Term` in `crates/forge_main/src/cli.rs:100` handles terminal-related operations
+
+## Implementation Plan
+
+### Phase 1: CLI Parameter Enhancement
+
+- [x] **Task 1.1: Add conversation ID generation parameter**
+  - Add `--generate-conversation-id` flag to CLI structure
+  - Update argument parsing to handle conversation ID generation
+  - Add validation and error handling for generation mode
+  - Rationale: Provides explicit mechanism for users to create conversation IDs
+
+- [x] **Task 1.2: Modify --resume to require conversation ID**
+  - Update `--resume` parameter to require `--conversation-id` argument
+  - Add clap validation to enforce this requirement
+  - Update help text and documentation for new behavior
+  - Rationale: Changes resume semantics from "find most recent" to "resume specific conversation"
+
+- [x] **Task 1.3: Add --conversation-id parameter**
+  - Add `--conversation-id` parameter for specifying conversation ID
+  - Implement conversation ID validation using existing `ConversationId::parse()`
+  - Add error handling for invalid conversation ID formats
+  - Rationale: Allows users to specify which conversation to use for new operations
+
+### Phase 2: Core Logic Implementation
+
+- [x] **Task 2.1: Implement conversation ID generation logic**
+  - Create `handle_generate_conversation_id()` method in UI layer
+  - Use existing `ConversationId::generate()` method for ID creation
+  - Output generated ID to stdout and exit cleanly
+  - Rationale: Provides the core functionality for creating new conversation IDs
+
+- [x] **Task 2.2: Update resume logic for explicit conversation loading**
+  - Modify `handle_resume()` to use `api.get_conversation()` instead of `api.last_conversation()`
+  - Add conversation existence validation and error handling
+  - Update user messages to show specific conversation being resumed
+  - Rationale: Changes resume behavior to work with explicit conversation IDs
+
+- [x] **Task 2.3: Update conversation creation to accept explicit IDs**
+  - Modify conversation initialization to use provided conversation ID when available
+  - Add validation to ensure conversation ID uniqueness when creating new conversations
+  - Implement proper error handling for duplicate conversation IDs
+  - Rationale: Allows users to create conversations with specific IDs
+
+### Phase 3: Shell Plugin Integration
+
+- [x] **Task 3.1: Create forge-term command for conversation ID generation**
+  - Add `forge-term` function to shell plugin for ID generation
+  - Implement conversation ID storage in shell environment variables
+  - Add user feedback and error handling for generation process
+  - Rationale: Provides user-friendly interface for managing conversation IDs
+
+- [x] **Task 3.2: Update command transformation for explicit conversation IDs**
+  - Modify `??` commands to use `--resume --conversation-id $FORGE_CONVERSATION_ID`
+  - Modify `?` commands to use `--conversation-id $FORGE_CONVERSATION_ID` when available
+  - Add fallback behavior when no conversation ID is set
+  - Rationale: Integrates new conversation ID management with existing shell workflow
+
+- [x] **Task 3.3: Add conversation ID lifecycle management**
+  - Implement conversation ID validation before command execution
+  - Add error handling for missing or invalid conversation IDs
+  - Implement cleanup and reset functionality for conversation IDs
+  - Rationale: Ensures robust conversation ID management throughout terminal session
+
+### Phase 4: API and Service Layer Updates
+
+- [x] **Task 4.1: Update API layer to support conversation ID parameters**
+  - Add methods to API trait for conversation ID validation and retrieval
+  - Implement conversation existence checking functionality
+  - Add proper error handling for conversation-related operations
+  - Rationale: Provides necessary API support for explicit conversation management
+
+- [x] **Task 4.2: Update service layer for conversation ID operations**
+  - Add conversation validation methods to conversation service
+  - Implement conversation ID uniqueness checking
+  - Add error handling for conversation-related service operations
+  - Rationale: Ensures service layer supports new conversation ID requirements
+
+### Phase 5: Testing and Validation
+
+- [x] **Task 5.1: Create unit tests for conversation ID generation**
+  - Test `ConversationId::generate()` produces valid unique IDs
+  - Test conversation ID parsing and validation
+  - Test error handling for invalid conversation ID formats
+  - Rationale: Ensures conversation ID generation works correctly
+
+- [x] **Task 5.2: Create integration tests for resume functionality**
+  - Test resuming existing conversations with explicit IDs
+  - Test error handling for non-existent conversation IDs
+  - Test conversation loading and state restoration
+  - Rationale: Verifies that resume functionality works with explicit IDs
+
+- [x] **Task 5.3: Create end-to-end tests for shell plugin integration**
+  - Test conversation ID generation and storage in shell environment
+  - Test command transformation with stored conversation IDs
+  - Test fallback behavior when no conversation ID is available
+  - Rationale: Ensures complete workflow works correctly from shell to application
+
+### Phase 6: Migration and Backward Compatibility
+
+- [x] **Task 6.1: Implement deprecation warnings for old resume behavior**
+  - Add warnings when `--resume` is used without `--conversation-id`
+  - Provide clear migration instructions to users
+  - Implement graceful fallback to current behavior during transition
+  - Rationale: Helps users transition to new behavior without breaking existing workflows
+
+- [x] **Task 6.2: Create migration documentation**
+  - Document breaking changes and migration steps
+  - Provide examples of new workflow patterns
+  - Create troubleshooting guide for common migration issues
+  - Rationale: Ensures users can successfully migrate to new approach
+
+## Verification Criteria
+
+- [x] **Criterion 1: Conversation ID Generation** `forge --generate-conversation-id` produces valid, unique conversation IDs
+- [x] **Criterion 2: Explicit Resume Functionality** `forge --resume --conversation-id <id>` successfully resumes the specified conversation
+- [x] **Criterion 3: Shell Integration** `forge-term generate-conversation-id` properly stores ID in shell environment
+- [x] **Criterion 4: Command Transformation** `?? text` transforms to `forge --resume --conversation-id <id> <<< text` when ID is available
+- [x] **Criterion 5: Error Handling** Invalid conversation IDs produce clear error messages without crashing
+- [x] **Criterion 6: Backward Compatibility** Existing `--resume` behavior works with deprecation warnings during transition
+- [x] **Criterion 7: Multi-Terminal Isolation** Multiple terminals with different conversation IDs maintain separate conversation histories
+
+## Potential Risks and Mitigations
+
+1. **Breaking Changes to Existing Workflows**
+   Mitigation: Implement deprecation warnings and fallback behavior; provide clear migration documentation; maintain backward compatibility during transition period
+
+2. **Conversation ID Collisions**
+   Mitigation: Use UUID-based generation which has extremely low collision probability; implement uniqueness validation when creating conversations
+
+3. **Shell Environment Variable Conflicts**
+   Mitigation: Use unique variable names (`FORGE_CONVERSATION_ID`); implement proper variable scoping; add validation for stored IDs
+
+4. **User Confusion with New Workflow**
+   Mitigation: Provide clear documentation and examples; implement helpful error messages; add interactive guidance when possible
+
+5. **Database Performance Impact**
+   Mitigation: Leverage existing conversation retrieval methods; ensure proper indexing on conversation_id column; monitor query performance
+
+6. **Migration Complexity**
+   Mitigation: Implement gradual migration approach; provide automated migration tools; offer support during transition period
+
+## Alternative Approaches
+
+1. **Optional Session ID Parameter**: Keep existing `--resume` behavior and add optional `--session-id` parameter
+   Trade-offs: Less breaking changes, but more complex implementation with two parallel behaviors
+
+2. **Environment Variable Only**: Use only environment variables without CLI parameter changes
+   Trade-offs: Simpler CLI changes, but less explicit control and harder to debug
+
+3. **Configuration File Based**: Store conversation IDs in configuration files instead of environment variables
+   Trade-offs: More persistent across shell sessions, but adds file management complexity
+
+4. **Hybrid Approach**: Support both explicit conversation IDs and automatic session management
+   Trade-offs: More flexible, but significantly more complex implementation and maintenance
+
+5. **Separate Command Set**: Create new commands (`forge-resume`, `forge-new`) alongside existing ones
+   Trade-offs: No breaking changes, but confusing user experience with multiple ways to do the same thing

plans/2025-09-27-AppConfigRepository_Implementation-v1.md

@@ -0,0 +1,122 @@
+# AppConfigRepository Implementation Plan
+
+## Objective
+
+Create a new AppConfigRepository following the established repository pattern in the codebase, and update all direct AppConfig usage to use the new repository pattern instead of the current AppConfigService implementation.
+
+## Implementation Plan
+
+### Phase 1: Repository Pattern Implementation
+
+- [x] **Create AppConfigRepository trait in forge_services/src/infra.rs**
+  - Define async methods for CRUD operations on AppConfig
+  - Follow the same pattern as ConversationRepository
+  - Include methods: get_app_config() -> Option<AppConfig>, set_app_config(config: &AppConfig) -> anyhow::Result<()>
+
+- [x] **Create AppConfigRepositoryImpl in forge_infra crate**
+  - Create new file: crates/forge_infra/src/database/repository/app_config.rs
+  - Implement the AppConfigRepository trait
+  - Handle file-based storage operations similar to current ForgeConfigService
+  - Include comprehensive tests following the project's testing patterns
+
+- [x] **Update forge_infra/src/database/mod.rs**
+  - Add module declaration for app_config repository
+  - Export the new AppConfigRepositoryImpl
+
+- [x] **Update ForgeInfra struct**
+  - Add app_config_repository field to ForgeInfra in crates/forge_infra/src/forge_infra.rs
+  - Initialize the repository in the constructor
+  - Implement AppConfigRepository trait for ForgeInfra by delegating to the repository
+
+### Phase 2: Service Layer Updates
+
+- [x] **Update ForgeConfigService implementation**
+  - Modify crates/forge_services/src/app_config.rs to use AppConfigRepository instead of direct file operations
+  - Replace direct file read/write with repository method calls
+  - Maintain the same AppConfigService interface for backward compatibility
+
+- [x] **Update Services trait integration**
+  - Add AppConfigRepository associated type to the Services trait in crates/forge_app/src/services.rs
+  - Add app_config_repository() method to Services trait
+  - Update the trait implementation in forge_services to return the repository
+
+### Phase 3: Direct Usage Migration
+
+- [x] **Update Authenticator class**
+  - Modify crates/forge_app/src/authenticator.rs to use AppConfigRepository through the services layer
+  - Replace direct AppConfigService calls with repository-based operations
+
+- [x] **Update forge_api implementations**
+  - Modify crates/forge_api/src/forge_api.rs and crates/forge_api/src/api.rs
+  - Ensure API layer uses the updated service layer with repository pattern
+
+- [x] **Update UI components**
+  - Modify crates/forge_main/src/ui.rs to use the updated service layer
+  - Ensure no direct AppConfig instantiation remains
+
+- [x] **Update authentication service**
+  - Modify crates/forge_services/src/auth.rs to use repository pattern
+  - Ensure LoginInfo and InitAuth operations work with the new pattern
+
+### Phase 4: Testing and Verification
+
+- [x] **Create comprehensive unit tests**
+  - Test AppConfigRepositoryImpl with various scenarios (file exists, doesn't exist, invalid JSON)
+  - Test error handling and edge cases
+  - Follow the project's testing pattern with fixtures, actual, expected structure
+
+- [x] **Create integration tests**
+  - Test the complete flow from API to repository
+  - Verify backward compatibility of AppConfigService interface
+
+- [x] **Update existing tests**
+  - Modify any tests that directly instantiate AppConfig to use proper fixtures
+  - Ensure all tests pass with the new repository pattern
+
+### Phase 5: Documentation and Cleanup
+
+- [x] **Remove deprecated direct usage**
+  - Remove any remaining direct file operations in ForgeConfigService
+  - Ensure all AppConfig operations go through the repository
+
+- [x] **Add documentation**
+  - Document the new repository pattern in code comments
+  - Update any architectural documentation if it exists
+
+- [x] **Verify consistency**
+  - Ensure the new pattern follows the same style as ConversationRepository
+  - Verify all async trait implementations are consistent
+
+## Verification Criteria
+
+- **Repository Pattern Compliance**: AppConfigRepository follows the same pattern as ConversationRepository with proper async traits and error handling
+- **Backward Compatibility**: All existing AppConfigService functionality continues to work without breaking changes
+- **Test Coverage**: New repository implementation has comprehensive unit tests with >90% coverage
+- **Integration Success**: All existing functionality (login, authentication, config management) works seamlessly with the new repository
+- **Code Quality**: New code passes all linting rules and follows project conventions
+- **Performance**: No performance degradation compared to the current file-based implementation
+
+## Potential Risks and Mitigations
+
+1. **Breaking Existing Functionality**
+   Mitigation: Maintain the AppConfigService interface and gradually migrate internal implementations while preserving public APIs
+
+2. **File System Access Complexity**
+   Mitigation: Reuse existing file infrastructure patterns from ForgeConfigService and follow the same error handling approach
+
+3. **Testing Integration Points**
+   Mitigation: Create mock implementations for testing and follow the established testing patterns used for ConversationRepository
+
+4. **Async Trait Complexity**
+   Mitigation: Follow the exact same async trait patterns used in ConversationRepository and other existing repositories
+
+## Alternative Approaches
+
+1. **Direct Migration**: Completely replace AppConfigService with repository pattern in one step
+   Trade-offs: Higher risk but simpler final architecture
+
+2. **Adapter Pattern**: Create an adapter that wraps the current service
+   Trade-offs: Lower risk but adds an extra abstraction layer
+
+3. **Hybrid Approach**: Keep both patterns and gradually deprecate the service
+   Trade-offs: Maintains maximum backward compatibility but increases code complexity

plans/2026-01-22-Fix Auto-Sync Workspace Registration Issue-v1.md

@@ -0,0 +1,135 @@
+# Fix Auto-Sync Workspace Registration Issue
+
+**Issue:** [#2288](https://github.com/tailcallhq/forgecode/issues/2288)
+
+**Problem:** The zsh plugin automatically syncs workspaces in the background on every directory change, causing unintended parent directories to be registered as workspaces. When users run `forge workspace list`, ancestor directories appear as "Current" instead of the actual working directory.
+
+**Root Cause:** `_forge_start_background_sync()` in `shell-plugin/lib/helpers.zsh:114-131` unconditionally runs `forge workspace sync` without checking if the workspace or its ancestors are already registered.
+
+---
+
+## Objective
+
+Prevent auto-sync from creating unintended workspace registrations while maintaining the convenience of automatic syncing for already-indexed workspaces.
+
+---
+
+## Implementation Plan
+
+### Phase 1: Add Workspace Detection Command
+
+- [ ] Add new CLI subcommand `forge workspace is-indexed [PATH]` that checks if a path (or any ancestor) is already registered as a workspace
+- [ ] Implement in `crates/forge_main/src/cli.rs` - add `IsIndexed` variant to `WorkspaceCommand` enum
+- [ ] Add handler in `crates/forge_main/src/ui.rs` that calls existing `is_indexed()` service method
+- [ ] The command should return exit code 0 if indexed, exit code 1 if not indexed
+- [ ] Output should be silent by default (only exit code matters for scripting)
+- [ ] Add optional `--verbose` flag to show which workspace was found (exact or ancestor)
+
+### Phase 2: Update Zsh Background Sync Logic
+
+- [ ] Modify `_forge_start_background_sync()` in `shell-plugin/lib/helpers.zsh:114-131`
+- [ ] Before running sync, call `$_FORGE_BIN workspace is-indexed "$workspace_path"`
+- [ ] Check exit code: if non-zero (not indexed), skip the sync and return early
+- [ ] Only proceed with background sync if exit code is 0 (workspace or ancestor is already indexed)
+- [ ] Add debug logging (when `FORGE_DEBUG=true`) to indicate when sync is skipped
+
+### Phase 3: Handle Initial Workspace Registration
+
+- [ ] Ensure manual `forge workspace sync` still works for first-time registration
+- [ ] Update documentation to clarify the auto-sync behavior (only syncs already-registered workspaces)
+- [ ] Consider adding a helper message when users first cd into a new directory that suggests running `forge workspace sync` to enable auto-sync
+
+### Phase 4: Update Workspace List Display
+
+- [ ] Enhance `on_list_workspaces()` in `crates/forge_main/src/ui.rs:3266-3311` to distinguish between exact match and ancestor match
+- [ ] When current workspace is an ancestor match, display as `[Current via ancestor]` or similar
+- [ ] Show the actual current directory path in the output when it differs from the workspace path
+
+---
+
+## Verification Criteria
+
+### Before Fix
+- [ ] Run `cd /Users/username` (parent directory)
+- [ ] Run `forge workspace sync` once
+- [ ] Run `cd /Users/username/Documents/Projects/forge` (subdirectory)
+- [ ] Trigger zsh accept-line (press Enter on any command)
+- [ ] Run `forge workspace list`
+- [ ] Verify: `/Users/username/Documents/Projects/forge` is incorrectly registered as a workspace
+
+### After Fix
+- [ ] Clean database and repeat above steps
+- [ ] Run `cd /Users/username/Documents/Projects/forge`
+- [ ] Trigger zsh accept-line (press Enter)
+- [ ] Run `forge workspace list`
+- [ ] Verify: Only `/Users/username` appears (no auto-sync of subdirectory)
+- [ ] Verify: List shows `[Current via ancestor]` or similar indication
+- [ ] Run explicit `forge workspace sync` in subdirectory
+- [ ] Verify: Now subdirectory is registered and will auto-sync on future visits
+
+### Edge Cases
+- [ ] Test behavior when no workspace exists at all (should not auto-sync)
+- [ ] Test behavior in deeply nested directories (should find closest ancestor)
+- [ ] Test behavior when `FORGE_SYNC_ENABLED=false` (should still respect flag)
+- [ ] Test manual sync in new directory (should still work)
+
+---
+
+## Potential Risks and Mitigations
+
+### Risk 1: Breaking Existing User Workflows
+**Mitigation:** Users who rely on automatic workspace creation will need to run `forge workspace sync` once per workspace. This is a one-time migration cost for better UX long-term.
+
+### Risk 2: Performance Impact
+**Mitigation:** The `workspace is-indexed` check is a fast database query (already exists in `is_indexed()` method). It should add negligible overhead.
+
+### Risk 3: Race Conditions
+**Mitigation:** The check and sync are not atomic, but this is acceptable - worst case, a sync happens when it shouldn't have. No data corruption risk.
+
+---
+
+## Alternative Approaches
+
+### Alternative 1: Opt-in Auto-Sync
+Instead of checking if workspace exists, require users to explicitly enable auto-sync per workspace via a flag or configuration file.
+
+**Pros:** More explicit control  
+**Cons:** More complex UX, requires additional configuration management
+
+### Alternative 2: Display-Only Fix
+Just improve the workspace list display to show `[Current via ancestor]` without changing auto-sync behavior.
+
+**Pros:** Simpler implementation, no behavior changes  
+**Cons:** Doesn't solve the root problem of unintended workspace registrations
+
+### Alternative 3: Auto-Sync with Depth Limit
+Only auto-sync directories within N levels of an existing workspace.
+
+**Pros:** Prevents deep directory pollution  
+**Cons:** Arbitrary limit, still creates unintended workspaces
+
+---
+
+## Dependencies
+
+- No external dependencies
+- Existing `is_indexed()` method in `WorkspaceService` can be reused
+- Zsh plugin already has access to `$_FORGE_BIN` for CLI calls
+
+---
+
+## Testing Strategy
+
+1. **Unit Tests:** Add tests for `workspace is-indexed` command in CLI tests
+2. **Integration Tests:** Test zsh function behavior with mocked CLI commands
+3. **Manual Testing:** Follow verification criteria above
+4. **Regression Testing:** Ensure existing workspace sync functionality unchanged
+
+---
+
+## Documentation Updates
+
+- [ ] Update `shell-plugin/README.md` to explain auto-sync behavior
+- [ ] Add note about one-time `workspace sync` requirement for new workspaces
+- [ ] Document `FORGE_SYNC_ENABLED` environment variable
+- [ ] Update workspace command documentation with new `is-indexed` subcommand

plans/2026-01-22-Fix Auto-Sync Workspace Registration Issue-v2.md

@@ -0,0 +1,138 @@
+# Fix Auto-Sync Workspace Registration Issue
+
+**Issue:** [#2288](https://github.com/tailcallhq/forgecode/issues/2288)
+
+**Problem:** The zsh plugin automatically syncs workspaces in the background on every directory change, causing unintended parent directories to be registered as workspaces. When users run `forge workspace list`, ancestor directories appear as "Current" instead of the actual working directory.
+
+**Root Cause:** `_forge_start_background_sync()` in `shell-plugin/lib/helpers.zsh:114-131` unconditionally runs `forge workspace sync` without checking if the workspace or its ancestors are already registered.
+
+---
+
+## Objective
+
+Prevent auto-sync from creating unintended workspace registrations while maintaining the convenience of automatic syncing for already-indexed workspaces.
+
+---
+
+## Implementation Plan
+
+### Phase 1: Add Porcelain Mode to Workspace Info Command
+
+- [ ] Add `--porcelain` flag to `workspace info` command in `crates/forge_main/src/cli.rs:262-266`
+- [ ] Update `on_workspace_info()` in `crates/forge_main/src/ui.rs:3328-3389` to handle porcelain mode
+- [ ] In porcelain mode, return exit code 0 if workspace exists (Some), exit code 1 if None
+- [ ] In porcelain mode, output should be silent (no text output, only exit code)
+- [ ] Existing behavior (display mode) remains unchanged
+- [ ] This leverages the existing `get_workspace_info()` call which already checks for workspace or ancestor
+
+### Phase 2: Update Zsh Background Sync Logic
+
+- [ ] Modify `_forge_start_background_sync()` in `shell-plugin/lib/helpers.zsh:114-131`
+- [ ] Before running sync, call `$_FORGE_BIN workspace info "$workspace_path" --porcelain 2>/dev/null`
+- [ ] Check exit code: if non-zero (not indexed), skip the sync and return early
+- [ ] Only proceed with background sync if exit code is 0 (workspace or ancestor is already indexed)
+- [ ] Add debug logging (when `FORGE_DEBUG=true`) to indicate when sync is skipped
+- [ ] Ensure the check runs silently (stderr redirect already in place)
+
+### Phase 3: Handle Initial Workspace Registration
+
+- [ ] Ensure manual `forge workspace sync` still works for first-time registration
+- [ ] Update shell-plugin documentation to clarify the auto-sync behavior (only syncs already-registered workspaces)
+- [ ] Consider adding a one-time message when users navigate to unindexed directories suggesting `forge workspace sync`
+
+### Phase 4: Update Workspace List Display (Optional Enhancement)
+
+- [ ] Enhance `on_list_workspaces()` in `crates/forge_main/src/ui.rs:3266-3311` to distinguish between exact match and ancestor match
+- [ ] When current workspace is an ancestor match, display as `[Current via ancestor]` or similar
+- [ ] Show the actual current directory path when it differs from the workspace path
+- [ ] This provides clarity without changing core behavior
+
+---
+
+## Verification Criteria
+
+### Before Fix
+- [ ] Run `cd /Users/username` (parent directory)
+- [ ] Run `forge workspace sync` once
+- [ ] Run `cd /Users/username/Documents/Projects/forge` (subdirectory)
+- [ ] Trigger zsh accept-line (press Enter on any command)
+- [ ] Run `forge workspace list`
+- [ ] Verify: `/Users/username/Documents/Projects/forge` is incorrectly registered as a workspace
+
+### After Fix
+- [ ] Clean database and repeat above steps
+- [ ] Run `cd /Users/username/Documents/Projects/forge`
+- [ ] Trigger zsh accept-line (press Enter)
+- [ ] Run `forge workspace list`
+- [ ] Verify: Only `/Users/username` appears (no auto-sync of subdirectory)
+- [ ] Verify: List shows parent as Current (expected due to ancestor matching)
+- [ ] Run explicit `forge workspace sync` in subdirectory
+- [ ] Verify: Now subdirectory is registered and will auto-sync on future visits
+
+### Edge Cases
+- [ ] Test behavior when no workspace exists at all (should not auto-sync)
+- [ ] Test `forge workspace info` with `--porcelain` flag returns correct exit codes
+- [ ] Test behavior in deeply nested directories (should find closest ancestor)
+- [ ] Test behavior when `FORGE_SYNC_ENABLED=false` (should still respect flag)
+- [ ] Test manual sync in new directory (should still work)
+
+---
+
+## Potential Risks and Mitigations
+
+### Risk 1: Breaking Existing User Workflows
+**Mitigation:** Users who rely on automatic workspace creation will need to run `forge workspace sync` once per workspace. This is a one-time migration cost for better UX long-term.
+
+### Risk 2: Performance Impact
+**Mitigation:** The `workspace info --porcelain` check reuses existing `get_workspace_info()` which is already fast. Negligible overhead.
+
+### Risk 3: Race Conditions
+**Mitigation:** The check and sync are not atomic, but this is acceptable - worst case, a sync happens when it shouldn't have. No data corruption risk.
+
+---
+
+## Alternative Approaches
+
+### Alternative 1: Create New `is-indexed` Subcommand
+Create a dedicated `forge workspace is-indexed` command instead of extending `info`.
+
+**Pros:** Clearer intent, dedicated purpose  
+**Cons:** More API surface, duplicates existing functionality
+
+### Alternative 2: Display-Only Fix
+Just improve the workspace list display to show `[Current via ancestor]` without changing auto-sync behavior.
+
+**Pros:** Simpler implementation, no behavior changes  
+**Cons:** Doesn't solve the root problem of unintended workspace registrations
+
+### Alternative 3: Auto-Sync with Depth Limit
+Only auto-sync directories within N levels of an existing workspace.
+
+**Pros:** Prevents deep directory pollution  
+**Cons:** Arbitrary limit, still creates unintended workspaces
+
+---
+
+## Dependencies
+
+- No external dependencies
+- Reuses existing `get_workspace_info()` method which already handles ancestor matching
+- Zsh plugin already has access to `$_FORGE_BIN` for CLI calls
+
+---
+
+## Testing Strategy
+
+1. **Unit Tests:** Add tests for `workspace info --porcelain` exit codes
+2. **Integration Tests:** Test zsh function behavior with mocked CLI commands
+3. **Manual Testing:** Follow verification criteria above
+4. **Regression Testing:** Ensure existing workspace info functionality unchanged
+
+---
+
+## Documentation Updates
+
+- [ ] Update `shell-plugin/README.md` to explain auto-sync behavior
+- [ ] Add note about one-time `workspace sync` requirement for new workspaces
+- [ ] Document `FORGE_SYNC_ENABLED` environment variable
+- [ ] Update workspace info command help text to mention `--porcelain` flag

plans/2026-03-31-slim-environment-and-add-get-config-v1.md

@@ -0,0 +1,229 @@
+# Slim Environment & Add `get_config` to `EnvironmentInfra`
+
+## Objective
+
+Reduce `Environment` to only the six fields that cannot be sourced from `ForgeConfig` — `os`, `pid`, `cwd`, `home`, `shell`, `base_path` — and expose `ForgeConfig` directly through a new `get_config` method on `EnvironmentInfra`. All service/app code that currently accesses configuration fields through `Environment` will instead call `infra.get_config()` and read the canonical `ForgeConfig` fields directly.
+
+---
+
+## Implementation Plan
+
+### Phase 1 — Slim `Environment` in `forge_domain`
+
+- [ ] Task 1. **Remove all `ForgeConfig`-sourced fields from the `Environment` struct** (`crates/forge_domain/src/env.rs:54-198`).
+
+  The 37 fields below the `// --- Infrastructure-derived fields ---` comment block — including `retry_config`, `max_search_lines`, `fetch_truncation_limit`, `session`, `commit`, `suggest`, `is_restricted`, `tool_supported`, `temperature`, `top_p`, `top_k`, `max_tokens`, `max_tool_failure_per_turn`, `max_requests_per_turn`, `compact`, `updates`, and all remaining mapped fields — must be deleted. Only the six runtime-derived fields remain: `os`, `pid`, `cwd`, `home`, `shell`, `base_path`.
+
+- [ ] Task 2. **Adjust `history_path()` to accept a `custom_path` parameter** (`crates/forge_domain/src/env.rs:267-271`).
+
+  `history_path()` currently reads `self.custom_history_path`, which originates from `ForgeConfig`. Change its signature to `pub fn history_path(&self, custom_path: Option<&PathBuf>) -> PathBuf` so callers pass the value sourced from `ForgeConfig` themselves. Update all call sites accordingly.
+
+- [ ] Task 3. **Remove `apply_op()` from `Environment`** (`crates/forge_domain/src/env.rs:222-261`).
+
+  This method mutates `session`, `commit`, and `suggest` — all fields being removed. The mutation logic will move to the infra layer (see Phase 3). Delete `apply_op` and its `#[cfg(test)]` unit tests that exercise it via `fixture_env`.
+
+- [ ] Task 4. **Remove the `SessionConfig` re-export from `Environment`'s imports if it becomes unused** (`crates/forge_domain/src/env.rs:10-13`).
+
+  After removing `session`, `commit`, `suggest` from `Environment`, check whether `SessionConfig`, `CommitConfig`, `SuggestConfig`, `RetryConfig`, `HttpConfig`, `MaxTokens`, `Temperature`, `TopK`, `TopP`, `Update`, and `Compact` are still needed in this file. Remove any that are now unreferenced.
+
+- [ ] Task 5. **Remove `AutoDumpFormat` from `env.rs` if it is no longer referenced there**.
+
+  `AutoDumpFormat` was used by the `auto_dump` field being removed. If it has no other use in `env.rs`, move its definition or re-export to the appropriate module, or leave it in `forge_domain` as a standalone type — do not silently delete it if it is still needed elsewhere in the domain.
+
+- [ ] Task 6. **Update the `fake::Dummy` derive on `Environment`**.
+
+  With only six fields, the `#[derive(fake::Dummy)]` annotation and any `#[dummy(...)]` attribute overrides on removed fields must be cleaned up. Verify the derive still compiles.
+
+---
+
+### Phase 2 — Add `type Config` and `get_config` to `EnvironmentInfra`
+
+- [ ] Task 7. **Add the `Config` associated type to `EnvironmentInfra`** (`crates/forge_app/src/infra.rs:21-39`).
+
+  Add `type Config;` as an associated type on the trait. Every service bound written as `F: EnvironmentInfra` will need the concrete type resolved through the `type Config` mechanism, so consider whether a `where Self::Config: ...` bound is necessary at the trait level (e.g. `Clone` and `Send` if callers cache the value).
+
+- [ ] Task 8. **Add `fn get_config(&self) -> Self::Config` to `EnvironmentInfra`**.
+
+  This method returns the full `ForgeConfig` to any consumer that holds a reference to an `EnvironmentInfra` implementor. Add it alongside the existing `get_environment`, `get_env_var`, and `get_env_vars` methods.
+
+- [ ] Task 9. **Add `forge_config` as a direct dependency of `forge_app`** (`crates/forge_app/Cargo.toml`).
+
+  `forge_app` now references `ForgeConfig` in the trait definition. Add the path dependency if it does not already exist.
+
+---
+
+### Phase 3 — Update `ForgeEnvironmentInfra` in `forge_infra`
+
+- [ ] Task 10. **Implement `type Config = ForgeConfig` and `get_config` on `ForgeEnvironmentInfra`** (`crates/forge_infra/src/env.rs:393-443`).
+
+  `get_config` reads from the existing `Arc<Mutex<Option<ForgeConfig>>>` cache, loading from disk on the first call — identical to how `get_environment` already works. Return the `ForgeConfig` value (cloned from cache).
+
+- [ ] Task 11. **Simplify `to_environment()` to populate only the six runtime fields** (`crates/forge_infra/src/env.rs:120-179`).
+
+  Remove the entire `// --- ForgeConfig-mapped fields ---` section. `to_environment` should only construct `os`, `pid`, `cwd`, `home`, `shell`, and `base_path`.
+
+- [ ] Task 12. **Delete `to_forge_config()` and all its `from_*` helper conversion functions** (`crates/forge_infra/src/env.rs:181-354`).
+
+  These were needed to round-trip `Environment ↔ ForgeConfig`. With `Environment` no longer carrying config data, the round-trip path is eliminated. Remove `to_forge_config`, `from_retry_config`, `from_http_config`, `from_tls_version`, `from_tls_backend`, `from_auto_dump_format`, `from_update_frequency`, `from_update`, and `from_compact`.
+
+- [ ] Task 13. **Rewrite `update_environment()` to operate on `ForgeConfig` directly** (`crates/forge_infra/src/env.rs:417-442`).
+
+  The new flow:
+  1. Load `ForgeConfig` from disk via `ConfigReader` (defaults + global only, as today).
+  2. Apply each `ConfigOperation` directly to the `ForgeConfig` using a new free function `apply_config_op(fc: &mut ForgeConfig, op: ConfigOperation)` defined in this file.
+  3. Call `fc.write()` to persist.
+  4. Invalidate the cache.
+
+  The `apply_config_op` function replicates the `SetProvider`, `SetModel`, `SetCommitConfig`, and `SetSuggestConfig` mutation logic that was previously in `Environment::apply_op`, but targeting `ForgeConfig`'s `session`, `commit`, and `suggest` fields of type `Option<ModelConfig>`.
+
+- [ ] Task 14. **Delete the round-trip identity test** (`crates/forge_infra/src/env.rs:483-509`).
+
+  The test `test_forge_config_environment_identity` verified that `fc → env → fc' → env'` preserved equality. Since `to_forge_config` is removed, this test is invalid. Remove it and add a simpler test that confirms `get_config` returns the same values as were written via `update_environment`.
+
+- [ ] Task 15. **Implement `type Config = ForgeConfig` and `get_config` on `ForgeInfra`** (`crates/forge_infra/src/forge_infra.rs:94-113`).
+
+  Add the delegation: `fn get_config(&self) -> ForgeConfig { self.config_infra.get_config() }`. Also add `type Config = ForgeConfig;`.
+
+- [ ] Task 16. **Update `ForgeInfra::new()` to read config through `get_config()` rather than `get_environment()`** (`crates/forge_infra/src/forge_infra.rs:58-91`).
+
+  `ForgeInfra::new()` currently calls `config_infra.get_environment()` to extract `env.parallel_file_reads` and `env.service_url` for constructing `ForgeDirectoryReaderService` and `ForgeGrpcClient`. Change these to read from `config_infra.get_config()` using the canonical `ForgeConfig` field names: `max_parallel_file_reads` and `services_url` (parsed to `Url`).
+
+---
+
+### Phase 4 — Update `MockInfra` in tests
+
+- [ ] Task 17. **Add a `ForgeConfig` field to `MockInfra`** (`crates/forge_services/src/app_config.rs:148-278`).
+
+  `MockInfra` currently holds `Arc<Mutex<Environment>>`. Add `config: Arc<Mutex<ForgeConfig>>` alongside it, initialised from `ForgeConfig::default()` or a faked value in `MockInfra::new()`.
+
+- [ ] Task 18. **Implement `type Config = ForgeConfig` and `get_config` on `MockInfra`**.
+
+  Return a clone of the locked `ForgeConfig` value.
+
+- [ ] Task 19. **Rewrite `update_environment` on `MockInfra` to operate on `ForgeConfig`**.
+
+  Replace the inline `Environment`-mutation logic with the same `apply_config_op` semantics (on `ForgeConfig`), keeping `get_environment` returning a still-valid slim `Environment` built from the stored cwd/os/shell/etc.
+
+- [ ] Task 20. **Update `MockInfra::get_environment()` to return a slim `Environment`**.
+
+  Since `Environment` now has only six fields, construct it from static test values (`os`, `pid`, `cwd`, `home`, `shell`, `base_path`) rather than from a full fake.
+
+- [ ] Task 21. **Update test assertions in `app_config.rs` that inspect `env.session` and `env.suggest`**.
+
+  Tests currently call `fixture.get_environment()` and then inspect `env.session`. Change these assertions to call `fixture.get_config()` and inspect `config.session` on the returned `ForgeConfig`. Update the field access paths to match `ForgeConfig`'s field names (`session: Option<ModelConfig>`, `model_id: Option<String>`, etc.).
+
+---
+
+### Phase 5 — Update all service and app consumers
+
+- [ ] Task 22. **Update `ForgeAppConfigService` to read session config via `get_config()`** (`crates/forge_services/src/app_config.rs:33-129`).
+
+  Every call to `self.infra.get_environment()` followed by `env.session`, `env.commit`, or `env.suggest` must be replaced with `self.infra.get_config()` accessing `config.session`, `config.commit`, `config.suggest` of type `Option<ModelConfig>`. Adapt the field access to `ModelConfig`'s `provider_id: Option<String>` and `model_id: Option<String>` fields.
+
+- [ ] Task 23. **Update `forge_services/src/auth.rs` — `env.service_url` → `get_config().services_url`**.
+
+  Parse `config.services_url` to `Url` at the call site as needed.
+
+- [ ] Task 24. **Update `forge_services/src/context_engine.rs` — `env.max_file_read_batch_size`** (two sites).
+
+  Replace with `infra.get_config().max_file_read_batch_size`.
+
+- [ ] Task 25. **Update `forge_services/src/attachment.rs` — `env.max_search_result_bytes`**.
+
+  Replace with `infra.get_config().max_search_result_bytes`.
+
+- [ ] Task 26. **Update `forge_app/src/tool_executor.rs` — `env.fetch_truncation_limit`**.
+
+  Replace with `infra.get_config().max_fetch_chars`.
+
+- [ ] Task 27. **Update `forge_app/src/tool_registry.rs` — `env.tool_timeout` and `env.max_search_lines`**.
+
+  Replace with `infra.get_config().tool_timeout_secs` and `infra.get_config().max_search_lines`.
+
+- [ ] Task 28. **Update `forge_app/src/changed_files.rs` — `env.parallel_file_reads`**.
+
+  Replace with `infra.get_config().max_parallel_file_reads`.
+
+- [ ] Task 29. **Update `forge_app/src/app.rs` — `env.tool_supported`**.
+
+  Replace with `infra.get_config().tool_supported`.
+
+- [ ] Task 30. **Audit all remaining `get_environment()` call sites that access now-removed fields**.
+
+  Run a codebase search for `get_environment()` followed by field access. For any that reference a field no longer on `Environment`, redirect to `get_config()`. Document any additional files not enumerated in Tasks 22–29.
+
+- [ ] Task 31. **Add `forge_config` as a direct dependency to any crate that now imports `ForgeConfig` for field access** (e.g. `forge_services`, `forge_app`).
+
+  For each crate modified in Tasks 22–29, verify `forge_config` is listed in its `Cargo.toml` and add it if absent.
+
+---
+
+### Phase 6 — Update other infra consumers
+
+- [ ] Task 32. **Update `ForgeHttpInfra::new()` which currently accepts `Environment`** (`crates/forge_infra/src/http.rs`).
+
+  If `ForgeHttpInfra` uses any `Environment` field that originated from `ForgeConfig` (e.g. `env.http`, `env.retry_config`), change it to accept `ForgeConfig` instead and read `config.http` and `config.retry` directly.
+
+- [ ] Task 33. **Update `ForgeCommandExecutorService::new()` which currently accepts `Environment`** (`crates/forge_infra/src/executor.rs`).
+
+  If it reads fields like `env.tool_timeout`, `env.shell`, or `env.cwd`, split the arguments: pass the slim `Environment` for `shell`/`cwd`, and pass the relevant `ForgeConfig` fields for config-sourced values.
+
+---
+
+### Phase 7 — Remove dead code and verify
+
+- [ ] Task 34. **Remove unused imports and dead code** across all modified files.
+
+  After removing fields from `Environment`, many imports in `forge_domain/src/env.rs`, `forge_infra/src/env.rs`, and consumer files will become unused. Clean them all up.
+
+- [ ] Task 35. **Remove the `AutoDumpFormat`-related and other now-unused conversion helpers** from `forge_infra/src/env.rs`.
+
+  The `to_auto_dump_format`, `to_compact`, `to_update`, `to_update_frequency`, `to_session_config`, `to_tls_version`, `to_tls_backend`, `to_http_config`, and `to_retry_config` functions may all become dead code. Remove any that are no longer called.
+
+- [ ] Task 36. **Run `cargo insta test --accept`** to verify all tests pass and update any snapshot tests affected by the structural changes.
+
+---
+
+## Verification Criteria
+
+- `Environment` contains exactly six fields: `os`, `pid`, `cwd`, `home`, `shell`, `base_path`. All path helper methods continue to compile and behave correctly.
+- `EnvironmentInfra` has `type Config;` and `fn get_config(&self) -> Self::Config` as part of its public interface.
+- Every `impl EnvironmentInfra` in the codebase (production: `ForgeEnvironmentInfra`, `ForgeInfra`; test: `MockInfra`) declares `type Config = ForgeConfig`.
+- No service or app code accesses a field on the return value of `get_environment()` that was formerly sourced from `ForgeConfig`; all such accesses use `get_config()` instead.
+- The `to_forge_config()` function and all `from_*` conversion helpers are deleted from `forge_infra/src/env.rs`.
+- `update_environment()` operates directly on `ForgeConfig` without involving `Environment` mutation.
+- `apply_op()` no longer exists on `Environment`; mutation logic lives in a free function in `forge_infra/src/env.rs`.
+- `cargo insta test --accept` completes without errors.
+- `cargo check` produces no warnings for unused imports or dead code in any modified file.
+
+---
+
+## Potential Risks and Mitigations
+
+1. **`SessionConfig` vs `ModelConfig` type mismatch**  
+   `Environment.session` was of type `Option<SessionConfig>` (domain type), while `ForgeConfig.session` is `Option<ModelConfig>` (config type). Service code that destructures `SessionConfig` will need updating to work with `ModelConfig`'s field names. Additionally, `SessionConfig` may become an orphaned domain type if nothing else uses it — audit its usages before deciding to retain or remove it.  
+   Mitigation: Before removing `SessionConfig`, run a workspace-wide search for all usages and migrate or remove them as part of Tasks 22 and 21.
+
+2. **`cwd` used in `ForgeCommandExecutorService` and `ForgeHttpInfra`**  
+   These types currently take a full `Environment` but may rely on a mix of infra fields (`cwd`, `shell`) and config fields (`tool_timeout`, `http`, `retry`). A naive split risks passing two objects where one worked before.  
+   Mitigation: Tasks 32–33 explicitly address this. The slim `Environment` is passed for runtime fields; individual `ForgeConfig` fields are passed separately, preserving the single-responsibility boundary at each constructor.
+
+3. **`history_path()` signature change breaks all callers**  
+   This is the only path helper that currently reads a `ForgeConfig` field. Changing its signature is a mechanical but wide-reaching refactor.  
+   Mitigation: Make the change in Task 2 early, then use compiler errors to find all call sites. Each call site must source `custom_history_path` from a locally available `ForgeConfig` (obtained via `get_config()`).
+
+4. **Crate dependency graph expansion**  
+   `forge_services` and `forge_app` currently have no direct dependency on `forge_config`. Adding one is architecturally significant — it means domain-level services now know about the infrastructure config format.  
+   Mitigation: This is an explicit requirement of the task. Task 31 ensures all `Cargo.toml` files are updated consistently. If future work wants to reintroduce a domain abstraction layer, a `ForgeConfig`-to-domain mapping can be re-introduced separately.
+
+5. **`fake::Dummy` derive on slim `Environment` may fail**  
+   The `fake` crate derives require all field types to implement `Dummy`. With six simple fields (`String`, `u32`, `PathBuf`, `Option<PathBuf>`), this should remain straightforward, but the `url::Url` `#[dummy(expr = ...)]` override that was on `service_url` is being removed.  
+   Mitigation: Task 6 ensures the derive is re-validated after the structural change.
+
+---
+
+## Alternative Approaches
+
+1. **Keep `Environment` as-is but add `get_config()` alongside `get_environment()`**: This is the minimal additive change — no consumer code is disrupted, and new code can opt into `get_config()`. Trade-off: `Environment` remains a redundant mirror of `ForgeConfig`, the `to_environment`/`to_forge_config` round-trip complexity is preserved, and the synchronisation risk (duplicate fields drifting out of step) persists.
+
+2. **Embed `ForgeConfig` as a field inside `Environment` rather than replacing the fields**: `Environment` could hold `pub config: ForgeConfig` plus the six infra fields, allowing a gradual migration of callers. Trade-off: Transitional approach that still results in duplicated field access patterns and retains the `to_environment` mapping, just restructured. Cleaner than alternative 1 but more disruptive than the targeted plan above.

plans/2026-04-05-config-init-at-startup-v1.md

@@ -0,0 +1,193 @@
+# Config Read at Application Init — Surface Errors, Remove Silent Defaults
+
+## Objective
+
+Currently, `ForgeConfig` is read lazily from disk inside `ForgeEnvironmentInfra` and any parse/deserialization errors are silently swallowed — returning `ForgeConfig::default()` (all-zero values) with only a tracing log that the user never sees. This causes silent breakage of all tool limits and agent parameters when the user's config file is corrupt or invalid.
+
+The goal is to:
+1. Read `ForgeConfig` **once at application startup** in `main.rs`, surfacing any parse error directly to the user before the app proceeds.
+2. Pass the pre-read config through the construction chain to every consumer.
+3. **Remove `get_config()` from the `EnvironmentInfra` trait** entirely — it is no longer needed since config is injected at construction time.
+4. Preserve the `update_environment` write path so that `forge config set` commands continue to work correctly.
+
+---
+
+## Architecture Overview
+
+### Current Flow (Lazy, Silent-Error)
+
+```
+main.rs
+  └─ ForgeAPI::init(cwd)
+       └─ ForgeInfra::new(cwd)
+            └─ ForgeEnvironmentInfra::new(cwd)      ← cache = None
+                 └─ (first get_config() call)
+                      └─ ForgeConfig::read()         ← disk I/O
+                           └─ Err(_) → Default::default()  ← SILENT!
+```
+
+### Target Flow (Eager, Error-Surfaced)
+
+```
+main.rs
+  └─ ForgeConfig::read()?                            ← fails loudly here
+  └─ ForgeAPI::init(cwd, config)
+       └─ ForgeInfra::new(cwd, config)
+            └─ ForgeEnvironmentInfra::new(cwd, config)  ← cache = Some(config)
+            └─ ForgeHttpInfra::new(config, ...)
+            └─ ForgeDirectoryReaderService::new(config.max_parallel_file_reads)
+            └─ ForgeGrpcClient::new(config.services_url.parse()?)
+```
+
+### What `update_environment` Does (Preserved)
+
+`ForgeEnvironmentInfra::update_environment` performs a **read-from-disk → mutate → write-to-disk → cache-invalidate** cycle whenever the user changes provider/model/reasoning settings. After invalidation, the next `get_config()` call re-reads from disk. Since `get_config()` is being removed from the trait, the internal cache mechanism in `ForgeEnvironmentInfra` must be adapted so the fresh post-write value is propagated back to all consumers that hold a stored config.
+
+The cleanest resolution: `update_environment` returns the updated `ForgeConfig` in its result, and callers store the new value. However, since the trait is used in many places, the simplest compatible approach is to keep the cache internal to `ForgeEnvironmentInfra` but make `update_environment` callable from the services layer to update its stored config — or to have the application re-read config after an update via a narrower dedicated trait method (not `get_config()` on the general infra trait).
+
+---
+
+## Key Invariants to Preserve
+
+1. **`update_environment` must still work** — `forge config set model ...` must update the TOML and the in-memory state visible to subsequent calls.
+2. **`/new` conversation re-creation** — `on_new()` calls `(self.new_api)()`, rebuilding `ForgeAPI`. The captured `ForgeConfig` in the closure must be the **latest** config (post any `update_environment` calls), not the startup snapshot.
+3. **`get_config()` removal scope** — removing it from `EnvironmentInfra` does not mean removing it from every consumer; it means the consumers receive the value as a constructor argument or method parameter rather than calling `infra.get_config()` at runtime.
+4. **`services_url` panic elimination** — with config surfaced in `main.rs`, the `.expect()` on `services_url.parse()` can be converted to `?`-propagation, making `ForgeInfra::new()` fallible.
+
+---
+
+## Implementation Plan
+
+### Phase 1 — Surface Config Errors in `ForgeConfig::read()`
+
+- [~] Task 1.1. **Fix silent error in `ConfigReader::read_global()`** (`crates/forge_config/src/reader.rs`): The `.required(false)` flag on `config::File::from(path)` silently swallows parse errors for malformed TOML files. Change this so that if the file *exists* but is invalid (e.g., malformed TOML, wrong types), an error is returned. Only missing files should be silently skipped. This may require checking file existence before adding the `config` source, or using a custom file reader that returns `Err` on parse failure but `Ok` on file-not-found.
+
+- [ ] Task 1.2. **Fix silent skip in `ConfigReader::read_legacy()`** (`crates/forge_config/src/reader.rs`): Currently uses `if let Ok(content) = content { ... } else { self }` — silently ignores errors. Change to at minimum emit a `warn!` log message, or propagate the error. Since legacy JSON is a migration concern, a `warn!` is appropriate rather than a hard error.
+
+- [ ] Task 1.3. **Verify `ForgeConfig::read()` return type** — it already returns `anyhow::Result<ForgeConfig>`. No signature change needed here. The fix is upstream in the reader chain ensuring errors actually reach the `Result::Err` variant.
+
+### Phase 2 — Read Config Once in `main.rs`
+
+- [ ] Task 2.1. **Call `ForgeConfig::read()` at the top of `main()` in `crates/forge_main/src/main.rs`** before the `UI::init` call. Use `?` propagation so any error is printed to stderr and exits with a non-zero code. The error message from `anyhow` will include the cause (e.g., "invalid TOML at line 12: expected string, found integer"), which is exactly what the user needs to see.
+
+- [ ] Task 2.2. **Thread the `config: ForgeConfig` into the `UI::init` factory closure** in `main.rs`. The closure currently captures `cwd: PathBuf`; it must now also capture `config: ForgeConfig`. Since `ForgeConfig` derives `Clone`, the closure can clone it on each invocation (once at startup, once per `/new` command).
+
+  > **Note on `/new` and config freshness**: The closure will capture the **startup config**. After a `forge config set` command, `update_environment` writes to disk and invalidates the `ForgeEnvironmentInfra` internal cache. However, since `get_config()` is being removed from the trait, the stale startup config captured in the closure would be used on the next `/new`. This must be addressed in Phase 4.
+
+### Phase 3 — Propagate Config Through the Construction Chain
+
+- [ ] Task 3.1. **Change `ForgeAPI::init` signature** (`crates/forge_api/src/forge_api.rs`): Add `config: ForgeConfig` as a parameter. Forward it to `ForgeInfra::new(cwd, config)`. This is the only `impl ForgeAPI<...>` concrete method that constructs the infra stack.
+
+- [ ] Task 3.2. **Change `ForgeInfra::new` signature** (`crates/forge_infra/src/forge_infra.rs`): Add `config: ForgeConfig` as a parameter. Remove the `config_infra.get_config()` call that currently triggers the lazy disk read. Pass `config` directly to:
+  - `ForgeEnvironmentInfra::new(cwd, config)` — seeds the internal cache
+  - `ForgeHttpInfra::new(config.clone(), ...)` — already accepts `ForgeConfig`
+  - `ForgeDirectoryReaderService::new(config.max_parallel_file_reads)` — already accepts the field
+  - `ForgeGrpcClient::new(...)` — use `?` propagation instead of `.expect()` (see Task 3.3)
+
+  Make `ForgeInfra::new` return `anyhow::Result<Self>` to allow `?`-propagation from within.
+
+- [ ] Task 3.3. **Replace `.expect()` with `?` for `services_url` parsing** (`crates/forge_infra/src/forge_infra.rs:73-78`): Now that `ForgeInfra::new` is fallible, convert `config.services_url.parse().expect(...)` to `config.services_url.parse().context("services_url must be a valid URL")?`. This turns a panic into a clean error message at startup.
+
+- [ ] Task 3.4. **Change `ForgeEnvironmentInfra::new` signature** (`crates/forge_infra/src/env.rs`): Add `config: ForgeConfig` parameter. Initialize `cache` as `Arc::new(Mutex::new(Some(config)))` instead of `None`. The `cached_config()` method (`env.rs:125-134`) already handles the `Some` case by returning the cached value — it will simply never need to perform a disk read for the initial config. The read-from-disk path in `read_from_disk()` becomes dead code after this change and can be removed.
+
+- [ ] Task 3.5. **Update `ForgeAPI::init` call site in `main.rs`** to handle the new `Result<Self>` return from `ForgeInfra::new` (if propagated up through `ForgeAPI::init`). The closure passed to `UI::init` currently produces `A` (not `Result<A>`); if `ForgeAPI::init` becomes fallible, either the closure's return type changes to `Result<A>` and `on_new` handles the error, or the URL validation is done eagerly before the closure is constructed in `main.rs`.
+
+  > **Recommended resolution**: Validate `services_url` in `main.rs` by parsing it there using `config.services_url.parse::<Url>().context(...)?` before creating the closure. Pass the parsed `Url` into `ForgeInfra::new` instead of the raw string. This keeps the factory closure infallible (consistent with current `UI<A, F>` design where `F: Fn() -> A`).
+
+### Phase 4 — Handle Config Freshness After `update_environment`
+
+The `/new` closure captures `ForgeConfig` at startup. After `update_environment` writes a new config and invalidates the `ForgeEnvironmentInfra` cache, the next `/new` would reconstruct `ForgeAPI` with the stale startup config. This must be addressed.
+
+- [ ] Task 4.1. **Expose a config-accessor on the existing `API` trait** that the `UI` can use to retrieve the latest config when constructing a new API instance on `/new`. Since `ForgeEnvironmentInfra` still holds the authoritative in-memory cache (updated after `update_environment`), calling `api.get_config()` after an `update_environment` will return the fresh value. The `UI` can call `self.api.get_config()` inside `on_new` to get the latest config, then pass it to the new `ForgeAPI` factory.
+
+  Concretely: Change the factory closure stored in `new_api` from `Fn() -> A` to `Fn(ForgeConfig) -> A`. The `UI::on_new` method calls `(self.new_api)(self.api.get_config())` to forward the live config into the new API instance.
+
+  Adjust `UI<A, F>` struct and `UI::init` accordingly:
+  - Change the `F` bound from `Fn() -> A` to `Fn(ForgeConfig) -> A`
+  - Update `main.rs` closure from `move || ForgeAPI::init(cwd.clone())` to `move |config| ForgeAPI::init(cwd.clone(), config)`
+  - Update `on_new` to call `(self.new_api)(self.api.get_config())` 
+
+  > This preserves `get_config()` on the `API` trait (not `EnvironmentInfra`) for this specific use case. The `API` trait's `get_config()` can delegate to the stored infra's cache (same as today), but the `EnvironmentInfra` trait no longer exposes it.
+
+### Phase 5 — Remove `get_config()` from `EnvironmentInfra` Trait
+
+- [ ] Task 5.1. **Remove `get_config()` from the `EnvironmentInfra` trait** in `crates/forge_app/src/infra.rs`. This is the core structural change. All code that calls `infra.get_config()` through the trait must be updated to receive `ForgeConfig` through another mechanism (constructor parameter, method parameter).
+
+- [ ] Task 5.2. **Remove `get_config()` from `ForgeInfra`** (`crates/forge_infra/src/forge_infra.rs`): The delegation to `config_infra.get_config()` is no longer needed.
+
+- [ ] Task 5.3. **Remove `get_config()` from `ForgeRepo`** (`crates/forge_repo/src/forge_repo.rs`): Same delegation removal.
+
+- [ ] Task 5.4. **Remove `get_config()` from `ForgeServices`** (`crates/forge_services/src/forge_services.rs`): Same delegation removal. The `AppConfigService` methods currently call `self.infra.get_config()` to read existing config fields before mutating — these should instead use the config passed through method parameters or read from the updated state returned by `update_environment`.
+
+- [ ] Task 5.5. **Audit all call sites of `get_config()` through the `EnvironmentInfra` trait** — specifically inside `crates/forge_app/src/app.rs`, `crates/forge_app/src/agent.rs`, `crates/forge_app/src/tool_executor.rs`, `crates/forge_app/src/operation.rs`, and `crates/forge_services/src/app_config.rs`. For each call site:
+  - If the caller is a service method, consider passing `ForgeConfig` as a method parameter from the call site one level up.
+  - If the caller is a long-lived struct that currently reads config on every operation, consider storing `ForgeConfig` as a field injected at construction time.
+
+- [ ] Task 5.6. **Update `ForgeAppConfigService::get_default_provider`, `get_provider_model`, etc.** (`crates/forge_services/src/app_config.rs`): These currently call `self.infra.get_config()` to read the current provider/model. After removing `get_config()` from `EnvironmentInfra`, the service needs another way to get the current config. Options:
+  - Store `ForgeConfig` in `ForgeAppConfigService` at construction time (simplest, but may go stale after `update_environment`).
+  - Have `update_environment` return the updated `ForgeConfig` value, letting callers store the fresh value.
+  - Keep a **separate, narrow trait** like `ConfigReader` with only `get_config()` on it, distinct from `EnvironmentInfra`, used only where runtime config re-reads are genuinely needed (i.e., after `update_environment` writes).
+
+  > **Recommended**: The cleanest approach given the existing architecture is to have `update_environment` return `ForgeConfig` (the new config after applying ops). Services that call `update_environment` can then update their stored config reference. This requires changing `update_environment`'s return type from `anyhow::Result<()>` to `anyhow::Result<ForgeConfig>` in the `EnvironmentInfra` trait.
+
+### Phase 6 — Remove `read_from_disk()` Dead Code
+
+- [ ] Task 6.1. **Remove `read_from_disk()` from `ForgeEnvironmentInfra`** (`crates/forge_infra/src/env.rs`): With the cache always pre-seeded from the constructor, the `read_from_disk()` method and its `error!("Failed to read config file. Using default config.")` fallback are dead code. Remove both the method and the `// NOTE: This should never-happen` comment that has been lying about the real risk.
+
+- [ ] Task 6.2. **Simplify `cached_config()`** (`crates/forge_infra/src/env.rs`): The `Mutex<Option<ForgeConfig>>` can be simplified. If the cache is always initialized via the constructor and only set to `None` by `update_environment` (which then repopulates from disk), the `Option` wrapper is still needed for the update cycle. Retain the structure but remove the `read_from_disk()` call in the `None` branch — instead call `ConfigReader::default().read_defaults().read_global().build()?` directly and propagate the error rather than swallowing it.
+
+  > **Note**: `cached_config()` currently returns `ForgeConfig` (not `Result<ForgeConfig>`). If `update_environment` invalidates the cache and the subsequent re-read can fail, `cached_config()` must return `Result<ForgeConfig>`. Propagate this change upward through `get_config()` on `ForgeEnvironmentInfra` (which may remain internal/non-trait after trait removal).
+
+### Phase 7 — Update Tests and Snapshots
+
+- [ ] Task 7.1. **Update mock implementations of `EnvironmentInfra`** in test code: Any `#[cfg(test)]` or mock structs that implement `EnvironmentInfra` will need `get_config()` removed from their impl blocks after Phase 5. Search for all `impl EnvironmentInfra` in the codebase and remove the `get_config()` method bodies.
+
+- [ ] Task 7.2. **Update tests that exercise `ForgeInfra::new` or `ForgeAPI::init`**: These now require a `ForgeConfig` argument. Construct test configs using `ForgeConfig::default()` (which provides Rust-defaulted zeroes) or `ForgeConfig::read()` where a realistic config is needed.
+
+- [ ] Task 7.3. **Run `cargo insta test --accept`** to update any snapshot tests affected by structural changes.
+
+- [ ] Task 7.4. **Run `cargo check`** across the workspace to surface any remaining compilation errors from the trait removal cascade.
+
+---
+
+## Verification Criteria
+
+- Starting forge with a corrupt `~/.forge.toml` file (e.g., `forge = {invalid`) must print a clear, human-readable error message to stderr and exit with a non-zero code — not silently start with default config.
+- Starting forge with a `FORGE_SERVICES_URL=not-a-url` environment variable must print a clear error and exit rather than panicking.
+- `forge config set model anthropic claude-3-opus` must still work correctly — the model is updated in `~/.forge.toml` and subsequent operations use the new model.
+- Starting a new conversation with `/new` after `forge config set ...` must reflect the updated config (not the startup snapshot).
+- `forge env` must still display the current config.
+- All existing tests pass under `cargo insta test --accept`.
+- `cargo check` produces no errors across the workspace.
+
+---
+
+## Potential Risks and Mitigations
+
+1. **`/new` gets stale config after `update_environment`**
+   Mitigation: Change the factory closure type from `Fn() -> A` to `Fn(ForgeConfig) -> A` (Task 4.1). `on_new` reads the latest config from the live API before constructing the new one.
+
+2. **`EnvironmentInfra` implementors in external or test code break on trait change**
+   Mitigation: Search all `impl EnvironmentInfra` blocks across the workspace (Task 7.1) and update them. Since the trait is internal (not `pub` across crate boundaries to user code), the scope is bounded to this repository.
+
+3. **`update_environment` re-read from disk can fail post-startup**
+   Mitigation: Change `update_environment` return type to `anyhow::Result<ForgeConfig>` and propagate the error up through the service layer to the UI, which displays it as a user-visible error message rather than silently ignoring it.
+
+4. **`ConfigReader::read_global()` change breaks behavior for missing config file**
+   Mitigation: The fix in Task 1.1 must distinguish between "file does not exist" (skip silently, as today) and "file exists but is malformed" (return error). Use `path.exists()` check before deciding whether to add the source as required or not.
+
+5. **`ForgeInfra::new` becoming `Result`-returning cascades through `ForgeAPI::init` and the closure**
+   Mitigation: Pre-validate `services_url` in `main.rs` before the closure (Task 3.5, recommended approach). This keeps the factory closure return type as `A` (not `Result<A>`), preserving the `UI<A, F>` generic constraint without requiring a `UI` redesign.
+
+6. **`AppConfigService::get_default_provider` and similar read-config methods need config access**
+   Mitigation: Implement the `update_environment` → returns `ForgeConfig` approach (Task 5.6). Alternatively, store `ForgeConfig` at service construction time and update it in-place after each `update_environment` call returns. The former is cleaner.
+
+---
+
+## Alternative Approaches
+
+1. **Keep `get_config()` on `EnvironmentInfra` but add startup validation**: Instead of full removal, keep the lazy read but call `ForgeConfig::read()?` in `main.rs` purely for validation (discard the result), then let the infra re-read it lazily. Simpler change, but duplicates disk reads and doesn't achieve the "config piped through everywhere" goal. Does not eliminate the dead error path in `read_from_disk()`.
+
+2. **Wrap `ForgeConfig` in `Arc<RwLock<ForgeConfig>>`**: Rather than threading config through constructors, store a shared `Arc<RwLock<ForgeConfig>>` that all consumers read from. `update_environment` acquires the write lock and updates in place. This is a valid reactive pattern but adds lock complexity and requires write-lock acquisition on every config read, even in hot paths like `tool_executor`.
+
+3. **Narrow the `EnvironmentInfra` trait instead of removing `get_config()`**: Split into `EnvironmentInfra` (env vars, environment) and a separate `ConfigInfra` trait (just `get_config()` and `update_environment()`). Services that need only config use `ConfigInfra`; services that need only env use `EnvironmentInfra`. This reduces the trait surface each service depends on and is a valid design improvement, but is a larger refactor scope than strictly required.

plans/agent-context-compaction-2025-03-24-concise.md

@@ -0,0 +1,72 @@
+# Agent Context Compaction Implementation Plan
+
+## Objective
+Add automatic context compaction to the `Agent` struct based on configurable triggers (token count, turn count, message count) with a specified maximum token limit.
+
+## Implementation Plan
+
+### 1. Define New Compaction Configuration Structure
+Create a `Compaction` struct in `crates/forge_domain/src/agent.rs` with:
+- `token_threshold`: Optional maximum token count trigger
+- `turn_threshold`: Optional maximum turns trigger
+- `message_threshold`: Optional maximum messages trigger
+- `max_tokens`: Maximum allowed tokens after compaction
+- `should_compact()` method to determine when compaction is needed
+
+### 2. Update Agent Struct
+Add an optional `compact` field to the `Agent` struct that follows existing patterns and merging strategies.
+
+### 3. Implement Context Compaction Logic
+Modify the `Orchestrator` implementation to:
+- Add `compact_context()` method to handle the compaction process
+- Update `init_agent_with_event()` to check compaction conditions before processing
+- Use existing `Summarize` mechanism for the initial implementation
+
+### 4. Enhance Token Counting
+Implement a more accurate token counting function to support compaction decisions.
+
+### 5. Handle Transform Deprecation
+- Add deprecation notice to the `Transform::Assistant` variant
+- Add warning logs when the deprecated functionality is used
+- Document migration path to the new approach
+
+### 6. Testing Strategy
+Add tests to verify:
+- Compaction configuration works correctly
+- Compaction triggers function as expected
+- Merging behavior for the new field
+- Context reduction achieves the token target
+
+### 7. Documentation Updates
+Update documentation with examples of the new configuration:
+
+```yaml
+# Example in forge.yaml
+agents:
+  myAgent:
+    id: myAgent
+    model: gpt-4-turbo
+    system_prompt: "You are a helpful assistant."
+    compact:
+      max_tokens: 4000
+      token_threshold: 6000
+      turn_threshold: 10
+      message_threshold: 30
+```
+
+## Verification Criteria
+1. Proper implementation of `Compaction` struct with needed fields and methods
+2. `Agent` struct correctly handles the new `compact` field
+3. Automatic compaction triggers when configured conditions are met
+4. Appropriate deprecation of the transform-based approach
+5. All tests pass, verifying compaction logic works as expected
+6. Clear documentation explains how to use the new feature
+
+## Implementation Sequence
+1. Add `Compaction` struct to `agent.rs`
+2. Add `compact` field to `Agent` struct
+3. Implement orchestrator compaction methods
+4. Add token counting enhancement
+5. Deprecate the transform-based approach
+6. Add tests for the new functionality
+7. Update documentation and examples

plans/agent-context-compaction-2025-03-24.md

@@ -0,0 +1,328 @@
+# Agent Context Compaction Implementation Plan
+
+## Objective
+
+Add a new field to the `Agent` struct that enables automatic context compaction based on configurable triggers (token count, turn count, message count) and a specified maximum token limit.
+
+## Implementation Plan
+
+### 1. Define a New Context Compaction Configuration Structure
+
+Create a new struct `Compaction` in `crates/forge_domain/src/agent.rs` that will hold the configuration options for context compaction:
+
+```rust
+/// Configuration for automatic context compaction
+#[derive(Debug, Clone, Serialize, Deserialize, Setters)]
+#[setters(strip_option, into)]
+pub struct Compaction {
+    /// Maximum token count before compaction is triggered
+    /// When the context exceeds this token count, compaction will be applied
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub token_threshold: Option<usize>,
+    
+    /// Maximum number of turns before compaction is triggered
+    /// After this many conversation turns, compaction will be applied
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub turn_threshold: Option<usize>,
+    
+    /// Maximum number of messages before compaction is triggered
+    /// After this many messages in the context, compaction will be applied
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub message_threshold: Option<usize>,
+    
+    /// Maximum allowed token count after compaction
+    /// The compaction process will reduce the context to approximately this token count
+    pub max_tokens: usize,
+}
+
+impl Compaction {
+    /// Creates a new context compaction configuration with the specified maximum token limit
+    pub fn new(max_tokens: usize) -> Self {
+        Self {
+            token_threshold: None,
+            turn_threshold: None,
+            message_threshold: None,
+            max_tokens,
+        }
+    }   
+    
+    /// Determines if compaction should be triggered based on the current context state
+    pub fn should_compact(
+        &self, 
+        context: &Context, 
+        turn_count: u64, 
+        message_count: usize
+    ) -> bool {
+        // Check token threshold
+        if let Some(token_threshold) = self.token_threshold {
+            let current_tokens = token_count(&context.to_text());
+            if current_tokens > token_threshold {
+                return true;
+            }
+        }
+        
+        // Check turn threshold
+        if let Some(turn_threshold) = self.turn_threshold {
+            if turn_count >= turn_threshold as u64 {
+                return true;
+            }
+        }
+        
+        // Check message threshold
+        if let Some(message_threshold) = self.message_threshold {
+            if message_count > message_threshold {
+                return true;
+            }
+        }
+        
+        false
+    }
+}
+```
+
+### 2. Update the Agent Struct
+
+Add the new `compact` field to the `Agent` struct in `crates/forge_domain/src/agent.rs`:
+
+```rust
+#[derive(Debug, Clone, Serialize, Deserialize, Merge, Setters)]
+#[setters(strip_option, into)]
+pub struct Agent {
+    // Existing fields...
+    
+    /// Configuration for automatic context compaction
+    /// When provided, enables automatic context management based on specified triggers
+    #[serde(skip_serializing_if = "Option::is_none")]
+    #[merge(strategy = crate::merge::option)]
+    pub compact: Option<Compaction>,
+    
+    // Other existing fields...
+}
+```
+
+### 3. Implement Context Compaction Logic
+
+Modify the `Orchestrator` implementation in `crates/forge_domain/src/orch.rs` to apply context compaction automatically:
+
+```rust
+impl<A: App> Orchestrator<A> {
+    // Add a new method to compact context
+    async fn compact_context(
+        &self, 
+        agent: &Agent, 
+        context: &mut Context
+    ) -> anyhow::Result<()> {
+        if let Some(config) = &agent.compact {
+            let max_tokens = config.max_tokens;
+            
+            // Use the existing Summarize mechanism
+            let mut summarize = Summarize::new(context, max_tokens);
+            while let Some(mut summary) = summarize.summarize() {
+                // Get the content to summarize
+                let content_to_summarize = summary.get();
+                
+                // TODO: In a future enhancement, we could use an AI model to generate better summaries
+                // For now, use a simple placeholder that the existing code will handle
+                summary.set("Summary of previous conversation");
+            }
+        }
+        Ok(())
+    }
+    
+    // Modify the init_agent_with_event method to check for compaction
+    async fn init_agent_with_event(&self, agent_id: &AgentId, event: &Event) -> anyhow::Result<()> {
+        // Existing code...
+        
+        // Before sending the context to the provider, check if compaction is needed
+        if let Some(config) = &agent.compact {
+            let turn_count = self.conversation.read().await.turn_count(&agent.id).unwrap_or(0);
+            let message_count = context.messages.len();
+            
+            if config.should_compact(&context, turn_count, message_count) {
+                self.compact_context(agent, &mut context).await?;
+                self.set_context(&agent.id, context.clone()).await?;
+            }
+        }
+        
+        // Continue with existing code...
+    }
+}
+```
+
+### 4. Update the Summarize Implementation
+
+Enhance the `Summarize` implementation in `crates/forge_domain/src/summarize.rs` to better handle context compaction:
+
+```rust
+// Add support for better summarization metrics
+fn token_count(text: &str) -> usize {
+    // This is a placeholder for a more accurate token counting function
+    // In a production implementation, this should use a proper tokenizer
+    text.split_whitespace().count() * 75 / 100
+}
+```
+
+### 5. Update or Deprecate the Transform::Assistant Variant
+
+Since we're dropping the transform-based approach, we need to handle the transition:
+
+1. Add a deprecation comment to the `Transform::Assistant` variant:
+```rust
+#[derive(Debug, Clone, Serialize, Deserialize)]
+#[serde(tag = "type", rename_all = "snake_case")]
+pub enum Transform {
+    /// Compresses multiple assistant messages into a single message
+    /// 
+    /// DEPRECATED: Use the new `compact` field on the Agent struct instead.
+    #[deprecated(
+        since = "next_version",
+        note = "Use the compact field on Agent instead"
+    )]
+    Assistant {
+        // existing fields...
+    },
+    
+    // Other variants...
+}
+```
+
+2. Add logging in the `execute_transform` method to warn about deprecated usage:
+```rust
+async fn execute_transform(
+    &self,
+    transforms: &[Transform],
+    mut context: Context,
+) -> anyhow::Result<Context> {
+    for transform in transforms.iter() {
+        match transform {
+            Transform::Assistant { .. } => {
+                tracing::warn!(
+                    "Transform::Assistant is deprecated. Use the compact field on Agent instead."
+                );
+                // Existing implementation...
+            },
+            // Other variants...
+        }
+    }
+    // Rest of the method...
+}
+```
+
+### 6. Add Tests
+
+Add new tests in `crates/forge_domain/src/agent.rs`:
+
+```rust
+#[cfg(test)]
+mod compact_tests {
+    use pretty_assertions::assert_eq;
+    use super::*;
+
+    #[test]
+    fn compact_config() {
+        let config = Compaction::new(1000)
+            .token_threshold(2000)
+            .turn_threshold(5)
+            .message_threshold(20);
+            
+        assert_eq!(config.max_tokens, 1000);
+        assert_eq!(config.token_threshold, Some(2000));
+        assert_eq!(config.turn_threshold, Some(5));
+        assert_eq!(config.message_threshold, Some(20));
+    }
+    
+    #[test]
+    fn test_should_compact() {
+        let config = Compaction::new(1000)
+            .token_threshold(2000)
+            .turn_threshold(5);
+            
+        // Mock context with token count > threshold
+        let mut context = Context::default();
+        for _ in 0..100 {
+            context = context.add_message(ContextMessage::user("Long message that would exceed the token threshold"));
+        }
+        
+        // Should compact due to token threshold
+        assert!(config.should_compact(&context, 1, 100));
+        
+        // Should compact due to turn threshold
+        assert!(config.should_compact(&context, 5, 100));
+        
+        // Should not compact for low values
+        let config = Compaction::new(1000)
+            .token_threshold(100000) // Very high threshold
+            .turn_threshold(100);    // Very high threshold
+        
+        assert!(!config.should_compact(&context, 1, 100));
+    }
+    
+    #[test]
+    fn compact() {
+        let config1 = Compaction::new(1000).token_threshold(2000);
+        let config2 = Compaction::new(1500).turn_threshold(3);
+        
+        // Base has no value, should take other's value
+        let mut base = Agent::new("Base"); // No compact set
+        let other = Agent::new("Other").compact(config2.clone());
+        base.merge(other);
+        assert_eq!(base.compact.as_ref().unwrap().max_tokens, 1500);
+        assert_eq!(base.compact.as_ref().unwrap().turn_threshold, Some(3));
+        
+        // Base has a value, should be overwritten
+        let mut base = Agent::new("Base").compact(config1.clone());
+        let other = Agent::new("Other").compact(config2.clone());
+        base.merge(other);
+        assert_eq!(base.compact.as_ref().unwrap().max_tokens, 1500);
+        assert_eq!(base.compact.as_ref().unwrap().turn_threshold, Some(3));
+        assert_eq!(base.compact.as_ref().unwrap().token_threshold, None);
+        
+        // Other has no value, should keep base's value
+        let mut base = Agent::new("Base").compact(config1.clone());
+        let other = Agent::new("Other"); // No compact set
+        base.merge(other);
+        assert_eq!(base.compact.as_ref().unwrap().max_tokens, 1000);
+        assert_eq!(base.compact.as_ref().unwrap().token_threshold, Some(2000));
+    }
+}
+```
+
+### 7. Update Documentation and Examples
+
+Add examples in documentation and configuration files:
+
+```yaml
+# Example in forge.yaml
+agents:
+  myAgent:
+    id: myAgent
+    model: gpt-4-turbo
+    system_prompt: "You are a helpful assistant."
+    compact:
+      max_tokens: 4000
+      token_threshold: 6000
+      turn_threshold: 10
+      message_threshold: 30
+```
+
+## Verification Criteria
+
+1. The `Compaction` struct should be correctly defined with all required fields and methods
+2. The `Agent` struct should have a new `compact` field that follows the existing patterns
+3. The orchestrator should automatically apply context compaction when the configured conditions are met
+4. The transform-based approach should be properly deprecated with warnings
+5. All tests should pass, demonstrating that the compaction logic works as expected
+6. Documentation and examples should clearly explain how to use the new feature
+
+## Implementation Steps
+
+1. Add the `Compaction` struct to `agent.rs`
+2. Add the `compact` field to the `Agent` struct
+3. Implement the `compact_context` method in the Orchestrator
+4. Update the `init_agent_with_event` method to check for compaction
+5. Enhance the token counting mechanism
+6. Deprecate the `Transform::Assistant` variant
+7. Add tests for the new functionality
+8. Update documentation and examples
+
+This implementation provides a flexible and automatic way to manage context compaction based on various triggers, replacing the more complex transform-based approach.

plans/agent-context-compaction-2025-03-25-concise.md

@@ -0,0 +1,220 @@
+# Context Compaction Logic Update Plan (Revised)
+
+## Objective
+
+Modify the context compaction logic in `crates/forge_domain/src/compaction.rs` to identify and compress only one continuous sequence of assistant messages at a time, rather than processing all sequences at once or compressing the entire context.
+
+## Current Implementation Analysis
+
+The current implementation in `compaction.rs` performs compaction on the entire context as a single unit:
+
+1. It checks if compaction is needed via `should_perform_compaction`
+2. If needed, it generates a summary of the entire context
+3. It then builds a new compacted context with just the summary
+
+This approach doesn't distinguish between different message roles or sequences, treating all messages equally in the compaction process.
+
+## Revised Implementation Plan
+
+### 1. Identify Single Compressible Sequence
+
+Add functionality to identify only the first sequence of assistant messages that qualify for compression:
+
+```rust
+/// Identifies the first sequence of assistant messages that can be compressed (2+ consecutive messages)
+fn identify_first_compressible_sequence(&self, context: &Context) -> Option<(usize, usize)> {
+    let messages = context.messages();
+    let mut current_sequence_start: Option<usize> = None;
+    
+    for (i, message) in messages.iter().enumerate() {
+        if message.is_assistant() {
+            // Start a new sequence or continue current one
+            if current_sequence_start.is_none() {
+                current_sequence_start = Some(i);
+            }
+        } else {
+            // End of a potential sequence
+            if let Some(start) = current_sequence_start {
+                // Only compress sequences with more than 1 assistant message
+                if i - start > 1 {
+                    return Some((start, i - 1));
+                }
+                current_sequence_start = None;
+            }
+        }
+    }
+    
+    // Check for a sequence at the end
+    if let Some(start) = current_sequence_start {
+        let end = messages.len() - 1;
+        if end - start > 0 {  // More than 1 message
+            return Some((start, end));
+        }
+    }
+    
+    None // No compressible sequence found
+}
+```
+
+### 2. Update Main Compaction Method
+
+Modify the main compaction method to identify and compress just one sequence:
+
+```rust
+pub async fn compact_context(&self, agent: &Agent, context: Context) -> Result<Context> {
+    if !self.should_perform_compaction(agent, &context) {
+        return Ok(context);
+    }
+    
+    debug!(
+        agent_id = %agent.id,
+        "Context compaction triggered"
+    );
+    
+    // Identify the first compressible sequence
+    if let Some(sequence) = self.identify_first_compressible_sequence(&context) {
+        debug!(
+            agent_id = %agent.id,
+            sequence_start = sequence.0,
+            sequence_end = sequence.1,
+            "Compressing assistant message sequence"
+        );
+        
+        // Compress just this sequence
+        self.compress_single_sequence(agent, context, sequence).await
+    } else {
+        debug!(agent_id = %agent.id, "No compressible sequences found");
+        Ok(context)
+    }
+}
+```
+
+### 3. Implement Single Sequence Compression
+
+Create a method to handle the compression of a single identified sequence:
+
+```rust
+async fn compress_single_sequence(
+    &self, 
+    agent: &Agent, 
+    original_context: Context, 
+    sequence: (usize, usize)
+) -> Result<Context> {
+    let messages = original_context.messages();
+    let (start, end) = sequence;
+    
+    // Extract the sequence to summarize
+    let sequence_messages = &messages[start..=end];
+    
+    // Generate summary for this sequence
+    let summary = self.generate_summary_for_sequence(agent, sequence_messages).await?;
+    
+    // Build a new context with the sequence replaced by the summary
+    let mut compacted_messages = Vec::new();
+    
+    // Add messages before the sequence
+    compacted_messages.extend(messages[0..start].to_vec());
+    
+    // Add the summary as a single assistant message
+    compacted_messages.push(ContextMessage::assistant(summary, None));
+    
+    // Add messages after the sequence
+    if end + 1 < messages.len() {
+        compacted_messages.extend(messages[end+1..].to_vec());
+    }
+    
+    // Build the new context
+    let mut compacted_context = Context::default();
+    
+    // Add system message if present in original context
+    if let Some(system_msg) = original_context.system_message() {
+        compacted_context = compacted_context.set_first_system_message(system_msg.clone());
+    }
+    
+    // Add all the processed messages
+    for msg in compacted_messages {
+        compacted_context = compacted_context.add_message(msg);
+    }
+    
+    Ok(compacted_context)
+}
+```
+
+### 4. Implement Sequence-Based Summary Generation
+
+Create a method to generate summaries for a specific sequence:
+
+```rust
+async fn generate_summary_for_sequence(
+    &self, 
+    agent: &Agent, 
+    messages: &[ContextMessage]
+) -> Result<String> {
+    let compact = agent.compact.as_ref().unwrap();
+
+    // Create a temporary context with just the sequence for summarization
+    let mut sequence_context = Context::default();
+    for msg in messages {
+        sequence_context = sequence_context.add_message(msg.clone());
+    }
+    
+    // Render the summarization prompt
+    let prompt = self
+        .services
+        .template_service()
+        .render_summarization(agent, &sequence_context)
+        .await?;
+
+    let message = ContextMessage::user(prompt);
+    let summary_context = Context::default().add_message(message);
+
+    // Get summary from the provider
+    let response = self
+        .services
+        .provider_service()
+        .chat(&compact.model, summary_context)
+        .await?;
+
+    self.collect_completion_stream_content(response).await
+}
+```
+
+### 5. Update Helper Methods
+
+The `should_perform_compaction` method remains unchanged since it's still applicable. The `collect_completion_stream_content` also remains as is.
+
+### 6. Remove Unused Methods
+
+The original `generate_summary` and `build_compacted_context` methods will be replaced by our new sequence-based methods, so they can be removed or repurposed.
+
+## Implementation Considerations
+
+1. **Processing Only One Sequence**: This approach only compresses one sequence at a time, which means that if there are multiple compressible sequences, only the first one will be compressed in a single call to `compact_context`. 
+
+2. **Repeated Compaction**: If desired, the caller can repeatedly call `compact_context` to compress additional sequences over multiple iterations.
+
+3. **Processing Order**: Sequences are identified from the beginning of the context, so the first eligible sequence found will be compressed first.
+
+4. **Message Order Preservation**: This approach preserves the order of all non-compressed messages, maintaining the conversation flow.
+
+## Verification Criteria
+
+1. **Correctness**: The compacted context should:
+   - Preserve all user messages in their original positions
+   - Replace only the first sequence of 2+ assistant messages with a summary
+   - Keep single assistant messages unchanged
+   - Keep other sequences of assistant messages unchanged (they are not processed in this call)
+
+2. **Functionality**:
+   - The compaction should trigger under the same conditions as before
+   - Summary generation should work properly for the identified sequence
+   - The context structure should be preserved
+
+3. **Edge Cases**:
+   - Empty contexts should be handled properly
+   - Contexts with no compressible sequences should be returned unchanged
+   - Boundary conditions (sequence at start/end of context) should work correctly
+
+4. **Performance**:
+   - This approach should be more efficient as it only processes one sequence per call
+   - Only one API call for summarization is made per call to `compact_context`

plans/agent-context-compaction-2025-03-25.md

@@ -0,0 +1,217 @@
+# Context Compaction Logic Update Plan
+
+## Objective
+
+Modify the context compaction logic in `crates/forge_domain/src/compaction.rs` to identify and compress only continuous sequences of assistant messages, rather than compressing the entire context. This will provide more targeted and effective context compression while preserving the structure of conversations.
+
+## Current Implementation Analysis
+
+The current implementation in `compaction.rs` performs compaction on the entire context as a single unit:
+
+1. It checks if compaction is needed via `should_perform_compaction`
+2. If needed, it generates a summary of the entire context
+3. It then builds a new compacted context with just the summary
+
+This approach doesn't distinguish between different message roles or sequences, treating all messages equally in the compaction process.
+
+## Implementation Plan
+
+### 1. Identify Compressible Sequences
+
+Add functionality to identify sequences of assistant messages that qualify for compression:
+
+```rust
+/// Identifies sequences of assistant messages that can be compressed (2+ consecutive messages)
+fn identify_compressible_sequences(&self, context: &Context) -> Vec<(usize, usize)> {
+    let messages = context.messages();
+    let mut sequences = Vec::new();
+    let mut current_sequence_start: Option<usize> = None;
+    
+    for (i, message) in messages.iter().enumerate() {
+        if message.is_assistant() {
+            // Start a new sequence or continue current one
+            if current_sequence_start.is_none() {
+                current_sequence_start = Some(i);
+            }
+        } else {
+            // End of a potential sequence
+            if let Some(start) = current_sequence_start {
+                // Only compress sequences with more than 1 assistant message
+                if i - start > 1 {
+                    sequences.push((start, i - 1));
+                }
+                current_sequence_start = None;
+            }
+        }
+    }
+    
+    // Check for a sequence at the end
+    if let Some(start) = current_sequence_start {
+        let end = messages.len() - 1;
+        if end - start > 0 {  // More than 1 message
+            sequences.push((start, end));
+        }
+    }
+    
+    sequences
+}
+```
+
+### 2. Update Main Compaction Method
+
+Modify the main compaction method to use the sequence identification:
+
+```rust
+pub async fn compact_context(&self, agent: &Agent, context: Context) -> Result<Context> {
+    if !self.should_perform_compaction(agent, &context) {
+        return Ok(context);
+    }
+    
+    debug!(
+        agent_id = %agent.id,
+        "Context compaction triggered"
+    );
+    
+    // Identify compressible sequences
+    let sequences = self.identify_compressible_sequences(&context);
+    
+    if sequences.is_empty() {
+        debug!(agent_id = %agent.id, "No compressible sequences found");
+        return Ok(context);
+    }
+    
+    // Process the compressible sequences and build new context
+    let compacted_context = self.compress_context_sequences(agent, context, sequences).await?;
+    
+    Ok(compacted_context)
+}
+```
+
+### 3. Implement Sequence Compression
+
+Create a method to handle the compression of identified sequences:
+
+```rust
+async fn compress_context_sequences(
+    &self, 
+    agent: &Agent, 
+    original_context: Context, 
+    sequences: Vec<(usize, usize)>
+) -> Result<Context> {
+    let messages = original_context.messages();
+    let mut compacted_messages = Vec::new();
+    
+    let mut next_index = 0;
+    
+    // Process each sequence
+    for (start, end) in sequences {
+        // Add any messages before this sequence
+        compacted_messages.extend(messages[next_index..start].to_vec());
+        
+        // Extract the sequence to summarize
+        let sequence = &messages[start..=end];
+        
+        // Only process if we have multiple assistant messages (safety check)
+        if sequence.len() > 1 && sequence.iter().all(|m| m.is_assistant()) {
+            // Generate summary for this sequence
+            let summary = self.generate_summary_for_sequence(agent, sequence).await?;
+            
+            // Add the summary as a single assistant message
+            compacted_messages.push(ContextMessage::assistant(summary, None));
+        } else {
+            // If not eligible for compression, keep original messages
+            compacted_messages.extend(sequence.to_vec());
+        }
+        
+        next_index = end + 1;
+    }
+    
+    // Add any remaining messages
+    if next_index < messages.len() {
+        compacted_messages.extend(messages[next_index..].to_vec());
+    }
+    
+    // Build the new context
+    let mut compacted_context = Context::default();
+    
+    // Add system message if present in original context
+    if let Some(system_msg) = original_context.system_message() {
+        compacted_context = compacted_context.set_first_system_message(system_msg.clone());
+    }
+    
+    // Add all the processed messages
+    for msg in compacted_messages {
+        compacted_context = compacted_context.add_message(msg);
+    }
+    
+    Ok(compacted_context)
+}
+```
+
+### 4. Update Summary Generation
+
+Create a method to generate summaries for specific sequences:
+
+```rust
+async fn generate_summary_for_sequence(
+    &self, 
+    agent: &Agent, 
+    messages: &[ContextMessage]
+) -> Result<String> {
+    let compact = agent.compact.as_ref().unwrap();
+
+    // Create a temporary context with just the sequence for summarization
+    let mut sequence_context = Context::default();
+    for msg in messages {
+        sequence_context = sequence_context.add_message(msg.clone());
+    }
+    
+    // Render the summarization prompt
+    let prompt = self
+        .services
+        .template_service()
+        .render_summarization(agent, &sequence_context)
+        .await?;
+
+    let message = ContextMessage::user(prompt);
+    let summary_context = Context::default().add_message(message);
+
+    // Get summary from the provider
+    let response = self
+        .services
+        .provider_service()
+        .chat(&compact.model, summary_context)
+        .await?;
+
+    self.collect_completion_stream_content(response).await
+}
+```
+
+### 5. Update Helper Methods
+
+The `should_perform_compaction` method remains unchanged since it's still applicable.
+
+### 6. Remove Unused Methods
+
+The original `generate_summary` and `build_compacted_context` methods will be replaced by our new sequence-based methods, so they can be removed or repurposed.
+
+## Verification Criteria
+
+1. **Correctness**: The compacted context should:
+   - Preserve all user messages in their original positions
+   - Replace only sequences of 2+ assistant messages with summaries
+   - Keep single assistant messages unchanged
+
+2. **Functionality**:
+   - The compaction should trigger under the same conditions as before
+   - Summary generation should work properly for each sequence
+   - The context structure should be preserved
+
+3. **Edge Cases**:
+   - Empty contexts should be handled properly
+   - Contexts with no compressible sequences should be returned unchanged
+   - Boundary conditions (sequences at start/end of context) should work correctly
+
+4. **Performance**:
+   - Any performance impact should be minimal, especially for large contexts
+   - The number of API calls for summarization should be proportional to the number of compressible sequences

renovate.json

@@ -0,0 +1,8 @@
+{
+  "$schema": "https://docs.renovatebot.com/renovate-schema.json",
+  "extends": [
+    "config:recommended"
+  ],
+  "automerge": true,
+  "platformAutomerge": true
+}

rust-analyzer.toml

@@ -0,0 +1,23 @@
+[workspace]
+# Enable proc-macro support
+procMacro.enable = true
+procMacro.ignored = {}
+
+# Improve macro expansion
+cargo.buildScripts.enable = true
+cargo.buildScripts.invocationStrategy = "per_workspace"
+cargo.buildScripts.invocationLocation = "workspace"
+
+# Better error handling for macros
+diagnostics.disabled = []
+diagnostics.warningsAsHint = []
+
+# Improve performance with large workspaces
+cargo.allTargets = false
+cargo.target = null
+
+# Enable all features for better analysis
+cargo.allFeatures = true
+
+# Improve macro expansion limits
+expand.limit = 512

rust-toolchain.toml

@@ -0,0 +1,3 @@
+[toolchain]
+channel = "1.97"
+profile = "default"

shell-plugin/forge.theme.zsh

@@ -0,0 +1,28 @@
+#!/usr/bin/env zsh
+
+# Enable prompt substitution for RPROMPT
+setopt PROMPT_SUBST
+
+# Model and agent info with token count
+# Fully formatted output directly from Rust
+# Returns ZSH-formatted string ready for use in RPROMPT
+function _forge_prompt_info() {
+    local forge_bin="${_FORGE_BIN:-${FORGE_BIN:-forge}}"
+    
+    # Get fully formatted prompt from forge (single command).
+    # Pass session model/provider as CLI flags when set so the rprompt
+    # reflects the active session override rather than global config.
+    local -a forge_cmd
+    forge_cmd=("$forge_bin")
+    forge_cmd+=(zsh rprompt)
+    [[ -n "$_FORGE_SESSION_MODEL" ]] && local -x FORGE_SESSION__MODEL_ID="$_FORGE_SESSION_MODEL"
+    [[ -n "$_FORGE_SESSION_PROVIDER" ]] && local -x FORGE_SESSION__PROVIDER_ID="$_FORGE_SESSION_PROVIDER"
+    [[ -n "$_FORGE_SESSION_REASONING_EFFORT" ]] && local -x FORGE_REASONING__EFFORT="$_FORGE_SESSION_REASONING_EFFORT"
+    _FORGE_CONVERSATION_ID=$_FORGE_CONVERSATION_ID _FORGE_ACTIVE_AGENT=$_FORGE_ACTIVE_AGENT COLUMNS=$COLUMNS "${forge_cmd[@]}" 2>/dev/null
+}
+
+# Right prompt: agent and model with token count (uses single forge prompt command)
+# Set RPROMPT if empty, otherwise append to existing value
+if [[ -z "$_FORGE_THEME_LOADED" ]]; then
+    RPROMPT='$(_forge_prompt_info)'"${RPROMPT:+ ${RPROMPT}}"
+fi

vertex.json

@@ -0,0 +1,112 @@
+[
+  {
+    "id": "google/gemini-3.5-flash",
+    "name": "Gemini 3.5 Flash",
+    "description": "",
+    "context_length": 1048576,
+    "tools_supported": true,
+    "supports_parallel_tool_calls": true,
+    "supports_reasoning": true,
+    "input_modalities": ["text", "image"]
+  },
+  {
+    "id": "mistral/mistral-large-2411",
+    "name": "Mistral Large 2411",
+    "description": "Mistral's powerful large language model",
+    "context_length": 128000,
+    "tools_supported": true,
+    "supports_parallel_tool_calls": true,
+    "supports_reasoning": false,
+    "input_modalities": ["text"]
+  },
+  {
+    "id": "mistral/mistral-small-2503",
+    "name": "Mistral Small 2503",
+    "description": "Mistral's efficient small language model",
+    "context_length": 128000,
+    "tools_supported": true,
+    "supports_parallel_tool_calls": true,
+    "supports_reasoning": false,
+    "input_modalities": ["text"]
+  },
+  {
+    "id": "mistral/codestral-2501",
+    "name": "Codestral 2501",
+    "description": "Mistral's code-specialized model",
+    "context_length": 256000,
+    "tools_supported": true,
+    "supports_parallel_tool_calls": true,
+    "supports_reasoning": false,
+    "input_modalities": ["text"]
+  },
+  {
+    "id": "meta/llama-4-maverick-17b-128e-instruct-maas",
+    "name": "Llama 4 Maverick 17B",
+    "description": "Meta's large instruction-tuned model with extended context",
+    "context_length": 1048576,
+    "tools_supported": true,
+    "supports_parallel_tool_calls": true,
+    "supports_reasoning": false,
+    "input_modalities": ["text"]
+  },
+  {
+    "id": "meta/llama-4-scout-17b-16e-instruct-maas",
+    "name": "Llama 4 Scout 17B",
+    "description": "Meta's efficient instruction-tuned model with massive context",
+    "context_length": 10485760,
+    "tools_supported": true,
+    "supports_parallel_tool_calls": true,
+    "supports_reasoning": false,
+    "input_modalities": ["text"]
+  },
+  {
+    "id": "google/gemini-2.0-flash-001",
+    "name": "Gemini 2.0 Flash 001",
+    "description": "Google's fast and capable multimodal model",
+    "context_length": 1048576,
+    "tools_supported": true,
+    "supports_parallel_tool_calls": true,
+    "supports_reasoning": true,
+    "input_modalities": ["text", "image"]
+  },
+  {
+    "id": "google/gemini-2.5-pro",
+    "name": "Gemini 2.5 Pro",
+    "description": "Google's most capable multimodal model",
+    "context_length": 1048576,
+    "tools_supported": true,
+    "supports_parallel_tool_calls": true,
+    "supports_reasoning": true,
+    "input_modalities": ["text", "image"]
+  },
+  {
+    "id": "google/gemini-2.5-flash",
+    "name": "Gemini 2.5 Flash",
+    "description": "Google's fast and capable model with thinking support",
+    "context_length": 1048576,
+    "tools_supported": true,
+    "supports_parallel_tool_calls": true,
+    "supports_reasoning": true,
+    "input_modalities": ["text", "image"]
+  },
+  {
+    "id": "google/gemini-3-pro-preview",
+    "name": "Gemini 3 Pro Preview",
+    "description": "Google's fast and capable model with thinking support",
+    "context_length": 1048576,
+    "tools_supported": true,
+    "supports_parallel_tool_calls": true,
+    "supports_reasoning": true,
+    "input_modalities": ["text", "image"]
+  },
+  {
+    "id": "google/gemini-3-flash-preview",
+    "name": "Gemini 3 Flash Preview",
+    "description": "Google's fast and capable model with thinking support",
+    "context_length": 1048576,
+    "tools_supported": true,
+    "supports_parallel_tool_calls": true,
+    "supports_reasoning": true,
+    "input_modalities": ["text", "image"]
+  }
+]