Add files using upload-large-folder tool

crates/forge_ci/src/jobs/bounty_job.rs

@@ -0,0 +1,74 @@
+//! Jobs for the bounty management workflow (v2).
+//!
+//! v2 uses a state-reconciliation model: each job fetches the full current
+//! state of an issue or PR from GitHub, computes the desired label set from
+//! the rules engine, diffs current vs desired, and applies the minimal patch.
+//!
+//! Three entry points:
+//! - `sync-all-issues.ts` — fetches all open issues with any bounty label and
+//!   reconciles their label sets in one pass. Runs on a schedule and on label
+//!   events.
+//! - `sync-pr.ts --pr N` — propagates labels from linked issues to the PR;
+//!   handles the rewarded lifecycle on merge.
+
+use gh_workflow::*;
+
+const SCRIPTS_DIR: &str = ".github/scripts/bounty/src";
+const TSX: &str = "npx tsx";
+
+/// Returns a checkout step — required before script invocation.
+fn checkout_step() -> Step<Use> {
+    Step::new("Checkout").uses("actions", "checkout", "v6")
+}
+
+/// Builds a three-step job: checkout + npm install + a single script
+/// invocation.
+fn sync_job(job_name: &str, script: &str, args: String) -> Job {
+    let cmd = format!("{TSX} {SCRIPTS_DIR}/{script} {args}");
+    Job::new(job_name)
+        .add_step(checkout_step())
+        .add_step(Step::new("Install npm packages").run("npm install"))
+        .add_step(Step::new("Sync bounty labels").run(cmd))
+}
+
+/// Creates a job that syncs bounty labels across all open issues that carry
+/// any bounty label.
+///
+/// Fetches every open issue with a "bounty" label prefix, computes the desired
+/// state for each, and applies the minimal patch in a single pass.
+///
+/// Triggered on: issues labeled/unlabeled/assigned/unassigned, and on schedule.
+pub fn sync_all_issues_job() -> Job {
+    let cmd = format!(
+        "{TSX} {SCRIPTS_DIR}/sync-all-issues.ts \
+            --repo ${{{{ github.repository }}}} \
+            --token ${{{{ secrets.GITHUB_TOKEN }}}} \
+            --execute"
+    );
+    Job::new("Sync all bounty issues")
+        .add_step(checkout_step())
+        .add_step(Step::new("Install npm packages").run("npm install"))
+        .add_step(Step::new("Sync all bounty labels").run(cmd))
+        .permissions(Permissions::default().issues(Level::Write))
+}
+
+/// Creates a job that propagates bounty labels from linked issues to the PR
+/// and handles the rewarded lifecycle when the PR is merged.
+///
+/// Triggered on: pull_request opened/edited/reopened, pull_request_target
+/// closed.
+pub fn sync_pr_job() -> Job {
+    sync_job(
+        "Sync PR bounty labels",
+        "sync-pr.ts",
+        "--pr ${{ github.event.pull_request.number }} \
+            --repo ${{ github.repository }} \
+            --token ${{ secrets.GITHUB_TOKEN }}"
+            .to_string(),
+    )
+    .permissions(
+        Permissions::default()
+            .issues(Level::Write)
+            .pull_requests(Level::Write),
+    )
+}

crates/forge_ci/src/jobs/build.rs

@@ -0,0 +1,9 @@
+use gh_workflow::*;
+
+use crate::jobs::release_build_job::release_build_job;
+
+/// Create a build job for drafts
+pub fn create_build_release_job_for_publishing() -> Job {
+    release_build_job("${{ github.event.release.tag_name }}", true)
+}
+

crates/forge_ci/src/jobs/draft_release_update_job.rs

@@ -0,0 +1,21 @@
+use gh_workflow::*;
+
+/// Create a job to update the release draft
+pub fn draft_release_update_job() -> Job {
+    Job::new("update_release_draft")
+        .add_step(
+            Step::new("Auto Labeler")
+                .uses("release-drafter", "release-drafter/autolabeler", "v7")
+                .if_condition(Expression::new(
+                    "github.event_name == 'pull_request_target'",
+                ))
+                .env(("GITHUB_TOKEN", "${{ secrets.GITHUB_TOKEN }}"))
+                .add_with(("config-name", "release-drafter.yml")),
+        )
+        .add_step(
+            Step::new("Release Drafter")
+                .uses("release-drafter", "release-drafter", "v7")
+                .env(("GITHUB_TOKEN", "${{ secrets.GITHUB_TOKEN }}"))
+                .add_with(("config-name", "release-drafter.yml")),
+        )
+}

crates/forge_ci/src/jobs/label_sync_job.rs

@@ -0,0 +1,20 @@
+use gh_workflow::*;
+
+/// Create a job to sync GitHub labels
+pub fn label_sync_job() -> Job {
+    Job::new("label-sync")
+        .permissions(
+            Permissions::default()
+                .issues(Level::Write)
+        )
+        .add_step(
+            Step::new("Checkout Code").uses("actions", "checkout", "v6")
+                .name("Checkout")
+        )
+        .add_step(
+            Step::new("Sync Labels").run(
+                "npx github-label-sync \\\n  --access-token ${{ secrets.GITHUB_TOKEN }} \\\n  --labels \".github/labels.json\" \\\n  ${{ github.repository }}"
+            )
+                .name("Sync labels")
+        )
+}

crates/forge_ci/src/jobs/lint.rs

@@ -0,0 +1,68 @@
+//! Shared lint commands for CI workflows
+
+/// Build a cargo command from parts
+fn cargo_cmd(parts: &[&str]) -> String {
+    parts.join(" ")
+}
+
+/// Base parts for fmt commands
+fn fmt_base() -> Vec<&'static str> {
+    vec!["cargo", "+nightly", "fmt", "--all"]
+}
+
+/// Base parts for clippy commands (shared across all clippy invocations).
+fn clippy_base() -> Vec<&'static str> {
+    vec![
+        "cargo",
+        "+nightly",
+        "clippy",
+        "--all-features",
+        "--workspace",
+    ]
+}
+
+/// Build a cargo fmt command
+pub fn fmt_cmd(fix: bool) -> String {
+    let mut parts = fmt_base();
+    if !fix {
+        parts.push("--check");
+    }
+    cargo_cmd(&parts)
+}
+
+/// Build a cargo clippy command that checks all targets for general warnings.
+pub fn clippy_cmd(fix: bool) -> String {
+    let mut parts = clippy_base();
+    parts.push("--all-targets");
+
+    if fix {
+        parts.extend(["--fix", "--allow-dirty"]);
+    }
+
+    parts.extend(["--", "-D", "warnings"]);
+
+    cargo_cmd(&parts)
+}
+
+/// Build a cargo clippy command for UTF-8 and indexing safety lints.
+///
+/// Excludes test code by omitting `--all-targets`.
+pub fn clippy_string_safety_cmd(fix: bool) -> String {
+    let mut parts = clippy_base();
+
+    if fix {
+        parts.extend(["--fix", "--allow-dirty"]);
+    }
+
+    parts.extend([
+        "--",
+        "-D",
+        "clippy::string_slice",
+        "-D",
+        "clippy::indexing_slicing",
+        "-D",
+        "clippy::disallowed_methods",
+    ]);
+
+    cargo_cmd(&parts)
+}

crates/forge_ci/src/jobs/mod.rs

@@ -0,0 +1,21 @@
+//! Jobs for CI workflows
+
+mod bounty_job;
+mod draft_release_update_job;
+mod label_sync_job;
+mod lint;
+mod release_build_job;
+mod release_draft;
+mod release_draft_pr;
+mod release_homebrew;
+mod release_npm;
+
+pub use bounty_job::*;
+pub use draft_release_update_job::*;
+pub use label_sync_job::*;
+pub use lint::*;
+pub use release_build_job::*;
+pub use release_draft::*;
+pub use release_draft_pr::*;
+pub use release_homebrew::*;
+pub use release_npm::*;

crates/forge_ci/src/jobs/release_build_job.rs

@@ -0,0 +1,103 @@
+use derive_setters::Setters;
+use gh_workflow::*;
+
+use crate::release_matrix::ReleaseMatrix;
+use crate::steps::setup_protoc;
+
+#[derive(Clone, Default, Setters)]
+#[setters(strip_option, into)]
+pub struct ReleaseBuilderJob {
+    // Required to burn into the binary
+    pub version: String,
+
+    // When provide the generated release will be uploaded
+    pub release_id: Option<String>,
+}
+
+impl ReleaseBuilderJob {
+    pub fn new(version: impl AsRef<str>) -> Self {
+        Self { version: version.as_ref().to_string(), release_id: None }
+    }
+
+    pub fn into_job(self) -> Job {
+        self.into()
+    }
+}
+
+impl From<ReleaseBuilderJob> for Job {
+    fn from(value: ReleaseBuilderJob) -> Job {
+        let mut job = Job::new("build-release")
+            .strategy(Strategy {
+                fail_fast: None,
+                max_parallel: None,
+                matrix: Some(ReleaseMatrix::default().into()),
+            })
+            .runs_on("${{ matrix.os }}")
+            .permissions(
+                Permissions::default()
+                    .contents(Level::Write)
+                    .pull_requests(Level::Write),
+            )
+            .add_step(Step::new("Checkout Code").uses("actions", "checkout", "v6"))
+            // Install protobuf compiler for non-cross builds
+            // Cross builds install protoc via Cross.toml pre-build commands
+            .add_step(
+                setup_protoc().if_condition(Expression::new("${{ matrix.cross == 'false' }}")),
+            )
+            // Install Rust with cross-compilation target
+            .add_step(
+                Step::new("Setup Cross Toolchain")
+                    .uses("taiki-e", "setup-cross-toolchain-action", "v1")
+                    .with(("target", "${{ matrix.target }}"))
+                    .if_condition(Expression::new("${{ matrix.cross == 'false' }}")),
+            )
+            // Explicitly add the target to ensure it's available
+            .add_step(
+                Step::new("Add Rust target")
+                    .run("rustup target add ${{ matrix.target }}")
+                    .if_condition(Expression::new("${{ matrix.cross == 'false' }}")),
+            )
+            // Build add link flags
+            .add_step(
+                Step::new("Set Rust Flags")
+                    .run(r#"echo "RUSTFLAGS=-C target-feature=+crt-static" >> $GITHUB_ENV"#)
+                    .if_condition(Expression::new(
+                        "!(contains(matrix.target, '-unknown-linux-') || contains(matrix.target, '-android'))",
+                    )),
+            )
+            // Build release binary
+            // Note: protoc is installed via:
+            // - arduino/setup-protoc action for non-cross builds
+            // - Cross.toml pre-build commands for cross builds (apt-get install protobuf-compiler)
+            .add_step(
+                Step::new("Build Binary")
+                    .uses("ClementTsang", "cargo-action", "v0.0.7")
+                    .add_with(("command", "build --release"))
+                    .add_with(("args", "--target ${{ matrix.target }}"))
+                    .add_with(("use-cross", "${{ matrix.cross }}"))
+                    .add_with(("cross-version", "0.2.5"))
+                    .add_env(("RUSTFLAGS", "${{ env.RUSTFLAGS }}"))
+                    .add_env(("POSTHOG_API_SECRET", "${{secrets.POSTHOG_API_SECRET}}"))
+                    .add_env(("APP_VERSION", value.version.to_string())),
+            );
+
+        if let Some(release_id) = value.release_id {
+            job = job
+                // Rename binary to target name
+                .add_step(
+                    Step::new("Copy Binary")
+                        .run("cp ${{ matrix.binary_path }} ${{ matrix.binary_name }}"),
+                )
+                // Upload to the generated github release id
+                .add_step(
+                    Step::new("Upload to Release")
+                        .uses("xresloader", "upload-to-github-release", "v1")
+                        .add_with(("release_id", release_id))
+                        .add_with(("file", "${{ matrix.binary_name }}"))
+                        .add_with(("overwrite", "true")),
+                );
+        }
+
+        job
+    }
+}

crates/forge_ci/src/jobs/release_draft.rs

@@ -0,0 +1,33 @@
+use gh_workflow::*;
+use indexmap::indexmap;
+
+/// Create a draft release job for GitHub Actions
+pub fn create_draft_release_job(build_job_id: &str) -> Job {
+    Job::new("draft_release")
+        .name("Draft Release")
+        .add_needs(build_job_id)
+        .cond(Expression::new(
+            "github.event_name == 'push' && github.ref == 'refs/heads/main'",
+        ))
+        // This job only runs on push to main, not needed for release events
+        .permissions(
+            Permissions::default()
+                .contents(Level::Write)
+                .pull_requests(Level::Write),
+        )
+        .add_step(Step::new("Checkout Code").uses("actions", "checkout", "v6"))
+        .add_step(
+            Step::new("Draft Release").uses("release-drafter", "release-drafter", "v7")
+                .id("create_release")
+                .env(("GITHUB_TOKEN", "${{ secrets.GITHUB_TOKEN }}"))
+                .with(("config-name", "release-drafter.yml")),
+        )
+        .add_step(
+            Step::new("Export Outputs").run("echo \"crate_release_id=${{ steps.create_release.outputs.id }}\" >> $GITHUB_OUTPUT && echo \"crate_release_name=${{ steps.create_release.outputs.tag_name }}\" >> $GITHUB_OUTPUT")
+                .id("set_output"),
+        )
+        .outputs(indexmap! {
+            "crate_release_name".to_string() => "${{ steps.set_output.outputs.crate_release_name }}".to_string(),
+            "crate_release_id".to_string() => "${{ steps.set_output.outputs.crate_release_id }}".to_string()
+        })
+}

crates/forge_ci/src/jobs/release_draft_pr.rs

@@ -0,0 +1,22 @@
+use gh_workflow::*;
+use indexmap::indexmap;
+
+/// Create a draft release job for GitHub Actions that runs on PRs
+pub fn create_draft_release_pr_job() -> Job {
+    Job::new("draft_release_pr")
+        .name("Draft Release for PR")
+        .cond(Expression::new(
+            "github.event_name == 'pull_request' && contains(github.event.pull_request.labels.*.name, 'ci: build all targets')",
+        ))
+        .add_step(Step::new("Checkout Code").uses("actions", "checkout", "v6"))
+        .add_step(
+            Step::new("Set Release Version").run(
+                r#"echo "crate_release_name=pr-build-${{ github.event.number }}" >> $GITHUB_OUTPUT && echo "crate_release_id=pr-build-${{ github.event.number }}" >> $GITHUB_OUTPUT"#,
+            )
+            .id("set_output"),
+        )
+        .outputs(indexmap! {
+            "crate_release_name".to_string() => "${{ steps.set_output.outputs.crate_release_name }}".to_string(),
+            "crate_release_id".to_string() => "${{ steps.set_output.outputs.crate_release_id }}".to_string()
+        })
+}

crates/forge_ci/src/jobs/release_homebrew.rs

@@ -0,0 +1,16 @@
+use gh_workflow::*;
+
+/// Create a homebrew release job
+pub fn release_homebrew_job() -> Job {
+    Job::new("homebrew_release")
+        .add_step(
+            Step::new("Checkout Code").uses("actions", "checkout", "v6")
+                .add_with(("repository", "antinomyhq/homebrew-code-forge"))
+                .add_with(("ref", "main"))
+                .add_with(("token", "${{ secrets.HOMEBREW_ACCESS }}")),
+        )
+        // Make script executable and run it with token
+        .add_step(
+            Step::new("Update Homebrew Formula").run("GITHUB_TOKEN=\"${{ secrets.HOMEBREW_ACCESS }}\" ./update-formula.sh ${{ github.event.release.tag_name }}"),
+        )
+}

crates/forge_ci/src/jobs/release_npm.rs

@@ -0,0 +1,35 @@
+use gh_workflow::*;
+use serde_json::Value;
+
+/// Create an NPM release job using matrix strategy for multiple repositories
+pub fn release_npm_job() -> Job {
+    let matrix = create_npm_matrix();
+
+    Job::new("npm_release")
+        .strategy(Strategy { fail_fast: None, max_parallel: None, matrix: Some(matrix) })
+        .add_step(
+            Step::new("Checkout Code")
+                .uses("actions", "checkout", "v6")
+                .add_with(("repository", "${{ matrix.repository }}"))
+                .add_with(("ref", "main"))
+                .add_with(("token", "${{ secrets.NPM_ACCESS }}")),
+        )
+        // Make script executable and run it with token
+        .add_step(
+            Step::new("Update NPM Package")
+                .run("./update-package.sh ${{ github.event.release.tag_name }}")
+                .add_env(("AUTO_PUSH", "true"))
+                .add_env(("CI", "true"))
+                .add_env(("NPM_TOKEN", "${{ secrets.NPM_TOKEN }}")),
+        )
+}
+
+/// Creates a matrix Value for NPM repositories
+fn create_npm_matrix() -> Value {
+    serde_json::json!({
+        "repository": [
+            "antinomyhq/npm-code-forge",
+            "antinomyhq/npm-forgecode"
+        ]
+    })
+}

crates/forge_ci/src/lib.rs

@@ -0,0 +1,4 @@
+mod jobs;
+mod release_matrix;
+pub mod steps;
+pub mod workflows;

crates/forge_ci/src/release_matrix.rs

@@ -0,0 +1,100 @@
+use serde::Serialize;
+use serde_json::Value;
+
+/// Matrix entry for build targets
+#[derive(Serialize, Clone)]
+pub struct MatrixEntry {
+    pub os: &'static str,
+    pub target: &'static str,
+    pub binary_name: &'static str,
+    pub binary_path: &'static str,
+    pub cross: &'static str,
+}
+
+#[derive(Clone)]
+pub struct ReleaseMatrix(Vec<MatrixEntry>);
+
+impl Default for ReleaseMatrix {
+    /// Returns a vector of all build matrix entries
+    fn default() -> Self {
+        ReleaseMatrix(vec![
+            MatrixEntry {
+                os: "ubuntu-latest",
+                target: "x86_64-unknown-linux-musl",
+                binary_name: "forge-x86_64-unknown-linux-musl",
+                binary_path: "target/x86_64-unknown-linux-musl/release/forge",
+                cross: "true",
+            },
+            MatrixEntry {
+                os: "ubuntu-latest",
+                target: "aarch64-unknown-linux-musl",
+                binary_name: "forge-aarch64-unknown-linux-musl",
+                binary_path: "target/aarch64-unknown-linux-musl/release/forge",
+                cross: "true",
+            },
+            MatrixEntry {
+                os: "ubuntu-latest",
+                target: "x86_64-unknown-linux-gnu",
+                binary_name: "forge-x86_64-unknown-linux-gnu",
+                binary_path: "target/x86_64-unknown-linux-gnu/release/forge",
+                cross: "false",
+            },
+            MatrixEntry {
+                os: "ubuntu-latest",
+                target: "aarch64-unknown-linux-gnu",
+                binary_name: "forge-aarch64-unknown-linux-gnu",
+                binary_path: "target/aarch64-unknown-linux-gnu/release/forge",
+                cross: "true",
+            },
+            MatrixEntry {
+                os: "macos-latest",
+                target: "x86_64-apple-darwin",
+                binary_name: "forge-x86_64-apple-darwin",
+                binary_path: "target/x86_64-apple-darwin/release/forge",
+                cross: "false",
+            },
+            MatrixEntry {
+                os: "macos-latest",
+                target: "aarch64-apple-darwin",
+                binary_name: "forge-aarch64-apple-darwin",
+                binary_path: "target/aarch64-apple-darwin/release/forge",
+                cross: "false",
+            },
+            MatrixEntry {
+                os: "windows-latest",
+                target: "x86_64-pc-windows-msvc",
+                binary_name: "forge-x86_64-pc-windows-msvc.exe",
+                binary_path: "target/x86_64-pc-windows-msvc/release/forge.exe",
+                cross: "false",
+            },
+            MatrixEntry {
+                os: "windows-latest",
+                target: "aarch64-pc-windows-msvc",
+                binary_name: "forge-aarch64-pc-windows-msvc.exe",
+                binary_path: "target/aarch64-pc-windows-msvc/release/forge.exe",
+                cross: "false",
+            },
+            MatrixEntry {
+                os: "ubuntu-latest",
+                target: "aarch64-linux-android",
+                binary_name: "forge-aarch64-linux-android",
+                binary_path: "target/aarch64-linux-android/release/forge",
+                cross: "true",
+            },
+        ])
+    }
+}
+
+impl ReleaseMatrix {
+    pub fn entries(&self) -> Vec<MatrixEntry> {
+        self.0.clone()
+    }
+}
+
+impl From<ReleaseMatrix> for Value {
+    fn from(value: ReleaseMatrix) -> Self {
+        serde_json::json!({
+            "include": value.entries()
+        })
+    }
+}

crates/forge_ci/src/steps/mod.rs

@@ -0,0 +1,3 @@
+mod setup_protoc;
+
+pub use setup_protoc::setup_protoc;

crates/forge_ci/src/steps/setup_protoc.rs

@@ -0,0 +1,11 @@
+use gh_workflow::*;
+
+/// Creates a step to setup the Protobuf compiler.
+///
+/// This step is reusable across all CI workflows that need protobuf
+/// compilation.
+pub fn setup_protoc() -> Step<Use> {
+    Step::new("Setup Protobuf Compiler")
+        .uses("arduino", "setup-protoc", "v3")
+        .with(("repo-token", "${{ secrets.GITHUB_TOKEN }}"))
+}

crates/forge_ci/src/workflows/autofix.rs

@@ -0,0 +1,57 @@
+use gh_workflow::generate::Generate;
+use gh_workflow::toolchain::Component;
+use gh_workflow::*;
+
+use crate::jobs;
+use crate::steps::setup_protoc;
+
+/// Generate the autofix workflow
+pub fn generate_autofix_workflow() {
+    let lint_fix_job = Job::new("Lint Fix")
+        .permissions(Permissions::default().contents(Level::Read))
+        .add_step(Step::new("Checkout Code").uses("actions", "checkout", "v6"))
+        .add_step(Step::new("Install SQLite").run("sudo apt-get install -y libsqlite3-dev"))
+        .add_step(setup_protoc())
+        .add_step(
+            Step::toolchain()
+                .add_nightly()
+                .add_component(Component::Clippy)
+                .add_component(Component::Rustfmt),
+        )
+        .add_step(Step::new("Cargo Fmt").run(jobs::fmt_cmd(true)))
+        .add_step(Step::new("Cargo Clippy").run(jobs::clippy_cmd(true)))
+        .add_step(
+            Step::new("Cargo Clippy String Safety").run(jobs::clippy_string_safety_cmd(false)),
+        )
+        .add_step(Step::new("Autofix").uses(
+            "autofix-ci",
+            "action",
+            "7a166d7532b277f34e16238930461bf77f9d7ed8",
+        ));
+
+    let events = Event::default()
+        .push(Push::default().add_branch("main"))
+        .pull_request(
+            PullRequest::default()
+                .add_type(PullRequestType::Opened)
+                .add_type(PullRequestType::Synchronize)
+                .add_type(PullRequestType::Reopened)
+                .add_branch("main"),
+        );
+
+    let workflow = Workflow::default()
+        .name("autofix.ci")
+        .add_env(RustFlags::deny("warnings"))
+        .on(events)
+        .concurrency(
+            Concurrency::default()
+                .group("autofix-${{github.ref}}")
+                .cancel_in_progress(false),
+        )
+        .add_job("lint", lint_fix_job);
+
+    Generate::new(workflow)
+        .name("autofix.yml")
+        .generate()
+        .unwrap();
+}

crates/forge_ci/src/workflows/bounty.rs

@@ -0,0 +1,47 @@
+use gh_workflow::generate::Generate;
+use gh_workflow::*;
+
+use crate::jobs::{sync_all_issues_job, sync_pr_job};
+
+/// Generate the bounty management workflow (v2).
+///
+/// Two jobs cover the full bounty lifecycle:
+/// - `sync-all-issues`: fetches all open issues with any bounty label and
+///   reconciles their label sets in one pass. Triggered on label/assignment
+///   events and daily on a schedule.
+/// - `sync-pr`: propagates bounty value labels from linked issues to the PR on
+///   open/edit, and applies the rewarded lifecycle on merge.
+pub fn generate_bounty_workflow() {
+    let events = Event::default()
+        .pull_request(
+            PullRequest::default()
+                .add_type(PullRequestType::Opened)
+                .add_type(PullRequestType::Edited)
+                .add_type(PullRequestType::Reopened),
+        )
+        .pull_request_target(PullRequestTarget::default().add_type(PullRequestType::Closed))
+        .issues(
+            Issues::default()
+                .add_type(IssuesType::Assigned)
+                .add_type(IssuesType::Unassigned)
+                .add_type(IssuesType::Labeled)
+                .add_type(IssuesType::Unlabeled),
+        )
+        .add_cron_schedule("0 2 * * *");
+
+    let workflow = Workflow::default()
+        .name("Bounty Management")
+        .on(events)
+        .permissions(
+            Permissions::default()
+                .issues(Level::Write)
+                .pull_requests(Level::Write),
+        )
+        .add_job("sync-all-issues", sync_all_issues_job())
+        .add_job("sync-pr", sync_pr_job());
+
+    Generate::new(workflow)
+        .name("bounty.yml")
+        .generate()
+        .unwrap();
+}

crates/forge_ci/src/workflows/ci.rs

@@ -0,0 +1,82 @@
+use gh_workflow::generate::Generate;
+use gh_workflow::*;
+
+use crate::jobs::{self, ReleaseBuilderJob};
+use crate::steps::setup_protoc;
+
+/// Generate the main CI workflow
+pub fn generate_ci_workflow() {
+    // Create a basic build job for CI with coverage
+    let build_job = Job::new("Build and Test")
+        .permissions(Permissions::default().contents(Level::Read))
+        .add_step(Step::new("Checkout Code").uses("actions", "checkout", "v6"))
+        .add_step(setup_protoc())
+        .add_step(Step::toolchain().add_stable())
+        .add_step(Step::new("Install cargo-llvm-cov").run("cargo install cargo-llvm-cov"))
+        .add_step(
+            Step::new("Generate coverage")
+                .run("cargo llvm-cov --all-features --workspace --lcov --output-path lcov.info"),
+        );
+
+    // Create a performance test job to ensure zsh rprompt stays fast
+    let perf_test_job = Job::new("zsh-rprompt-performance")
+        .name("Performance: zsh rprompt")
+        .permissions(Permissions::default().contents(Level::Read))
+        .add_step(Step::new("Checkout Code").uses("actions", "checkout", "v6"))
+        .add_step(setup_protoc())
+        .add_step(Step::toolchain().add_stable())
+        .add_step(
+            Step::new("Run performance benchmark")
+                .run("./scripts/benchmark.sh --threshold 60 zsh rprompt"),
+        );
+
+    let draft_release_job = jobs::create_draft_release_job("build");
+    let draft_release_pr_job = jobs::create_draft_release_pr_job();
+    let events = Event::default()
+        .push(Push::default().add_branch("main").add_tag("v*"))
+        .pull_request(
+            PullRequest::default()
+                .add_type(PullRequestType::Opened)
+                .add_type(PullRequestType::Synchronize)
+                .add_type(PullRequestType::Reopened)
+                .add_type(PullRequestType::Labeled)
+                .add_branch("main"),
+        );
+    let build_release_pr_job =
+        ReleaseBuilderJob::new("${{ needs.draft_release_pr.outputs.crate_release_name }}")
+            .into_job()
+            .add_needs("draft_release_pr")
+            .cond(Expression::new(
+                [
+                    "github.event_name == 'pull_request'",
+                    "contains(github.event.pull_request.labels.*.name, 'ci: build all targets')",
+                ]
+                .join(" && "),
+            ));
+    let build_release_job =
+        ReleaseBuilderJob::new("${{ needs.draft_release.outputs.crate_release_name }}")
+            .release_id("${{ needs.draft_release.outputs.crate_release_id }}")
+            .into_job()
+            .add_needs("draft_release")
+            .cond(Expression::new(
+                [
+                    "github.event_name == 'push'",
+                    "github.ref == 'refs/heads/main'",
+                ]
+                .join(" && "),
+            ));
+    let workflow = Workflow::default()
+        .name("ci")
+        .add_env(RustFlags::deny("warnings"))
+        .on(events)
+        .concurrency(Concurrency::default().group("${{ github.workflow }}-${{ github.ref }}"))
+        .add_env(("OPENROUTER_API_KEY", "${{secrets.OPENROUTER_API_KEY}}"))
+        .add_job("build", build_job)
+        .add_job("zsh_rprompt_perf", perf_test_job)
+        .add_job("draft_release", draft_release_job)
+        .add_job("draft_release_pr", draft_release_pr_job)
+        .add_job("build_release", build_release_job)
+        .add_job("build_release_pr", build_release_pr_job);
+
+    Generate::new(workflow).name("ci.yml").generate().unwrap();
+}

crates/forge_ci/src/workflows/labels.rs

@@ -0,0 +1,21 @@
+use gh_workflow::generate::Generate;
+use gh_workflow::*;
+
+use crate::jobs::label_sync_job;
+
+/// Generate labels workflow
+pub fn generate_labels_workflow() {
+    let labels_workflow = Workflow::default()
+        .name("Github Label Sync")
+        .on(Event {
+            push: Some(Push { branches: vec!["main".to_string()], ..Push::default() }),
+            ..Event::default()
+        })
+        .permissions(Permissions::default().contents(Level::Write))
+        .add_job("label-sync", label_sync_job());
+
+    Generate::new(labels_workflow)
+        .name("labels.yml")
+        .generate()
+        .unwrap();
+}

crates/forge_ci/src/workflows/mod.rs

@@ -0,0 +1,17 @@
+//! Workflow definitions for CI/CD
+
+mod autofix;
+mod bounty;
+mod ci;
+mod labels;
+mod release_drafter;
+mod release_publish;
+mod stale;
+
+pub use autofix::*;
+pub use bounty::*;
+pub use ci::*;
+pub use labels::*;
+pub use release_drafter::*;
+pub use release_publish::*;
+pub use stale::*;

crates/forge_ci/src/workflows/release_drafter.rs

@@ -0,0 +1,36 @@
+use gh_workflow::generate::Generate;
+use gh_workflow::*;
+
+use crate::jobs::draft_release_update_job;
+
+/// Generate release drafter workflow
+pub fn generate_release_drafter_workflow() {
+    let release_drafter = Workflow::default()
+        .name("Release Drafter")
+        .on(Event {
+            push: Some(Push { branches: vec!["main".to_string()], ..Push::default() }),
+            pull_request_target: Some(PullRequestTarget {
+                types: vec![
+                    PullRequestType::Opened,
+                    PullRequestType::Reopened,
+                    PullRequestType::Synchronize,
+                    PullRequestType::Labeled,
+                    PullRequestType::Unlabeled,
+                    PullRequestType::Closed,
+                ],
+                branches: vec!["main".to_string()],
+            }),
+            ..Event::default()
+        })
+        .permissions(
+            Permissions::default()
+                .contents(Level::Write)
+                .pull_requests(Level::Write),
+        )
+        .add_job("update_release_draft", draft_release_update_job());
+
+    Generate::new(release_drafter)
+        .name("release-drafter.yml")
+        .generate()
+        .unwrap();
+}

crates/forge_ci/src/workflows/release_publish.rs

@@ -0,0 +1,32 @@
+use gh_workflow::generate::Generate;
+use gh_workflow::*;
+
+use crate::jobs::{ReleaseBuilderJob, release_homebrew_job, release_npm_job};
+
+/// Generate npm release workflow
+pub fn release_publish() {
+    let release_build_job = ReleaseBuilderJob::new("${{ github.event.release.tag_name }}")
+        .release_id("${{ github.event.release.id }}");
+    let npm_release_job = release_npm_job().add_needs("build_release");
+    let homebrew_release_job = release_homebrew_job().add_needs("build_release");
+
+    let npm_workflow = Workflow::default()
+        .name("Multi Channel Release")
+        .on(Event {
+            release: Some(Release { types: vec![ReleaseType::Published] }),
+            ..Event::default()
+        })
+        .permissions(
+            Permissions::default()
+                .contents(Level::Write)
+                .pull_requests(Level::Write),
+        )
+        .add_job("build_release", release_build_job.into_job())
+        .add_job("npm_release", npm_release_job)
+        .add_job("homebrew_release", homebrew_release_job);
+
+    Generate::new(npm_workflow)
+        .name("release.yml")
+        .generate()
+        .unwrap();
+}

crates/forge_ci/src/workflows/stale.rs

@@ -0,0 +1,48 @@
+use gh_workflow::generate::Generate;
+use gh_workflow::*;
+use indexmap::indexmap;
+use serde_json::json;
+
+/// Generate the stale issues and PRs workflow
+pub fn generate_stale_workflow() {
+    let workflow = Workflow::default()
+        .name("Close Stale Issues and PR")
+        .on(Event::default().add_schedule(Schedule::new("0 * * * *")))
+        .permissions(
+            Permissions::default()
+                .issues(Level::Write)
+                .pull_requests(Level::Write),
+        )
+        .env(Env::from(indexmap! {
+            "DAYS_BEFORE_ISSUE_STALE".to_string() => json!("30"),
+            "DAYS_BEFORE_ISSUE_CLOSE".to_string() => json!("7"),
+            "DAYS_BEFORE_PR_STALE".to_string() => json!("5"),
+            "DAYS_BEFORE_PR_CLOSE".to_string() => json!("10"),
+        }))
+        .add_job(
+            "stale",
+            Job::new("Stale Issues")
+                .add_step(
+                    Step::new("Mark Stale Issues").uses("actions", "stale", "v10")
+                        .with(Input::from(indexmap! {
+                            "stale-issue-label".to_string() => json!("state: inactive"),
+                            "stale-pr-label".to_string() => json!("state: inactive"),
+                            "stale-issue-message".to_string() => json!(r#"**Action required:** Issue inactive for ${{ env.DAYS_BEFORE_ISSUE_STALE }} days.
+Status update or closure in ${{ env.DAYS_BEFORE_ISSUE_CLOSE }} days."#),
+                            "close-issue-message".to_string() => json!("Issue closed after ${{ env.DAYS_BEFORE_ISSUE_CLOSE }} days of inactivity."),
+                            "stale-pr-message".to_string() => json!(r#"**Action required:** PR inactive for ${{ env.DAYS_BEFORE_PR_STALE }} days.
+Status update or closure in ${{ env.DAYS_BEFORE_PR_CLOSE }} days."#),
+                            "close-pr-message".to_string() => json!("PR closed after ${{ env.DAYS_BEFORE_PR_CLOSE }} days of inactivity."),
+                            "days-before-issue-stale".to_string() => json!("${{ env.DAYS_BEFORE_ISSUE_STALE }}"),
+                            "days-before-issue-close".to_string() => json!("${{ env.DAYS_BEFORE_ISSUE_CLOSE }}"),
+                            "days-before-pr-stale".to_string() => json!("${{ env.DAYS_BEFORE_PR_STALE }}"),
+                            "days-before-pr-close".to_string() => json!("${{ env.DAYS_BEFORE_PR_CLOSE }}"),
+                        })),
+                ),
+        );
+
+    Generate::new(workflow)
+        .name("stale.yml")
+        .generate()
+        .unwrap();
+}

crates/forge_ci/tests/ci.rs

@@ -0,0 +1,36 @@
+use forge_ci::workflows as workflow;
+
+#[test]
+fn generate() {
+    workflow::generate_ci_workflow();
+}
+
+#[test]
+fn test_release_drafter() {
+    workflow::generate_release_drafter_workflow();
+}
+
+#[test]
+fn test_release_workflow() {
+    workflow::release_publish();
+}
+
+#[test]
+fn test_labels_workflow() {
+    workflow::generate_labels_workflow();
+}
+
+#[test]
+fn test_stale_workflow() {
+    workflow::generate_stale_workflow();
+}
+
+#[test]
+fn test_autofix_workflow() {
+    workflow::generate_autofix_workflow();
+}
+
+#[test]
+fn test_bounty_workflow() {
+    workflow::generate_bounty_workflow();
+}

crates/forge_config/src/auto_dump.rs

@@ -0,0 +1,25 @@
+use schemars::JsonSchema;
+use serde::{Deserialize, Serialize};
+
+/// The output format used when auto-dumping a conversation on task completion.
+#[derive(Debug, Clone, PartialEq, Serialize, Deserialize, JsonSchema, fake::Dummy)]
+#[serde(rename_all = "snake_case")]
+pub enum AutoDumpFormat {
+    /// Dump as a JSON file
+    Json,
+    /// Dump as an HTML file
+    Html,
+}
+
+#[cfg(test)]
+mod tests {
+    use pretty_assertions::assert_eq;
+
+    use super::*;
+
+    #[test]
+    fn test_auto_dump_format_variants() {
+        assert_eq!(AutoDumpFormat::Json, AutoDumpFormat::Json);
+        assert_eq!(AutoDumpFormat::Html, AutoDumpFormat::Html);
+    }
+}

crates/forge_config/src/compact.rs

@@ -0,0 +1,266 @@
+use std::time::Duration;
+
+use derive_setters::Setters;
+use fake::Dummy;
+use schemars::JsonSchema;
+use serde::{Deserialize, Serialize};
+
+use crate::Percentage;
+
+/// Frequency at which forge checks for updates
+#[derive(Default, Debug, Clone, Serialize, Deserialize, JsonSchema, PartialEq, fake::Dummy)]
+#[serde(rename_all = "snake_case")]
+pub enum UpdateFrequency {
+    Daily,
+    Weekly,
+    Never,
+    #[default]
+    Always,
+}
+
+impl From<UpdateFrequency> for Duration {
+    fn from(val: UpdateFrequency) -> Self {
+        match val {
+            UpdateFrequency::Daily => Duration::from_secs(60 * 60 * 24),
+            UpdateFrequency::Weekly => Duration::from_secs(60 * 60 * 24 * 7),
+            UpdateFrequency::Never => Duration::MAX,
+            UpdateFrequency::Always => Duration::ZERO,
+        }
+    }
+}
+
+/// Configuration for automatic forge updates
+#[derive(
+    Debug, Clone, Serialize, Deserialize, Default, JsonSchema, Setters, PartialEq, fake::Dummy,
+)]
+#[setters(strip_option, into)]
+pub struct Update {
+    /// How frequently forge checks for updates: daily, weekly, always, or never
+    pub frequency: Option<UpdateFrequency>,
+    /// Whether to automatically install updates without prompting
+    pub auto_update: Option<bool>,
+}
+
+/// Configuration for automatic context compaction for all agents
+#[derive(Debug, Clone, Serialize, Deserialize, Setters, JsonSchema, PartialEq)]
+#[setters(strip_option, into)]
+pub struct Compact {
+    /// Number of most recent messages to preserve during compaction.
+    /// These messages won't be considered for summarization. Works alongside
+    /// eviction_window - the more conservative limit (fewer messages to
+    /// compact) takes precedence.
+    #[serde(default)]
+    pub retention_window: usize,
+
+    /// Maximum percentage of the context that can be summarized during
+    /// compaction. Valid values are between 0.0 and 1.0, where 0.0 means no
+    /// compaction and 1.0 allows summarizing all messages. Works alongside
+    /// retention_window - the more conservative limit (fewer messages to
+    /// compact) takes precedence.
+    #[serde(default)]
+    pub eviction_window: Percentage,
+
+    /// Maximum number of tokens to keep after compaction
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub max_tokens: Option<usize>,
+
+    /// Maximum number of tokens before triggering compaction. This acts as an
+    /// absolute cap and is combined with
+    /// `token_threshold_percentage` by taking the lower value.
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub token_threshold: Option<usize>,
+
+    /// Maximum percentage of the model context window used to derive the token
+    /// threshold before triggering compaction. This is combined with
+    /// `token_threshold` by taking the lower value.
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub token_threshold_percentage: Option<Percentage>,
+
+    /// Maximum number of conversation turns before triggering compaction
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub turn_threshold: Option<usize>,
+
+    /// Maximum number of messages before triggering compaction
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub message_threshold: Option<usize>,
+
+    /// Model ID to use for compaction, useful when compacting with a
+    /// cheaper/faster model. If not specified, the root level model will be
+    /// used.
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub model: Option<String>,
+
+    /// Whether to trigger compaction when the last message is from a user
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub on_turn_end: Option<bool>,
+}
+
+impl Default for Compact {
+    fn default() -> Self {
+        Self::new()
+    }
+}
+
+impl Compact {
+    /// Creates a new compaction configuration with all optional fields unset
+    pub fn new() -> Self {
+        Self {
+            max_tokens: None,
+            token_threshold: None,
+            token_threshold_percentage: None,
+            turn_threshold: None,
+            message_threshold: None,
+            model: None,
+            eviction_window: Percentage::new(0.2).unwrap(),
+            retention_window: 0,
+            on_turn_end: None,
+        }
+    }
+}
+
+impl Dummy<fake::Faker> for Compact {
+    fn dummy_with_rng<R: fake::RngExt + ?Sized>(_: &fake::Faker, rng: &mut R) -> Self {
+        use fake::Fake;
+        Self {
+            retention_window: fake::Faker.fake_with_rng(rng),
+            eviction_window: Percentage::from((0.0f64..=1.0f64).fake_with_rng::<f64, R>(rng)),
+            max_tokens: fake::Faker.fake_with_rng(rng),
+            token_threshold: fake::Faker.fake_with_rng(rng),
+            token_threshold_percentage: fake::Faker.fake_with_rng(rng),
+            turn_threshold: fake::Faker.fake_with_rng(rng),
+            message_threshold: fake::Faker.fake_with_rng(rng),
+            model: fake::Faker.fake_with_rng(rng),
+            on_turn_end: fake::Faker.fake_with_rng(rng),
+        }
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use pretty_assertions::assert_eq;
+
+    use super::*;
+    use crate::ForgeConfig;
+    use crate::reader::ConfigReader;
+
+    #[test]
+    fn test_f64_eviction_window_round_trip() {
+        let fixture = Compact {
+            eviction_window: Percentage::new(0.2).unwrap(),
+            ..Compact::new()
+        };
+
+        let toml = toml_edit::ser::to_string_pretty(&fixture).unwrap();
+
+        assert!(
+            toml.contains("eviction_window = 0.2\n"),
+            "expected `eviction_window = 0.2` in TOML output, got:\n{toml}"
+        );
+    }
+
+    #[test]
+    fn test_f64_eviction_window_deserialize_round_trip() {
+        let fixture = Compact {
+            eviction_window: Percentage::new(0.2).unwrap(),
+            ..Compact::new()
+        };
+        let config_fixture = ForgeConfig::default().compact(fixture.clone());
+
+        let toml = toml_edit::ser::to_string_pretty(&config_fixture).unwrap();
+
+        let actual = ConfigReader::default()
+            .read_defaults()
+            .read_toml(&toml)
+            .build()
+            .unwrap();
+        let actual = actual.compact.expect("compact config should deserialize");
+
+        assert_eq!(actual.eviction_window, fixture.eviction_window);
+    }
+
+    #[test]
+    fn test_token_threshold_percentage_round_trip() {
+        let fixture = Compact {
+            token_threshold_percentage: Some(Percentage::new(0.7).unwrap()),
+            ..Compact::new()
+        };
+        let config_fixture = ForgeConfig::default().compact(fixture.clone());
+
+        let toml = toml_edit::ser::to_string_pretty(&config_fixture).unwrap();
+
+        assert!(
+            toml.contains("token_threshold_percentage = 0.7\n"),
+            "expected `token_threshold_percentage = 0.7` in TOML output, got:\n{toml}"
+        );
+
+        let actual = ConfigReader::default()
+            .read_defaults()
+            .read_toml(&toml)
+            .build()
+            .unwrap();
+        let actual = actual.compact.expect("compact config should deserialize");
+
+        assert_eq!(
+            actual.token_threshold_percentage,
+            fixture.token_threshold_percentage
+        );
+    }
+
+    #[test]
+    fn test_token_threshold_percentage_rejects_out_of_range() {
+        let toml = "[compact]\ntoken_threshold_percentage = 1.5\n";
+
+        let result = ConfigReader::default()
+            .read_defaults()
+            .read_toml(toml)
+            .build();
+
+        assert!(
+            result.is_err(),
+            "expected error for token_threshold_percentage = 1.5, got: {:?}",
+            result.ok()
+        );
+    }
+
+    #[test]
+    fn test_eviction_window_rejects_out_of_range() {
+        let toml = "[compact]\neviction_window = 1.5\n";
+
+        let result = ConfigReader::default()
+            .read_defaults()
+            .read_toml(toml)
+            .build();
+
+        assert!(
+            result.is_err(),
+            "expected error for eviction_window = 1.5, got: {:?}",
+            result.ok()
+        );
+    }
+
+    #[test]
+    fn test_update_frequency_never_round_trip() {
+        let fixture =
+            ForgeConfig::default().updates(Update::default().frequency(UpdateFrequency::Never));
+
+        let toml = toml_edit::ser::to_string_pretty(&fixture).unwrap();
+
+        assert!(
+            toml.contains("frequency = \"never\"\n"),
+            "expected `frequency = \"never\"` in TOML output, got:\n{toml}"
+        );
+
+        let actual = ConfigReader::default()
+            .read_defaults()
+            .read_toml(&toml)
+            .build()
+            .unwrap();
+
+        let expected = Some(
+            Update::default()
+                .frequency(UpdateFrequency::Never)
+                .auto_update(true),
+        );
+        assert_eq!(actual.updates, expected);
+    }
+}

crates/forge_config/src/config.rs

@@ -0,0 +1,516 @@
+use std::collections::HashMap;
+use std::path::PathBuf;
+
+use derive_setters::Setters;
+use fake::Dummy;
+use schemars::JsonSchema;
+use serde::{Deserialize, Serialize};
+
+use crate::reader::ConfigReader;
+use crate::writer::ConfigWriter;
+use crate::{
+    AutoDumpFormat, Compact, Decimal, HttpConfig, ModelConfig, ReasoningConfig, RetryConfig, Update,
+};
+
+/// Wire protocol a provider uses for chat completions.
+#[derive(Debug, Clone, PartialEq, Serialize, Deserialize, JsonSchema, Dummy)]
+pub enum ProviderResponseType {
+    OpenAI,
+    OpenAIResponses,
+    Anthropic,
+    Bedrock,
+    Google,
+    OpenCode,
+}
+
+/// Category of a provider.
+#[derive(Debug, Clone, PartialEq, Default, Serialize, Deserialize, JsonSchema, Dummy)]
+#[serde(rename_all = "snake_case")]
+pub enum ProviderTypeEntry {
+    /// LLM provider for chat completions.
+    #[default]
+    Llm,
+    /// Context engine provider for code indexing and search.
+    ContextEngine,
+}
+
+/// Authentication method supported by a provider.
+///
+/// Only the simple (non-OAuth) methods are available here; providers that
+/// require OAuth device or authorization-code flows must be configured via the
+/// file-based `provider.json` override instead.
+#[derive(Debug, Clone, PartialEq, Serialize, Deserialize, JsonSchema, Dummy)]
+#[serde(rename_all = "snake_case")]
+pub enum ProviderAuthMethod {
+    ApiKey,
+    GoogleAdc,
+}
+
+/// A URL parameter variable for a provider, used to substitute template
+/// variables in URL strings.
+#[derive(Debug, Clone, PartialEq, Serialize, Deserialize, JsonSchema, Dummy)]
+#[serde(rename_all = "snake_case")]
+pub struct ProviderUrlParam {
+    /// The environment variable name used as the template variable key.
+    pub name: String,
+    /// Optional preset values for this parameter shown as suggestions in the
+    /// UI.
+    #[serde(default, skip_serializing_if = "Vec::is_empty")]
+    pub options: Vec<String>,
+    /// Whether this parameter is optional. When `true`, the parameter may be
+    /// left blank without causing an error.
+    #[serde(default, skip_serializing_if = "std::ops::Not::not")]
+    pub optional: bool,
+}
+
+/// Source of models for a provider: either a URL to fetch them from or a
+/// static list defined inline.
+#[derive(Debug, Clone, PartialEq, Serialize, Deserialize, JsonSchema, Dummy)]
+#[serde(untagged)]
+pub enum ModelListConfig {
+    /// URL template used to fetch the model list dynamically.
+    Url(String),
+    /// A static list of models defined directly in the configuration.
+    Hardcoded(Vec<forge_domain::Model>),
+}
+
+/// A single provider entry defined inline in `forge.toml`.
+///
+/// Inline providers are merged with the built-in provider list; entries with
+/// the same `id` override the corresponding built-in entry field-by-field,
+/// while entries with a new `id` are appended to the list.
+#[derive(Debug, Default, Clone, PartialEq, Serialize, Deserialize, JsonSchema, Dummy)]
+#[serde(rename_all = "snake_case")]
+pub struct ProviderEntry {
+    /// Unique provider identifier used in model paths (e.g. `"my_provider"`).
+    pub id: String,
+    /// Environment variable holding the API key for this provider.
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub api_key_var: Option<String>,
+    /// URL template for chat completions; may contain `{{VAR}}` placeholders
+    /// that are substituted from the credential's url params.
+    pub url: String,
+    /// Model source: either a URL template for dynamic discovery or a static
+    /// list of models defined inline.
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub models: Option<ModelListConfig>,
+    /// Wire protocol used by this provider.
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub response_type: Option<ProviderResponseType>,
+    /// Environment variables whose values are substituted into `{{VAR}}`
+    /// placeholders in the `url` and `models` templates.
+    #[serde(default, skip_serializing_if = "Vec::is_empty")]
+    pub url_param_vars: Vec<ProviderUrlParam>,
+    /// Additional HTTP headers sent with every request to this provider.
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub custom_headers: Option<HashMap<String, String>>,
+    /// Provider category; defaults to `llm` when omitted.
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub provider_type: Option<ProviderTypeEntry>,
+    /// Authentication methods supported by this provider; defaults to
+    /// `["api_key"]` when omitted.
+    #[serde(default, skip_serializing_if = "Vec::is_empty")]
+    pub auth_methods: Vec<ProviderAuthMethod>,
+}
+
+/// Top-level Forge configuration merged from all sources (defaults, file,
+/// environment).
+#[derive(Default, Debug, Setters, Clone, PartialEq, Serialize, Deserialize, JsonSchema, Dummy)]
+#[serde(rename_all = "snake_case")]
+#[setters(strip_option)]
+pub struct ForgeConfig {
+    /// Retry settings applied at the system level to all IO operations.
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub retry: Option<RetryConfig>,
+    /// Maximum number of lines returned by a single file search operation.
+    #[serde(default)]
+    pub max_search_lines: usize,
+    /// Maximum number of bytes returned by a single file search operation.
+    #[serde(default)]
+    pub max_search_result_bytes: usize,
+    /// Maximum number of characters returned from a URL fetch.
+    #[serde(default)]
+    pub max_fetch_chars: usize,
+    /// Maximum number of lines captured from the leading portion of shell
+    /// command output.
+    #[serde(default)]
+    pub max_stdout_prefix_lines: usize,
+    /// Maximum number of lines captured from the trailing portion of shell
+    /// command output.
+    #[serde(default)]
+    pub max_stdout_suffix_lines: usize,
+    /// Maximum number of characters per line in shell command output.
+    #[serde(default)]
+    pub max_stdout_line_chars: usize,
+    /// Maximum number of characters per line when reading a file.
+    #[serde(default)]
+    pub max_line_chars: usize,
+    /// Maximum number of lines read from a file in a single operation.
+    #[serde(default)]
+    pub max_read_lines: u64,
+    /// Maximum number of files read in a single batch operation.
+    #[serde(default)]
+    pub max_file_read_batch_size: usize,
+    /// HTTP client settings including proxy, TLS, and timeout configuration.
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub http: Option<HttpConfig>,
+    /// Maximum file size in bytes permitted for read operations.
+    #[serde(default)]
+    pub max_file_size_bytes: u64,
+    /// Maximum image file size in bytes permitted for read operations.
+    #[serde(default)]
+    pub max_image_size_bytes: u64,
+    /// Maximum time in seconds a single tool call may run before being
+    /// cancelled.
+    #[serde(default)]
+    pub tool_timeout_secs: u64,
+    /// Whether to automatically open HTML dump files in the browser after
+    /// creation.
+    #[serde(default)]
+    pub auto_open_dump: bool,
+    /// Directory where debug request files are written; disabled when absent.
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub debug_requests: Option<PathBuf>,
+    /// Path to the conversation history file; defaults to the global history
+    /// location when absent.
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub custom_history_path: Option<PathBuf>,
+    /// Maximum number of conversations shown in the conversation list.
+    #[serde(default)]
+    pub max_conversations: usize,
+    /// Maximum number of candidate results returned from the initial semantic
+    /// search vector query.
+    #[serde(default)]
+    pub max_sem_search_results: usize,
+    /// Number of top results retained after re-ranking in semantic search.
+    #[serde(default)]
+    pub sem_search_top_k: usize,
+    /// Base URL of the Forge services API used for semantic search and
+    /// indexing.
+    #[serde(default)]
+    #[dummy(expr = "\"https://api.forgecode.dev/api\".to_string()")]
+    pub services_url: String,
+    /// Maximum number of file extensions included in the agent system prompt.
+    #[serde(default)]
+    pub max_extensions: usize,
+    /// Format used when automatically creating a session dump after task
+    /// completion; disabled when absent.
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub auto_dump: Option<AutoDumpFormat>,
+    /// Maximum number of files read concurrently during batch operations.
+    #[serde(default)]
+    pub max_parallel_file_reads: usize,
+    /// Time-to-live in seconds for the cached model API list.
+    #[serde(default)]
+    pub model_cache_ttl_secs: u64,
+    /// Default model and provider configuration used when not overridden by
+    /// individual agents.    
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub session: Option<ModelConfig>,
+    /// Model and provider configuration used for commit message generation.
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub commit: Option<ModelConfig>,
+    /// Whether `forge commit` should override `GIT_COMMITTER_NAME` and
+    /// `GIT_COMMITTER_EMAIL` with the Forge identity. Defaults to `true` via
+    /// the embedded `.forge.toml` defaults.
+    #[serde(default)]
+    pub use_forge_committer: bool,
+    /// Maximum number of recent commits included as context for commit message
+    /// generation.
+    #[serde(default)]
+    pub max_commit_count: usize,
+    /// Model and provider configuration used for shell command suggestion
+    /// generation.
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub suggest: Option<ModelConfig>,
+
+    // --- Workflow fields ---
+    /// Configuration for automatic Forge updates.
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub updates: Option<Update>,
+
+    /// Output randomness for all agents; lower values are deterministic, higher
+    /// values are creative (0.0–2.0).
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub temperature: Option<Decimal>,
+
+    /// Nucleus sampling threshold for all agents; limits token selection to the
+    /// top cumulative probability mass (0.0–1.0).
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub top_p: Option<Decimal>,
+
+    /// Top-k vocabulary cutoff for all agents; restricts sampling to the k
+    /// highest-probability tokens (1–1000).
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub top_k: Option<u32>,
+
+    /// Maximum tokens the model may generate per response for all agents
+    /// (1–100,000).
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub max_tokens: Option<u32>,
+
+    /// Maximum tool failures per turn before the orchestrator forces
+    /// completion.
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub max_tool_failure_per_turn: Option<usize>,
+
+    /// Maximum number of requests that can be made in a single turn.
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub max_requests_per_turn: Option<usize>,
+
+    /// Context compaction settings applied to all agents; falls back to each
+    /// agent's individual setting when absent.
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub compact: Option<Compact>,
+
+    /// Whether restricted mode is active; when enabled, tool execution requires
+    /// explicit permission grants.
+    #[serde(default)]
+    pub restricted: bool,
+
+    /// Whether tool use is supported in the current environment; when false,
+    /// all tool calls are disabled.
+    #[serde(default)]
+    pub tool_supported: bool,
+
+    /// Reasoning configuration applied to all agents; controls effort level,
+    /// token budget, and visibility of the model's thinking process.
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub reasoning: Option<ReasoningConfig>,
+
+    /// Additional provider definitions merged with the built-in provider list.
+    ///
+    /// Entries with an `id` matching a built-in provider override its fields;
+    /// entries with a new `id` are appended and become available for model
+    /// selection.
+    #[serde(default, skip_serializing_if = "Vec::is_empty")]
+    pub providers: Vec<ProviderEntry>,
+
+    /// Currency symbol displayed in the shell rprompt next to the session cost
+    /// (e.g. `"$"`, `"€"`, `"₹"`). Defaults to `"$"`.
+    #[serde(default)]
+    pub currency_symbol: String,
+
+    /// Conversion rate applied to costs before display in the shell rprompt.
+    /// The raw USD cost is multiplied by this value, allowing costs to be shown
+    /// in a local currency. Defaults to `1.0` (no conversion).
+    #[serde(default)]
+    pub currency_conversion_rate: Decimal,
+
+    /// Enables the pending todos hook that checks for incomplete todo items
+    /// when a task ends and reminds the LLM about them.
+    #[serde(default)]
+    pub verify_todos: bool,
+
+    /// Switches patch replacement fallback from the legacy fuzzy-search range
+    /// lookup to the newer text-patch gRPC API.
+    /// Defaults to `false` so patching continues to use the legacy fallback
+    /// behavior unless explicitly enabled in `forge.toml`.
+    #[serde(default)]
+    pub use_text_patch_fallback: bool,
+
+    /// Whether the deep research agent is available.
+    ///
+    /// When set to `true`, the Sage agent is added to the agent list and
+    /// the `:sage` app command is enabled. Defaults to `false`.
+    #[serde(default)]
+    pub research_subagent: bool,
+
+    /// Enables subagent support via the task tool; when true the forge agent
+    /// gains access to the `task` tool for delegating work to specialised
+    /// sub-agents, and the `sage` research-only agent tool is removed.
+    /// When false the `task` tool is disabled and `sage` is available instead.
+    #[serde(default)]
+    pub subagents: bool,
+
+    /// Enables automatic VS Code extension installation when Forge runs inside
+    /// VS Code and the extension is not already installed.
+    #[serde(default)]
+    pub auto_install_vscode_extension: bool,
+
+    /// When `true`, all system messages in the conversation are merged into a
+    /// single leading system message before the request is sent. Enable this
+    /// for providers that reject requests containing system messages after
+    /// user or assistant turns (e.g. vLLM, NVIDIA NIM).
+    #[serde(default)]
+    pub merge_system_messages: bool,
+}
+
+impl ForgeConfig {
+    /// Reads and merges configuration from all sources, returning the resolved
+    /// [`ForgeConfig`].
+    ///
+    /// # Errors
+    ///
+    /// Returns an error if the config path cannot be resolved, the file cannot
+    /// be read, or deserialization fails.
+    pub fn read() -> crate::Result<ForgeConfig> {
+        ConfigReader::default()
+            .read_legacy()
+            .read_defaults()
+            .read_global()
+            .read_env()
+            .build()
+    }
+
+    /// Writes the configuration to the user config file.
+    ///
+    /// # Errors
+    ///
+    /// Returns an error if the configuration cannot be serialized or written to
+    /// disk.
+    pub fn write(&self) -> crate::Result<()> {
+        let path = ConfigReader::config_path();
+        ConfigWriter::new(self.clone()).write(&path)
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use pretty_assertions::assert_eq;
+
+    use super::*;
+    use crate::reader::ConfigReader;
+
+    #[test]
+    fn test_f32_temperature_round_trip() {
+        let fixture = ForgeConfig { temperature: Some(Decimal(0.1)), ..Default::default() };
+
+        let toml = toml_edit::ser::to_string_pretty(&fixture).unwrap();
+
+        assert!(
+            toml.contains("temperature = 0.1\n"),
+            "expected `temperature = 0.1` in TOML output, got:\n{toml}"
+        );
+    }
+
+    #[test]
+    fn test_f32_top_p_round_trip() {
+        let fixture = ForgeConfig { top_p: Some(Decimal(0.9)), ..Default::default() };
+
+        let toml = toml_edit::ser::to_string_pretty(&fixture).unwrap();
+
+        assert!(
+            toml.contains("top_p = 0.9\n"),
+            "expected `top_p = 0.9` in TOML output, got:\n{toml}"
+        );
+    }
+
+    #[test]
+    fn test_f32_temperature_deserialize_round_trip() {
+        let fixture = ForgeConfig { temperature: Some(Decimal(0.1)), ..Default::default() };
+
+        let toml = toml_edit::ser::to_string_pretty(&fixture).unwrap();
+
+        let actual = ConfigReader::default().read_toml(&toml).build().unwrap();
+
+        assert_eq!(actual.temperature, fixture.temperature);
+    }
+
+    #[test]
+    fn test_provider_static_model_list_deserialization() {
+        let fixture = r#"
+[[providers]]
+id = "ollama"
+url = "http://127.0.0.1:8000/v1/chat/completions"
+response_type = "OpenAI"
+auth_methods = ["api_key"]
+
+[[providers.models]]
+id = "Qwen3.6-35B-A3b-q3-mlx"
+name = "Qwen3.5-35B"
+description = "Qwen local reasoning model with advanced problem-solving capabilities"
+context_length = 262144
+tools_supported = true
+supports_parallel_tool_calls = true
+supports_reasoning = true
+input_modalities = ["text"]
+
+[[providers.models]]
+id = "llama3.2-3b"
+name = "Llama 3.2 3B"
+description = "Meta Llama 3.2 3B lightweight local model"
+context_length = 131072
+tools_supported = true
+supports_parallel_tool_calls = false
+supports_reasoning = false
+input_modalities = ["text"]
+"#;
+
+        let actual = ConfigReader::default().read_toml(fixture).build().unwrap();
+
+        let expected = vec![ProviderEntry {
+            id: "ollama".to_string(),
+            url: "http://127.0.0.1:8000/v1/chat/completions".to_string(),
+            response_type: Some(ProviderResponseType::OpenAI),
+            auth_methods: vec![ProviderAuthMethod::ApiKey],
+            models: Some(ModelListConfig::Hardcoded(vec![
+                forge_domain::Model::new("Qwen3.6-35B-A3b-q3-mlx")
+                    .name("Qwen3.5-35B".to_string())
+                    .description(
+                        "Qwen local reasoning model with advanced problem-solving capabilities"
+                            .to_string(),
+                    )
+                    .context_length(262144)
+                    .tools_supported(true)
+                    .supports_parallel_tool_calls(true)
+                    .supports_reasoning(true)
+                    .input_modalities(vec![forge_domain::InputModality::Text]),
+                forge_domain::Model::new("llama3.2-3b")
+                    .name("Llama 3.2 3B".to_string())
+                    .description("Meta Llama 3.2 3B lightweight local model".to_string())
+                    .context_length(131072)
+                    .tools_supported(true)
+                    .supports_parallel_tool_calls(false)
+                    .supports_reasoning(false)
+                    .input_modalities(vec![forge_domain::InputModality::Text]),
+            ])),
+            ..Default::default()
+        }];
+
+        assert_eq!(actual.providers, expected);
+    }
+
+    #[test]
+    fn test_provider_url_model_list_deserialization() {
+        let fixture = r#"
+[[providers]]
+id = "my_provider"
+url = "http://example.com/v1/chat/completions"
+models = "http://example.com/v1/models"
+"#;
+
+        let actual = ConfigReader::default().read_toml(fixture).build().unwrap();
+
+        let expected = vec![ProviderEntry {
+            id: "my_provider".to_string(),
+            url: "http://example.com/v1/chat/completions".to_string(),
+            models: Some(ModelListConfig::Url(
+                "http://example.com/v1/models".to_string(),
+            )),
+            ..Default::default()
+        }];
+
+        assert_eq!(actual.providers, expected);
+    }
+
+    #[test]
+    fn test_auto_install_vscode_extension_defaults_to_true() {
+        let actual = ConfigReader::default().read_defaults().build().unwrap();
+
+        assert_eq!(actual.auto_install_vscode_extension, true);
+    }
+
+    #[test]
+    fn test_auto_install_vscode_extension_can_be_disabled() {
+        let toml = "auto_install_vscode_extension = false\n";
+
+        let actual = ConfigReader::default()
+            .read_defaults()
+            .read_toml(toml)
+            .build()
+            .unwrap();
+
+        assert_eq!(actual.auto_install_vscode_extension, false);
+    }
+}

crates/forge_config/src/decimal.rs

@@ -0,0 +1,94 @@
+/// A floating-point newtype that serializes to two decimal places, preventing
+/// `toml_edit` from emitting noisy bit-pattern approximations such as
+/// `0.10000000149011612` or `0.20000000000000001`.
+///
+/// The inner value is stored as `f64`. When used for fields that ultimately
+/// require `f32`, callers should cast via `value() as f32`.
+pub struct Decimal(pub f64);
+
+impl Decimal {
+    /// Returns the inner `f64` value.
+    pub fn value(&self) -> f64 {
+        self.0
+    }
+}
+
+impl std::fmt::Debug for Decimal {
+    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
+        self.0.fmt(f)
+    }
+}
+
+impl Clone for Decimal {
+    fn clone(&self) -> Self {
+        *self
+    }
+}
+
+impl Copy for Decimal {}
+
+impl PartialEq for Decimal {
+    fn eq(&self, other: &Self) -> bool {
+        self.0 == other.0
+    }
+}
+
+impl PartialOrd for Decimal {
+    fn partial_cmp(&self, other: &Self) -> Option<std::cmp::Ordering> {
+        self.0.partial_cmp(&other.0)
+    }
+}
+
+impl Default for Decimal {
+    fn default() -> Self {
+        Self(0.0)
+    }
+}
+
+impl From<f64> for Decimal {
+    fn from(v: f64) -> Self {
+        Self(v)
+    }
+}
+
+impl From<f32> for Decimal {
+    fn from(v: f32) -> Self {
+        Self(v as f64)
+    }
+}
+
+impl From<Decimal> for f64 {
+    fn from(d: Decimal) -> Self {
+        d.0
+    }
+}
+
+impl schemars::JsonSchema for Decimal {
+    fn schema_name() -> std::borrow::Cow<'static, str> {
+        f64::schema_name()
+    }
+
+    fn json_schema(r#gen: &mut schemars::generate::SchemaGenerator) -> schemars::Schema {
+        f64::json_schema(r#gen)
+    }
+}
+
+impl fake::Dummy<fake::Faker> for Decimal {
+    fn dummy_with_rng<R: fake::RngExt + ?Sized>(_: &fake::Faker, rng: &mut R) -> Self {
+        use fake::Fake;
+        Self((0.0f64..2.0f64).fake_with_rng(rng))
+    }
+}
+
+impl serde::Serialize for Decimal {
+    fn serialize<S: serde::Serializer>(&self, serializer: S) -> Result<S::Ok, S::Error> {
+        let formatted: f64 = format!("{:.2}", self.0).parse().unwrap();
+        serializer.serialize_f64(formatted)
+    }
+}
+
+impl<'de> serde::Deserialize<'de> for Decimal {
+    fn deserialize<D: serde::Deserializer<'de>>(deserializer: D) -> Result<Self, D::Error> {
+        Ok(Self(f64::deserialize(deserializer)?))
+    }
+}

crates/forge_config/src/error.rs

@@ -0,0 +1,18 @@
+/// Errors produced by the `forge_config` crate.
+#[derive(Debug, thiserror::Error)]
+pub enum Error {
+    /// Failed to read or parse configuration from a file or environment.
+    #[error("Config error: {0}")]
+    Config(#[from] config::ConfigError),
+
+    /// Failed to serialize or write configuration.
+    #[error("Serialization error: {0}")]
+    Serialization(#[from] toml_edit::ser::Error),
+
+    /// An I/O error occurred while reading or writing configuration files.
+    #[error("IO error: {0}")]
+    Io(#[from] std::io::Error),
+
+    #[error("JSON error: {0}")]
+    Serde(#[from] serde_json::Error),
+}

crates/forge_config/src/http.rs

@@ -0,0 +1,95 @@
+use schemars::JsonSchema;
+use serde::{Deserialize, Serialize};
+
+/// TLS version enum for configuring TLS protocol versions.
+#[derive(Debug, Clone, PartialEq, Serialize, Deserialize, JsonSchema, fake::Dummy)]
+#[serde(rename_all = "snake_case")]
+pub enum TlsVersion {
+    #[serde(rename = "1.0")]
+    V1_0,
+    #[serde(rename = "1.1")]
+    V1_1,
+    #[serde(rename = "1.2")]
+    V1_2,
+    #[serde(rename = "1.3")]
+    V1_3,
+}
+
+/// TLS backend option.
+#[derive(Debug, Clone, PartialEq, Serialize, Deserialize, JsonSchema, fake::Dummy)]
+#[serde(rename_all = "snake_case")]
+pub enum TlsBackend {
+    #[serde(rename = "default")]
+    Default,
+    #[serde(rename = "rustls")]
+    Rustls,
+}
+
+/// HTTP client configuration.
+#[derive(Debug, Clone, PartialEq, Serialize, Deserialize, JsonSchema, fake::Dummy)]
+#[serde(rename_all = "snake_case")]
+pub struct HttpConfig {
+    pub connect_timeout_secs: u64,
+    pub read_timeout_secs: u64,
+    pub pool_idle_timeout_secs: u64,
+    pub pool_max_idle_per_host: usize,
+    pub max_redirects: usize,
+    pub hickory: bool,
+    pub tls_backend: TlsBackend,
+    /// Minimum TLS protocol version to use
+    pub min_tls_version: Option<TlsVersion>,
+    /// Maximum TLS protocol version to use
+    pub max_tls_version: Option<TlsVersion>,
+    /// Adaptive window sizing for improved flow control
+    pub adaptive_window: bool,
+    /// Keep-alive interval in seconds
+    pub keep_alive_interval_secs: Option<u64>,
+    /// Keep-alive timeout in seconds
+    pub keep_alive_timeout_secs: u64,
+    /// Keep-alive while connection is idle
+    pub keep_alive_while_idle: bool,
+    /// Accept invalid certificates
+    pub accept_invalid_certs: bool,
+    /// Paths to root certificate files
+    pub root_cert_paths: Option<Vec<String>>,
+}
+
+#[cfg(test)]
+mod tests {
+    use pretty_assertions::assert_eq;
+
+    use super::*;
+
+    #[test]
+    fn test_http_config_fields() {
+        let config = HttpConfig {
+            connect_timeout_secs: 30,
+            read_timeout_secs: 900,
+            pool_idle_timeout_secs: 90,
+            pool_max_idle_per_host: 5,
+            max_redirects: 10,
+            hickory: false,
+            tls_backend: TlsBackend::Default,
+            min_tls_version: None,
+            max_tls_version: None,
+            adaptive_window: true,
+            keep_alive_interval_secs: Some(60),
+            keep_alive_timeout_secs: 10,
+            keep_alive_while_idle: true,
+            accept_invalid_certs: false,
+            root_cert_paths: None,
+        };
+        assert_eq!(config.connect_timeout_secs, 30);
+        assert_eq!(config.adaptive_window, true);
+    }
+
+    #[test]
+    fn test_tls_version_variants() {
+        assert_eq!(TlsVersion::V1_3, TlsVersion::V1_3);
+    }
+
+    #[test]
+    fn test_tls_backend_variants() {
+        assert_eq!(TlsBackend::Default, TlsBackend::Default);
+    }
+}

crates/forge_config/src/legacy.rs

@@ -0,0 +1,81 @@
+use std::collections::HashMap;
+use std::path::PathBuf;
+
+use serde::Deserialize;
+
+use crate::{ForgeConfig, ModelConfig};
+
+/// Intermediate representation of the legacy `~/forge/.config.json` format.
+///
+/// This format stores the active provider as a top-level string and models as
+/// a map from provider ID to model ID, which differs from the TOML config's
+/// nested `session`, `commit`, and `suggest` sub-objects.
+#[derive(Debug, Deserialize)]
+#[serde(rename_all = "camelCase")]
+pub(crate) struct LegacyConfig {
+    /// The active provider ID (e.g. `"anthropic"`).
+    #[serde(default)]
+    provider: Option<String>,
+    /// Map from provider ID to the model ID to use with that provider.
+    #[serde(default)]
+    model: HashMap<String, String>,
+    /// Commit message generation provider/model pair.
+    #[serde(default)]
+    commit: Option<LegacyModelRef>,
+    /// Shell command suggestion provider/model pair.
+    #[serde(default)]
+    suggest: Option<LegacyModelRef>,
+}
+
+/// A provider/model pair as expressed in the legacy JSON config.
+#[derive(Debug, Deserialize)]
+struct LegacyModelRef {
+    provider: Option<String>,
+    model: Option<String>,
+}
+
+impl LegacyConfig {
+    /// Reads the legacy `~/forge/.config.json` file at `path`, parses it, and
+    /// returns the equivalent TOML representation as a [`String`].
+    ///
+    /// Because every field in [`ForgeConfig`] is `Option`, fields not covered
+    /// by the legacy format are `None` and omitted from the serialized TOML,
+    /// so they cannot overwrite values from lower-priority config layers.
+    ///
+    /// # Errors
+    ///
+    /// Returns an error if the file cannot be read, the JSON is invalid, or the
+    /// resulting config cannot be serialized to TOML.
+    pub(crate) fn read(path: &PathBuf) -> crate::Result<String> {
+        let contents = std::fs::read_to_string(path)?;
+        let config = serde_json::from_str::<LegacyConfig>(&contents)?;
+        let forge_config = config.into_forge_config();
+        let content = toml_edit::ser::to_string_pretty(&forge_config)?;
+        Ok(content)
+    }
+
+    /// Converts a [`LegacyConfig`] into the fields of [`ForgeConfig`] that it
+    /// covers, leaving all other fields at their defaults (`None`).
+    fn into_forge_config(self) -> ForgeConfig {
+        let session = self.provider.as_deref().and_then(|provider_id| {
+            self.model
+                .get(provider_id)
+                .cloned()
+                .map(|model_id| ModelConfig { provider_id: provider_id.to_string(), model_id })
+        });
+
+        let commit = self.commit.and_then(|c| {
+            c.provider
+                .zip(c.model)
+                .map(|(provider_id, model_id)| ModelConfig { provider_id, model_id })
+        });
+
+        let suggest = self.suggest.and_then(|s| {
+            s.provider
+                .zip(s.model)
+                .map(|(provider_id, model_id)| ModelConfig { provider_id, model_id })
+        });
+
+        ForgeConfig { session, commit, suggest, ..Default::default() }
+    }
+}

crates/forge_config/src/lib.rs

@@ -0,0 +1,29 @@
+mod auto_dump;
+mod compact;
+mod config;
+mod decimal;
+mod error;
+mod http;
+mod legacy;
+mod model;
+mod percentage;
+mod reader;
+mod reasoning;
+mod retry;
+mod writer;
+
+pub use auto_dump::*;
+pub use compact::*;
+pub use config::*;
+pub use decimal::*;
+pub use error::Error;
+pub use http::*;
+pub use model::*;
+pub use percentage::*;
+pub use reader::*;
+pub use reasoning::*;
+pub use retry::*;
+pub use writer::*;
+
+/// A `Result` type alias for this crate's [`Error`] type.
+pub type Result<T> = std::result::Result<T, Error>;

crates/forge_config/src/model.rs

@@ -0,0 +1,26 @@
+use derive_setters::Setters;
+use schemars::JsonSchema;
+use serde::{Deserialize, Serialize};
+
+/// A type alias for a provider identifier string.
+pub type ProviderId = String;
+
+/// A type alias for a model identifier string.
+pub type ModelId = String;
+
+/// Pairs a provider and model together for a specific operation.
+#[derive(Debug, Setters, Clone, PartialEq, Serialize, Deserialize, JsonSchema, fake::Dummy)]
+#[setters(into)]
+pub struct ModelConfig {
+    /// The provider to use for this operation.
+    pub provider_id: String,
+    /// The model to use for this operation.
+    pub model_id: String,
+}
+
+impl ModelConfig {
+    /// Creates a new ModelConfig with the given provider and model IDs.
+    pub fn new(provider_id: impl Into<String>, model_id: impl Into<String>) -> Self {
+        Self { provider_id: provider_id.into(), model_id: model_id.into() }
+    }
+}

crates/forge_config/src/percentage.rs

@@ -0,0 +1,136 @@
+use crate::Decimal;
+
+/// A percentage value constrained to `[0.0, 1.0]`, built on top of [`Decimal`]
+/// to inherit its two-decimal-place serialization and clean TOML output.
+///
+/// Validation is enforced at deserialization time, so any config file with an
+/// out-of-range value is rejected with a descriptive error.
+#[derive(Default)]
+pub struct Percentage(Decimal);
+
+impl Percentage {
+    const MIN: f64 = 0.0;
+    const MAX: f64 = 1.0;
+
+    /// Construct a validated `Percentage`.
+    ///
+    /// # Errors
+    ///
+    /// Returns `Err` if `value` is outside `[0.0, 1.0]`.
+    pub fn new(value: f64) -> Result<Self, String> {
+        if (Self::MIN..=Self::MAX).contains(&value) {
+            Ok(Self(Decimal(value)))
+        } else {
+            Err(format!(
+                "value must be between {} and {}, got {value}",
+                Self::MIN,
+                Self::MAX
+            ))
+        }
+    }
+
+    /// Returns the inner `f64` value.
+    pub fn value(&self) -> f64 {
+        self.0.value()
+    }
+}
+
+impl std::fmt::Debug for Percentage {
+    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
+        self.0.fmt(f)
+    }
+}
+
+impl Clone for Percentage {
+    fn clone(&self) -> Self {
+        *self
+    }
+}
+
+impl Copy for Percentage {}
+
+impl PartialEq for Percentage {
+    fn eq(&self, other: &Self) -> bool {
+        self.0 == other.0
+    }
+}
+
+impl PartialOrd for Percentage {
+    fn partial_cmp(&self, other: &Self) -> Option<std::cmp::Ordering> {
+        self.0.partial_cmp(&other.0)
+    }
+}
+
+impl From<f64> for Percentage {
+    fn from(v: f64) -> Self {
+        Self(Decimal::from(v))
+    }
+}
+
+impl From<Percentage> for f64 {
+    fn from(p: Percentage) -> Self {
+        p.0.into()
+    }
+}
+
+impl schemars::JsonSchema for Percentage {
+    fn schema_name() -> std::borrow::Cow<'static, str> {
+        Decimal::schema_name()
+    }
+
+    fn json_schema(r#gen: &mut schemars::generate::SchemaGenerator) -> schemars::Schema {
+        Decimal::json_schema(r#gen)
+    }
+}
+
+impl fake::Dummy<fake::Faker> for Percentage {
+    fn dummy_with_rng<R: fake::RngExt + ?Sized>(_: &fake::Faker, rng: &mut R) -> Self {
+        use fake::Fake;
+        Self(Decimal((0.0f64..=1.0f64).fake_with_rng::<f64, R>(rng)))
+    }
+}
+
+impl serde::Serialize for Percentage {
+    fn serialize<S: serde::Serializer>(&self, serializer: S) -> Result<S::Ok, S::Error> {
+        self.0.serialize(serializer)
+    }
+}
+
+impl<'de> serde::Deserialize<'de> for Percentage {
+    fn deserialize<D: serde::Deserializer<'de>>(deserializer: D) -> Result<Self, D::Error> {
+        let decimal = Decimal::deserialize(deserializer)?;
+        Self::new(decimal.value()).map_err(serde::de::Error::custom)
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use pretty_assertions::assert_eq;
+
+    use super::*;
+
+    #[test]
+    fn test_percentage_valid_range() {
+        assert!(Percentage::new(0.0).is_ok());
+        assert!(Percentage::new(0.5).is_ok());
+        assert!(Percentage::new(1.0).is_ok());
+    }
+
+    #[test]
+    fn test_percentage_rejects_out_of_range() {
+        assert!(Percentage::new(-0.1).is_err());
+        assert!(Percentage::new(1.1).is_err());
+    }
+
+    #[test]
+    fn test_percentage_serializes_to_2dp() {
+        #[derive(serde::Serialize)]
+        struct Fixture {
+            value: Percentage,
+        }
+        let fixture = Fixture { value: Percentage::new(0.2).unwrap() };
+        let actual = toml_edit::ser::to_string_pretty(&fixture).unwrap();
+        let expected = "value = 0.2\n";
+        assert_eq!(actual, expected);
+    }
+}

crates/forge_config/src/reader.rs

@@ -0,0 +1,314 @@
+use std::path::PathBuf;
+use std::sync::LazyLock;
+
+use config::ConfigBuilder;
+use config::builder::DefaultState;
+
+use crate::ForgeConfig;
+use crate::legacy::LegacyConfig;
+
+/// Loads all `.env` files found while walking up from the current working
+/// directory to the root, with priority given to closer (lower) directories.
+/// Executed at most once per process.
+static LOAD_DOT_ENV: LazyLock<()> = LazyLock::new(|| {
+    let cwd = std::env::current_dir().unwrap_or_else(|_| PathBuf::from("."));
+    let mut paths = vec![];
+    let mut current = PathBuf::new();
+
+    for component in cwd.components() {
+        current.push(component);
+        paths.push(current.clone());
+    }
+
+    paths.reverse();
+
+    for path in paths {
+        let env_file = path.join(".env");
+        if env_file.is_file() {
+            dotenvy::from_path(&env_file).ok();
+        }
+    }
+});
+
+/// Caches base-path resolution for the process lifetime.
+static BASE_PATH: LazyLock<PathBuf> = LazyLock::new(ConfigReader::resolve_base_path);
+
+/// Merges [`ForgeConfig`] from layered sources using a builder pattern.
+#[derive(Default)]
+pub struct ConfigReader {
+    builder: ConfigBuilder<DefaultState>,
+}
+
+impl ConfigReader {
+    /// Returns the path to the legacy JSON config file
+    /// (`~/.forge/.config.json`).
+    pub fn config_legacy_path() -> PathBuf {
+        Self::base_path().join(".config.json")
+    }
+
+    /// Returns the path to the primary TOML config file
+    /// (`~/.forge/.forge.toml`).
+    pub fn config_path() -> PathBuf {
+        Self::base_path().join(".forge.toml")
+    }
+
+    /// Returns the base directory for all Forge config files.
+    ///
+    /// Resolution order:
+    /// 1. `FORGE_CONFIG` environment variable, if set.
+    /// 2. `~/forge` (legacy path), if that directory exists, so users who have
+    ///    not yet run `forge config migrate` continue to read from their
+    ///    existing directory without disruption.
+    /// 3. `~/.forge` as the default path.
+    pub fn base_path() -> PathBuf {
+        BASE_PATH.clone()
+    }
+
+    fn resolve_base_path() -> PathBuf {
+        if let Ok(path) = std::env::var("FORGE_CONFIG") {
+            return PathBuf::from(path);
+        }
+
+        let base = dirs::home_dir().unwrap_or(PathBuf::from("."));
+        let path = base.join("forge");
+
+        // Prefer ~/forge (legacy) when it exists so existing users are not
+        // disrupted; fall back to ~/.forge as the default.
+        if path.exists() {
+            tracing::info!("Using legacy path");
+            return path;
+        }
+
+        tracing::info!("Using new path");
+        base.join(".forge")
+    }
+
+    /// Adds the provided TOML string as a config source without touching the
+    /// filesystem.
+    pub fn read_toml(mut self, contents: &str) -> Self {
+        self.builder = self
+            .builder
+            .add_source(config::File::from_str(contents, config::FileFormat::Toml));
+
+        self
+    }
+
+    /// Adds the embedded default config (`../.forge.toml`) as a source.
+    pub fn read_defaults(self) -> Self {
+        let defaults = include_str!("../.forge.toml");
+
+        self.read_toml(defaults)
+    }
+
+    /// Adds `FORGE_`-prefixed environment variables as a config source.
+    pub fn read_env(mut self) -> Self {
+        self.builder = self.builder.add_source(
+            config::Environment::with_prefix("FORGE")
+                .prefix_separator("_")
+                .separator("__")
+                .try_parsing(true)
+                .list_separator(",")
+                .with_list_parse_key("retry.status_codes")
+                .with_list_parse_key("http.root_cert_paths"),
+        );
+
+        self
+    }
+
+    /// Builds and deserializes all accumulated sources into a [`ForgeConfig`].
+    ///
+    /// Triggers `.env` file loading (at most once per process) by walking up
+    /// the directory tree from the current working directory, with closer
+    /// directories taking priority.
+    ///
+    /// # Errors
+    ///
+    /// Returns an error if the configuration cannot be built or deserialized.
+    pub fn build(self) -> crate::Result<ForgeConfig> {
+        *LOAD_DOT_ENV;
+        let config = self.builder.build()?;
+        Ok(config.try_deserialize::<ForgeConfig>()?)
+    }
+
+    /// Adds `~/.forge/.forge.toml` as a config source, silently skipping if
+    /// absent.
+    pub fn read_global(mut self) -> Self {
+        let path = Self::config_path();
+        self.builder = self
+            .builder
+            .add_source(config::File::from(path).required(false));
+        self
+    }
+
+    /// Reads `~/.forge/.config.json` (legacy format) and adds it as a source,
+    /// silently skipping errors.
+    pub fn read_legacy(self) -> Self {
+        let content = LegacyConfig::read(&Self::config_legacy_path());
+        if let Ok(content) = content {
+            self.read_toml(&content)
+        } else {
+            self
+        }
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use std::sync::{Mutex, MutexGuard};
+
+    use pretty_assertions::assert_eq;
+
+    use super::*;
+    use crate::ModelConfig;
+
+    /// Serializes tests that mutate environment variables to prevent races.
+    static ENV_MUTEX: Mutex<()> = Mutex::new(());
+
+    /// Holds env vars set for a test's duration and removes them on drop, while
+    /// holding [`ENV_MUTEX`].
+    struct EnvGuard {
+        keys: Vec<&'static str>,
+        _lock: MutexGuard<'static, ()>,
+    }
+
+    impl EnvGuard {
+        /// Acquires [`ENV_MUTEX`], sets each `(key, value)` pair in the
+        /// environment, and removes each key in `remove` if present. All
+        /// set keys are cleaned up on drop.
+        #[must_use]
+        fn set(pairs: &[(&'static str, &str)]) -> Self {
+            Self::set_and_remove(pairs, &[])
+        }
+
+        /// Like [`set`] but also removes the listed keys before the test runs.
+        #[must_use]
+        fn set_and_remove(pairs: &[(&'static str, &str)], remove: &[&'static str]) -> Self {
+            let lock = ENV_MUTEX.lock().unwrap_or_else(|e| e.into_inner());
+            let keys = pairs.iter().map(|(k, _)| *k).collect();
+            for key in remove {
+                unsafe { std::env::remove_var(key) };
+            }
+            for (key, value) in pairs {
+                unsafe { std::env::set_var(key, value) };
+            }
+            Self { keys, _lock: lock }
+        }
+    }
+
+    impl Drop for EnvGuard {
+        fn drop(&mut self) {
+            for key in &self.keys {
+                unsafe { std::env::remove_var(key) };
+            }
+        }
+    }
+
+    #[test]
+    fn test_base_path_uses_forge_config_env_var() {
+        let _guard = EnvGuard::set(&[("FORGE_CONFIG", "/custom/forge/dir")]);
+        let actual = ConfigReader::resolve_base_path();
+        let expected = PathBuf::from("/custom/forge/dir");
+        assert_eq!(actual, expected);
+    }
+
+    #[test]
+    fn test_base_path_falls_back_to_home_dir_when_env_var_absent() {
+        // Hold the env mutex and ensure FORGE_CONFIG is absent so this test
+        // cannot race with test_base_path_uses_forge_config_env_var.
+        let _guard = EnvGuard::set_and_remove(&[], &["FORGE_CONFIG"]);
+
+        let actual = ConfigReader::resolve_base_path();
+        // Without FORGE_CONFIG set the path must be either "forge" (legacy,
+        // preferred when ~/forge exists) or ".forge" (default new path).
+        let name = actual.file_name().unwrap();
+        assert!(
+            name == "forge" || name == ".forge",
+            "Expected base_path to end with 'forge' or '.forge', got: {:?}",
+            name
+        );
+    }
+
+    #[test]
+    fn test_read_parses_without_error() {
+        let actual = ConfigReader::default().read_defaults().build();
+        assert!(actual.is_ok(), "read() failed: {:?}", actual.err());
+    }
+
+    #[test]
+    fn test_legacy_layer_does_not_overwrite_defaults() {
+        // Simulate what `read_legacy` does: serialize a ForgeConfig that only
+        // carries session/commit/suggest (all other fields are None) and layer
+        // it on top of the embedded defaults. The default values must survive.
+        let legacy = ForgeConfig {
+            session: Some(ModelConfig {
+                provider_id: "anthropic".to_string(),
+                model_id: "claude-3".to_string(),
+            }),
+            ..Default::default()
+        };
+        let legacy_toml = toml_edit::ser::to_string_pretty(&legacy).unwrap();
+
+        let actual = ConfigReader::default()
+            // Read legacy first and then defaults
+            .read_toml(&legacy_toml)
+            .read_defaults()
+            .build()
+            .unwrap();
+
+        // Session should come from the legacy layer
+        assert_eq!(
+            actual.session,
+            Some(ModelConfig {
+                provider_id: "anthropic".to_string(),
+                model_id: "claude-3".to_string(),
+            })
+        );
+
+        // Default values from .forge.toml must be retained, not reset to zero
+        assert_eq!(actual.max_parallel_file_reads, 64);
+        assert_eq!(actual.max_read_lines, 2000);
+        assert_eq!(actual.tool_timeout_secs, 300);
+        assert_eq!(actual.max_search_lines, 1000);
+        assert_eq!(actual.tool_supported, true);
+    }
+
+    #[test]
+    fn test_read_session_from_env_vars() {
+        let _guard = EnvGuard::set(&[
+            ("FORGE_SESSION__PROVIDER_ID", "fake-provider"),
+            ("FORGE_SESSION__MODEL_ID", "fake-model"),
+        ]);
+
+        let actual = ConfigReader::default()
+            .read_defaults()
+            .read_env()
+            .build()
+            .unwrap();
+
+        let expected = Some(ModelConfig {
+            provider_id: "fake-provider".to_string(),
+            model_id: "fake-model".to_string(),
+        });
+        assert_eq!(actual.session, expected);
+    }
+
+    #[test]
+    fn test_use_forge_committer_defaults_to_true() {
+        let actual = ConfigReader::default().read_defaults().build().unwrap();
+
+        assert_eq!(actual.use_forge_committer, true);
+    }
+
+    #[test]
+    fn test_use_forge_committer_can_be_disabled() {
+        let toml = "use_forge_committer = false\n";
+
+        let actual = ConfigReader::default()
+            .read_defaults()
+            .read_toml(toml)
+            .build()
+            .unwrap();
+
+        assert_eq!(actual.use_forge_committer, false);
+    }
+}

crates/forge_config/src/reasoning.rs

@@ -0,0 +1,57 @@
+use derive_setters::Setters;
+use schemars::JsonSchema;
+use serde::{Deserialize, Serialize};
+use strum_macros::Display as StrumDisplay;
+
+/// Controls the reasoning behaviour of a model, including effort level, token
+/// budget, and visibility of the thinking process.
+#[derive(
+    Default, Debug, Clone, PartialEq, Serialize, Deserialize, JsonSchema, fake::Dummy, Setters,
+)]
+#[serde(rename_all = "snake_case")]
+#[setters(strip_option)]
+pub struct ReasoningConfig {
+    /// Controls the effort level of the model's reasoning.
+    /// Supported by openrouter and forge provider.
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub effort: Option<Effort>,
+
+    /// Controls how many tokens the model can spend thinking.
+    /// Should be greater than 1024 but less than the overall max_tokens.
+    /// Supported by openrouter, anthropic, and forge provider.
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub max_tokens: Option<usize>,
+
+    /// When true, the model thinks deeply but the reasoning is hidden from the
+    /// caller. Supported by openrouter and forge provider.
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub exclude: Option<bool>,
+
+    /// Enables reasoning at the "medium" effort level with no exclusions.
+    /// Supported by openrouter, anthropic, and forge provider.
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub enabled: Option<bool>,
+}
+
+/// Effort level for model reasoning.
+#[derive(
+    Debug, Clone, PartialEq, Serialize, Deserialize, JsonSchema, fake::Dummy, StrumDisplay,
+)]
+#[serde(rename_all = "lowercase")]
+#[strum(serialize_all = "lowercase")]
+pub enum Effort {
+    /// No reasoning; skips the thinking step entirely.
+    None,
+    /// Minimal reasoning; fastest and cheapest.
+    Minimal,
+    /// Low reasoning effort.
+    Low,
+    /// Medium reasoning effort; the default for most providers.
+    Medium,
+    /// High reasoning effort.
+    High,
+    /// Extra-high reasoning effort (OpenAI / OpenRouter).
+    XHigh,
+    /// Maximum reasoning effort; only available on select Anthropic models.
+    Max,
+}

crates/forge_config/src/retry.rs

@@ -0,0 +1,48 @@
+use derive_setters::Setters;
+use schemars::JsonSchema;
+use serde::{Deserialize, Serialize};
+
+/// Configuration for retry mechanism.
+#[derive(
+    Default, Debug, Clone, PartialEq, Serialize, Deserialize, JsonSchema, fake::Dummy, Setters,
+)]
+#[serde(rename_all = "snake_case")]
+#[setters(into)]
+pub struct RetryConfig {
+    /// Initial backoff delay in milliseconds for retry operations
+    pub initial_backoff_ms: u64,
+    /// Minimum delay in milliseconds between retry attempts
+    pub min_delay_ms: u64,
+    /// Backoff multiplication factor for each retry attempt
+    pub backoff_factor: u64,
+    /// Maximum number of retry attempts
+    pub max_attempts: usize,
+    /// HTTP status codes that should trigger retries
+    pub status_codes: Vec<u16>,
+    /// Maximum delay between retries in seconds
+    pub max_delay_secs: Option<u64>,
+    /// Whether to suppress retry error logging and events
+    pub suppress_errors: bool,
+}
+
+#[cfg(test)]
+mod tests {
+    use pretty_assertions::assert_eq;
+
+    use super::*;
+
+    #[test]
+    fn test_retry_config_fields() {
+        let config = RetryConfig {
+            initial_backoff_ms: 200,
+            min_delay_ms: 1000,
+            backoff_factor: 2,
+            max_attempts: 8,
+            status_codes: vec![429, 500, 502, 503, 504, 408, 522, 524, 520, 529],
+            max_delay_secs: None,
+            suppress_errors: false,
+        };
+        assert_eq!(config.initial_backoff_ms, 200);
+        assert_eq!(config.suppress_errors, false);
+    }
+}

crates/forge_config/src/writer.rs

@@ -0,0 +1,40 @@
+use std::path::Path;
+
+use crate::ForgeConfig;
+
+/// Writes a [`ForgeConfig`] to the user configuration file on disk.
+pub struct ConfigWriter {
+    config: ForgeConfig,
+}
+
+impl ConfigWriter {
+    /// Creates a new `ConfigWriter` for the given configuration.
+    pub fn new(config: ForgeConfig) -> Self {
+        Self { config }
+    }
+
+    /// Serializes and writes the configuration to `path`, creating all parent
+    /// directories recursively if they do not already exist.
+    ///
+    /// The output includes a leading `$schema` key pointing to the Forge
+    /// configuration JSON schema, which enables editor validation and
+    /// auto-complete.
+    ///
+    /// # Errors
+    ///
+    /// Returns an error if the configuration cannot be serialized or the file
+    /// cannot be written.
+    pub fn write(&self, path: &Path) -> crate::Result<()> {
+        if let Some(parent) = path.parent() {
+            std::fs::create_dir_all(parent)?;
+        }
+
+        let config_toml = toml_edit::ser::to_string_pretty(&self.config)?;
+        let contents =
+            format!("\"$schema\" = \"https://forgecode.dev/schema.json\"\n\n{config_toml}");
+
+        std::fs::write(path, contents)?;
+
+        Ok(())
+    }
+}

crates/forge_config/tests/schema.rs

@@ -0,0 +1,30 @@
+use std::path::Path;
+
+use forge_config::ForgeConfig;
+use pretty_assertions::assert_eq;
+
+#[tokio::test]
+async fn generate_workflow_schema() -> anyhow::Result<()> {
+    let schema = schemars::schema_for!(ForgeConfig);
+    let generated_schema = serde_json::to_string_pretty(&schema)?;
+
+    // Use the crate root directory for the schema file
+    let crate_root = env!("CARGO_MANIFEST_DIR");
+    let schema_path = Path::new(crate_root).join("../../forge.schema.json");
+
+    if is_ci::uncached() {
+        // On CI: validate that the generated schema matches the committed file
+        let existing_schema = tokio::fs::read_to_string(&schema_path).await?;
+        assert_eq!(
+            generated_schema.trim(),
+            existing_schema.trim(),
+            "Generated workflow schema does not match the committed schema file. \
+             Please run the test locally to update the schema file."
+        );
+    } else {
+        // Locally: generate and write the schema file
+        tokio::fs::write(&schema_path, generated_schema).await?;
+    }
+
+    Ok(())
+}

crates/forge_embed/src/lib.rs

@@ -0,0 +1,39 @@
+use handlebars::Handlebars;
+use include_dir::{Dir, DirEntry, File};
+
+/// Returns an iterator over all files embedded in `dir`, recursively
+/// descending into subdirectories.
+pub fn files(dir: &'static Dir<'static>) -> impl Iterator<Item = &'static File<'static>> {
+    dir.entries().iter().flat_map(walk_entry)
+}
+
+fn walk_entry(
+    entry: &'static DirEntry<'static>,
+) -> Box<dyn Iterator<Item = &'static File<'static>>> {
+    match entry {
+        DirEntry::File(f) => Box::new(std::iter::once(f)),
+        DirEntry::Dir(d) => Box::new(d.entries().iter().flat_map(walk_entry)),
+    }
+}
+
+/// Registers all files in `dir` (recursively) as Handlebars templates.
+///
+/// Template names match the relative file path as returned by
+/// [`File::path`] (e.g. `forge-system-prompt.md`). Panics if any file path
+/// is not valid UTF-8, if any file content is not valid UTF-8, or if template
+/// parsing fails.
+pub fn register_templates(hb: &mut Handlebars<'_>, dir: &'static Dir<'static>) {
+    for file in files(dir) {
+        let name = file.path().to_str().unwrap_or_else(|| {
+            panic!(
+                "embedded template path '{:?}' is not valid UTF-8",
+                file.path()
+            )
+        });
+        let content = file
+            .contents_utf8()
+            .unwrap_or_else(|| panic!("embedded template '{}' is not valid UTF-8", name));
+        hb.register_template_string(name, content)
+            .unwrap_or_else(|e| panic!("failed to register template '{}': {}", name, e));
+    }
+}

crates/forge_eventsource/src/error.rs

@@ -0,0 +1,59 @@
+use core::fmt;
+use std::string::FromUtf8Error;
+
+use forge_eventsource_stream::EventStreamError;
+use nom::error::Error as NomError;
+#[cfg(doc)]
+use reqwest::RequestBuilder;
+use reqwest::header::HeaderValue;
+use reqwest::{Error as ReqwestError, Response, StatusCode};
+
+/// Error raised when a [`RequestBuilder`] cannot be cloned. See
+/// [`RequestBuilder::try_clone`] for more information
+#[derive(Debug, Clone, Copy)]
+pub struct CannotCloneRequestError;
+
+impl fmt::Display for CannotCloneRequestError {
+    fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result {
+        f.write_str("expected a cloneable request")
+    }
+}
+
+impl std::error::Error for CannotCloneRequestError {}
+
+/// Error raised by the EventSource stream fetching and parsing
+#[derive(Debug, Error)]
+pub enum Error {
+    /// Source stream is not valid UTF8
+    #[error(transparent)]
+    Utf8(FromUtf8Error),
+    /// Source stream is not a valid EventStream
+    #[error(transparent)]
+    Parser(NomError<String>),
+    /// The HTTP Request could not be completed
+    #[error(transparent)]
+    Transport(ReqwestError),
+    /// The `Content-Type` returned by the server is invalid
+    #[error("Invalid header value: {0:?}")]
+    InvalidContentType(HeaderValue, Box<Response>),
+    /// The status code returned by the server is invalid
+    #[error("Invalid status code: {0}")]
+    InvalidStatusCode(StatusCode, Box<Response>),
+    /// The `Last-Event-ID` cannot be formed into a Header to be submitted to
+    /// the server
+    #[error("Invalid `Last-Event-ID`: {0}")]
+    InvalidLastEventId(String),
+    /// The stream ended
+    #[error("Stream ended")]
+    StreamEnded,
+}
+
+impl From<EventStreamError<ReqwestError>> for Error {
+    fn from(err: EventStreamError<ReqwestError>) -> Self {
+        match err {
+            EventStreamError::Utf8(err) => Self::Utf8(err),
+            EventStreamError::Parser(err) => Self::Parser(err),
+            EventStreamError::Transport(err) => Self::Transport(err),
+        }
+    }
+}

crates/forge_eventsource/src/event_source.rs

@@ -0,0 +1,290 @@
+use core::pin::Pin;
+use std::time::Duration;
+
+use forge_eventsource_stream::Eventsource;
+pub use forge_eventsource_stream::{Event as MessageEvent, EventStreamError};
+#[cfg(not(target_arch = "wasm32"))]
+use futures_core::future::BoxFuture;
+use futures_core::future::Future;
+#[cfg(target_arch = "wasm32")]
+use futures_core::future::LocalBoxFuture;
+#[cfg(not(target_arch = "wasm32"))]
+use futures_core::stream::BoxStream;
+#[cfg(target_arch = "wasm32")]
+use futures_core::stream::LocalBoxStream;
+use futures_core::stream::Stream;
+use futures_core::task::{Context, Poll};
+use futures_timer::Delay;
+use pin_project_lite::pin_project;
+use reqwest::header::{HeaderName, HeaderValue};
+use reqwest::{Error as ReqwestError, IntoUrl, RequestBuilder, Response, StatusCode};
+
+use crate::error::{CannotCloneRequestError, Error};
+use crate::retry::{DEFAULT_RETRY, RetryPolicy};
+
+#[cfg(not(target_arch = "wasm32"))]
+type ResponseFuture = BoxFuture<'static, Result<Response, ReqwestError>>;
+#[cfg(target_arch = "wasm32")]
+type ResponseFuture = LocalBoxFuture<'static, Result<Response, ReqwestError>>;
+
+#[cfg(not(target_arch = "wasm32"))]
+type EventStream = BoxStream<'static, Result<MessageEvent, EventStreamError<ReqwestError>>>;
+#[cfg(target_arch = "wasm32")]
+type EventStream = LocalBoxStream<'static, Result<MessageEvent, EventStreamError<ReqwestError>>>;
+
+type BoxedRetry = Box<dyn RetryPolicy + Send + Unpin + 'static>;
+
+/// The ready state of an [`EventSource`]
+#[derive(Debug, Clone, Copy, Eq, PartialEq, Ord, PartialOrd)]
+#[repr(u8)]
+pub enum ReadyState {
+    /// The EventSource is waiting on a response from the endpoint
+    Connecting = 0,
+    /// The EventSource is connected
+    Open = 1,
+    /// The EventSource is closed and no longer emitting Events
+    Closed = 2,
+}
+
+pin_project! {
+/// Provides the [`Stream`] implementation for the [`Event`] items. This wraps the
+/// [`RequestBuilder`] and retries requests when they fail.
+#[project = EventSourceProjection]
+pub struct EventSource {
+    builder: RequestBuilder,
+    #[pin]
+    next_response: Option<ResponseFuture>,
+    #[pin]
+    cur_stream: Option<EventStream>,
+    #[pin]
+    delay: Option<Delay>,
+    is_closed: bool,
+    retry_policy: BoxedRetry,
+    last_event_id: String,
+    last_retry: Option<(usize, Duration)>
+}
+}
+
+impl EventSource {
+    /// Wrap a [`RequestBuilder`]
+    pub fn new(builder: RequestBuilder) -> Result<Self, CannotCloneRequestError> {
+        let builder = builder.header(
+            reqwest::header::ACCEPT,
+            HeaderValue::from_static("text/event-stream"),
+        );
+        let res_future = Box::pin(builder.try_clone().ok_or(CannotCloneRequestError)?.send());
+        Ok(Self {
+            builder,
+            next_response: Some(res_future),
+            cur_stream: None,
+            delay: None,
+            is_closed: false,
+            retry_policy: Box::new(DEFAULT_RETRY),
+            last_event_id: String::new(),
+            last_retry: None,
+        })
+    }
+
+    /// Create a simple EventSource based on a GET request
+    pub fn get<T: IntoUrl>(url: T) -> Self {
+        Self::new(reqwest::Client::new().get(url)).unwrap()
+    }
+
+    /// Close the EventSource stream and stop trying to reconnect
+    pub fn close(&mut self) {
+        self.is_closed = true;
+    }
+
+    /// Set the retry policy
+    pub fn set_retry_policy(&mut self, policy: BoxedRetry) {
+        self.retry_policy = policy
+    }
+
+    /// Get the last event id
+    pub fn last_event_id(&self) -> &str {
+        &self.last_event_id
+    }
+
+    /// Get the current ready state
+    pub fn ready_state(&self) -> ReadyState {
+        if self.is_closed {
+            ReadyState::Closed
+        } else if self.delay.is_some() || self.next_response.is_some() {
+            ReadyState::Connecting
+        } else {
+            ReadyState::Open
+        }
+    }
+}
+
+fn check_response(response: Response) -> Result<Response, Error> {
+    match response.status() {
+        StatusCode::OK => {}
+        status => {
+            return Err(Error::InvalidStatusCode(status, Box::new(response)));
+        }
+    }
+    let content_type =
+        if let Some(content_type) = response.headers().get(&reqwest::header::CONTENT_TYPE) {
+            content_type
+        } else {
+            return Err(Error::InvalidContentType(
+                HeaderValue::from_static(""),
+                Box::new(response),
+            ));
+        };
+    if content_type
+        .to_str()
+        .map_err(|_| ())
+        .and_then(|s| s.parse::<mime::Mime>().map_err(|_| ()))
+        .map(|mime_type| {
+            matches!(
+                (mime_type.type_(), mime_type.subtype()),
+                (mime::TEXT, mime::EVENT_STREAM)
+            )
+        })
+        .unwrap_or(false)
+    {
+        Ok(response)
+    } else {
+        Err(Error::InvalidContentType(
+            content_type.clone(),
+            Box::new(response),
+        ))
+    }
+}
+
+impl<'a> EventSourceProjection<'a> {
+    fn clear_fetch(&mut self) {
+        self.next_response.take();
+        self.cur_stream.take();
+    }
+
+    fn retry_fetch(&mut self) -> Result<(), Error> {
+        self.cur_stream.take();
+        let req = self.builder.try_clone().unwrap().header(
+            HeaderName::from_static("last-event-id"),
+            HeaderValue::from_str(self.last_event_id)
+                .map_err(|_| Error::InvalidLastEventId(self.last_event_id.clone()))?,
+        );
+        let res_future = Box::pin(req.send());
+        self.next_response.replace(res_future);
+        Ok(())
+    }
+
+    fn handle_response(&mut self, res: Response) {
+        self.last_retry.take();
+        let mut stream = res.bytes_stream().eventsource();
+        stream.set_last_event_id(self.last_event_id.clone());
+        self.cur_stream.replace(Box::pin(stream));
+    }
+
+    fn handle_event(&mut self, event: &MessageEvent) {
+        *self.last_event_id = event.id.clone();
+        if let Some(duration) = event.retry {
+            self.retry_policy.set_reconnection_time(duration)
+        }
+    }
+
+    fn handle_error(&mut self, error: &Error) {
+        self.clear_fetch();
+        if let Some(retry_delay) = self.retry_policy.retry(error, *self.last_retry) {
+            let retry_num = self.last_retry.map(|retry| retry.0).unwrap_or(1);
+            *self.last_retry = Some((retry_num, retry_delay));
+            self.delay.replace(Delay::new(retry_delay));
+        } else {
+            *self.is_closed = true;
+        }
+    }
+}
+
+/// Events created by the [`EventSource`]
+#[derive(Debug, Clone, Eq, PartialEq)]
+pub enum Event {
+    /// The event fired when the connection is opened
+    Open,
+    /// The event fired when a [`MessageEvent`] is received
+    Message(MessageEvent),
+}
+
+impl From<MessageEvent> for Event {
+    fn from(event: MessageEvent) -> Self {
+        Event::Message(event)
+    }
+}
+
+impl Stream for EventSource {
+    type Item = Result<Event, Error>;
+
+    fn poll_next(self: Pin<&mut Self>, cx: &mut Context) -> Poll<Option<Self::Item>> {
+        let mut this = self.project();
+
+        if *this.is_closed {
+            return Poll::Ready(None);
+        }
+
+        if let Some(delay) = this.delay.as_mut().as_pin_mut() {
+            match delay.poll(cx) {
+                Poll::Ready(_) => {
+                    this.delay.take();
+                    if let Err(err) = this.retry_fetch() {
+                        *this.is_closed = true;
+                        return Poll::Ready(Some(Err(err)));
+                    }
+                }
+                Poll::Pending => return Poll::Pending,
+            }
+        }
+
+        if let Some(response_future) = this.next_response.as_mut().as_pin_mut() {
+            match response_future.poll(cx) {
+                Poll::Ready(Ok(res)) => {
+                    this.clear_fetch();
+                    match check_response(res) {
+                        Ok(res) => {
+                            this.handle_response(res);
+                            return Poll::Ready(Some(Ok(Event::Open)));
+                        }
+                        Err(err) => {
+                            *this.is_closed = true;
+                            return Poll::Ready(Some(Err(err)));
+                        }
+                    }
+                }
+                Poll::Ready(Err(err)) => {
+                    let err = Error::Transport(err);
+                    this.handle_error(&err);
+                    return Poll::Ready(Some(Err(err)));
+                }
+                Poll::Pending => {
+                    return Poll::Pending;
+                }
+            }
+        }
+
+        match this
+            .cur_stream
+            .as_mut()
+            .as_pin_mut()
+            .unwrap()
+            .as_mut()
+            .poll_next(cx)
+        {
+            Poll::Ready(Some(Err(err))) => {
+                let err = err.into();
+                this.handle_error(&err);
+                Poll::Ready(Some(Err(err)))
+            }
+            Poll::Ready(Some(Ok(event))) => {
+                this.handle_event(&event);
+                Poll::Ready(Some(Ok(event.into())))
+            }
+            Poll::Ready(None) => {
+                let err = Error::StreamEnded;
+                this.handle_error(&err);
+                Poll::Ready(Some(Err(err)))
+            }
+            Poll::Pending => Poll::Pending,
+        }
+    }
+}

crates/forge_eventsource/src/lib.rs

@@ -0,0 +1,33 @@
+//! Provides a simple wrapper for [`reqwest`] to provide an Event Source
+//! implementation. You can learn more about Server Sent Events (SSE) take a
+//! look at [the MDN docs](https://developer.mozilla.org/en-US/docs/Web/API/Server-sent_events/Using_server-sent_events)
+//! This crate uses [`forge_eventsource_stream`] to wrap the underlying Bytes
+//! stream, and retries failed requests.
+//!
+//! # Example
+//!
+//! ```ignore
+//! let mut es = EventSource::get("http://localhost:8000/events");
+//! while let Some(event) = es.next().await {
+//!     match event {
+//!         Ok(Event::Open) => println!("Connection Open!"),
+//!         Ok(Event::Message(message)) => println!("Message: {:#?}", message),
+//!         Err(err) => {
+//!             println!("Error: {}", err);
+//!             es.close();
+//!         }
+//!     }
+//! }
+//! ```
+
+#[macro_use]
+extern crate thiserror;
+
+mod error;
+mod event_source;
+mod reqwest_ext;
+pub mod retry;
+
+pub use error::{CannotCloneRequestError, Error};
+pub use event_source::{Event, EventSource, ReadyState};
+pub use reqwest_ext::RequestBuilderExt;

crates/forge_eventsource/src/reqwest_ext.rs

@@ -0,0 +1,17 @@
+use reqwest::RequestBuilder;
+
+use crate::error::CannotCloneRequestError;
+use crate::event_source::EventSource;
+
+/// Provides an easy interface to build an [`EventSource`] from a
+/// [`RequestBuilder`]
+pub trait RequestBuilderExt {
+    /// Create a new [`EventSource`] from a [`RequestBuilder`]
+    fn eventsource(self) -> Result<EventSource, CannotCloneRequestError>;
+}
+
+impl RequestBuilderExt for RequestBuilder {
+    fn eventsource(self) -> Result<EventSource, CannotCloneRequestError> {
+        EventSource::new(self)
+    }
+}

crates/forge_eventsource/src/retry.rs

@@ -0,0 +1,120 @@
+//! Helpers to handle connection delays when receiving errors
+
+use std::time::Duration;
+
+use crate::error::Error;
+#[cfg(doc)]
+use crate::event_source::{Event, EventSource};
+
+/// Describes how an [`EventSource`] should retry on receiving an [`enum@Error`]
+pub trait RetryPolicy {
+    /// Submit a new retry delay based on the [`enum@Error`], last retry number
+    /// and duration, if available. A policy may also return `None` if it
+    /// does not want to retry
+    fn retry(&self, error: &Error, last_retry: Option<(usize, Duration)>) -> Option<Duration>;
+
+    /// Set a new reconnection time if received from an [`Event`]
+    fn set_reconnection_time(&mut self, duration: Duration);
+}
+
+/// A [`RetryPolicy`] which backs off exponentially
+#[derive(Debug, Clone)]
+pub struct ExponentialBackoff {
+    /// The start of the backoff
+    pub start: Duration,
+    /// The factor of which to backoff by
+    pub factor: f64,
+    /// The maximum duration to delay
+    pub max_duration: Option<Duration>,
+    /// The maximum number of retries before giving up
+    pub max_retries: Option<usize>,
+}
+
+impl ExponentialBackoff {
+    /// Create a new exponential backoff retry policy
+    pub const fn new(
+        start: Duration,
+        factor: f64,
+        max_duration: Option<Duration>,
+        max_retries: Option<usize>,
+    ) -> Self {
+        Self { start, factor, max_duration, max_retries }
+    }
+}
+
+impl RetryPolicy for ExponentialBackoff {
+    fn retry(&self, _error: &Error, last_retry: Option<(usize, Duration)>) -> Option<Duration> {
+        if let Some((retry_num, last_duration)) = last_retry {
+            if self.max_retries.is_none() || retry_num < self.max_retries.unwrap() {
+                let duration = last_duration.mul_f64(self.factor);
+                if let Some(max_duration) = self.max_duration {
+                    Some(duration.min(max_duration))
+                } else {
+                    Some(duration)
+                }
+            } else {
+                None
+            }
+        } else {
+            Some(self.start)
+        }
+    }
+    fn set_reconnection_time(&mut self, duration: Duration) {
+        self.start = duration;
+        if let Some(max_duration) = self.max_duration {
+            self.max_duration = Some(max_duration.max(duration))
+        }
+    }
+}
+
+/// A [`RetryPolicy`] which always emits the same delay
+#[derive(Debug, Clone)]
+pub struct Constant {
+    /// The delay to return
+    pub delay: Duration,
+    /// The maximum number of retries to return before giving up
+    pub max_retries: Option<usize>,
+}
+
+impl Constant {
+    /// Create a new constant retry policy
+    pub const fn new(delay: Duration, max_retries: Option<usize>) -> Self {
+        Self { delay, max_retries }
+    }
+}
+
+impl RetryPolicy for Constant {
+    fn retry(&self, _error: &Error, last_retry: Option<(usize, Duration)>) -> Option<Duration> {
+        if let Some((retry_num, _)) = last_retry {
+            if self.max_retries.is_none() || retry_num < self.max_retries.unwrap() {
+                Some(self.delay)
+            } else {
+                None
+            }
+        } else {
+            Some(self.delay)
+        }
+    }
+    fn set_reconnection_time(&mut self, duration: Duration) {
+        self.delay = duration;
+    }
+}
+
+/// A [`RetryPolicy`] which never retries
+#[derive(Debug, Clone, Copy, Default)]
+pub struct Never;
+
+impl RetryPolicy for Never {
+    fn retry(&self, _error: &Error, _last_retry: Option<(usize, Duration)>) -> Option<Duration> {
+        None
+    }
+    fn set_reconnection_time(&mut self, _duration: Duration) {}
+}
+
+/// The default [`RetryPolicy`] when initializing an [`EventSource`]
+pub const DEFAULT_RETRY: ExponentialBackoff = ExponentialBackoff::new(
+    Duration::from_millis(300),
+    2.,
+    Some(Duration::from_secs(5)),
+    None,
+);

crates/forge_infra/src/auth/error.rs

@@ -0,0 +1,37 @@
+use std::time::Duration;
+
+/// Authentication flow errors.
+#[derive(Debug, Clone, thiserror::Error)]
+pub enum Error {
+    /// Authentication initiation failed.
+    #[error("Authentication initiation failed: {0}")]
+    InitiationFailed(String),
+
+    /// Authentication timed out waiting for user.
+    #[error("Authentication timed out after {0:?}")]
+    Timeout(Duration),
+
+    /// Device code or session expired before completion.
+    #[error("Device code or session expired")]
+    Expired,
+
+    /// User denied authorization request.
+    #[error("User denied authorization")]
+    Denied,
+
+    /// Polling operation failed due to network or server error.
+    #[error("Polling failed: {0}")]
+    PollFailed(String),
+
+    /// Authentication completion failed.
+    #[error("Authentication completion failed: {0}")]
+    CompletionFailed(String),
+
+    /// Token refresh operation failed.
+    #[error("Token refresh failed: {0}")]
+    RefreshFailed(String),
+
+    /// Invalid authentication context for the flow type.
+    #[error("Invalid context: {0}")]
+    InvalidContext(String),
+}

crates/forge_infra/src/auth/http/anthropic.rs

@@ -0,0 +1,148 @@
+use forge_app::OAuthHttpProvider;
+use forge_domain::{AuthCodeParams, OAuthConfig, OAuthTokenResponse};
+use oauth2::PkceCodeChallenge;
+use serde::Serialize;
+
+use crate::auth::util::build_http_client;
+
+/// Anthropic Provider - Non-standard PKCE implementation
+/// Quirk: state parameter equals PKCE verifier
+#[allow(unused)]
+pub struct AnthropicHttpProvider;
+
+#[allow(unused)]
+#[derive(Debug, Serialize)]
+struct AnthropicTokenRequest {
+    /// Authorization code from callback
+    code: String,
+    /// State parameter (equals PKCE verifier)
+    state: String,
+    /// Must be "authorization_code"
+    grant_type: String,
+    /// OAuth client ID
+    client_id: String,
+    /// Redirect URI (must match authorization request)
+    #[serde(skip_serializing_if = "Option::is_none")]
+    redirect_uri: Option<String>,
+    /// PKCE code verifier
+    code_verifier: String,
+}
+
+#[async_trait::async_trait]
+impl OAuthHttpProvider for AnthropicHttpProvider {
+    async fn build_auth_url(&self, config: &OAuthConfig) -> anyhow::Result<AuthCodeParams> {
+        // Anthropic quirk: state = verifier
+        let (challenge, verifier) = PkceCodeChallenge::new_random_sha256();
+
+        let mut url = config.auth_url.clone();
+        url.query_pairs_mut()
+            .append_pair("client_id", &config.client_id)
+            .append_pair("response_type", "code")
+            .append_pair("scope", &config.scopes.join(" "))
+            .append_pair("code_challenge", challenge.as_str())
+            .append_pair("code_challenge_method", "S256")
+            .append_pair("state", verifier.secret()); // ← Non-standard!
+
+        if let Some(redirect_uri) = &config.redirect_uri {
+            url.query_pairs_mut()
+                .append_pair("redirect_uri", redirect_uri);
+        }
+
+        if let Some(extra_params) = &config.extra_auth_params {
+            for (key, value) in extra_params {
+                url.query_pairs_mut().append_pair(key, value);
+            }
+        }
+
+        Ok(AuthCodeParams {
+            auth_url: url.to_string(),
+            state: verifier.secret().to_string(),
+            code_verifier: Some(verifier.secret().to_string()),
+        })
+    }
+
+    async fn exchange_code(
+        &self,
+        config: &OAuthConfig,
+        code: &str,
+        verifier: Option<&str>,
+    ) -> anyhow::Result<OAuthTokenResponse> {
+        // Anthropic-specific token exchange
+        let (code, state) = if code.contains('#') {
+            let parts: Vec<&str> = code.split('#').collect();
+            (
+                parts.first().map(|s| s.to_string()).unwrap_or_default(),
+                parts.get(1).map(|s| s.to_string()),
+            )
+        } else {
+            (code.to_string(), None)
+        };
+
+        let verifier = verifier
+            .ok_or_else(|| anyhow::anyhow!("PKCE verifier required for Anthropic OAuth"))?;
+
+        let request_body = AnthropicTokenRequest {
+            code,
+            state: state.unwrap_or_else(|| verifier.to_string()),
+            grant_type: "authorization_code".to_string(),
+            client_id: config.client_id.to_string(),
+            redirect_uri: config.redirect_uri.clone(),
+            code_verifier: verifier.to_string(),
+        };
+
+        let client = self.build_http_client(config)?;
+        let response = client
+            .post(config.token_url.as_str())
+            .header("Content-Type", "application/json")
+            .json(&request_body)
+            .send()
+            .await?;
+
+        if !response.status().is_success() {
+            let status = response.status();
+            let error_text = response.text().await.unwrap_or_default();
+            anyhow::bail!("Token exchange failed with status {status}: {error_text}");
+        }
+
+        Ok(response.json().await?)
+    }
+
+    /// Create HTTP client with provider-specific headers/behavior
+    fn build_http_client(&self, config: &OAuthConfig) -> anyhow::Result<reqwest::Client> {
+        build_http_client(config.custom_headers.as_ref())
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use forge_domain::OAuthConfig;
+    use url::Url;
+
+    use super::*;
+
+    fn test_oauth_config() -> OAuthConfig {
+        OAuthConfig {
+            client_id: "test_client".to_string().into(),
+            auth_url: Url::parse("https://example.com/auth").unwrap(),
+            token_url: Url::parse("https://example.com/token").unwrap(),
+            scopes: vec!["read".to_string(), "write".to_string()],
+            redirect_uri: Some("https://example.com/callback".to_string()),
+            use_pkce: true,
+            token_refresh_url: None,
+            extra_auth_params: None,
+            custom_headers: None,
+        }
+    }
+
+    #[tokio::test]
+    async fn test_anthropic_provider_state_equals_verifier() {
+        let provider = AnthropicHttpProvider;
+        let config = test_oauth_config();
+
+        let result = provider.build_auth_url(&config).await.unwrap();
+
+        // Anthropic quirk: state should equal verifier
+        assert_eq!(result.state, result.code_verifier.unwrap());
+        assert!(result.auth_url.contains("code_challenge_method=S256"));
+    }
+}

crates/forge_infra/src/auth/http/github.rs

@@ -0,0 +1,35 @@
+use forge_app::OAuthHttpProvider;
+use forge_domain::{AuthCodeParams, OAuthConfig, OAuthTokenResponse};
+
+use super::standard::StandardHttpProvider;
+use crate::auth::util::build_http_client;
+
+/// GitHub Provider - HTTP 200 responses may contain errors
+pub struct GithubHttpProvider;
+
+#[async_trait::async_trait]
+impl OAuthHttpProvider for GithubHttpProvider {
+    async fn build_auth_url(&self, config: &OAuthConfig) -> anyhow::Result<AuthCodeParams> {
+        // Use standard flow - no quirks in auth URL
+        StandardHttpProvider.build_auth_url(config).await
+    }
+
+    async fn exchange_code(
+        &self,
+        config: &OAuthConfig,
+        code: &str,
+        verifier: Option<&str>,
+    ) -> anyhow::Result<OAuthTokenResponse> {
+        // Use standard exchange - quirks handled in HTTP client via
+        // github_compliant_http_request
+        StandardHttpProvider
+            .exchange_code(config, code, verifier)
+            .await
+    }
+
+    fn build_http_client(&self, config: &OAuthConfig) -> anyhow::Result<reqwest::Client> {
+        // GitHub quirk: HTTP 200 responses may contain errors
+        // This is handled by the github_compliant_http_request function
+        build_http_client(config.custom_headers.as_ref())
+    }
+}

crates/forge_infra/src/auth/http/mod.rs

@@ -0,0 +1,7 @@
+mod anthropic;
+mod github;
+mod standard;
+
+pub(crate) use anthropic::AnthropicHttpProvider;
+pub(crate) use github::GithubHttpProvider;
+pub(crate) use standard::StandardHttpProvider;

crates/forge_infra/src/auth/http/standard.rs

@@ -0,0 +1,139 @@
+use forge_app::OAuthHttpProvider;
+use forge_domain::{AuthCodeParams, OAuthConfig, OAuthTokenResponse};
+use oauth2::{CsrfToken, PkceCodeChallenge, Scope};
+use serde::Serialize;
+
+use crate::auth::util::*;
+
+/// Standard RFC-compliant OAuth provider
+pub struct StandardHttpProvider;
+
+#[derive(Debug, Serialize)]
+struct StandardTokenRequest<'a> {
+    grant_type: &'static str,
+    code: &'a str,
+    client_id: &'a str,
+    #[serde(skip_serializing_if = "Option::is_none")]
+    redirect_uri: Option<&'a str>,
+    #[serde(skip_serializing_if = "Option::is_none")]
+    code_verifier: Option<&'a str>,
+}
+
+#[async_trait::async_trait]
+impl OAuthHttpProvider for StandardHttpProvider {
+    async fn build_auth_url(&self, config: &OAuthConfig) -> anyhow::Result<AuthCodeParams> {
+        // Use oauth2 library - standard flow
+        use oauth2::{AuthUrl, ClientId, TokenUrl};
+
+        let mut client =
+            oauth2::basic::BasicClient::new(ClientId::new(config.client_id.to_string()))
+                .set_auth_uri(AuthUrl::new(config.auth_url.to_string())?)
+                .set_token_uri(TokenUrl::new(config.token_url.to_string())?);
+
+        if let Some(redirect_uri) = &config.redirect_uri {
+            client = client.set_redirect_uri(oauth2::RedirectUrl::new(redirect_uri.clone())?);
+        }
+
+        let mut request = client.authorize_url(CsrfToken::new_random);
+
+        for scope in &config.scopes {
+            request = request.add_scope(Scope::new(scope.clone()));
+        }
+
+        if let Some(extra_params) = &config.extra_auth_params {
+            for (key, value) in extra_params {
+                request = request.add_extra_param(key, value);
+            }
+        }
+
+        let (auth_url, csrf_state, pkce_verifier) = if config.use_pkce {
+            let (challenge, verifier) = PkceCodeChallenge::new_random_sha256();
+            let (url, state) = request.set_pkce_challenge(challenge).url();
+            (url, state, Some(verifier))
+        } else {
+            let (url, state) = request.url();
+            (url, state, None)
+        };
+
+        Ok(AuthCodeParams {
+            auth_url: auth_url.to_string(),
+            state: csrf_state.secret().to_string(),
+            code_verifier: pkce_verifier.map(|v| v.secret().to_string()),
+        })
+    }
+
+    async fn exchange_code(
+        &self,
+        config: &OAuthConfig,
+        code: &str,
+        verifier: Option<&str>,
+    ) -> anyhow::Result<OAuthTokenResponse> {
+        let http_client = self.build_http_client(config)?;
+        let request_body = StandardTokenRequest {
+            grant_type: "authorization_code",
+            code,
+            client_id: config.client_id.as_ref(),
+            redirect_uri: config.redirect_uri.as_deref(),
+            code_verifier: verifier,
+        };
+
+        let response = http_client
+            .post(config.token_url.as_str())
+            .header("Content-Type", "application/x-www-form-urlencoded")
+            .header("Accept", "application/json")
+            .body(serde_urlencoded::to_string(&request_body)?)
+            .send()
+            .await?;
+
+        let status = response.status();
+        let body = response.text().await?;
+
+        if !status.is_success() {
+            anyhow::bail!("OAuth token exchange failed ({status}): {body}");
+        }
+
+        // Parse the raw token payload so provider-specific fields like
+        // `id_token` are preserved instead of being dropped by generic helpers.
+        Ok(parse_token_response(&body)?)
+    }
+
+    /// Create HTTP client with provider-specific headers/behavior
+    fn build_http_client(&self, config: &OAuthConfig) -> anyhow::Result<reqwest::Client> {
+        build_http_client(config.custom_headers.as_ref())
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use forge_domain::OAuthConfig;
+    use url::Url;
+
+    use super::*;
+
+    fn test_oauth_config() -> OAuthConfig {
+        OAuthConfig {
+            client_id: "test_client".to_string().into(),
+            auth_url: Url::parse("https://example.com/auth").unwrap(),
+            token_url: Url::parse("https://example.com/token").unwrap(),
+            scopes: vec!["read".to_string(), "write".to_string()],
+            redirect_uri: Some("https://example.com/callback".to_string()),
+            use_pkce: true,
+            token_refresh_url: None,
+            extra_auth_params: None,
+            custom_headers: None,
+        }
+    }
+
+    #[tokio::test]
+    async fn test_standard_provider_build_auth_url() {
+        let provider = StandardHttpProvider;
+        let config = test_oauth_config();
+
+        let result = provider.build_auth_url(&config).await.unwrap();
+
+        assert!(result.auth_url.contains("client_id=test_client"));
+        assert!(result.auth_url.contains("response_type=code"));
+        assert!(result.code_verifier.is_some());
+        assert_ne!(&result.state, result.code_verifier.as_ref().unwrap());
+    }
+}